@opengsd/gsd-core 1.12.0 → 1.13.0

package/gsd-core/references/agent-contracts.md

@@ -11,11 +11,11 @@ This doc describes what IS, not what should be. Casing inconsistencies are docum
 | Agent | Role | Completion Markers | Consumed by | Kind |
 |-------|------|--------------------|--------------|------|
 | gsd-ai-researcher | AI framework research | No marker (writes the AI-SPEC.md framework section via Edit) | `gsd-core/workflows/ai-integration-phase.md` reads the AI-SPEC.md section after the agent returns | artifact+query |
-| gsd-planner | Plan creation | `## PLANNING COMPLETE`, `## OUTLINE COMPLETE`, `## PHASE SPLIT RECOMMENDED`, `## ⚠ Source Audit`, `## CHECKPOINT REACHED`, `## PLANNING INCONCLUSIVE` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `gsd-core/workflows/plan-review-convergence.md`, `gsd-core/workflows/quick.md` | sentinel-match |
+| gsd-planner | Plan creation | `## PLANNING COMPLETE`, `## OUTLINE COMPLETE`, `## PHASE SPLIT RECOMMENDED`, `## ⚠ Source Audit`, `## CHECKPOINT REACHED`, `## PLANNING INCONCLUSIVE`, `## REVISION_CONFLICT` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `gsd-core/workflows/plan-review-convergence.md`, `gsd-core/workflows/quick.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/verify-work.md` | sentinel-match |
 | gsd-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `agents/gsd-debug-session-manager.md`, `agents/gsd-debugger.md` | sentinel-match |
 | gsd-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/research-phase.md`, `agents/gsd-project-researcher.md` | sentinel-match |
 | gsd-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/research-phase.md`, `agents/gsd-phase-researcher.md` | sentinel-match |
-| gsd-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/stall-detection-helpers.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/ui-phase.md`, `gsd-core/workflows/verify-work.md`, `agents/gsd-ui-checker.md` | sentinel-match |
+| gsd-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/stall-detection-helpers.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/import.md`, `gsd-core/workflows/ui-phase.md`, `gsd-core/workflows/verify-work.md`, `agents/gsd-ui-checker.md` | sentinel-match |
 | gsd-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` (unconsumed: blocked-research return — spawners detect failure via the #222 SUMMARY.md-on-disk check, no dispatch branch keys on the marker) | `gsd-core/workflows/new-milestone.md`, `gsd-core/workflows/new-project.md` | sentinel-match |
 | gsd-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED`, `## INVESTIGATION INCONCLUSIVE`, `## TDD CHECKPOINT`, `## FIX REJECTED BY GUARDRAIL` | `agents/gsd-debug-session-manager.md`, `gsd-core/workflows/diagnose-issues.md`, `gsd-core/workflows/plan-phase.md`, `agents/gsd-executor.md` | sentinel-match |
 | gsd-debug-session-manager | Debug checkpoint loop | `## DEBUG SESSION COMPLETE`, `## CONTINUE_REQUIRED` | `gsd-core/workflows/debug.md` | sentinel-match |
@@ -23,7 +23,7 @@ This doc describes what IS, not what should be. Casing inconsistencies are docum
 | gsd-ui-auditor | UI review | `## UI REVIEW COMPLETE` | `gsd-core/workflows/ui-review.md` | sentinel-match |
 | gsd-dom-verifier | Live-DOM UAT verification | No marker (writes `{phase}-DOM-VERIFY.md` directly; the frontmatter `outcome` / `reason` scalars carry the verdict, and `could_not_look` is never conflated with `nothing_to_report`) | `{phase}-DOM-VERIFY.md` artifact, written by the `live-dom-uat` capability's `execute:wave:post` step dispatched from `gsd-core/workflows/execute-phase.md` | artifact+query |
 | gsd-ui-checker | UI validation | `## ISSUES FOUND`, `## UI-SPEC VERIFIED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/ui-phase.md`, `gsd-core/workflows/verify-work.md`, `agents/gsd-plan-checker.md` | sentinel-match |
-| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` | `gsd-core/workflows/ui-phase.md` | sentinel-match |
+| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED`, `## REVISION_CONFLICT` | `gsd-core/workflows/ui-phase.md` | sentinel-match |
 | gsd-verifier | Post-execution verification | `## Verification Complete` (unconsumed: Marker Rule 2 recorded decision — intentional title-case marker; completion is detected via the artifact route, nothing matches the marker) | `*-VERIFICATION.md` artifact + `gsd_run query verification.status` in `gsd-core/workflows/verify-work.md` | artifact+query |
 | gsd-integration-checker | Cross-phase integration check | `## Integration Check Complete` (unconsumed: Marker Rule 2 recorded decision — intentional title-case marker; the auditor reads the inline report, nothing matches the marker) | `gsd-core/workflows/audit-milestone.md` reads the agent's inline return text directly (agent has no Write tool -- it cannot write an artifact) | structured-return |
 | gsd-nyquist-auditor | Sampling audit | `## PARTIAL`, `## ESCALATE`, `## GAPS FILLED` (non-standard) | `gsd-core/workflows/validate-phase.md`, `gsd-core/workflows/secure-phase.md`, `agents/gsd-security-auditor.md` | sentinel-match |

package/gsd-core/references/edge-probe.md

@@ -41,19 +41,23 @@ core finding that the spec layer is the measured weak point:
 
 ## Inputs
 
