Module owning the canonical phase-verification status projection shared by phase transition, progress, manager, autonomous, and closeout readiness paths. `readVerificationStatus(phaseDir, opts?)` reads the phase's `*-VERIFICATION.md` frontmatter `status` and projects every answer through `VERIFICATION_ROUTES` — the ONE routing table, keyed by the closed enum `VERIFICATION_STATUS` (`passed`, `gaps_found`, `human_needed`, `stale`, `missing`, `unparseable`, `phase_dir_not_found`; #5118, ADR-5057 Phase 4) — adding the bare command it routes to as `route`. It fail-closes — only `{passed}` satisfies the canonical gate; every other member routes away from "complete" (#1522). A report may carry only the writer subset `VERIFIER_STATUSES` (`passed`, `gaps_found`, `human_needed`); any other value (a case variant, `verified`, a reader-only member, a non-string) throws `VerificationStatusError`, which the CLI reports once, centrally, as ERROR_REASON `verification_status_invalid` and `isPhaseComplete` maps to its UNREADABLE scope. A path with no phase directory behind it reads `phase_dir_not_found` (a usage error, no next command), never `missing`. `stale` has one route, `execute-phase`, whose regenerating action is the shared step `execute-phase/steps/verify-phase-goal.md` that verify-work's stale arm also runs. Staleness is one of TWO mutually exclusive checks, selected by whether the report DECLARES a fingerprint (#4155, i.e. either `covered_files` or `covered_digest` is present — a report that declares only one, or an empty/malformed pair, fails closed to `stale` rather than silently downgrading to the weaker legacy check): a report with a well-formed pair is checked by `computeCoveredDigest(projectRoot, coveredFiles)` — a deterministic sha256-of-sha256s over the SORTED, de-duplicated, `./`/`..`-canonicalized covered set, hashed by file BYTES always through the real `node:fs`, never a caller-injected `opts.fs` seam (`covered_files` spans the whole `projectRoot`, not just `.planning/`, so a caller-scoped containment wrapper narrower than `projectRoot` would reject legitimate covered files; the per-file re-check inside `computeCoveredDigest`/`deriveCoveredDigest` is the actual confinement boundary: an implementation path against `projectRoot`, a `.planning`-spelled one against the LONGEST-prefix ANCHORED planning scope `bestPlanningScopeForRel` selects — see the v3 entry below, #5095 R7 — OR `projectRoot`) — recomputed and compared to the stored digest. Fingerprint **v2** (#4623) leaves repo-wide planning documents — any DIRECT child of a planning root: `.planning/` itself, and the phase's own planning root (the parent of its `phases/`, so the `.planning/<project>/` and `workstreams/<ws>/` layouts of `planningDir` are covered without the digest knowing what a workstream is; `sharedPlanningRoots` / `isSharedPlanningDoc`, defined by position so the set cannot drift as new top-level documents appear) — OUT OF THE HASH while still validating them exactly as every other covered path (confined to `projectRoot`, present, a regular file — the fail-closed contract is unchanged; only the bytes are ignored): every phase rewrites them as ordinary bookkeeping, and the closing phase's own `phase.complete` / `requirements mark-complete` writes them AFTER the verifier ran, so under v1 a phase staled itself and every sibling that had declared them. A declaration consisting ONLY of shared documents hashes nothing and is `null` (stale), like an empty one. A stored digest names its version (`v<N>:sha256:…`) and is recomputed under THAT version (`parseFingerprintVersion`, `KNOWN_FINGERPRINT_VERSIONS`), never the current constant, so a legacy v1/v2 report keeps its own semantics until it is re-fingerprinted, an upgrade alone stales nothing, and a version this build cannot recompute fails closed to `stale`. For a **v1/v2** stored digest, `allCurrentArtifactsCovered` additionally re-scans the LIVE phase directory (via `scanPhasePlans`, short-circuited so it only runs once the digest itself has matched, and fails closed to `false` on any scope other than `SCOPE.COMPLETE`) for every current `*-PLAN.md`/`*-SUMMARY.md` and requires each to be represented in `covered_files`: a plan or summary added to the phase AFTER verification, never declared, would otherwise pass the digest check untouched. Fingerprint **v3** (#5095, ADR-5057 Phase 2, the current default `FINGERPRINT_VERSION`) closes that input set instead of patching around it: (1) a report path (basename `VERIFICATION.md` or `*-VERIFICATION.md`) is NEVER an input to its own digest — filtered by `canonicalizeCoveredFiles`/`isVerificationReportPath` one function above `computeCoveredDigest`, since that function never receives the report's own path to compare against; (2) the hashed set is `canonicalize(declared ∪ phaseArtifactPaths(phaseDir))` — the phase's own live `*-PLAN.md`/`*-SUMMARY.md` (mapped to the root they actually live in) are UNIONED into the digest on both the emit (`cmdVerificationFingerprint`) and check (`readVerificationStatus`) sides, so `allCurrentArtifactsCovered` is not consulted for v3 — a plan/summary added after fingerprinting moves the digest itself; (3) containment additionally admits a `.planning`-spelled path whose realpath sits in one of the ANCHORED planning scopes `resolveContainmentRoots` enumerates from the project root alone (`.planning`, `.planning/<project>`, `.planning/workstreams/<ws>`, `.planning/<project>/workstreams/<ws>` — never derived from a caller's `phaseDir`, #5095 R7) — a symlinked `.planning/workstreams/<ws>/phases`, `.planning/<project>/phases`, or a whole `.planning/<project>`/`.planning/workstreams/<ws>` store maps to that SAME scope's spelling, never collapsing onto (or being dropped from) the top-level `.planning/phases/<phase>/…` shape a single scope root could only recognise; a scope whose realpath is the filesystem root or an ancestor of the checkout root is refused outright, never admitted; this containment widening applies to every version, never just v3. ANY mismatch — digest, an uncovered current artifact (v1/v2 only), or a covered path that is missing, unreadable, or escapes every known root (`resolveProjectRoot(phaseDir)` — the operator's validated `--project-dir` when one was given (#4894), otherwise `findProjectRoot(phaseDir)`; the fingerprint CLI resolves its root through the same call, so a digest is always recomputed under the root it was emitted under — canonicalized via real `fs`, never the injected seam — it is a trusted caller-derived anchor, not attacker-influenced covered-input data) — routes to `stale`, fail-closed (`computeCoveredDigest` returns `null` for the whole set rather than a partial digest). A report with no fingerprint metadata at all (every report predating #4155) falls back to the legacy `findStaleVerificationSummary`, which flags a SUMMARY newer than the VERIFICATION file — unchanged. The verifier computes `covered_digest` via the CLI (`verification.fingerprint <phaseDir> <file>...`, routed in `verification-command-router.cjs`; since #4623 the covered files are bare positionals or `--files a[,b]`, repeatable and mixable, the phase dir must be an existing directory — an omitted one used to hash the wrong set at exit 0 — and any other `--flag` is a usage error rather than a covered path), never by hand — this is deterministic math, not an LLM-estimated value. The legacy path alone keeps the module's original no-throw, degrade-to-safe contract (any FS error → `missing` / not-stale); the fingerprint path's contract is stricter (any FS error → `stale`), matching #4155's fail-closed design. `isPhaseComplete(phaseDir, deps?)` is the single canonical owner of "is phase P complete?" (ADR-3180 §7.4, issue #3186, disk-strict per #2957): it wraps `readVerificationStatus`, calling it UNCONDITIONALLY — plan count is never a precondition, so a zero-plan phase with a passing `*-VERIFICATION.md` is complete (#3168) — and returns `{ value: { complete, verification }, scope }`; `complete` is exactly `verification.status === 'passed'`. A ROADMAP checkbox carries no machine authority and is never consulted. `cmdPhaseComplete`, `buildPhaseCompletionProjection`, and `buildStateFrontmatter` all route through it. Source of truth: `gsd-core/bin/lib/verification.cjs` (generated from `src/verification.cts`).
0 commit comments