6baa2a8182
* test(#1961): add failing-first bug-taxonomy routing contract tests Epic #1957 Phase 2B. Source-text-is-the-product contract tests (3 taxonomy classes, explicit class->technique routing table, Bohrbug->repro+SBFL+bisect, Heisenbug->record-replay/stability+SKIP-SBFL, Concurrency->atomicity/order/ deadlock checklist, bug_class in DEBUG Current Focus, supersede-not-append) plus a routing-table specification object pinning the documented decisions (SBFL forbidden on Heisenbug is the load-bearing 1B/2B seam). Failing-first: reference, Phase 1.75, and routing-table reframe do not yet exist. * feat(#1961): add bug-taxonomy classification + strategy routing to gsd-debugger Epic #1957 Phase 2B (reliability-critical). Adds Phase 1.75: classify the failure as Bohrbug / Heisenbug-Mandelbug / Concurrency, then route the investigation technique via an explicit class->technique table (Kernighan: no opaque heuristic). Bohrbug -> reproduction + SBFL (Phase 1.25) + git bisect; Heisenbug/Mandelbug -> record-replay (rr) + stability-stress + statistical sampling, with SBFL explicitly SKIPPED (a flaky spectrum poisons the Ochiai ranking — the load-bearing 1B/2B seam); Concurrency -> the atomicity/order/deadlock checklist first. Reframes (supersedes, not appends — Zawinski) the flat 'Technique Selection by situation' table into a class-routed table; the 11 techniques remain as routed targets. bug_class recorded in Current Focus (DEBUG template); common-bug- patterns catalog cross-referenced to the taxonomy. Full rules extracted to gsd-core/references/debugger-bug-taxonomy.md. INVENTORY + manifest + agent-size baseline + install-parity goldens + AGENTS.md updated. * fix(#1961): address orthogonal review (phase-name drift, General lane, revoke framing, row-scoped tests, bounding) - HIGH: reference said 'Phase 1B' (epic shorthand); corrected to the deployed 'Phase 1.25' (matches the agent + SBFL reference). - HIGH: 6 of 11 techniques (Rubber duck, Delta, Working backwards, Differential, Comment-out, Follow-the-indirection) were orphaned by the situation-table reframe. Added a 'General (any class, situation-cued)' lane to BOTH the reference routing table and the agent's Technique Selection table that re-homes them — supersede-not-append now holds. - MEDIUM: the SBFL-skip is structurally retroactive (Phase 1.25 runs before Phase 1.75 classification), so reframed the table column from 'Do NOT use' to 'Revoke if already run' + an explicit 'retroactive revocation, not proactive skip' note stating the ordering honestly. - MEDIUM: contract tests are now row-scoped (parse the table by class, assert per-row) instead of presence-only; added a guard that the previously- orphaned techniques now have a General-lane route. - LOW: pinned the canonical bug_class value form (lowercase-kebab: bohrbug|heisenbug-mandelbug|concurrency; prose may use title-case). - NIT: added a 'Bound the Heisenbug-chase runs' note (rr/stability/sampling timeouts) per the unbounded-subprocess gauntlet. * chore(#1961): backfill changeset pr number (PR #2407)
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