@opengsd/gsd-core 1.10.0 → 1.11.0

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

@@ -8,38 +8,55 @@ This doc describes what IS, not what should be. Casing inconsistencies are docum
 
 ## Agent Registry
 
-| Agent | Role | Completion Markers |
-|-------|------|--------------------|
-| gsd-planner | Plan creation | `## PLANNING COMPLETE` |
-| gsd-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` |
-| gsd-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
-| gsd-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` |
-| gsd-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` |
-| gsd-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` |
-| gsd-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED` |
-| gsd-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED` |
-| gsd-ui-auditor | UI review | `## UI REVIEW COMPLETE` |
-| gsd-ui-checker | UI validation | `## ISSUES FOUND` |
-| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` |
-| gsd-verifier | Post-execution verification | `## Verification Complete` (title case) |
-| gsd-integration-checker | Cross-phase integration check | `## Integration Check Complete` (title case) |
-| gsd-nyquist-auditor | Sampling audit | `## PARTIAL`, `## ESCALATE` (non-standard) |
-| gsd-security-auditor | Security audit | `## OPEN_THREATS`, `## ESCALATE` (non-standard) |
-| gsd-codebase-mapper | Codebase analysis | No marker (writes docs directly) |
-| gsd-assumptions-analyzer | Assumption extraction | No marker (returns `## Assumptions` sections) |
-| gsd-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) |
-| gsd-doc-writer | Doc generation | No marker (writes docs directly) |
-| gsd-advisor-researcher | Advisory research | No marker (utility agent) |
-| gsd-user-profiler | User profiling | No marker (returns JSON in analysis tags) |
-| gsd-intel-updater | Codebase intelligence analysis | `## INTEL UPDATE COMPLETE`, `## INTEL UPDATE FAILED` |
+| Agent | Role | Completion Markers | Consumed by | Kind |
+|-------|------|--------------------|--------------|------|
+| gsd-ai-researcher | AI framework research | No marker (writes the AI-SPEC.md framework section via Edit) | `gsd-core/workflows/ai-integration-phase.md` reads the AI-SPEC.md section after the agent returns | artifact+query |
+| gsd-planner | Plan creation | `## PLANNING COMPLETE`, `## OUTLINE COMPLETE`, `## PHASE SPLIT RECOMMENDED`, `## ⚠ Source Audit`, `## CHECKPOINT REACHED`, `## PLANNING INCONCLUSIVE` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `gsd-core/workflows/plan-review-convergence.md`, `gsd-core/workflows/quick.md` | sentinel-match |
+| gsd-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `agents/gsd-debug-session-manager.md`, `agents/gsd-debugger.md` | sentinel-match |
+| gsd-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/research-phase.md`, `agents/gsd-project-researcher.md` | sentinel-match |
+| gsd-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/research-phase.md`, `agents/gsd-phase-researcher.md` | sentinel-match |
+| gsd-plan-checker | Plan validation | `## VERIFICATION PASSED`, `## ISSUES FOUND` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/stall-detection-helpers.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/ui-phase.md`, `gsd-core/workflows/verify-work.md`, `agents/gsd-ui-checker.md` | sentinel-match |
+| gsd-research-synthesizer | Multi-research synthesis | `## SYNTHESIS COMPLETE`, `## SYNTHESIS BLOCKED` (unconsumed: blocked-research return — spawners detect failure via the #222 SUMMARY.md-on-disk check, no dispatch branch keys on the marker) | `gsd-core/workflows/new-milestone.md`, `gsd-core/workflows/new-project.md` | sentinel-match |
+| gsd-debugger | Debug investigation | `## DEBUG COMPLETE`, `## ROOT CAUSE FOUND`, `## CHECKPOINT REACHED`, `## INVESTIGATION INCONCLUSIVE`, `## TDD CHECKPOINT`, `## FIX REJECTED BY GUARDRAIL` | `agents/gsd-debug-session-manager.md`, `gsd-core/workflows/diagnose-issues.md`, `gsd-core/workflows/plan-phase.md`, `agents/gsd-executor.md` | sentinel-match |
+| gsd-debug-session-manager | Debug checkpoint loop | `## DEBUG SESSION COMPLETE`, `## CONTINUE_REQUIRED` | `gsd-core/workflows/debug.md` | sentinel-match |
+| gsd-roadmapper | Roadmap creation/revision | `## ROADMAP CREATED`, `## ROADMAP REVISED`, `## ROADMAP BLOCKED`, `## ROADMAP DRAFT` (unconsumed: draft-presentation format the shipped execution flow never invokes — Step 8 returns `## ROADMAP CREATED`; retained for interactive draft review) | `gsd-core/workflows/new-milestone.md`, `gsd-core/workflows/new-project.md` | sentinel-match |
+| gsd-ui-auditor | UI review | `## UI REVIEW COMPLETE` | `gsd-core/workflows/ui-review.md` | sentinel-match |
+| gsd-ui-checker | UI validation | `## ISSUES FOUND`, `## UI-SPEC VERIFIED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/ui-phase.md`, `gsd-core/workflows/verify-work.md`, `agents/gsd-plan-checker.md` | sentinel-match |
+| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` | `gsd-core/workflows/ui-phase.md` | sentinel-match |
+| gsd-verifier | Post-execution verification | `## Verification Complete` (unconsumed: Marker Rule 2 recorded decision — intentional title-case marker; completion is detected via the artifact route, nothing matches the marker) | `*-VERIFICATION.md` artifact + `gsd_run query verification.status` in `gsd-core/workflows/verify-work.md` | artifact+query |
+| gsd-integration-checker | Cross-phase integration check | `## Integration Check Complete` (unconsumed: Marker Rule 2 recorded decision — intentional title-case marker; the auditor reads the inline report, nothing matches the marker) | `gsd-core/workflows/audit-milestone.md` reads the agent's inline return text directly (agent has no Write tool -- it cannot write an artifact) | structured-return |
+| gsd-nyquist-auditor | Sampling audit | `## PARTIAL`, `## ESCALATE`, `## GAPS FILLED` (non-standard) | `gsd-core/workflows/validate-phase.md`, `gsd-core/workflows/secure-phase.md`, `agents/gsd-security-auditor.md` | sentinel-match |
+| gsd-security-auditor | Security audit | `## OPEN_THREATS`, `## ESCALATE`, `## SECURED` (non-standard) | `gsd-core/workflows/secure-phase.md`, `gsd-core/workflows/validate-phase.md`, `agents/gsd-nyquist-auditor.md` | sentinel-match |
+| gsd-codebase-mapper | Codebase analysis | No marker (writes docs directly) | `.planning/codebase/*.md` artifacts, checked via `ls`/`wc -l` in `gsd-core/workflows/map-codebase.md` | artifact+query |
+| gsd-code-fixer | Applies code-review fixes | No marker (fix commits + REVIEW.md updates) | `gsd-core/workflows/code-review-fix.md` reads REVIEW.md resolution state + git log | artifact+query |
+| gsd-code-reviewer | Source-code review | No marker (writes REVIEW.md) | `gsd-core/workflows/code-review.md` reads REVIEW.md | artifact+query |
+| gsd-assumptions-analyzer | Assumption extraction | No marker (returns `## Assumptions` sections) | `gsd-core/workflows/discuss-phase-assumptions.md` reads the inline `## Assumptions` sections from the agent's return | structured-return |
+| gsd-doc-classifier | Planning-doc classification | No marker (writes `.planning/intel/classifications/*.json`) | `gsd-core/workflows/ingest-docs.md` reads the classification JSON | artifact+query |
+| gsd-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) | `.planning/tmp/verify-{doc_filename}.json` artifact, read by `gsd-core/workflows/docs-update.md` | artifact+query |
+| gsd-doc-writer | Doc generation | No marker (writes docs directly) | generated doc files, consumed by `gsd-core/workflows/docs-update.md` and `gsd-core/workflows/docs-update/steps/dispatch-monorepo-packages.md` | artifact+query |
+| gsd-domain-researcher | Domain research | No marker (writes the AI-SPEC.md domain section via Edit) | `gsd-core/workflows/ai-integration-phase.md` reads the AI-SPEC.md section after the agent returns | artifact+query |
+| gsd-eval-auditor | Evaluation coverage audit | No marker (writes the REVIEW.md audit section) | `gsd-core/workflows/eval-review.md` reads REVIEW.md | artifact+query |
+| gsd-eval-planner | Evaluation strategy design | No marker (writes the AI-SPEC.md evaluation section via Edit) | `gsd-core/workflows/ai-integration-phase.md` reads the AI-SPEC.md section after the agent returns | artifact+query |
+| gsd-framework-selector | Framework decision matrix | No marker (returns the interactive decision matrix inline) | `gsd-core/workflows/ai-integration-phase.md` reads the returned matrix | structured-return |
+| gsd-advisor-researcher | Advisory research | No marker (utility agent) | `gsd-core/workflows/discuss-phase/modes/advisor.md` reads the inline comparison table from the agent's return | structured-return |
+| gsd-user-profiler | User profiling | No marker (returns JSON in analysis tags) | `gsd-core/workflows/profile-user.md` extracts the inline `<analysis>` JSON block from the agent's return | structured-return |
+| gsd-intel-updater | Codebase intelligence analysis | No marker (`.planning/intel/*.json` artifacts) | `.planning/intel/*.json` artifacts, read via `gsd_run intel query` / `intel validate` (no `*.md` workflow currently spawns this agent -- see `docs/adr/22-plan-drift-guard.md`, "never auto-spawned") | artifact+query |
+| gsd-mempalace-curator | Ship-time MemPalace curation | No marker (writes the session diary + cross-links) | `gsd-core/workflows/ship.md` reads the diary artifacts | artifact+query |
+| gsd-pattern-mapper | Codebase pattern mapping | `## PATTERN MAPPING COMPLETE` | `gsd-core/workflows/plan-phase.md` (also spawned by `gsd-core/workflows/settings.md`) | sentinel-match |
+| gsd-doc-synthesizer | Doc synthesis for `/gsd:ingest-docs` | No marker (SYNTHESIS.md and INGEST-CONFLICTS.md artifacts) | `.planning/intel/SYNTHESIS.md` and `.planning/INGEST-CONFLICTS.md` artifacts, read by `gsd-core/workflows/ingest-docs.md` | artifact+query |
 
 ## Marker Rules
 
 1. **ALL-CAPS markers** (e.g., `## PLANNING COMPLETE`) are the standard convention
