ffd5370464
* fix(#2903): use the command form that actually works in reader-facing docs Docs told readers to type the colon form, which no runtime registers -- 18 of 19 runtimes use slash-hyphen and the 19th uses shell-var -- so anyone copying an example got an unrecognized command. Swept 178 occurrences across 53 files, locale mirrors included so they do not re-diverge from English. The colon form is a source-authoring token, not a user-facing one: install-time converters key on it to produce the hyphen form runtimes actually register. So the sweep is scoped, and three things are deliberately left alone: - ADRs, which are a historical record; editing their prose falsifies what was written at the time. - The legacy release-notes archive, pending a maintainer decision on whether it follows the same historical carve-out. Excluding it keeps a later reversal additive rather than a revert. - Source artifacts under commands, workflows and agents, where the colon form is load-bearing. Rewriting those would break the installed-skill guarantee across every runtime -- the single largest hazard here. The plugin namespace form is a real, separate token and survives untouched. Adds a lint enforcing exactly that boundary, since the correct form genuinely differs by directory and nothing previously caught the drift. Also fixes a hardcoded colon form in the capability-matrix generator. The sweep alone would have left the generated matrix disagreeing with the template that produces it, so the fix is at the source and the output regenerated. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2903): stop the sweep misquoting source frontmatter Adversarial review caught three lines where the sweep rewrote a citation of the literal YAML name: key from a source command file. That key genuinely is the colon form -- this change's own carve-out logic says source-authoring tokens keep it -- so the docs ended up misquoting the real files. One of the three is an acceptance-checklist assertion, which the sweep turned into a false statement. Restored the three citations to match their sources verbatim, surgically: where a line carried both a name: citation and a real reader-facing slash command, only the citation reverted and the command stayed corrected. The guard needed the same distinction, or it would have flagged the restoration and reddened the build: a gsd:<cmd> token preceded by name: is a citation of a source token and is now permitted. The exemption is deliberately narrow -- a bare gsd:<cmd> anywhere else still fails -- with a test pinning that narrowness. Also makes the detection case-insensitive. Review found /GSD:next slipped through silently; no such casing exists in the tree today, so this closes a latent gap rather than fixing a live one. Swept the whole tree for further corrupted citations: none beyond the three. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2903): retire the stale-next invariant and sweep next like every other command Maintainer decision on a genuine conflict between two contracts. Invariant #3054 banned the literal /gsd-next from user-facing docs because it named a retired workflow-advance command. But commands/gsd/next.md is a live command -- the state-aware smart-entry launcher -- and this issue requires docs to use the hyphen form every runtime actually registers. Both could not hold for this one command, so docs had been sidestepping the ban by keeping the colon form, which is exactly the defect this issue exists to remove. FEATURES.md already recorded the reassignment: the hyphen form "is not the retired workflow-advance command; it is reserved for the state-aware smart-entry launcher. Workflow advancement remains under /gsd-progress --next." With that reassignment the invariant's premise is obsolete and the guard now contradicts the documented command form, so it is retired with a comment recording why rather than deleted silently. next is now swept like every other command, and the earlier exemption added to the new guard is removed so nothing is special-cased. Four citations of the literal name: frontmatter key stay in colon form, because the source file really does carry name: gsd:next and a doc quoting it must reproduce it verbatim. Two of those lines were reworded to say which side is the frontmatter key and which is the slash command, since they previously conflated the two. Verified the retired scan would now genuinely fail against this tree -- the conflict was real and resolved, not dodged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#2903): backfill changeset pr number Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
6.6 KiB
CONTEXT.md schema reference
A per-phase CONTEXT.md is GSD Core's carrier for implementation decisions captured during /gsd-discuss-phase. It is the primary upstream input for both the research and planning agents. This page documents its structure. See docs index.
Overview
Every phase that has been through the discuss workflow produces one CONTEXT.md at:
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
For example: .planning/phases/03-post-feed/03-CONTEXT.md.
The file is produced by write_context in gsd-core/workflows/discuss-phase.md (or its PRD / ADR ingest express paths). It is never edited by hand during normal operation — the discuss-phase workflow writes it and downstream agents read it as a sealed source of truth.
Frontmatter
CONTEXT.md carries no YAML frontmatter. Metadata is inline at the top of the body:
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
The Status field is always Ready for planning when the file is first written. It is not updated after creation.
Block structure
The body is divided into named XML-style blocks. The blocks appear in a fixed order and are read by downstream agents by block name, not by line number.
| Block | Purpose | Populated by | Consumed by |
|---|---|---|---|
<domain> |
States the phase boundary — what this phase delivers and what is explicitly out of scope. Anchors the scope guardrail throughout planning and execution. | discuss-phase (from ROADMAP.md phase goal) |
gsd-planner, gsd-plan-checker (scope compliance) |
<spec_lock> |
Present only when a *-SPEC.md was found by the check_spec step. Lists locked requirement counts and scope boundaries; agents are directed to read SPEC.md directly for full requirements. |
discuss-phase (conditional) |
gsd-planner (reads SPEC.md rather than re-reading requirements here) |
<decisions> |
Implementation decisions captured from the discussion, keyed with D-NN identifiers. Categories emerge from what was actually discussed rather than a fixed taxonomy. Includes a Claude's Discretion sub-section for areas the user delegated. |
discuss-phase (interactive discussion) |
gsd-planner (locked decisions must be implemented), gsd-plan-checker (Dimension 7 compliance) |
<canonical_refs> |
Full relative paths to every spec, ADR, feature doc, or design doc relevant to this phase. Mandatory — every CONTEXT.md must have this section. Agents must read listed files before planning or implementing. | discuss-phase (accumulated from ROADMAP.md refs + user references during discussion + codebase scout) |
gsd-phase-researcher, gsd-planner |
<code_context> |
Reusable assets, established patterns, and integration points discovered during the scout_codebase step. Guides agents towards existing code rather than re-implementing. |
discuss-phase (codebase scout) |
gsd-planner, gsd-phase-researcher |
<specifics> |
Concrete "I want it like X" references, product comparisons, or particular examples captured verbatim during discussion. | discuss-phase (freeform user input) |
gsd-planner |
<deferred> |
Ideas that arose in discussion but belong in other phases. Preserved so they are not lost. Includes a Reviewed Todos sub-section when todos were reviewed but not folded into scope. |
discuss-phase (scope-creep redirect) |
Not consumed by automated agents; human reference only |
Decision identifier format
Every decision in <decisions> carries a sequential D-NN identifier:
### Layout style
- **D-01:** Card-based layout, not timeline or list
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
Identifiers are scoped to the phase. D-01 in Phase 3 is unrelated to D-01 in Phase 7. The plan-checker (Dimension 7) verifies that every D-NN is addressed by at least one task action in the generated plans.
Canonical references
The <canonical_refs> block is mandatory. Agents that find it absent treat the CONTEXT.md as incomplete and surface a warning. Entries are grouped by topic and carry a full relative path plus a brief statement of what the file decides or defines:
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Feed display
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
### Empty states
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
</canonical_refs>
When a project has no external specs, the section states this explicitly:
No external specs — requirements fully captured in decisions above
Inline mentions like "see ADR-019" scattered in <decisions> are insufficient; agents need the full path in the dedicated section.
Decision Coverage Gate relationship
The plan-checker's Dimension 7: Context Compliance enforces a coverage gate after planning:
- Every
D-NNidentifier in<decisions>must appear in at least one plan task's<action>or rationale. - No task may implement anything listed in
<deferred>(scope creep). Claude's Discretionareas are exempted from this check — the planner may choose freely.
A CONTEXT.md where decisions survive into plans is considered compliant. A CONTEXT.md whose decisions are silently dropped or partially delivered triggers Dimension 7b: Scope Reduction Detection, which is always a BLOCKER.
SPEC.md integration
When /gsd-spec-phase has been run before discussing a phase, the check_spec step finds the *-SPEC.md file and activates <spec_lock>:
<spec_lock>
## Requirements (locked via SPEC.md)
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
</spec_lock>
When <spec_lock> is present, <decisions> contains only implementation decisions from the discussion — the "how", not the "what". Requirements are not duplicated between the two files.
Footer
Every CONTEXT.md ends with an identity footer:
---
*Phase: XX-name*
*Context gathered: [date]*