@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/bin/lib/update-context.cjs

@@ -127,6 +127,23 @@ function preferFirst(entries, preferred) {
     const rest = entries.filter(([rt]) => rt !== preferred);
     return [...pref, ...rest];
 }
+// GLOBAL probe: absolute env candidates first (in preferFirst order, first
+// hasInstall hit wins), then $HOME-relative. Single resolver shared by the
+// preferredConfigDir fast path's same-path dedup and the full cascade (#4197),
+// so both compare against the global dir the resolution would actually select —
+// an env-directed candidate, not necessarily the $HOME-relative pathname.
+function resolveGlobalCandidate(fs, env, home, preferred) {
+    for (const [rt, absdir] of preferFirst(envRuntimeDirs({ env, home }), preferred)) {
+        if (hasInstall(fs, absdir))
+            return { runtime: rt, dir: node_path_1.default.resolve(absdir) };
+    }
+    for (const [rt, reldir] of preferFirst(exports.RUNTIME_DIRS, preferred)) {
+        const cand = node_path_1.default.resolve(home, reldir);
+        if (hasInstall(fs, cand))
+            return { runtime: rt, dir: cand };
+    }
+    return { runtime: '', dir: '' };
+}
 /**
  * Pure resolver. Returns { installedVersion, scope, runtime, gsdDir }.
  */
@@ -137,11 +154,17 @@ function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = ''
     // Fast path: a validated preferredConfigDir (custom --config-dir install).
     if (preferredConfigDir && hasInstall(fs, preferredConfigDir)) {
         const resolvedPref = node_path_1.default.resolve(preferredConfigDir);
+        // Same-path dedup the cascade applies (#4197): a preferred dir that IS the
+        // selected global install (an env candidate or the $HOME-relative dir) is
+        // GLOBAL even when cwd === $HOME also makes it the cwd-relative match.
+        const { dir: globalDir } = resolveGlobalCandidate(fs, env, home, preferred);
         let scope = 'GLOBAL';
-        for (const [, reldir] of exports.RUNTIME_DIRS) {
-            if (node_path_1.default.resolve(cwd, reldir) === resolvedPref) {
-                scope = 'LOCAL';
-                break;
+        if (resolvedPref !== globalDir) {
+            for (const [, reldir] of exports.RUNTIME_DIRS) {
+                if (node_path_1.default.resolve(cwd, reldir) === resolvedPref) {
+                    scope = 'LOCAL';
+                    break;
+                }
             }
         }
         return {
@@ -151,7 +174,6 @@ function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = ''
             gsdDir: preferredConfigDir,
         };
     }
-    const orderedEnv = preferFirst(envRuntimeDirs({ env, home }), preferred);
     const orderedRuntime = preferFirst(exports.RUNTIME_DIRS, preferred);
     // LOCAL probe (relative to cwd).
     let localRuntime = '', localDir = '';
@@ -163,25 +185,9 @@ function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = ''
             break;
         }
     }
-    // GLOBAL probe: absolute env candidates first, then $HOME-relative.
-    let globalRuntime = '', globalDir = '';
-    for (const [rt, absdir] of orderedEnv) {
-        if (hasInstall(fs, absdir)) {
-            globalRuntime = rt;
-            globalDir = node_path_1.default.resolve(absdir);
-            break;
-        }
-    }
-    if (!globalRuntime) {
-        for (const [rt, reldir] of orderedRuntime) {
-            const cand = node_path_1.default.resolve(home, reldir);
-            if (hasInstall(fs, cand)) {
-                globalRuntime = rt;
-                globalDir = cand;
-                break;
-            }
-        }
-    }
+    // GLOBAL probe: absolute env candidates first, then $HOME-relative — the
+    // same resolver the fast path dedups against.
+    const { runtime: globalRuntime, dir: globalDir } = resolveGlobalCandidate(fs, env, home, preferred);
     const localValid = trustedVersionAt(fs, localDir);
     const isLocal = !!localValid && (!globalDir || localDir !== globalDir);
     if (isLocal) {

package/gsd-core/bin/lib/vendor/js-yaml.cjs

@@ -1262,16 +1262,21 @@
                 state.result += _result;
             }
         }
