@opengsd/gsd-core 1.12.0 → 1.14.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/compact-content-gate.md

@@ -0,0 +1,66 @@
+# Compact Content Gate
+
+Shared by every workflow spine split under ADR-4139, and by every lazily-read fragment or
+planning-artifact template given a compact variant under Phase 6 (#4406). States the config check
+and both resolution rules once — a spine or fragment references this file; it never restates
+either check inline.
+
+## The check
+
+```bash
+COMPACT_CONTENT=$(gsd_run query config-get workflow.compact_content --raw 2>/dev/null || echo "false")
+```
+
+## Stream 1 — spine + detail (top-level, eagerly `@`-included workflows)
+
+- **`COMPACT_CONTENT` is `"false"` (default):** Read every part under this workflow's own `detail/` directory (a sibling of this spine, e.g. `gsd-core/workflows/<name>/detail/*.md`) now, in full, before continuing past this point. Their content elaborates on the spine you are reading — treat everything they say as part of this document from here on.
+- **`COMPACT_CONTENT` is `"true"`:** Do not read the detail file. Continue directly with the spine's own content — per ADR-4139 Decision 3, it is complete enough to run this workflow correctly on its own.
+
+**The fail-safe this holds (ADR-4139 Decision 4):** A `Read` that does not fire for any reason (tool error, a skipped step, a misread condition) leaves you running on the spine alone. That is the same, correct, terser state an opted-in project runs in on purpose — never a state with no instructions. The spine's own completeness is what makes this safe; this gate is only ever additive.
+
+## Streams 1b and 4 — variant resolution (lazily-read fragments and planning-artifact templates)
+
+For a `workflows/<name>/{modes,steps,templates}/*.md` fragment or a `gsd-core/templates/**`
+planning-artifact template that has a registered `.compact.md` sibling (same directory, same stem,
+`.compact.md` suffix):
+
+- **`COMPACT_CONTENT` is `"false"` (default), or the file has no registered `.compact.md` sibling:** Read the canonical path exactly as named — unchanged from today.
+- **`COMPACT_CONTENT` is `"true"` and a `.compact.md` sibling is registered:** Read the `.compact.md` sibling instead of the canonical path.
+
+Both files are complete, independently — Read exactly one, never both, and never read the compact
+sibling's content as an addendum to the canonical file.
+
+**The fail-safe this holds:** unlike stream 1, a call site this rule actually applies to is already
+reached only by a runtime `Read` — a missed `Read` already means zero overlay content, with or
+without `workflow.compact_content`. Selecting between two independently-complete files at that
+call site does not introduce a new way to end up with nothing; the worst case is identical to
+today's. This is why stream 1b/4 can use variant-swap (two independent files) where stream 1 could
+not: the degradation-direction argument that ruled out converting stream 1's `@`-includes (ADR-4139
+Decision 4) does not apply at a genuine runtime-`Read` call site, because there is no
+host-guaranteed baseline being traded away there.
+
+**This rule is scoped per call site, not per file.** A `gsd-core/templates/**` file can have both
+kinds of reference in the corpus at once — some places name it inside an eager `@`-include or an
+orchestrator build-time embed (the same mechanism as stream 1, just reaching a template path
+instead of a workflow path), others name it in prose instructing a runtime `Read`. Only the latter
+gets rewritten to point at this rule; an eager reference to the canonical file is left exactly as
+it is, for the same reason stream 1's `@`-includes were left alone — converting it would trade a
+host-guaranteed load for a conditional one. Before wiring any call site, confirm by inspection
+which kind it is; do not assume every mention of a `gsd-core/templates/**` path is a runtime `Read`
+just because the directory's typical case is.
+
+## Stream 2 — agent-skill payloads (the `gsd_run query agent-skills` CLI seam)
+
+`agents/<name>.compact.md`, same directory, same stem, `.compact.md` suffix — registered and
+checked the same way as streams 1b/4. The selection is different: this seam already runs through
+a real function call (`cmdAgentSkills`, `src/init.cts`), so the resolution happens **in code**,
+not by a `gsd_run query config-get` prose instruction. There is nothing to state here for a
+workflow author to follow, because no workflow author calls this seam directly — it fires only
+inside the `#2454` persona fallback for non-Claude, AGENTS-native runtimes that cannot dispatch a
+named subagent.
+
+Same two rules as streams 1b/4, enforced in code instead of prose: `workflow.compact_content` off,
+or no registered `.compact.md` sibling for that agent, serves the canonical persona unchanged; on,
+with a sibling registered, serves the compact one. The one addition code gives that prose could
+not: a missing sibling is disclosed in the served payload itself (a leading `<!-- gsd: no compact
+payload registered ... -->` comment) rather than silently serving canonical with no signal at all.

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/loop-hook-dispatch.md

