From fc8ce5ed1c94e444a21459e3d06ebc5a4e62e9bd Mon Sep 17 00:00:00 2001 From: Norair Arutshyan Date: Thu, 17 Sep 2026 11:10:27 +0100 Subject: [PATCH 1/3] feat(list): propose priority and author change metadata Adds an OpenSpec change proposal (no implementation) for optional priority and author fields on change metadata, surfaced in `openspec list`. Closes #1899 Co-Authored-By: Claude Sonnet 5 --- .../.openspec.yaml | 2 ++ .../add-priority-author-metadata/proposal.md | 22 ++++++++++++ .../specs/change-creation/spec.md | 24 +++++++++++++ .../specs/cli-list/spec.md | 35 +++++++++++++++++++ 4 files changed, 83 insertions(+) create mode 100644 openspec/changes/add-priority-author-metadata/.openspec.yaml create mode 100644 openspec/changes/add-priority-author-metadata/proposal.md create mode 100644 openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md create mode 100644 openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md diff --git a/openspec/changes/add-priority-author-metadata/.openspec.yaml b/openspec/changes/add-priority-author-metadata/.openspec.yaml new file mode 100644 index 0000000000..d28e909f6b --- /dev/null +++ b/openspec/changes/add-priority-author-metadata/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-17 diff --git a/openspec/changes/add-priority-author-metadata/proposal.md b/openspec/changes/add-priority-author-metadata/proposal.md new file mode 100644 index 0000000000..3e41af131f --- /dev/null +++ b/openspec/changes/add-priority-author-metadata/proposal.md @@ -0,0 +1,22 @@ +## Why + +`openspec list` shows every in-flight change with no way to tell which one matters most or who owns it. With several parallel changes, triaging what to pick up next means opening every `proposal.md`. Filed as [#1899](https://github.com/Fission-AI/OpenSpec/issues/1899). + +## What Changes + +- Add optional `priority` (`low` | `medium` | `high`) and `author` (string) fields to per-change metadata (`.openspec.yaml`), validated by `ChangeMetadataSchema`. +- `createChange` auto-populates `author` from `git config user.name` at `openspec new change` time when the caller doesn't pass one explicitly, and leaves it unset when git config has no name to offer. +- `openspec list` reads `.openspec.yaml` per change and shows `priority`/`author` as additional table columns, and includes them in `--json` output, whenever a change sets them. Changes that set neither render exactly as they do today. + +## Capabilities + +### Modified Capabilities +- `change-creation`: metadata schema gains optional `priority` (enum) and `author` (string) fields; change creation auto-populates `author` from git config when the caller omits it. +- `cli-list`: change list output (table and `--json`) gains optional priority/author columns. + +## Impact + +- `src/core/change-metadata/schema.ts` — new optional `priority`/`author` fields on `ChangeMetadataSchema`. +- `src/utils/change-utils.ts` / `src/commands/workflow/new-change.ts` — resolve `author` from `git config user.name` when not explicitly provided. +- `src/core/list.ts` — read `.openspec.yaml` per change, render the new columns, extend the JSON shape. +- No breaking changes: both fields are optional and existing changes/output are unaffected. diff --git a/openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md b/openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md new file mode 100644 index 0000000000..4962d6b868 --- /dev/null +++ b/openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md @@ -0,0 +1,24 @@ +## ADDED Requirements + +### Requirement: Change Metadata Priority and Author +The system SHALL support optional `priority` and `author` fields in a change's metadata. + +#### Scenario: Priority accepted +- **WHEN** a change's `.openspec.yaml` sets `priority` to one of `low`, `medium`, or `high` +- **THEN** metadata validation accepts the value + +#### Scenario: Invalid priority rejected +- **WHEN** a change's `.openspec.yaml` sets `priority` to a value other than `low`, `medium`, or `high` +- **THEN** metadata validation rejects the value + +#### Scenario: Author auto-populated from git config +- **WHEN** `createChange` is called without an explicit `author` and `git config user.name` resolves to a non-empty value +- **THEN** the created change's `.openspec.yaml` includes that value as `author` + +#### Scenario: Explicit author takes precedence +- **WHEN** `createChange` is called with an explicit `author` option +- **THEN** the created change's `.openspec.yaml` uses the provided value instead of `git config user.name` + +#### Scenario: No git config available +- **WHEN** `createChange` is called without an explicit `author` and `git config user.name` is unset or git is unavailable +- **THEN** the created change's `.openspec.yaml` omits the `author` field diff --git a/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md b/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md new file mode 100644 index 0000000000..7151e1b760 --- /dev/null +++ b/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md @@ -0,0 +1,35 @@ +## MODIFIED Requirements + +### Requirement: Output Format +The command SHALL display items in a clear, readable table format with mode-appropriate progress or counts. + +#### Scenario: Displaying change list (default) +- **WHEN** displaying the list of changes +- **THEN** show a table with columns: + - Change name (directory name) + - Task progress (e.g., "3/5 tasks" or "✓ Complete") + - Priority (when set in `.openspec.yaml`, e.g. "high") + - Author (when set in `.openspec.yaml`) + +#### Scenario: Displaying spec list +- **WHEN** displaying the list of specs +- **THEN** show a table with columns: + - Spec id (directory name) + - Requirement count (e.g., "requirements 12") + +#### Scenario: Change without priority or author +- **WHEN** a change's `.openspec.yaml` sets neither `priority` nor `author` +- **THEN** its row omits those columns' values without breaking table alignment + +## ADDED Requirements + +### Requirement: JSON Output Includes Priority and Author +The command's `--json` output for changes SHALL include `priority` and `author` fields when set in the change's metadata. + +#### Scenario: JSON output with metadata present +- **WHEN** `openspec list --json` is executed and a change's `.openspec.yaml` sets `priority` and `author` +- **THEN** that change's JSON entry includes `priority` and `author` with those values + +#### Scenario: JSON output with metadata absent +- **WHEN** `openspec list --json` is executed and a change's `.openspec.yaml` sets neither field +- **THEN** that change's JSON entry omits the `priority` and `author` keys From a7a9647a2613330df64148f909242b494b34baaa Mon Sep 17 00:00:00 2001 From: Norair Arutshyan Date: Fri, 18 Sep 2026 09:52:26 +0100 Subject: [PATCH 2/3] fix(proposal): clarify author input path and column inclusion rule Addresses CodeRabbit review on #1914: - change-creation: state that author flows through CreateChangeOptions.metadata.author (surfaced as `--author`), while priority has no creation-time input and is only set by hand-editing .openspec.yaml. - cli-list: state the table-level rule explicitly - a Priority/Author column appears only when at least one listed change sets it, with empty cells for rows that don't, and the legacy two-column layout when neither is set by anything in the list. Co-Authored-By: Claude Sonnet 5 --- .../specs/change-creation/spec.md | 14 ++++++++++--- .../specs/cli-list/spec.md | 20 +++++++++++-------- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md b/openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md index 4962d6b868..947b39bbbb 100644 --- a/openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md +++ b/openspec/changes/add-priority-author-metadata/specs/change-creation/spec.md @@ -3,6 +3,14 @@ ### Requirement: Change Metadata Priority and Author The system SHALL support optional `priority` and `author` fields in a change's metadata. +`author` is a creation-time input: `createChange`'s `options.metadata` gains an +optional `author` field alongside the existing `goal`, `affected_areas`, and +`initiative` fields, and `openspec new change` exposes it as `--author `. +`priority` is not a creation-time input in this proposal — `createChange` has +no `priority` option or flag. A change gets a `priority` only by hand-editing +`.openspec.yaml` after creation; this requirement covers accepting and +validating that value, not setting it during creation. + #### Scenario: Priority accepted - **WHEN** a change's `.openspec.yaml` sets `priority` to one of `low`, `medium`, or `high` - **THEN** metadata validation accepts the value @@ -12,13 +20,13 @@ The system SHALL support optional `priority` and `author` fields in a change's m - **THEN** metadata validation rejects the value #### Scenario: Author auto-populated from git config -- **WHEN** `createChange` is called without an explicit `author` and `git config user.name` resolves to a non-empty value +- **WHEN** `createChange` is called with no `author` in `options.metadata` and `git config user.name` resolves to a non-empty value - **THEN** the created change's `.openspec.yaml` includes that value as `author` #### Scenario: Explicit author takes precedence -- **WHEN** `createChange` is called with an explicit `author` option +- **WHEN** `createChange` is called with `options.metadata.author` set (for example via `openspec new change --author `) - **THEN** the created change's `.openspec.yaml` uses the provided value instead of `git config user.name` #### Scenario: No git config available -- **WHEN** `createChange` is called without an explicit `author` and `git config user.name` is unset or git is unavailable +- **WHEN** `createChange` is called with no `author` in `options.metadata` and `git config user.name` is unset or git is unavailable - **THEN** the created change's `.openspec.yaml` omits the `author` field diff --git a/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md b/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md index 7151e1b760..5cd3233041 100644 --- a/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md +++ b/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md @@ -5,11 +5,7 @@ The command SHALL display items in a clear, readable table format with mode-appr #### Scenario: Displaying change list (default) - **WHEN** displaying the list of changes -- **THEN** show a table with columns: - - Change name (directory name) - - Task progress (e.g., "3/5 tasks" or "✓ Complete") - - Priority (when set in `.openspec.yaml`, e.g. "high") - - Author (when set in `.openspec.yaml`) +- **THEN** show a table with columns: Change name (directory name) and Task progress (e.g., "3/5 tasks" or "✓ Complete") #### Scenario: Displaying spec list - **WHEN** displaying the list of specs @@ -17,9 +13,17 @@ The command SHALL display items in a clear, readable table format with mode-appr - Spec id (directory name) - Requirement count (e.g., "requirements 12") -#### Scenario: Change without priority or author -- **WHEN** a change's `.openspec.yaml` sets neither `priority` nor `author` -- **THEN** its row omits those columns' values without breaking table alignment +#### Scenario: Priority column included only when some change sets it +- **WHEN** displaying the list of changes and at least one listed change's `.openspec.yaml` sets `priority` +- **THEN** the table includes a Priority column, with an empty cell for any row whose change does not set `priority` + +#### Scenario: Author column included only when some change sets it +- **WHEN** displaying the list of changes and at least one listed change's `.openspec.yaml` sets `author` +- **THEN** the table includes an Author column, with an empty cell for any row whose change does not set `author` + +#### Scenario: Legacy layout when no change sets priority or author +- **WHEN** displaying the list of changes and no listed change's `.openspec.yaml` sets `priority` or `author` +- **THEN** the table renders with only the Change name and Task progress columns, unchanged from today's layout ## ADDED Requirements From aa34b95f678b04ed283325839f2bfda3b0d62b4d Mon Sep 17 00:00:00 2001 From: Norair Arutshyan Date: Sat, 19 Sep 2026 15:55:14 +0100 Subject: [PATCH 3/3] fix(proposal): preserve relative modification time in legacy list layout CodeRabbit review on #1922: the legacy-layout scenario only named Change name and Task progress, omitting the relative modification time column that today's `openspec list` also renders. Since this PR is proposal-only, that omission could read as license to drop the column when implementing. Co-Authored-By: Claude Sonnet 5 --- .../changes/add-priority-author-metadata/specs/cli-list/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md b/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md index 5cd3233041..1c2822720a 100644 --- a/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md +++ b/openspec/changes/add-priority-author-metadata/specs/cli-list/spec.md @@ -23,7 +23,7 @@ The command SHALL display items in a clear, readable table format with mode-appr #### Scenario: Legacy layout when no change sets priority or author - **WHEN** displaying the list of changes and no listed change's `.openspec.yaml` sets `priority` or `author` -- **THEN** the table renders with only the Change name and Task progress columns, unchanged from today's layout +- **THEN** the table renders with only the Change name, Task progress, and relative modification time columns, unchanged from today's layout ## ADDED Requirements