@opengsd/gsd-core 1.7.0 → 1.8.0

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

@@ -15,6 +15,17 @@
  * inside a fenced code block) is ignored — this is the exact failure mode that
  * issue #586 / PR #650 identified. The shared extractFrontmatter parser anchors
  * its regex at byte 0 of the document, which provides this guarantee.
+ *
+ * #2348 staleness signal: whether a *-VERIFICATION.md is stale (a summary newer
+ * than it) is decided from git commit time when a file is committed AND clean,
+ * and from filesystem mtime otherwise. mtimes are assigned at checkout time and
+ * are not preserved by `git clone` / `cp -R`, and any unrelated `touch` /
+ * reformat / editor-save re-stales a valid report — so a committed phase could
+ * read `passed` on one machine and `stale` on a fresh clone purely from checkout
+ * order. Git commit time is content-tied and clone-stable; mtime is retained
+ * only for uncommitted or working-tree-dirty files, where it is the true
+ * last-changed signal. Both are real wall-clock change times, so the comparison
+ * is sound even when one file uses each.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -29,6 +40,7 @@ const phaseId = require("./phase-id.cjs");
 const frontmatterMod = require("./frontmatter.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
 const scanPhasePlans = require("./plan-scan.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const { output, error } = io;
 const { extractPhaseToken } = phaseId;
 const { extractFrontmatter } = frontmatterMod;
@@ -87,6 +99,79 @@ const VERIFICATION_ROUTING_TABLE = {
         next_command: '/gsd:execute-phase',
     },
 };
+/** Normalize separators to posix (git emits `/`; callers may pass `\` on Windows). */
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Match a git-emitted (repo-root-relative) path back to the caller's
+ * phaseDir-relative request by exact match or `/`-bounded suffix — precise
+ * enough that a root file and a nested `plans/` file can never collide (a plain
+ * basename match could). Returns the original caller-form file string, or null.
+ */
+function matchRequestedFile(gitPath, requested, requestedPosix) {
+    const g = toPosix(gitPath);
+    for (let i = 0; i < requested.length; i++) {
+        const want = requestedPosix[i];
+        if (g === want || g.endsWith('/' + want))
+            return requested[i];
+    }
+    return null;
+}
+/**
+ * Parse `git log --format=%ct --name-only` output into file → most-recent commit
+ * time (ms). Output is reverse-chronological, so a file's FIRST appearance
+ * top-down is its latest commit. `%ct` headers are pure digits; path lines
+ * contain a `.` (the `.md` extension) — so the two are unambiguous.
+ */
+function parseCommitTimes(stdout, requested, requestedPosix) {
+    const out = new Map();
+    let currentCt = null;
+    for (const line of stdout.split('\n')) {
+        if (line.length === 0)
+            continue;
+        if (/^\d+$/.test(line)) {
+            currentCt = Number.parseInt(line, 10);
+            continue;
+        }
+        if (currentCt === null)
+            continue;
+        const rel = matchRequestedFile(line, requested, requestedPosix);
+        if (rel !== null && !out.has(rel))
+            out.set(rel, currentCt * 1000);
+    }
+    return out;
+}
+function defaultPhaseCleanCommitTimesMs(phaseDir, files, execGitFn = shell_command_projection_cjs_1.execGit) {
+    if (files.length === 0)
+        return new Map();
+    const requestedPosix = files.map(toPosix);
+    const logRes = execGitFn(['log', '--first-parent', '--format=%ct', '--name-only', '--', ...files], {
+        cwd: phaseDir,
+    });
+    if (logRes.error || logRes.exitCode !== 0 || logRes.stdout.length === 0)
+        return new Map();
+    const commitTimes = parseCommitTimes(logRes.stdout, files, requestedPosix);
+    if (commitTimes.size === 0)
+        return commitTimes;
+    // Drop dirty files (working tree ≠ HEAD) so their mtime is used instead. If the
+    // dirty-check itself is INCONCLUSIVE (git diff errored / non-zero — as opposed
+    // to "ran and reported no dirty files"), we cannot prove any file is clean, so
+    // fail SAFE: discard the commit times and let every file fall back to mtime,
+    // the same direction as a git-log failure. Trusting possibly-stale commit times
+    // here would silently mask a real edit (false "not stale"). (#2348)
+    const diffRes = execGitFn(['diff', '--name-only', 'HEAD', '--', ...files], { cwd: phaseDir });
+    if (diffRes.error || diffRes.exitCode !== 0)
+        return new Map();
+    for (const line of diffRes.stdout.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const rel = matchRequestedFile(line, files, requestedPosix);
+        if (rel !== null)
+            commitTimes.delete(rel);
+    }
+    return commitTimes;
+}
 /**
  * Build a 'missing' result from the routing table.
  * Used for two early-return paths: no *-VERIFICATION.md file found, and
@@ -100,7 +185,7 @@ function missingResult() {
         next_command: route.next_command,
     };
 }
-function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default) {
+function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default, phaseCleanCommitTimesMs = defaultPhaseCleanCommitTimesMs) {
     // FS errors (TOCTOU: a SUMMARY listed by scanPhasePlans then removed before statSync;
     // unreadable dir; broken symlink; file->dir swap) must degrade to "not stale" rather
     // than throw uncaught into callers that are NOT under the planning lock
@@ -112,23 +197,31 @@ function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default) {
         const verificationFile = phaseFiles.filter((f) => f.endsWith('-VERIFICATION.md')).sort()[0];
         if (!verificationFile)
             return null;
-        const verificationMtimeMs = fsImpl.statSync(node_path_1.default.join(phaseDir, verificationFile)).mtimeMs;
-        let newestStaleSummary = null;
-        const summaryFiles = scanPhasePlans(phaseDir).summaryFiles;
-        for (const summaryFile of summaryFiles.sort()) {
-            const summaryMtimeMs = fsImpl.statSync(node_path_1.default.join(phaseDir, summaryFile)).mtimeMs;
-            if (summaryMtimeMs <= verificationMtimeMs)
-                continue;
-            if (!newestStaleSummary || summaryMtimeMs > newestStaleSummary.mtimeMs) {
-                newestStaleSummary = { summaryFile, mtimeMs: summaryMtimeMs };
+        const summaryFiles = scanPhasePlans(phaseDir).summaryFiles
+            .slice()
+            .sort();
+        // No summary can be newer than the verification → never stale. Return before
+        // touching git so a phase with no summaries costs zero subprocesses. (#2348)
+        if (summaryFiles.length === 0)
+            return null;
+        // Each file's effective "last changed" time = its commit time when committed
+        // AND clean (content-tied and clone-stable), else its filesystem mtime (the
+        // uncommitted working-tree edit). Both are real wall-clock change times, so
+        // comparing a clean file's commit time against a dirty file's mtime is sound.
+        // One resolver call = two git subprocesses for the whole phase. (#2348)
+        const cleanCommitMs = phaseCleanCommitTimesMs(phaseDir, [verificationFile, ...summaryFiles]);
+        const effectiveTimeMs = (file) => cleanCommitMs.has(file)
+            ? cleanCommitMs.get(file)
+            : fsImpl.statSync(node_path_1.default.join(phaseDir, file)).mtimeMs;
+        const verificationTimeMs = effectiveTimeMs(verificationFile);
+        for (const summaryFile of summaryFiles) {
+            // The caller only needs whether the phase is stale, not which summary —
+            // the first stale summary (in sorted order) is enough. Short-circuit.
+            if (effectiveTimeMs(summaryFile) > verificationTimeMs) {
+                return { verificationFile, summaryFile };
             }
         }
-        if (!newestStaleSummary)
-            return null;
-        return {
-            verificationFile,
-            summaryFile: newestStaleSummary.summaryFile,
-        };
+        return null;
     }
     catch {
         return null;
@@ -151,6 +244,7 @@ function findStaleVerificationSummary(phaseDir, fsImpl = node_fs_1.default) {
  */
 function readVerificationStatus(phaseDir, opts = {}) {
     const fsImpl = opts.fs ?? node_fs_1.default;
+    const phaseCleanCommitTimesMs = opts.phaseCleanCommitTimesMs ?? defaultPhaseCleanCommitTimesMs;
     // Phase token for the gaps_found command
     const baseName = node_path_1.default.basename(phaseDir);
     const phaseToken = extractPhaseToken(baseName);
@@ -200,7 +294,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
             next_command: `/gsd:plan-phase ${phaseNumber} --gaps`,
         };
     }