@@ -57,6 +57,24 @@ Dispatch the referenced unit. Exactly one of `ref.skill`, `ref.agent`, or `ref.c
 
 Wait for the result before continuing to the next hook or the next step.
 
+**`supportsReviewerLanes` (optional, boolean).** A `step` entry may carry
+`supportsReviewerLanes: true` alongside `ref` (#4209). A workflow opts a step into external
+reviewer-lane dispatch by calling `gsd_run review-lane dispatch-step --cap-id <capId> --point
+<point> --explicit <slugs> ...` — `dispatch-step` resolves its OWN active hook for `<point>` (via
+`resolveActiveHooksForPoint`, the same in-process resolver `loop render-hooks` itself calls) and
+checks whether `<capId>`'s hook carries this field before proceeding; the workflow does not
+resolve or gate on the trait itself, only passes the two flags naming which step it is. When the
+trait reads exactly `true`, `dispatch-step` routes through `dispatchReviewerLanes`, the one
+interpreter in `src/reviewer-step-dispatch.cts` that reuses the existing reviewer-lane selection,
+planning, and invocation machinery, so any explicitly selected reviewer lane also reviews the
+same scope. Absent or `false` is inert: `dispatch-step` itself is a no-op (a non-boolean value is
+rejected by `capability-validator.cjs` at load time, so it never reaches `dispatch-step` at all).
+This is the only place a step opts into reviewer-lane support: a capability beyond `code-review`
+reuses it by declaring the same trait on its own step and calling `dispatch-step` with
+`--cap-id`/`--point`, with zero bespoke TRAIT-RESOLUTION code of its own. The workflow still owns
+matching its own CLI flags against the reviewer-lane roster and assembling the evidence block
+handed to its consolidator — those are NOT part of what this trait makes reusable.
+
 A `step` is **advisory by construction**: it never blocks or redirects the host workflow —
 that is what a `gate` is for. Each dispatch is best-effort; on error record a warning and
 continue, honoring `onError`.

package/gsd-core/references/model-profiles.md

@@ -58,6 +58,10 @@ Model profiles control which Claude model each GSD agent uses. This allows balan
 3. **Profile table** — the per-agent column from the active `model_profile`
 4. **Runtime default** — when nothing else applies
 
+Steps 2–4 select the *tier*; a `model_profile_overrides.<runtime>.<tier>` entry then
+maps that tier to a concrete model (#4192 — honored on the claude runtime as well, so
+pinning composes with tiering instead of replacing it).
+
 ### Why two layers above the profile?
 
 - **Profile** is a global tier strategy (everyone runs balanced).
@@ -215,8 +219,11 @@ is (highest → lowest):
    (see §Dynamic Routing — escalation steps tier up per attempt counter)
 4. If no dynamic_routing match, check models[phase_type] for a phase-type tier
    (see §Per-Phase-Type Model Map for the agent → phase-type mapping)
-5. If no phase-type slot, look up agent in profile table
-6. Pass model parameter to Task call
+5. Check model_profile_overrides.<runtime>.<tier> for a per-tier model override
+   (honored on the claude runtime too — #4192; verbatim unless it maps to the
+   current tier alias)
+6. If no phase-type slot, look up agent in profile table
+7. Pass model parameter to Task call
 ```
 
 `model` and `effort` resolve through different mechanisms at different
@@ -246,7 +253,9 @@ Override specific agents without changing the entire profile:
 }
 ```
 
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
+Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `fable`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`). `fable` is a Claude Code Agent-tool alias, not a GSD profile tier — it has no column in the profile table above.
+
+On the Claude runtime, fully-qualified Claude model IDs are honored as explicit generation pins (#4192): an ID that names the current tier default (e.g. `"claude-sonnet-5"`) resolves to its tier alias — the same model in the form the Agent tool always accepts — while any other ID (e.g. `"claude-opus-4-7"`) resolves verbatim, with a warn-once stderr note that setups accepting only tier aliases will not honor a full ID. To pin a generation for a whole tier rather than one agent, set `model_profile_overrides.claude.<tier>` (see docs/CONFIGURATION.md — Runtime-Aware Profiles).
 
 ## Switching Profiles
 

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.