fix(show): include requirement and scenario names in JSON

[ryandemelo]

Closes #1971

Also answers the secondary request in #1918, which asks for the same names so tools can match a delta to its baseline.

show --json described each requirement as its SHALL sentence and each scenario as its bullets. The parser already reads both headers and then dropped them, so nothing in the JSON said which requirement was which by the name archive matches on.

What changes

Each requirement and each scenario in show --json now carries a name. This applies to spec JSON and to the requirement / requirements objects inside change deltas.

The names come from the same normalization archive already uses. For a requirement, normalizeRequirementName removes the Requirement: prefix and a closing # run. For a scenario, the MODIFIED scenario loss check's own name reader is now exported as scenarioNameFromHeaderText, so a scenario name in the JSON is always the name that check compares. C# keeps its #. A level 4 header without Scenario: is named by its text, since it already counts as a scenario.

The field is additive. It is optional in RequirementSchema and ScenarioSchema, so objects built outside the parser still validate. No existing field changes.

Docs

The two JSON examples in docs-lab/reference/cli.md show the new fields, and a short paragraph says what each name is. docs/agent-contract.md section 4.2 spells out the requirement and scenario shape.

Testing

pnpm test passes, 5944 tests. pnpm lint is clean. Five new tests cover prefix and closing run removal, a # inside a name, a level 4 header without Scenario:, change delta names for ADDED and MODIFIED, and the CLI output with -r and --no-scenarios. All five fail on main.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

Configuration used: Repository: Fission-AI/OpenSpec/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 913de013-6670-4f11-b08f-c5dd0cd72d5c

📥 Commits

Reviewing files that changed from the base of the PR and between 050b0d6 and d10e465.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: Fission-AI/OpenSpec/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 3e789c16-2a8d-4686-84f6-bbd76a16934a

📥 Commits

Reviewing files that changed from the base of the PR and between db23097 and 050b0d6.

📒 Files selected for processing (10)

• .changeset/show-json-names.md
• docs-lab/reference/cli.md
• docs/agent-contract.md
• src/commands/spec.ts
• src/core/parsers/markdown-parser.ts
• src/core/parsers/requirement-blocks.ts
• src/core/schemas/base.schema.ts
• test/commands/spec.test.ts
• test/core/parsers/change-parser.test.ts
• test/core/parsers/markdown-parser.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

show --json now includes requirement and scenario names for spec and change data. The parser derives the names from Markdown headers and removes applicable prefixes and closing heading markers.

Changes

Requirement and scenario names

Layer / File(s)	Summary
Name fields and Markdown header parsing src/core/schemas/base.schema.ts, src/core/parsers/requirement-blocks.ts, src/core/parsers/markdown-parser.ts, test/core/parsers/*	Requirement and scenario schemas accept optional name fields. Markdown parsing derives names from headers, removes applicable prefixes and closing heading markers, and tests these cases.
Show JSON output and documentation src/commands/spec.ts, test/commands/spec.test.ts, docs-lab/reference/cli.md, docs/agent-contract.md, .changeset/show-json-names.md	Filtered spec requirements retain their names. CLI tests verify names in JSON output. Documentation and the changeset describe the name fields and their correspondence to archive header names.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 050b0

Requirement and scenario names appear to flow through the intended JSON outputs consistently. No issue identified here prevents merging after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 7 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue [#1971] requires normalized name fields for requirements and scenarios in spec JSON and change delta objects, while preserving existing fields. The parser now adds normalized requirement names…
Out of Scope Changes check	✅ Passed	The changes stay within issue [#1971]. Source changes implement name extraction and JSON propagation. Tests verify the new behavior. Documentation and the changeset describe the new JSON fields and th…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding requirement and scenario names to show --json output.

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 7 files. (3 skipped: 3 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alfred-openspec]

Approved at d10e465. Requirement and scenario names now use the same normalization as archive and the scenario-loss check, the JSON addition is backward-compatible, filtered and no-scenario output retain requirement names, and the CLI plus agent contracts are updated. The full check matrix is green. Final review of the docs-lab change by @TabishB is still required.