@opengsd/gsd-core 1.11.0 → 1.13.0

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/execute-phase-wave-guard.md

@@ -13,9 +13,9 @@
 
    ```bash
    if [ "$ISOLATION" = "harness-worktree" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
-     _WAVE_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
+     _WAVE_DEGRADE=$(gsd_run query worktree.base-check --mode "$ISOLATION" --pick shouldDegrade 2>/dev/null || true)
      if [ "$_WAVE_DEGRADE" = "true" ]; then
-       _WAVE_DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
+       _WAVE_DEGRADE_MSG=$(gsd_run query worktree.base-check --mode "$ISOLATION" --pick message 2>/dev/null || true)
        [ -n "$_WAVE_DEGRADE_MSG" ] && printf '%s\n' "$_WAVE_DEGRADE_MSG" >&2
        echo "⚠ [#1369] Worktree fork base diverged from orchestrator HEAD (wave merges advanced HEAD past origin/HEAD). Auto-degrading to sequential mode for this wave to avoid base-mismatch halts." >&2
        # Both must move together (#2652): dispatch keys on ISOLATION.
@@ -27,11 +27,13 @@
 
    If `shouldDegrade` is `true`, override `USE_WORKTREES=false` for **this wave only** —
    all plans in this wave execute sequentially on the main working tree. Later waves re-run
-   this check and may re-enable worktree isolation if `origin/HEAD` is updated (e.g. via
-   `git fetch` or `worktree.baseRef:"head"` config).
+   this check and may re-enable worktree isolation once `origin/HEAD` matches HEAD again
+   (e.g. via `git fetch` or a push that advances it).
 
-   **To avoid this degrade across all waves:** set `worktree.baseRef:"head"` in
-   `.claude/settings.local.json` (or run `gsd-tools worktree set-baseref`). This tells
-   Claude Code to fork from the live HEAD instead of `origin/HEAD`, so each wave's new
-   worktrees always start from the correct post-merge base. See #683 for the base-ref
-   configuration detail.
+   **Why `worktree.baseRef:"head"` does not avoid this degrade (#48, #3659):** the runtime
+   harness does not read project-settings `baseRef` — an isolated dispatch always forks from
+   `origin/HEAD` regardless of the setting, so the check compares against the real fork base
+   and degrades whenever HEAD has diverged. Parallel worktrees return once HEAD is
+   merged/pushed so `origin/HEAD` matches it. The setting still restores parallel execution
+   on runtimes where GSD itself creates the worktrees (orchestrator-managed isolation:
+   Codex, OpenCode, Kimi, Kimi Code). See #683 for the base-ref configuration detail.

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/failing-direction.md

@@ -0,0 +1,78 @@
+# Check 8f — Stated Failing Direction (#3172)
+
+> Reference file for gsd-plan-checker agent. Loaded on-demand via `@` reference.
+
+**Question:** For each runnable `<automated>` command, does the plan say what output constitutes
+failure?
+
+Checks 8a–8d ask whether an acceptance command is *present*, and Verify Command Path
+Resolvability asks whether its target *resolves*. This one asks whether the command is
+**falsifiable at all**. A command with no expressible failure mode is not an acceptance test —
+it reads as rigour and delivers none.
+
+#3172: a planner emitted 21 `<automated>` commands that could not run. Cargo exited non-zero, so
+that instance failed loudly — luck, not design. The same class of error with a command that
+exits 0 on a no-op passes green and silently. Requiring a stated failing direction is the only
+shape that catches the silent case, because it forces the plan to name the failure signal rather
+than assume the command has one.
+
+## The contract
+
+```xml
+<verify>
+  <automated>npm --prefix apps/api test -- auth.spec.ts</automated>
+  <fails_when>non-zero exit, or "0 passed" in the summary line</fails_when>
+</verify>
+```
+
+Within one `<task>`, each `<fails_when>` binds to the nearest **preceding** `<automated>`; a
+command's binding statement is the **first** one that follows it. N runnable commands need N
+statements.
+
+## Do not hand-reason this
+
+`gsd-core/workflows/plan-phase.md` runs the deterministic probe **before** spawning this checker
+and interpolates the result into the verification prompt as `{FAILING_DIRECTIONS}`, inside a
+`<failing_direction_probe>` block. This check reads that already-supplied JSON — it never invokes
+`gsd_run check verify-failure-directions` itself. If `{FAILING_DIRECTIONS}` is absent from the
+prompt, treat this check as silent (nothing to check) rather than trying to run the probe.
+
+The probe never executes command text (PLAN.md is untrusted, LLM-authored). It is a **presence**
+recognizer: it proves a statement exists and is not a placeholder. It does not judge whether the
+statement names the *right* signal — that judgment is yours, below.
+
+## Process — act on `severity` only
+
+| `severity` | `status` | Action |
+|---|---|---|
+| `blocker` | `missing` | **BLOCKER** — quote the `command` verbatim: it has no stated failing direction |
+| `blocker` | `empty` | **BLOCKER** — a `<fails_when>` is present but blank |
+| `blocker` | `placeholder` | **BLOCKER** — quote the placeholder text; `TBD` is not a failure signal |
+| `warning` | `orphan` | **WARNING** — a `<fails_when>` that follows no command; it satisfies nothing |
+| `none` | `ok` / `sentinel` | silent |
+
+Rules:
+
+- **Report, never prescribe.** State which command has no stated failure mode. Do **not** author
+  the statement for the planner. A prescribed statement is copied verbatim and carries zero
+  information — that reproduces #3172 one level up, exactly as the #2401 probe refuses to
+  prescribe a replacement path.
+- `status: sentinel` is a `MISSING — Wave 0 must create …` placeholder command. It is not
+  runnable, so it has no failure mode to state. **Not a finding.** Say nothing; checks 8a/8d
+  own it.
+- A non-empty `readError` means the probe **could not look**. Report that as a WARNING in its own
+  words; it is not a clean bill of health.
+- **Your added judgment, on `ok` rows only:** a statement that is present, non-empty and
+  non-placeholder can still be vacuous — *"the command fails"*, *"it doesn't work"*, *"an error
+  occurs"* restate the word "failure" without naming an observable signal. Raise those as a
+  **WARNING**, naming what a usable statement looks like (an exit code, a string in the output, a
+  missing line). Do **not** escalate a vacuous statement to BLOCKER: the deterministic layer owns
+  the blockers so that a BLOCKER is always reproducible, and prose judgment stays advisory.
+- **Length is not a signal.** `<fails_when>non-zero exit</fails_when>` is a complete failing
+  direction. There is no minimum length, word count, or required keyword.
+
+## Not in scope
+
+A command that runs successfully and asserts nothing (a test-name filter matching zero tests and
+exiting 0) is the adjacent **vacuous pass** problem. It is explicitly out of scope for this
+check — see the issue's "Out of scope". Do not report it here.

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/gate-prompts.md

@@ -2,7 +2,7 @@
 
 Reusable prompt patterns for structured gate checks in workflows and agents.
 
-**For checkpoint box format details, see `gsd-core/references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
+**For checkpoint format details, see `gsd-core/references/ui-brand.md`** -- a checkpoint is a `### CHECKPOINT: {Type}` heading followed by its content, then a `---` break and the bolded action prompt. Never a fixed-width drawn border: it wraps in a narrow pane.
 
 ## Rules
 

