@opengsd/gsd-core 1.7.0 → 1.9.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gsd-core",
       "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
-      "version": "1.7.0",
+      "version": "1.9.0",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",

package/.opencode/plugins/gsd-core.js

@@ -200,9 +200,23 @@ function mapToolInput(args) {
  * @param {string} [opts.cwd]         working directory for the child
  * @returns {{ stdout: string, exitCode: number, timedOut: boolean }}
  */
+const warnedMissingHooks = new Set();
+
 function runHook(hookFile, payload, opts = {}) {
   const hookPath = path.join(HOOKS_DIR, hookFile);
   if (!fs.existsSync(hookPath)) {
+    // A missing guard script means the guard is silently NOT enforced — the
+    // exact failure mode of #2305 (plugin staged, hooks bundle not). Never
+    // break the tool call (the adapter's design contract), but never be
+    // silent about it either: warn loudly, once per hook file.
+    if (!warnedMissingHooks.has(hookFile)) {
+      warnedMissingHooks.add(hookFile);
+      console.error(
+        `[gsd-core] hook script missing: ${hookPath} — ${hookFile} is NOT ` +
+          "enforced. The GSD install may be incomplete; reinstall (or run " +
+          "/gsd-update) to restage the hooks/ bundle.",
+      );
+    }
     return { stdout: "", exitCode: 0, timedOut: false };
   }
   const timeout = opts.timeout ?? 8000;
@@ -225,6 +239,32 @@ function runHook(hookFile, payload, opts = {}) {
   return { stdout, exitCode, timedOut: result.signal === "SIGTERM" };
 }
 
+/**
+ * In-process check for whether context-usage warnings are disabled in project
+ * config. Mirrors the exact semantics of the same check inside
+ * hooks/gsd-context-monitor.js (introduced by #1073): an explicit
+ * `config.hooks.context_warnings === false` disables them; a missing or
+ * unparseable .planning/config.json keeps them enabled (the default).
+ *
+ * #2697: hoisting this check in-process lets the adapter SKIP the context-monitor
+ * spawn entirely when the user has opted out, instead of paying a full Node boot
+ * inside the child only to read the boolean and exit. Missing/unparseable config
+ * MUST behave identically to the hook (enabled) so the default path is unchanged.
+ *
+ * @param {string} cwd  project working directory (the plugin's currentCwd)
+ * @returns {boolean} true when context warnings are explicitly disabled
+ */
+function contextWarningsDisabled(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.hooks?.context_warnings === false;
+  } catch {
+    // Missing or unparseable config → proceed with defaults (context warnings enabled).
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Hook output translation → OpenCode semantics
 // ---------------------------------------------------------------------------
@@ -573,7 +613,11 @@ const GsdCorePlugin = async ({ directory } = {}) => {
 
       // gsd-context-monitor.js — context usage warnings (Bash/Edit/Write/Task/...)
       // Only meaningful when a session_id is tracked (writes metrics sentinel).
-      if (currentSessionId) {
+      // #2697: skip the subprocess spawn entirely when context warnings are
+      // explicitly disabled in project config — the hook would exit early anyway,
+      // so hoisting the check in-process avoids paying a Node boot per tool call.
+      // Missing/unparseable config = enabled (default), so the spawn still runs.
+      if (currentSessionId && !contextWarningsDisabled(cwd)) {
         const payload = {
           hook_event_name: "PostToolUse",
           tool_name: claudeTool,

package/README.md

@@ -60,6 +60,8 @@ New here? Follow [Your first project](docs/tutorials/your-first-project.md) for
 
 ## Documentation
 
+**What's new in 1.7.0** → [docs/whats-new-1.7.0.md](docs/whats-new-1.7.0.md)
+
 **Tutorials** — learning by doing:
 - [Your first project](docs/tutorials/your-first-project.md)
 - [Onboarding an existing codebase](docs/tutorials/onboarding-an-existing-codebase.md)

package/agents/gsd-code-fixer.md

@@ -456,7 +456,7 @@ For each finding in sorted order:
 
 **If verification passed:**
 
-Use `gsd-tools query commit` with conventional format (message first, then every staged file path):
+Use `gsd_run query commit` with conventional format (message first, then every staged file path):
 ```bash
 _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 gsd_run query commit \

package/agents/gsd-codebase-mapper.md

@@ -175,7 +175,7 @@ Write document(s) to `.planning/codebase/` using the templates below.
 **Document naming:** UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)
 
 **Template filling:**
-1. Replace `[YYYY-MM-DD]` with the date provided in your prompt (the `Today's date:` line). NEVER guess or infer the date — always use the exact date from the prompt.
+1. Set the `**Analysis Date:**` line, the `*... analysis: ...*` footer, and any `<!-- refreshed: ... -->` header to the date provided in your prompt (the `Today's date:` line), overwriting whatever date is already there. NEVER guess or infer the date — always use the exact date from the prompt.
 2. Replace `[Placeholder text]` with findings from exploration
 3. If something is not found, use "Not detected" or "Not applicable"
 4. Always include file paths with backticks

package/agents/gsd-debug-session-manager.md

@@ -270,30 +270,102 @@ If user selects 1 or 2: spawn continuation agent (with any additional context pr
 
 If user selects 3: proceed to Step 4 with fix = "not applied".
 
+### 3f. FIX REJECTED BY GUARDRAIL
+
+When agent returns `## FIX REJECTED BY GUARDRAIL`:
+
+Present the failing signal and evidence to the user via AskUserQuestion:
+```
+Fix rejected by the acceptance guardrail.
+
+Failing signal: {failing signal}
+Evidence: {why it failed}
+
+Options:
+1. Revise fix — spawn continuation agent to revise the fix so the signal passes
+2. Accept as technical debt — record the unmet signal + justification (the fix lands without the gate passing; this is never silent)
+3. Abandon — stop; session stays unresolved
+```
+
+If user selects 1: spawn continuation agent with `goal: find_and_fix` naming the failing signal to revise. Loop back to Step 3.
+
+If user selects 2: spawn continuation agent instructed to record `guardrail_verdict: accepted_debt` + the justification in the debug file, then proceed to request_human_verification. Loop back to Step 3.
+
+If user selects 3: proceed to Step 4 with fix = "not applied (guardrail rejected)".
+
 ## Step 4: Return Compact Summary
 
+**Non-terminal early stop — check this FIRST.** Before returning any summary below, ask: is your own turn/context budget exhausted while the debugger (`gsd-debugger`) is still investigating — i.e. you have NOT reached `DEBUG COMPLETE`, a user-chosen `ABANDONED`, or exhausted the `INVESTIGATION INCONCLUSIVE` options? If so, do NOT fabricate a `DEBUG SESSION COMPLETE` or `ABANDONED` summary to fit this shape. Return the non-terminal marker instead:
+
+```markdown
+## CONTINUE_REQUIRED
+
+**Session:** {debug_file_path}
+**Status:** {status from frontmatter, e.g. investigating}
+**Next action:** {next_action from Current Focus}
+**Reason:** session-manager turn/context budget exhausted — investigation still in progress
+```
+
+`CONTINUE_REQUIRED` is distinct from both terminal shapes below AND from `## CHECKPOINT REACHED` (Step 3d): a `CHECKPOINT REACHED` is a genuine user-input/approval checkpoint that already correctly pauses via `AskUserQuestion` before looping back to Step 3 — it is not returned to the orchestrator. `CONTINUE_REQUIRED` is emitted only when no checkpoint is pending and the loop simply cannot proceed further in this turn. The orchestrator resumes by re-spawning this agent with the SAME `slug`/`debug_file_path` — the on-disk checkpoint at `.planning/debug/{slug}.md` (its `status` and `next_action`) is the source of truth for where to pick up. Never return control to the user as if the session were complete when it is not.
+
 Read the resolved (or current) debug file to extract final Resolution values.
 
-Return compact summary:
+**Commit before returning a terminal summary (#2568).** This agent owns the terminal path —
+it applies fixes, archives to `resolved/`, and returns the summary — but carried no commit
+step, so `commit_docs` was never consulted on the normal `/gsd:debug` flow and session docs
+were left untracked. Do this for **both** terminal shapes below, and **NOT** for
+`CONTINUE_REQUIRED` above: that shape is non-terminal, and committing there would strand a
+half-finished session looking done, exactly as fabricating a terminal summary would.
+`CHECKPOINT REACHED` (Step 3d) likewise does not commit — it pauses for user input and loops
+back to Step 3.
+
+1. **In-session fix code.** If a fix was applied during this session and its code changes are
+   still uncommitted, commit them first. Stage **specific files only** — the files the fix
+   touched. Do this rather than `git add -A`, which would sweep unrelated working-tree
+   changes into a debug commit. Guard on staged content: `gsd-debugger.md`'s
+   `archive_session` step may already have committed this fix on the confirmed-checkpoint
+   path, and a bare `git commit` with nothing staged exits non-zero and would abort this
+   step before the summary is returned:
+   ```bash
+   git add <files the fix touched>
+   git diff --cached --quiet || git commit -m "fix: {brief description}"
+   ```
+2. **Session doc.** Commit via the CLI, which already gates on `commit_docs` and returns
+   `skipped_commit_docs_false` when disabled — call it unconditionally rather than
+   re-checking the config here, so the policy lives in one place. `query commit` treats an
+   empty diff as `nothing_to_commit` and exits 0, so a second call after
+   `archive_session` already committed the doc is a safe no-op. The canonical `gsd_run` preamble is
+   established once in Step 2 and is the single definition this agent carries (repo
+   invariant: exactly one preamble per agent file, before its first call):
+   ```bash
+   # resolved session — path spelled literally; this agent receives `slug` and
+   # `debug_file_path`, NOT a `debug_dir` variable (see <session_parameters>).
+   gsd_run query commit "docs(debug): resolve {slug} session" --files .planning/debug/resolved/{slug}.md
+   # abandoned session (checkpoint retained for `/gsd:debug continue {slug}`)
+   gsd_run query commit "docs(debug): checkpoint {slug} session" --files {debug_file_path}
+   ```
+
+Return compact summary (terminal — investigation resolved):
 
 ```markdown
 ## DEBUG SESSION COMPLETE
 
 **Session:** {final path — resolved/ if archived, otherwise debug_file_path}
-**Root Cause:** {one sentence from Resolution.root_cause, or "not determined"}
+**Root Cause:** {one sentence, or a '; '-joined list when the AND-gate identified multiple contributing causes, from Resolution.root_cause; or "not determined"}
 **Fix:** {one sentence from Resolution.fix, or "not applied"}
 **Cycles:** {N} (investigation) + {M} (fix)
 **TDD:** {yes/no}
 **Specialist review:** {specialist_hint used, or "none"}
+**Prevention:** {one-line from the blameless postmortem — "why not caught: <gate, or 'none (no gate existed for this class)'>; guard: <artifact>"}
 ```
 
-If the session was abandoned by user choice, return:
+If the session was abandoned by user choice, return (terminal — user stopped):
 
 ```markdown
 ## DEBUG SESSION COMPLETE
 
 **Session:** {debug_file_path}
-**Root Cause:** {one sentence if found, or "not determined"}
+**Root Cause:** {one sentence if found (or a '; '-joined list if the AND-gate identified multiple contributing causes), or "not determined"}
 **Fix:** not applied
 **Cycles:** {N}
 **TDD:** {yes/no}
@@ -311,5 +383,7 @@ If the session was abandoned by user choice, return:
 - [ ] Specialist dispatch executed when specialist_dispatch_enabled and hint maps to a skill
 - [ ] TDD gate applied when tdd_mode=true and ROOT CAUSE FOUND
 - [ ] Loop continues until DEBUG COMPLETE, ABANDONED, or user stops
+- [ ] Non-terminal `CONTINUE_REQUIRED` (not a fabricated terminal summary) returned when the manager's own turn/context budget is exhausted mid-investigation
+- [ ] Session doc (and any uncommitted fix code from this session) committed before a terminal summary, respecting `commit_docs` — and NOT committed on the non-terminal `CONTINUE_REQUIRED` path
 - [ ] Compact summary returned (at most 2K tokens)
 </success_criteria>

package/agents/gsd-debugger.md

@@ -253,6 +253,10 @@ reasoning_checkpoint:
   falsification_test: "[what specific observation would prove this hypothesis wrong]"
   fix_rationale: "[why the proposed fix addresses the root cause — not just the symptom]"
   blind_spots: "[what you haven't tested that could invalidate this hypothesis]"
+  candidate_causes:
+    - "[cause in category: code|config|environment|data]"
+    - "[cause in a DIFFERENT category — single-category is not a branch]"
+  and_gate: "[could this failure require >1 contributing condition simultaneously? yes/no + why — see RCA branching]"
 ```
 
 **Check before proceeding:**
@@ -260,8 +264,9 @@ reasoning_checkpoint:
 - Is the confirming evidence direct observation, not inference?
 - Does the fix address the root cause or a symptom?
 - Have you documented your blind spots honestly?
+- **Did you branch across ≥2 categories and answer the AND-gate?** (Single-cause is fine when the AND-gate is no — but you must have checked.)
 
-If you cannot fill all five fields with specific, concrete answers — you do not have a confirmed root cause yet. Return to investigation_loop.
+If you cannot fill all seven fields with specific, concrete answers — you do not have a confirmed root cause yet. Return to investigation_loop.
 
 ## Minimal Reproduction
 
@@ -274,6 +279,7 @@ If you cannot fill all five fields with specific, concrete answers — you do no
 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
@@ -443,18 +449,21 @@ MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as
 
 **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.
 
-## Technique Selection
+## Technique Selection (routed by bug class)
 
-| Situation | Technique |
-|-----------|-----------|
-| Large codebase, many files | Binary search |
-| Confused about what's happening | Rubber duck, Observability first |
-| Complex system, many interactions | Minimal reproduction |
-| Know the desired output | Working backwards |
-| Used to work, now doesn't | Differential debugging, Git bisect |
-| Many possible causes | Comment out everything, Binary search |
-| Paths, URLs, keys constructed from variables | Follow the indirection |
-| Always | Observability first (before making changes) |
+Classify the failure first (Phase 1.75), then route by class — not by ad-hoc
+situation:
+
+@~/.claude/gsd-core/references/debugger-bug-taxonomy.md
+
+| bug_class | Route to | Revoke if already run |
+|---|---|---|
+| Bohrbug | deterministic reproduction → SBFL (Phase 1.25) → git bisect → binary search | — |
+| Heisenbug / Mandelbug | record-replay (`rr`) → stability-stress → statistical sampling | SBFL — Phase 1.25 runs before classification; if it ran, mark its Evidence entry revoked (flaky spectrum poisons the ranking) |
+| Concurrency | atomicity / order / deadlock checklist (see reference) FIRST | — |
+| General (any class) | Binary search, Working backwards, Differential, Delta debugging, Comment-out-everything, Follow-the-indirection, Rubber duck, Observability first (always, before changes) | — |
+
+The class rows pick the first move; the General lane holds situation-cued techniques that apply to any class. When the situation table and the class route disagree, the class route wins.
 
 ## Combining Techniques
 
@@ -590,6 +599,13 @@ function processUserData(user) {
 // 5. Test is now regression protection forever
 ```
 
+**Harden the regression test (so the Phase 1A mutation guardrail bites):**
+
+@~/.claude/gsd-core/references/debugger-repro-hardening.md
+
+- **Classify the oracle** before writing the assertion — `specified` / `derived` (contract/model) / `metamorphic` / `implicit` (crash, weakest). Record it under `Resolution.oracle_type`. Never default to implicit silently.
+- **Add boundary neighbors** around the fixed defect's equivalence class — off-by-one (N±1), min/max (0/length), empty/singleton — the single reported value misses the adjacent off-by-one.
+
 ## Verification Checklist
 
 ```markdown
@@ -788,9 +804,11 @@ Each resolved session appends one entry:
 ## {slug} — {one-line description}
 - **Date:** {ISO date}
 - **Error patterns:** {comma-separated keywords extracted from symptoms.errors and symptoms.actual}
-- **Root cause:** {from Resolution.root_cause}
+- **Root cause(s):** {from Resolution.root_cause — one cause, or a '; '-joined list when the AND-gate fired}
 - **Fix:** {from Resolution.fix}
 - **Files changed:** {from Resolution.files_changed}
+- **Why not caught:** {which existing gate (test/typecheck/lint/review/verify/build) should have caught it — or "no gate existed for this class"}
+- **Recurrence guard:** {the concrete artifact preventing this class from returning — regression test (path:name) / assertion / lint rule / type refinement / config-default change / KB pattern}
 ---
 ```
 
@@ -804,9 +822,11 @@ At the **end of `archive_session`**, after the session file is moved to `resolve
 
 ## Matching Logic
 
-Matching is keyword overlap, not semantic similarity. Extract nouns and error substrings from `Symptoms.errors` and `Symptoms.actual`. Scan each knowledge base entry's `Error patterns` field for overlapping tokens (case-insensitive, 2+ word overlap = candidate match).
+**Semantic-first, keyword-fallback.** Query MemPalace with the current symptoms and surface the top-k meaning-similar prior resolutions — this catches same-root-cause/different-wording cases keyword overlap misses. Fall back to keyword overlap on `knowledge-base.md` when MemPalace is absent. See:
+
+@~/.claude/gsd-core/references/debugger-semantic-recall.md
 
-**Important:** A match is a **hypothesis candidate**, not a confirmed diagnosis. Surface it in Current Focus and test it first — but do not skip other hypotheses or assume correctness.
+**Important:** A match is a **hypothesis candidate**, not a confirmed diagnosis — surface it in Current Focus and test it first; do not skip other hypotheses or assume correctness.
 
 </knowledge_base_protocol>
 
@@ -966,12 +986,10 @@ At investigation decision points, apply structured reasoning:
 **Autonomous investigation. Update file continuously.**
 
 **Phase 0: Check knowledge base**
-- If `.planning/debug/knowledge-base.md` exists, read it
-- Extract keywords from `Symptoms.errors` and `Symptoms.actual` (nouns, error substrings, identifiers)
-- Scan knowledge base entries for 2+ keyword overlap (case-insensitive)
+- Query MemPalace semantically with the current symptoms (top-k meaning-similar prior resolutions); fall back to reading `.planning/debug/knowledge-base.md` and keyword overlap when MemPalace is absent
 - If match found:
   - Note in Current Focus: `known_pattern_candidate: "{matched slug} — {description}"`
-  - Add to Evidence: `found: Knowledge base match on [{keywords}] → Root cause was: {root_cause}. Fix was: {fix}.`
+  - Add to Evidence: `found: Knowledge base match on [{keywords}] → Root cause was: {root_cause}. Fix was: {fix}. Why not caught: {why_not_caught}. Recurrence guard: {recurrence_guard}.` (the last two are absent on old entries — that's fine; consume them when present)
   - Test this hypothesis FIRST in Phase 2 — but treat it as one hypothesis, not a certainty
 - If no match: proceed normally
 
@@ -983,14 +1001,32 @@ At investigation decision points, apply structured reasoning:
 - Run app/tests to observe behavior
 - APPEND to Evidence after each finding
 
+**Phase 1.25: Spectrum-based fault localization (optional, coverage-gated)**
+- When a runnable test suite with per-test coverage exists (≥1 failing AND ≥1 passing test), compute an Ochiai suspiciousness ranking and seed the top-N into Evidence before forming hypotheses — narrows the search space deterministically before LLM reasoning:
+
+@~/.claude/gsd-core/references/debugger-sbfl.md
+
+- Skip with a logged note when there is no test suite, no failing tests, or no per-test coverage; investigation proceeds unchanged
+
 **Phase 1.5: Check common bug patterns**
 - Read @~/.claude/gsd-core/references/common-bug-patterns.md
 - Match symptoms to pattern categories using the Symptom-to-Category Quick Map
 - Any matching patterns become hypothesis candidates for Phase 2
 - If no patterns match, proceed to open-ended hypothesis formation
 
+**Phase 1.75: Classify the failure**
+- Assign a `bug_class` — Bohrbug (deterministic) / Heisenbug-Mandelbug (transient, non-deterministic) / Concurrency — and record it in Current Focus. The class routes which investigation technique to use:
+
+@~/.claude/gsd-core/references/debugger-bug-taxonomy.md
+
+- Bohrbug → reproduction + SBFL + bisect; Heisenbug/Mandelbug → record-replay/stability (skip SBFL — flaky spectra poison it); Concurrency → the atomicity/order/deadlock checklist first
+
 **Phase 2: Form hypothesis**
 - Based on evidence AND common pattern matches, form SPECIFIC, FALSIFIABLE hypothesis
+- **Branch, don't chain** — at hypothesis formation (so it's done before the Phase 4 commit), enumerate candidate causes across ≥2 Ishikawa categories (code / config / environment / data) and answer the AND-gate check; `root_cause` may hold a set when the AND-gate fires:
+
+@~/.claude/gsd-core/references/debugger-rca-branching.md
+
 - Update Current Focus with hypothesis, test, expecting, next_action
 
 **Phase 3: Test hypothesis**
@@ -1043,7 +1079,7 @@ Return structured diagnosis:
 
 **Debug Session:** .planning/debug/{slug}.md
 
-**Root Cause:** {from Resolution.root_cause}
+**Root Cause:** {from Resolution.root_cause — one cause, or a '; '-joined list when the AND-gate identified multiple contributing causes}
 
 **Evidence Summary:**
 - {key finding 1}
@@ -1083,7 +1119,7 @@ Update status to "fixing".
 
 **0. Structured Reasoning Checkpoint (MANDATORY)**
 - Write the `reasoning_checkpoint` block to Current Focus (see Structured Reasoning Checkpoint in investigation_techniques)
-- Verify all five fields can be filled with specific, concrete answers
+- Verify every field can be filled with specific, concrete answers — including the RCA `candidate_causes` (≥2 categories) and `and_gate` fields
 - If any field is vague or empty: return to investigation_loop — root cause is not confirmed
 
 **1. Implement minimal fix**
@@ -1091,11 +1127,15 @@ Update status to "fixing".
 - Make SMALLEST change that addresses root cause
 - Update Resolution.fix and Resolution.files_changed
 
-**2. Verify**
+**2. Verify (Fix-Acceptance Guardrail)**
 - Update status to "verifying"
-- Test against original Symptoms
-- If verification FAILS: status -> "investigating", return to investigation_loop
-- If verification PASSES: Update Resolution.verification, proceed to request_human_verification
+- Run the multi-signal guardrail before accepting the fix:
+
+@~/.claude/gsd-core/references/debugger-fix-acceptance.md
+
+- Record every signal's result under `Resolution.verification` (per-signal schema in the reference)
+- If ANY applicable signal fails (and no documented technical-debt escape applies): return `## FIX REJECTED BY GUARDRAIL` (see structured_returns) — do NOT request human verification
+- If all applicable signals pass: set `guardrail_verdict: accepted`, proceed to request_human_verification
 </step>
 
 <step name="request_human_verification">
@@ -1174,9 +1214,13 @@ Then commit planning docs via CLI (respects `commit_docs` config automatically):
 gsd_run query commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
 ```
 
-**Append to knowledge base:**
+**Append to knowledge base (with the Prevention block):**
+
+Read `.planning/debug/resolved/{slug}.md` to extract final `Resolution` values. Then produce the **Prevention block** — a blameless postmortem (branching 5-Whys per RCA, "why wasn't this caught?", and a concrete recurrence guard):
+
+@~/.claude/gsd-core/references/debugger-prevention.md
 
-Read `.planning/debug/resolved/{slug}.md` to extract final `Resolution` values. Then append to `.planning/debug/knowledge-base.md` (create file with header if it doesn't exist):
+Then append to `.planning/debug/knowledge-base.md` (create file with header if it doesn't exist):
 
 If creating for the first time, write this header first:
 ```markdown
@@ -1193,9 +1237,11 @@ Then append the entry:
 ## {slug} — {one-line description of the bug}
 - **Date:** {ISO date}
 - **Error patterns:** {comma-separated keywords from Symptoms.errors + Symptoms.actual}
-- **Root cause:** {Resolution.root_cause}
+- **Root cause(s):** {Resolution.root_cause — joined as '; ' when multiple contributing causes were confirmed}
 - **Fix:** {Resolution.fix}
 - **Files changed:** {Resolution.files_changed joined as comma list}
+- **Why not caught:** {which existing gate (test/typecheck/lint/review/verify/build) should have caught it — or "no gate existed for this class"}
+- **Recurrence guard:** {concrete artifact preventing this class from returning — regression test (path:name) / assertion / lint rule / KB pattern / type refinement / config-default change}
 ---
 
 ```
@@ -1205,6 +1251,8 @@ Commit the knowledge base update alongside the resolved session:
 gsd_run query commit "docs: update debug knowledge base with {slug}" --files .planning/debug/knowledge-base.md
 ```
 
+**Index into MemPalace (when available)** per the semantic-recall reference — the Resolution summary (not raw symptoms), redacted — so a future Phase-0 query surfaces it by meaning. Skip with a logged note when MemPalace is absent or the KB write failed; `knowledge-base.md` is the durable fallback.
+
 Report completion and offer next steps.
 </step>
 
@@ -1298,7 +1346,7 @@ Orchestrator presents checkpoint to user, gets response, spawns fresh continuati
 
 **Debug Session:** .planning/debug/{slug}.md
 
-**Root Cause:** {specific cause with evidence}
+**Root Cause:** {specific cause with evidence — one cause, or a '; '-joined list when the AND-gate identified multiple contributing causes}
 
 **Evidence Summary:**
 - {key finding 1}
@@ -1334,6 +1382,16 @@ Orchestrator presents checkpoint to user, gets response, spawns fresh continuati
 
 Only return this after human verification confirms the fix.
 
+## FIX REJECTED BY GUARDRAIL
+
+Returned when a fix-acceptance guardrail signal fails (see `@~/.claude/gsd-core/references/debugger-fix-acceptance.md`). Do **not** mark the session resolved.
+
+**Debug Session:** .planning/debug/{slug}.md
+**Failing signal:** {signal 1–5 name}
+**Evidence:** {why the signal failed — e.g. "mutant at fix site survived", "deletion-only diff with no RCA justification", "bug did not return on revert"}
+
+The session-manager continuation surfaces this and offers revise / accept-as-debt / abandon.
+
 ## INVESTIGATION INCONCLUSIVE
 
 ```markdown

package/agents/gsd-executor.md

@@ -144,6 +144,10 @@ At execution decision points, apply structured reasoning:
 
 For each task:
 
+0. **Precondition check (before any other task work):** If the task carries a `<precondition>` element, evaluate that single prose line first — it names a runnable/checkable fact the task assumes (env var set, prior-phase artifact present, server responding to `/health`, `user_setup` step done). Verify with **read-only checks only** — file existence, env var presence (no value output), idempotent `GET /health`-style pings. Do NOT run commands with side effects (writes, network POSTs, secret emission) as the check; if a side-effecting check seems required, halt and surface via checkpoint instead.
+   - **Met OR absent:** continue with no visible change to execution flow. The precondition is a no-op for the rest of the task loop.
+   - **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, even under `AUTO_CFG=true` — a missing prerequisite is not a verification step a human can rubber-stamp; it is a fact the executor cannot establish on its own. The human either satisfies the precondition (sets the env var, completes the `user_setup` step, regenerates the artifact) or reruns `/gsd:plan-phase` to restructure.
+
 1. **If `type="auto"`:**
    - Check for `tdd="true"` → follow TDD execution flow
    - Execute task, apply deviation rules as needed
@@ -152,11 +156,17 @@ For each task:
    - Commit (see task_commit_protocol)
    - Track completion + commit hash for Summary
 
-2. **If `type="checkpoint:*"`:**
+2. **If `type="tracer"`:** (the leading thin end-to-end slice — production-quality, never a throwaway)
+   - Execute and commit exactly like `type="auto"` (real implementation, real `<verify>`, atomic commit).
+   - **Then run the tracer feedback gate BEFORE any expansion task** — an early integration checkpoint on the proven slice:
+     - **Autonomous run (auto mode active — `AUTO_CHAIN` or `AUTO_CFG` is `"true"`, per `<auto_mode_detection>`):** re-run the tracer's `<verify>` end-to-end. If it **fails**, HALT and surface it (deviation Rule 1) — do NOT proceed to expansion tasks. Pouring more layers onto a broken foundation is exactly the failure this gate prevents. If it passes, log `⚡ Tracer verified end-to-end — expanding` and continue.
+     - **Interactive run (auto mode not active):** immediately after committing the tracer, STOP and return a `checkpoint:human-verify` for the tracer's `<verify>` (the working slice) using checkpoint_return_format, before any expansion task.
+
+3. **If `type="checkpoint:*"`:**
    - STOP immediately — return structured checkpoint message
    - A fresh agent will be spawned to continue
 
-3. After all tasks: run overall verification, confirm success criteria, document deviations
+4. After all tasks: run overall verification, confirm success criteria, document deviations
 </step>
 
 </execution_flow>
@@ -310,6 +320,8 @@ For full automation-first patterns, server lifecycle, CLI handling:
 
 **Quick reference:** Users NEVER run CLI commands. Users ONLY visit URLs, click UI, evaluate visuals, provide secrets. Claude does all automation.
 
+**Tracer feedback gate:** a `type="tracer"` task is followed by an early integration checkpoint on the proven slice (see `<execution_flow>` → `execute_tasks`) — in autonomous runs a failing tracer `<verify>` HALTS before any expansion task; in interactive runs the executor emits a `checkpoint:human-verify` for the tracer immediately after committing it.
+
 ---
 
 **Auto-mode checkpoint behavior** (when `AUTO_CFG` is `"true"`):
@@ -483,11 +495,11 @@ if [ -f .git ]; then  # worktree
     echo "DO NOT use 'git update-ref' to rewind the protected branch — surface as blocker (#2924)." >&2
     exit 1
   fi
-  # Positive allow-list: HEAD must be on the canonical Claude Code worktree-agent
-  # branch namespace (`worktree-agent-<id>`). This catches feature/* and any other
-  # arbitrary branch that the deny-list would silently allow (#2924).
-  if ! echo "$ACTUAL_BRANCH" | grep -Eq '^worktree-agent-[A-Za-z0-9._/-]+$'; then
-    echo "FATAL: refusing to commit — worktree HEAD '$ACTUAL_BRANCH' is not in the worktree-agent-* namespace." >&2
+  # Positive allow-list: HEAD must be on a per-agent branch (`agent-<id>` or
+  # legacy `worktree-agent-<id>`). This catches feature/* and any other
+  # arbitrary branch that the deny-list would silently allow (#2924, #1995).
+  if ! echo "$ACTUAL_BRANCH" | grep -Eq '^(worktree-)?agent-[A-Za-z0-9._/-]+$'; then
+    echo "FATAL: refusing to commit — worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* namespace." >&2
     echo "Agent commits must live on per-agent branches; surface as blocker (#2924)." >&2
     exit 1
   fi
@@ -626,7 +638,16 @@ This file is the canonical output of this step. The orchestrator reads `.plannin
 
 **Use template:** @~/.claude/gsd-core/templates/summary.md
 
-**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date), status (`status: complete` — required so the audit-open scanner recognises the summary as done).
+**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date), status (`status: complete` — required so the audit-open scanner recognises the summary as done), and `actuals` (#2632).
+
+**`actuals` (required when the plan carried an `estimate`):** record what the phase ACTUALLY cost, on the SAME scale the estimate used — `estimateTokens` (chars/4) over the realized diff, NOT a harness token count. Mixing scales measures the measurement methods, not the miss.
+```yaml
+actuals:
+  tokens: 74000    # chars/4 over the files you actually changed
+  tasks: 5         # tasks completed
+  commits: 7       # commits made
+```
+These pair with the plan's `estimate` to calibrate future estimates (ADR-2629). Do not round to look closer to the estimate — a flattering number corrupts every later projection.
 
 **Title:** `# Phase [X] Plan [Y]: [Name] Summary`
 
@@ -660,6 +681,21 @@ Or: "None - plan executed exactly as written."
 
 If any stubs exist, add a `## Known Stubs` section to the SUMMARY listing each stub with its file, line, and reason. These are tracked for the verifier to catch. Do NOT mark a plan as complete if stubs exist that prevent the plan's goal from being achieved — either wire the data or document in the plan why the stub is intentional and which future plan will resolve it.
 
+**Broken-windows ledger (issue #1950).** For each stub, skipped test, or unrun `<verify>` recorded above, ALSO append it to the cross-phase defect register at `.planning/WINDOWS.md`. The ledger accumulates across phases and blocks `/gsd:ship` while any entry is `open`, so a stub written here is visible at ship time even after the per-phase SUMMARY scrolls out of context. Append one entry per defect:
+
+```bash
+gsd_run windows append \
+  --kind stub \
+  --phase "${PHASE_NUMBER}" \
+  --file "<path-relative-to-repo-root>" \
+  --line "<line-number-or-omit>" \
+  --description "<one-line description, same wording as the Known Stubs row>"
+```
+
+Use `--kind skipped-test` for a `t.skip(...)` / `test.todo(...)` you left behind, `--kind unrun-verify` for a `<verify>` you could not run, or `--kind deviation` for a documented plan deviation. The full kind vocabulary: `stub | todo | fixme | skipped-test | lint-warning | unmet-truth | unrun-verify | deviation`.
+
+The ledger is **optional**: if `gsd_run windows append` returns `windows_ledger_missing` or `windows_ok` without writing, continue without error — population is best-effort and never blocks execution. Recording here is what makes the defect visible to the ship gate later; forgetting to record is the failure mode this ledger exists to prevent.
+
 **Threat surface scan:** Before writing the SUMMARY, check if any files created/modified introduce security-relevant surface NOT in the plan's `<threat_model>` — new network endpoints, auth paths, file access patterns, or schema changes at trust boundaries. If found, add:
 
 ```markdown
@@ -753,7 +789,7 @@ gsd_run query commit "docs({phase}-{plan}): complete [plan-name] plan" --files \
 Separate from per-task commits — captures execution results only.
 
 **Handling the SDK return envelope (#3678):** `gsd-tools query commit` returns
-one of three shapes:
+one of these shapes:
 
 - `{committed: true, hash, reason: 'committed'}` — commit succeeded; record
   the hash in the completion format.
@@ -766,6 +802,10 @@ one of three shapes:
   success path.** Record "skipped (.planning gitignored)" and move on.
 - `{committed: false, reason: 'nothing_to_commit' | 'commit_failed', ...}` —
   no-op / genuine failure; surface in the completion notes.
+- `{committed: false, reason: 'staging_failed' | 'staging_timeout', file, error}` —
+  `git add` itself failed (#2608), e.g. an unwritable index. Nothing committed,
+  index rolled back. Surface `file` + `error` (git's stderr); do not retry — a
+  retry hits the same cause.
 
 **Do not fall back to raw `git add` / `git commit` / `git add -f`** when the
 SDK returns `skipped: true`. The SDK's skip is the user's deliberate choice