@opengsd/gsd-core 1.9.1 → 1.11.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.9.1",
+      "version": "1.11.0",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",
@@ -19,6 +19,5 @@
     "gsd"
   ],
   "commands": "./commands/gsd/",
-  "skills": "./skills/",
-  "hooks": "./hooks/hooks.json"
+  "skills": "./skills/"
 }

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

@@ -563,7 +563,14 @@ const GsdCorePlugin = async ({ directory } = {}) => {
         handleHookResult(r, output);
       }
 
-      // 4. gsd-workflow-guard.js — workflow advisory + git-force-add block
+      // 4. gsd-write-guard.js — hard-block catastrophic shrink of curated
+      //    .planning/ artifacts (ROADMAP.md, milestones/*-ROADMAP.md, STATE.md)
+      if (claudeTool === "Write") {
+        const r = runHook("gsd-write-guard.js", prePayload());
+        handleHookResult(r, output);
+      }
+
+      // 5. gsd-workflow-guard.js — workflow advisory + git-force-add block
       //    (covers Write/Edit/MultiEdit AND Bash force-add detection)
       if (isWriteLike || claudeTool === "Bash") {
         const r = runHook("gsd-workflow-guard.js", prePayload());

package/agents/gsd-code-fixer.md

@@ -252,6 +252,17 @@ USE_WORKTREES=$(node -e '
 branch=$(git branch --show-current)
 test -n "$branch" || { echo "Detached HEAD is not supported for review-fix (#2686)"; exit 1; }
 
+# #2647 defense-in-depth: padded_phase is interpolated into a worktree PATH
+# and a git BRANCH NAME below. The orchestrator (code-review-fix.md) already
+# validates it as ^[0-9]+(\.[0-9]+)?$, but this agent prompt is a literal bash
+# contract any caller can spawn — validate at the SINK too, so a future caller
+# that forgets cannot turn ${padded_phase} into a path-traversal or branch-name
+# injection. Reject anything that is not digits + an optional single dotted
+# numeric suffix (e.g. '02' or '36.14'); reject '../', spaces, shell metachars.
+if ! [[ "$padded_phase" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
+  echo "Invalid padded_phase for review-fix: '$padded_phase' (expected e.g. '02' or '36.14')"; exit 1
+fi
+
 # Recovery-sentinel handling (#2839):
 # Path is ${phase_dir}/.review-fix-recovery-pending.json. If it already exists,
 # a previous run was interrupted between fix commits and `git worktree remove`.
@@ -303,7 +314,20 @@ if [ "$USE_WORKTREES" = "false" ]; then
   reviewfix_branch="$branch"
   echo "workflow.use_worktrees=false — editing/committing in the main checkout (no worktree)."
 else
-  wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")
+  # #2647: create the worktree INSIDE the repo under the same `.claude/worktrees/`
+  # dir the harness-managed executor worktrees already use. An absolute `/tmp`
+  # path landed outside the project tree (outside the agent session's permission
+  # allowlist → every Read inside prompted; on Windows/Git Bash mktemp also
+  # produced an un-removable short `C:/mvwtNN` path to dodge MAX_PATH). A
+  # repo-relative path inherits the repository's existing permission scope, is
+  # valid and short on Windows as well as POSIX, and is covered by the single
+  # `.gitignore` rule for `.claude/` (`.gitignore:12`). Uniqueness across
+  # concurrent runs for the same phase comes from the PID (`$$`) + epoch suffix
+  # (replacing mktemp's XXXXXX). `$main_repo` is resolved the same way the
+  # cleanup tail below resolves it (`git worktree list --porcelain` first line).
+  main_repo="$(git worktree list --porcelain | awk '/^worktree / { sub(/^worktree /, ""); print; exit }')"
+  wt="$main_repo/.claude/worktrees/rf-${padded_phase}-$$-$(date +%s)"
+  mkdir -p "$wt"
 
   # Create a temp branch from the current branch tip so the worktree
   # attaches to that NEW branch rather than the user's currently-checked-out
@@ -338,7 +362,7 @@ Concrete steps:
 1. Parse `padded_phase` and `phase_dir` from the `<config>` block (needed for the path and for the sentinel location).
 2. Resolve the current branch: `branch=$(git branch --show-current)`. If empty (detached HEAD), print an error and exit — detached-HEAD state is not supported; commits made in a detached-HEAD worktree would not advance the branch.
 3. **Recovery check (#2839, #2990):** If `${phase_dir}/.review-fix-recovery-pending.json` already exists, a prior run was interrupted. Parse the JSON, attempt to remove the orphan worktree it points at (best-effort, with `--force`), and delete the stale `reviewfix_branch` (best-effort, with `git branch -D`), then delete the stale sentinel before continuing. This makes a re-run of `/gsd:code-review --fix` self-healing.
-4. Create a unique worktree path: `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")`. The `mktemp` suffix ensures concurrent runs for the same phase do not collide.
+4. Create a unique worktree path **inside the repo**: `main_repo="$(git worktree list --porcelain | awk '/^worktree / { sub(/^worktree /, ""); print; exit }')"` then `wt="$main_repo/.claude/worktrees/rf-${padded_phase}-$$-$(date +%s)"` + `mkdir -p "$wt"`. The path lives under the same `.claude/worktrees/` dir the harness-managed executor worktrees use (already gitignored via `.claude/`, already in the session's permission scope), and the `$$`-PID + epoch suffix ensures concurrent runs for the same phase do not collide (#2647 — an absolute `/tmp` path landed outside the project tree and prompted on every read).
 5. Run `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` — this creates a NEW branch (`gsd-reviewfix/${padded_phase}-$$`) starting from the current branch tip and attaches the worktree to that new branch. Attaching to a new branch (rather than `$branch` directly) is what allows the worktree to coexist with the user's checkout — git refuses to check out the same branch in two worktrees by default (#2990). Commits made inside the worktree advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits.
 6. **Write the recovery sentinel** at `${phase_dir}/.review-fix-recovery-pending.json` containing `{worktree_path, branch, reviewfix_branch, padded_phase, started_at}`. Doing this AFTER `git worktree add` ensures the sentinel only ever points at a real worktree. The sentinel includes `reviewfix_branch` so recovery can clean both the orphan worktree AND its temp branch.
 7. All subsequent file reads, edits, and commits happen inside `$wt` (which is on `$reviewfix_branch`, not `$branch`).
@@ -636,7 +660,7 @@ _Iteration: {N}_
 
 <critical_rules>
 
-**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `wt=$(mktemp -d "/tmp/sv-${padded_phase}-reviewfix-XXXXXX")` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). Using `mktemp` ensures concurrent runs do not collide. Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail when done (treat it as a finally block) — but only when a worktree was actually created; when `workflow.use_worktrees` is `false` the cleanup early-exits (no worktree to remove). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
+**ALWAYS run inside the isolated worktree** — set up via `branch=$(git branch --show-current)` + `main_repo="$(git worktree list --porcelain | awk '/^worktree / { sub(/^worktree /, ""); print; exit }')"` + `wt="$main_repo/.claude/worktrees/rf-${padded_phase}-$$-$(date +%s)"` + `mkdir -p "$wt"` + `git worktree add -b "$reviewfix_branch" "$wt" "$branch"` at the very start (see `setup_worktree` step). The worktree path is repo-relative under `.claude/worktrees/` (the same dir the harness-managed executor worktrees use — gitignored via `.claude/`, inside the session's permission scope); the `$$`-PID + epoch suffix ensures concurrent runs do not collide (#2647 — a hardcoded `/tmp` path landed outside the project tree and prompted on every read). Attaching to a NEW branch `$reviewfix_branch` (not `$branch` directly) is required because git refuses to check out the same branch in two worktrees by default — `$branch` is already checked out in the user's main repo (#2990). Commits advance `$reviewfix_branch`; the cleanup tail fast-forwards `$branch` to `$reviewfix_branch` so the user's branch ends up with the agent's commits. Every file read, edit, and commit must happen inside `$wt`. Run the four-step cleanup tail when done (treat it as a finally block) — but only when a worktree was actually created; when `workflow.use_worktrees` is `false` the cleanup early-exits (no worktree to remove). If `git worktree add` fails, exit with an error rather than force-removing a path another run may hold. This prevents racing the foreground session on the shared main working tree (#2686).
 
 **#2825 — honor `workflow.use_worktrees`.** Before creating a worktree, read the
 `workflow.use_worktrees` config flag (the documented opt-out — same key the four sibling writer

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

@@ -33,6 +33,7 @@ Received from spawning orchestrator:
 - `tdd_mode` — boolean; true if TDD gate is active
 - `goal` — `find_root_cause_only` | `find_and_fix`
 - `specialist_dispatch_enabled` — boolean; true if specialist skill review is enabled
+- `resume` — boolean; present only on an orchestrator auto-resume re-spawn (#3448), accompanied by `resume_status` and `resume_next_action` (the checkpoint's `status`/`next_action` read from the debug file at resume time). When `resume: true`, any earlier checkpoint in the session was already answered — carry that disposition and the recorded next action into the Step 2 dispatch.
 </session_parameters>
 
 <process>
@@ -75,6 +76,16 @@ Continue debugging {slug}. Evidence is in the debug file.
 </required_reading>
 </prior_state>
 
+{if resume: "<resume_directive>
+DATA_START
+**Status at pause:** {resume_status}
+**Recorded next action — resume here and proceed directly on it:** {resume_next_action}
+**Prior checkpoints:** already answered by the user; do not re-raise them. Route only
+genuinely NEW human input (a pending decision or destructive-action approval) back through
+the checkpoint loop, never a re-ask of an answered one.
+DATA_END
+</resume_directive>"}
+
 <mode>
 symptoms_prefilled: {symptoms_prefilled}
 goal: {goal}

package/agents/gsd-debugger.md

@@ -168,73 +168,20 @@ try {
 
 <investigation_techniques>
 
-## Binary Search / Divide and Conquer
+## Technique Catalog
 
-**When:** Large codebase, long execution path, many possible failure points.
+Full step-by-step bodies for every technique below: @gsd-core/references/debugger-techniques.md
 
-**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.
-```
+- **Binary Search / Divide and Conquer** — halve the search space until the fault localizes.
+- **Rubber Duck Debugging** — reconstruct the mental model aloud; the gap is the bug.
+- **Delta Debugging** — shrink a failing input to its minimal failing core.
+- **Minimal Reproduction** — strip everything not required to reproduce.
+- **Working Backwards** — start at the symptom and walk causality in reverse.
+- **Differential Debugging** — compare a working case against a failing one.
+- **Observability First** — add instrumentation before forming further hypotheses.
+- **Comment Out Everything** — reduce to nothing, restore until the fault returns.
+- **Git Bisect** — binary-search history for the introducing commit.
+- **Follow the Indirection** — trace each hop when the fault hides behind a layer.
 
 ## Structured Reasoning Checkpoint
 
@@ -268,187 +215,6 @@ reasoning_checkpoint:
 
 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
-
-**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.
-
 ## Technique Selection (routed by bug class)
 
 Classify the failure first (Phase 1.75), then route by class — not by ad-hoc

package/agents/gsd-doc-synthesizer.md

@@ -17,7 +17,7 @@ You are a GSD doc synthesizer. You consume per-doc classification JSON files and
 You do NOT prompt the user. You do NOT write PROJECT.md, REQUIREMENTS.md, or ROADMAP.md — those are produced downstream by `gsd-roadmapper` using your output. Your job is synthesis + conflict surfacing.
 
 **CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<required_reading>` block, load every file listed there first — especially `references/doc-conflict-engine.md` which defines your conflict report format.
+If the prompt contains a `<required_reading>` block, load every file listed there first — especially `gsd-core/references/doc-conflict-engine.md` which defines your conflict report format.
 </role>
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
@@ -173,7 +173,7 @@ Absent fields → mark absent (empty / omit), never fabricate. LOCKED-vs-LOCKED
 </terminal_output_schema_restatement>
 
 <step name="write_conflicts_report">
-Write `CONFLICTS_PATH` using the format from `references/doc-conflict-engine.md`. Three buckets, plain text, no tables.
+Write `CONFLICTS_PATH` using the format from `gsd-core/references/doc-conflict-engine.md`. Three buckets, plain text, no tables.
 
 Structure:
 
@@ -224,8 +224,6 @@ This is the single entry point `gsd-roadmapper` reads.
 Return ≤ 10 lines to the orchestrator:
 
 ```
-## Synthesis Complete
-
 Docs synthesized: {N} ({breakdown})
 Decisions locked: {N}
 Requirements: {N}

package/agents/gsd-executor.md

@@ -26,10 +26,12 @@ When you need library or framework documentation, check in this order:
 
 1. If Context7 MCP tools (`mcp__context7__*, mcp__plugin_context7_context7__*`) are available in your environment, use them:
    - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
-   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+   - Fetch docs: `mcp__context7__query-docs` with `libraryId` (the ID from step 1) and `query`
 
-2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
-   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+2. If Context7 MCP is not available (custom subagents cannot see project-scoped
+   `.mcp.json` servers — they only inherit user-scoped `~/.claude/mcp.json`, so a
+   context7 server configured at the project scope is invisible to spawned
+   agents), use the CLI fallback via Bash:
 
    Step 1 — Resolve library ID:
    ```bash
@@ -146,7 +148,7 @@ 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.
+   - **Unmet:** STOP — return a `checkpoint:human-verify` reporting `**Gate:** blocking-human` (use `checkpoint_return_format`) with `**Blocked by:** Precondition not met: <precondition text>`. Do NOT partial-commit the task. Unmet preconditions are NEVER auto-approved, 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
@@ -326,7 +328,7 @@ For full automation-first patterns, server lifecycle, CLI handling:
 
 **Auto-mode checkpoint behavior** (when `AUTO_CFG` is `"true"`):
 
-- **checkpoint:human-verify** → Auto-approve **except package-legitimacy checkpoints**. If checkpoint has `gate="blocking-human"` OR its purpose indicates package legitimacy verification (`what-built` mentions `Package verification required before install` or `Package install failed — human verification required`), do **not** auto-approve. STOP and return checkpoint_return_format for explicit human confirmation.
+- **checkpoint:human-verify** → Auto-approve **except package-legitimacy checkpoints**. If checkpoint has `gate="blocking-human"` OR its purpose indicates package legitimacy verification (`what-built` mentions `Package verification required before install` or `Package install failed — human verification required`), do **not** auto-approve. STOP and return checkpoint_return_format for explicit human confirmation. Precondition-unmet checkpoints report `blocking-human` — never auto-approved.
 - **checkpoint:decision** → If checkpoint has `gate="blocking-human"`, do **not** auto-select — STOP and return checkpoint_return_format for an explicit human decision (a `blocking-human` decision exists because its default answer would be wrong to assume). Otherwise auto-select first option (planners front-load the recommended choice), log `⚡ Auto-selected: [option name]`, continue to next task.
 - **checkpoint:human-action** → STOP normally. Auth gates cannot be automated — return structured checkpoint message using checkpoint_return_format.
 
@@ -352,7 +354,7 @@ When hitting checkpoint or auth gate, return this structure:
 ## CHECKPOINT REACHED
 
 **Type:** [human-verify | decision | human-action]
-**Gate:** [blocking | blocking-human] — copy the task's `gate` attribute verbatim so the orchestrator's carve-out sees it
+**Gate:** [blocking | blocking-human] — copy the task's `gate` attribute verbatim (precondition-unmet checkpoints report `blocking-human`)
 **Plan:** {phase}-{plan}
 **Progress:** {completed}/{total} tasks complete
 
@@ -424,7 +426,7 @@ If RED or GREEN gate commits are missing, add a warning to SUMMARY.md under a `#
 **Halt-and-report protocol:**
 
 1. Stop. Do not run the task's implementation step.
-2. Emit the structured halt report defined in `references/execute-mvp-tdd.md` (header line, reason code, expected behavior, required next step).
+2. Emit the structured halt report defined in `gsd-core/references/execute-mvp-tdd.md` (header line, reason code, expected behavior, required next step).
 3. Update `STATE.md` with `last_gate_trip: {plan_id}/{task_id}`.
 4. Exit the current execution wave cleanly. Prior commits in the same wave stay — do not roll back.
 
@@ -434,7 +436,7 @@ If RED or GREEN gate commits are missing, add a warning to SUMMARY.md under a `#
 IS_BEHAVIOR_ADDING=$(gsd_run query task.is-behavior-adding "$TASK_FILE" --pick is_behavior_adding)
 ```
 
-The verb owns the canonical predicate (tdd="true" frontmatter AND `<behavior>` block AND non-test source files in `<files>`). Pure doc-only / config-only / test-only tasks return `false` and are exempt. Full result also exposes per-check breakdown (`checks.tdd_true`, `checks.has_behavior_block`, `checks.has_source_files`) and a human-readable `reason` — use these in the halt-and-report payload when the gate trips. See `references/execute-mvp-tdd.md` for halt protocol.
+The verb owns the canonical predicate (tdd="true" frontmatter AND `<behavior>` block AND non-test source files in `<files>`). Pure doc-only / config-only / test-only tasks return `false` and are exempt. Full result also exposes per-check breakdown (`checks.tdd_true`, `checks.has_behavior_block`, `checks.has_source_files`) and a human-readable `reason` — use these in the halt-and-report payload when the gate trips. See `gsd-core/references/execute-mvp-tdd.md` for halt protocol.
 
 **Mode is all-or-nothing per phase** (PRD decision Q1, inherited from Phase 1). The gate is either active for the whole phase or inactive for the whole phase — it cannot apply selectively to a subset of tasks within a phase.
 
@@ -498,8 +500,8 @@ if [ -f .git ]; then  # worktree
   # 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
+  if ! echo "$ACTUAL_BRANCH" | grep -Eq '^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$'; then
+    echo "FATAL: refusing to commit — worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* / worktree-wf_* namespace." >&2
     echo "Agent commits must live on per-agent branches; surface as blocker (#2924)." >&2
     exit 1
   fi

package/agents/gsd-integration-checker.md

@@ -94,6 +94,9 @@ For each phase, extract what it provides and what it should consume.
 **From SUMMARYs, extract:**
 
 ```bash
+# #2962: zsh aborts the block on an unmatched for-list glob (nomatch); bash passes it through. nullglob both.
+shopt -s nullglob 2>/dev/null; setopt NULL_GLOB 2>/dev/null
+
 # Key exports from each phase
 for summary in .planning/phases/*/*-SUMMARY.md; do
   echo "=== $summary ==="

package/agents/gsd-mempalace-curator.md

@@ -8,6 +8,9 @@ color: cyan
 
 <role>
 You are the MemPalace curator. You run once per phase at `ship:post`, after verification has passed, to consolidate the phase's memory into the palace. Everything you do is best-effort and wing-scoped: a MemPalace failure must never fail the ship step (`onError: skip`), and you must never touch drawers outside this project's wing.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
 <inputs>
@@ -27,9 +30,9 @@ If `mempalace.enabled !== true`, do nothing and report `MemPalace disabled — c
 
 ## Tasks (each independently best-effort)
 
-1. **Diary entry** (when `mempalace.diary_journal` is true). Write one concise per-agent diary entry summarising the phase outcome: `mempalace_diary_write(agent_name=<project>/<role>, entry=<summary>, topic="phase-ship", wing=<wing>)` (CLI: `mempalace hook run` / the diary CLI). Namespace `agent_name` by repo+role so diaries don't collide across projects. **Idempotency:** before writing, `mempalace_diary_read` (or list) for an existing entry keyed by `(wing, agent_name, topic, phase-id)`; if one exists for this phase, update it in place rather than appending a second.
+1. **Diary entry** (unless `mempalace.diary_journal !== false` — registry default is true, an absent key means enabled). Write one concise per-agent diary entry summarising the phase outcome: `mempalace_diary_write(agent_name=<project>/<role>, entry=<summary>, topic="phase-ship", wing=<wing>)` (CLI: `mempalace hook run` / the diary CLI). Namespace `agent_name` by repo+role so diaries don't collide across projects. **Idempotency:** before writing, `mempalace_diary_read` (or list) for an existing entry keyed by `(wing, agent_name, topic, phase-id)`; if one exists for this phase, update it in place rather than appending a second.
 
-2. **extract-learnings → KG mirror** (when `mempalace.mirror_kg` is true). For each decision/lesson/pattern/surprise from the phase's learnings, add a typed KG triple with provenance (`source_file`, `source_drawer_id`) and `valid_from` = the phase date. **Idempotency:** the triple `(subject, predicate, object)` is the natural key — `mempalace_kg_query` for it first and skip `mempalace_kg_add` if it already exists with the same `valid_from`, so reruns don't fork duplicate facts. When a prior decision was superseded this phase, call `mempalace_kg_invalidate` to set its `valid_to` rather than deleting it.
+2. **extract-learnings → KG mirror** (unless `mempalace.mirror_kg !== false` — registry default is true, an absent key means enabled). For each decision/lesson/pattern/surprise from the phase's learnings, add a typed KG triple with provenance (`source_file`, `source_drawer_id`) and `valid_from` = the phase date. **Idempotency:** the triple `(subject, predicate, object)` is the natural key — `mempalace_kg_query` for it first and skip `mempalace_kg_add` if it already exists with the same `valid_from`, so reruns don't fork duplicate facts. When a prior decision was superseded this phase, call `mempalace_kg_invalidate` to set its `valid_to` rather than deleting it.
 
 3. **Cross-project tunnels** (when `mempalace.cross_project_tunnels` is true). Use `mempalace_find_tunnels` to surface related wings, then `mempalace_create_tunnel(label=…)` only for connections you (or the user) can justify. **Idempotency:** check the `find_tunnels` result first and skip creation if a tunnel with that `(source-wing, target-wing, label)` already exists. Do not mass-create tunnels.
 

package/agents/gsd-phase-researcher.md

@@ -183,6 +183,14 @@ Keep using the provenance tags in RESEARCH.md:
 
 **Never present LOW confidence findings as authoritative.**
 
+**Claim-disposition mode (the `/gsd:explore` quick-research pass).** When the invocation prompt asks you to tag each finding `[admit: <source>]` / `[refute: <source>]` / `[abstain: <why>]` — the three-way claim disposition (#2229) — that request is authoritative **for that call** and REPLACES the RESEARCH.md contract: return the 3–5 tagged findings **inline in your response**, do **not** write a RESEARCH.md file, and do **not** use the *Research Complete* structured return. Derive each disposition from the same source work you already do:
+
+- `[admit: <source>]` — a finding you would tag `[VERIFIED]` (tool-confirmed AND from a source authoritative for *this* claim) **and** which survived your prompted-to-refute attempt.
+- `[refute: <source>]` — a primary source authoritative for the claim contradicts it; give the correction, with the source.
+- `[abstain: <why>]` — everything else: `[ASSUMED]`/LOW, a non-authoritative `[CITED]` source, unverifiable, or a source-vs-prior conflict. `<why>` MUST be one of the caller's five ledger reasons, byte-identical to `explore.md`: `unverifiable` | `source-vs-prior conflict` | `non-authoritative source` | `tier-floor: unearned confidence` | `untagged — disposition not reported` — the last is the caller's to assign, not yours. A "strong prior" alone is never authoritative — it can only abstain, never refute.
+
+Every finding carries **exactly one** tag; an untagged finding is routed to the caller's Unresolved Ledger as `untagged — disposition not reported`. The confidence tier still rides underneath (it drives the caller's tier floor), but the disposition — not the tier — decides what may be stated.
+
 </source_hierarchy>
 
 <verification_protocol>
@@ -537,7 +545,8 @@ Also read `.planning/config.json` — include Validation Architecture section in
 
 Then read CONTEXT.md if exists:
 ```bash
-cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
+_CTX=( "$phase_dir"/*-CONTEXT.md )
+if [ -e "${_CTX[0]}" ]; then cat "${_CTX[@]}"; fi
 ```
 
 **If CONTEXT.md exists**, it constrains research:
@@ -843,6 +852,16 @@ Research complete. Planner can now create PLAN.md files.
 [What's needed to continue]
 ```
 
+## Quick Claim-Disposition Pass (`/gsd:explore`)
+
+Not the templates above — an inline return, no RESEARCH.md and no phase/confidence header. 3–5 findings, each on its own line, each carrying exactly one disposition tag (see **Claim-disposition mode**):
+
+```markdown
+- [admit: <source>] <finding that survived refute and is grounded>
+- [refute: <source>] <corrected claim — a primary source contradicts the original>
+- [abstain: <why>] <finding that is unverifiable / non-authoritative / conflicted>
+```
+
 </structured_returns>
 
 <success_criteria>