golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
8a5166598c6bcae87908d2e03a52bed2782cfe41
msd-core/docs/reference/context-md.md
Tom Boucher 06eba5fdb0 fix(#4130): parse phase-prefixed decision IDs (D4-01) (#4357) 
* 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>
2026-09-05 21:05:19 -04:00

158 lines
7.0 KiB
Markdown
Raw Blame History

# 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](../README.md).
---
## 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:
```markdown
# 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):
```markdown
### 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:
```markdown
<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:
1. Every `D-NN` identifier in `<decisions>` must appear in at least one plan task's `<action>` or rationale.
2. No task may implement anything listed in `<deferred>` (scope creep).
3. `Claude's Discretion` areas 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>`:
```markdown
<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:
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## Related
- [PLAN.md schema](plan-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Discuss modes](../workflow-discuss-mode.md)
- [docs index](../README.md)
Reference in New Issue View Git Blame Copy Permalink