Files

Tom Boucher ec7e49a64c fix(#3576 ): repair all 43 dead references/ cites and gate the canonical resolvable form (#3596 )

* 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>

2026-08-17 15:24:24 -04:00

4.8 KiB

Raw Blame History

MVP Concepts — index

Cross-reference for the six MVP-related reference files. Each file has a single, narrow purpose. This index exists so future readers (and agents resolving @-refs) can find the right file without grepping the directory.

Canonical domain terms for the concepts named below live in CONTEXT.md under "Domain terms" — start there if you need a precise definition.

File map

File	Purpose	Loaded by
`gsd-core/references/planner-mvp-mode.md`	Rules. Vertical-slice planning rules, slice ordering, Walking Skeleton constraints.	`gsd-planner` agent when `MVP_MODE=true`
`gsd-core/references/skeleton-template.md`	Template. Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`.	`gsd-planner` agent when the Walking Skeleton gate fires
`gsd-core/references/user-story-template.md`	Template. Format and slot definitions for `As a / I want to / So that`.	`gsd-mvp-phase` workflow during interactive prompting; `gsd-planner` when emitting the `## Phase Goal` header
`gsd-core/references/spidr-splitting.md`	Splitting discipline. Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase.	`gsd-mvp-phase` workflow when the user story exceeds size threshold
`gsd-core/references/execute-mvp-tdd.md`	Gate. MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition.	`gsd-executor` agent when `MVP_MODE=true && TDD_MODE=true`
`gsd-core/references/verify-mvp-mode.md`	UAT framing. Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md.	`gsd-verifier` agent when the phase under verification has `mode: mvp`

Concept-to-file map

If you're looking for the canonical statement of a concept, this is where to find it:

MVP Mode resolution chain — workflows/plan-phase.md Step 1 (CLI flag → roadmap → config → false). Mirrored in execute-phase.md and verify-work.md.
**Mode:** mvp parser — gsd-core/bin/lib/roadmap.cjs (searchPhaseInContent + cmdRoadmapAnalyze). Workflows compare against the parser output, never re-parse.
User Story regex — /^As a .+, I want to .+, so that .+\.$/ — applied at runtime by gsd-verifier (the user-story-format guard) and gsd-mvp-phase (interactive validation).
Behavior-Adding Task predicate — gsd-core/references/execute-mvp-tdd.md (the canonical three-check definition). Applied at runtime by gsd-executor.
Walking Skeleton gate condition — workflows/plan-phase.md (Phase 1 + new project + --mvp + no prior summaries → emit SKELETON.md).
MVP+TDD Gate (RED→GREEN enforcement) — gsd-core/references/execute-mvp-tdd.md.
MVP-mode UAT framing (user-flow first, technical deferred) — gsd-core/references/verify-mvp-mode.md.
Per-phase mode authoring — workflows/mvp-phase.md (writes **Mode:** mvp to ROADMAP.md after collecting the user story).
Project-wide mode prompt at init — workflows/new-project.md (Vertical MVP vs Horizontal Layers question).

Interactions worth knowing

--mvp and --prd <file> together on Phase 1. Both paths converge at the planner spawn. The PRD express path creates CONTEXT.md from the PRD file and continues to the research step; the Walking Skeleton gate fires independently when Phase 1 + new project + --mvp. The planner therefore receives both WALKING_SKELETON=true and PRD-derived context. This is intentional: the PRD informs what the skeleton should prove.
MVP_MODE is all-or-nothing per phase, not per task. A phase is either MVP-mode or standard. Mixed-mode phases are not supported (PRD #2826 Q1).
TDD_MODE is independent of MVP_MODE. TDD can be on without MVP, MVP can be on without TDD. Only the intersection (both true) activates the MVP+TDD Gate.
The gsd-roadmapper agent makes the MVP/standard decision once at project init based on PROJECT_MODE. Per-phase opt-in/out happens later via /gsd:mvp-phase or /gsd-edit-phase.

Tests

Structural contract tests for each integration site live under tests/:

plan-phase-mvp-flag.test.cjs — plan-phase MVP_MODE resolution chain
planner-mvp-mode.test.cjs — gsd-planner agent MVP section
mvp-phase-command.test.cjs, mvp-phase-integration.test.cjs, mvp-phase-spidr.test.cjs — /gsd:mvp-phase
execute-mvp-tdd-gate.test.cjs, executor-mvp-tdd-section.test.cjs — MVP+TDD Gate
verifier-mvp-section.test.cjs, verify-mvp-uat.test.cjs — verifier UAT framing
new-project-mvp-prompt.test.cjs — mode prompt at init
progress-mvp-display.test.cjs, stats-mvp-display.test.cjs, graphify-mvp-viz.test.cjs — discovery surfaces

4.8 KiB Raw Blame History