@opengsd/gsd-core 1.5.0-rc.4 → 1.5.0

package/gsd-core/bin/lib/verify.cjs

@@ -14,8 +14,6 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const validate_cjs_1 = require("./validate.cjs");
 const validate_cjs_2 = require("./validate.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports -- core.cjs is an export= CommonJS module
-const core = require("./core.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
@@ -31,7 +29,27 @@ const package_identity_cjs_1 = require("./package-identity.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const schema_detect_cjs_1 = require("./schema-detect.cjs");
 const artifacts_cjs_1 = require("./artifacts.cjs");
-const { loadConfig, normalizePhaseName, phaseTokenMatches, escapeRegex, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, output, error, checkAgentsInstalled, CONFIG_DEFAULTS, inspectWorktreeHealth, } = core;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- agent-install-check.cjs is an export= CommonJS module
+const agentInstallCheck = require("./agent-install-check.cjs");
+const { checkAgentsInstalled } = agentInstallCheck;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output, error } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderMod = require("./config-loader.cjs");
+const { loadConfig, CONFIG_DEFAULTS } = configLoaderMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorMod = require("./phase-locator.cjs");
+const { findPhaseInternal } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParserMod = require("./roadmap-parser.cjs");
+const { getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone } = roadmapParserMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const worktreeSafetyMod = require("./worktree-safety.cjs");
+const { inspectWorktreeHealth } = worktreeSafetyMod;
 const { planningDir } = planningWorkspace;
 const { extractFrontmatter, parseMustHavesBlock } = frontmatterMod;
 const { writeStateMd } = stateMod;
@@ -215,6 +233,293 @@ function scanNegativeGrepCommentEcho(content) {
     }
     return { errors, warnings };
 }
+/**
+ * Issue #968 — file-wide negative-grep sibling conflict detector.
+ * A file-wide negative grep gate (! grep -Eq 'PAT' FILE or grep -c 'PAT' FILE == 0)
+ * bans a construct across the WHOLE file. When a sibling task in the same plan
+ * legitimately requires the same construct in the same file, the two gates are
+ * mutually unsatisfiable. This is a WARN-only check (never changes valid:false).
+ */
+function scanFileWideNegativeGateConflict(content) {
+    const warnings = [];
+    // Normalize newlines; join backslash line-continuations (same as #429).
+    const text = (content || '')
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .replace(/\\\n/g, ' ');
+    // Allowlisted patterns: <!-- planner-region-allow: PAT -->
+    const allow = new Set();
+    const allowRe = /<!--\s*planner-region-allow:\s*(.+?)\s*-->/g;
+    let am;
+    while ((am = allowRe.exec(text)) !== null)
+        allow.add(am[1]);
+    // Helper predicates (reused from #429 style).
+    // Zero-equality comparison: spaced == 0 or -eq 0.
+    const zeroCmp = (s) => /\s==?\s*0\b/.test(s) || /-eq\s+0\b/.test(s) || /\bequals\s+0\b/.test(s);
+    // grep options include -c / --count
+    const optsHaveCount = (opts) => /(?:^|\s)-[A-Za-z]*c[A-Za-z]*(?=\s|$)/.test(opts) || /--count\b/.test(opts);
+    // grep options include -v / --invert-match (inverted count is NOT a negative gate)
+    const optsHaveInvert = (opts) => /(?:^|\s)-[A-Za-z]*v[A-Za-z]*(?=\s|$)/.test(opts) || /--invert-match\b/.test(opts);
+    // A bareword that is a plausible grep pattern (not a stray flag/number).
+    const plausibleBare = (s) => /[A-Za-z0-9_]/.test(s) && !/^[-=!<>0-9]+$/.test(s);
+    // Regex to extract grep arguments: opts run then PAT (quoted or bare).
+    const grepArgRe = /grep((?:\s+-{1,2}[A-Za-z][A-Za-z-]*)+)\s+(?:'([^']*)'|"([^"]*)"|([^\s'"|>&;$()\[\]]+))/g;
+    // FIX 1 (ReDoS): Linear-time "does reqText satisfy the grep pattern" — no RegExp execution.
+    // Never calls new RegExp, so no catastrophic backtracking is possible.
+    //
+    // Handles literal patterns and `.`/`.*/`.+`/`\s`-style wildcard gaps and `^`/`$` anchors.
+    // Patterns using character classes (`[…]`), alternation (`a|b`), or other regex constructs
+    // fall back to a conservative literal-substring check, so the detector may NOT warn on those
+    // (false-negative is the safe direction for a warn-only advisory).
+    const patternRequiredIn = (pat, reqText) => {
+        const hay = (reqText || '').slice(0, 8000); // bound the haystack
+        if (!pat)
+            return false;
+        // Strip ERE anchors — position constraints don't change whether the construct is required.
+        pat = pat.replace(/^\^/, '').replace(/\$$/, '');
+        if (!pat)
+            return false;
+        // Pure literal (no regex metacharacters): direct substring.
+        if (!/[.*+?^${}()|[\]\\]/.test(pat))
+            return hay.includes(pat);
+        const SENT = ' ';
+        // Replace simple wildcard gaps (\s* \w+ .* .+ .? bare .) with a sentinel.
+        let work = pat
+            .replace(/\\[sSwWdD][*+?]?/g, SENT)
+            .replace(/\.[*+?]/g, SENT)
+            .replace(/\./g, SENT);
+        work = work.replace(/\\(.)/g, '$1'); // de-escape \( \. etc → literal char
+        const joined = work.split(SENT).join('');
+        // Unhandled regex constructs remain → safe literal-substring fallback on the raw pattern.
+        if (/[*+?^${}()|[\]]/.test(joined))
+            return hay.includes(pat);
+        const frags = work.split(SENT).filter(Boolean);
+        if (!frags.length)
+            return false; // all-wildcard pattern → no meaningful requirement
+        let pos = 0;
+        for (const f of frags) {
+            const idx = hay.indexOf(f, pos);
+            if (idx === -1)
+                return false;
+            pos = idx + f.length;
+        }
+        return true;
+    };
+    // FIX 2 (file basename over-match): exact normalized match; basename fallback ONLY for
+    // unqualified gate files (no path separator).
+    const normPath = (p) => p.replace(/^\.\//, '').trim();
+    // File-wide discriminator: a token AFTER PAT that looks like a path.
+    // Paths have /, a file extension, or match a known task <files> entry.
+    // Globs (containing *) are excluded (unresolvable — no warn).
+    const looksLikePath = (token) => !token.includes('*') &&
+        (token.includes('/') || /\.[a-zA-Z]{1,6}$/.test(token));
+    // FIX 5 (hasLeadingNot): collapse to one command-boundary-anchored regex.
+    // Negation at a command boundary: start of segment, or after ; & | ( newline / then / do.
+    // FIX 4 (isRegionScoped tightened): return true ONLY when grep is downstream of a
+    // sed line-range or awk range producer. Other pipe sources (cat, tac, etc.) are file-wide.
+    const isRegionScoped = (seg) => {
+        if (!seg.includes('|'))
+            return false;
+        const before = seg.slice(0, seg.lastIndexOf('|'));
+        // sed -n line/range extraction, e.g. sed -n '12,40p' FILE  or  sed -n '/a/,/b/p' FILE
+        if (/\bsed\s+-n\b/.test(before))
+            return true;
+        // awk range pattern, e.g. awk '/start/,/end/' FILE
+        if (/\bawk\b[^|]*\/[^/]*\/\s*,\s*\/[^/]*\//.test(before))
+            return true;
+        return false;
+    };
+    const taskRe = /<task[^>]*>([\s\S]*?)<\/task>/g;
+    const tasks = [];
+    let tm;
+    while ((tm = taskRe.exec(text)) !== null) {
+        const tc = tm[1];
+        // Extract task name.
+        const namem = tc.match(/<name>([\s\S]*?)<\/name>/);
+        const name = namem ? namem[1].trim() : 'unnamed';
+        // Extract <files> entries.
+        const filesm = tc.match(/<files>([\s\S]*?)<\/files>/);
+        const filesText = filesm ? filesm[1] : '';
+        const files = filesText.split(/[,\s]+/).map(s => s.trim()).filter(Boolean);
+        // Gate text: <verify>/<automated>/<acceptance_criteria>.
+        const gateFragments = [];
+        for (const tag of ['verify', 'automated', 'acceptance_criteria']) {
+            const re = new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'g');
+            let mm;
+            while ((mm = re.exec(tc)) !== null)
+                gateFragments.push(mm[1]);
+        }
+        // Requirement text: <action>/<acceptance_criteria>.
+        const reqFragments = [];
+        for (const tag of ['action', 'acceptance_criteria']) {
+            const re = new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'g');
+            let mm;
+            while ((mm = re.exec(tc)) !== null)
+                reqFragments.push(mm[1]);
+        }
+        // Strip XML tags from gate text so segments containing embedded
+        // XML closing tags (e.g. <automated>cmd</automated> nested inside <verify>)
+        // don't bleed into the file-path token extraction.
+        const rawGateText = gateFragments.join('\n');
+        const gateText = rawGateText.replace(/<[^>]+>/g, ' ');
+        tasks.push({
+            name,
+            files,
+            gateText,
+            reqText: reqFragments.join('\n'),
+        });
+    }
+    if (tasks.length < 2)
+        return { warnings, valid: true };
+    // FIX 3 (extensionless known files): build a normalized set of ALL tasks' <files> entries
+    // so that extensionless filenames like Dockerfile are also recognized as valid file tokens.
+    const knownFiles = new Set();
+    for (const t of tasks) {
+        for (const f of t.files)
+            knownFiles.add(normPath(f));
+    }
+    // Extended looksLikePath: accepts known <files> entries even without an extension.
+    const isFileLike = (token) => {
+        if (token.includes('*'))
+            return false; // exclude globs
+        if (looksLikePath(token))
+            return true;
+        return knownFiles.has(normPath(token));
+    };
+    // Dedup key: (taskAIdx, taskBIdx, pat, file)
+    const seen = new Set();
+    // For each task A, scan gate text for file-wide negative grep bans.
+    for (let ai = 0; ai < tasks.length; ai++) {
+        const taskA = tasks[ai];
+        // Split gate text into shell segments (split on && / || within lines).
+        const segments = taskA.gateText.split('\n').flatMap(line => line.split(/\s*(?:&&|\|\|)\s*/));
+        for (const seg of segments) {
+            if (!/grep/.test(seg))
+                continue;
+            // FIX 5: Negation at a command boundary: start of segment, or after ; & | ( newline / then / do.
+            // Also handles ! negating an entire pipeline (e.g. ! cat FILE | grep ...).
+            const hasLeadingNot = 
+            // Direct ! grep: negation immediately before grep keyword
+            /(?:^|[\n;&|(]|\bthen\b|\bdo\b)\s*!\s*grep/.test(seg) ||
+                // Pipeline negation: ! at command boundary, grep appears in pipeline after |
+                (/(?:^|[\n;&|(]|\bthen\b|\bdo\b)\s*!\s*\w/.test(seg) && /\|\s*grep\b/.test(seg));
+            const hasCountZero = zeroCmp(seg);
+            // Extract grep invocation and check for count.
+            grepArgRe.lastIndex = 0;
+            let pat = null;
+            let file = null;
+            let isBan = false;
+            // FIX 4 helper: given a segment and the grep match end position, find the
+            // file argument. First try the token immediately after PAT; if none qualifies,
+            // try a cat/tac producer or < FILE redirect from the full segment.
+            const resolveFileArg = (segment, afterPatStr) => {
+                // Primary: token immediately after PAT in the grep command
+                const fileM = afterPatStr.match(/^\s+([^\s'"|>&;$()\[\]]+)/);
+                const rawFile = fileM ? fileM[1] : null;
+                if (rawFile && isFileLike(rawFile))
+                    return rawFile;
+                // FIX 4: For NON-region segments, also look for cat/tac producer or < FILE redirect
+                const catM = segment.match(/\b(?:cat|tac)\s+([^\s'"|>&;()]+)/);
+                if (catM && isFileLike(catM[1]))
+                    return catM[1];
+                const redirM = segment.match(/<\s*([^\s'"|>&;()]+)/);
+                if (redirM && isFileLike(redirM[1]))
+                    return redirM[1];
+                return null;
+            };
+            // If leading !, it might be a count or a direct !grep
+            if (hasLeadingNot && !hasCountZero) {
+                // Direct ! grep PAT FILE form: grep opts PAT FILE
+                // Extract PAT and FILE from the grep invocation
+                grepArgRe.lastIndex = 0;
+                let gm;
+                while ((gm = grepArgRe.exec(seg)) !== null) {
+                    const opts = gm[1];
+                    if (optsHaveInvert(opts))
+                        continue; // -v form: not a ban
+                    // PAT
+                    const rawPat = gm[2] !== undefined ? gm[2] :
+                        gm[3] !== undefined ? gm[3] :
+                            gm[4] !== undefined && plausibleBare(gm[4]) ? gm[4] : null;
+                    if (!rawPat)
+                        continue;
+                    // FILE: next non-option token after PAT (or cat/tac/redirect in segment)
+                    const afterPat = seg.slice((gm.index || 0) + gm[0].length);
+                    const rawFile = resolveFileArg(seg, afterPat);
+                    if (rawFile) {
+                        pat = rawPat;
+                        file = rawFile;
+                        isBan = true;
+                    }
+                }
+            }
+            if (!isBan && hasCountZero) {
+                // count grep form: grep -c PAT FILE == 0 or [ $(grep -c PAT FILE) -eq 0 ]
+                grepArgRe.lastIndex = 0;
+                let gm;
+                while ((gm = grepArgRe.exec(seg)) !== null) {
+                    const opts = gm[1];
+                    if (!optsHaveCount(opts) || optsHaveInvert(opts))
+                        continue;
+                    const rawPat = gm[2] !== undefined ? gm[2] :
+                        gm[3] !== undefined ? gm[3] :
+                            gm[4] !== undefined && plausibleBare(gm[4]) ? gm[4] : null;
+                    if (!rawPat)
+                        continue;
+                    const afterPat = seg.slice((gm.index || 0) + gm[0].length);
+                    const rawFile = resolveFileArg(seg, afterPat);
+                    if (rawFile) {
+                        pat = rawPat;
+                        file = rawFile;
+                        isBan = true;
+                    }
+                }
+            }
+            if (!isBan || !pat || !file)
+                continue;
+            if (allow.has(pat))
+                continue;
+            // Skip if region-scoped (grep downstream of a sed/awk pipe — region extracted)
+            if (isRegionScoped(seg))
+                continue;
+            // For each other task B: check if B's <files> includes FILE AND B's reqText contains PAT
+            for (let bi = 0; bi < tasks.length; bi++) {
+                if (bi === ai)
+                    continue;
+                const taskB = tasks[bi];
+                // FIX 2: Exact normalized match; basename fallback ONLY for unqualified gate files.
+                const gateFile = normPath(file);
+                const bMatchesFile = taskB.files.some((bf) => {
+                    const nbf = normPath(bf);
+                    if (nbf === gateFile)
+                        return true;
+                    // basename fallback only when the gate file is an unqualified bare filename (no dir separator)
+                    if (!gateFile.includes('/') && node_path_1.default.basename(nbf) === gateFile)
+                        return true;
+                    return false;
+                });
+                if (!bMatchesFile)
+                    continue;
+                // FIX 1: Use linear-time patternRequiredIn instead of new RegExp (ReDoS-safe).
+                const bRequiresPat = patternRequiredIn(pat, taskB.reqText);
+                if (!bRequiresPat)
+                    continue;
+                const dedupeKey = `${ai}:${bi}:${pat}:${file}`;
+                if (seen.has(dedupeKey))
+                    continue;
+                seen.add(dedupeKey);
+                warnings.push(`Region-scope conflict (#968): task "${taskA.name}" negative-greps "${pat}" file-wide on ${file}, ` +
+                    `but sibling task "${taskB.name}" requires it in the same file. ` +
+                    `A file-wide ban is unsatisfiable when a sibling needs the construct elsewhere — ` +
+                    `region-scope task "${taskA.name}"'s gate (sed -n/awk range then grep) or use an AST/test check. ` +
+                    `See planner-antipatterns.md "Region-Scoped Negative Gates", or add ` +
+                    `<!-- planner-region-allow: ${pat} --> if intentional.`);
+            }
+        }
+    }
+    // This detector is warn-only: it never sets valid=false.
+    return { warnings, valid: true };
+}
 function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (!filePath) {
         error('file path required');
@@ -272,6 +577,8 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     const echoScan = scanNegativeGrepCommentEcho(content);
     errors.push(...echoScan.errors);
     warnings.push(...echoScan.warnings);
+    const conflictScan = scanFileWideNegativeGateConflict(content);
+    warnings.push(...conflictScan.warnings);
     output({
         valid: errors.length === 0,
         errors,
@@ -1121,7 +1428,6 @@ function cmdValidateHealth(cwd, options, raw) {
         if (phaseConvention === 'milestone-prefixed') {
             if (node_fs_1.default.existsSync(roadmapPath)) {
                 const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-                const { getMilestoneFromPhaseId } = core;
                 const mismatches = checkMilestonePrefixMismatches(roadmapContent, {
                     getMilestoneFromPhaseId: getMilestoneFromPhaseId,
                 });
@@ -1610,6 +1916,7 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
 }
 module.exports = {
     scanNegativeGrepCommentEcho,
+    scanFileWideNegativeGateConflict,
     cmdVerifySummary,
     cmdVerifyPlanStructure,
     cmdVerifyPhaseCompleteness,

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -19,8 +19,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const core = require("./core.cjs");
-const { readSubdirectories } = core;
+const coreUtilsMod = require("./core-utils.cjs");
+const { readSubdirectories } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planScan = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports

package/gsd-core/bin/lib/workstream.cjs

@@ -18,8 +18,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const core = require("./core.cjs");
-const { output, error, toPosixPath, getMilestoneInfo, generateSlugInternal } = core;
+const io = require("./io.cjs");
+const { output, error } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtils = require("./core-utils.cjs");
+const { toPosixPath, generateSlugInternal } = coreUtils;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParser = require("./roadmap-parser.cjs");
+const { getMilestoneInfo } = roadmapParser;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");

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

@@ -172,8 +172,7 @@ function executeWorktreePrunePlan(plan, deps = {}) {
     }
     const result = execGit(['worktree', 'prune'], { cwd: plan.repoRoot });
     if (result.timedOut) {
-        // AC4: surface timedOut as a first-class field so callers (e.g.
-        // pruneOrphanedWorktrees in core.cjs) can log a structured WARNING rather
+        // AC4: surface timedOut as a first-class field so callers can log a structured WARNING rather
         // than silently ignoring it (PRED.k302 — error-swallowing-empty-sentinel).
         return {
             ok: false,
@@ -305,11 +304,14 @@ function normalizeCleanupManifestEntry(entry) {
         return null;
     if (!/^worktree-agent-[A-Za-z0-9._/-]+$/.test(branch))
         return null;
+    const rawAllowedBases = Array.isArray(e.allowed_bases) ? e.allowed_bases : [];
+    const allowedBases = Array.from(new Set([expectedBase, ...rawAllowedBases.filter((base) => typeof base === 'string' && base.length > 0)]));
     return {
         agent_id: typeof e.agent_id === 'string' ? e.agent_id : null,
         worktree_path: worktreePath,
         branch,
         expected_base: expectedBase,
+        allowed_bases: allowedBases,
     };
 }
 function normalizeCleanupManifest(manifest) {
@@ -530,7 +532,10 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             break;
         }
         const mergeBase = execGit(['merge-base', 'HEAD', entry.branch], { cwd: plan.repoRoot });
-        if (!gitResultOk(mergeBase) || mergeBase.stdout.trim() !== entry.expected_base) {
+        const allowedBases = Array.isArray(entry.allowed_bases) && entry.allowed_bases.length > 0
+            ? entry.allowed_bases
+            : [entry.expected_base];
+        if (!gitResultOk(mergeBase) || !allowedBases.includes(mergeBase.stdout.trim())) {
             result.status = 'blocked';
             result.reason = 'base_mismatch';
             result.stderr = mergeBase?.stderr || '';
@@ -927,6 +932,40 @@ function cmdWorktreeReapOrphans(cwd) {
 }
 // Unused exports kept for API compatibility
 void parseWorktreeListPaths;
+// ─── Moved from core.cjs (ADR-857 T0 #1268 rehome-core-squatters) ─────────────
+/**
+ * Resolve the main worktree root when running inside a git worktree.
+ * In a linked worktree, .planning/ lives in the main worktree, not in the linked one.
+ * Returns the main worktree path, or cwd if not in a worktree.
+ */
+function resolveWorktreeRoot(cwd) {
+    const context = resolveWorktreeContext(cwd, {
+        existsSync: node_fs_1.default.existsSync,
+    });
+    return context.effectiveRoot;
+}
+/**
+ * Clear stale worktree metadata references via `git worktree prune`.
+ *
+ * Destructive linked-worktree removal is disabled by default for safety.
+ *
+ * @param repoRoot - absolute path to the main (or any) worktree of
+ *   the repository; used as `cwd` for git commands.
+ * @returns list of worktree paths that were removed (always empty)
+ */
+function pruneOrphanedWorktrees(repoRoot) {
+    try {
+        const plan = planWorktreePrune(repoRoot, { allowDestructive: false }, { parseWorktreePorcelain });
+        const pruneResult = executeWorktreePrunePlan(plan);
+        if (pruneResult && pruneResult.timedOut) {
+            process.stderr.write('[gsd-tools] WARNING: worktree health check degraded' +
+                ' — git worktree prune timed out after 10s.' +
+                ' Orphaned worktree metadata may remain until the next successful run.\n');
+        }
+    }
+    catch { /* never crash the caller */ }
+    return [];
+}
 module.exports = {
     resolveWorktreeContext,
     parseWorktreePorcelain,
@@ -941,4 +980,6 @@ module.exports = {
     cmdWorktreeCleanupWave,
     reapOrphanWorktrees,
     cmdWorktreeReapOrphans,
+    resolveWorktreeRoot,
+    pruneOrphanedWorktrees,
 };

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

@@ -53,6 +53,8 @@
     "workflow.cross_ai_command",
     "workflow.cross_ai_timeout",
     "workflow.subagent_timeout",
+    "workflow.test_command",
+    "workflow.build_command",
     "executor.stall_detect_interval_minutes",
     "executor.stall_threshold_minutes",
     "workflow.inline_plan_threshold",

package/gsd-core/references/planner-antipatterns.md

@@ -128,3 +128,49 @@ When the literal MUST appear in the plan body verbatim — e.g. the plan documen
 ```
 
 One marker per literal. The marker exempts only the exact literal it names.
+
+## Region-Scoped Negative Gates
+
+> Surfaced at plan-write time by `verify.plan-structure` (the `validate_plan` step), WARN-level. Issue #968.
+
+A **negative grep** — `! grep -Eq 'PAT' file` or `grep -c 'PAT' file == 0` — asserts a construct is absent. `grep` is file-scoped by nature: it has no notion of function or region. This breaks down when a phase splits one file across parallel tasks with legitimately opposite needs for the same construct in different regions:
+
+- **Task A** bans the construct file-wide — a synchronous factory must not block on a refresh: `! grep -Eq 'await .*refresh' app/page.py`.
+- **Task B** legitimately requires it elsewhere in the same file — a post-reindex handler must `await bridge.refresh()` to repopulate state.
+
+Both occurrences are real, correct production code in different functions of one file. A file-wide negative grep cannot say "absent in function X, present in function Y", so the two gates are mutually unsatisfiable with a direct call — the executor is pushed into an indirection whose only purpose is to relocate the matched string out of the file (pure gate-appeasement, zero behaviour change). This is distinct from Comment-Text Discipline (#429): there is no comment echo and no allowlist helps — the construct must genuinely be present in one region and absent in another.
+
+**The fix:** region-scope the negative gate so "absent in region X" stops implying "absent file-wide."
+
+### Bad — file-wide ban unsatisfiable against a sibling's real code
+
+```xml
+<!-- Task A -->
+<verify><automated>! grep -Eq 'await .*refresh' app/page.py</automated></verify>
+<!-- Task B (same file, different function) -->
+<action>Add a post-reindex handler in app/page.py that awaits bridge.refresh().</action>
+<files>app/page.py</files>
+```
+
+Task B writing `await bridge.refresh()` trips Task A's file-wide gate, though both are correct.
+
+### Good — scope the gate to the factory region
+
+```xml
+<!-- Task A: ban only inside the synchronous factory, not the whole file -->
+<verify><automated>! awk '/^def make_page/,/^def /' app/page.py | grep -Eq 'await .*refresh'</automated></verify>
+<!-- or a fixed line range -->
+<verify><automated>! sed -n '12,40p' app/page.py | grep -Eq 'await .*refresh'</automated></verify>
+```
+
+The factory region is asserted clean; the reindex handler elsewhere in the same file keeps its required `await bridge.refresh()`. Both gates pass with no code restructuring. Prefer an AST/structural check or a focused unit test where region extraction is fragile.
+
+### When the split is intentional and unavoidable
+
+If region-scoping is genuinely impractical and the file split is intentional, suppress the warning with a marker naming the pattern:
+
+```
+<!-- planner-region-allow: await .*refresh -->
+```
+
+One marker per pattern. The marker exempts only the exact pattern it names. Prefer region-scoping over suppression.

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

@@ -36,6 +36,8 @@ Configuration options for `.planning/` directory behavior.
 | `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. 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.test_command` | `null` | Custom shell command run as the regression/test gate by verify-phase, execute-phase, audit-fix, and post-merge-gate. When unset, GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). Example: `npm test`. |
+| `workflow.build_command` | `null` | Custom shell command run as the build gate by the post-merge gate. When unset, the build step is skipped/auto-detected. Example: `npm run build`. |
 | `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"`) |
 | `manager.flags.plan` | `""` | Flags passed to plan workflow when dispatched from manager |
@@ -220,7 +222,7 @@ Squash merge is recommended — keeps main branch history clean while preserving
 
 ## Complete Field Reference
 
-Generated from `CONFIG_DEFAULTS` (core.cjs) and `VALID_CONFIG_KEYS` (config.cjs).
+Generated from `CONFIG_DEFAULTS` (configuration.cjs) and `VALID_CONFIG_KEYS` (config-schema.cjs).
 
 ### Core Fields
 
@@ -262,6 +264,8 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.skip_discuss` | boolean | `false` | `true`, `false` | Skip discuss phase entirely |
 | `workflow.use_worktrees` | boolean | `true` | `true`, `false` | Run executor agents in isolated git worktrees |
 | `workflow.subagent_timeout` | number | `300000` | Any positive integer (ms) | Timeout for parallel subagent tasks (default: 5 minutes) |
+| `workflow.test_command` | string\|null | `null` | Any shell command | Regression/test gate command run by verify-phase, execute-phase, audit-fix, and post-merge-gate. Unset → GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). |
+| `workflow.build_command` | string\|null | `null` | Any shell command | Build gate command run by the post-merge gate. Unset → build step auto-detected/skipped. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
 | `workflow.code_review` | boolean | `true` | `true`, `false` | Enable built-in code review step in the ship workflow |
 | `workflow.code_review_depth` | string | `"standard"` | `"light"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow |