06eba5fdb0
* test(#4130): failing-first regression for phase-prefixed decision IDs Add the #4130 matrix: D4-01/D12-01 across all three bullet forms, tags, discretion, wrapped lead-ins, gate-level plan/verify end-to-end rows, and parity properties (well-formed digit-prefixed ids parse to their exact id; a non-digit injected into the prefix fails loud). Update the #2347 non-D-prefix fixture from D5-NN (now a legal grammar) to DEC-NN, and graduate the representative d5-prefix corpus fixture from could-not-parse to parsed-but-uncovered. All new rows are RED against origin/next; they go green with the parser fix in the next commit. * fix(#4130): parse phase-prefixed decision IDs (D4-01) The three declaration grammars, the parse-miss guard, the #3939 join regexes, and the token evidence all anchored on the literal 'D-' (or '**D-'), so an ID carrying a digit-run phase prefix between the leading letter and the hyphen matched nothing — while the #2347 shape detector correctly called those bullets decision-shaped, collapsing the whole CONTEXT.md to could-not-parse with 0 extracted instead of a coverage verdict. Derive the extractor ID grammar from one shared DECISION_ID_SOURCE ('D[0-9]*-' + the existing alnum tail, full id captured), widen the guard/join anchors to ID_ATTEMPT_SOURCE (bare 'D-' or a digit-initial prefix run, so a typo'd 'D4x-01' fails loud while letter-initial prose like 'Deferred-until' stays none-present), and align the bare-token evidence. Both gates and the gap-checker share the parser, so all three surfaces read phase-prefixed decisions now; the gate messages name the accepted forms including the phase-prefixed one. * docs(#4130): document the phase-prefixed decision identifier form The canonical CONTEXT.md reference said decisions carry 'a sequential D-NN identifier' with no mention of the optional phase-number prefix the parser now accepts (D4-01) or the alphanumeric tail it always accepted (D-INFRA-01). Name both in the Decision identifier format section, EN and ja-JP. * chore(#4130): changeset * chore(#4130): backfill PR number in changeset --------- Co-authored-by: sim <sim@local>
7.0 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. An optional
phase-number prefix may sit between the D and the hyphen (D4-01) — useful on
multi-phase projects where bare D-01 collides across phases; the digits are read
as part of the identifier (#4130):
### 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
### Phase-4 decisions
- **D4-01:** Phase-scoped identifier, distinct from any other phase's D-01
Alphanumeric tails (D-INFRA-01) are also accepted. 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 decision identifier 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]*