@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/references/checkpoints.md

@@ -30,7 +30,7 @@ The gate spans two layers, and both must honor it. `gsd-executor` refuses to aut
 
 **When:** Claude completed automated work, human confirms it works correctly.
 
-> **Default mode (#3309): `workflow.human_verify_mode = end-of-phase`.** New projects do NOT halt mid-flight at `checkpoint:human-verify`. The planner suppresses those task emissions and embeds the verification details into the relevant `auto` task's `<verify><human-check>` block; the verifier harvests every `<verify><human-check>` at end-of-phase (Step 8) and consolidates them into the existing `human_needed` → `{phase_num}-UAT.md` flow in `workflows/execute-phase.md`. The user reviews everything in one batch.
+> **Default mode (#3309): `workflow.human_verify_mode = end-of-phase`.** New projects do NOT halt mid-flight at *planner-emitted* `checkpoint:human-verify` tasks. (The executor-synthesized **tracer feedback gate** is the one runtime checkpoint this mode also governs, with its own precedence chain — see "Tracer feedback gate (#3299)" below.) The planner suppresses those task emissions and embeds the verification details into the relevant `auto` task's `<verify><human-check>` block; the verifier harvests every `<verify><human-check>` at end-of-phase (Step 8) and consolidates them into the existing `human_needed` → `{phase_num}-UAT.md` flow in `workflows/execute-phase.md`. The user reviews everything in one batch.
 >
 > **Why this is the default:** every mid-flight halt costs a full executor cold-start (CLAUDE.md, MEMORY.md, STATE.md, plan re-read on respawn) because subagent context is discarded across the pause. A plan with N human-verify checkpoints pays the cold-start cost N+1 times — measured at "tens of thousands of tokens" per round-trip on real projects.
 >
@@ -107,6 +107,30 @@ The gate spans two layers, and both must honor it. `gsd-executor` refuses to aut
   <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 ```
+
+### Tracer feedback gate (#3299)
+
+A `type="tracer"` task is followed by an early integration checkpoint on the proven slice, run BEFORE any expansion task. This checkpoint is **synthesized by the executor at runtime** — no planner emits it — so planner-side `human_verify_mode` suppression cannot reach it. It must therefore consult the mode itself.
+
+Evaluate the rows **in order** and take the first that matches — they are a precedence chain, not independent conditions:
+
+| # | Run | Tracer `<verify>` | Behavior |
+|---|---|---|---|
+| 1 | **Any run, any mode** (incl. auto) | task carries `gate="blocking-human"` | **STOP → `checkpoint:human-verify`.** Never auto-continued. |
+| 2 | Auto mode active (`AUTO_CHAIN`/`AUTO_CFG`) | any (row 1 already took `blocking-human`) | Re-run verify; HALT on failure, continue on success. **Pre-existing behavior — unchanged by #3299.** |
+| 3 | Interactive, `end-of-phase` (default) | only `<automated>` | Re-run verify; HALT on failure, continue to expansion on success — **no checkpoint** |
+| 4 | Interactive, `end-of-phase` | carries `<human-check>` | STOP → `checkpoint:human-verify` |
+| 5 | Interactive, `mid-flight` | any | STOP → `checkpoint:human-verify` |
+
+**Carve-outs — the #3299 auto-continue (row 3) applies ONLY when all three hold:** the run is interactive, the mode is `end-of-phase`, and the tracer's `<verify>` contains only `<automated>`. Anything else STOPs or falls to the pre-existing auto-mode branch. HALT-on-failure is unconditional in rows 2 and 3 alike: a failing tracer never becomes an approvable checkpoint and never proceeds to expansion, because layering expansion onto a broken slice is the failure this gate exists to prevent.
+
+Row 1 is deliberately **not** scoped to interactive runs. Golden rule 6 above states that `gate="blocking-human"` stops for a human in *every* mode including auto-mode, and a precedence chain that let an autonomous run continue past it would make this file assert two incompatible rules about the same gate. No planner emits `gate` on a `type="tracer"` task today, but `src/verify.cts` parses only `type` and does not consult `gate` on non-checkpoint tasks, so a hand-authored, imported, or externally-generated `PLAN.md` can carry it and validate — unreachable by our planner is not unreachable.
+
+Read `HUMAN_VERIFY_MODE` with an explicit default — `workflow.human_verify_mode` is absent from `SCHEMA_DEFAULTS`, so a bare `config-get` exits non-zero with `Key not found` on any project whose `config.json` predates #3309:
+
+```bash
+HUMAN_VERIFY_MODE=$(gsd_run query config-get workflow.human_verify_mode --default end-of-phase --raw 2>/dev/null || echo "end-of-phase")
+```
 </type>
 
 <type name="decision">
@@ -299,9 +323,7 @@ When Claude encounters `type="checkpoint:*"`:
 
 **For checkpoint:human-verify:**
 ```
-╔═══════════════════════════════════════════════════════╗
-║  CHECKPOINT: Verification Required                    ║
-╚═══════════════════════════════════════════════════════╝
+### CHECKPOINT: Verification Required
 
 Progress: 5/8 tasks complete
 Task: Responsive dashboard layout
@@ -314,16 +336,14 @@ How to verify:
   3. Tablet (768px): Sidebar collapses to icons
   4. Mobile (375px): Sidebar hidden, hamburger menu appears
 
-────────────────────────────────────────────────────────
-→ YOUR ACTION: Type "approved" or describe issues
-────────────────────────────────────────────────────────
+---
+
+**→ YOUR ACTION: Type "approved" or describe issues**
 ```
 
 **For checkpoint:decision:**
 ```
-╔═══════════════════════════════════════════════════════╗
-║  CHECKPOINT: Decision Required                        ║
-╚═══════════════════════════════════════════════════════╝
+### CHECKPOINT: Decision Required
 
 Progress: 2/6 tasks complete
 Task: Select authentication provider
@@ -345,16 +365,14 @@ Options:
      Pros: Free, no vendor lock-in, widely adopted
      Cons: More setup work, DIY security updates
 
-────────────────────────────────────────────────────────
-→ YOUR ACTION: Select supabase, clerk, or nextauth
-────────────────────────────────────────────────────────
+---
+
+**→ YOUR ACTION: Select supabase, clerk, or nextauth**
 ```
 
 **For checkpoint:human-action:**
 ```
-╔═══════════════════════════════════════════════════════╗
-║  CHECKPOINT: Action Required                          ║
-╚═══════════════════════════════════════════════════════╝
+### CHECKPOINT: Action Required
 
 Progress: 3/8 tasks complete
 Task: Deploy to Vercel
@@ -369,9 +387,9 @@ What you need to do:
 
 I'll verify: vercel whoami returns your account
 
-────────────────────────────────────────────────────────
-→ YOUR ACTION: Type "done" when authenticated
-────────────────────────────────────────────────────────
+---
+
+**→ YOUR ACTION: Type "done" when authenticated**
 ```
 </execution_protocol>
 

package/gsd-core/references/decimal-phase-calculation.md

@@ -6,7 +6,7 @@ Calculate the next decimal phase number for urgent insertions.
 
 ```bash
 # Get next decimal phase after phase 6
-gsd-tools query phase.next-decimal 6
+gsd_run query phase.next-decimal 6
 ```
 
 Output:
@@ -32,13 +32,13 @@ With existing decimals:
 ## Extract Values
 
 ```bash
-DECIMAL_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --pick next)
-BASE_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
+DECIMAL_PHASE=$(gsd_run query phase.next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(gsd_run query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
 ```
 
 Or with --raw flag:
 ```bash
-DECIMAL_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --raw)
+DECIMAL_PHASE=$(gsd_run query phase.next-decimal "${AFTER_PHASE}" --raw)
 # Returns just: 06.1
 ```
 
@@ -56,7 +56,7 @@ DECIMAL_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --raw)
 Decimal phase directories use the full decimal number:
 
 ```bash
-SLUG=$(gsd-tools query generate-slug "$DESCRIPTION" --raw)
+SLUG=$(gsd_run query generate-slug "$DESCRIPTION" --raw)
 PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
 mkdir -p "$PHASE_DIR"
 ```

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

@@ -47,6 +47,14 @@ The five shapes are: `numeric-range`, `collection`, `text`, `stateful`, `io`. Wh
 `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.
+
 ## Taxonomy (8 categories)
 
 Closed and small by design: a fixed eight the author must explicitly clear beats thirty

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

@@ -40,9 +40,7 @@ The executor MUST:
 2. Emit a structured halt report:
 
    ```
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    MVP+TDD GATE TRIPPED — Plan {plan_id}, Task {task_id}
-   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### MVP+TDD GATE TRIPPED — Plan {plan_id}, Task {task_id}
 
    Reason: {missing_red_commit | red_commit_not_failing | feat_before_test}
 

package/gsd-core/references/execute-phase-between-wave-reset.md

@@ -1,5 +1,5 @@
 7b. **Pre-wave dependency check (waves 2+ only):**
-    Before wave N+1, run `gsd-tools.cjs query verify.key-links {phase_dir}/{plan}-PLAN.md` for each upcoming plan.
+    Before wave N+1, run `gsd_run query verify.key-links {phase_dir}/{plan}-PLAN.md` for each upcoming plan.
     If any PRIOR-wave artifact link fails, present:
     - `## Cross-Plan Wiring Gap` with plan/link/from/pattern rows
     - Options: investigate+fix before continue, or continue with cascade risk
@@ -24,19 +24,16 @@
    # Unset per-wave manifest so wave N+1 creates a fresh one (#3384, #1369).
    unset WAVE_WORKTREE_MANIFEST
 
-   # Between-wave base refresh (#1369): after wave N merges and tracking commits, HEAD has
-   # advanced. Re-assert worktree.baseRef:"head" (idempotent — no-op if already set) so the
-   # Claude Code harness re-reads the live HEAD on the next Agent(isolation="worktree") call
-   # rather than using a cached session-start commit as the fork base.
+   # Between-wave base re-check (#1369, #3659): after wave N merges and tracking commits,
+   # HEAD has advanced. Re-asserting worktree.baseRef:"head" is deliberately NOT done here —
+   # the runtime harness does not read project-settings baseRef (#48), so in
+   # harness-worktree mode the setting cannot influence the fork base. The safety re-check
+   # below compares HEAD against the REAL fork base and degrades the remaining waves
+   # whenever they diverge, avoiding the base-mismatch FATAL in executor agents.
    if [ "$ISOLATION" = "harness-worktree" ] && [ "$USE_WORKTREES" != "false" ]; then
-     gsd_run query worktree.set-baseref 2>/dev/null || true
-
-     # Safety re-check: evaluate degradation AFTER the wave N commits. If HEAD has diverged
-     # from origin/HEAD and baseRef is NOT "head", degrade remaining waves to sequential to
-     # avoid the base-mismatch FATAL in executor agents.
-     _BETWEEN_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || echo "false")
+     _BETWEEN_DEGRADE=$(gsd_run query worktree.base-check --mode "$ISOLATION" --pick shouldDegrade 2>/dev/null || echo "false")
      if [ "$_BETWEEN_DEGRADE" = "true" ]; then
-       _DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
+       _DEGRADE_MSG=$(gsd_run query worktree.base-check --mode "$ISOLATION" --pick message 2>/dev/null || true)
        [ -n "$_DEGRADE_MSG" ] && printf '%s\n' "$_DEGRADE_MSG" >&2
        printf 'Degrading to sequential mode for remaining waves: HEAD advanced past worktree fork base after wave %s merge (#1369).\n' "${N}" >&2
        # Both must move together (#2652): dispatch keys on ISOLATION.

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/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/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/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)
 ```