@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -28,6 +28,7 @@
     "verifier": true,
     "nyquist_validation": true,
     "ai_integration_phase": true,
+    "agent_hint_routing": true,
     "human_verify_mode": "end-of-phase",
     "auto_advance": false,
     "_auto_chain_active": false,

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -35,6 +35,7 @@
     "workflow.plan_chunked",
     "workflow.specless_probe_fallback",
     "workflow.plan_review_convergence",
+    "workflow.agent_hint_routing",
     "code_quality.fallow.enabled",
     "code_quality.fallow.scope",
     "code_quality.fallow.profile",
@@ -63,6 +64,8 @@
     "workflow.context_guard_mode",
     "executor.stall_detect_interval_minutes",
     "executor.stall_threshold_minutes",
+    "planner.stall_detect_interval_minutes",
+    "planner.stall_threshold_minutes",
     "workflow.inline_plan_threshold",
     "hooks.context_warnings",
     "hooks.workflow_guard",
@@ -178,7 +181,12 @@
     {
       "topLevel": "model_policy",
       "source": "^model_policy\\.runtime_tiers\\.[a-zA-Z0-9_-]+\\.(opus|sonnet|haiku)$",
-      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku>"
+      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku> (#3587)"
+    },
+    {
+      "topLevel": "phase_commit_docs",
+      "source": "^phase_commit_docs\\.\\d+[A-Z]?(?:\\.\\d+)*$",
+      "description": "phase_commit_docs.<phase-id> — per-phase commit_docs override (#3587). The <phase-id> segment is a hand-copy of the canonical PHASE_NUMBER_TOKEN_SOURCE grammar owned by src/phase-id.cts (#2128); this manifest is hand-maintained JSON so it cannot import that constant. Pinned against drift by the behavioral parity test in tests/commit-docs-bypass.test.cjs (folded 'phase-commit-docs' block, describe block 'E', #3587) — do not hand-edit this pattern without updating that test."
     }
   ]
 }

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/artifact-types.md

@@ -43,6 +43,13 @@ reads is inert — the consumption mechanism is what gives an artifact meaning.
 - **Lifecycle**: Created at plan completion → Read by subsequent plans in same phase
 - **Location**: `.planning/phases/XX-name/XX-YY-SUMMARY.md`
 - **Consumed by**: Orchestrator (progress), planner (context for future plans), `milestone-summary`