-A list of requirements, each a `{ id, text, shapes? }` record where `text` is a testable
-statement and `shapes` is an optional author-supplied override of the data/behavior shape.
-The five shapes are: `numeric-range`, `collection`, `text`, `stateful`, `io`. When
-`shapes` is absent, a heuristic classifier proposes them from the requirement prose
-(propose-then-confirm) — the author may correct the shape.
-
-**`text` is English, whatever language the SPEC is in.** The heuristic cues are English
-word-boundary patterns, so a project running with `response_language` set must pass `text` as a
-faithful English translation of the requirement; the SPEC itself keeps the original language and
-the `id` is never translated. Prose in another language matches no cue, classifies to zero
-shapes, and surfaces as `unclassified` (#1110) — the probe contributes nothing. Where a
-requirement carries no cue even in English, author `shapes` explicitly rather than leaning on
-the classifier.
+A list of requirements, each a `{ id, text, text_en?, shapes? }` record where `text` is a
+testable statement, `text_en` is an optional English translation of `text`, and `shapes` is an
+optional author-supplied override of the data/behavior shape. The five shapes are:
+`numeric-range`, `collection`, `text`, `stateful`, `io`. When `shapes` is absent, a heuristic
+classifier proposes them from the requirement prose — reading `text_en` in preference to
+`text` when present (`text_en ?? text`) — (propose-then-confirm); the author may correct the
+shape.
+
+**The classifier reads English; `text` does not have to be.** The heuristic cues (`SHAPE_CUES`)
+are English word-boundary patterns, so a requirement whose `text` is not English classifies to
+zero shapes unless `text_en` supplies a faithful English translation. A project running with
+`response_language` set should populate `text_en` for every requirement; `text` keeps its own
+meaning — the requirement's own text, in whatever language the SPEC uses — and is never
+translated or overwritten. `text_en` is engine input, not part of the SPEC. `id` is never
+translated. Prose that matches no cue in either field surfaces as `unclassified` (#1110) — the
+probe contributes nothing for that requirement. Where a requirement carries no cue even in
+English, author `shapes` explicitly rather than leaning on the classifier.
 
 ## Taxonomy (8 categories)
 

package/gsd-core/references/execute-mvp-tdd.md

@@ -1,11 +1,10 @@
-# Execute-Phase — MVP+TDD Gate (Runtime Enforcement)
+# Execute-Phase — TDD Gate (Runtime Enforcement)
 
-> Loaded by `execute-phase` workflow and `gsd-executor` agent only when **both** `MVP_MODE=true` AND `TDD_MODE=true` for the phase. Defines the runtime gate that blocks behavior-adding tasks until a failing-test commit exists.
+> Loaded by `execute-phase` workflow and `gsd-executor` agent when `TDD_MODE=true` for the phase (#4011 — the gate no longer requires MVP mode; MVP may imply TDD, but TDD never requires MVP). Defines the runtime gate that blocks behavior-adding tasks until a failing-test commit exists.
 
 ## When this gate fires
 
-- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `gsd-core/references/planner-mvp-mode.md`).
-- `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config).
+- `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config). MVP mode is NOT required (#4011).
 - The current task being executed has `tdd="true"` in its `<task>` frontmatter (set by the planner per Phase 1).
 - The task's `<behavior>` block lists at least one expected behavior.
 
@@ -13,15 +12,18 @@ If any of these is false, the gate is inactive — execution proceeds normally.
 
 ## What the gate checks
 
-For each task gated by MVP+TDD, the executor MUST verify (before running the implementation step):
+For each task gated by TDD, the executor MUST verify (before running the implementation step):
 
 1. **A failing-test commit exists.** Search git log on the current branch for a commit matching `test({phase}-{plan})` whose subject mentions the same plan as the current task. The commit must touch a test file (`*.test.*`, `*.spec.*`, `tests/**`).
-2. **The test was actually red.** The commit message body or the executor's recent shell history must show the test failed when first run. Acceptable evidence:
-   - Commit message contains `RED:` prefix or `(RED)` tag
-   - Recent terminal output shows `FAIL` or non-zero exit on the new test before any implementation commit
+2. **The test was actually red — INTENTIONALLY (#3770).** A nonzero exit is not RED by itself: syntax errors, zero-test discovery, fixture crashes, parser errors, and unrelated assertions are INVALID_RED. The executor must persist the RED evidence record (command, exit code, failing test, expected result from `<behavior>`, actual result) and verify it:
+   ```bash
+   gsd_run check tdd-red-evidence <record.json> --raw
+   ```
+   - `RED_EVIDENCE_OK` (reason `target_test_failed`): the TARGET test named by the plan failed on a real assertion — the ONLY verdict that authorizes GREEN.
+   - `INVALID_RED` (reasons `unexpected_green`, `zero_tests_discovered`, `nonzero_exit_without_test_failure`, `fixture_or_load_failure`, `no_target_test_failure`, `invalid_record`, `unreadable_record`): the gate trips — halt, fix the RED phase (test identity, fixture, discovery), and re-verify before any implementation step. A `RED:` prefix or `(RED)` tag in the commit message is NOT sufficient evidence on its own.
 3. **No implementation commit yet.** No `feat({phase}-{plan})` commit may exist for the same plan ID before the failing-test commit.
 
-If any check fails, the gate trips.
+If any check fails, the gate trips. For check 2, an INVALID_RED verdict (`check tdd-red-evidence`) trips the gate — the executor MUST halt and block the implementation step.
 
 ## What "behavior-adding task" means
 
@@ -40,9 +42,9 @@ The executor MUST:
 2. Emit a structured halt report:
 
    ```
-### MVP+TDD GATE TRIPPED — Plan {plan_id}, Task {task_id}
+### TDD GATE TRIPPED — Plan {plan_id}, Task {task_id}
 
-   Reason: {missing_red_commit | red_commit_not_failing | feat_before_test}
+   Reason: {missing_red_commit | red_commit_not_failing | feat_before_test | invalid_red}
 
    Behavior expected to be tested:
    - {first behavior bullet}
@@ -56,24 +58,24 @@ The executor MUST:
 3. Exit the current execution wave cleanly. Do NOT roll back any prior commits in the same wave.
 4. Update `STATE.md` with `last_gate_trip: {plan_id}/{task_id}` so the user can resume after writing the test.
 
-## Escalation: end-of-phase TDD review under MVP+TDD
+## Escalation: end-of-phase TDD review under TDD
 
 The existing end-of-phase TDD review (in `workflows/execute-phase.md`'s `tdd_review_checkpoint` step) is normally **advisory** — it surfaces gate violations but does not block phase completion.
 
-Under MVP+TDD, escalate this to **blocking**:
+Under TDD mode, escalate this to **blocking**:
 - If any TDD plan is missing a RED or GREEN commit, the executor MUST refuse to mark the phase complete.
 - The user is shown the same review table, but the verdict line reads:
-  > "Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under MVP+TDD. Resolve and re-run /gsd execute-phase, or override with `/gsd execute-phase {phase} --force-mvp-gate` to ship anyway."
+  > "Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under TDD. Resolve and re-run /gsd execute-phase, or override with `/gsd execute-phase {phase} --force-mvp-gate` to ship anyway."
 
 The `--force-mvp-gate` flag is documented but not introduced by this plan — it is the escape hatch the spec mentions; if the user later builds it, the workflow already references the contract.
 
 ## What this gate does NOT do
 
 - It does not enforce REFACTOR commits. REFACTOR remains optional (per `gsd-core/references/tdd.md`).
-- It does not check test quality (the test could be trivially passing). That's the planner's job.
+- It does not check test quality (the test could be trivially weak). That's the planner's job. It DOES check that the RED failure was intentional — the target test failing an assertion (#3770).
 - It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
 - It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
 
 ## Compatibility with existing TDD discipline
 
-This gate is additive to `gsd-core/references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.
+This gate is additive to `gsd-core/references/tdd.md`. Tasks not under TDD mode continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.

package/gsd-core/references/execute-phase-response-language.md

@@ -2,6 +2,12 @@
 
 **If `response_language` is set:** User-facing orchestrator output (questions, narration, report-template prose) in `{response_language}`; technical terms, code, file paths, and subagent prompts stay in English. Pass `response_language: {value}` into every spawned subagent prompt so any user-facing output they produce stays in the configured language.
 
+**The `gsd-verifier` subagent has no workflow file of its own (#2529):** the `verify_phase_goal` step reaches it by dispatch, not by reading a workflow, so there is no file in which to place a directive — the dispatch prompt is the only place its coverage can live. That prompt MUST carry this line verbatim, immediately after `Create VERIFICATION.md.`:
+
+`Use response_language {response_language} for all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code and paths.`
+
+It lives here rather than inline in `workflows/execute-phase.md` for the same reason the rest of this file does — that workflow is held under the frozen byte ceiling named below, and this `@-reference` is eager, so the orchestrator loads this instruction with the workflow either way.
+
 The literal report templates embedded in this workflow (`## Execution Plan`, `## Phase {X}: {Name} Execution Complete`, `## ⚠ Phase {X}: {Name} — Gaps Found`, etc.) are a structural source, not literal output to copy verbatim — render their prose translated into `{response_language}` while keeping headings' structural markers, table columns, IDs, commands, and file paths unchanged.
 
 This directive was extracted from `workflows/execute-phase.md` to keep that file under the frozen pre-phase-6 byte ceiling (ADR-857 Phase 6 capstone, `tests/claude-orchestration.test.cjs`). The `@-reference` is eager, so the runtime still loads this content alongside the workflow — the extraction is purely a file-size discipline, not a lazy-load optimization.

package/gsd-core/references/executor-examples.md

@@ -69,6 +69,48 @@
 - MAYBE → Rule 4 (ask the user)
 - NO → Out of scope (log to deferred-items.md)
 
+### Writing `deferred-items.md`
+
+The file has no template — write it by hand, as a Markdown list under a
+`## Deferred Items` heading. What counts as one entry:
+
+- One entry per top-level list item. `-`, `*` and `+` all count, and so does a
+  dot-terminated ordered marker (`1.`) when the list starts at `0.` or `1.`, or
+  continues a list already open at that level — a sentence that merely opens
+  with a number (`2026. was a bad year`) is prose, not an item, and so is a
+  list numbered from `2.` upward until its first `0.`/`1.` line. `1)` is not a
+  marker here, and neither is an ordinal past nine digits (`999999999.`
+  counts, `1234567890.` does not).
+- Continuation lines indent beneath their entry. Fields go on those lines:
+  `status: resolved`, or the bolded `**Status:** resolved` convention. **The
+  BARE key is lower-case only** — write `Status: resolved` without the bold and
+  the field is not read, so the entry stays open with no warning. Bold it or
+  lower-case it. The bolded form matches the key case-insensitively, and the
+  VALUE is case-insensitive in both forms.
+- A `* * *` or `- - -` separator closes the list rather than opening an entry,
+  and nothing inside a fenced code block is an entry or a field — at any indent,
+  including one deeper than CommonMark's three-space cap, which is what a fence
+  written under a nested bullet looks like. A fence that is never closed runs to
+  the end of its own entry and no further, so an unclosed delimiter cannot hide
+  the entries after it — a closed pair of delimiters is a fence, whatever sits
+  between them.
+
+An entry is RESOLVED only if it carries an explicit `status: resolved`. Anything
+else — including an entry with no `status:` at all — stays open and will surface
+in `audit-open`, `audit-uat` and `complete-milestone`. That is deliberate: the
+scanner never silently drops a possibly-open item. What it reads as something
+other than an item is the short list above — a fenced line, a separator, and an
+ordered list numbered from `2.` upward at a paragraph position — and nothing
+else.
+
+```markdown
+## Deferred Items
+
+- Retry budget is hardcoded at 3
+  status: open
+  **What:** `fetchWithRetry` ignores the configured budget.
+```
+
 ## Checkpoint Examples
 
 ### Good checkpoint placement

package/gsd-core/references/few-shot-examples/plan-checker.md

@@ -17,13 +17,13 @@ last_calibrated: 2026-03-24
 > ```yaml
 > issues:
 >   - dimension: task_completeness
->     severity: BLOCKER
->     finding: "Task T1 action says 'implement the authentication feature' without naming target files, functions to create, or middleware to apply. Executor cannot determine what to build."
->     affected_field: "<action>"
->     suggested_fix: "Specify: create authMiddleware in src/middleware/auth.js, apply to routes in src/routes/api.js lines 12-45, verify with integration test"
+>     severity: blocker
+>     required_property: "Every task action names its target files, and any functions it creates"
+>     description: "Task T1 action says 'implement the authentication feature' without naming target files, functions to create, or middleware to apply. Executor cannot determine what to build."
+>     fix_hint: "Specify: create authMiddleware in src/middleware/auth.js, apply to routes in src/routes/api.js lines 12-45, verify with integration test"
 > ```
 
-**Why this is good:** The checker cited the specific dimension (task_completeness), quoted the problematic text, explained why it is a blocker (executor cannot determine what to build), and gave a concrete fix with file paths and function names. The finding is actionable -- the planner knows exactly what to add.
+**Why this is good:** The checker stated the invariant that failed (`required_property`), cited the specific dimension (task_completeness), quoted the problematic text as evidence, explained why it is a blocker (executor cannot determine what to build), and gave a concrete example route with file paths and function names. The finding is actionable -- and because the binding payload is the property rather than the example, the planner may satisfy it a different way.
 
 ### Example 2: BLOCKER for same-wave file conflict between two plans
 
@@ -34,13 +34,13 @@ last_calibrated: 2026-03-24
 > ```yaml
 > issues:
 >   - dimension: dependency_correctness
->     severity: BLOCKER
->     finding: "Plans 01 and 02 both modify gsd-core/workflows/execute-phase.md in wave 1 with no depends_on relationship. Concurrent execution will cause merge conflicts or lost changes."
->     affected_field: "files_modified"
->     suggested_fix: "Either move Plan 02 to wave 2 with depends_on: ['01'] or consolidate the file changes into a single plan"
+>     severity: blocker
+>     required_property: "Same-wave plans never modify the same file without a declared dependency"
+>     description: "Plans 01 and 02 both modify gsd-core/workflows/execute-phase.md in wave 1 with no depends_on relationship. Concurrent execution will cause merge conflicts or lost changes."
+>     fix_hint: "Either move Plan 02 to wave 2 with depends_on: ['01'] or consolidate the file changes into a single plan"
 > ```
 
-**Why this is good:** The checker identified a real structural problem -- two plans modifying the same file in the same wave without a dependency relationship. It cited dependency_correctness, named both plans, the conflicting file, and provided two alternative fixes.
+**Why this is good:** The checker identified a real structural problem -- two plans modifying the same file in the same wave without a dependency relationship. It stated the property that must hold, cited dependency_correctness, named both plans and the conflicting file, and offered two example routes -- neither of which binds, since either makes the property true.
 
 ## Negative Examples
 
@@ -64,10 +64,10 @@ last_calibrated: 2026-03-24
 > ```yaml
 > issues:
 >   - dimension: scope_sanity
->     severity: INFO
->     finding: "Plan has 3 tasks -- consider splitting into smaller plans for faster iteration"
->     affected_field: "task count"
->     suggested_fix: "Split tasks into separate plans"
+>     severity: info
+>     required_property: "Each plan stays within the per-plan context budget"
+>     description: "Plan has 3 tasks -- consider splitting into smaller plans for faster iteration"
+>     fix_hint: "Split tasks into separate plans"
 > ```
 
-**Why this is bad:** The checker flagged a non-issue. scope_sanity allows 2-3 tasks per plan -- 3 tasks is within limits. The checker applied a personal preference ("smaller is better") rather than the documented threshold. This wastes planner time on false positives and erodes trust in the checker's judgment. A correct check would produce no issue for this plan.
+**Why this is bad:** The checker flagged a non-issue. The `required_property` it states is already satisfied, which is the tell: scope_sanity allows 2-3 tasks per plan -- 3 tasks is within limits. The checker applied a personal preference ("smaller is better") rather than the documented threshold. This wastes planner time on false positives and erodes trust in the checker's judgment. A correct check would produce no issue for this plan.

package/gsd-core/references/mvp-concepts.md

@@ -12,7 +12,7 @@ Canonical domain terms for the concepts named below live in [CONTEXT.md](../../C
 | `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/execute-mvp-tdd.md` | **Gate.** 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 `TDD_MODE=true` (#4011) |
 | `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
@@ -33,7 +33,7 @@ If you're looking for the canonical statement of a concept, this is where to fin
 
 - **`--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.
+- **`TDD_MODE` is independent of `MVP_MODE`.** TDD can be on without MVP, MVP can be on without TDD. The TDD runtime gate activates on `TDD_MODE` alone (#4011); MVP mode remains free to imply TDD without being required by it.
 - **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

package/gsd-core/references/plan-checker-examples.md

@@ -0,0 +1,41 @@
+# Plan-Checker Examples
+
+> Progressive-disclosure reference for `agents/gsd-plan-checker.md`. The checker
+> inlines this file from its `<examples>` block via `@`; the calibrated few-shot
+> set lives separately in `gsd-core/references/few-shot-examples/plan-checker.md`.
+
+## Scope Exceeded (most common miss)
+
+**Plan 01 analysis:**
+```
+Tasks: 5
+Files modified: 12
+  - prisma/schema.prisma
+  - src/app/api/auth/login/route.ts
+  - src/app/api/auth/logout/route.ts
+  - src/app/api/auth/refresh/route.ts
+  - src/middleware.ts
+  - src/lib/auth.ts
+  - src/lib/jwt.ts
+  - src/components/LoginForm.tsx
+  - src/components/LogoutButton.tsx
+  - src/app/login/page.tsx
+  - src/app/dashboard/page.tsx
+  - src/types/auth.ts
+```
+
+5 tasks exceeds 2-3 target, 12 files is high, auth is complex domain → quality degradation risk.
+
+```yaml
+issue:
+  dimension: scope_sanity
+  severity: blocker
+  required_property: "Each plan stays within the per-plan context budget"
+  description: "Plan 01 has 5 tasks with 12 files - exceeds context budget"
+  plan: "01"
+  metrics:
+    tasks: 5
+    files: 12
+    estimated_context: "~80%"
+  fix_hint: "Split into: 01 (schema + API), 02 (middleware + lib), 03 (UI components)"
+```

package/gsd-core/references/planner-antipatterns.md

@@ -228,3 +228,28 @@ test -f src/i18n/en.json && test -f src/i18n/de.json || { echo "missing input fi
 ```
 
 **When `|| echo "default"` is acceptable:** only when absence is semantically the default AND the result is NOT used in a comparison that should detect absence.
+
+## External Review Before PR Open (#4107)
+
+Apply this ordering only when opening the PR is known to trigger automatic external review and the plan also has internal review lanes.
+
+**Bad:**
+
+```text
+Wave 1: Open PR; automatic external review starts
+Wave 2: Run internal review
+Wave 3: Apply accepted fixes
+```
+
+The external reviewer spends its first pass on a diff the plan already expects to change.
+
+**Good:**
+
+```text
+Wave 1: Run internal review
+Wave 2: Apply accepted fixes
+Wave 3: If applicable, re-check the open-time property; then immediately open PR
+Wave 4+: Run post-open CI, external review, and tracking work
+```
+
+Nothing may intervene between an applicable re-check and the open. Post-open work may follow; "immediately" constrains only that gap. Opening-time properties do not justify an early PR.

package/gsd-core/references/planner-chunked.md

@@ -23,7 +23,11 @@ Return:
 | {padded_phase}-02 | [brief objective] | 1 | none | REQ-003 |
 ```
 
-The orchestrator reads this table, then spawns one single-plan Task per row.
+The orchestrator reads this table, groups rows by `Wave` (ascending, blank treated as `1`), then
+spawns one single-plan Task per row — one Wave at a time, serially across Waves. Within a Wave,
+Tasks are spawned one at a time by default, or together (`run_in_background=true` on each, issued
+in one message) when `planning.chunked_parallel: true` and the host's negotiated dispatch capacity
+supports it (#3777; see `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md` §8.5.2).
 
 ### single-plan
 

package/gsd-core/references/planner-coupling.md

@@ -0,0 +1,42 @@
+# Planner Coupling — Same-Wave Shared Mutable State
+
+> Progressive-disclosure reference for `agents/gsd-planner.md`. The planner agent
+> reads this file when assigning waves (issue #3724). The slim pointer in
+> `agents/gsd-planner.md` → `assign_waves` routes here; the canonical schema row
+> for `coupling_justified` lives in `docs/reference/plan-md.md`. The verifying
+> side is `agents/gsd-plan-checker.md` Dimension 3b (#1954).
+
+## The rule
+
+`files_modified`/`files_deleted` overlap is not the only coupling between
+same-wave plans. If two plans in the same wave touch the same **mutable
+resource** through their task actions — a config key, DB table/row, migration,
+env var, singleton, cache — with at least one writer, or one plan produces a
+prerequisite the other consumes, the pair is coupled through shared state even
+though no file overlaps: under parallel execution the outcome depends on which
+executor gets there first.
+
+Resolve it one of three ways, in order of preference:
+
+1. **Declare the edge** — add the producing plan to the consumer's
+   `depends_on`. Wave assignment then orders them automatically.
+2. **Re-wave** — move one plan to a later wave when the dependency direction
+   is unclear but an ordering is still wanted.
+3. **Justify the pair** — when the coupling is deliberate and genuinely
+   order-independent (both orders produce a correct result), record it in
+   either plan's frontmatter, one `"plan-id: reason"` entry per coupled peer:
+
+   ```yaml
+   coupling_justified: ["03-02: both plans append independent keys to config; order irrelevant"]
+   ```
+
+   The plan-checker's Dimension 3b recognizes the declaration and does not
+   flag the pair, so a deliberately coupled plan set passes verification
+   without serializing waves it was designed to run in parallel.
+
+## Why declare it up front
+
+Dimension 3b flags same-wave plan pairs with an undeclared shared-mutable-state
+dependency (advisory severity — it never blocks). Declaring the edge, re-waving,
+or justifying the pair at plan time means the first checker pass comes back
+clean instead of surfacing an advisory the planner then has to interpret.

package/gsd-core/references/planner-quick-batch.md

@@ -0,0 +1,71 @@
+# Quick-Batch Mode — Planner Reference
+
+Triggered when `<planning_context>` declares `**Mode:** quick-batch`
+(#3676, epic #3344, ADR-1239 "Quick-batch binding"). One dispatch = one
+item's plan — the SAME single-plan, 1-3-task scope as `/gsd:quick`'s own
+`quick`/`quick-full` modes, with one fixed difference: **`depends_on` and
+`files_modified` frontmatter are ALWAYS required, regardless of whether
+`--validate` was requested.** This reuses the EXISTING frontmatter grammar
+(the same keys full phase planning already emits — see the frontmatter
+schema table above); it is not a new schema.
+
+**Why always, not gated on `--validate`.** The coordinating workflow
+(`gsd-core/workflows/quick-batch.md`) recomputes every item's execution wave
+from these two fields after each DAG layer's planners return (`quick-batch
+update`, wrapping `updateBatchItems`) — without them, every item stays in
+wave 0 forever and the batch cannot parallelize independent items or
+sequence dependent ones correctly. This is load-bearing dispatch input, not
+an optional quality signal.
+
+### `depends_on` — reference SIBLING items by `quick_id`, never invent one
+
+The `<planning_context>` you receive includes a **full batch task catalog** —
+every item's `quick_id` + description, not just your own. When your item's
+implementation genuinely requires another item's item to land first (shared
+file, prerequisite API, sequencing the user implied), declare it:
+
+```yaml
+depends_on: ["260101-abc"]   # a quick_id from the task catalog
+```
+
+- Reference ONLY `quick_id`s from the task catalog you were given. Never
+  reference a plan id from a phase, another batch, or a value you invented.
+- Empty array (`depends_on: []`) is the correct, common answer when your item
+  is genuinely independent — do not manufacture a dependency to seem
+  thorough.
+- A dependency on your OWN `quick_id` (self-reference) or on an id outside
+  the catalog is rejected by `quick-batch update` and blocks the whole
+  layer's persistence — when uncertain, prefer `[]` over a guess.
+
+### `files_modified` — every path your plan's tasks will touch
+
+```yaml
+files_modified: ["src/foo.ts", "tests/foo.test.ts"]
+```
+
+Used two ways downstream, both from THIS field (never re-derived from your
+plan's prose): (1) `partitionByFileOverlap` splits same-wave items that
+would touch the same file into separate waves, so two isolated worktrees
+never race on one path; (2) at merge time the coordinator reads it FRESH from
+your PLAN.md (not from what you declared here at planning time — keep the
+frontmatter accurate if you revise the plan) for the advisory scope-
+conformance check.
+
+### `files_deleted` — only if your plan removes a file
+
+```yaml
+files_deleted: ["legacy/old-module.ts"]
+```
+
+Optional; omit entirely when your plan deletes nothing. If your plan DOES
+delete a file and you omit this, the merge's deletions guard blocks that
+deletion as undeclared — there is no "authorize everything" fallback.
+
+### What quick-batch mode does NOT need
+
+Same exclusions as `/gsd:quick`'s own modes: no `requirements` (no ROADMAP
+linkage — a quick-batch item is not a phase), no `estimate` block, no
+`user_setup` unless genuinely needed. `must_haves` is required only when the
+calling prompt's own `<constraints>` says so (mirrors `--validate`'s
+existing quick-full behavior) — that instruction rides the prompt, not this
+reference.

package/gsd-core/references/planner-reviews.md

@@ -40,3 +40,50 @@ Use standard PLANNING COMPLETE return format, adding a reviews section:
 |---------|--------|
 | {concern} | {why — out of scope, disagree, etc.} |
 ```
+
+### Step 5: Write the ledger into PLAN.md (#3806)
+
+The two tables above are not only the planner's return payload — they are also the **canonical
+Review Dispositions Ledger**, and they belong in the affected PLAN.md itself, in this exact shape.
+`gsd-core/workflows/plan-phase.md` (`<review_incorporation_contract>`) and
+`agents/gsd-plan-checker.md` (Review Incorporation dimension) both point back to this section for
+the ledger's shape rather than restating it — this is the one place it is defined.
+
+## Review Dispositions Ledger
+
+Add or extend a `## Review Dispositions Ledger` section in the affected PLAN.md, containing one
+`### Round {N} — {REVIEWS_sha}` subsection per reviews-mode round that touched this plan, where
+`{REVIEWS_sha}` is the commit that wrote the REVIEWS.md snapshot being ruled on (the short sha from
+`git log -1 --format=%h -- <phase_dir>/<NN>-REVIEWS.md`, after `workflows/review.md`'s REVIEWS.md
+commit step). Under each round heading, use the two tables from Step 4 above, unchanged in shape:
+
+```markdown
+## Review Dispositions Ledger
+
+### Round 1 — a1b2c3d
+
+### Review Feedback Addressed
+| Concern | Severity | How Addressed |
+|---------|----------|---------------|
+| {concern} | HIGH | Plan {N}, Task {M}: {how} |
+
+### Review Feedback Deferred
+| Concern | Reason |
+|---------|--------|
+| {concern} | {why — out of scope, disagree, etc.} |
+```
+
+**Anchoring.** Any reference to a specific REVIEWS.md line cites `L##@{REVIEWS_sha}` (e.g.
+`L32@a1b2c3d`) — a bare line number is meaningless once the next round rewrites REVIEWS.md
+wholesale. `{Concern}` and `{Reason}` stay free text; do not invent a reviewer/severity enum — the
+reviewer roster is capability-owned and open to third-party additions (see each capability's
+`reviewer.reviewsSection`).
+
+**Append-only.** A later round never edits or deletes a prior round's tables. To overturn a prior
+round's verdict, add a new row in the current round's table whose Reason/How Addressed names the
+round and concern it supersedes (e.g. "Supersedes Round 1 Deferred: {concern} — now addressed in
+Plan 3").
+
+**Out of scope for this contract.** A deterministic lint/check verb that mechanically enforces this
+shape is a separate, later addition (#3806 part 2) — this section defines the format only. Legacy
+PLAN.md content written before this convention existed is not migrated or flagged by it.