-2. **Title-case markers** (e.g., `## Verification Complete`) exist in gsd-verifier and gsd-integration-checker -- these are intentional as-is, not bugs
+2. **Title-case markers in gsd-verifier and gsd-integration-checker are intentional as-is, not bugs — a recorded decision.** Their rows are `artifact+query`/`structured-return` (completion is detected through the row's `Kind` route), and the markers are carried as `(unconsumed: Marker Rule 2 recorded decision …)` annotations: an auditable exemption, never deleted and never silently passed. `## Synthesis Complete` in gsd-doc-synthesizer was NOT covered by this rule; #3565 deleted it deliberately because it case-collides with gsd-research-synthesizer's `## SYNTHESIS COMPLETE` and nothing matched it
 3. **Non-standard markers** (e.g., `## PARTIAL`, `## ESCALATE`) in audit agents indicate partial results requiring orchestrator judgment
-4. **Agents without markers** either write artifacts directly to disk or return structured data (JSON/sections) that the caller parses
+4. **`Kind` describes how a caller actually detects an agent's completion, and is exactly one of:**
+   - `sentinel-match` -- a workflow, command, or another agent detects completion by an exact-case string match against a declared marker
+   - `artifact+query` -- the agent writes a file (report, JSON, generated doc) and the caller reads or queries that artifact instead of matching any marker text
+   - `structured-return` -- the agent has no way to write files (no `Write` tool) or simply doesn't; it returns parseable sections, a table, or JSON inline, and the caller reads that return text directly
 5. Markers must appear as H2 headings (`## `) at the start of a line in the agent's final output
+6. The `Consumed by` / `Kind` columns are machine-enforced by `check:contract-drift` (`scripts/check-contract-drift.cjs`), which cross-checks this table against what each `agents/*.md` file actually emits in-fence and what every `gsd-core/workflows/**`, `commands/**`, and `agents/**` file actually consumes. Update this table whenever an agent's return contract changes -- a stale row is a violation the check will report, not something to leave for later.
+7. A marker entry annotated `(unconsumed: <reason>)` is emitted deliberately but matched by no workflow, command, or agent — e.g. `## ROADMAP DRAFT`, a presentation format a human approves interactively. The check still verifies the marker is declared **and** emitted, and still counts it for case-collision purposes; only the consumer requirement is waived. Use it for display formats, never to silence a real orphan.
 
 ## Key Handoff Contracts
 

package/gsd-core/references/checkpoints.md

@@ -9,14 +9,14 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
 4. **Secrets come from user, automation comes from Claude** - Ask for API keys, then Claude uses them via CLI
 5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow._auto_chain_active` or `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
-6. **`gate="blocking-human"` is never auto-approved** — a checkpoint carrying this gate stops for a human in *every* mode, including auto-mode, regardless of its type. Rule 5 does not apply to it.
+6. **`gate="blocking-human"` is never auto-approved** — a checkpoint carrying this gate stops for a human in *every* mode, including auto-mode, regardless of its type. Rule 5 does not apply to it. The executor's precondition-unmet checkpoint (a task's `<precondition>` evaluated false — unmet `user_setup` step, missing env var, absent prior-phase artifact) reports this gate (#3210).
 
 **The `gate` attribute:**
 
 | Value | Auto-mode behavior | Use for |
 |-------|--------------------|---------|
 | `gate="blocking"` | Bypassed per rule 5 (human-verify auto-approves, decision auto-selects) | The default. Post-hoc verification and implementation choices that are safe to take the recommended path on when unattended. |
-| `gate="blocking-human"` | **Never bypassed.** Stops for a human in auto-mode too. | Irreversible or trust-establishing steps a human must actually see: package-legitimacy verification before install, and any decision whose default answer would be wrong to assume. |
+| `gate="blocking-human"` | **Never bypassed.** Stops for a human in auto-mode too. | Irreversible or trust-establishing steps a human must actually see: package-legitimacy verification before install, any decision whose default answer would be wrong to assume, and unmet `<precondition>` facts the executor cannot establish on its own (#3210). |
 
 Reach for `gate="blocking-human"` whenever auto-approving the checkpoint would defeat its purpose. If the checkpoint exists because a human must *decide* something, `blocking` is the wrong gate — auto-mode will decide it for them.
 

package/gsd-core/references/context-budget.md

@@ -2,7 +2,7 @@
 
 Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
 
-See also: `references/universal-anti-patterns.md` for the complete set of universal rules.
+See also: `gsd-core/references/universal-anti-patterns.md` for the complete set of universal rules.
 
 ---
 

package/gsd-core/references/dispatch-isolation-gate.md

@@ -0,0 +1,138 @@
+# Dispatch isolation gate (ADR-1239 / #2584)
+
+The single source of truth for **how a dispatch site decides whether it may run an agent
+isolated**. Every workflow that spawns an executor-like subagent reads this file and follows
+it, rather than restating the rule inline (#2652).
+
+`ISOLATION` — not `RUNTIME` — is the decision variable. **Never branch a dispatch site on a
+runtime id.** Isolation is a negotiated capability declared per host; a runtime-name test
+silently diverges the moment a new host declares support, which is exactly how #2652 happened:
+`quick.md` and `diagnose-issues.md` kept a `RUNTIME != "claude"` gate after #2584 migrated the
+phase scheduler, so Codex — which declares `orchestrator-worktree` — was refused isolation it
+had in fact negotiated.
+
+## Resolve ISOLATION
+
+Run this in the dispatch site's config-gate step, right after `RUNTIME` / `USE_WORKTREES` are
+read. It requires `gsd_run` to be defined (the standard shim preamble).
+
+```bash
+# Isolation is a NEGOTIATED CAPABILITY, not a runtime id (#2584). Fail-closed to none.
+# #3045: this call PERSISTS the resolution to the run-scoped sentinel the isolation
+# guard hooks read, as an unconditional side effect of resolving it.
+# Keep the resolver's own failure DISTINGUISHABLE from a genuine `none`. Both
+# fail closed — that policy is right — but only one of them may claim the host
+# declared no primitive. A shim-resolution failure, a non-zero exit or empty
+# stdout is NOT a capability verdict, and reporting it as one tells a Claude
+# Code user their runtime "declares no executor-isolation primitive", which is
+# false (#2652 review).
+_ISOLATION_RAW=$(gsd_run query dispatch-isolation --raw 2>/dev/null)
+_ISOLATION_RC=$?
+if [ $_ISOLATION_RC -ne 0 ] || [ -z "$_ISOLATION_RAW" ]; then
+  ISOLATION=none
+  ISOLATION_RESOLVED=false      # fail closed, but we did NOT learn a verdict
+else
+  ISOLATION="$_ISOLATION_RAW"
+  ISOLATION_RESOLVED=true
+fi
+case "$ISOLATION" in
+  harness-worktree|orchestrator-worktree|none) ;;
+  *) ISOLATION=none; ISOLATION_RESOLVED=false ;;   # out of vocabulary is not a verdict either
+esac
+
+# Project-level opt-out wins on every host; a host with no primitive fails closed.
+[ "$USE_WORKTREES" = "false" ] && ISOLATION=none
+if [ "$ISOLATION" = "none" ] && [ "$USE_WORKTREES" != "false" ]; then
+  if [ "$ISOLATION_RESOLVED" = "true" ]; then
+    echo "FATAL: runtime '$RUNTIME' declares no executor-isolation primitive (dispatch.isolation=none) — agents would run unisolated against the main checkout. Set workflow.use_worktrees=false." >&2
+  else
+    echo "FATAL: could not resolve this runtime's executor-isolation capability — 'gsd_run query dispatch-isolation' failed or returned nothing, so GSD cannot tell whether isolation is available. Refusing to dispatch rather than guess (a guard that cannot verify must not answer 'safe'). Re-run once the gsd-tools shim resolves, or set workflow.use_worktrees=false to run sequentially on purpose." >&2
+  fi
+  exit 1
+fi
+
+# Re-record: the opt-out above is decided in shell, where the resolver cannot see
+# it, so the sentinel still asserts the naturally-resolved mode. See "Re-record
+# after every degrade" below — this is the first of the mandatory calls.
+gsd_run query dispatch-isolation --raw --force-isolation "$ISOLATION" >/dev/null 2>&1 || true
+```
+
+| `ISOLATION` | Meaning | What a dispatch site does |
+|---|---|---|
+| `harness-worktree` | The host's own harness creates and binds a worktree per agent. | Pass the host's declared `harnessFlag` on the dispatch. GSD runs no git. |
+| `orchestrator-worktree` | No harness primitive, but a headless exec accepting a working directory. | GSD creates the worktree and process-spawns the agent into it. GSD performs every git operation. |
+| `none` | No isolation primitive. | Run inline, sequentially. |
+
+Fail-closed is the invariant: an undeclared, unknown, or unresolvable declaration degrades to
+`none`, never to an unsafe parallel path.
+
+## Resolve the harness flag (harness-worktree only)
+
+The flag is descriptor data — never hardcode `isolation="worktree"`, which is Claude Code's
+literal and wrong on any other harness-worktree host (Cursor declares the same capability).
+
+```bash
+HARNESS_FLAG=""
+if [ "$ISOLATION" = "harness-worktree" ]; then
+  HARNESS_FLAG=$(gsd_run query dispatch-isolation --json 2>/dev/null \
+    | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const j=JSON.parse(s);process.stdout.write(j&&j.harnessFlag?j.harnessFlag:"")}catch{process.stdout.write("")}})')
+  [ -n "$HARNESS_FLAG" ] || { echo "FATAL: runtime declares dispatch.isolation=harness-worktree but no harnessIsolationFlag — refusing to dispatch an agent that would believe it is isolated." >&2; exit 1; }
+fi
+```
+
+Substitute `$HARNESS_FLAG` for the `{harnessFlag}` placeholder in the dispatch call. On Claude
+Code it resolves to literally `isolation="worktree"`.
+
+## Single-agent dispatch sites
+
+`quick.md` and `diagnose-issues.md` spawn through the host's own subagent tool, which can only
+express the `harness-worktree` model. On an `orchestrator-worktree` host they must degrade to
+sequential rather than pass a harness flag the host will ignore — dispatching unisolated while
+reporting isolation is the one outcome worse than running sequentially:
+
+```bash
+if [ "$ISOLATION" = "orchestrator-worktree" ]; then
+  echo "⚠ Runtime '$RUNTIME' declares dispatch.isolation=orchestrator-worktree, which requires GSD-driven process spawning. This dispatch site uses the host subagent tool, so it is running sequentially on the main working tree instead. Parallel wave execution (/gsd:execute-phase) is unaffected." >&2
+  ISOLATION=none
+  USE_WORKTREES=false
+  gsd_run query dispatch-isolation --raw --force-isolation none >/dev/null 2>&1 || true
+fi
+```
+
+## Re-record after every degrade
+
+**Any block that changes `$ISOLATION` after the resolve above MUST re-record it before
+dispatch.** This is not optional bookkeeping — it is what keeps the dispatch legal.
+
+`query dispatch-isolation` writes the mode it resolved into a run-scoped sentinel
+(`.gsd/dispatch-isolation-sentinel.json`) as an unconditional side effect, and the shipped
+`PreToolUse` isolation guards read that sentinel at the instant of the dispatch call
+(`hooks/gsd-agent-isolation-guard.js`, `hooks/gsd-cursor-subagent-start.js`, shared reader
+`hooks/lib/isolation-sentinel.js`, #3045). Every degrade in this file is decided **in shell**,
+where the resolver cannot see it. Degrade without re-recording and the sentinel still asserts
+`harness-worktree` while the dispatch correctly omits the harness flag — the guard reads that
+as a dropped isolation flag and **denies the dispatch with exit 2**. The task does not run
+unisolated; it does not run at all.
+
+```bash
+gsd_run query dispatch-isolation --raw --force-isolation "$ISOLATION" >/dev/null 2>&1 || true
+```
+
+`--force-isolation` pushes the final, shell-computed value through the same single write path
+(`none` also clears the stored `harnessFlag`, since none applies to sequential dispatch). It is
+idempotent and last-write-wins, so a site that degrades more than once simply calls it again —
+record immediately before dispatch so the sentinel is always fresh. Best-effort by design: a
+write failure must never fail the dispatch, since the guards' sentinel-absent fallback is safe,
+just less precise.
+
+Wave sites re-record per plan rather than per phase — see
+`gsd-core/workflows/execute-phase/steps/per-plan-worktree-gate.md`.
+
+Wave fan-out sites (`execute-phase`) implement both models — see
+`gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md`.
+
+## Base divergence
+
+Any site that ends up with `ISOLATION != none` must also run the `worktree.base-check`
+auto-degrade before dispatch (#683, #1369, #1941), or the agent's `worktree_branch_check` guard
+halts on a stale fork base. `quick.md` and `execute-phase` do this today.

package/gsd-core/references/doc-conflict-engine.md

@@ -56,7 +56,7 @@ Exit WITHOUT writing any destination files. The gate must hold regardless of WAR
 
 **If only WARNINGS and/or INFO (no blockers):**
 
-Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
+Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `gsd-core/references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
 
 **If the report is empty (no entries in any bucket):**
 

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

@@ -4,7 +4,7 @@
 
 ## When this gate fires
 
-- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `references/planner-mvp-mode.md`).
+- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `gsd-core/references/planner-mvp-mode.md`).
 - `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config).
 - The current task being executed has `tdd="true"` in its `<task>` frontmatter (set by the planner per Phase 1).
 - The task's `<behavior>` block lists at least one expected behavior.
@@ -71,11 +71,11 @@ The `--force-mvp-gate` flag is documented but not introduced by this plan — it
 
 ## What this gate does NOT do
 
-- It does not enforce REFACTOR commits. REFACTOR remains optional (per `references/tdd.md`).
+- It does not enforce REFACTOR commits. REFACTOR remains optional (per `gsd-core/references/tdd.md`).
 - It does not check test quality (the test could be trivially passing). That's the planner's job.
 - It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
 - It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
 
 ## Compatibility with existing TDD discipline
 
-This gate is additive to `references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.
+This gate is additive to `gsd-core/references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.

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

@@ -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,
@@ -26,7 +28,7 @@
    # 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
+   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
@@ -37,7 +39,9 @@
        _DEGRADE_MSG=$(gsd_run query worktree.base-check --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,16 +7,20 @@
    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
+   if [ "$ISOLATION" = "harness-worktree" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
      _WAVE_DEGRADE=$(gsd_run query worktree.base-check --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)
        [ -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
    ```

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 box format details, see `gsd-core/references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
 
 ## Rules
 

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

@@ -12,7 +12,7 @@ Always use this for `.planning/` files — it handles `commit_docs` and gitignor
 gsd-tools 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
 
@@ -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/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,7 +90,7 @@ 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`
 

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 `node gsd-tools.cjs 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/planner-guidance.md

@@ -162,24 +162,18 @@ Derive plans from actual work. Granularity determines compression tolerance, not
 Run `/clear` first for a fresh context window, then execute: `/gsd:execute-phase {phase}`
 ```
 
-## Gap Closure Plans Created Return Format
+## Gap Closure Return (artifact-based — #3440)
 
-```markdown
-## GAP CLOSURE PLANS CREATED
+Gap-closure completion has **no completion marker**: nothing consumes one. The return contract is the artifacts themselves — `verify-work.md` spawns you in `--gaps` mode, and your output is complete when the fix plans are on disk carrying `gap_closure: true` in their frontmatter; the spawning workflow detects the files (never a return string), and `/gsd:execute-phase {phase} --gaps-only` consumes them. (The former `GAP CLOSURE PLANS CREATED` completion marker was retired as vestigial — it had no dispatch branch anywhere.)
 
 **Phase:** {phase-name}
 **Closing:** {N} gaps from {VERIFICATION|UAT}.md
 
-### Plans
-
 | Plan | Gaps Addressed | Files |
 |------|----------------|-------|
 | {phase}-04 | [gap truths] | [files] |
 
-### Next Steps
-
-Execute: `/gsd:execute-phase {phase} --gaps-only`
-```
+**Next step for the orchestrator:** `/gsd:execute-phase {phase} --gaps-only`
 
 ## Checkpoint Reached / Revision Complete
 

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

@@ -121,7 +121,7 @@ The executor agent reads `<precondition>` before any other task work:
 |---|---|
 | **Absent** | No visible change — execute the task exactly as today. Back-compat for every existing plan. |
 | **Met** | No visible change — proceed with the task. The precondition is logged in the SUMMARY only if it was non-trivial to verify. |
-| **Unmet** | STOP — return a `checkpoint:human-verify` (use `checkpoint_return_format`) with `**Blocked by:** Precondition not met: <precondition text>`. Do NOT partial-commit the task. Unmet preconditions are NEVER auto-approved — a missing prerequisite is not a verification step a human can rubber-stamp, it is a fact the executor cannot establish on its own. |
+| **Unmet** | STOP — return a `checkpoint:human-verify` reporting `**Gate:** blocking-human` (use `checkpoint_return_format`) with `**Blocked by:** Precondition not met: <precondition text>`. Do NOT partial-commit the task. Unmet preconditions are NEVER auto-approved — a missing prerequisite is not a verification step a human can rubber-stamp, it is a fact the executor cannot establish on its own. |
 
 ## Plan-structure validation
 

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

@@ -7,7 +7,7 @@ Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with
 **Execution contract:** REVIEWS.md is audit trail and feedback input, not a second execution contract. /gsd:execute-phase primarily consumes PLAN.md plus the normal phase context. Every current actionable review finding must therefore be incorporated into the relevant PLAN.md or explicitly deferred/rejected in that PLAN.md.
 
 ### Step 1: Load REVIEWS.md
-Read the reviews file from `<files_to_read>`. Parse:
+Read the reviews file from `<required_reading>`. Parse:
 - Per-reviewer feedback (strengths, concerns, suggestions)
 - Consensus Summary (agreed concerns = highest priority to address)
 - Divergent Views (investigate, make a judgment call)