@opengsd/gsd-core 1.13.0 → 1.15.0

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

@@ -32,6 +32,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
 const { stripProjectCodePrefix, extractPhaseToken, comparePhaseNum } = phaseIdMod;
@@ -380,6 +381,25 @@ function splitSegments(cmd) {
         .map(s => s.trim())
         .filter(s => s.length > 0);
 }
+/**
+ * Decode entity-escaped ampersands (`&` → `&`) — #4730, the grounding
+ * gate's share of the #3611 defect. Planners emit `<automated>` bodies with
+ * `&amp;&amp;` as the chain operator, and the executing agent reads the
+ * decoded (rendered) form. Without this decode, `splitSegments` cuts
+ * `&amp;&amp;` at its semicolons and a `cd` target absorbs the trailing
+ * `&amp` fragment (`rawTarget: "src &amp"`), reporting an existing directory
+ * as a `missing_dir` blocker. Applied to the command text inside
+ * `resolveVerifyCommandTarget` — before any segment splitting or target
+ * resolution, after `result.command` has captured the text verbatim — so the
+ * escaped and literal forms of the same command produce identical verdicts.
+ * Kept module-private beside `splitSegments`, mirroring the sibling
+ * `src/verify.cts`'s own private `decodeEntityAmps` (#3611): the two gates
+ * are separate modules that independently parse `<automated>` text, and
+ * neither imports the other.
+ */
+function decodeEntityAmps(s) {
+    return s.replace(/&amp;/g, '&');
+}
 /** Strip a single matching pair of surrounding quotes, if present. */
 function stripQuotes(s) {
     if (s.length >= 2) {
@@ -438,6 +458,16 @@ function stripLeadingDotSlash(s) {
  * without touching the filesystem. A climb that names a concrete sibling (e.g.
  * `cd ../../frontend`, the exact #2401 shape) still names something checkable
  * and falls through to the normal filesystem probe below.
+ *
+ * An ABSOLUTE target outside the project root takes the same `outside_root`
+ * exit (#4767). It is more ambiguous across worktrees, not less: it is pinned
+ * to exactly one checkout, and when a planner copies the orchestrator's cwd
+ * into `<automated>` that checkout is the main tree — so under worktree
+ * isolation the command exists, runs, and passes against code the worktree
+ * changed and the main tree did not. Existence is therefore not evidence for
+ * an absolute target outside the root, and the filesystem is not consulted.
+ * Containment goes through `tryWithinRootLexical` (#4636) — lexical because the
+ * probe is read-only and must not depend on the target existing.
  */
 function isPureAncestorClimb(rel) {
     if (rel.length === 0)
@@ -453,7 +483,7 @@ function declaredPathCovers(declaredPaths, norm) {
         if (typeof p !== 'string')
             return false;
         const dp = stripLeadingDotSlash(toSlash(p));
-        return dp === target || dp.startsWith(target + '/');
+        return dp === target || dp.startsWith(target + '/'); // allow-handrolled-containment: declared-path coverage for pending-creation detection, not containment
     });
 }
 /**
@@ -501,7 +531,10 @@ function resolveVerifyCommandTarget(command, options) {
     if (typeof command !== 'string')
         return result;
     result.command = command;
-    const trimmed = command.trim();
+    // #4730: decode entity-escaped ampersands BEFORE segment splitting (see
+    // decodeEntityAmps) so the chain operator is visible to the splitter and
+    // the verdict matches what the executing agent's decoded form grounds to.
+    const trimmed = decodeEntityAmps(command.trim());
     if (trimmed === '')
         return result;
     // Nyquist "MISSING — Wave 0 must create …" sentinel; Dimension 8 owns it.
@@ -550,7 +583,18 @@ function resolveVerifyCommandTarget(command, options) {
     result.form = form;
     result.rawTarget = rawTarget;
     result.target = target;
-    if (!isAbs) {
+    if (isAbs) {
+        // #4767: an absolute target outside projectRoot is `outside_root`, same
+        // as the bare climb — see isPureAncestorClimb's doc for why existence is
+        // not evidence here and the filesystem is deliberately not consulted.
+        if ((0, security_cjs_1.tryWithinRootLexical)(target, base) === null) {
+            result.status = 'ok';
+            result.severity = 'warning';
+            result.reason = 'outside_root';
+            return result;
+        }
+    }
+    else {
         const rel = node_path_1.default.relative(base, target);
         if (isPureAncestorClimb(rel)) {
             result.status = 'ok';

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
@@ -37,7 +38,7 @@ const worktreeSafetyMod = require("./worktree-safety.cjs");
 // 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");
@@ -63,7 +64,11 @@ 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;
@@ -152,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;
     };
@@ -846,8 +854,15 @@ function scanQuantitativeCriteria(content) {
             // 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.
+            // #4774: the lookahead keeps `||` — a logical OR, the construct that
+            // HANDLES the failure (e.g. the `git cat-file -e <sha> || echo missing`
+            // ghost-control idiom, reachable here when prose apostrophes leave the
+            // segment's quote state unclosed) — quiet, while `|` and `|&` (a real
+            // pipeline stage, stderr-merged or not) still warn. Accepted trade-off:
+            // a QUOTED `||` literal ahead of a real pipe (``git grep 'a||b' f | wc -l``)
+            // also goes quiet — the lookahead cannot reach past the doubled pipe.
             // allow-adhoc-markdown: shell pipeline stage boundary, not a table cell (#4024)
-            if (/\bgit\s+[a-z][^\n|]*\|/.test(seg)) {
+            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);
             }
@@ -918,6 +933,13 @@ function extractPlanTaskInfos(content) {
         const nameArr = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(body, 'name');
         const hasName = nameArr.length > 0;
         const name = hasName ? nameArr[0].trim() : '';
+        // `(?:^|\s)` (not `\b`) so a hyphenated attribute ending in `auto_select`
+        // can never be mistaken for the real attribute — the same defensive
+        // anchor as extractOptionIds' `id` match below (#4095).
+        const autoSelectMatch = attrs.match(/(?:^|\s)auto_select\s*=\s*["']([^"']*)["']/);
+        const autoSelect = autoSelectMatch ? autoSelectMatch[1] : null;
+        const optionsArr = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(body, 'options');
+        const optionIds = optionsArr.length > 0 ? extractOptionIds(optionsArr[0]) : [];
         infos.push({
             name,
             type,
@@ -935,6 +957,8 @@ function extractPlanTaskInfos(content) {
             hasHowToVerify: /<how-to-verify[\s>]/.test(body),
             hasDecision: /<decision[\s>]/.test(body),
             hasOptions: /<options[\s>]/.test(body),
+            autoSelect,
+            optionIds,
             hasInstructions: /<instructions[\s>]/.test(body),
             hasVerification: /<verification[\s>]/.test(body),
             hasResumeSignal: /<resume-signal[\s>]/.test(body),
@@ -946,6 +970,35 @@ function extractPlanTaskInfos(content) {
     }
     return infos;
 }
+/**
+ * Extract the `id` attribute of every `<option id="…">` opening tag found in
+ * `optionsBody` (the inner text of one `<options>…</options>` block), in
+ * document order. Bounded attribute scan (`[^>]{0,500}`), mirroring the same
+ * ReDoS-safe idiom `extractPlanTaskInfos` uses for the `<task type="…">`
+ * attribute string — this file's established pattern for reading an
+ * attribute value without a general XML parser (#4095).
+ */
+function extractOptionIds(optionsBody) {
+    const ids = [];
+    if (typeof optionsBody !== 'string' || optionsBody.length === 0)
+        return ids;
+    const OPTION_OPEN_RE = /<option(\s[^>]{0,500})?>/g;
+    let match;
+    while ((match = OPTION_OPEN_RE.exec(optionsBody)) !== null) {
+        const attrs = match[1] ?? '';
+        // `(?:^|\s)` (not `\b`) so a decoy attribute like `data-id="…"` inside
+        // the same opening tag cannot be mistaken for the real `id` — `\b`
+        // matches at the `-`→`i` boundary too, which `.match()`'s
+        // first-hit-wins semantics would then silently prefer (#4095).
+        const idMatch = attrs.match(/(?:^|\s)id\s*=\s*["']([^"']{1,200})["']/);
+        if (idMatch)
+            ids.push(idMatch[1]);
+        if (match.index === OPTION_OPEN_RE.lastIndex) {
+            OPTION_OPEN_RE.lastIndex++;
+        }
+    }
+    return ids;
+}
 function isCheckpointType(type) {
     return type.startsWith('checkpoint:');
 }
@@ -988,6 +1041,15 @@ function validatePlanTaskStructure(task) {
                     errors.push(`Task '${taskName}' missing <decision>`);
                 if (!task.hasOptions)
                     errors.push(`Task '${taskName}' missing <options>`);
+                if (task.autoSelect !== null) {
+                    if (task.autoSelect.length === 0) {
+                        errors.push(`Task '${taskName}' auto_select is empty — name an <option id="…">`);
+                    }
+                    else if (task.hasOptions && !task.optionIds.includes(task.autoSelect)) {
+                        errors.push(`Task '${taskName}' auto_select="${task.autoSelect}" does not match any `
+                            + `<option id="…"> (available: ${task.optionIds.join(', ') || 'none'})`);
+                    }
+                }
                 break;
             case 'checkpoint:human-action':
                 if (!task.hasAction)
@@ -1157,6 +1219,11 @@ function cmdVerifyPhaseCompleteness(cwd, phase, raw) {
         warnings,
     }, raw, errors.length === 0 ? 'complete' : 'incomplete');
 }
+// #4678: citations may carry a trailing line suffix (":42", ":1-20") that
+// describes a location inside the file, not part of the path itself.
+function stripLineSuffix(ref) {
+    return ref.replace(/:\d+(?:-\d+)?$/, '');
+}
 function cmdVerifyReferences(cwd, filePath, raw) {
     if (!filePath) {
         error('file path required');
@@ -1172,9 +1239,10 @@ function cmdVerifyReferences(cwd, filePath, raw) {
     const atRefs = content.match(/@([^\s\n,)]+\/[^\s\n,)]+)/g) || [];
     for (const ref of atRefs) {
         const cleanRef = ref.slice(1);
-        const resolved = cleanRef.startsWith('~/')
-            ? node_path_1.default.join(process.env['HOME'] || '', cleanRef.slice(2))
-            : node_path_1.default.join(cwd, cleanRef);
+        const fsRef = stripLineSuffix(cleanRef);
+        const resolved = fsRef.startsWith('~/')
+            ? node_path_1.default.join(process.env['HOME'] || '', fsRef.slice(2))
+            : node_path_1.default.join(cwd, fsRef);
         if (node_fs_1.default.existsSync(resolved)) {
             found.push(cleanRef);
         }
@@ -1182,14 +1250,14 @@ function cmdVerifyReferences(cwd, filePath, raw) {
             missing.push(cleanRef);
         }
     }
-    const backtickRefs = content.match(/`([^`]+\/[^`]+\.[a-zA-Z]{1,10})`/g) || [];
+    const backtickRefs = content.match(/`([^`]+\/[^`]+\.[a-zA-Z]{1,10}(?::\d+(?:-\d+)?)?)`/g) || [];
     for (const ref of backtickRefs) {
         const cleanRef = ref.slice(1, -1);
         if (cleanRef.startsWith('http') || cleanRef.includes('${') || cleanRef.includes('{{'))
             continue;
         if (found.includes(cleanRef) || missing.includes(cleanRef))
             continue;
-        const resolved = node_path_1.default.join(cwd, cleanRef);
+        const resolved = node_path_1.default.join(cwd, stripLineSuffix(cleanRef));
         if (node_fs_1.default.existsSync(resolved)) {
             found.push(cleanRef);
         }
@@ -1251,28 +1319,75 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
         const artFullPath = node_path_1.default.join(cwd, artPath);
         const exists = node_fs_1.default.existsSync(artFullPath);
         const check = { path: artPath, exists, issues: [], passed: false };
-        if (exists) {
-            const fileContent = (0, shell_command_projection_cjs_1.platformReadSync)(artFullPath) || '';
-            const lineCount = fileContent.split('\n').length;
-            if (artifact['min_lines'] && lineCount < artifact['min_lines']) {
-                check['issues'].push(`Only ${lineCount} lines, need ${artifact['min_lines']}`);
-            }
-            if (artifact['contains'] && !fileContent.includes(artifact['contains'])) {
-                check['issues'].push(`Missing pattern: ${artifact['contains']}`);
-            }
-            if (artifact['exports']) {
-                const exports = Array.isArray(artifact['exports'])
-                    ? artifact['exports']
-                    : [artifact['exports']];
-                for (const exp of exports) {
-                    if (!fileContent.includes(exp))
-                        check['issues'].push(`Missing export: ${exp}`);
+        // #4685: one artifact's I/O problem is that artifact's failure, never the
+        // whole plan's. `safeReadFile` rethrows every errno except ENOENT, so before
+        // this an unreadable entry — a directory most commonly, but equally an EACCES
+        // file or a dangling mount — threw out of the loop and the command reported
+        // NOTHING: not the offending entry, and not the plan's other, perfectly good
+        // artifacts either. A check that disappears is worse than a check that fails,
+        // because a failure is visible.
+        //
+        // Scope of this guard, stated precisely (review nit): the `try` encloses the
+        // whole per-artifact body, but the only statements in it that can throw are the
+        // `statSync` and the read — the `min_lines`/`contains`/`exports` checks below
+        // are pure string operations. So this catches I/O, and nothing here is a
+        // deliberate guard around those criteria checks. A path `fs.existsSync` already
+        // rejected never reaches here either (that is the `File not found` branch), so
+        // this is not a claim to catch every way a path can be unusable.
+        try {
+            if (exists) {
+                // A directory is reported as its own kind of failure, distinct from
+                // `File not found`: the path resolved, it simply is not the thing an
+                // artifact entry can be checked against. Verifying a directory (matching
+                // `contains:`/`min_lines:`/`exports:` across the files inside it) is a
+                // feature decision, deliberately not made here.
+                if (node_fs_1.default.statSync(artFullPath).isDirectory()) {
+                    check['issues'].push('Not a file: path is a directory');
+                }
+                else {
+                    // `safeReadFile` returns null on ENOENT, and `|| ''` would turn that
+                    // into an empty file — which an entry carrying only `path`/`provides`
+                    // would then PASS, having checked nothing. `statSync` just succeeded, so
+                    // a null here means the artifact went away mid-check. Report that rather
+                    // than inheriting a pass from it. (Pre-existing above this fix, reachable
+                    // through the same race after `existsSync`; found in review.)
+                    const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(artFullPath);
+                    if (rawContent === null) {
+                        check['issues'].push('Unreadable: disappeared during check');
+                        results.push(check);
+                        continue;
+                    }
+                    const fileContent = rawContent;
+                    const lineCount = fileContent.split('\n').length;
+                    if (artifact['min_lines'] && lineCount < artifact['min_lines']) {
+                        check['issues'].push(`Only ${lineCount} lines, need ${artifact['min_lines']}`);
+                    }
+                    if (artifact['contains'] && !fileContent.includes(artifact['contains'])) {
+                        check['issues'].push(`Missing pattern: ${artifact['contains']}`);
+                    }
+                    if (artifact['exports']) {
+                        const exports = Array.isArray(artifact['exports'])
+                            ? artifact['exports']
+                            : [artifact['exports']];
+                        for (const exp of exports) {
+                            if (!fileContent.includes(exp))
+                                check['issues'].push(`Missing export: ${exp}`);
+                        }
+                    }
+                    check['passed'] = check['issues'].length === 0;
                 }
             }
-            check['passed'] = check['issues'].length === 0;
+            else {
+                check['issues'].push('File not found');
+            }
         }
-        else {
-            check['issues'].push('File not found');
+        catch (err) {
+            // Unreadable for some other reason. Record the errno rather than a generic
+            // message — an operator seeing EACCES acts differently from one seeing EIO —
+            // and leave `passed` false.
+            const e = err;
+            check['issues'].push(`Unreadable: ${e.code || (e.message ?? String(err))}`);
+            check['passed'] = false;
         }
         results.push(check);
     }
@@ -1378,11 +1493,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';
@@ -1390,7 +1505,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:`
@@ -1458,8 +1573,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.
@@ -1467,7 +1582,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)) {
@@ -1823,9 +1938,9 @@ function resolvePhaseDirByToken(phasesDir, phaseArg) {
     const matched = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
     if (matched)
         return node_path_1.default.join(phasesDir, matched);
-    const check = (0, security_cjs_1.validatePath)(phaseArg, phasesDir);
-    if (check.safe && node_fs_1.default.existsSync(check.resolved))
-        return check.resolved;
+    const contained = (0, security_cjs_2.tryWithinRoot)(phaseArg, phasesDir);
+    if (contained !== null && node_fs_1.default.existsSync(contained))
+        return contained;
     return null;
 }
 /**
@@ -1986,6 +2101,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
@@ -2034,16 +2253,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({
@@ -2056,6 +2304,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 = [];
@@ -2076,6 +2345,8 @@ function cmdVerifyCodebaseDrift(cwd, raw) {
             // 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')
@@ -2154,5 +2425,6 @@ module.exports = {
     cmdVerifyCodebaseDrift,
     computeContextDrift,
     cmdVerifyContextDrift,
+    cmdStampCodebaseMap,
     STATE_HEAD_ADVISORY_COMMITS,
 };

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

@@ -733,6 +733,7 @@ module.exports = {
     inspectWorkstream,
     isCompletedInventory: workstream_inventory_builder_cjs_1.isCompletedInventory,
     listWorkstreamInventories,
+    readCurrentMilestoneVersion,
     sortWorkstreamInventories,
     workstreamsRoot,
 };