docs: fix openspec status examples in cli.md

.changeset/fix-cli-status-docs.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": patch
+---
+
+docs: fix `openspec status` examples in cli.md to match actual CLI output (field names, indicators, and JSON structure).

docs/cli.md

@@ -437,29 +437,28 @@ openspec status --change add-dark-mode --json
 ```
 Change: add-dark-mode
 Schema: spec-driven
+Progress: 2/4 artifacts complete
 
-Artifacts:
-  ✓ proposal     proposal.md exists
-  ✓ specs        specs/ exists
-  ◆ design       ready (requires: specs)
-  ○ tasks        blocked (requires: design)
-
-Next: Create design using /opsx:continue
+[x] proposal
+[ ] design
+[x] specs
+[-] tasks (blocked by: design)
 ```
 
 **Output (JSON):**
 
 ```json
 {
-  "change": "add-dark-mode",
-  "schema": "spec-driven",
+  "changeName": "add-dark-mode",
+  "schemaName": "spec-driven",
+  "isComplete": false,
+  "applyRequires": ["tasks"],
   "artifacts": [
-    {"id": "proposal", "status": "complete", "path": "proposal.md"},
-    {"id": "specs", "status": "complete", "path": "specs/"},
-    {"id": "design", "status": "ready", "requires": ["specs"]},
-    {"id": "tasks", "status": "blocked", "requires": ["design"]}
-  ],
-  "next": "design"
+    {"id": "proposal", "outputPath": "proposal.md", "status": "done"},
+    {"id": "design", "outputPath": "design.md", "status": "ready"},
+    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"},
+    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]}
+  ]
 }
 ```
 

openspec/changes/fix-cli-status-docs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-25

openspec/changes/fix-cli-status-docs/design.md

@@ -0,0 +1,32 @@
+## Context
+
+The `docs/cli.md` file contains example output for the `openspec status` command that doesn't match the actual CLI output. The discrepancies exist in both text and JSON format examples. The source of truth is the actual CLI implementation in `src/commands/workflow/status.ts` and `src/commands/workflow/shared.ts`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Replace the incorrect text and JSON examples with output that matches the actual CLI behavior
+- Ensure examples are verifiable by running the actual commands
+
+**Non-Goals:**
+- Changing the CLI output format itself
+- Updating any other documentation sections
+- Adding new documentation sections
+
+## Decisions
+
+### 1. Derive examples from actual CLI output
+
+**Decision:** Run `openspec status` against a real change and use the actual output (sanitized with a user-friendly change name) as the documentation examples.
+
+**Rationale:** This eliminates guesswork and ensures accuracy. The examples should be copy-pasted from real output, not written from memory.
+
+### 2. Validate after editing
+
+**Decision:** After updating the documentation, verify correctness by comparing every field name and format in the documented examples against the actual CLI output.
+
+**Rationale:** The original bug was introduced because examples were written without validation. The fix must not repeat this mistake.
+
+## Risks / Trade-offs
+
+- **[Examples go stale if CLI output changes]** → Low risk for a single fix. A systemic solution (generated docs) is out of scope.

openspec/changes/fix-cli-status-docs/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+The `docs/cli.md` documentation for the `openspec status` command shows example output (both text and JSON) that doesn't match the actual CLI output. Anyone reading the docs to understand or parse the output will encounter field names and formats that don't exist, making the documentation misleading for both users and integration developers.
+
+## What Changes
+
+- Fix the text output example for `openspec status` to match actual format (`[x]`/`[ ]`/`[-]` indicators, `Progress:` line, `Change:`/`Schema:` headers)
+- Fix the JSON output example to use correct field names (`changeName` not `change`, `schemaName` not `schema`, `status: "done"` not `status: "complete"`, `isComplete`, `applyRequires`, `outputPath`, `missingDeps`)
+- Remove the non-existent `"next"` field and `"requires"` field from the JSON example
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+_None._ This is a documentation-only fix with no behavioral changes. No spec-level requirements are affected.
+
+## Impact
+
+- `docs/cli.md` — status command examples (text and JSON output sections)

openspec/changes/fix-cli-status-docs/specs/docs-agent-instructions/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: CLI status documentation accuracy
+
+The `docs/cli.md` status command examples SHALL match the actual output produced by the CLI.
+
+#### Scenario: Text output example matches actual format
+
+- **WHEN** comparing the text output example in `docs/cli.md` to the output of `openspec status --change <name>`
+- **THEN** the documented indicators SHALL be `[x]` for done, `[ ]` for ready, and `[-]` for blocked
+- **AND** the documented headers SHALL include `Change:`, `Schema:`, and `Progress: N/M artifacts complete`
+- **AND** blocked artifacts SHALL show `(blocked by: dep1, dep2)` notation
+
+#### Scenario: JSON output example matches actual field names
+
+- **WHEN** comparing the JSON output example in `docs/cli.md` to the output of `openspec status --change <name> --json`
+- **THEN** the documented top-level fields SHALL be `changeName`, `schemaName`, `isComplete`, `applyRequires`, and `artifacts`
+- **AND** each artifact object SHALL have fields `id`, `outputPath`, `status`, and optionally `missingDeps`
+- **AND** the `status` field values SHALL be `done`, `ready`, or `blocked`
+
+#### Scenario: Validation by running actual CLI
+
+- **WHEN** the documentation update is complete
+- **THEN** the implementer MUST run `openspec status` (both text and `--json` modes) against a real change and verify every field name, value format, and indicator symbol matches the documented examples

openspec/changes/fix-cli-status-docs/tasks.md

@@ -0,0 +1,13 @@
+## 1. Fix Documentation Examples
+
+- [x] 1.1 Update the text output example in `docs/cli.md` (lines ~437-448) to match actual `openspec status` format: `[x]`/`[ ]`/`[-]` indicators, `Change:`/`Schema:`/`Progress:` headers, `(blocked by: ...)` notation
+- [x] 1.2 Update the JSON output example in `docs/cli.md` (lines ~452-464) to use correct field names: `changeName`, `schemaName`, `isComplete`, `applyRequires`, `artifacts` with `id`/`outputPath`/`status`/`missingDeps`
+
+## 2. Validation
+
+- [x] 2.1 Run `openspec status --change <name>` (text mode) and verify every line in the documented example matches the actual output format
+- [x] 2.2 Run `openspec status --change <name> --json` and verify every field name and value format in the documented example matches the actual output
+
+## 3. Changeset
+
+- [x] 3.1 Create a changeset file (`.changeset/fix-cli-status-docs.md`) with a patch bump describing the documentation fix