@opengsd/gsd-core 1.3.1 → 1.4.0-rc.2

package/gsd-core/bin/lib/worktree-base-ref.cjs

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * Worktree base-ref detection and degradation logic (issue #683).
+ *
+ * Determines whether a worktree's HEAD has drifted from the fork base that the
+ * Claude Code harness would use to create a 'fresh' parallel worktree. When
+ * drift is detected the caller should fall back to sequential execution on the
+ * main working tree to avoid a base mismatch.
+ *
+ * Pure/testable module: all I/O is injectable via the `deps` argument so unit
+ * tests can run without touching the real filesystem or spawning real git.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shortSha = shortSha;
+exports.readBaseRefFromSettings = readBaseRefFromSettings;
+exports.applyWorktreeBaseRef = applyWorktreeBaseRef;
+exports.resolveEffectiveBaseRef = resolveEffectiveBaseRef;
+exports.cmdWorktreeBaseCheck = cmdWorktreeBaseCheck;
+exports.cmdWorktreeSetBaseRef = cmdWorktreeSetBaseRef;
+exports.evaluateWorktreeBaseDegrade = evaluateWorktreeBaseDegrade;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Strip JSONC comments (line and block forms) from a string to produce valid JSON.
+ * Handles comments inside strings correctly (does not strip them).
+ * Mirrors the same logic in bin/install.js:stripJsonComments.
+ */
+function stripJsonComments(text) {
+    let result = '';
+    let i = 0;
+    let inString = false;
+    let stringChar = '';
+    while (i < text.length) {
+        // Handle string literals — don't strip comments inside strings
+        if (inString) {
+            if (text[i] === '\\') {
+                result += text[i] + (text[i + 1] || '');
+                i += 2;
+                continue;
+            }
+            if (text[i] === stringChar) {
+                inString = false;
+            }
+            result += text[i];
+            i++;
+            continue;
+        }
+        // Start of string
+        if (text[i] === '"' || text[i] === "'") {
+            inString = true;
+            stringChar = text[i];
+            result += text[i];
+            i++;
+            continue;
+        }
+        // Line comment
+        if (text[i] === '/' && text[i + 1] === '/') {
+            // Skip to end of line
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            continue;
+        }
+        // Block comment
+        if (text[i] === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i += 2; // skip closing */
+            continue;
+        }
+        result += text[i];
+        i++;
+    }
+    // Remove trailing commas before } or ] (common in JSONC)
+    return result.replace(/,\s*([}\]])/g, '$1');
+}
+/**
+ * Parse a string as JSONC (JSON with comments). Returns the parsed value or
+ * throws a SyntaxError if the content is genuinely malformed.
+ */
+function parseJsonc(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return JSON.parse(stripJsonComments(text));
+    }
+}
+// ─── Message constants (verbatim — downstream docs/tests depend on these) ─────
+function buildMsgDiverged(headSha, forkRef, forkSha) {
+    return `⚠ Worktree base mismatch: HEAD (${shortSha(headSha)}) differs from ${forkRef} (${shortSha(forkSha)}). Running this phase sequentially on the main working tree. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
+}
+const MSG_UNKNOWN = `⚠ Cannot determine the worktree fork base (origin/HEAD unresolved). Running this phase sequentially on the main working tree to avoid a base mismatch. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
+// ─── Exports ──────────────────────────────────────────────────────────────────
+/**
+ * Returns the first 8 characters of a SHA, or '' if null/empty.
+ */
+function shortSha(sha) {
+    if (!sha)
+        return '';
+    return sha.slice(0, 8);
+}
+/**
+ * Extracts settings.worktree.baseRef if it is a string; otherwise null.
+ * Defensive: settings may be null/undefined, worktree may be missing or
+ * not an object.
+ */
+function readBaseRefFromSettings(settings) {
+    if (settings == null || typeof settings !== 'object')
+        return null;
+    const s = settings;
+    if (s.worktree == null || typeof s.worktree !== 'object' || Array.isArray(s.worktree))
+        return null;
+    const worktree = s.worktree;
+    if (typeof worktree.baseRef !== 'string')
+        return null;
+    return worktree.baseRef;
+}
+/**
+ * No-clobber application of worktree.baseRef = 'head'.
+ *
+ * - If baseRef is absent/null/undefined → set to 'head', return changed:true.
+ * - If already 'head' → skip, return skipped:'already-head'.
+ * - If any other string → skip without overwriting, return skipped:'explicit-other'.
+ *
+ * Mutates `settings` in place and also returns it.
+ */
+function applyWorktreeBaseRef(settings) {
+    // Defensive: caller must pass a plain object — reject null, arrays, and primitives.
+    if (settings === null || Array.isArray(settings) || typeof settings !== 'object') {
+        throw new TypeError(`applyWorktreeBaseRef: expected a plain object, got ${settings === null ? 'null' : Array.isArray(settings) ? 'array' : typeof settings}`);
+    }
+    // Ensure worktree object exists, preserving any existing keys
+    if (settings.worktree == null || typeof settings.worktree !== 'object' || Array.isArray(settings.worktree)) {
+        settings.worktree = {};
+    }
+    const worktree = settings.worktree;
+    const current = typeof worktree.baseRef === 'string' ? worktree.baseRef : null;
+    if (current === 'head') {
+        return { changed: false, settings, skipped: 'already-head', previous: 'head' };
+    }
+    if (current !== null) {
+        // Some other explicit string value — don't overwrite
+        return { changed: false, settings, skipped: 'explicit-other', previous: current };
+    }
+    // Absent/null/undefined → set to 'head'
+    worktree.baseRef = 'head';
+    return { changed: true, settings, skipped: null, previous: null };
+}
+/**
+ * Reads settings.local.json then settings.json under claudeDir, extracts
+ * worktree.baseRef from the first file that provides a non-null string value.
+ *
+ * deps.readFile(path) must return the file contents or null on any error.
+ */
+function resolveEffectiveBaseRef(claudeDir, deps) {
+    const readFile = deps?.readFile ?? ((p) => {
+        try {
+            return node_fs_1.default.readFileSync(p, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    });
+    const localPath = node_path_1.default.join(claudeDir, 'settings.local.json');
+    const sharedPath = node_path_1.default.join(claudeDir, 'settings.json');
+    function parseBaseRef(filePath) {
+        const contents = readFile(filePath);
+        if (contents == null)
+            return null;
+        try {
+            const parsed = parseJsonc(contents);
+            return readBaseRefFromSettings(parsed);
+        }
+        catch {
+            return null;
+        }
+    }
+    const localRef = parseBaseRef(localPath);
+    if (localRef !== null)
+        return localRef;
+    return parseBaseRef(sharedPath);
+}
+/**
+ * CLI command: check current worktree base-ref degradation status.
+ *
+ * Reads effective baseRef from <cwd>/.claude settings, runs degradation
+ * evaluation, writes JSON result to stdout (or injected write), and returns
+ * the result object.
+ */
+function cmdWorktreeBaseCheck(cwd, _args, deps) {
+    const claudeDir = node_path_1.default.join(cwd, '.claude');
+    const effectiveBaseRef = resolveEffectiveBaseRef(claudeDir, deps?.readFile ? { readFile: deps.readFile } : undefined);
+    const result = evaluateWorktreeBaseDegrade({
+        cwd,
+        effectiveBaseRef,
+        execGit: deps?.execGit,
+    });
+    const write = deps?.write ?? ((s) => process.stdout.write(s));
+    write(JSON.stringify(result, null, 2) + '\n');
+    return result;
+}
+/**
+ * CLI command: write worktree.baseRef = 'head' into <cwd>/.claude/settings.local.json.
+ *
+ * No-clobber: if the file already has an explicit baseRef that is not 'head',
+ * the existing value is preserved and output reflects skipped:'explicit-other'.
+ * If the file contains malformed JSON, throws a clear error rather than
+ * silently clobbering the user's file.
+ */
+function cmdWorktreeSetBaseRef(cwd, _args, deps) {
+    const file = node_path_1.default.join(cwd, '.claude', 'settings.local.json');
+    const readFile = deps?.readFile ??
+        ((p) => { try {
+            return node_fs_1.default.readFileSync(p, 'utf8');
+        }
+        catch {
+            return null;
+        } });
+    const raw = readFile(file);
+    let settings = {};
+    if (raw != null) {
+        let parsed;
+        try {
+            parsed = parseJsonc(raw);
+        }
+        catch {
+            throw new Error(`Refusing to modify ${file}: existing JSON is malformed`);
+        }
+        if (parsed === null || Array.isArray(parsed) || typeof parsed !== 'object') {
+            throw new Error(`Refusing to modify ${file}: expected a JSON object at the top level`);
+        }
+        settings = parsed;
+    }
+    const apply = applyWorktreeBaseRef(settings);
+    if (apply.changed) {
+        const dir = node_path_1.default.dirname(file);
+        const existsSync = deps?.existsSync ?? node_fs_1.default.existsSync;
+        const mkdirFn = deps?.mkdir ??
+            ((p, opts) => { node_fs_1.default.mkdirSync(p, opts); });
+        if (!existsSync(dir)) {
+            mkdirFn(dir, { recursive: true });
+        }
+        const writeFile = deps?.writeFile ??
+            ((p, content) => { node_fs_1.default.writeFileSync(p, content, 'utf8'); });
+        writeFile(file, JSON.stringify(settings, null, 2) + '\n');
+    }
+    const output = {
+        changed: apply.changed,
+        skipped: apply.skipped,
+        previous: apply.previous,
+        baseRef: 'head',
+        file,
+    };
+    const write = deps?.write ?? ((s) => process.stdout.write(s));
+    write(JSON.stringify(output, null, 2) + '\n');
+    return output;
+}
+/**
+ * Evaluates whether the current worktree HEAD has diverged from the fork base
+ * (origin/HEAD) that the Claude Code harness would use when creating a 'fresh'
+ * parallel worktree.
+ *
+ * Returns a structured result with shouldDegrade, reason, and a user-visible
+ * message when degradation is warranted.
+ */
+function evaluateWorktreeBaseDegrade(deps) {
+    const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
+    const cwd = deps?.cwd;
+    const cwdOpts = cwd ? { cwd } : {};
+    // a. If baseRef is explicitly 'head' the harness forks from HEAD — no mismatch possible.
+    // Claude Code's worktree.baseRef accepts only "fresh" (= origin/HEAD, the default) or "head".
+    // Therefore special-casing "head" here and otherwise comparing HEAD against origin/HEAD is
+    // complete: any non-"head" value (including "fresh" and absent/null) has fresh/origin-HEAD
+    // semantics and must be evaluated against origin/HEAD. (Reference: Claude Code worktrees docs, #683.)
+    if (deps?.effectiveBaseRef === 'head') {
+        return { shouldDegrade: false, reason: 'baseref-head', message: null, headSha: null, forkRef: null, forkSha: null };
+    }
+    // b. Resolve HEAD sha.
+    const headResult = execGit(['rev-parse', 'HEAD'], cwdOpts);
+    const headStdout = headResult.stdout ? headResult.stdout.trim() : '';
+    if (headResult.exitCode !== 0 || !headStdout) {
+        return { shouldDegrade: false, reason: 'no-head', message: null, headSha: null, forkRef: null, forkSha: null };
+    }
+    const headSha = headStdout;
+    // c. Resolve fork base (what the harness forks 'fresh' worktrees from = origin/HEAD).
+    let forkRef = null;
+    let forkSha = null;
+    // Try direct origin/HEAD rev-parse first.
+    const directResult = execGit(['rev-parse', '--verify', '--quiet', 'origin/HEAD'], cwdOpts);
+    const directStdout = directResult.stdout ? directResult.stdout.trim() : '';
+    if (directResult.exitCode === 0 && directStdout) {
+        forkRef = 'origin/HEAD';
+        forkSha = directStdout;
+    }
+    else {
+        // Fall back via symbolic-ref → refs/remotes/origin/HEAD
+        const symResult = execGit(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], cwdOpts);
+        const symStdout = symResult.stdout ? symResult.stdout.trim() : '';
+        if (symResult.exitCode === 0 && symStdout) {
+            const ref = symStdout;
+            const symShaResult = execGit(['rev-parse', '--verify', '--quiet', ref], cwdOpts);
+            const symShaStdout = symShaResult.stdout ? symShaResult.stdout.trim() : '';
+            if (symShaResult.exitCode === 0 && symShaStdout) {
+                // Strip leading 'refs/remotes/' to get e.g. 'origin/next'
+                forkRef = ref.replace(/^refs\/remotes\//, '');
+                forkSha = symShaStdout;
+            }
+        }
+    }
+    // d. Evaluate.
+    if (forkSha === null) {
+        return { shouldDegrade: true, reason: 'fork-ref-unknown', message: MSG_UNKNOWN, headSha, forkRef: null, forkSha: null };
+    }
+    if (forkSha === headSha) {
+        return { shouldDegrade: false, reason: 'head-matches-fork', message: null, headSha, forkRef, forkSha };
+    }
+    const message = buildMsgDiverged(headSha, forkRef, forkSha);
+    return { shouldDegrade: true, reason: 'head-diverged-from-fork', message, headSha, forkRef, forkSha };
+}

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -406,6 +406,12 @@ function defaultFindSummaryFiles(worktreePath) {
  *
  * For each *SUMMARY.md found under <worktreePath>/.planning/:
  *   - compute relative path from worktree root  → .planning/<id>-SUMMARY.md
+ *   - if the file is ALREADY COMMITTED on the worktree branch
+ *     (`git cat-file -e HEAD:<relPath>` returns exit 0), skip the copy entirely:
+ *     the merge will carry it naturally and copying it as an untracked file would
+ *     cause a "untracked working tree files would be overwritten by merge" collision.
+ *     On timeout or fatal exit (128) the rescue is also skipped (fail-closed).
+ *     (#706 — execute-phase committed-SUMMARY contract)
  *   - destination = <repoRoot>/<relPath>
  *   - copy when dest is absent or content differs
  *
@@ -419,6 +425,7 @@ function defaultFindSummaryFiles(worktreePath) {
  *     failure — it sets needsCopy=true and the copy is attempted normally.
  */
 function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
+    const execGit = deps.execGit || execGitDefault;
     const findSummaryFiles = deps.findSummaryFiles || defaultFindSummaryFiles;
     const existsSync = deps.existsSync || node_fs_1.default.existsSync;
     const readFileSync = deps.readFileSync || ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
@@ -432,6 +439,30 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
         // Normalize to forward slashes so the Set comparison against `git status --porcelain`
         // output works on Windows too (git always emits forward slashes in porcelain output).
         const relPath = absPath.slice(worktreePath.length).replace(/^[/\\]/, '').replace(/\\/g, '/');
+        // #706: skip rescue when the SUMMARY is already committed on the branch.
+        // Use `git cat-file -e HEAD:<relPath>` (not `ls-files --error-unmatch`) so
+        // the check is against the committed tree, not the index.  ls-files also
+        // matches staged-but-uncommitted files, which would skip rescue when the
+        // file is staged but not yet committed — the merge wouldn't carry it, and
+        // the executor's content could be lost.  cat-file -e HEAD:<path> returns
+        // exit 0 only when the object exists in the committed HEAD tree.
+        //
+        // Fail-closed on timeout/fatal git errors: if we cannot determine whether
+        // the file is committed, do NOT rescue it (rescuing an actually-committed
+        // file would re-create the untracked collision; the merge will surface the
+        // issue).  The cleanup will be blocked by merge_failed in the worst case,
+        // which is the observable behaviour before this fix and is recoverable.
+        const catFileResult = execGit(['-C', worktreePath, 'cat-file', '-e', `HEAD:${relPath}`], { cwd: repoRoot });
+        if (catFileResult.exitCode !== 1) {
+            // Rescue only when cat-file definitively reports the object is absent (exit 1).
+            //   exit 0  → object exists (committed on HEAD) — merge will carry it, skip.
+            //   exit 128 → fatal git error (corrupt store, unborn HEAD, etc.) — uncertain,
+            //              fail-closed: do NOT rescue to avoid recreating the #706 collision.
+            //   timedOut / null / other → unreliable result — same fail-closed policy.
+            // In all non-1 cases the merge will either succeed naturally (0) or surface
+            // the problem safely (128/timeout), which is the recoverable pre-fix behaviour.
+            continue;
+        }
         const dest = node_path_1.default.join(repoRoot, relPath);
         let needsCopy = !existsSync(dest);
         if (!needsCopy) {

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

@@ -106,7 +106,8 @@
     "model_policy.budget",
     "model_policy.high",
     "model_policy.medium",
-    "model_policy.low"
+    "model_policy.low",
+    "agent_skills_security.trusted_global_roots"
   ],
   "runtimeStateKeys": [
     "workflow._auto_chain_active"

package/gsd-core/bin/verify-reapply-patches.cjs

@@ -32,6 +32,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 
 const SIGNIFICANT_MIN_CHARS = 12;
 const GSD_HOOK_VERSION_LINE_RE = /^(?:\/\/|#)\s*gsd-hook-version:\s*\S+\s*$/i;
@@ -48,10 +49,9 @@ function parseArgs(argv) {
       process.stdout.write(
         'usage: verify-reapply-patches.cjs --patches-dir <path> --config-dir <path> [--pristine-dir <path>] [--json]\n',
       );
-      process.exit(0);
+      throw new ExitError(0);
     } else {
-      process.stderr.write(`unknown argument: ${arg}\n`);
-      process.exit(2);
+      throw new ExitError(2, `unknown argument: ${arg}`);
     }
   }
   return opts;
@@ -281,16 +281,13 @@ function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashe
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (!opts.patchesDir || !opts.configDir) {
-    process.stderr.write('--patches-dir and --config-dir are required\n');
-    process.exit(2);
+    throw new ExitError(2, '--patches-dir and --config-dir are required');
   }
   if (!fs.existsSync(opts.patchesDir)) {
-    process.stderr.write(`patches dir not found: ${opts.patchesDir}\n`);
-    process.exit(2);
+    throw new ExitError(2, `patches dir not found: ${opts.patchesDir}`);
   }
   if (!fs.existsSync(opts.configDir)) {
-    process.stderr.write(`config dir not found: ${opts.configDir}\n`);
-    process.exit(2);
+    throw new ExitError(2, `config dir not found: ${opts.configDir}`);
   }
 
   const files = walk(opts.patchesDir).filter((f) => !f.endsWith('backup-meta.json'));
@@ -342,11 +339,11 @@ function main() {
     }
   }
 
-  process.exit(failures.length > 0 ? 1 : 0);
+  return failures.length > 0 ? 1 : 0;
 }
 
 if (require.main === module) {
-  main();
+  runMain(main);
 }
 
 module.exports = { computeUserAddedLines, isSignificantLine, verifyFile, walk, REASON, readPristineHashes, sha256 };

package/gsd-core/references/planner-load-graph-context.md

@@ -0,0 +1,36 @@
+# Planner — Load Graph Context
+
+> Loaded by `gsd-planner` at the `load_graph_context` step.
+
+Check for knowledge graph:
+
+```bash
+ls .planning/graphs/graph.json 2>/dev/null
+```
+
+If graph.json exists, check freshness:
+
+```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 command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/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
+gsd_run graphify status
+```
+
+If the status response has `stale: true`, note for later: "Graph is {age_hours}h old -- treat semantic relationships as approximate." Include this annotation inline with any graph context injected below.
+
+Query the graph for phase-relevant dependency context (single query per D-06):
+
+```bash
+gsd_run graphify query "<phase-goal-keyword>" --budget 2000
+```
+
+Use the keyword that best captures the phase goal. Examples:
+- Phase "User Authentication" -> query term "auth"
+- Phase "Payment Integration" -> query term "payment"
+- Phase "Database Migration" -> query term "migration"
+
+If the query returns nodes and edges, incorporate as dependency context for planning:
+- Which modules/files are semantically related to this phase's domain
+- Which subsystems may be affected by changes in this phase
+- Cross-document relationships that inform task ordering and wave structure
+
+If no results or graph.json absent, continue without graph context.

package/gsd-core/references/planning-config.md

@@ -34,7 +34,7 @@ Configuration options for `.planning/` directory behavior.
 | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
-| `workflow.use_worktrees` | `true` | Whether executor agents run in isolated git worktrees. Set to `false` to disable worktrees — agents execute sequentially on the main working tree instead. Recommended for solo developers or when worktree merges cause issues. |
+| `workflow.use_worktrees` | `true` | Whether executor agents run in isolated git worktrees. Set to `false` to disable worktrees — agents execute sequentially on the main working tree instead. Recommended for solo developers or when worktree merges cause issues. Note: if your branch is ahead of `origin/HEAD` (a diverged milestone or feature branch), GSD auto-degrades to sequential and prints a warning; set `worktree.baseRef:"head"` in `.claude/settings.local.json` to restore parallel execution. See the branch-divergence note below. |
 | `workflow.subagent_timeout` | `300000` | Timeout in milliseconds for parallel subagent tasks (e.g. codebase mapping). Increase for large codebases or slower models. Default: 300000 (5 minutes). |
 | `workflow.inline_plan_threshold` | `2` | Plans with this many tasks or fewer execute inline (Pattern C) instead of spawning a subagent. Avoids ~14K token spawn overhead for small plans. Set to `0` to always spawn subagents. |
 | `manager.flags.discuss` | `""` | Flags passed to `/gsd:discuss-phase` when dispatched from manager (e.g. `"--auto --analyze"`) |
@@ -385,6 +385,8 @@ Several config fields affect each other or trigger special behavior:
 
 8. **`sub_repos` auto-sync** -- On every config load, GSD scans for child directories with `.git` and updates the `sub_repos` array if the filesystem has changed. Legacy `multiRepo: true` is automatically migrated to a detected `sub_repos` array.
 
+9. **`workflow.use_worktrees` and branch divergence** -- When `use_worktrees` is `true` (default), executor worktrees are forked from `origin/HEAD` by the Claude Code harness. If your current branch has commits that `origin/HEAD` does not (for example an unmerged milestone or feature branch), GSD automatically degrades to sequential execution for that run and prints a one-line `⚠ Worktree base mismatch` warning. To restore parallel execution permanently, set `worktree.baseRef:"head"` in `.claude/settings.local.json` (run `node gsd-tools.cjs worktree set-baseref`). This makes the harness fork worktrees from the live HEAD instead of `origin/HEAD`. Both fresh installs and upgrades of GSD Core set this automatically (no-clobber) when `use_worktrees` is enabled; you can also run the command manually at any time. Setting `workflow.use_worktrees: false` is the alternative if worktrees are not needed at all.
+
 ---
 
 ## Example Configurations

package/gsd-core/references/research-documentation-lookup.md

@@ -0,0 +1,29 @@
+When you need library or framework documentation, check in this order:
+
+1. If Context7 MCP tools (`mcp__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`
+
+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:
+
+   Step 1 — Resolve library ID:
+   ```bash
+   if command -v ctx7 &>/dev/null; then
+     ctx7 library <name> "<query>"
+   else
+     echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
+   fi
+   ```
+   Step 2 — Fetch documentation:
+   ```bash
+   if command -v ctx7 &>/dev/null; then
+     ctx7 docs <libraryId> "<query>"
+   else
+     echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
+   fi
+   ```
+
+Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
+works via Bash and produces equivalent output. Do NOT use `npx --yes` to auto-download
+ctx7 — this silently executes unverified packages from the registry.

package/gsd-core/references/research-philosophy.md

@@ -0,0 +1,29 @@
+## Claude's Training as Hypothesis
+
+Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
+
+**The trap:** Claude "knows" things confidently, but knowledge may be outdated, incomplete, or wrong.
+
+**The discipline:**
+1. **Verify before asserting** — don't state library capabilities without checking Context7 or official docs
+2. **Date your knowledge** — "As of my training" is a warning flag
+3. **Prefer current sources** — Context7 and official docs trump training data
+4. **Flag uncertainty** — LOW confidence when only training data supports a claim
+
+## Honest Reporting
+
+Research value comes from accuracy, not completeness theater.
+
+**Report honestly:**
+- "I couldn't find X" is valuable (now we know to investigate differently)
+- "This is LOW confidence" is valuable (flags for validation)
+- "Sources contradict" is valuable (surfaces real ambiguity)
+
+**Avoid:** Padding findings, stating unverified claims as facts, hiding uncertainty behind confident language.
+
+## Research is Investigation, Not Confirmation
+
+**Bad research:** Start with hypothesis, find evidence to support it
+**Good research:** Gather evidence, form conclusions from evidence
+
+When researching "best library for X": find what the ecosystem actually uses, document tradeoffs honestly, let evidence drive recommendation.

package/gsd-core/references/research-verification-protocol.md

@@ -0,0 +1,27 @@
+## Known Pitfalls
+
+### Configuration Scope Blindness
+**Trap:** Assuming global configuration means no project-scoping exists
+**Prevention:** Verify ALL configuration scopes (global, project, local, workspace)
+
+### Deprecated Features
+**Trap:** Finding old documentation and concluding feature doesn't exist
+**Prevention:** Check current official docs, review changelog, verify version numbers and dates
+
+### Negative Claims Without Evidence
+**Trap:** Making definitive "X is not possible" statements without official verification
+**Prevention:** For any negative claim — is it verified by official docs? Have you checked recent updates? Are you confusing "didn't find it" with "doesn't exist"?
+
+### Single Source Reliance
+**Trap:** Relying on a single source for critical claims
+**Prevention:** Require multiple sources: official docs (primary), release notes (currency), additional source (verification)
+
+## Pre-Submission Checklist
+
+- [ ] All research domains in this agent's scope investigated (e.g. stack, features, architecture, patterns, pitfalls — whichever apply)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources cross-referenced for critical claims
+- [ ] URLs provided for authoritative sources
+- [ ] Publication dates checked (prefer recent/current)
+- [ ] Confidence levels assigned honestly
+- [ ] "What might I have missed?" review completed

package/gsd-core/workflows/execute-phase.md

@@ -92,6 +92,16 @@ if [ "$RUNTIME" = "codex" ] && [ "$USE_WORKTREES" != "false" ]; then
 fi
 # Sweep orphaned locked worktrees from prior crashed sessions before spawning executors (#3707).
 [ "$USE_WORKTREES" != "false" ] && gsd_run query worktree.reap-orphans 2>/dev/null || true
+# Auto-degrade to sequential if HEAD has diverged from the worktree fork base (#683).
+# Only applies to Claude Code (isolation="worktree" is Claude-Code-specific).
+if [ "$RUNTIME" = "claude" ] && [ "$USE_WORKTREES" != "false" ]; then
+  _SHOULD_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
+  if [ "$_SHOULD_DEGRADE" = "true" ]; then
+    _DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
+    [ -n "$_DEGRADE_MSG" ] && printf '%s\n' "$_DEGRADE_MSG" >&2
+    USE_WORKTREES=false
+  fi
+fi
 ```
 Codex maps subagents to `spawn_agent`, which has no direct Codex mapping for Claude Code's `isolation="worktree"` parameter. Failing closed prevents main-checkout edits while the workflow believes agents are isolated.
 
@@ -111,6 +121,8 @@ fi
 
 When `USE_WORKTREES` (project-level) is `false`, all executor agents run without `isolation="worktree"` — they execute sequentially on the main working tree instead of in parallel worktrees. The per-plan decision below has no effect when worktrees are project-disabled.
 
+`USE_WORKTREES` is also automatically set to `false` for the duration of a run when `worktree base-check` detects that the orchestrator HEAD has diverged from the worktree fork base (the #683 condition — e.g. an unmerged milestone or feature branch). This check runs only when `RUNTIME=claude` because `isolation="worktree"` is a Claude Code-specific feature; other runtimes do not use it. The auto-degrade prints a one-line warning to stderr and falls through to the sequential path so executors do not hit the exit-42 worktree-branch-check halt. To restore parallel worktree execution, set `worktree.baseRef:"head"` in `.claude/settings.local.json` (or run `gsd-tools worktree set-baseref`) — this makes the fork base track the live HEAD instead of a fixed remote ref. The `worktree-branch-check` exit-42 guard inside each executor remains in place as a backstop.
+
 Read context window size for adaptive prompt enrichment:
 
 ```bash
@@ -188,7 +200,7 @@ if [ "$MVP_MODE" = "true" ] && [ "$TDD_MODE" = "true" ]; then
   fi
 fi
 ```
-Pure doc-only / config-only / test-only tasks return `is_behavior_adding=false` and are exempt. See `execute-mvp-tdd.md` for the halt report format.
+Pure doc-only / config-only / test-only tasks return `is_behavior_adding=false` and are exempt. When the gate trips, Read `~/.claude/gsd-core/references/execute-mvp-tdd.md` for the exact halt report format.
 </step>
 
 <step name="check_blocking_antipatterns" priority="first">
@@ -1413,16 +1425,15 @@ ${VERIFIER_SKILLS}",
 
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-Read status:
+Read status via the canonical query (scoped to frontmatter, covers missing/unknown cases):
 ```bash
-grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
+VERIFICATION=$(gsd_run query verification.status "$PHASE_DIR" 2>/dev/null)
+STATUS=$(printf '%s' "$VERIFICATION" | jq -r '.status' 2>/dev/null || echo "")
+NEXT_ACTION=$(printf '%s' "$VERIFICATION" | jq -r '.next_action' 2>/dev/null || echo "")
+NEXT_COMMAND=$(printf '%s' "$VERIFICATION" | jq -r '.next_command' 2>/dev/null || echo "")
 ```
 
-| Status | Action |
-|--------|--------|
-| `passed` | → update_roadmap |
-| `human_needed` | Persist and present human testing items; keep phase pending until verification reruns as `passed` |
-| `gaps_found` | Present gap summary, offer `/gsd:plan-phase {phase} --gaps ${GSD_WS}` |
+Route on `$STATUS`: if `passed`, proceed to update_roadmap. Otherwise keep the phase pending — present `$NEXT_ACTION` to the user and, when `$NEXT_COMMAND` is non-empty, show it as the next command to run. The query covers all cases including missing files (`missing`) and unexpected values (`unknown`), so no per-status arm needs to be listed here.
 
 **If human_needed:**