@opengsd/gsd-core 1.10.0 → 1.12.0

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
@@ -7,7 +7,9 @@
 
 7c. **Between-wave manifest reset and worktree base refresh (waves 2+ only — #1369):**
 
-   **REQUIRED before each wave transition when `USE_WORKTREES != "false"` and `RUNTIME = "claude"`.**
+   **REQUIRED before each wave transition when `USE_WORKTREES != "false"` and
+   `ISOLATION = "harness-worktree"`** (#2652 — keyed on the negotiated isolation model, not the
+   runtime name).
 
    Wave N's `WAVE_WORKTREE_MANIFEST` was consumed by `worktree.cleanup-wave` in step 5.5. It must be
    unset so wave N+1's step 3 creates a fresh manifest for the new wave's worktrees. Without this,
@@ -22,22 +24,21 @@
    # 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.
-   if [ "$RUNTIME" = "claude" ] && [ "$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-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
+     _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.
        USE_WORKTREES=false
+       ISOLATION=none
      fi
    fi
    ```

package/gsd-core/references/execute-phase-context-guard.md

@@ -1,7 +1,7 @@
 0. **Context exhaustion guard — `context_guard` (BEFORE spawning, #1452):**
 
    Before spawning any agents for this wave, self-assess context pressure using the
-   degradation signals in `references/context-budget.md`. Signs of POOR tier (70%+):
+   degradation signals in `gsd-core/references/context-budget.md`. Signs of POOR tier (70%+):
    increasing vagueness, skipped steps, silent partial completion.
 
    Read `workflow.context_guard_mode` from `.planning/config.json` (default `warn`).

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

@@ -4,4 +4,4 @@
 
 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/fix-2285-claude-orchestration-wiring.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.
+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

@@ -7,27 +7,33 @@
    immediately with a base-mismatch fatal.
 
    **Run this check at the start of every wave when `USE_WORKTREES != "false"` and
-   `RUNTIME = "claude"`**, including Wave 1 (where it mirrors the initialize-step check):
+   `ISOLATION = "harness-worktree"`** (#2652 — the harness caches the fork base, so this is a
+   property of the isolation model, not of the runtime name; Cursor declares it too),
+   including Wave 1 (where it mirrors the initialize-step check):
 
    ```bash
-   if [ "$RUNTIME" = "claude" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
-     _WAVE_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
+   if [ "$ISOLATION" = "harness-worktree" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
+     _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.
        USE_WORKTREES=false
+       ISOLATION=none
      fi
    fi
    ```
 
    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 `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,17 +9,17 @@ 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` or `.planning/` is gitignored. No manual conditional checks needed.
+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.
 
 ## Amend previous commit
 
 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
@@ -37,4 +37,5 @@ gsd-tools query commit "" --files .planning/codebase/*.md --amend
 
 - `commit_docs: false` in config
 - `.planning/` is gitignored
+- `phase_commit_docs.<phase-id>` resolves `false` for the phase being committed — overrides the project-wide `commit_docs` for that phase only (reason `skipped_commit_docs_phase_false`)
 - No changes to commit (check with `git status --porcelain .planning/`)

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

@@ -31,7 +31,7 @@ Inject `fragment.inline` verbatim into the context for the role named in `into`
 
 ### `step`
 
-Dispatch the referenced unit:
+Dispatch the referenced unit. Exactly one of `ref.skill`, `ref.agent`, or `ref.command` is set.
 
 - `ref.skill` present → dispatch via the Skill tool with skill id `gsd-<ref.skill>`.
 - `ref.agent` present → dispatch via the Agent tool with `subagent_type` = `ref.agent`.
@@ -42,10 +42,47 @@ Dispatch the referenced unit:
   ◆ Spawning <agent>... (runs in a subagent — no output until it returns; expected, not a freeze)
   ```
 
+- `ref.command` present → **validate it IN-CONTEXT first, before any shell use.** It comes
+  from a capability manifest, which may be third-party. Check the value you read from
+  `activeHooks` against `^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$` yourself — **never** by pasting
+  it into a shell command to be tested there, because a value carrying a quote, `;`,
+  `` ` ``, `$(`, or a newline would terminate the assignment and run as its own statement
+  before any shell-side check could execute. A value that fails is a malformed manifest:
+  record a warning, skip that hook, continue to the next entry. Only a value that has passed
+  is run, with the phase number appended:
+
+  ```bash
+  gsd_run ${ref.command} --phase "${PHASE_NUMBER}" --raw
+  ```
+
 Wait for the result before continuing to the next hook or the next step.
 
+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`.
+
+**A point whose workflow hand-rolls one `kind` does not implement this contract.** Several
+host workflows historically matched a single hook (e.g. `execute:post` matched only
+`ref.skill == "code-review"`), so any other step registered there was declared and silently
+never run. When a workflow defers to this file, it dispatches **every** active `step` entry,
+not one shape of one.
+
 ### `gate`
 
+**Validate `check` before any shell use.** `check.query` and `check.predicate` come from a
+capability manifest, which may be third-party — and `gates[].check` is **not** one of the
+executable surfaces the install consent prompt discloses (`hooks`, command modules,
+`mcpServers`, reviewer lanes), so a capability can be consented to as declarative-only and
+still reach a shell through a gate. Check the query value you read from `activeHooks` against
+`^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$` yourself, IN-CONTEXT — **never** by pasting it into a
+shell command to be tested there, because a value carrying a quote, `;`, a `` ` ``, `$(`, or a
+newline would terminate the assignment and run as its own statement before any shell-side
+check could execute. A value that fails is a malformed manifest: record a warning, route it
+per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
+element** for the same reason — never re-quote it into a shell string, where an apostrophe
+would close the literal. This is the identical requirement `step` → `ref.command` carries
+above; it was stated there and omitted here, which is the gap #3559 closed.
+
 Evaluate `check` (one of `query`, `predicate`, or `agentVerdict`). Then honor `blocking`:
 
 - `blocking: true` → if the check returns `block: true`, surface `check.message` to the user
@@ -53,9 +90,31 @@ Evaluate `check` (one of `query`, `predicate`, or `agentVerdict`). Then honor `b
 - `blocking: false` → advisory only; surface the message but continue regardless of outcome.
 
 Honor `onError` if the check itself errors: `skip` means treat as non-blocking and continue;
-`fail` means surface the error and stop.
+`halt` means surface the error and stop.
 
 ## Empty / absent `activeHooks`
 
 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

@@ -219,10 +219,18 @@ is (highest → lowest):
 6. Pass model parameter to Task call
 ```
 
-The same precedence applies to `reasoning_effort` resolution on runtimes
-that support it (Codex), so `model` and `reasoning_effort` always derive
-from the same tier source — a `models[phase_type]` or
-`dynamic_routing` override flips both.
+`model` and `effort` resolve through different mechanisms at different
+times — they do not share the ladder above. `model` resolves at runtime,
+per spawn, from `.planning/config.json`; a config change takes effect on
+the next spawn. `effort` (claude runtime) has its own cascade
+(`agent_overrides` → `routing_tier_defaults` → `default`; see
+`docs/CONFIGURATION.md` § "Where effort actually reaches") and is baked at
+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 `gsd_run effort sync --apply`
+re-syncs the agent files. Codex agents instead pin
+`model_reasoning_effort` in `~/.codex/agents/*.toml` at install time.
 
 ## Per-Agent Overrides
 

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

@@ -8,12 +8,12 @@ Canonical domain terms for the concepts named below live in [CONTEXT.md](../../C
 
 | File | Purpose | Loaded by |
 |---|---|---|
-| `references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gsd-planner` agent when `MVP_MODE=true` |
-| `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 |
-| `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 |
-| `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 |
-| `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` |
-| `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` |
+| `gsd-core/references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gsd-planner` agent when `MVP_MODE=true` |
+| `gsd-core/references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `gsd-planner` agent when the Walking Skeleton gate fires |
+| `gsd-core/references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `gsd-mvp-phase` workflow during interactive prompting; `gsd-planner` when emitting the `## Phase Goal` header |
+| `gsd-core/references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `gsd-mvp-phase` workflow when the user story exceeds size threshold |
+| `gsd-core/references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `gsd-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
+| `gsd-core/references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `gsd-verifier` agent when the phase under verification has `mode: mvp` |
 
 ## Concept-to-file map
 
@@ -22,10 +22,10 @@ If you're looking for the canonical statement of a concept, this is where to fin
 - **MVP Mode resolution chain** — `workflows/plan-phase.md` Step 1 (CLI flag → roadmap → config → false). Mirrored in `execute-phase.md` and `verify-work.md`.
 - **`**Mode:** mvp` parser** — `gsd-core/bin/lib/roadmap.cjs` (`searchPhaseInContent` + `cmdRoadmapAnalyze`). Workflows compare against the parser output, never re-parse.
 - **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `gsd-verifier` (the user-story-format guard) and `gsd-mvp-phase` (interactive validation).
-- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gsd-executor`.
+- **Behavior-Adding Task predicate** — `gsd-core/references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gsd-executor`.
 - **Walking Skeleton gate condition** — `workflows/plan-phase.md` (Phase 1 + new project + `--mvp` + no prior summaries → emit `SKELETON.md`).
-- **MVP+TDD Gate** (RED→GREEN enforcement) — `references/execute-mvp-tdd.md`.
-- **MVP-mode UAT framing** (user-flow first, technical deferred) — `references/verify-mvp-mode.md`.
+- **MVP+TDD Gate** (RED→GREEN enforcement) — `gsd-core/references/execute-mvp-tdd.md`.
+- **MVP-mode UAT framing** (user-flow first, technical deferred) — `gsd-core/references/verify-mvp-mode.md`.
 - **Per-phase mode authoring** — `workflows/mvp-phase.md` (writes `**Mode:** mvp` to ROADMAP.md after collecting the user story).
 - **Project-wide mode prompt at init** — `workflows/new-project.md` (Vertical MVP vs Horizontal Layers question).
 

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