ec7e49a64c
* test(#3576): gate shipped reference citations on the canonical resolvable form Failing-first gate for #3576: a backticked bare references/<name>.md cite resolves from no install location (agents, workflows, and references all install where a bare relative references/ path is dead). The gate walks the runtime-loaded trees the issue prescribes, strips @~/ include tokens PER-TOKEN (a line-skip guard would miss a bare cite sharing a line with an include — the issue-named trap), pins the genuinely relative ../ href and canonical forms as non-offenders, and checks canonical cite targets exist. 43 offenders today across 19 files. * fix(#3576): repair all 43 dead references/ cites to the canonical resolvable form Every backticked bare references/<name>.md cite across the 19 shipped files rewritten to gsd-core/references/<name>.md — the form every required_reading block and @~/ include already uses, and the only form that resolves from any install location. All 20 cited targets verified to exist; the one genuinely relative href (plan-phase.md's ../references/mvp-concepts.md) is untouched (the repair is backtick-anchored). Growth acks: new fragment for the three first-time paths, #3206-pattern appends to the five fragments already naming the other grown files (two ack sources may never name the same path). execute-phase.md lands at 93,391/93,400 and gsd-executor.md at 49,150/49,152 — exactly the issue's projections; every repair fits. * fix(#3576): drop stale default.md growth ack (nested modes file is hash-attributed, not growth-ratcheted) Review finding: the emitted-attribution ratchet covers only top-level workflows/ + agents/ files; discuss-phase/modes/default.md's delta is source-attributed, so acknowledging its growth is a stale entry the differential lane fails on. * chore(#3576): add changeset fragment * chore(#3576): backfill changeset pr number --------- Co-authored-by: sim <sim@local>
GSD Canonical Artifact Registry
This directory contains the template files for every artifact that GSD workflows officially produce. The table below is the authoritative index: if a .planning/ root file is not listed here, gsd-health will flag it as W019 (unrecognized artifact).
Agents should query this file before treating a .planning/ file as authoritative. If the file name does not appear below, it is not a canonical GSD artifact.
.planning/ Root Artifacts
These files live directly at .planning/ — not inside phase subdirectories.
| File | Template | Produced by | Purpose |
|---|---|---|---|
PROJECT.md |
project.md |
/gsd:new-project |
Project identity, goals, requirements summary |
ROADMAP.md |
roadmap.md |
/gsd:new-milestone, /gsd:new-project |
Phase plan with milestones and progress tracking |
STATE.md |
state.md |
/gsd:new-project, /gsd:health --repair |
Current session state, active phase, last activity |
REQUIREMENTS.md |
requirements.md |
/gsd:new-milestone |
Functional requirements with traceability |
MILESTONES.md |
milestone.md |
/gsd:complete-milestone |
Log of completed milestones with accomplishments |
BACKLOG.md |
(inline) | /gsd-add-backlog |
Pending ideas and deferred work |
LEARNINGS.md |
(inline) | /gsd:extract-learnings, /gsd:execute-phase |
Phase retrospective learnings for future plans |
THREADS.md |
(inline) | /gsd:thread |
Persistent discussion threads |
config.json |
config.json |
/gsd:new-project, /gsd:health --repair |
Project-specific GSD configuration |
CLAUDE.md |
claude-md.md |
/gsd-profile |
Auto-assembled Claude Code context file |
RETROSPECTIVE.md |
(inline) | /gsd:complete-milestone |
Living milestone retrospective updated at each milestone close |
Version-stamped artifacts (pattern: vX.Y-*.md)
| Pattern | Produced by | Purpose |
|---|---|---|
vX.Y-MILESTONE-AUDIT.md |
/gsd:audit-milestone |
Milestone audit report before archiving |
These files are archived to .planning/milestones/ by /gsd:complete-milestone. Finding them at the .planning/ root after completion indicates the archive step was skipped.
Phase Subdirectory Artifacts (.planning/phases/NN-name/)
These files live inside a phase directory. They are NOT checked by W019 (which only inspects the .planning/ root).
| File Pattern | Template | Produced by | Purpose |
|---|---|---|---|
NN-MM-PLAN.md |
phase-prompt.md |
/gsd:plan-phase |
Executable implementation plan |
NN-MM-SUMMARY.md |
summary.md |
/gsd:execute-phase |
Post-execution summary with learnings |
NN-CONTEXT.md |
context.md |
/gsd:discuss-phase |
Scoped discussion decisions for the phase |
NN-RESEARCH.md |
research.md |
/gsd:plan-phase, /gsd:plan-phase --research-phase <N> |
Technical research for the phase |
NN-VALIDATION.md |
VALIDATION.md |
/gsd:plan-phase (Nyquist) |
Validation architecture (Nyquist method) |
NN-UAT.md |
UAT.md |
/gsd:validate-phase |
User acceptance test results |
NN-PATTERNS.md |
(inline) | /gsd:plan-phase (pattern mapper) |
Analog file mapping for the phase |
NN-UI-SPEC.md |
UI-SPEC.md |
/gsd:ui-phase |
UI design contract |
NN-SECURITY.md |
SECURITY.md |
/gsd:secure-phase |
Security threat model |
NN-AI-SPEC.md |
AI-SPEC.md |
/gsd:ai-integration-phase |
AI integration spec with eval strategy |
NN-DEBUG.md |
DEBUG.md |
/gsd:debug |
Debug session log |
NN-REVIEWS.md |
(inline) | /gsd:review |
Cross-AI review feedback |
Milestone Archive (.planning/milestones/)
Files archived by /gsd:complete-milestone. These are never checked by W019.
| File Pattern | Source |
|---|---|
vX.Y-ROADMAP.md |
Snapshot of ROADMAP.md at milestone close |
vX.Y-REQUIREMENTS.md |
Snapshot of REQUIREMENTS.md at milestone close |
vX.Y-MILESTONE-AUDIT.md |
Moved from .planning/ root |
vX.Y-phases/ |
Archived phase directories (if --archive-phases used) |
Adding a New Canonical Artifact
When a new workflow produces a .planning/ root file:
- Add the file name to
CANONICAL_EXACTingsd-core/bin/lib/artifacts.cjs - Add a row to the
.planning/Root Artifacts table above - Add the template to
gsd-core/templates/if one exists