-    const staleVerification = findStaleVerificationSummary(phaseDir, fsImpl);
+    const staleVerification = findStaleVerificationSummary(phaseDir, fsImpl, phaseCleanCommitTimesMs);
     if (staleVerification) {
         const entry = VERIFICATION_ROUTING_TABLE['stale'];
         return {
@@ -251,6 +345,7 @@ function cmdVerificationStatus(cwd, phaseDirArg, raw) {
 module.exports = {
     VERIFIER_STATUSES,
     VERIFICATION_ROUTING_TABLE,
+    defaultPhaseCleanCommitTimesMs,
     findStaleVerificationSummary,
     readVerificationStatus,
     cmdVerificationStatus,

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

@@ -31,6 +31,7 @@ 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 markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const model_catalog_cjs_1 = require("./model-catalog.cjs");
 // 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;
@@ -42,7 +43,7 @@ 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, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
+const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, extractPhaseToken, comparePhaseNum } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal } = phaseLocatorMod;
@@ -52,6 +53,9 @@ const { getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone } = ro
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const worktreeSafetyMod = require("./worktree-safety.cjs");
 const { inspectWorktreeHealth } = worktreeSafetyMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- commands.cjs is an export= CommonJS module
+const commandsMod = require("./commands.cjs");
+const { determinePhaseStatus } = commandsMod;
 const { planningDir, planningRoot } = planningWorkspace;
 const { extractFrontmatter, parseMustHavesBlock } = frontmatterMod;
 const { writeStateMd } = stateMod;
@@ -516,6 +520,131 @@ function scanFileWideNegativeGateConflict(content) {
     // This detector is warn-only: it never sets valid=false.
     return { warnings, valid: true };
 }
+/**
+ * Single pass over `<task ...>…</task>` blocks. The body pattern is
+ * ReDoS-safe stop-at-next-open (mirrors `taggedBlockPattern` in
+ * markdown-sectionizer.cts): bounded attributes (`[^>]{0,1000}`) and a body
+ * boundary that terminates at the NEXT `<task[\s>]` opening, so a document
+ * full of unclosed `<task>` openings scans linearly. Captures both the
+ * attribute string (group 1, so the `type=` selector is not lost the way it is
+ * with `extractTaggedBlocks`) and the body (group 2).
+ */
+const PLAN_TASK_BLOCK_RE = /<task(\s[^>]{0,1000})?>((?:(?!<task[\s>])[\s\S])*?)<\/task>/g;
+/**
+ * Extract one `PlanTaskInfo` per `<task …>…</task>` block in `content`.
+ *
+ * Why a dedicated regex instead of `extractTaggedBlocks('task', true)`:
+ * `extractTaggedBlocks` discards the opening tag, so the task's `type=`
+ * attribute (which selects the validation branch) is lost. This helper
+ * captures both the attribute string and the body in one pass, then reuses
+ * `extractTaggedBlocks` on the body for sub-element extraction.
+ */
+function extractPlanTaskInfos(content) {
+    const infos = [];
+    if (typeof content !== 'string' || content.length === 0)
+        return infos;
+    PLAN_TASK_BLOCK_RE.lastIndex = 0;
+    let match;
+    while ((match = PLAN_TASK_BLOCK_RE.exec(content)) !== null) {
+        const attrs = match[1] ?? '';
+        const body = match[2] ?? '';
+        const typeMatch = attrs.match(/\btype\s*=\s*["']?([\w:-]+)/i);
+        const type = typeMatch ? typeMatch[1].toLowerCase() : '';
+        const nameArr = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(body, 'name');
+        const hasName = nameArr.length > 0;
+        const name = hasName ? nameArr[0].trim() : '';
+        infos.push({
+            name,
+            type,
+            hasName,
+            hasFiles: /<files>/.test(body),
+            hasAction: /<action>/.test(body),
+            hasVerify: /<verify>/.test(body),
+            hasDone: /<done>/.test(body),
+            hasWhatBuilt: /<what-built>/.test(body),
+            hasHowToVerify: /<how-to-verify>/.test(body),
+            hasDecision: /<decision>/.test(body),
+            hasOptions: /<options>/.test(body),
+            hasInstructions: /<instructions>/.test(body),
+            hasVerification: /<verification>/.test(body),
+            hasResumeSignal: /<resume-signal>/.test(body),
+        });
+        // Guard against zero-length matches looping forever.
+        if (match.index === PLAN_TASK_BLOCK_RE.lastIndex) {
+            PLAN_TASK_BLOCK_RE.lastIndex++;
+        }
+    }
+    return infos;
+}
+function isCheckpointType(type) {
+    return type.startsWith('checkpoint:');
+}
+/**
+ * Validate one plan task's structure against its type-specific canonical field
+ * set (per `gsd-core/references/checkpoints.md`):
+ *   - `checkpoint:human-verify` requires `<what-built>` / `<how-to-verify>` /
+ *      `<resume-signal>` (the "checkpoint triple").
+ *   - `checkpoint:decision` requires `<decision>` / `<options>` /
+ *      `<resume-signal>`.
+ *   - `checkpoint:human-action` requires `<action>` / `<instructions>` /
+ *      `<verification>` / `<resume-signal>`.
+ *   - Unknown `checkpoint:*` subtypes require only the universal
+ *      `<resume-signal>` (forward-compat — newer checkpoint types registered
+ *      in the reference don't need a verifier change to pass structure
+ *      validation).
+ *   - All other types (`auto`, `tracer`, `manual`, bare `<task>`, …) keep the
+ *      historical `<action>` / `<verify>` / `<done>` / `<files>` requirements.
+ */
+function validatePlanTaskStructure(task) {
+    const errors = [];
+    const warnings = [];
+    const taskName = task.hasName ? task.name : 'unnamed';
+    if (!task.hasName) {
+        errors.push('Task missing <name> element');
+    }
+    if (isCheckpointType(task.type)) {
+        if (!task.hasResumeSignal) {
+            errors.push(`Task '${taskName}' missing <resume-signal>`);
+        }
+        switch (task.type) {
+            case 'checkpoint:human-verify':
+                if (!task.hasWhatBuilt)
+                    errors.push(`Task '${taskName}' missing <what-built>`);
+                if (!task.hasHowToVerify)
+                    errors.push(`Task '${taskName}' missing <how-to-verify>`);
+                break;
+            case 'checkpoint:decision':
+                if (!task.hasDecision)
+                    errors.push(`Task '${taskName}' missing <decision>`);
+                if (!task.hasOptions)
+                    errors.push(`Task '${taskName}' missing <options>`);
+                break;
+            case 'checkpoint:human-action':
+                if (!task.hasAction)
+                    errors.push(`Task '${taskName}' missing <action>`);
+                if (!task.hasInstructions)
+                    errors.push(`Task '${taskName}' missing <instructions>`);
+                if (!task.hasVerification)
+                    errors.push(`Task '${taskName}' missing <verification>`);
+                break;
+            default:
+                // Unknown checkpoint:* subtype: <resume-signal> is the only universal
+                // requirement (forward-compat).
+                break;
+        }
+    }
+    else {
+        if (!task.hasAction)
+            errors.push(`Task '${taskName}' missing <action>`);
+        if (!task.hasVerify)
+            warnings.push(`Task '${taskName}' missing <verify>`);
+        if (!task.hasDone)
+            warnings.push(`Task '${taskName}' missing <done>`);
+        if (!task.hasFiles)
+            warnings.push(`Task '${taskName}' missing <files>`);
+    }
+    return { errors, warnings };
+}
 function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (!filePath) {
         error('file path required');
@@ -534,25 +663,20 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
         if (fm[field] === undefined)
             errors.push(`Missing required frontmatter field: ${field}`);
     }
+    const extractedTasks = extractPlanTaskInfos(content);
     const tasks = [];
-    for (const taskContent of (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(content, 'task', true)) {
-        const nameArr = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(taskContent, 'name');
-        const taskName = nameArr.length ? nameArr[0].trim() : 'unnamed';
-        const hasFiles = /<files>/.test(taskContent);
-        const hasAction = /<action>/.test(taskContent);
-        const hasVerify = /<verify>/.test(taskContent);
-        const hasDone = /<done>/.test(taskContent);
-        if (nameArr.length === 0)
-            errors.push('Task missing <name> element');
-        if (!hasAction)
-            errors.push(`Task '${taskName}' missing <action>`);
-        if (!hasVerify)
-            warnings.push(`Task '${taskName}' missing <verify>`);
-        if (!hasDone)
-            warnings.push(`Task '${taskName}' missing <done>`);
-        if (!hasFiles)
-            warnings.push(`Task '${taskName}' missing <files>`);
-        tasks.push({ name: taskName, hasFiles, hasAction, hasVerify, hasDone });
+    for (const task of extractedTasks) {
+        const verdict = validatePlanTaskStructure(task);
+        errors.push(...verdict.errors);
+        warnings.push(...verdict.warnings);
+        tasks.push({
+            name: task.hasName ? task.name : 'unnamed',
+            type: task.type,
+            hasFiles: task.hasFiles,
+            hasAction: task.hasAction,
+            hasVerify: task.hasVerify,
+            hasDone: task.hasDone,
+        });
     }
     if (tasks.length === 0)
         warnings.push('No <task> elements found');
@@ -567,6 +691,24 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (hasCheckpoints && fm['autonomous'] !== 'false' && String(fm['autonomous']) !== 'false') {
         errors.push('Has checkpoint tasks but autonomous is not false');
     }
+    // #1951: a decision rated one-way is supposed to be confirmed before it is
+    // walked through. Warn (never error — <reversibility> stays additive) when a
+    // one-way rating has no checkpoint:decision anywhere ahead of it in the plan,
+    // which is the planner emitting the rating but skipping the gate.
+    const decisionCheckpointOffsets = [];
+    for (const m of content.matchAll(/<task\s+type=["']?checkpoint:decision/g)) {
+        if (m.index !== undefined)
+            decisionCheckpointOffsets.push(m.index);
+    }
+    for (const m of content.matchAll(/<reversibility\s[^>]*rating=["']?one-way/g)) {
+        const at = m.index;
+        if (at === undefined)
+            continue;
+        if (!decisionCheckpointOffsets.some((offset) => offset < at)) {
+            warnings.push('Task rated <reversibility rating="one-way"> has no preceding checkpoint:decision — '
+                + 'a one-way door must be confirmed before the agent walks through it');
+        }
+    }
     const echoScan = scanNegativeGrepCommentEcho(content);
     errors.push(...echoScan.errors);
     warnings.push(...echoScan.warnings);
@@ -1207,9 +1349,22 @@ function cmdValidateHealth(cwd, options, raw) {
         try {
             const rawCfg = node_fs_1.default.readFileSync(configPath, 'utf-8');
             const parsed = JSON.parse(rawCfg);
-            const validProfiles = ['quality', 'balanced', 'budget', 'inherit'];
-            if (parsed['model_profile'] && !validProfiles.includes(parsed['model_profile'])) {
-                addIssue('warning', 'W004', `config.json: invalid model_profile "${parsed['model_profile']}"`, `Valid values: ${validProfiles.join(', ')}`);
+            if (parsed['model_profile'] && !model_catalog_cjs_1.VALID_PROFILES.includes(parsed['model_profile'])) {
+                addIssue('warning', 'W004', `config.json: invalid model_profile "${parsed['model_profile']}"`, `Valid values: ${model_catalog_cjs_1.VALID_PROFILES.join(', ')}`);
+            }
+            const configModels = parsed['models'];
+            if (configModels && typeof configModels === 'object' && !Array.isArray(configModels)) {
+                for (const [phaseType, tierValue] of Object.entries(configModels)) {
+                    if (!model_catalog_cjs_1.VALID_PHASE_TYPES.has(phaseType)) {
+                        addIssue('warning', 'W022', `config.json: models has an unknown phase type "${phaseType}" which will be ignored`, `Valid phase types: ${[...model_catalog_cjs_1.VALID_PHASE_TYPES].join(', ')}`);
+                    }
+                    else if (typeof tierValue !== 'string' || !model_catalog_cjs_1.VALID_TIERS.has(tierValue)) {
+                        addIssue('warning', 'W022', `config.json: models.${phaseType} has an invalid tier value ${JSON.stringify(tierValue)} which will be ignored`, `Valid tiers: ${[...model_catalog_cjs_1.VALID_TIERS].join(', ')}`);
+                    }
+                }
+            }
+            else if (configModels !== undefined && configModels !== null) {
+                addIssue('warning', 'W022', `config.json: models is set to ${JSON.stringify(configModels)}, but must be an object mapping phase types to tiers — this value will be ignored`, `Set models to an object like {"planning": "sonnet"}, or remove the key to use profile defaults`);
             }
         }
         catch (err) {
@@ -1260,6 +1415,49 @@ function cmdValidateHealth(cwd, options, raw) {
             addIssue('warning', 'W005', `Phase directory "${e.name}" doesn't follow NN-name format`, 'Rename to match pattern (e.g., 01-setup)');
         }
     }
+    // W023 (#2408): detect two or more real on-disk phase directories that
+    // normalize to the same phase key (e.g. `05-real/` + `05-real-stray/`).
+    // The collision silently breaks /gsd-stats status accuracy (now folded by
+    // precedence — see commands.cts foldPhaseStatus) and forces an operator
+    // decision. Wording is neutral — never guesses which directory is "real".
+    {
+        const groups = new Map();
+        for (const e of phaseDirEntries) {
+            // extractPhaseToken never returns empty — for unparseable dir names it
+            // falls back to the dir name itself. Two distinct unparseable names
+            // therefore normalize to distinct keys and cannot false-positive here;
+            // only dirs whose tokens collapse to the same key (e.g. `05-real` and
+            // `05-real-stray` → token `05`) produce a collision group.
+            const token = extractPhaseToken(e.name);
+            const key = normalizePhaseName(token);
+            const list = groups.get(key);
+            if (list)
+                list.push(e.name);
+            else
+                groups.set(key, [e.name]);
+        }
+        for (const [key, dirs] of groups) {
+            if (dirs.length < 2)
+                continue;
+            // Compute each dir's status independently so the warning is informative.
+            // Sort by phase id for stable output regardless of readdir order; tie-
+            // break on the dir name itself so two dirs sharing the same phase token
+            // (the collision case itself) still sort deterministically (V8's stable
+            // sort would otherwise fall back to non-portable fs.readdirSync order).
+            const described = dirs
+                .slice()
+                .sort((a, b) => comparePhaseNum(a, b) || String(a).localeCompare(String(b)))
+                .map((d) => {
+                const files = phaseDirFiles.get(d) || [];
+                const plans = files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
+                const summaries = files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+                const status = determinePhaseStatus(plans, summaries, node_path_1.default.join(phasesDir, d), 'Not Started');
+                return `${d} (${status})`;
+            })
+                .join(', ');
+            addIssue('warning', 'W023', `Phase directories collide on normalized key "${key}": ${described}`, 'Inspect each directory; rename or remove the duplicate so only one directory maps to this phase key');
+        }
+    }
     for (const e of phaseDirEntries) {
         const phaseFiles = phaseDirFiles.get(e.name) || [];
         const plans = phaseFiles.filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md');

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

@@ -72,6 +72,7 @@
     "statusline.show_last_command",
     "statusline.context_position",
     "statusline.show_context_tokens",
+    "statusline.state_format",
     "statusline.show_git",
     "workflow.max_discuss_passes",
     "features.thinking_partner",
@@ -148,8 +149,8 @@
     },
     {
       "topLevel": "dynamic_routing",
-      "source": "^dynamic_routing\\.(enabled|escalate_on_failure|max_escalations|tier_models\\.(light|standard|heavy))$",
-      "description": "dynamic_routing.<enabled|escalate_on_failure|max_escalations|tier_models.<light|standard|heavy>>"
+      "source": "^dynamic_routing\\.(enabled|escalate_on_failure|max_escalations|provider_escalation|tier_models\\.(light|standard|heavy))$",
+      "description": "dynamic_routing.<enabled|escalate_on_failure|max_escalations|provider_escalation|tier_models.<light|standard|heavy>>"
     },
     {
       "topLevel": "model_overrides",

package/gsd-core/references/api-coverage.md

@@ -24,13 +24,26 @@ treated as an external-API integration when **either**:
 1. a `COVERAGE.md` matrix is present in the phase directory (the planner produced
    one at `plan:pre`), **or**
 2. the phase scope shows a strong external-API-integration signal (an integration
-   verb co-occurring with an external-API noun, or an explicit `<Service>
-   API|SDK|REST|GraphQL` surface) and no matrix yet exists.
-
-Non-API phases (refactors, bug fixes, internal-only work, features that merely
-*mention* an existing internal API) do **not** fire the gate — the trigger
-requires a compound signal, so a bare word like "api" in "the public API of
-UserController" is intentionally ignored.
+   verb and an external-API noun **in the same clause**, or an explicit
+   `<Service> API|SDK|REST|GraphQL` surface naming a real service) and no matrix
+   yet exists.
+
+The detector is deliberately **fail-closed**: it leans toward firing, because a
+false positive is dismissed by a one-line `COVERAGE.md` "no external API
+integration" declaration, whereas a false *negative* silently lets a real
+external-API phase past this blocking gate — strictly worse. So it suppresses
+only prose that is unambiguously not external integration. A bare word like
+"api" in "the public API of UserController" is ignored (no integration verb +
+named service); the clause boundary is the whole relationship test, so an
+integration verb and an API noun in **different** clauses do not pair. Since
+#2365 the detector also excludes non-prose spans before matching: fenced code
+blocks, inline `` `code` `` spans, and path-shaped tokens (a first-party
+`src/app/api/profile/route.ts` route is a file path, not an external API, while
+an external host like `api.stripe.com/v1` still counts). In the
+`<Service> API` surface position it rejects capitalized sentence starters
+("The API"), locality/protocol descriptors ("Internal API", "REST API"),
+compound modifiers ("Resolver-only API"), and first-party-qualified services
+("internal Payments API") — a real vendor name is none of these.
 
 ## The two touch points
 
@@ -70,6 +83,23 @@ must be non-empty and unique; every decision must be `INTEGRATE` or `OPT-OUT`;
 every `OPT-OUT` must have a reason. Violations block the seal with a precise
 error.
 
+### Declaring "no external API integration" (#2365)
+
+A phase that integrates no external API/SDK/service — but was still asked for a
+matrix (e.g. the detector over-fired, or a team wants the decision on record) —
+declares it instead of fabricating a row:
+
+```markdown
+No external API integration: UI-only phase, no third-party surface.
+```
+
+The reason is **required**, exactly like an `OPT-OUT` reason — the declaration
+is a reasoned decision, not a bypass. A `COVERAGE.md` containing both the
+declaration and coverage rows is contradictory and blocks the seal. When the
+detector still finds integration signals in the phase scope, the declaration
+wins (it is the human overrule for a fallible detector) but the gate output
+surfaces the overridden signals so the contradiction is visible, not silent.
+
 ## A second integration against the same need
 
 A second platform for an existing capability (e.g. adding YouTube alongside

package/gsd-core/references/checkpoints.md

@@ -474,7 +474,7 @@ npm run dev &
 DEV_SERVER_PID=$!
 
 # Wait for ready (max 30s) — uses fetch() for cross-platform compatibility
-timeout 30 bash -c 'until node -e "fetch(\"http://localhost:3000\").then(r=>{process.exit(r.ok?0:1)}).catch(()=>process.exit(1))" 2>/dev/null; do sleep 1; done'
+gsd_run run-with-timeout 30 -- bash -c 'until node -e "fetch(\"http://localhost:3000\").then(r=>{process.exit(r.ok?0:1)}).catch(()=>process.exit(1))" 2>/dev/null; do sleep 1; done'
 ```
 
 **Port conflicts:** Kill stale process (`lsof -ti:3000 | xargs kill`) or use alternate port (`--port 3001`).

package/gsd-core/references/common-bug-patterns.md

@@ -97,6 +97,19 @@ Checklist of frequent bug patterns to scan before forming hypotheses. Ordered by
 3. **Each checked pattern is a hypothesis candidate** — verify or eliminate with evidence
 4. **If no pattern matches**, proceed to open-ended investigation
 
+### Pattern categories → bug taxonomy (Phase 1.75)
+
+The categories here feed bug-class classification (see `debugger-bug-taxonomy.md`):
+
+| Pattern category | Typical bug_class |
+|---|---|
+| Null / Undefined, Off-by-One, State, Import, Type, Regex, Error Handling, Scope | Bohrbug (deterministic) |
+| Async / Timing (intermittent, leaked timer, init order) | Heisenbug / Concurrency |
+| Environment / Config (works-here-not-there) | Heisenbug / Mandelbug (or config-as-root-cause) |
+| Data Shape / API Contract | Bohrbug (or Mandelbug if volume-dependent) |
+
+The taxonomy routes the investigation technique (SBFL + bisect for Bohrbugs; record-replay/stability for Heisenbugs; atomicity/order/deadlock checklist for Concurrency).
+
 ### Symptom-to-Category Quick Map
 
 | Symptom | Check First |