package/gsd-core/references/git-integration.md

@@ -51,7 +51,7 @@ Phases:
 What to commit:
 
 ```bash
-gsd-tools query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+gsd_run query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
 ```
 
 </format>
@@ -136,7 +136,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 What to commit:
 
 ```bash
-gsd-tools query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+gsd_run query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -156,7 +156,7 @@ Current: [task name]
 What to commit:
 
 ```bash
-gsd-tools query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+gsd_run query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
 ```
 
 </format>
@@ -279,7 +279,7 @@ Set `commit_docs: false` so planning docs stay local and are not committed to an
 
 1. **Auto-detection:** During `/gsd:new-project`, directories with their own `.git` folder are detected and offered for selection as sub-repos. On subsequent runs, `loadConfig` auto-syncs the `sub_repos` list with the filesystem — adding newly created repos and removing deleted ones. This means `config.json` may be rewritten automatically when repos change on disk.
 2. **File grouping:** Code files are grouped by their sub-repo prefix (e.g., `backend/src/api/users.ts` belongs to the `backend/` repo).
-3. **Independent commits:** Each sub-repo receives its own atomic commit via `gsd-tools.cjs commit-to-subrepo`. File paths are made relative to the sub-repo root before staging.
+3. **Independent commits:** Each sub-repo receives its own atomic commit via `gsd_run commit-to-subrepo`. File paths are made relative to the sub-repo root before staging.
 4. **Planning stays local:** The `.planning/` directory is not committed; it acts as cross-repo coordination.
 
 ### Commit Routing
@@ -287,7 +287,7 @@ Set `commit_docs: false` so planning docs stay local and are not committed to an
 Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
 
 ```bash
