@opengsd/gsd-core 1.14.0 → 1.15.0

package/gsd-core/bin/lib/undo-commit-selection.cjs

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Undo Commit Selection — issue #4661 (absorbed into epic #4906, Phase 5).
+ *
+ * Pure scope-matching logic for `/gsd:undo --phase N` / `--plan N-M`, replacing
+ * the two hand-rolled `git log --oneline | grep -E ...` pipelines that used to
+ * live in `gsd-core/workflows/undo.md`. Those greps were unanchored substring
+ * matches against a live regex built from unvalidated user input — four
+ * documented bug classes (see #4661):
+ *
+ *   1. The id was interpolated raw into an ERE: `.` and `+` are live
+ *      metacharacters there, so a malformed or merely differently-shaped id
+ *      silently matched the WRONG phase.
+ *   2. The grep was unanchored, so a commit that only MENTIONS a scope
+ *      (`docs(99-01): explain feat(03-01): commit convention`) was wrongly
+ *      selected as a DECLARATION of it.
+ *   3. Phase-mode's `\):` suffix and plan-mode's missing suffix disagreed on
+ *      the same commit (`feat(03-01)!: breaking change`).
+ *   4. The "obvious" fix — anchoring `git log --oneline`'s record start —
+ *      is a trap: it silently drops `fixup! ...` / `Revert "..."` wrapper
+ *      commits (a worse failure, a silent partial revert) and returns zero
+ *      matches under `color.ui=always` (ANSI codes precede the sha).
+ *
+ * This module closes all four by parsing each commit subject through the
+ * SAME anchored conventional-commit grammar the changelog/PR-title gate uses
+ * (`HEADER_RE`, reused verbatim from `scripts/release-notes/conventional-title.cjs`
+ * — see the require() below), then comparing the extracted scope to the
+ * caller-supplied target id by exact STRING EQUALITY. No regex is built from
+ * user input at any point past `validatePhaseNumber` (src/security.cts),
+ * which the CLI caller (`gsd-tools.cjs query select-revert-commits`) runs
+ * BEFORE this module ever sees the id.
+ *
+ * Deliberately no `fs`/`child_process` in this file: it operates purely on
+ * `{sha, subject}` records the caller already fetched (e.g. via `git log
+ * --format=%H%x00%s`), so it is unit-testable without touching git or the
+ * filesystem.
+ *
+ * KNOWN LIMIT (documented, not a defect): `unwrapSubject` unwraps ONE level
+ * of a `fixup! `/`squash! `/`Revert "..."` wrapper. A doubly-wrapped subject
+ * (e.g. `Revert "fixup! feat(03-01): work"`) is treated as unparseable (no
+ * declared scope) after that single unwrap — it is NOT selected, never
+ * mis-selected. This bounds the module to the wrapper shapes git itself
+ * produces (`fixup!`/`squash!` from `--fixup`/`--squash`, `Revert "..."` from
+ * `git revert`), each of which wraps a single ordinary commit subject, not
+ * another wrapper.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectCommitsByDeclaredScope = selectCommitsByDeclaredScope;
+const node_path_1 = __importDefault(require("node:path"));
+// Reuse the exact HEADER_RE the changelog classifier and PR-title CI gate
+// already depend on (#1549) — never fork a second copy of this grammar. A
+// bare `require()` (not a TS `import ... = require(...)`) is used
+// deliberately: `scripts/` sits outside this build's `rootDir` ("src", see
+// tsconfig.build.json) and carries no `.d.ts`, so a type-checked import-equals
+// would fail module resolution (TS7016) under `strict`/`noImplicitAny`. A
+// plain `require()` resolves through Node's ambient `NodeRequire` type
+// (`(id: string) => any`) instead, sidestepping that check entirely — the
+// cast below is the only place the resulting shape is asserted.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const conventionalTitle = require(node_path_1.default.resolve(__dirname, '..', '..', '..', 'scripts', 'release-notes', 'conventional-title.cjs'));
+const { HEADER_RE } = conventionalTitle;
+// ─── Subject unwrapping (Known limit: exactly ONE level) ──────────────────
+const FIXUP_PREFIX = 'fixup! ';
+const SQUASH_PREFIX = 'squash! ';
+const REVERT_RE = /^Revert "(.*)"$/;
+/**
+ * Strip exactly one `fixup! `/`squash! `/`Revert "..."` wrapper layer off a
+ * commit subject, returning the (possibly) unwrapped remainder. Never
+ * recurses — a doubly-wrapped subject is returned with only its outermost
+ * layer removed, which is intentionally still unparseable by `HEADER_RE` (see
+ * module doc comment).
+ */
+function unwrapSubject(subject) {
+    if (subject.startsWith(FIXUP_PREFIX))
+        return subject.slice(FIXUP_PREFIX.length);
+    if (subject.startsWith(SQUASH_PREFIX))
+        return subject.slice(SQUASH_PREFIX.length);
+    const revertMatch = REVERT_RE.exec(subject);
+    if (revertMatch)
+        return revertMatch[1];
+    return subject;
+}
+/**
+ * Parse a (possibly wrapped) commit subject into its declared conventional-
+ * commit scope, or `null` when the subject carries no parseable scope: no
+ * clean `type[(scope)][!]:` header at all, or a header with no `(scope)`
+ * group. Never regex-matches against untrusted `targetId` — this function
+ * only ever consumes the commit's OWN subject text.
+ */
+function parseDeclaredScope(subject) {
+    const unwrapped = unwrapSubject(subject);
+    const m = HEADER_RE.exec(unwrapped);
+    if (!m)
+        return null;
+    const scopeWithParens = m[2]; // e.g. "(03-01)" — includes parens, or undefined
+    if (!scopeWithParens)
+        return null;
+    // HEADER_RE's scope group is `\([^)]*\)` — always at least the two paren
+    // characters when present, so slicing them off is safe unconditionally.
+    return scopeWithParens.slice(1, -1);
+}
+/**
+ * Select commits whose DECLARED conventional-commit scope identifies
+ * `targetId`, by exact string equality (`'plan'` mode) or exact-or-phase-
+ * prefixed equality (`'phase'` mode). `targetId` is assumed ALREADY
+ * VALIDATED/NORMALIZED by the caller (e.g. via `validatePhaseNumber` from
+ * `src/security.cts`) — this function performs no validation of its own, and
+ * never builds a regex from it (string equality / `startsWith` only), so a
+ * malformed or metacharacter-laden `targetId` cannot cause a wildcard-style
+ * over-match the way the retired grep pipelines could.
+ */
+function selectCommitsByDeclaredScope(commits, targetId, mode = 'plan') {
+    const phasePrefix = `${targetId}-`;
+    const classified = commits.map(({ sha, subject }) => {
+        const parsedScope = parseDeclaredScope(subject);
+        let matched = false;
+        if (parsedScope !== null) {
+            matched = mode === 'phase'
+                ? parsedScope === targetId || parsedScope.startsWith(phasePrefix)
+                : parsedScope === targetId;
+        }
+        return { sha, subject, parsedScope, matched };
+    });
+    const selected = classified
+        .filter((c) => c.matched)
+        .map(({ sha, subject }) => ({ sha, subject }));
+    return { selected, classified };
+}

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

@@ -51,7 +51,7 @@ const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const security_cjs_1 = require("./security.cjs");
 const { output, error } = io;
 const { extractPhaseToken, scopeToPhase } = phaseId;
-const { extractFrontmatter } = frontmatterMod;
+const { extractFrontmatter, FRONTMATTER_UNPARSEABLE } = frontmatterMod;
 const { normalizeLineEndings } = coreUtilsMod;
 const { SCOPE } = planningScopeMod;
 // ─── Constants ────────────────────────────────────────────────────────────────
@@ -102,8 +102,14 @@ const VERIFICATION_ROUTING_TABLE = {
     },
     stale: {
         status: 'stale',
-        next_action: 'Verification is stale. Re-run verify-work before transition.',
-        next_command: '',
+        // #4682: staleness means covered source files changed after the verifier
+        // last ran — the only remedy is re-running the verifier.
+        // /gsd-verify-work never rewrites VERIFICATION.md, so advising it from
+        // here was an advice loop. execute-phase resumes at the verification
+        // gates and re-runs the verifier (its resume tree routes a stale report
+        // to re-verification), which regenerates VERIFICATION.md and its digest.
+        next_action: 'Verification is stale — covered source files changed after the verifier last ran. Re-run execute-phase for this phase: it resumes at the verification gates and re-runs the verifier, regenerating VERIFICATION.md and its digest. verify-work alone cannot refresh a stale report.',
+        next_command: 'execute-phase',
     },
     // INTERNAL SENTINEL: constructed when no *-VERIFICATION.md file exists or when
     // the file has no parseable frontmatter status. Never emitted by the verifier.
@@ -112,6 +118,15 @@ const VERIFICATION_ROUTING_TABLE = {
         next_action: 'No verification report found — the verify step never completed. Running execute-phase is safe here: it resumes at the verification gates and does not re-run plans that already have a SUMMARY.md (see #2868).',
         next_command: 'execute-phase',
     },
+    // #4806: the report EXISTS but its frontmatter is not parseable YAML —
+    // fundamentally different from "missing" (the verify step DID run; re-running
+    // execute-phase cannot fix a YAML typo). Consumers treat any non-'passed'
+    // status as blocking, so this value fails safe while telling the truth.
+    unparseable: {
+        status: 'unparseable',
+        next_action: "The *-VERIFICATION.md frontmatter is not parseable YAML — fix the syntax error in the report itself. Re-running execute-phase cannot fix a YAML typo in an existing report.",
+        next_command: '',
+    },
     // INTERNAL SENTINEL: constructed when the file has a status value not in
     // VERIFIER_STATUSES. Never emitted by the verifier.
     unknown: {
@@ -174,8 +189,95 @@ function canonicalizeCoveredFiles(files) {
  * Bump on any change to the digest's input shape (path list, hashing order,
  * per-file hash algorithm) so an old stored digest can never collide with a
  * differently-computed new one — a version mismatch is just a mismatch.
+ *
+ * Version history:
+ *   v1 (#4155) — every covered path's whole bytes, uniformly.
+ *   v2 (#4623) — repo-wide planning documents (`isSharedPlanningDoc`) are
+ *                excluded from the hash by construction.
+ *
+ * A stored digest names its own version (`v<N>:sha256:…`), and
+ * `readVerificationStatus` recomputes under the STORED version rather than
+ * this constant — so bumping it does not flip every already-verified phase
+ * to `stale` on upgrade. A legacy v1 report keeps v1 semantics, shared
+ * documents included, until it is re-fingerprinted; only a version outside
+ * `KNOWN_FINGERPRINT_VERSIONS` is unrecomputable and fails closed.
  */
-const FINGERPRINT_VERSION = 1;
+const FINGERPRINT_VERSION = 2;
+const KNOWN_FINGERPRINT_VERSIONS = new Set([1, 2]);
+/**
+ * #4623: the planning roots whose DIRECT children are repo-wide planning
+ * documents, as project-root-relative posix paths. Always `.planning`; plus
+ * the phase's OWN planning root when a phase directory is known — the parent
+ * of its `phases/` directory, which is how `planningDir` lays out every
+ * scope (`.planning`, `.planning/<project>`, `.planning/workstreams/<ws>`,
+ * `.planning/<project>/workstreams/<ws>`; `planning-workspace.cts`). Derived
+ * from the phase's position rather than from a list of layouts so a
+ * workstream-scoped `ROADMAP.md` is recognised without this function
+ * knowing what a workstream is, and so `.planning/research/notes.md` is
+ * NOT mistaken for one — lexically the two are indistinguishable from
+ * `.planning/<project>/ROADMAP.md`. A phase directory that does not sit
+ * under the project root (unit fixtures at a bare tmpdir) contributes no
+ * extra root.
+ */
+function sharedPlanningRoots(projectRoot, phaseDir) {
+    const roots = ['.planning'];
+    if (phaseDir) {
+        const phasesDir = node_path_1.default.dirname(node_path_1.default.resolve(phaseDir));
+        const planningDir = node_path_1.default.dirname(phasesDir);
+        const rel = normalizeRel(node_path_1.default.relative(node_path_1.default.resolve(projectRoot), planningDir));
+        // Two structural checks, both load-bearing: the phase dir's PARENT must be
+        // the `phases/` directory `planningDir` lays every scope out with, and the
+        // derived root must sit inside `.planning/`. Without them any accepted
+        // directory — `<root>/src/phases/01-fake` — would nominate `src` as a
+        // planning root and silently drop real implementation evidence from the
+        // digest (found by the cross-AI review of this change). A shape that fails
+        // either check contributes no extra root; `.planning` itself is already
+        // present.
+        if (node_path_1.default.basename(phasesDir) === 'phases' &&
+            rel.startsWith('.planning/') &&
+            !rel.includes('/../') &&
+            !roots.includes(rel)) {
+            roots.push(rel);
+        }
+    }
+    return roots;
+}
+/**
+ * #4623: a covered path names a repo-wide planning document when it sits
+ * DIRECTLY under one of `sharedPlanningRoots` — `ROADMAP.md`,
+ * `REQUIREMENTS.md`, `STATE.md`, `PROJECT.md`, `MILESTONES.md`,
+ * `config.json`, … — as opposed to a phase's own artifacts under
+ * `<root>/phases/<phase>/` or a research note under `.planning/research/`.
+ * Every phase rewrites these as ordinary bookkeeping (a roadmap checkbox, a
+ * requirement's traceability cell, STATE.md's position), so hashing their
+ * whole bytes into one phase's digest coupled every phase's staleness to
+ * every other phase's close — and to its OWN close, since `phase.complete`
+ * and `requirements mark-complete` write them after the verifier has
+ * already run.
+ *
+ * Defined by position, not by a name list, so the set cannot drift as new
+ * top-level planning documents appear (the tree already carries a dozen).
+ * `rel` is expected posix-normalized (`canonicalizeCoveredFiles`), so a
+ * `./.planning/ROADMAP.md` spelling has already collapsed to the bare form.
+ */
+function isSharedPlanningDoc(rel, roots = ['.planning']) {
+    if (rel === '' || rel.endsWith('/'))
+        return false;
+    return roots.includes(node_path_1.default.posix.dirname(rel));
+}
+/**
+ * #4623: the fingerprint version a stored `covered_digest` was computed
+ * under, or `null` when the prefix is absent, malformed, or names a version
+ * this build cannot recompute (an unknown version is a mismatch by
+ * construction — the fail-closed shape `FINGERPRINT_VERSION`'s doc promises).
+ */
+function parseFingerprintVersion(digest) {
+    const m = /^v(\d+):sha256:/.exec(digest);
+    if (!m)
+        return null;
+    const version = Number(m[1]);
+    return KNOWN_FINGERPRINT_VERSIONS.has(version) ? version : null;
+}
 /**
  * #4155: recompute the deterministic content fingerprint over a verifier's
  * declared covered-input set (phase PLAN/SUMMARY, mapped requirements,
@@ -216,14 +318,23 @@ const FINGERPRINT_VERSION = 1;
  * confinement work (against `projectRoot`, the correct boundary for this
  * data), so no security property is lost by bypassing a narrower seam here.
  */
-function computeCoveredDigest(projectRoot, coveredFiles) {
+function computeCoveredDigest(projectRoot, coveredFiles, version = FINGERPRINT_VERSION, opts = {}) {
+    // #4623: `version` selects the input shape to hash under — the CURRENT
+    // one for a fresh fingerprint (the CLI verb), or the STORED one when
+    // `readVerificationStatus` recomputes against a report's own digest.
+    // `opts.phaseDir` lets v2 recognise the phase's own planning root
+    // (`sharedPlanningRoots`); without it only `.planning/` itself is shared.
+    if (!KNOWN_FINGERPRINT_VERSIONS.has(version))
+        return null;
     const uniqueSorted = canonicalizeCoveredFiles(coveredFiles);
     if (uniqueSorted.length === 0)
         return null;
+    const sharedRoots = version >= 2 ? sharedPlanningRoots(projectRoot, opts.phaseDir) : [];
+    let hashed = 0;
     // Canonicalize the root ONCE — every candidate's realpath is checked against
     // this, not the possibly-symlinked `projectRoot` argument itself. Always via
     // the REAL fs, never fsImpl: `projectRoot` is a trusted anchor the CALLER
-    // derived (findProjectRoot), not attacker-influenced covered-input data —
+    // derived (resolveProjectRoot), not attacker-influenced covered-input data —
     // routing it through a caller-scoped containment seam (e.g. #4155's
     // containmentEnforcingVerificationFs, confined to `.planning/`, a proper
     // SUBSET of `projectRoot`) would reject the root itself and fail every
@@ -262,6 +373,15 @@ function computeCoveredDigest(projectRoot, coveredFiles) {
             const st = node_fs_1.default.statSync(real);
             if (!st.isFile())
                 return null;
+            // #4623 (v2+): a repo-wide planning document is VALIDATED exactly as
+            // every other covered path — confined, present, a regular file; the
+            // fail-closed contract above is unchanged — but its bytes contribute
+            // nothing to the digest. It may stay declared in `covered_files` (the
+            // verifier's instructions long said to list the mapped requirement,
+            // and every report already written does); its bookkeeping churn can
+            // no longer read as drift.
+            if (isSharedPlanningDoc(rel, sharedRoots))
+                continue;
             bytes = node_fs_1.default.readFileSync(real);
         }
         catch {
@@ -269,12 +389,19 @@ function computeCoveredDigest(projectRoot, coveredFiles) {
         }
         const fileHash = node_crypto_1.default.createHash('sha256').update(bytes).digest('hex');
         parts.push(`${rel}\n${fileHash}\n`);
+        hashed++;
     }
+    // #4623 (v2+): a declaration made ONLY of shared planning documents has no
+    // evidence in it at all — a constant digest over the header would satisfy
+    // the fingerprint pair while grounding the verification in nothing. Fail
+    // closed, the same way an empty declaration does.
+    if (version >= 2 && hashed === 0)
+        return null;
     const aggregate = node_crypto_1.default
         .createHash('sha256')
-        .update(`v${FINGERPRINT_VERSION}\n${parts.join('')}`, 'utf-8')
+        .update(`v${version}\n${parts.join('')}`, 'utf-8')
         .digest('hex');
-    return `v${FINGERPRINT_VERSION}:sha256:${aggregate}`;
+    return `v${version}:sha256:${aggregate}`;
 }
 /**
  * #4155: the content fingerprint only recomputes digests for paths the
@@ -687,6 +814,16 @@ function readVerificationStatus(phaseDir, opts = {}) {
         // same root cause as the false-clean class fixed elsewhere in #3707-CR.
         const content = normalizeLineEndings(fsImpl.readFileSync(filePath, 'utf-8'));
         fm = extractFrontmatter(content, filePath);
+        // #4806: an unparseable frontmatter block is NOT "missing" — the file
+        // exists and verification ran. Report a distinct status so the caller is
+        // sent to fix the YAML, not to re-run execute-phase.
+        if (fm[FRONTMATTER_UNPARSEABLE] === true) {
+            return {
+                status: 'unparseable',
+                next_action: "The *-VERIFICATION.md frontmatter is not parseable YAML — fix the syntax error in the report itself. Re-running execute-phase cannot fix a YAML typo in an existing report.",
+                next_command: '',
+            };
+        }
         const statusVal = fm['status'];
         // status is always a scalar string in a well-formed VERIFICATION.md frontmatter;
         // only accept string values — arrays and objects are not valid status values.
@@ -741,9 +878,19 @@ function readVerificationStatus(phaseDir, opts = {}) {
         // short-circuit in turn: the live-directory re-scan (for a plan/summary
         // added AFTER verification and never declared in covered_files) only
         // runs once the digest itself has already matched.
+        //
+        // #4623: recompute under the STORED digest's own version, not the
+        // current constant — a v1 report written before the shared-document
+        // exclusion keeps v1 semantics rather than going stale on upgrade. An
+        // unknown version parses to `null`, which `computeCoveredDigest`
+        // refuses (returns `null`), so the compare below fails closed.
+        const storedVersion = hasWellFormedFingerprint && typeof coveredDigestVal === 'string'
+            ? parseFingerprintVersion(coveredDigestVal)
+            : null;
         isStale =
             !hasWellFormedFingerprint ||
-                computeCoveredDigest((0, project_root_cjs_1.findProjectRoot)(phaseDir), coveredFilesVal) !== coveredDigestVal ||
+                storedVersion === null ||
+                computeCoveredDigest((0, project_root_cjs_1.resolveProjectRoot)(phaseDir), coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal ||
                 !allCurrentArtifactsCovered(phaseDir, coveredFilesVal);
     }
     else {
@@ -761,7 +908,10 @@ function readVerificationStatus(phaseDir, opts = {}) {
         return {
             status: entry.status,
             next_action: entry.next_action,
-            next_command: projectNextCommand('verify-work', runtime, phaseArg),
+            // #4682: execute-phase resumes at the verification gates and re-runs
+            // the verifier, regenerating VERIFICATION.md and its digest — the same
+            // routing the `missing` sentinel has used since #2868.
+            next_command: projectNextCommand('execute-phase', runtime, phaseArg),
         };
     }
     // 3. Route — exclude internal sentinels from raw-file lookup (they are
@@ -898,6 +1048,69 @@ function cmdVerificationResolveFile(cwd, phaseDirArg, raw) {
     }
     output({ verification_file: verificationPath }, raw, verificationPath);
 }
+/**
+ * #4623: parse the argv tokens after `verification.fingerprint <phaseDir>`
+ * into a covered-file list. The router hands over a raw positional slice,
+ * so every `--files`-style form other `gsd-tools` verbs accept (`commit
+ * --files a b`, `docs/CLI-TOOLS.md`) used to reach `computeCoveredDigest`
+ * with the literal token `--files` — or an unsplit `"a,b"` — as a covered
+ * path, and the whole command failed closed with "a covered file is
+ * missing, unreadable, or escapes the project root". On the reporting
+ * project that message convinced two people the digest was permanently
+ * unrecomputable.
+ *
+ * Accepted, all equivalent and freely mixed:
+ *   - bare positionals            `a b`            (the documented form, unchanged)
+ *   - a single flag               `--files a`
+ *   - a comma-separated value     `--files a,b`    (also `--files=a,b`)
+ *   - a repeated flag             `--files a --files b`
+ *
+ * Only a `--files` VALUE is comma-split: a bare positional keeps its bytes,
+ * so the documented form's behaviour on a comma-bearing filename is
+ * unchanged. Any other `--flag` is an explicit usage error, never a path —
+ * a mis-typed flag must not fail as "file missing" again. (`--raw` never
+ * reaches here; the CLI entry point splices it out before routing.)
+ */
+function parseFingerprintFileArgs(tokens) {
+    const files = [];
+    const EMPTY_VALUE = '--files requires at least one path for verification.fingerprint (a path, or a comma-separated list)';
+    const splitList = (value) => value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === '--files') {
+            const value = tokens[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                return { error: '--files requires a value for verification.fingerprint (a path, or a comma-separated list)' };
+            }
+            const list = splitList(value);
+            // An empty or all-comma value is a usage error, never a silent no-op —
+            // the caller would otherwise meet the generic zero-files error and go
+            // looking for a missing path.
+            if (list.length === 0)
+                return { error: EMPTY_VALUE };
+            files.push(...list);
+            i++;
+        }
+        else if (token.startsWith('--files=')) {
+            const list = splitList(token.slice('--files='.length));
+            if (list.length === 0)
+                return { error: EMPTY_VALUE };
+            files.push(...list);
+        }
+        else if (token.startsWith('--')) {
+            return {
+                error: `unknown flag ${token} for verification.fingerprint (covered files are bare positionals or --files <a[,b]>, repeatable)`,
+            };
+        }
+        else {
+            files.push(token);
+        }
+    }
+    return { files };
+}
 /**
  * CLI command handler (#4155): compute the covered-input fingerprint the
  * verifier embeds in VERIFICATION.md frontmatter (`covered_files`,
@@ -913,7 +1126,13 @@ function cmdVerificationResolveFile(cwd, phaseDirArg, raw) {
  * @param cwd         - Current working directory.
  * @param phaseDirArg - Phase directory path (absolute or relative to cwd);
  *                       its project root is the base covered paths resolve against.
- * @param files       - Covered-input paths, relative to the project root.
+ *                       Must be an existing directory (#4623): with the
+ *                       phase dir omitted, the first covered file used to be
+ *                       taken as the phase dir and the rest hashed — a
+ *                       plausible digest over the wrong set, at exit 0.
+ * @param fileArgs    - The argv tokens after the phase dir, parsed by
+ *                       `parseFingerprintFileArgs`: covered-input paths
+ *                       relative to the project root, bare or via `--files`.
  * @param raw         - Whether to emit raw (non-JSON) output: just the
  *                       `covered_digest` string, so `VAR=$(gsd_run query
  *                       verification.fingerprint "$PHASE_DIR" ... --raw)` is
@@ -921,17 +1140,34 @@ function cmdVerificationResolveFile(cwd, phaseDirArg, raw) {
  *                       from the caller's own input list in that mode, so
  *                       only the computed digest needs a raw form.
  */
-function cmdVerificationFingerprint(cwd, phaseDirArg, files, raw) {
+function cmdVerificationFingerprint(cwd, phaseDirArg, fileArgs, raw) {
     if (!phaseDirArg) {
         error('phase directory required for verification.fingerprint');
         return;
     }
+    const phaseDir = node_path_1.default.resolve(cwd, phaseDirArg);
+    let phaseDirIsDir = false;
+    try {
+        phaseDirIsDir = node_fs_1.default.statSync(phaseDir).isDirectory();
+    }
+    catch {
+        // not found → not a directory
+    }
+    if (!phaseDirIsDir) {
+        error(`phase directory not found: ${phaseDirArg} — verification.fingerprint takes the phase directory first, then the covered files`);
+        return;
+    }
+    const parsed = parseFingerprintFileArgs(fileArgs);
+    if ('error' in parsed) {
+        error(parsed.error);
+        return;
+    }
+    const files = parsed.files;
     if (files.length === 0) {
         error('at least one covered file required for verification.fingerprint');
         return;
     }
-    const phaseDir = node_path_1.default.resolve(cwd, phaseDirArg);
-    const projectRoot = (0, project_root_cjs_1.findProjectRoot)(phaseDir);
+    const projectRoot = (0, project_root_cjs_1.resolveProjectRoot)(phaseDir);
     // canonicalizeCoveredFiles here is for the emitted `covered_files` field —
     // computeCoveredDigest canonicalizes its own `coveredFiles` argument
     // internally too (it must, for callers like readVerificationStatus that
@@ -939,8 +1175,21 @@ function cmdVerificationFingerprint(cwd, phaseDirArg, files, raw) {
     // already-canonical list keeps that internal pass a cheap no-op rather
     // than a second meaningfully different canonicalization.
     const uniqueSorted = canonicalizeCoveredFiles(files);
-    const digest = computeCoveredDigest(projectRoot, uniqueSorted);
+    const digest = computeCoveredDigest(projectRoot, uniqueSorted, FINGERPRINT_VERSION, { phaseDir });
     if (digest === null) {
+        // #4623: name the one null that is NOT a bad path — a declaration made
+        // only of shared planning documents hashes nothing under v2, and the
+        // generic message below would send the caller looking for a missing file
+        // that is not missing. Discriminated AFTER the v2 attempt, and only when a
+        // v1 pass over the same list (which hashes, and therefore validates, every
+        // path) succeeds: an all-shared list with a missing or directory member is
+        // a bad path first, and gets the generic message.
+        const sharedRoots = sharedPlanningRoots(projectRoot, phaseDir);
+        if (uniqueSorted.every((f) => isSharedPlanningDoc(f, sharedRoots)) &&
+            computeCoveredDigest(projectRoot, uniqueSorted, 1) !== null) {
+            error(`could not compute fingerprint — every covered file is a repo-wide planning document (direct children of ${sharedRoots.join(', ')} never enter the digest); declare the phase's own artifacts and implementation files`);
+            return;
+        }
         error('could not compute fingerprint — a covered file is missing, unreadable, or escapes the project root');
         return;
     }
@@ -958,5 +1207,9 @@ module.exports = {
     cmdVerificationStatus,
     cmdVerificationResolveFile,
     computeCoveredDigest,
+    sharedPlanningRoots,
+    isSharedPlanningDoc,
+    parseFingerprintVersion,
+    parseFingerprintFileArgs,
     cmdVerificationFingerprint,
 };

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)
@@ -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';