@opengsd/gsd-core 1.12.0 → 1.14.0

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

@@ -13,6 +13,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const validate_cjs_1 = require("./validate.cjs");
+const security_cjs_1 = require("./security.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
@@ -23,14 +24,21 @@ const stateMod = require("./state.cjs");
 const modelProfilesMod = require("./model-profiles.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
 const planScanMod = require("./plan-scan.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
+const verificationMod = require("./verification.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- core-utils.cjs is an export= CommonJS module
 const coreUtilsMod = require("./core-utils.cjs");
 const { findOrphanSummaries, findUnsummarizedPlans } = coreUtilsMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- worktree-safety.cjs is an export= CommonJS module
+const worktreeSafetyMod = require("./worktree-safety.cjs");
+// Single owner of git C-quoted-path decoding (see #4081 note at the
+// codebase-drift --name-status parse loop).
+const { decodeGitQuotedPath } = worktreeSafetyMod;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
-const security_cjs_1 = require("./security.cjs");
+const security_cjs_2 = require("./security.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const schema_detect_cjs_1 = require("./schema-detect.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
@@ -56,7 +64,12 @@ const { SEVERITY: HEALTH_SEVERITY, REMEDY_ACTION, REMEDY_RISK, evaluateRules, ev
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-snapshot.cjs is an export= CommonJS module
 const planningSnapshotMod = require("./planning-snapshot.cjs");
 const { buildPlanningSnapshot } = planningSnapshotMod;
-const { planningDir } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- onboard-projection.cjs is an export= CommonJS module
+const onboardProjectionMod = require("./onboard-projection.cjs");
+const { REQUIRED_CODEBASE_MAP_FILES } = onboardProjectionMod;
+const clock_cjs_1 = require("./clock.cjs");
+const { planningDir, planningRoot, withPlanningLock } = planningWorkspace;
+const { defaultPhaseCleanCommitTimesMs } = verificationMod;
 const { extractFrontmatter, parseMustHavesBlock } = frontmatterMod;
 const { readStateHeadFreshness } = stateMod;
 /**
@@ -144,9 +157,12 @@ function verifySummaryCore(cwd, summaryPath, checkFileCount, opts) {
         if (firstSegment.indexOf('.') > 0)
             return false;
         // Containment guard: a `../`-bearing reference must not turn this advisory
-        // into a filesystem existence probe outside the project.
-        const resolved = node_path_1.default.resolve(projectRoot, candidate);
-        if (resolved !== projectRoot && !resolved.startsWith(projectRoot + node_path_1.default.sep))
+        // into a filesystem existence probe outside the project. Lexical (ADR-4650
+        // decision 6): the candidate is a string pulled from a SUMMARY document and
+        // by construction may not exist yet — existence is what gets probed
+        // downstream — and this is a pure string-heuristic filter with no other fs
+        // access, so a realpath call would also change its cost profile.
+        if ((0, security_cjs_1.tryWithinRootLexical)(candidate, projectRoot) === null)
             return false;
         return true;
     };
@@ -694,6 +710,189 @@ function scanFileWideNegativeGateConflict(content) {
     // This detector is warn-only: it never sets valid=false.
     return { warnings, valid: true };
 }
+/**
+ * Issue #4024 — quantitative-criteria trap-shape scanner, the third plan-discipline
+ * gate in this family (after #429's comment-echo gate and #968's file-wide
+ * negative-gate conflict detector). #429/#968 judge `grep -c … == 0` shapes; this
+ * scanner judges the OTHER quantitative criterion shapes that are provably traps
+ * at HEAD, so a plan whose criteria are unsatisfiable-or-vacuous before any
+ * executor touches them no longer passes `verify plan-structure` clean.
+ *
+ * Scope: criteria text only — `<acceptance_criteria>`, `<automated>`, and
+ * `<verify>` blocks. Prose elsewhere in the plan (e.g. an explanatory
+ * `<action>`) is not judged (fail-open; see the negative-space section of the
+ * #4024 diagnosis).
+ *
+ * Ban list, each rule with a corrected arm asserted in tests (a rule that fires
+ * on its own fix is a refusal, not a rule):
+ *   R1 (error) exact count out of `grep -c` with N ≥ 2 — `grep -c` counts LINES,
+ *       not matches. Hedged counts (`>=`, "at least"), `== 0` (the #429/#968
+ *       family) and the `== 1` presence idiom stay clean.
+ *   R2 (error) bulk observed-failing claims — "all N tests … observed failing" /
+ *       "tests N through M … each … observed failing". A test asserting a
+ *       non-change cannot go red before the change exists. Per-test
+ *       "discriminates" wording and subset claims stay clean.
+ *   R3 (error) `$VAR` unquoted in command position — zsh does not word-split an
+ *       unquoted expansion, the command exits 127, and any arm reading its
+ *       status passes vacuously.
+ *   R4 (warn)  a fallible command (`git …`) in a non-final pipeline stage — the
+ *       pipeline reports the LAST stage's status, so the failure is swallowed.
+ *       Warn-only: the shape is ambiguous unless the criterion reads the status.
+ *   R5 (error) `wc` output compared by string equality (`… | wc -l | grep -x 0`)
+ *       — BSD `wc` pads its output, so the comparison never matches.
+ *   R6 (error) `git diff`/`git log` with a relative `HEAD~N` anchor — it names
+ *       whatever commit happened to land (another session's). Bare `git diff`
+ *       with no range is a WARNING: a committed change produces no output and
+ *       the check passes, but an uncommitted-tree check is a legitimate idiom.
+ *
+ * Legitimate exit: `<!-- plan-criteria-allow: R# - reason -->` (house style of
+ * `planner-discipline-allow`); the reason must be non-empty. Fail open: no
+ * criteria zones → no findings; every parse is text-only, nothing executes.
+ */
+function scanQuantitativeCriteria(content) {
+    const errors = [];
+    const warnings = [];
+    // Criteria zones: <acceptance_criteria>, <automated>, <verify>. A <verify>
+    // block contains its <automated> child, so the same segment may be harvested
+    // twice — dedupe findings by message below.
+    const zones = [];
+    for (const tag of ['acceptance_criteria', 'automated', 'verify']) {
+        for (const block of (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(content || '', tag)) {
+            zones.push({ text: block, prose: tag === 'acceptance_criteria' });
+        }
+    }
+    if (zones.length === 0)
+        return { errors, warnings };
+    // Allow markers may sit anywhere in the plan (same as the sibling scanners).
+    // The reason must be non-empty: `R1 - -->` is not an auditable exit.
+    const allow = new Set();
+    const allowRe = /<!--\s*plan-criteria-allow:\s*(R[1-6])\s+-\s+([^>]*\S)\s*-->/g;
+    let am;
+    while ((am = allowRe.exec(content || '')) !== null)
+        allow.add(am[1]);
+    const record = (bucket, rule, message, seen) => {
+        if (allow.has(rule) || seen.has(message))
+            return;
+        seen.add(message);
+        bucket.push(message);
+    };
+    // A count-grep invocation (grep with -c / --count), per the #429 idiom.
+    const countGrepRe = /grep((?:\s+-{1,2}[A-Za-z][A-Za-z-]*)+)\s+(?:'[^']*'|"[^"]*"|[^\s|>&;]+)/g;
+    const optsHaveCount = (opts) => /(?:^|\s)-[A-Za-z]*c[A-Za-z]*(?=\s|$)/.test(opts) || /--count\b/.test(opts);
+    const hasCountGrep = (s) => {
+        countGrepRe.lastIndex = 0;
+        let m;
+        while ((m = countGrepRe.exec(s)) !== null) {
+            if (optsHaveCount(m[1]))
+                return true;
+        }
+        return false;
+    };
+    const seenErr = new Set();
+    const seenWarn = new Set();
+    for (const zone of zones) {
+        // Same normalization as the sibling scanners (#3611): newline join,
+        // backslash continuation join, entity-amp decode.
+        const text = decodeEntityAmps(zone.text
+            .replace(/\r\n/g, '\n')
+            .replace(/\r/g, '\n')
+            .replace(/\\\n/g, ' '));
+        // R2 — bulk observed-failing prose (acceptance_criteria only). The gap
+        // [^\n.]{0,120} keeps the subject and the claim adjacent within one
+        // sentence, so the corrected arm (a subset claim, or "each test
+        // discriminates") never fires.
+        if (zone.prose) {
+            const bulkRedRes = [
+                /\ball\s+(?:\d+|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\s+tests\b[^\n.]{0,120}?observed\s+fail/i,
+                /\btests\s+\d+\s+through\s+\d+\b[^\n.]{0,120}?observed\s+fail/i,
+            ];
+            for (const re of bulkRedRes) {
+                if (re.test(text)) {
+                    record(errors, 'R2', '[plan-criteria R2] A bulk "all N tests / tests N through M were observed failing" criterion is ' +
+                        'unsatisfiable whenever any of the N tests asserts a non-change, which cannot go red before the ' +
+                        'change exists. Say "each test discriminates" (fails before the change, passes after), and attach a ' +
+                        'mutation record for any test that cannot be seen red.', seenErr);
+                }
+            }
+        }
+        for (const seg of text.split('\n').flatMap(splitShellSegments)) {
+            // R1 — exact count out of `grep -c` (N ≥ 2). Spaced `==`/`-eq` (the
+            // #429 zeroCmp idiom, excluding assignments and >=/<=/!=), or the prose
+            // "returns exactly N".
+            if (hasCountGrep(seg)) {
+                const exact = [];
+                let m;
+                const shellCmp = /\s==?\s*(\d+)\b/g;
+                while ((m = shellCmp.exec(seg)) !== null)
+                    exact.push(parseInt(m[1], 10));
+                const eqCmp = /-eq\s+(\d+)\b/g;
+                while ((m = eqCmp.exec(seg)) !== null)
+                    exact.push(parseInt(m[1], 10));
+                const proseCmp = /\breturns?\s+exactly\s+(\d+)\b/gi;
+                while ((m = proseCmp.exec(seg)) !== null)
+                    exact.push(parseInt(m[1], 10));
+                if (exact.some((n) => n >= 2)) {
+                    record(errors, 'R1', '[plan-criteria R1] An exact count out of `grep -c` is a trap: `grep -c` counts LINES, not matches, ' +
+                        'so the criterion can be false at HEAD before any executor touches it. Use `>= 1`, `== 0`, or ' +
+                        '`grep -n` and read the line numbers.', seenErr);
+                }
+            }
+            // R3 — unquoted $VAR in command position (zsh does not word-split; the
+            // command exits 127 and any arm reading its status passes vacuously).
+            // The anchor tolerates a markdown list bullet and/or an inline-code
+            // backtick before the command — criteria are prose lines like
+            // "- `$NOKEY npx tsx x.ts` exits 0" — but nothing else: the expansion
+            // must still be the FIRST token of the command itself.
+            if (/^(?:[-*]\s*)?\u0060?\$[A-Z_][A-Z0-9_]*\s/.test(seg)) {
+                record(errors, 'R3', '[plan-criteria R3] `$VAR` unquoted in command position does not word-split under zsh — the shell ' +
+                    'looks for a command literally named by the whole expansion and exits 127, so any arm reading its ' +
+                    'status passes vacuously. Write the prefix inline or use a shell function.', seenErr);
+            }
+            // R4 — a fallible `git …` in a non-final pipeline stage: the pipeline
+            // reports the LAST stage's status, so git's failure is swallowed.
+            // Warn-only: without a status assertion the shape is ambiguous.
+            // Not a markdown table: the negated-pipe class matches a SHELL pipeline
+            // stage boundary (git before the next `|`), the same shape the
+            // #429/#968 scanners use; there is no table row to parse.
+            // allow-adhoc-markdown: shell pipeline stage boundary, not a table cell (#4024)
+            if (/\bgit\s+[a-z][^\n|]*\|/.test(seg)) {
+                record(warnings, 'R4', '[plan-criteria R4] A fallible `git` in a non-final pipeline stage is swallowed — the pipeline reports ' +
+                    'the last stage\'s status, so a broken command reads as clean. Capture the status first.', seenWarn);
+            }
+            // R5 — `wc` output compared by string equality: BSD `wc` pads its output
+            // (seven spaces then the number), so `grep -x 0` can never match.
+            if (/\bwc\b/.test(seg) && /\bgrep\s+(?:-{1,2}[A-Za-z]*x[A-Za-z]*|--line-regexp)\s+['"]?\d+['"]?/.test(seg)) {
+                record(errors, 'R5', '[plan-criteria R5] `wc` output compared by string equality is unsatisfiable on BSD `wc`, which pads ' +
+                    'its output before the number. Compare numerically: `test "$n" -eq 0`, or `tr -d \' \'` first.', seenErr);
+            }
+            // R6 — relative HEAD~N anchors name whatever commit happened to land;
+            // a bare `git diff` with no range makes a committed change invisible.
+            if (/\bgit\s+(?:diff|log)\b[^\n|;&]*\bHEAD~\d+/.test(seg)) {
+                record(errors, 'R6', '[plan-criteria R6] `git diff`/`git log` with a relative `HEAD~N` anchor names whatever commit ' +
+                    'happened to land last — in a repository with parallel sessions that is another session\'s commit. ' +
+                    'Pin an explicit range: `<sha>^..<sha>`.', seenErr);
+            }
+            else {
+                // The argument span ends at the closing backtick of an inline-code
+                // span ("`git diff` shows ..."), at a redirection, or at a chain
+                // operator — trailing prose must never read as diff arguments.
+                const bareDiff = /\bgit\s+diff\b([^\u0060\n|;&<>]*)/.exec(seg);
+                if (bareDiff) {
+                    const rest = bareDiff[1].trim();
+                    // Bare or flags-only (no rev, range, or path): ambiguous between an
+                    // uncommitted-tree check (legitimate) and a committed-change check
+                    // (vacuously clean) — warn, never error.
+                    if (rest === '' || /^-{1,2}[A-Za-z-]+$/.test(rest)) {
+                        record(warnings, 'R6', '[plan-criteria R6] Bare `git diff` with no revision range produces no output for a COMMITTED ' +
+                            'change, so the criterion passes vacuously. Pin an explicit range (`<sha>^..<sha>`) unless the ' +
+                            'check is intentionally about the uncommitted tree.', seenWarn);
+                    }
+                }
+            }
+        }
+    }
+    return { errors, warnings };
+}
 /**
  * Single pass over `<task ...>…</task>` blocks. The body pattern is
  * ReDoS-safe stop-at-next-open (mirrors `taggedBlockPattern` in
@@ -904,6 +1103,12 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     warnings.push(...echoScan.warnings);
     const conflictScan = scanFileWideNegativeGateConflict(content);
     warnings.push(...conflictScan.warnings);
+    // #4024: quantitative-criteria trap shapes (exact grep -c counts, bulk
+    // observed-failing claims, $VAR command position, swallowed pipeline
+    // stages, wc string-equality, relative git anchors).
+    const quantScan = scanQuantitativeCriteria(content);
+    errors.push(...quantScan.errors);
+    warnings.push(...quantScan.warnings);
     output({
         valid: errors.length === 0,
         errors,
@@ -1080,12 +1285,19 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
         results.push(check);
     }
     const passed = results.filter((r) => r['passed']).length;
+    // Positive-evidence floor (#3956): a non-empty artifacts block whose items are
+    // all bare strings / path-less objects is item-by-item skipped, leaving results
+    // empty; `passed === results.length` would then be `0 === 0` → a vacuous GREEN
+    // over zero checks. Require at least one checked artifact, mirroring the
+    // no-vacuous-pass rule at src/uat-predicate.cts. The fully-empty block is still
+    // caught earlier by the `artifacts.length === 0` guard and returns its error.
+    const allPassed = results.length > 0 && passed === results.length;
     output({
-        all_passed: passed === results.length,
+        all_passed: allPassed,
         passed,
         total: results.length,
         artifacts: results,
-    }, raw, passed === results.length ? 'valid' : 'invalid');
+    }, raw, allPassed ? 'valid' : 'invalid');
 }
 /**
  * Returns a Set of file paths (relative to cwd) that are promised by plans in
@@ -1174,11 +1386,11 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
             // project. Leave sourceContent as null so the existing not-found /
             // pending classification below runs unchanged. Note this guard is
             // narrower than it may look: `from: "."` is a non-empty string, so it
-            // still reaches validatePath and safeReadFile below, and DOES read the
+            // still reaches tryWithinRoot and safeReadFile below, and DOES read the
             // cwd directory (yielding "Source read failed: EISDIR") — this branch
             // only short-circuits the true empty-string case.
-            const fromCheck = (0, security_cjs_1.validatePath)(fromPath, cwd);
-            if (!fromCheck.safe) {
+            const fromContained = (0, security_cjs_2.tryWithinRoot)(fromPath, cwd);
+            if (fromContained === null) {
                 // Do not echo result.error — it embeds absolute host paths.
                 check['path_rejected'] = 'from';
                 check['detail'] = 'Source path rejected — resolves outside the project directory';
@@ -1186,7 +1398,7 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
                 continue;
             }
             try {
-                sourceContent = (0, shell_command_projection_cjs_1.platformReadSync)(fromCheck.resolved);
+                sourceContent = (0, shell_command_projection_cjs_1.platformReadSync)(fromContained);
             }
             catch (err) {
                 // Report the errno only — never the message or path (untrusted `from:`
@@ -1254,8 +1466,8 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
                             // An empty/missing `to:` is a malformed plan, not a
                             // path-confinement violation — only a non-empty path that
                             // actually resolves outside the project is path_rejected.
-                            const toCheck = (0, security_cjs_1.validatePath)(toPath, cwd);
-                            if (!toCheck.safe) {
+                            const toContained = (0, security_cjs_2.tryWithinRoot)(toPath, cwd);
+                            if (toContained === null) {
                                 // Do not read a rejected `to:` — treat as no target content
                                 // and do not echo result.error, which embeds absolute host
                                 // paths.
@@ -1263,7 +1475,7 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
                                 check['detail'] = `Pattern "${link['pattern']}" not found in source; target path rejected — resolves outside the project directory`;
                             }
                             else {
-                                targetContent = (0, shell_command_projection_cjs_1.platformReadSync)(toCheck.resolved);
+                                targetContent = (0, shell_command_projection_cjs_1.platformReadSync)(toContained);
                             }
                         }
                         if (targetContent && pat.test(targetContent)) {
@@ -1299,7 +1511,17 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
     // A pending link (from: file promised by a same-or-later-wave plan) is not a
     // hard failure — it should not count against the all_verified gate (#1202).
     const hardFailed = results.filter((r) => !r['verified'] && !r['pending']).length;
-    const allVerified = hardFailed === 0;
+    // Positive-evidence floor (#3956): an all-bare-string key_links block skips
+    // every item (only `typeof link === 'string'` items are continue-skipped
+    // above), leaving results empty; `hardFailed === 0` would then be a vacuous
+    // GREEN over zero checks. Require at least one checked link. (A `from:`-less
+    // object is NOT skipped, unlike a path-less object on the artifacts side — it
+    // falls through to a `verified: false` result and hard-fails, so it was never
+    // part of the vacuous-pass surface; only the all-bare-string case is.) A
+    // pending link IS pushed to results (with pending: true), so an all-pending
+    // block still satisfies results.length > 0 and its #1202 non-hard-failing
+    // semantics are unchanged — the floor only rejects the zero-result case.
+    const allVerified = results.length > 0 && hardFailed === 0;
     output({
         all_verified: allVerified,
         verified,
@@ -1593,6 +1815,121 @@ function cmdValidateAgents(cwd, raw) {
         sandbox_posture: sandboxPosture,
     }, raw);
 }
+// ─── Context drift (#3348) ───────────────────────────────────────────────────
+/**
+ * Resolve a phase directory under `phasesDir` from a user-supplied `phaseArg`,
+ * via the canonical phase-directory matcher (phase-id.cjs::matchPhaseDirs) rather
+ * than a naive substring test — a bare `.includes(phaseArg)` lets a non-existent
+ * phase silently match a different phase whose directory name merely contains the
+ * requested token (e.g. "1" matching "11-expansion"). Falls back to an exact
+ * directory-name match. Returns null if neither resolves. (#1571, #2528)
+ */
+function resolvePhaseDirByToken(phasesDir, phaseArg) {
+    const normalizedPhase = normalizePhaseName(phaseArg);
+    const dirEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+    const dirNames = dirEntries.filter((e) => e.isDirectory()).map((e) => e.name);
+    const matched = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
+    if (matched)
+        return node_path_1.default.join(phasesDir, matched);
+    const contained = (0, security_cjs_2.tryWithinRoot)(phaseArg, phasesDir);
+    if (contained !== null && node_fs_1.default.existsSync(contained))
+        return contained;
+    return null;
+}
+/**
+ * Pure comparator: which of `entries` have an effective last-changed time
+ * STRICTLY BEFORE `contextEffectiveMs` (CONTEXT.md's own effective time)? Strict
+ * `<` is "stale" (matches findStaleVerificationSummary's own strict `>` convention
+ * for "newer than" elsewhere in this codebase — an artifact committed in the SAME
+ * commit/second as CONTEXT.md is in sync, not stale).
+ */
+function computeContextDrift(contextEffectiveMs, entries) {
+    return entries.filter((e) => e.effectiveMs < contextEffectiveMs).map((e) => e.file);
+}
+function buildContextDriftMessage(staleArtifacts, phaseArg) {
+    const parts = [`CONTEXT.md decisions are newer than: ${staleArtifacts.join(', ')}.`];
+    if (staleArtifacts.some((f) => f.endsWith('-RESEARCH.md'))) {
+        parts.push(`Regenerate research: /gsd:plan-phase ${phaseArg} --research.`);
+    }
+    if (staleArtifacts.some((f) => f.endsWith('-PATTERNS.md'))) {
+        parts.push('Regenerate patterns: delete the PATTERNS.md file, then re-run /gsd:plan-phase.');
+    }
+    if (staleArtifacts.some((f) => f.endsWith('-VALIDATION.md') || (f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md')))) {
+        parts.push('Regenerate or manually reconcile VALIDATION.md / SPEC.md against the current decisions.');
+    }
+    parts.push('Do not hand-inject the newer decisions into a prompt as a substitute for regenerating — that carries the staleness forward.');
+    return parts.join(' ');
+}
+function cmdVerifyContextDrift(cwd, phaseArg, raw) {
+    if (!phaseArg) {
+        error('Usage: verify context-drift <phase>');
+        return;
+    }
+    const pDir = planningDir(cwd);
+    const phasesDir = node_path_1.default.join(pDir, 'phases');
+    const emitSkip = (reason, message = '') => {
+        output({ block: false, skipped: true, reason, stale_artifacts: [], message }, raw);
+    };
+    if (!node_fs_1.default.existsSync(phasesDir)) {
+        emitSkip('phase-not-found', `Phase directory not found: ${phaseArg}`);
+        return;
+    }
+    // Same phase-directory resolution rule cmdVerifySchemaDrift uses (#1571, #2528):
+    // matchPhaseDirs, never a naive substring test.
+    const phaseDir = resolvePhaseDirByToken(phasesDir, phaseArg);
+    if (!phaseDir) {
+        emitSkip('phase-not-found', `Phase directory not found: ${phaseArg}`);
+        return;
+    }
+    let phaseFiles;
+    try {
+        phaseFiles = node_fs_1.default.readdirSync(phaseDir).slice().sort();
+    }
+    catch {
+        emitSkip('phase-not-found', `Phase directory not found: ${phaseArg}`);
+        return;
+    }
+    const contextFile = phaseFiles.find((f) => f.endsWith('-CONTEXT.md'));
+    if (!contextFile) {
+        emitSkip('no-context-md');
+        return;
+    }
+    const researchFile = phaseFiles.find((f) => f.endsWith('-RESEARCH.md'));
+    const patternsFile = phaseFiles.find((f) => f.endsWith('-PATTERNS.md'));
+    const validationFile = phaseFiles.find((f) => f.endsWith('-VALIDATION.md'));
+    const specFile = phaseFiles.find((f) => f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md'));
+    const upstreamFiles = [researchFile, patternsFile, validationFile, specFile].filter((f) => !!f);
+    if (upstreamFiles.length === 0) {
+        emitSkip('no-upstream-artifacts');
+        return;
+    }
+    const allFiles = [contextFile, ...upstreamFiles];
+    const cleanCommitMs = defaultPhaseCleanCommitTimesMs(phaseDir, allFiles);
+    const effectiveTimeMs = (file) => cleanCommitMs.has(file)
+        ? cleanCommitMs.get(file)
+        : node_fs_1.default.statSync(node_path_1.default.join(phaseDir, file)).mtimeMs;
+    const contextMs = effectiveTimeMs(contextFile);
+    const driftEntries = upstreamFiles.map((f) => ({ file: f, effectiveMs: effectiveTimeMs(f) }));
+    const staleArtifacts = computeContextDrift(contextMs, driftEntries);
+    let wf;
+    try {
+        const rawCfg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(pDir, 'config.json'), 'utf-8'));
+        wf = rawCfg['workflow'];
+    }
+    catch {
+        wf = undefined;
+    }
+    const action = wf?.context_drift_action === 'block' ? 'block' : 'warn';
+    const block = staleArtifacts.length > 0 && action === 'block';
+    const message = staleArtifacts.length > 0 ? buildContextDriftMessage(staleArtifacts, phaseArg) : '';
+    output({
+        block,
+        skipped: false,
+        stale_artifacts: staleArtifacts,
+        action,
+        message,
+    }, raw);
+}
 function cmdVerifySchemaDrift(cwd, phaseArg, skipFlag, raw) {
     if (!phaseArg) {
         error('Usage: verify schema-drift <phase> [--skip]');
@@ -1611,18 +1948,7 @@ function cmdVerifySchemaDrift(cwd, phaseArg, skipFlag, raw) {
     // matching "11-expansion"), making the drift gate inspect the wrong phase.
     // This shares the one selection rule with find-phase / verify
     // phase-completeness rather than restating it. (#1571, #2528)
-    let phaseDir = null;
-    const normalizedPhase = normalizePhaseName(phaseArg);
-    const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-    const dirNames = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-    const drift = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
-    if (drift)
-        phaseDir = node_path_1.default.join(phasesDir, drift);
-    if (!phaseDir) {
-        const exact = node_path_1.default.join(phasesDir, phaseArg);
-        if (node_fs_1.default.existsSync(exact))
-            phaseDir = exact;
-    }
+    const phaseDir = resolvePhaseDirByToken(phasesDir, phaseArg);
     if (!phaseDir) {
         output({ block: false, drift_detected: false, blocking: false, message: `Phase directory not found: ${phaseArg}` }, raw);
         return;
@@ -1668,6 +1994,110 @@ function cmdVerifySchemaDrift(cwd, phaseArg, skipFlag, raw) {
         skipped: isSkipped,
     }, raw);
 }
+/**
+ * Stamp `last_mapped_commit` (plus `last_mapped_at`) into the frontmatter of
+ * every codebase-map document that exists on disk, using the current HEAD sha.
+ *
+ * #3418: `drift.cjs` shipped a correct `writeMappedCommit` with no production
+ * caller, so no full `/gsd:map-codebase` run ever wrote the machine-readable
+ * baseline that `cmdVerifyCodebaseDrift` reads. The stamp lives in CODE rather
+ * than in a prose instruction to the mapper agent on purpose: an agent that
+ * decides its work is already done skips a prose step silently, which is the
+ * exact class of failure the stamp exists to detect.
+ *
+ * Only documents that already exist are stamped -- a `--fast` map produces four
+ * of the seven, and this must not conjure the missing three as frontmatter-only
+ * stubs that would then satisfy the seven-file completeness probe. `only`
+ * (`--files a.md,b.md`) narrows further, for a caller that refreshed a subset.
+ *
+ * Non-blocking by contract, like every other drift surface: any failure emits
+ * `skipped` with a reason and exits 0.
+ */
+function cmdStampCodebaseMap(cwd, raw, only) {
+    // Non-hoisted: load-order matters for circular dep guard
+    // eslint-disable-next-line @typescript-eslint/no-require-imports -- drift.cjs is an export= CommonJS module
+    const drift = require('./drift.cjs');
+    const emit = (payload) => output(payload, raw);
+    const skip = (reason) => ({
+        stamped: [],
+        commit: null,
+        stamped_at: null,
+        skipped: true,
+        reason,
+    });
+    try {
+        // Probed outside the lock on purpose: taking the lock creates `.planning/`
+        // if absent, and a stamp against a project that has no codebase map at all
+        // must not conjure the directory. The per-document existence check inside
+        // the lock is the one that matters -- a map deleted after this probe lands
+        // on `no-codebase-map` there rather than being recreated as stubs.
+        const codebaseDir = node_path_1.default.join(planningDir(cwd), 'codebase');
+        if (!node_fs_1.default.existsSync(codebaseDir)) {
+            emit(skip('no-codebase-dir'));
+            return;
+        }
+        // `--files` restricts the stamp to the documents a caller actually
+        // refreshed. The execute-phase auto-remap path rewrites STRUCTURE.md and
+        // ARCHITECTURE.md only; stamping the other five at HEAD there would claim a
+        // currency they do not have. Membership is checked against the closed
+        // seven-document set, so an unknown name is a fail-loud non-answer rather
+        // than a path this function tries to resolve. An empty value is refused
+        // rather than read as "no filter": a caller that meant to narrow the scope
+        // must not silently widen it to all seven.
+        let candidates = REQUIRED_CODEBASE_MAP_FILES;
+        if (only) {
+            if (only.length === 0) {
+                emit(skip('empty-codebase-map-file-filter'));
+                return;
+            }
+            const unknown = only.filter((file) => !candidates.includes(file));
+            if (unknown.length > 0) {
+                emit(skip('unknown-codebase-map-file: ' + unknown.join(',')));
+                return;
+            }
+            candidates = candidates.filter((file) => only.includes(file));
+        }
+        // Everything the stamp reads is read under the lock it writes under, the
+        // same lock the rest of the .planning/ writers take. Two stampers can run
+        // at once (the full map-codebase run and the execute-phase auto-remap);
+        // one that resolved HEAD or listed the present documents before waiting on
+        // the lock would write its now-stale sha over the newer one, or recreate a
+        // document deleted while it waited as a frontmatter-only stub.
+        const result = withPlanningLock(cwd, () => {
+            const revProbe = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', 'HEAD'], { cwd });
+            if (revProbe.exitCode !== 0)
+                return skip('not-a-git-repo');
+            const commit = revProbe.stdout.trim();
+            if (!/^[0-9a-f]{7,40}$/.test(commit))
+                return skip('unreadable-head');
+            const present = candidates.filter((file) => node_fs_1.default.existsSync(node_path_1.default.join(codebaseDir, file)));
+            if (present.length === 0)
+                return skip('no-codebase-map');
+            // Host-local calendar day, matching the `**Analysis Date:**` line the
+            // mapper agent writes -- the two freshness markers must not disagree by
+            // a timezone.
+            const stampedAt = clock_cjs_1.realClock.localToday();
+            const write = drift['writeMappedCommit'];
+            const stamped = [];
+            const failed = [];
+            for (const file of present) {
+                try {
+                    write(node_path_1.default.join(codebaseDir, file), commit, stampedAt);
+                    stamped.push(file);
+                }
+                catch (err) {
+                    // One unwritable document must not cost the stamp on the other six.
+                    failed.push({ file, reason: err instanceof Error ? err.message : String(err) });
+                }
+            }
+            return { stamped, failed, commit, stamped_at: stampedAt, skipped: false, reason: null };
+        });
+        emit(result);
+    }
+    catch (err) {
+        emit(skip('exception: ' + (err instanceof Error ? err.message : String(err))));
+    }
+}
 function cmdVerifyCodebaseDrift(cwd, raw) {
     // Non-hoisted: load-order matters for circular dep guard
     // eslint-disable-next-line @typescript-eslint/no-require-imports -- drift.cjs is an export= CommonJS module
@@ -1716,16 +2146,45 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
             });
             return;
         }
-        const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
-        let base = lastMapped;
-        if (!base) {
-            base = EMPTY_TREE;
+        // #3418: an absent or unresolvable baseline means NO COMPARISON IS POSSIBLE.
+        // It is neither zero drift nor total drift, and reporting it as either is a
+        // lie the consumer cannot detect. The former fallback diffed HEAD against
+        // the empty tree, so every tracked file read as newly added and the gate
+        // reported maximum drift identically on every run -- which made a genuinely
+        // stale map indistinguishable from a fresh one, and let `spawn_mapper` fire
+        // a whole-repo remap while presenting itself as an incremental one.
+        if (!lastMapped) {
+            emit({
+                block: false,
+                skipped: true,
+                reason: 'no-mapped-commit',
+                action_required: false,
+                directive: 'none',
+                elements: [],
+                last_mapped_commit: null,
+            });
+            return;
         }
-        else {
-            const verify = (0, shell_command_projection_cjs_1.execGit)(['cat-file', '-t', base], { cwd });
-            if (verify.exitCode !== 0)
-                base = EMPTY_TREE;
+        const baseProbe = (0, shell_command_projection_cjs_1.execGit)(['cat-file', '-t', lastMapped], { cwd });
+        if (baseProbe.exitCode !== 0 || baseProbe.stdout.trim() !== 'commit') {
+            // A stamp git cannot resolve: history rewrite, GC, or a shallow clone.
+            // Distinct reason from 'no-mapped-commit' -- the map claims a baseline,
+            // this repository just cannot see it, which is an operator-actionable
+            // difference (re-map vs. unshallow). A resolvable non-commit (a tree or
+            // blob sha, a ref name) is the same class of bad baseline: git would
+            // happily diff against it and report drift against the wrong object.
+            emit({
+                block: false,
+                skipped: true,
+                reason: 'unresolvable-mapped-commit',
+                action_required: false,
+                directive: 'none',
+                elements: [],
+                last_mapped_commit: lastMapped,
+            });
+            return;
         }
+        const base = lastMapped;
         const diff = (0, shell_command_projection_cjs_1.execGit)(['diff', '--name-status', base, 'HEAD'], { cwd });
         if (diff.exitCode !== 0) {
             emit({
@@ -1738,6 +2197,27 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
             });
             return;
         }
+        // #3418: GSD's own planning artifacts are not codebase structure. A
+        // map-codebase run commits `.planning/codebase/*.md`, so a correctly
+        // stamped baseline would be re-poisoned by the very commit that carries
+        // the stamp -- the next gate invocation would report the map's own seven
+        // documents as seven new directories, back over the default threshold of
+        // three. Derived from planningRoot() rather than a hardcoded literal so a
+        // repoint of the planning root cannot leave this filter behind.
+        //
+        // `git diff --name-status` always prints repo-root-relative paths, so a cwd
+        // below the root needs the `sub/` prefix or the filter matches nothing.
+        // That prefix comes from git (`--show-prefix`: root-relative, forward
+        // slashes, trailing slash, empty at the root). The rejected alternative was
+        // path.relative(`--show-toplevel`, cwd), which mixes two path producers: on
+        // Windows os.tmpdir() hands back the 8.3 short form while git resolves the
+        // long one, so relative() between them yields a `../..` chain that matches
+        // nothing. The `.planning` half below is safe to compute with relative()
+        // because both of its sides are the same cwd string.
+        const prefixProbe = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--show-prefix'], { cwd });
+        const repoPrefix = prefixProbe.exitCode === 0 ? prefixProbe.stdout.trim() : '';
+        const planningPrefix = repoPrefix + node_path_1.default.relative(cwd, planningRoot(cwd)).split(node_path_1.default.sep).join('/') + '/';
+        const isPlanningArtifact = (file) => file.split('\\').join('/').startsWith(planningPrefix);
         const added = [];
         const modified = [];
         const deleted = [];
@@ -1748,7 +2228,18 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
             if (!m)
                 continue;
             const status = m[1];
-            const file = m[3] || m[2];
+            // execGit sets no core.quotepath config, so git's default `true` applies:
+            // any path containing non-ASCII bytes (or `"`, `\`, control bytes) is
+            // C-quoted — `"docs/\350\256\276…/overview.md"`. Capturing that verbatim
+            // garbles affected_paths/elements and makes isPathMapped compare the
+            // quoted prefix (`"docs`) against STRUCTURE.md, misclassifying DOCUMENTED
+            // directories as new_dir (#4081). Decode with the single owner of the
+            // git C-quote seam (worktree-safety.cjs); a non-quoted value — the plain
+            // ASCII common case — passes through untouched. Both capture groups are
+            // decoded: R/C lines carry old AND new paths, either may be quoted.
+            const file = decodeGitQuotedPath(m[3] || m[2]);
+            if (isPlanningArtifact(file))
+                continue;
             if (status === 'A' || status === 'R' || status === 'C')
                 added.push(file);
             else if (status === 'M')
@@ -1811,6 +2302,7 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
 module.exports = {
     scanNegativeGrepCommentEcho,
     scanFileWideNegativeGateConflict,
+    scanQuantitativeCriteria,
     cmdVerifySummary,
     verifySummaryCore,
     cmdVerifyPlanStructure,
@@ -1824,5 +2316,8 @@ module.exports = {
     cmdValidateAgents,
     cmdVerifySchemaDrift,
     cmdVerifyCodebaseDrift,
+    computeContextDrift,
+    cmdVerifyContextDrift,
+    cmdStampCodebaseMap,
     STATE_HEAD_ADVISORY_COMMITS,
 };