-gsd-tools query commit-to-subrepo "feat(02-01): add user API" \
+gsd_run query commit-to-subrepo "feat(02-01): add user API" \
   --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
 ```
 

package/gsd-core/references/git-planning-commit.md

@@ -1,6 +1,6 @@
 # Git Planning Commit
 
-Commit planning artifacts via `gsd-tools query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `gsd-tools.cjs commit`).
+Commit planning artifacts via `gsd_run query commit`, which checks `commit_docs` config and gitignore status.
 
 ## Commit via CLI
 
@@ -9,7 +9,7 @@ Pass the message first, then file paths via `--files`. Both `commit` and `commit
 Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
 
 ```bash
-gsd-tools query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+gsd_run query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
 ```
 
 The CLI will return `skipped` (with reason) if `commit_docs` is `false`, `.planning/` is gitignored, or a per-phase `phase_commit_docs.<phase-id>` override resolves `false` for the phase being committed. No manual conditional checks needed.
@@ -19,7 +19,7 @@ The CLI will return `skipped` (with reason) if `commit_docs` is `false`, `.plann
 To fold `.planning/` file changes into the previous commit:
 
 ```bash
-gsd-tools query commit "" --files .planning/codebase/*.md --amend
+gsd_run query commit "" --files .planning/codebase/*.md --amend
 ```
 
 ## Commit Message Patterns

package/gsd-core/references/gsd-run-resolver.md

@@ -4,5 +4,5 @@ Use this bootstrap block when a workflow must call `gsd-tools` from the active w
 Keep this resolver centralized; workflows should reference this file instead of copying the shell probe.
 
 ```bash
-_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 ```

package/gsd-core/references/loop-hook-dispatch.md

@@ -96,3 +96,25 @@ Honor `onError` if the check itself errors: `skip` means treat as non-blocking a
 
 If `activeHooks` is absent, null, or an empty array, skip silently and continue to the next
 step in the workflow. No output to the user is needed.
+
+## The `execute:task` point (a different shape)
+
+`execute:task` exists below wave granularity — it is evaluated once per task, inside the
+`execute:wave:pre` / `execute:wave:post` bracket, immediately before that task's `read_first`
+gate. It is **not** one of the 12 points documented above, does not appear in `steps` /
+`contributions` / `gates`, and is never dispatched through `gsd_run loop render-hooks <point>` or
+this file's `activeHooks` envelope.
+
+Instead, a capability declares task-content resolution directly in its manifest body via
+`taskContentResolver` (`trackerPrefix` + a bounded `invoke`) — see
+[Capability manifest reference](../../docs/reference/capability-manifest.md). `execute-plan.md`'s
+per-task loop calls `gsd_run task resolve-content --plan <path> --task-id <tracker-id> --raw`
+directly, an unconditional, required subprocess invocation with a real, binding exit code —
+never a prose-dispatched `step`/`gate` entry chosen from an `activeHooks` array.
+
+This point always runs — there is no `when` config gate and no autonomous-mode elision. That is
+deliberate, not an oversight: the twelve points above are best-effort prose dispatch, which
+`execute:task`'s hard-halt safety property cannot be built on top of (a missed dispatch is
+indistinguishable from a legitimate resolver-empty fallback). See
+[ADR-3646](../../docs/adr/3646-per-task-content-resolution-seam.md) for the full rationale,
+including why a `kind: "gate"` shape was rejected outright.

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

@@ -228,7 +228,7 @@ the next spawn. `effort` (claude runtime) has its own cascade
 install time into the `effort:` frontmatter key of
 `~/.claude/agents/gsd-*.md` — Claude Code's Agent tool has no per-spawn
 effort parameter, so per-agent frontmatter is the only channel. An effort
-config change has no effect until `node gsd-tools.cjs effort sync --apply`
+config change has no effect until `gsd_run effort sync --apply`
 re-syncs the agent files. Codex agents instead pin
 `model_reasoning_effort` in `~/.codex/agents/*.toml` at install time.
 

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/nyquist-compliance.md