+- **`status:`** — `complete` (default) or **`halted`**. `halted` records a *designed stop*:
+  the plan ran and answered its question, but the answer means the work it was gating cannot
+  proceed (a spike that returns "no", for example). It is a success, not a failure — the plan
+  did its job. Marking a SUMMARY `halted` propagates transitively over `depends_on`: every
+  plan that depends on it, directly or through a chain, is reported as **blocked** rather than
+  offered to the executor as ordinary incomplete work, and is named with its cause. Any other
+  value — including no `status:` field at all — reads as complete. (#2830)
 
 ### HANDOFF.json / .continue-here.md
 - **Shape**: Structured pause state (JSON machine-readable + Markdown human-readable)
@@ -72,11 +79,11 @@ reads is inert — the consumption mechanism is what gives an artifact meaning.
 - **Location**: `.planning/spikes/SPIKE-NNN/`
 - **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff
 
-### Spike README.md / MANIFEST.md (per-spike, via /gsd:spike)
-- **Shape**: YAML frontmatter (spike, name, validates, verdict, related, tags) + run instructions + results
+### Spike README.md (per-spike) / MANIFEST.md (per-project index, via /gsd:spike)
+- **Shape**: README — YAML frontmatter (spike, idea, name, validates, verdict, related, tags) + run instructions + results. MANIFEST.md — one `### {idea-key}` section per idea under `## Ideas` (idea paragraph + its own scoped Requirements), plus one durable `## Spikes` table (with an Idea column) indexing every spike across every idea.
 - **Lifecycle**: Created by `/gsd:spike` → Verified → Wrapped up by `/gsd-spike-wrap-up`
 - **Location**: `.planning/spikes/NNN-name/README.md`, `.planning/spikes/MANIFEST.md`
-- **Consumed by**: `/gsd-spike-wrap-up` for curation; `pause-work` for spike context handoff
+- **Consumed by**: `/gsd-spike-wrap-up` for curation (Requirements pulled only from the idea key(s) it wraps); `pause-work` for spike context handoff
 
 ### Sketch README.md / MANIFEST.md / index.html (per-sketch)
 - **Shape**: YAML frontmatter (sketch, name, question, winner, tags) + variants as tabbed HTML

package/gsd-core/references/autonomous-ui-design-contract.md

@@ -0,0 +1,42 @@
+# UI Design Contract (Frontend Phases) — Autonomous Mode
+
+Step 3a.5 of `/gsd:autonomous`: resolve whether the current phase needs a UI-SPEC.md generated before planning, and generate one via active `plan:pre` step hooks if so. Always non-blocking — proceeds to step 3b (Plan) regardless of outcome.
+
+**Inputs:** `PHASE_NUM`, `PHASE_DIR` from execute_phase.
+
+Resolve active `plan:pre` hooks:
+
+```bash
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+HOOKS_JSON=$(gsd_run loop render-hooks plan:pre --raw)
+```
+
+Read the `activeHooks` array directly from `HOOKS_JSON` (in-context — do NOT invoke a shell pipeline). **Compute the active UI step hooks** = entries from `activeHooks` where `kind == "step"` and `ref.skill` is set. **If there are NO active step hooks → skip silently to 3b.** (This covers `workflow.ui_phase=false` — including configurations where only a gate-only entry is present, e.g. `ui_phase=false` + `ui_safety_gate=true` produces `activeHooks=[{kind:"gate"}]`. Autonomous never runs the plan:pre gate — it is always pipeline mode — so a gate-only active set is equivalent to no active step and is silently skipped here. This matches OLD §3a.5 behaviour.)
+
+(At least one active step hook ⇒ `workflow.ui_phase` is on.) Run the UI-SPEC gate:
+
+```bash
+GATE=$(gsd_run check ui-plan-gate "${PHASE_NUM}" --raw)
+```
+
+Read `frontend` and `hasUiSpec` from `GATE` (in-context).
+
+**If `frontend` is false:** Skip silently to 3b.
+
+**If `hasUiSpec` is true (UI-SPEC already exists):** Skip silently to 3b.
+
+**Otherwise (frontend phase + no UI-SPEC):** For each active step hook (the `kind == "step"` set from above, in array order):
+
+```
+Skill(skill="gsd-${ref.skill}", args="${PHASE_NUM}")
+```
+
+(Prepend `gsd-` to `ref.skill` — so `ui-phase` → `gsd-ui-phase`. Bare `${PHASE_NUM}` args — autonomous style, same pattern as the verify:post dispatch.) Entries where `kind == "gate"` are silently ignored — autonomous is always pipeline mode, there is no blocking gate here.
+
+After all step hooks return, re-read:
+
+```bash
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+```
+
+**If `UI_SPEC_FILE` is still empty:** Display warning `Phase ${PHASE_NUM}: UI-SPEC generation did not produce output — continuing without design contract.` and proceed to 3b. NON-BLOCKING.

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/debugger-techniques.md

@@ -0,0 +1,255 @@
+# Debugger technique catalog
+
+Full technique bodies for `agents/gsd-debugger.md`, extracted per
+`DEFECT.AGENT-FILE-SIZE-CAP-BREACH` (issue #2995, epic #1671 Phase 6.4). The agent
+keeps each technique's name and routing entry; the step-by-step detail lives here.
+
+## Binary Search / Divide and Conquer
+
+**When:** Large codebase, long execution path, many possible failure points.
+
+**How:** Cut problem space in half repeatedly until you isolate the issue.
+
+1. Identify boundaries (where works, where fails)
+2. Add logging/testing at midpoint
+3. Determine which half contains the bug
+4. Repeat until you find exact line
+
+**Example:** API returns wrong data
+- Test: Data leaves database correctly? YES
+- Test: Data reaches frontend correctly? NO
+- Test: Data leaves API route correctly? YES
+- Test: Data survives serialization? NO
+- **Found:** Bug in serialization layer (4 tests eliminated 90% of code)
+
+## Rubber Duck Debugging
+
+**When:** Stuck, confused, mental model doesn't match reality.
+
+**How:** Explain the problem out loud in complete detail.
+
+Write or say:
+1. "The system should do X"
+2. "Instead it does Y"
+3. "I think this is because Z"
+4. "The code path is: A -> B -> C -> D"
+5. "I've verified that..." (list what you tested)
+6. "I'm assuming that..." (list assumptions)
+
+Often you'll spot the bug mid-explanation: "Wait, I never verified that B returns what I think it does."
+
+## Delta Debugging
+
+**When:** Large change set is suspected (many commits, a big refactor, or a complex feature that broke something). Also when "comment out everything" is too slow.
+
+**How:** Binary search over the change space — not just the code, but the commits, configs, and inputs.
+
+**Over commits (use git bisect):**
+Already covered under Git Bisect. But delta debugging extends it: after finding the breaking commit, delta-debug the commit itself — identify which of its N changed files/lines actually causes the failure.
+
+**Over code (systematic elimination):**
+1. Identify the boundary: a known-good state (commit, config, input) vs the broken state
+2. List all differences between good and bad states
+3. Split the differences in half. Apply only half to the good state.
+4. If broken: bug is in the applied half. If not: bug is in the other half.
+5. Repeat until you have the minimal change set that causes the failure.
+
+**Over inputs:**
+1. Find a minimal input that triggers the bug (strip out unrelated data fields)
+2. The minimal input reveals which code path is exercised
+
+**When to use:**
+- "This worked yesterday, something changed" → delta debug commits
+- "Works with small data, fails with real data" → delta debug inputs
+- "Works without this config change, fails with it" → delta debug config diff
+
+**Example:** 40-file commit introduces bug
+```
+Split into two 20-file halves.
+Apply first 20: still works → bug in second half.
+Split second half into 10+10.
+Apply first 10: broken → bug in first 10.
+... 6 splits later: single file isolated.
+```
+
+## Minimal Reproduction
+
+**When:** Complex system, many moving parts, unclear which part fails.
+
+**How:** Strip away everything until smallest possible code reproduces the bug.
+
+1. Copy failing code to new file
+2. Remove one piece (dependency, function, feature)
+3. Test: Does it still reproduce? YES = keep removed. NO = put back.
+4. Repeat until bare minimum
+5. Bug is now obvious in stripped-down code
+6. **Shrinking (input-space bugs)** — when the bug triggers on a class of inputs, wrap it in a property (fast-check for JS/TS, Hypothesis for Python) and let the shrinker auto-minimize the counterexample; store the **minimized** input as the regression seed. See `gsd-core/references/debugger-repro-hardening.md`.
+
+**Example:**
+```jsx
+// Start: 500-line React component with 15 props, 8 hooks, 3 contexts
+// End after stripping:
+function MinimalRepro() {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    setCount(count + 1); // Bug: infinite loop, missing dependency array
+  });
+
+  return <div>{count}</div>;
+}
+// The bug was hidden in complexity. Minimal reproduction made it obvious.
+```
+
+## Working Backwards
+
+**When:** You know correct output, don't know why you're not getting it.
+
+**How:** Start from desired end state, trace backwards.
+
+1. Define desired output precisely
+2. What function produces this output?
+3. Test that function with expected input - does it produce correct output?
+   - YES: Bug is earlier (wrong input)
+   - NO: Bug is here
+4. Repeat backwards through call stack
+5. Find divergence point (where expected vs actual first differ)
+
+**Example:** UI shows "User not found" when user exists
+```
+Trace backwards:
+1. UI displays: user.error → Is this the right value to display? YES
+2. Component receives: user.error = "User not found" → Correct? NO, should be null
+3. API returns: { error: "User not found" } → Why?
+4. Database query: SELECT * FROM users WHERE id = 'undefined' → AH!
+5. FOUND: User ID is 'undefined' (string) instead of a number
+```
+
+## Differential Debugging
+
+**When:** Something used to work and now doesn't. Works in one environment but not another.
+
+**Time-based (worked, now doesn't):**
+- What changed in code since it worked?
+- What changed in environment? (Node version, OS, dependencies)
+- What changed in data?
+- What changed in configuration?
+
+**Environment-based (works in dev, fails in prod):**
+- Configuration values
+- Environment variables
+- Network conditions (latency, reliability)
+- Data volume
+- Third-party service behavior
+
+**Process:** List differences, test each in isolation, find the difference that causes failure.
+
+**Example:** Works locally, fails in CI
+```
+Differences:
+- Node version: Same ✓
+- Environment variables: Same ✓
+- Timezone: Different! ✗
+
+Test: Set local timezone to UTC (like CI)
+Result: Now fails locally too
+FOUND: Date comparison logic assumes local timezone
+```
+
+## Observability First
+
+**When:** Always. Before making any fix.
+
+**Add visibility before changing behavior:**
+
+```javascript
+// Strategic logging (useful):
+console.log('[handleSubmit] Input:', { email, password: '***' });
+console.log('[handleSubmit] Validation result:', validationResult);
+console.log('[handleSubmit] API response:', response);
+
+// Assertion checks:
+console.assert(user !== null, 'User is null!');
+console.assert(user.id !== undefined, 'User ID is undefined!');
+
+// Timing measurements:
+console.time('Database query');
+const result = await db.query(sql);
+console.timeEnd('Database query');
+
+// Stack traces at key points:
+console.log('[updateUser] Called from:', new Error().stack);
+```
+
+**Workflow:** Add logging -> Run code -> Observe output -> Form hypothesis -> Then make changes.
+
+## Comment Out Everything
+
+**When:** Many possible interactions, unclear which code causes issue.
+
+**How:**
+1. Comment out everything in function/file
+2. Verify bug is gone
+3. Uncomment one piece at a time
+4. After each uncomment, test
+5. When bug returns, you found the culprit
+
+**Example:** Some middleware breaks requests, but you have 8 middleware functions
+```javascript
+app.use(helmet()); // Uncomment, test → works
+app.use(cors()); // Uncomment, test → works
+app.use(compression()); // Uncomment, test → works
+app.use(bodyParser.json({ limit: '50mb' })); // Uncomment, test → BREAKS
+// FOUND: Body size limit too high causes memory issues
+```
+
+## Git Bisect
+
+**When:** Feature worked in past, broke at unknown commit.
+
+**How:** Binary search through git history.
+
+```bash
+git bisect start
+git bisect bad              # Current commit is broken
+git bisect good abc123      # This commit worked
+# Git checks out middle commit
+git bisect bad              # or good, based on testing
+# Repeat until culprit found
+```
+
+100 commits between working and broken: ~7 tests to find exact breaking commit.
+
+## Follow the Indirection
+
+**When:** Code constructs paths, URLs, keys, or references from variables — and the constructed value might not point where you expect.
+
+**The trap:** You read code that builds a path like `path.join(configDir, 'hooks')` and assume it's correct because it looks reasonable. But you never verified that the constructed path matches where another part of the system actually writes/reads.
+
+**How:**
+1. Find the code that **produces** the value (writer/installer/creator)
+2. Find the code that **consumes** the value (reader/checker/validator)
+3. Trace the actual resolved value in both — do they agree?
+4. Check every variable in the path construction — where does each come from? What's its actual value at runtime?
+
+**Common indirection bugs:**
+- Path A writes to `dir/sub/hooks/` but Path B checks `dir/hooks/` (directory mismatch)
+- Config value comes from cache/template that wasn't updated
+- Variable is derived differently in two places (e.g., one adds a subdirectory, the other doesn't)
+- Template placeholder (`{{VERSION}}`) not substituted in all code paths
+
+**Example:** Stale hook warning persists after update
+```
+Check code says:  hooksDir = path.join(configDir, 'hooks')
+                  configDir = ~/.claude
+                  → checks ~/.claude/hooks/
+
+Installer says:   hooksDest = path.join(targetDir, 'hooks')
+                  targetDir = ~/.claude/gsd-core
+                  → writes to ~/.claude/gsd-core/hooks/
+
+MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as stale
+```
+
+**The discipline:** Never assume a constructed path is correct. Resolve it to its actual value and verify the other side agrees. When two systems share a resource (file, directory, key), trace the full path in both.
+

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.