@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/shared/exit-codes.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# GENERATED FILE — DO NOT EDIT BY HAND.
+# Source of truth: gsd-core/bin/shared/exit-codes.json. Regenerate with:
+#   node scripts/gen-exit-code-registry.cjs --write
+#
+# One `export EXIT_<NAME>=<code>` per gsd-core/bin/shared/exit-codes.json
+# entry (ADR-3889 §2, #3905/#3906/#3908). POSIX sh, safe under `set -u`:
+# sourcing this file only ever ASSIGNS variables, never reads one, so it
+# cannot trip an unset-variable check regardless of the caller's existing
+# environment.
+#
+# Usage (from a scanner under scripts/):
+#   . "$(dirname "$0")/../gsd-core/bin/shared/exit-codes.sh"
+#   exit "$EXIT_UNAVAILABLE"
+export EXIT_HOOK_DENY=2
+export EXIT_USAGE=64
+export EXIT_NO_INPUT=66
+export EXIT_UNAVAILABLE=69
+export EXIT_INTERNAL=70
+export EXIT_DEGRADED=80

package/gsd-core/bin/shared/model-catalog.json

@@ -112,7 +112,7 @@
     "openai": {
       "opus":   { "low": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" }, "medium": { "model": "gpt-5.6-sol", "reasoning_effort": "high" }, "high": { "model": "gpt-5.6-sol", "reasoning_effort": "xhigh" } },
       "sonnet": { "low": { "model": "gpt-5.6-luna", "reasoning_effort": "low" }, "medium": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.6-sol", "reasoning_effort": "medium" } },
-      "haiku":  { "low": { "model": "gpt-5.6-luna", "reasoning_effort": "minimal" }, "medium": { "model": "gpt-5.6-luna", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" } }
+      "haiku":  { "low": { "model": "gpt-5.6-luna", "reasoning_effort": "low" }, "medium": { "model": "gpt-5.6-luna", "reasoning_effort": "medium" }, "high": { "model": "gpt-5.6-terra", "reasoning_effort": "medium" } }
     },
     "google": {
       "opus":   { "low": { "model": "gemini-2.5-flash-lite" }, "medium": { "model": "gemini-3-flash" }, "high": { "model": "gemini-3.1-pro-preview" } },
@@ -130,6 +130,12 @@
       "haiku":  { "low": null, "medium": null, "high": null }
     }
   },
+  "codexModelEffort": {
+    "_baseline": ["low", "medium", "high", "xhigh", "max"],
+    "gpt-5.6-sol":   ["low", "medium", "high", "xhigh", "max", "ultra"],
+    "gpt-5.6-terra": ["low", "medium", "high", "xhigh", "max"],
+    "gpt-5.6-luna":  ["low", "medium", "high", "xhigh", "max"]
+  },
   "agents": {
     "gsd-planner":                { "golden": "opus",   "balanced": "opus",   "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
     "gsd-roadmapper":             { "golden": "opus",   "balanced": "sonnet", "budget": "sonnet", "phaseType": "planning",     "routingTier": "heavy" },
@@ -149,6 +155,7 @@
     "gsd-ui-auditor":             { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
     "gsd-doc-writer":             { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "execution",    "routingTier": "standard" },
     "gsd-doc-verifier":           { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
+    "gsd-dom-verifier":           { "golden": "sonnet", "balanced": "sonnet", "budget": "haiku",  "phaseType": "verification", "routingTier": "light" },
 
     "gsd-advisor-researcher":     { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },
     "gsd-ai-researcher":          { "golden": "opus",   "balanced": "sonnet", "budget": "haiku",  "phaseType": "research",     "routingTier": "standard" },

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

@@ -8,38 +8,56 @@ 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` | `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-dom-verifier | Live-DOM UAT verification | No marker (writes `{phase}-DOM-VERIFY.md` directly; the frontmatter `outcome` / `reason` scalars carry the verdict, and `could_not_look` is never conflated with `nothing_to_report`) | `{phase}-DOM-VERIFY.md` artifact, written by the `live-dom-uat` capability's `execute:wave:post` step dispatched from `gsd-core/workflows/execute-phase.md` | artifact+query |
+| gsd-ui-checker | UI validation | `## ISSUES FOUND`, `## UI-SPEC VERIFIED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/ui-phase.md`, `gsd-core/workflows/verify-work.md`, `agents/gsd-plan-checker.md` | sentinel-match |
+| gsd-ui-researcher | UI spec creation | `## UI-SPEC COMPLETE`, `## UI-SPEC BLOCKED` | `gsd-core/workflows/ui-phase.md` | sentinel-match |
+| gsd-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 — a display/presentation format no orchestrator branch consumes (the `## ROADMAP DRAFT` header was the canonical case until #3797 folded its content into `## ROADMAP CREATED`). 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/api-coverage.md

@@ -53,7 +53,26 @@ compound modifiers ("Resolver-only API"), and first-party-qualified services
    `capabilities/ai-integration/fragments/api-coverage-plan-pre.md`.
 2. **Seal time (`verify:pre`).** The blocking `api-coverage.verify-pre` gate
    runs `check api-coverage.verify-pre <phase-dir>` and blocks unless a valid
-   matrix exists (or no integration is detected).
+   matrix exists (or no integration is detected in a scope it could actually
+   read).
+
+### Seal-time outcomes
+
+| Condition | Verdict |
+|---|---|
+| Valid `COVERAGE.md` matrix | pass |
+| `No external API integration: <reason>` declaration | pass (the reasoned human overrule) |
+| Malformed / partial matrix | **block** |
+| No matrix, integration signal found | **block** |
+| No matrix, no signal, scope was read | pass |
+| No matrix, **scope could not be established** | **block** — `scope_unavailable: true` (#3909) |
+| Phase token unresolvable | **block** |
+| Plan file exists but unreadable | **block** |
+| No `.planning/phases` tree at all | pass — not a GSD project layout |
+
+The last four are the fail-closed arms: the gate refuses to certify "no
+external-API integration" from scope it did not read. A phase with real plans
+and no API vocabulary is the fifth row, and is unaffected.
 
 ## The coverage matrix format
 
@@ -126,7 +145,10 @@ zero — the matrix is the durable subtraction record.
 
 ```bash
 echo "$PHASE_SCOPE" | node gsd-core/bin/lib/api-coverage.cjs --json
-# exit 0 = integration detected, 1 = none, 2 = startup error
+# exit 0 = integration detected, 1 = none (real input, examined, no signal)
+# NO_INPUT = stdin was empty or whitespace-only (registry code — ADR-3889 Phase 3, #3907)
+# UNAVAILABLE = stdin read failed (registry code)
+# NO_INPUT/UNAVAILABLE emit {"skipped":true,"reason":"no_input"|"stdin_error"} — no `detected` key
 ```
 
 The detector is a pure function (`detectApiIntegration` → `{ detected, signals,

package/gsd-core/references/autonomous-smart-discuss.md

@@ -5,7 +5,7 @@ Smart discuss is the autonomous-optimized variant of `gsd-discuss-phase`. It pro
 **Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
 
 ```bash
-PHASE_STATE=$(gsd-tools query init.phase-op ${PHASE_NUM})
+PHASE_STATE=$(gsd_run query init.phase-op ${PHASE_NUM})
 ```
 
 Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.
@@ -94,7 +94,7 @@ Read the 3-5 most relevant files to understand existing patterns.
 **Get phase details:**
 
 ```bash
-DETAIL=$(gsd-tools query roadmap.get-phase ${PHASE_NUM})
+DETAIL=$(gsd_run query roadmap.get-phase ${PHASE_NUM})
 ```
 
 Extract `goal`, `requirements`, `success_criteria` from the JSON response.
@@ -266,7 +266,7 @@ Write the file.
 **Commit:**
 
 ```bash
-gsd-tools query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+gsd_run query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 Display confirmation:

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.
 
@@ -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/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/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/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/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

@@ -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.
@@ -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}
 
@@ -71,11 +69,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.