@@ -0,0 +1,74 @@
+# Dimension 8 — Nyquist Compliance (checks 8a–8e)
+
+> Reference file for gsd-plan-checker agent. Loaded on-demand via `@` reference.
+> Extracted from `agents/gsd-plan-checker.md` in #3172 to stay under the agent's
+> LARGE size cap. Checks 8a-8e are moved unchanged; the only edit is to the
+> Dimension 8 Output table, which gains a `Failing Direction` column and a
+> stated/runnable tally so check 8f's result is reported alongside them.
+> Check 8f itself lives in its own reference:
+> @gsd-core/references/failing-direction.md
+
+**Skip if:** `workflow.nyquist_validation` is explicitly set to `false` in config.json
+(absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation
+Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not
+applicable)"
+
+## Check 8e — VALIDATION.md Existence (Gate)
+
+Before running checks 8a-8d, verify VALIDATION.md exists:
+
+```bash
+ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null
+```
+
+**If missing:** **BLOCKING FAIL** — "VALIDATION.md not found for phase {N}. Re-run
+`/gsd:plan-phase {N} --research` to regenerate."
+Skip checks 8a-8d entirely. Report Dimension 8 as FAIL with this single issue.
+
+**If exists:** Proceed to checks 8a-8d.
+
+## Check 8a — Automated Verify Presence
+
+For each `<task>` in each plan:
+- `<verify>` must contain `<automated>` command, OR a Wave 0 dependency that creates the test
+  first
+- If `<automated>` is absent with no Wave 0 dependency → **BLOCKING FAIL**
+- If `<automated>` says "MISSING", a Wave 0 task must reference the same test file path →
+  **BLOCKING FAIL** if link broken
+
+## Check 8b — Feedback Latency Assessment
+
+For each `<automated>` command:
+- Full E2E suite (playwright, cypress, selenium) → **WARNING** — suggest faster unit/smoke test
+- Watch mode flags (`--watchAll`) → **BLOCKING FAIL**
+- Delays > 30 seconds → **WARNING**
+
+## Check 8c — Sampling Continuity
+
+Map tasks to waves. Per wave, any consecutive window of 3 implementation tasks must have ≥2
+with `<automated>` verify. 3 consecutive without → **BLOCKING FAIL**.
+
+## Check 8d — Wave 0 Completeness
+
+For each `<automated>MISSING</automated>` reference:
+- Wave 0 task must exist with matching `<files>` path
+- Wave 0 plan must execute before dependent task
+- Missing match → **BLOCKING FAIL**
+
+## Dimension 8 Output
+
+```
+## Dimension 8: Nyquist Compliance
+
+| Task | Plan | Wave | Automated Command | Failing Direction | Status |
+|------|------|------|-------------------|-------------------|--------|
+| {task} | {plan} | {wave} | `{command}` | `{fails_when}` / ❌ | ✅ / ❌ |
+
+Sampling: Wave {N}: {X}/{Y} verified → ✅ / ❌
+Wave 0: {test file} → ✅ present / ❌ MISSING
+Failing directions: {stated}/{runnable} → ✅ / ❌
+Overall: ✅ PASS / ❌ FAIL
+```
+
+If FAIL: return to planner with specific fixes. Same revision loop as other dimensions
+(max 3 loops).

package/gsd-core/references/offer-next.md

@@ -4,7 +4,6 @@
   extraction restores byte-budget headroom the frozen ceiling exists to provide.
 -->
 
-
 **Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/gsd:plan-phase {X} --gaps`). No additional routing needed — skip auto-advance.
 
 **No-transition check (spawned by auto-advance chain):**
@@ -41,10 +40,9 @@ STOP. Do not proceed to auto-advance or transition.
 **If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**
 
 ```
-╔══════════════════════════════════════════╗
-║  AUTO-ADVANCING → TRANSITION             ║
-║  Phase {X} verified, continuing chain    ║
-╚══════════════════════════════════════════╝
+### AUTO-ADVANCING → TRANSITION
+
+Phase {X} verified, continuing chain
 ```
 
 Execute the transition workflow inline (do NOT use Agent — orchestrator context is ~10-15%, transition needs phase completion data already in context):

package/gsd-core/references/phase-argument-parsing.md

@@ -14,7 +14,7 @@ From `$ARGUMENTS`:
 The `find-phase` command handles normalization and validation in one step:
 
 ```bash
-PHASE_INFO=$(gsd-tools query find-phase "${PHASE}")
+PHASE_INFO=$(gsd_run query find-phase "${PHASE}")
 ```
 
 Returns JSON with:
@@ -45,7 +45,7 @@ fi
 Use `roadmap get-phase` to validate phase exists:
 
 ```bash
-PHASE_CHECK=$(gsd-tools query roadmap.get-phase "${PHASE}" --pick found)
+PHASE_CHECK=$(gsd_run query roadmap.get-phase "${PHASE}" --pick found)
 if [ "$PHASE_CHECK" = "false" ]; then
   echo "ERROR: Phase ${PHASE} not found in roadmap"
   exit 1
@@ -57,5 +57,5 @@ fi
 Use `find-phase` for directory lookup:
 
 ```bash
-PHASE_DIR=$(gsd-tools query find-phase "${PHASE}" --raw)
+PHASE_DIR=$(gsd_run query find-phase "${PHASE}" --raw)
 ```

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