+        function chargeMergeWork(state) {
+            state.totalMergeKeys++;
+            if (state.maxTotalMergeKeys !== -1 && state.totalMergeKeys > state.maxTotalMergeKeys) {
+                throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
+            }
+        }
         function mergeMappings(state, destination, source, overridableKeys) {
             if (!common2.isObject(source)) {
                 throwError(state, "cannot merge mappings; the provided source object is unacceptable");
             }
+            chargeMergeWork(state);
             var sourceKeys = Object.keys(source);
             for (var index = 0, quantity = sourceKeys.length; index < quantity; index += 1) {
                 var key = sourceKeys[index];
-                if (state.maxTotalMergeKeys !== -1 && ++state.totalMergeKeys > state.maxTotalMergeKeys) {
-                    throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
-                }
+                chargeMergeWork(state);
                 if (!_hasOwnProperty.call(destination, key)) {
                     setProperty(destination, key, source[key]);
                     overridableKeys[key] = true;
@@ -1299,6 +1304,9 @@
             }
             if (keyTag === "tag:yaml.org,2002:merge") {
                 if (Array.isArray(valueNode)) {
+                    if (valueNode.length > 100) {
+                        throwError(state, "abnormal merge sequence size");
+                    }
                     for (var _index = 0, _quantity = valueNode.length; _index < _quantity; _index += 1) {
                         mergeMappings(state, _result, valueNode[_index], overridableKeys);
                     }

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

@@ -48,9 +48,10 @@ const coreUtilsMod = require("./core-utils.cjs");
 const planningScopeMod = require("./planning-scope.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 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 ────────────────────────────────────────────────────────────────
@@ -101,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.
@@ -111,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: {
@@ -173,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 = 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).
  */
-const FINGERPRINT_VERSION = 1;
+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,
@@ -215,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
@@ -251,13 +363,25 @@ function computeCoveredDigest(projectRoot, coveredFiles) {
             // confinement check above is not enough. realpathSync resolves the
             // actual target; re-confining against realRoot closes that gap.
             const real = node_fs_1.default.realpathSync(resolved);
-            const realRel = node_path_1.default.relative(realRoot, real);
-            if (realRel === '' || realRel === '..' || realRel.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(realRel)) {
+            // Both operands are already realpath-resolved (this fn's own realpathSync calls
+            // above), so the shared containment comparison applies directly (ADR-4650) —
+            // no re-resolution through assertWithinRoot/tryWithinRoot, which would redo work
+            // this function already owns for its exists-vs-escaped tri-state.
+            if (!(0, security_cjs_1.isContainedIn)(real, realRoot)) {
                 return null;
             }
             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 {
@@ -265,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
@@ -471,7 +602,7 @@ function resolvePhaseArtifactFile(entries, bareName, options = {}) {
         // filtered out, and if that leaves nothing the code falls through to
         // `allowBare`/`null` deliberately.
         const scoped = options.phaseDirName
-            ? scopeToPhase(candidates, options.phaseDirName)
+            ? scopeToPhase(candidates, options.phaseDirName, options.convention)
             : candidates;
         if (scoped.length > 0)
             return scoped[0];
@@ -528,7 +659,7 @@ function resolveVerificationFile(entries, options = {}) {
 function resolveUatFile(entries, options = {}) {
     return resolvePhaseArtifactFile(entries, 'UAT.md', options);
 }
-function findStaleVerificationSummary(phaseDir, fsImpl = defaultFsImpl, phaseCleanCommitTimesMs = defaultPhaseCleanCommitTimesMs) {
+function findStaleVerificationSummary(phaseDir, fsImpl = defaultFsImpl, phaseCleanCommitTimesMs = defaultPhaseCleanCommitTimesMs, convention) {
     // FS errors (TOCTOU: a SUMMARY listed by scanPhasePlans then removed before statSync;
     // unreadable dir; broken symlink; file->dir swap) must degrade rather than throw
     // uncaught into callers that are NOT under the planning lock (init.manager /
@@ -544,9 +675,20 @@ function findStaleVerificationSummary(phaseDir, fsImpl = defaultFsImpl, phaseCle
         // or sentinel-numbered canonically-shaped file cannot outrank this
         // phase's own (possibly non-canonical) report. #3511: phaseDirName scopes
         // the fallback path to this same phase (see resolveVerificationFile docs).
+        // #4187: allowBare — this staleness seam must see the same report set the
+        // status reader sees, or a bare report could never read `stale` while its
+        // dashed twin could (two answers from one verb).
         const phaseDirName = node_path_1.default.basename(phaseDir);
-        const phaseToken = extractPhaseToken(phaseDirName);
-        const verificationFile = resolveVerificationFile(phaseFiles, { phaseToken, phaseDirName });
+        // #612: derive the token with the resolved convention so a bracket dir's
+        // own token is read behind its `{CODE}.{MM}-` prefix. #4187: keep the bare
+        // report tier aligned with the status reader.
+        const phaseToken = extractPhaseToken(phaseDirName, convention);
+        const verificationFile = resolveVerificationFile(phaseFiles, {
+            allowBare: true,
+            phaseToken,
+            phaseDirName,
+            convention,
+        });
         if (!verificationFile)
             return { determined: true, stale: false };
         const summaryFiles = scanPhasePlans(phaseDir).summaryFiles
@@ -587,7 +729,9 @@ function findStaleVerificationSummary(phaseDir, fsImpl = defaultFsImpl, phaseCle
  * 1. Find the phase's verification report via `resolveVerificationFile`
  *    (canonical `<phase-token>-VERIFICATION.md` preferred; falls back to the
  *    alphabetically-first `*-VERIFICATION.md` that belongs to THIS phase when
- *    none is canonical — #3357/#3511). If none → status 'missing'.
+ *    none is canonical — #3357/#3511; and, when the directory's only report
+ *    is a bare `VERIFICATION.md`, that file — #4187, matching
+ *    `verification.resolve-file`). If none → status 'missing'.
  * 2. Extract `status` from FRONTMATTER ONLY via the shared extractFrontmatter
  *    parser (DEFECT.FRONTMATTER-SCALAR-BROAD-GREP fix — parser anchors at byte 0).
  *    If no frontmatter block or no `status` key → status 'missing'.
@@ -608,7 +752,12 @@ function readVerificationStatus(phaseDir, opts = {}) {
     const fsImpl = opts.fs ?? defaultFsImpl;
     const phaseCleanCommitTimesMs = opts.phaseCleanCommitTimesMs ?? defaultPhaseCleanCommitTimesMs;
     const runtime = opts.runtime ?? 'claude';
-    // Phase token for the gaps_found command
+    // Phase token for the gaps_found command — deliberately convention-LESS
+    // even when `opts.convention` is present: the token becomes a bare COMMAND
+    // ARGUMENT below, and a bare bracket phase number is milestone-ambiguous
+    // (`02` cannot tell GSD.01-02 from GSD.02-02), so the argument keeps its
+    // pre-#612 shape. The convention-aware token is derived separately for
+    // FILE RESOLUTION only (`resolutionToken`, at the readdir below).
     const baseName = node_path_1.default.basename(phaseDir);
     const phaseToken = extractPhaseToken(baseName);
     const derivedPhaseNumber = phaseToken.length > 0 ? phaseToken : baseName;
@@ -624,12 +773,21 @@ function readVerificationStatus(phaseDir, opts = {}) {
     let verificationFile = null;
     try {
         const entries = fsImpl.readdirSync(phaseDir);
-        // #3492: pin selection to THIS phase's own token (already derived above
-        // for the routed command argument) so a stray cross-phase or
-        // sentinel-numbered canonically-shaped file cannot outrank this phase's
-        // own (possibly non-canonical) report. #3511: baseName also scopes the
-        // fallback path to this same phase (see resolveVerificationFile docs).
-        verificationFile = resolveVerificationFile(entries, { phaseToken, phaseDirName: baseName });
+        // #3492: pin selection to THIS phase's own token so a stray cross-phase
+        // or sentinel-numbered canonically-shaped file cannot outrank this phase's
+        // own report. #612: derive a separate convention-aware RESOLUTION token
+        // for bracket directories while the routed command argument above stays
+        // convention-less and milestone-unambiguous. #4187: keep the bare report
+        // tier aligned with every other verification reader.
+        const resolutionToken = opts.convention === 'bracket'
+            ? extractPhaseToken(baseName, opts.convention)
+            : phaseToken;
+        verificationFile = resolveVerificationFile(entries, {
+            allowBare: true,
+            phaseToken: resolutionToken,
+            phaseDirName: baseName,
+            convention: opts.convention,
+        });
     }
     catch {
         // Directory unreadable → treat as missing
@@ -656,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.
@@ -710,13 +878,23 @@ 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 {
-        const staleCheck = findStaleVerificationSummary(phaseDir, fsImpl, phaseCleanCommitTimesMs);
+        const staleCheck = findStaleVerificationSummary(phaseDir, fsImpl, phaseCleanCommitTimesMs, opts.convention);
         isStale = staleCheck.determined && staleCheck.stale;
         // staleCheck is either {determined:true, stale:false} (checked; nothing
         // stale) or {determined:false} (could not check — fs/scan/clock failure).
@@ -730,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
@@ -800,6 +981,7 @@ function isPhaseComplete(phaseDir, deps = {}) {
         phaseCleanCommitTimesMs: deps.phaseCleanCommitTimesMs,
         runtime: deps.runtime,
         phaseNumber: deps.phaseNumber,
+        convention: deps.convention,
     });
     return {
         value: {
@@ -866,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`,
@@ -881,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
@@ -889,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
@@ -907,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;
     }
@@ -926,5 +1207,9 @@ module.exports = {
     cmdVerificationStatus,
     cmdVerificationResolveFile,
     computeCoveredDigest,
+    sharedPlanningRoots,
+    isSharedPlanningDoc,
+    parseFingerprintVersion,
+    parseFingerprintFileArgs,
     cmdVerificationFingerprint,
 };