Skip to content

Commit 84b4dfe

Browse files
trek-esimclaude
authored
refactor(#5170): typed gate evidence and a verdict-driven exit status (Phase 8 of #5056) (#5171)
* refactor(#5170): typed gate evidence and a verdict-driven exit status (T1) Add src/gate-evidence.cts: Evidence<T> (found / none / unreadable), readTextEvidence and readDirEvidence (ENOENT and ENOTDIR are none; every other failure is unreadable carrying the errno), and verdictFromEvidence whose unreadable arm must return a branded UnreadableVerdict. GateOutcome gains 'unreadable' and gate-verdict gains gateUnreadable. Add src/gate-exit.cts: gateExitOutcome is a total mapping from a verdict and a mode to PASS, FAIL or UNAVAILABLE, and declareGateExit declares it through the new cli-exit declareOutcome after output() has run. emitGateResult declares in payload mode, so a delivered verdict keeps exit 0 and an unreadable one exits UNAVAILABLE. phase uat-passed and verify artifacts derive their exit status from their verdict (status mode): a negative verdict exits 1, a plan with nothing to evaluate exits UNAVAILABLE. Their stdout JSON is unchanged. verify-work.md and gsd-verifier.md branch on the exit status in the same change. Refs #5170, #5056 Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): correct tests that pinned exit 0 on a failing verdict phase uat-passed with passed:false and verify artifacts with all_passed:false now exit 1, and a plan with no artifacts to evaluate exits UNAVAILABLE. These assertions required result.success on a negative verdict, which encoded the old exit-0-on-failure behavior; they now pin the exit status that follows the verdict, and the surfaces that only need an answer accept exit 0 or 1. Refs #5170, #5056 Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): gate evidence, gate exit, and verdict-driven CLI exit status Cover readTextEvidence and readDirEvidence (missing, directory, injected EACCES and EIO, empty file, ENOTDIR), the compile-time guarantee that the unreadable arm cannot return a passing verdict, the total gateExitOutcome mapping as a seeded fast-check property with a positive control, declareOutcome, and child-process CLI tests for phase uat-passed and verify artifacts. Refs #5170, #5056 Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(#5170): gate reads run on typed evidence; "could not look" is outcome unreadable (T2) Migrate every gate module read onto the Evidence seam and delete the tolerant readers (ADR-5057 section 4, third bullet): - gate-phase-context: readIfExists is deleted. resolvePhaseDirOrEmpty becomes resolvePhaseDir (Evidence), findUiSpecInDir and lookupRoadmapPhase answer none vs unreadable, locateUiSpec composes the two, and the two empty catch clauses are gone. - gate-evidence: evidenceFromError, readDirEntriesEvidence, statEvidence and the Observed type, so a gate never needs a bare catch around a read. - ui-plan-gate / ui-safety-gate: an unreadable ROADMAP or phase directory, and ui-safety's unresolvable scope, are outcome unreadable (block stays the gate's own policy). The verify-command-paths / verify-failure-directions probes that cannot look are outcome unreadable with the payload unchanged. - api-coverage verify-pre: the empty readdir catch at the COVERAGE.md lookup is unreadable and never falls through to the detector; an unreadable COVERAGE.md or plan scope stays block:true with outcome unreadable. - tdd-review-checkpoint: an unreadable plan or phase directory is unreadable, not "not a TDD plan"; an absent phase directory stays none and the existing skip. - predicate: findPhaseArtifact throws on an unreadable lookup (the existing usage failure) instead of reading it as "artifact not found". - tdd-red-evidence, decision-coverage plan/verify and their support module read CONTEXT.md, plans, summaries and listed files as evidence; an unreadable one is outcome unreadable instead of an empty string that certifies "no decisions". Delivered pass/skip/advisory/block payloads for readable evidence are unchanged (the cutover goldens still match byte for byte). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): correct expectations that pinned "could not look" as skip / exit 0 A verdict whose evidence could not be read is outcome unreadable and exits 69 (UNAVAILABLE); it is never a skip or exit 0. Update the tests that pinned the old outcome: - cutover goldens: the nine arms that cannot look (ui-safety unresolvable scope, both verify probes, unreadable COVERAGE.md / plan scope) now record exitCode 69; their stdout is unchanged byte for byte. - unit tests for ui-safety, verify-command-paths, verify-failure-directions and the evaluation-scope consumers expect outcome unreadable. - the execute-wave pipeline fixture wrote files_modified outside the plan's frontmatter; it now carries the field in the frontmatter block, the shape production plans have, because schema-drift reads it through the Frontmatter Module. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): schema-drift reads files_modified through the Frontmatter Module; negated grep gates are scanned (#4562, #4541) verify schema-drift (#4562): the plan's files_modified came from a `files_modified:\s*\[...\]` regex that knew only the inline array, so a YAML block sequence yielded no files and a schema change reported "no drift". The list is now read the way phase-plan-index reads it (RawPlan.filesModified), so block sequences (one or many items), inline arrays and CRLF all yield the files. A plan or summary that cannot be read is reported as unreadable (the existing payload plus unreadable / unreadable_file / read_error, exit 69) and is never "no files, no drift"; --skip still bypasses the gate. verify plan-structure (#4541): the negative-grep comment-echo scan fired only for `grep -c 'LIT' f == 0`. `! grep -q 'LIT' f`, `if ! grep ...` and `grep ...; test $? -ne 0` are the same gate and now fire too, and the error names both forms; a plain positive `grep -q 'LIT' f` gate does not fire, and an inverted grep is still a positive assertion. A negated command pasted into an <action> does not flag itself. Tests: block-sequence (1 and N items), inline, CRLF, unreadable plan / summary, --skip control; negated spellings, positive controls, allowlist, bareword, and an end-to-end plan-structure case. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): unreadable evidence is outcome unreadable and exits UNAVAILABLE in every gate (matrix rows 16-23) Behavioral coverage, each with a control that reads cleanly: - cutover suite: exit status follows the verdict, driven through the real CLI (ui-safety unresolvable scope, both probes, unreadable api-coverage evidence exit 69 with the payload unchanged; a delivered block stays exit 0). - api-coverage: the phase directory that cannot be listed (the former empty catch) is unreadable and never the detector's pass; an unreadable COVERAGE.md and plan scope keep block:true with outcome unreadable. - tdd-review-checkpoint: an unreadable plan is unreadable, an absent phase directory is none and the existing skip. - predicate: an unlistable phase directory is the usage failure, an absent one is artifactNotFound. - ui-plan: unreadable phase directory and ROADMAP; decision-coverage plan and verify: unreadable CONTEXT.md, plan and listed file; tdd-red-evidence: unreadable record. Read and readdir failures are injected by replacing the fs method and restoring it in finally. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(#5170): document the exit status of the verify probes check verify-command-paths and check verify-failure-directions exit 0 whenever they could look (a blocker finding is still exit 0) and exit 69 (UNAVAILABLE) with the same JSON when they could not. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): ui-auditor screenshot block follows redirects, probes the documented ports, and reports failed captures as not captured (#4176) The static capture block misread a redirecting dev server as no server (no -L, equality against 200), printed "Screenshots captured" when every capture failed (stderr discarded, no exit or file check), and never tried the 5173/8080 fallback the next line documents. It now probes 3000, 5173, 8080 with -L and a bounded --max-time, judges each capture by exit status and a non-empty file, and ends on captured / PARTIAL / NOT captured. Both agents/gsd-ui-auditor.md and the compact variant carry the fix; the test executes the extracted block against a local http server. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): set the full tmpdir triad in the ui-auditor screenshot block harness Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): run-tests fails a chunk whose registered tests did not all reach the report (#4031) --test-force-exit (the Windows post-test hang backstop, #1051/#869) can end the node --test parent while part of a test file's results is still unread on the child's pipe (nodejs/node#64833). The runner then printed a smaller count and exited 0, so every reported count was a lower bound. The count of registered tests now comes from the child over a channel that does not share that pipe: scripts/lib/test-registration-ledger.cjs is loaded into each test-file child with --require, counts the test()/it() registrations made through node:test and appends one line per file at exit. The ndjson reporter records the kind (suite or test) of every pass/fail, and analyzeChunkAccounting compares the two per file. A chunk that exited 0 with registered > reported now fails, naming the chunk and the counts, and the remaining chunks still run. The check is one-sided (run-time subtests are reported but not registered), so it can miss a loss but cannot invent one. --test-force-exit stays the default, so the Windows hang protection is intact. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(#5170): name the registration ledger preload outside the test-* pattern and regenerate the conformance tiers A scripts/lib file whose basename matches Node's test-collection pattern would be collected and executed as a test by the remote runner, so the preload is registration-ledger-preload.cjs. The Windows and macOS conformance-tier lists are regenerated for the two new test files. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): workflow callers of the probe verbs and gate dispatch treat exit 69 as "could not look" The verify-command-paths / verify-failure-directions probes and the ui-plan-gate now exit 69 (UNAVAILABLE) when they could not look, still printing their JSON. plan-phase.md, the quick plan-checker loop and the ui-plan-gate capture branch on the captured exit status instead of reading the JSON blind: 0 is a normal look, 69 hands the unresolvable payload to the checker unchanged, any other non-zero is a command failure. verify-work.md's gate dispatch captures CHECK_EXIT like the other dispatch hosts, and the shared loop-hook-dispatch contract states once that exit 69 is a step-1 command failure routed by onError, never a verdict. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): verify-work's phase uat-passed capture survives set -e and aborts on exit 69 (matrix row 30) Extracts both documented captures from verify-work.md and runs them under bash with set -e and a stub gsd_run: exit 0 and exit 1 with JSON are verdicts and are read, exit 1 with nothing on stdout, exit 69 and exit 2 abort with "could not run" and read nothing. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): an unresolvable evaluation scope is outcome unreadable and exits 69; the workflow captures keep its JSON `check evaluation-scope` mapped scope.status 'unresolvable' (a missing git, a timeout, an unknown phase) to outcome 'skip' and exit 0: "could not look" reported as a pass-shaped exit. It is now outcome 'unreadable' (block stays false: the resolver is not a policy), so the router exits UNAVAILABLE (69). The JSON payload is unchanged and still printed. Consumers: the code-review and quick-task scope captures no longer discard the JSON that carries the degradation reason (`|| SCOPE_JSON=""`) nor abort under `set -e`; exit 69 keeps the JSON, any other non-zero status drops stdout. The gsd-code-reviewer agent (full and compact) notes exit 69. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): an unresolvable evaluation scope is unreadable / exit 69; workflow captures survive set -e Corrects the resolver test that pinned 'skip' for an unresolvable scope, and adds the CLI case (exit 69 with the JSON and reason on stdout, payload equal to the in-process verdict), the degraded control (exit 0), and a bash set -e harness over the code-review and quick-task captures (exit 0 / 69 / 68 / 70 / 1-with-empty-stdout). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): gap-analysis and the remaining existsSync probes read typed evidence; schema-drift exceptions exit UNAVAILABLE src/gap-checker.cts (the engine behind `check gap-analysis-plan-post`) swallowed every read: an unreadable config, REQUIREMENTS.md, CONTEXT.md or plan became '' (so every ID read "Not covered", or "No requirements or decisions to check"), a phase directory read failure never reached the verdict, and `existsSync` answered "absent" for an EACCES on a parent. Every read is now `readTextEvidence`; anything that exists but cannot be read is listed in an additive `unreadable` field (present only when non-empty, so the delivered wire shape is unchanged) and the gate returns outcome `unreadable` (block:false, advisory policy unchanged) which exits 69. An unreadable REQUIREMENTS.md no longer makes every cited ID "Missing from REQUIREMENTS.md". `fs.existsSync` probes whose answer decides a verdict are replaced by `statEvidence`: api-coverage (the phases tree and the phase directory) and decision-coverage-plan (CONTEXT.md); the verify gate's redundant probe is dropped (its one read already yields none/unreadable). An EACCES is `unreadable`, never "not a GSD project" / "CONTEXT.md missing". `verify schema-drift`: the catch around the gate printed a non-blocking "exception:" payload and exited 0, so a gate that threw looked like "no drift"; it now declares UNAVAILABLE after printing the same payload, and an unexaminable phases directory is `unreadable` instead of "No phases directory". `tdd-red-evidence` parses the record through typed evidence instead of a catch that returned null. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): tolerant probes read typed evidence (gap-analysis, api-coverage, decision-coverage) Real EISDIR fixtures where a real failure can be built; fs.statSync/readFileSync monkeypatched to throw EACCES (restored in finally, never chmod) where it cannot. Absent controls stay `none` (documented policy); the gap-analysis CLI case asserts exit 69 with the table on stdout and exit 0 for the control. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * ci(#5170): gate-evidence drift guard (matrix rows 35-37) wired into lint:ci scripts/lint-gate-evidence-drift.cjs parses the gate modules, check-auto-mode, gap-checker, decision-coverage-support and every gate-exit importer (router, phase, verify) with @typescript-eslint/parser and fails on: an empty or literal-only catch, any `readIfExists` reference, a gate verb entry owning its exit (process.exitCode / process.exit / numeric return / direct declareOutcome), a passing verdict in an `unreadable` arm, and a verb catch that prints a payload without declaring an exit. The allowlist is empty. Run over the pre-Phase-8 sources it flags the original census (the empty catches and readIfExists). Positive controls: one fixture per shape under tests/fixtures/gate-evidence-drift/ (stored as .cts.txt so no compiler or linter walks a deliberately violating file) plus a clean fixture; the test runs the guard against them, boundaries (0/1/2 catch statements), a seeded fast-check property, fail-closed cases, and publishes the census over the real tree as a function asserted zero. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): verify schema-drift exits 69 for an exception and for an unexaminable phases directory Real CLI: no phases directory stays exit 0 (control); a file where the phases directory belongs throws inside the gate and exits 69 with the unchanged non-blocking payload; an EACCES on the phases stat (preload patch, never chmod) is `unreadable` with exit 69. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): remaining gate verbs exit through the verdict; empty scope is NO_INPUT verify plan-structure/phase-completeness/references/commits/key-links build real verdicts and exit 1 (negative), 66 (read, genuinely empty scope), 69 (could not look; an empty plan file is found '', not absent). schema-drift, codebase-drift, context-drift and prohibition-enforcement route through gate-exit in payload mode (the gate dispatch reads .block and routes a non-zero exit by onError). Duplicated CONTEXT.md-missing and schema-drift payload builders collapse; hand-built found literals use evidenceFound; gap-checker indentation fixed. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): shell consumers of gate verbs are exit-status aware safe_resume_gate and the TDD gate fail closed on an unresolvable evaluation scope, completion reconciliation keeps the scope status, the autonomous UI gate and the decision-coverage and drift pre-checks no longer read exit 69 as "nothing there". Test helpers (fs failure injection, tool probe, CLI runner, doc bash spans) move to tests/helpers and the duplicated copies are removed. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * ci(#5170): drift guard discovers gate verb entries and flags exit/existence collapses Entries come from the verify/phase/check routers, not a name list; new rules verb-no-gate-exit, verdict-owns-exit and exists-collapse (one named allowlist site, stale entries are problems), with positive-control fixtures and a census. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): run-tests fails a chunk whose accounting evidence is unreadable A missing ledger or events file for a chunk that exited 0 is a failure, not a warning, and a registered file is matched to its results by real path only (no basename fallback). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(#5170): refresh INVENTORY rows for the gate modules and regenerate conformance tiers Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): an unreadable nested plans/ is unreadable in every gate that sources plans from the scan scanPhasePlans marks a phase whose nested plans/ directory exists but cannot be read as SCOPE.TRUNCATED and returns the plans it could see. The TDD review checkpoint, decision-coverage (readPhaseFiles), gap-analysis, the evaluation scope's summary set and api-coverage (which checked only UNREADABLE) took that short list for the phase's plans, so a plan, a decision citation or an API integration could be the one they never saw. gate-evidence owns the one reader (readPlanScanEvidence / readPlanSetEvidence): only SCOPE.COMPLETE is a result, every other scope is unreadable (exit 69). api-coverage reads its plans as typed evidence; its unreadable-plan message carries the errno code instead of the operating-system message. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): verify verbs read the plan set as evidence and answer an unreadable drift input with one policy - phase-completeness, schema-drift and key-links (the plans that may promise a file) treat a plan scan that did not see every plan as unreadable, never a short plan set. - Every return path of plan-structure / references / artifacts / key-links goes through emitVerbVerdict (the target file's unreadable verdict is built by a pure helper and emitted at the call site); artifact and key-link reads are typed evidence instead of a catch that records the failure in a string. - codebase-drift with an unreadable map document and a non-blocking verdict is outcome unreadable (exit 69) with the existing payload plus documents_unreadable; a blocking verdict stands. - context-drift treats an absent .planning/phases as none (the documented skip, exit 0), the same as schema-drift; an unexaminable tree stays unreadable for both. - query verify.* and verify <sub> agree on the declared exit and the verdict JSON; the parity is pinned over 0 / 1 / 66 / 69. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): the static frontend-evidence probe reads typed evidence ui-plan-gate blocks only when a vocabulary match is corroborated by static frontend evidence, and the probe turned every read failure (an unreadable package.json, a directory that could not be listed, a native source file that could not be opened) into "no evidence", so the gate passed over a tree it had not looked at. readStaticFrontendEvidence returns found / none / unreadable; the gate reports an unreadable probe as outcome unreadable when it could flip the verdict (a frontend phase with no UI-SPEC). Affirmative evidence wins over a failure elsewhere. hasStaticFrontendEvidence remains as the boolean projection. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): a filtered test run cannot make the registration ledger report unaccounted tests A test file run under --test-name-pattern, --test-skip-pattern or --test-only (reachable through NODE_OPTIONS) registers tests the runner then excludes without reporting them, so registered > reported was a false red. The preload marks such a child's ledger line filtered and the accounting leaves that file out of the comparison; unfiltered files in the same chunk are still checked. describe.skip, test.skip and todo were already accounted (a skipped suite's body never registers; skip and todo are reported) and are now pinned against a real file run. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): shell consumers capture a gate verb's status under set -e and never concatenate its payload with a fallback - Every `X=$(gsd_run ...); X_EXIT=$?` capture (a bare assignment aborts under set -e before the status or the JSON is read) is `X=$(...) && X_EXIT=0 || X_EXIT=$?`, including the gate dispatch blocks of wave-post-gate-hooks, verify-phase-goal, ship, plan-phase and verify-work. - codebase-drift-gate.md no longer appends `|| echo '{...}'` to a verb that already printed its exit-69 payload (two JSON documents on stdout): the fallback is applied only when the verb printed nothing. - structural-pre-pass.md reads rangeBase from a captured status instead of a pipe into sed, and says so when the audit widens to the whole repository. - The ui-auditor expands DEV_PORTS through its digit runs only (no glob, path or URL fragment reaches the loop or the probed URL). - Every extracted block now runs under a real set -e with a stub gsd_run for exit 0 / 1 / 69 / 2-with-empty-stdout (no setE escape hatch); the bash-block tests fail instead of skipping under CI when bash, jq or curl is missing. - The autonomous UI gate's status variable is GATE_RC (the section is pinned to carry no exit vocabulary); the decision-coverage gate block keeps its blocking guard inside the window its drift test reads. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * ci(#5170): the gate-evidence drift guard is path-sensitive, per-symbol and no longer evadable - verb-no-gate-exit requires EVERY return path (and the fall-through end) of a discovered entry to settle the exit; the original #4686 shape — an early `output({ error }); return;` beside a branch that emits through the seam — is flagged. Helper closures resolve in their own file, then through its imports, never by a bare name across src/. - pass-shaped-catch flags any catch that neither rethrows nor produces unreadable evidence or an unreadable verdict (void err; return '', a named empty constant, an assignment then a return, a call that only records the error). - unreadable-arm-passes covers the else of !== 'unreadable', an early-returning !== 'unreadable', !== 'found', a switch fall-through and the default of a found+none switch, the final else of a found+none chain, a variable-valued outcome and same-file helpers. - exists-collapse sees computed members, destructured and aliased fs imports, alias assignments, .call and sequence callees. - A positive-control fixture per evasion; the allowlist stays the one named finalizeFiles/missingOnDisk entry and the census is zero on the tree. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(#5170): INVENTORY rows describe the unreadable / exit-69 contract of the gate modules The ui-plan, ui-safety, evaluation-scope and verify-probe rows said "degraded verdict"; they now name outcome unreadable and exit UNAVAILABLE, and the rows of every module changed by the review fixes (gate-evidence, gap-checker, decision-coverage, gap-analysis, api-coverage, tdd checkpoint, ui-frontend- evidence) name the unreadable arms. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(#5170): gate verb exit statuses, the evidence feature section and a how-to for script authors Reference: the exit table (0 / 1 / 66 / 69), the status-versus-payload mode of every gate verb, phase uat-passed, codebase-drift, and the registered-code page. Explanation: the FEATURES section (generated from a docs/features fragment) on why unreadable is distinct from none, why the exit is a function of the verdict and why check verbs stay payload mode. How-to: capturing a gate verb's status safely under set -e, a decision table, and the reason shapes of an unreadable verdict. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(#5170): changeset for the verdict-driven gate exit status Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(#5170): the exit-code reference page is generated, so the gate-verb prose lives in the CLI tools reference docs/reference/exit-codes.md is rewritten by gen-exit-code-docs and failed lint:generated-sync with a hand-added section; the section is dropped and the links point at the generated page itself. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(#5170): the unreadable exit-69 JSON carries the gate's own fields, not an outcome key Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): the registration ledger counts leaf results at the serializer, not by wrapping test() The first real run of the #4031 accounting reported every test file as "N registered, 0 reported". The preload wrapped test()/it() in a Proxy, a JS frame between the test file and node:test. node:test stamps each test with the location of its CALLER (getCallerLocation in the harness) and reports that as the event's `file`, so under the preload every result came back located in registration-ledger-preload.cjs: the ledger keyed the real test file, the events keyed the preload, and nothing matched. It would also have pointed every spec-reporter failure location at the preload. The preload now taps v8.DefaultSerializer.prototype.writeValue, which the child's own reporter calls for every event it frames onto the pipe to the parent, and counts leaf test:pass/test:fail per the `file` each event carries. That adds no frame to any test() call, and the parent's ndjson reporter reads back the same field, so both sides count the same events under the same key: a skipped test, a skipped suite, a run-time subtest and a name/only filter need no special case and the `filtered` marker is gone. Both sides are still compared by realpath, with no basename fallback. The temp-root tests spawned a nested run-tests.cjs that inherited NODE_TEST_CONTEXT, so its `node --test` refused to run any file and exited 0 with no report. The runner now fails that chunk (unreadable evidence), so the spawns clear the context as run-tests-harness.test.cjs does and the probe file really runs. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(#5170): register the ledger preload in the installed scripts/lib set and regenerate the install-tree fixtures scripts/lib/registration-ledger-preload.cjs ships like its sibling ndjson-reporter.cjs (the runner requires both from scripts/lib). Without an entry in GSD_SCRIPTS_LIB_FILES uninstall() would orphan it. The 19 install-tree fixtures change by exactly that one path each (npm run gen:install-tree). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): the QA walk models a verdict-driven exit 1; the io census follows the verify verbs' typed verdicts loop-walk.qa: `phase uat-passed` on a failing UAT now exits 1 with its verdict on stdout. The classifier read every exit 1 without a stderr envelope as unstructured-error and dropped stdout, so the uat-fail-then-remediate scenario's expectations on `passed` / `no_uat_artifacts` found no json (and json-contract would have flagged the step). classify() now reads an exit 1 whose stdout IS a verdict (a boolean `passed` or `block`) as the new verdict-refused kind with the verdict as its json; any other exit-1 stdout, including a healthy-looking `{ok:true}` body, stays an error, and a structured stderr envelope still wins. The scenario file is unchanged apart from a note of the exit status. io.test: the A3 census counts `output({error})` object-literal call sites. The eight in verify.cts were converted to typed verdicts (the payload's `error` rides inside the verdict and the verb declares its exit status), so verify.cts leaves the census: 69 -> 61 across 8 modules, with the reason recorded beside the entry. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): the uniform gate `block` contract reads a gate verb's payload at exit 69 as well as exit 0 `check ui.safety-gate` in the test's empty temp directory cannot resolve its evaluation scope, so it now exits 69 (UNAVAILABLE, "could not look"). It still prints its verdict payload with the boolean `block` field on stdout, which is the contract the host loop reads; the test spawned with execFileSync, which throws on any non-zero status and discarded the stdout, so a documented status read as "command failed or returned non-JSON output". Every declared gate query returns a boolean `block` (measured for all eight, with a phase number and with a path); the probe now captures stdout under the documented gate-verb statuses (0, and 69 for could-not-look) and fails on any other status or on missing JSON. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): the extracted shell blocks do not depend on jq; the gate-evidence typing fixtures follow the must-not-compile precedent The Tester Image has no jq: the plan-phase decision-coverage block died with "jq: command not found" (exit 127) before the logic under test ran. runBash now defines `jq` as a function over tests/helpers/jq-subset-stub.cjs, which implements exactly the two filters the block uses with jq's own semantics (`//` on false/null, -e exit status, -r raw strings; verified equal to jq 1.x over 26 document/filter pairs) and refuses any other filter with exit 3, so a block that grows a new jq filter fails loudly instead of passing through a lookalike. The stub's semantics are pinned by tests in gate-consumer-exit-awareness.test.cjs. tests/fixtures/gate-evidence-typing/*.cts are tsc-checked by path in gate-evidence.test.cjs (two must-not-compile, one positive control) and resolve to no ESLint rule. They take the same allowlist entries, with reasons, as the brand-typing fixtures of the same shape (#3059), which keeps their .cts path. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): the safe-resume and TDD RED captures are the resolver call itself, still exit-status aware tests/safe-resume-gate-anchoring.test.cjs (the Phase 7 contract) finds the resume gate's and the RED gate's resolver call by the text `PLAN_COMMITS=$(gsd_run check evaluation-scope --plan ... --max-commits 30` and the single line `RED_COMMIT=$(gsd_run check evaluation-scope ... --pathspec ...`. The exit-status rewrite named the raw capture PLAN_SCOPE / RED_SCOPE, so those lines no longer existed and nine rows failed ("the RED_COMMIT line must exist"). The capture is now assigned to PLAN_COMMITS / RED_COMMIT directly (`... ) && PLAN_SCOPE_RC=0 || PLAN_SCOPE_RC=$?`), the guard on the status is unchanged (exit 69 and every other non-zero status stop before any commit list is read), and the next line reduces the captured JSON to the `<sha> <subject>` list in place. The exit-awareness test extracts the same spans from the renamed variables. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * refactor(#5170): gsd-ui-auditor loads its static capture block from a reference; gsd-verifier's exit prose is tighter gsd-ui-auditor.md was 7 bytes under the DEFAULT hard cap before the #4176 capture block fix, so the fix (+1520 bytes) put it at 26089 (cap 24576) and gsd-verifier.md at 49309 (LARGE cap 49152) with the exit-status prose. The caps are red lines: the capture block moves, verbatim, to gsd-core/references/ui-screenshot-capture.md (with the paragraph that explains its outcome line), the agent and its compact variant keep one instruction that loads it, and the file is 24080 bytes (compact 14094). The block is unchanged, so tests/ui-auditor-screenshot-block.test.cjs still executes it, now resolved through the @-reference both agent files carry. gsd-verifier.md keeps its four exit statuses (0, 1, 66, 69) for verify.artifacts and verify.key-links in fewer words: 49080 bytes. INVENTORY row, manifest and the 19 install-tree fixtures follow the new reference (one added path each). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(#5170): refresh the compact-content baselines and the platform conformance tiers `node scripts/benchmark-compact-content.cjs --write` (the workflow growth of this change: execute-phase, plan-phase, verify-work splits) and `node scripts/benchmark-compact-content-variants.cjs --write` (the ui-auditor pair, which shrank by 160 bytes), plus `node scripts/gen-platform-conformance-tier.cjs --write` for the test files this change added to the lane classification. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(#5170): acknowledge the emitted growth of the exit-status-aware gate consumers The shell consumers of the gate verbs now capture each verb's exit status and say what a "could not look" status (69) stopped, instead of reading an empty result as "nothing there". That text is deliberate, user-visible workflow and agent prose, so the ten emitted files below grew on purpose. Each key is the bare filename. gsd-ui-auditor.md and its compact variant ended smaller than the base (the capture block moved to a reference), so neither carries an acknowledgment. The changeset also names the runner's unreadable-evidence arm of its test accounting. Emitted-Drift-Ack-Growth: code-review.md — the phase file-scope capture keeps the resolver's exit 69 JSON and names the status instead of reading a failed capture as an empty scope Emitted-Drift-Ack-Growth: execute-phase.md — the safe-resume gate and the TDD RED gate capture the evaluation-scope status and stop on 69 instead of reading could-not-look as no commits Emitted-Drift-Ack-Growth: execute-plan.md — the codebase-map changed-file list warns on an unavailable evaluation scope instead of printing nothing as if no file changed Emitted-Drift-Ack-Growth: gsd-plan-checker.md — verify.plan-structure is captured with its exit status in the per-plan loop and in step 5 (0 and 1 are verdicts, 69 is could-not-look) Emitted-Drift-Ack-Growth: gsd-planner.md — the plan-structure self-check captures verify.plan-structure's exit status instead of discarding it Emitted-Drift-Ack-Growth: gsd-verifier.md — verify.artifacts, verify.key-links and verify.commits are captured with their exit status and the agent states what 1, 66 and 69 mean for Steps 4 and 5 Emitted-Drift-Ack-Growth: plan-phase.md — the decision-coverage gate, the drift pre-checks, the UI and verify-command gates and the gate dispatch capture exit status and stop or warn on 69 Emitted-Drift-Ack-Growth: quick.md — the quick-task review scope capture keeps the resolver's exit 69 JSON and says why the scope is empty Emitted-Drift-Ack-Growth: ship.md — the ship gate dispatch captures the verb's exit status so a gate that could not run is not read as a pass Emitted-Drift-Ack-Growth: verify-work.md — the gate dispatch and the two phase uat-passed captures read the exit status (0 and 1 are verdicts, 69 and any other status could not look) and survive set -e Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): the ui-auditor's static capture fence stays inline in <screenshot_approach>; the size cap is met by tightening prose and comments Moving the static capture block to a reference removed the bash fence that tests/ui-interaction-capture.test.cjs extracts from <screenshot_approach> to keep the static (Playwright) and interaction (chrome-devtools) paths apart: 30 failures, "<screenshot_approach> must keep its static bash fence". That contract is structural, so the fence returns inline and the reference, its INVENTORY row, manifest entry, install-tree path and the test's @-reference extractor are removed again. gsd-ui-auditor.md is 24464 bytes (cap 24576, base 24569): the static block is condensed (comments folded into one line, the case statement for the outcome), the post-block paragraphs are merged, and comment lines and prose in the interaction fence and its section are tightened. No interaction-fence code line changed (checked line by line against the prior text), so its behavior tests are unaffected. The compact variant carries the same behavior in a denser block at 15086 bytes (base 14583): that growth is the #4176 capture fix itself. Emitted-Drift-Ack-Growth: gsd-ui-auditor.compact.md — the static screenshot block gains redirect following, the 3000/5173/8080 fallback and an outcome line (captured, PARTIAL, NOT captured) judged from the files written (#4176) Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): only a negative verdict at exit 1 is a refusal; the capstone pins which gate may exit 69 tests/qa/result.cjs read an exit 1 over ANY boolean `passed` / `block` as verdict-refused. An exit 1 whose stdout says `passed:true` or `block:false` contradicts its own verdict, the defect class #5170 closes, so it stays an unstructured error; only `passed:false` / `block:true` is a legitimate refusal. Tests pin both polarities with the positive controls (and a mixed payload where the negative field still refuses). tests/phase6-capstone-conformance.test.cjs accepted exit 69 from every `check` verb that printed a boolean `block`. Measured for every declared query: only ui.safety-gate exits 69 in the empty, non-git temp directory, because it resolves its file scope through the evaluation-scope resolver, which cannot resolve outside a git work tree (payload `scopeStatus: 'unresolvable'`). That set is pinned; any other verb answering 69, or the pinned one answering anything else, fails. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): a chunk whose ledger counted no result while the reporter received some fails; the accounting states its real blind spots The preload counts at v8.DefaultSerializer.prototype.writeValue, which holds only while node:test's child reporter frames events through it. If a Node change moves that, every count is 0 and the check would silently stop detecting loss. That is positively established whenever the reporter RECEIVED results the ledger never counted (a received result was necessarily handed to the child's serializer first), so analyzeChunkAccounting now reports `ledgerCountedNothing` and run-tests fails the chunk (formatAccountingCountDead). It is chunk-level and keyed on reportedAll > 0, so files that legitimately report nothing (skip/todo-only, empty) and a chunk where any file counted results are not caught; a per-file rule was rejected because a legitimate zero-count line sits beside counted files. The "like for like by construction" wording is removed from the accounting comment and the preload header, which now list what is NOT caught: a child that emitted nothing, a SIGKILLed child (no exit ledger line), a file reported but never registered, and the dependence on the serializer hook. Tests pin the four boundaries of the dead count and the mixed-file case. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): the jq stub's agreement with jq is pinned over 13 documents x 2 filters, its divergences are named; the io census explains why verify.cts left it The earlier claim of equality with real jq on 26 pairs was true when measured but only 14 cases were pinned. The test now pins all 13 documents against both filters with expected values measured from real jq, and pins the known divergences (empty stdin: jq exits 4, the stub 2; a string/array `.data` or a top-level array: jq errors with exit 5, the stub reads null; an object printed by -r: jq pretty-prints, the stub prints compact). The stub header lists them; none is reachable from the gate handler's JSON. tests/io.test.cjs: the stale "verify 8" breakdown is marked as measured then, and the census entry now states the real reason verify.cts left it. Read from src/verify.cts and src/gate-exit.cts: emitVerbVerdict prints the verdict payload through output() with a non-literal argument (so the literal-shape census no longer sees the sites), output() still records DEGRADED for a payload carrying an `error` key, and declareGateExit then overrides it for a non-PASS verdict (unreadable 69, empty 66, block in status mode 1) while a PASS leaves output()'s outcome untouched. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(#5170): backfill the changeset PR number (#5171) Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): withFsFailure refuses an fs method that does not exist A misspelled method would inject nothing, and the test that relied on it would pass without exercising a failure. The Memtrace PR review flagged the unchecked fs[method] lookup. The other three review findings are not defects: labels[index] and FORMS[form] index collections with keys drawn from the same collection, and the setTimeout in the ui-auditor harness is a watchdog kill bound for a spawned child, cleared on close. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): test-file children write their results to a blocking stdout, so --test-force-exit no longer drops them (#4031) CI (docs-lint, plugin-validate) failed with "N tests registered, M reported" while the TAP summary itself said M, so the accounting was right and results really did not reach the report. Root cause, from node's v24 runner source and measured on a Linux node:24 container: the runner forwards --test-force-exit to every test-file child (getRunArgs); each forced child calls process.exit() the moment its root test ends, and its stdout, the pipe its V8-framed results travel on, is non-blocking on POSIX, so frames still queued in the Socket are discarded (nodejs/node#64833, fix proposed in nodejs/node#64875). It needs no concurrency: plugin-validate lost 23 of 54 in a single file. Measurement (Node 24.18.0, Linux, 20 files x 300 tests, concurrency 8, the runner's own events file and ledger, 4 runs each): count-only preload 5049-5074 reported of 6000 (ledger 6000: the child had emitted them all, so the loss is child to parent); preload that makes the child's stdout blocking 6000/6000 on every run; without force-exit 6000/6000. registration-ledger-preload.cjs now sets the child's stdout handle blocking at load (blockChildStdout, best-effort, test-file children only), the same operation the upstream fix performs at force-exit, but done up front so nothing is ever queued. --test-force-exit stays on every platform: it is the Windows post-test hang guard (#1051) and nothing about that changes, whereas dropping it on POSIX would trade a loud accounting failure for silent hangs on leaked handles. The accounting stays as the backstop for any other loss. Unit rows pin blockChildStdout; the behavioral proof is a real shard's own accounting. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): fix the CI-only failures of the preload and jq-stub tests; acknowledge the code-reviewer agent growth Read from the failed CI run of the previous head, each with its platform: - ubuntu shards 1-3, windows 2/3: "the human_needed UAT precheck" and "the phase-completion predicate" read PASSED=false for {"passed":true} at exit 0 (tests/verify-work-auto-transition.test.cjs:465). runBash defined `jq` as the subset stub unconditionally, shadowing the REAL jq that GitHub's runners have, and the stub knows only the two filters of the plan-phase block, so verify-work's `jq -r '.passed // false'` failed and fell back to "false". It passed on the bench because those rows skip there (no jq). The stub is now defined only when `command -v jq` finds none. - windows 2/3: every run-tests-accounting row that spawns the ndjson reporter died with ERR_UNSUPPORTED_ESM_URL_SCHEME ("Received protocol 'd:'"): --test-reporter takes an import specifier, and a bare Windows path is not one (run-tests.cjs itself passes pathToFileURL for this reason). The tests do too. - macOS: the ledger key is node's own realpath (/private/var/...) while the rows expected path.resolve of the symlinked tmp (/var/...); they compare against the realpath, as the runner's matching does. - ubuntu 3/3, ubuntu, macOS: emitted-attribution against the CI base 2cc432e names gsd-code-reviewer.md (+210) and its compact variant (+30): the exit-69 wording the resolver-driven file scope now carries. Acknowledged below; every other grown emitted file already carries its trailer, and none is stale. Emitted-Drift-Ack-Growth: gsd-code-reviewer.md — states that the evaluation-scope resolver exits 69 for status unresolvable while still printing its JSON, so an empty files list is read as could-not-look and fails closed instead of as a clean review Emitted-Drift-Ack-Growth: gsd-code-reviewer.compact.md — the same exit-69 wording for the compact variant of the reviewer's scope resolution Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(#5170): tests that capture process.stdout.write no longer swallow node:test's report frames The accounting still failed on CI after the blocking-stdout fix, on exactly two files: ci-pr-mergeability.test.cjs (81 registered, 38 reported) and ci-next-health.test.cjs (37 registered, 3 reported). The results were genuinely dropped child to parent, by the tests themselves, not over-counted: their callMain() does t.mock.method(process.stdout, 'write', ...) and t.mock.method(process.stderr, 'write', ...) to capture the CLI's output. In a test-file child node:test writes its V8-framed results as Buffers through process.stdout.write, looked up at write time, so while the mock is active the frames are captured into the test's array and never reach the parent: no error, exit 0. Measured on Node 24 with a real framed test-file child: 22 tests of which two mock process.stdout.write reported 11; the same shape with the fixed helper reported 22; 22 plain tests reported 22. tests/helpers/stdio-capture.cjs captureStringWrites() records the strings the code under test writes (the scripts write strings) and forwards everything else to the real write. Both files use it. A unit row pins it. Any other test that mocks the stdio writes the same way will now be named by the accounting, which is its job. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * fix(#5170): every ledger line carries the real path, including the zero-result one macOS CI failed one row: `--test-only` expected the ledger file as /private/var/... and got /var/.... The ledger has two sources for a file name: node's own result events (`data.file`, already resolved through symlinks) and, for a child that reports no result, process.argv[1] as given. With the tmp dir symlinked (macOS /var -> /private/var) the two kinds of line disagreed about the same file. The preload now writes canonicalPath() (path.resolve + best-effort fs.realpathSync.native, falling back to the absolute spelling) on every line. analyzeChunkAccounting normalizes both sides regardless; a shim with a symlinked tmp dir confirms it matches both spellings. The accounting tests compare with fs.realpathSync.native throughout; the remaining path.resolve rows feed synthetic paths straight to analyzeChunkAccounting, which normalizes them itself. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(#5170): regenerate the context indexes after rebasing onto the latest next Upstream added the Test-Report Adapter Module entry next to this branch's Gate Evidence and Gate Exit entries in CONTEXT.md; both generated indexes are rebuilt from the merged glossary (301 predicates). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent 81cb6f8 commit 84b4dfe

201 files changed

Lines changed: 9313 additions & 1272 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
type: Fixed
3+
pr: 5171
4+
---
5+
**A gate verb that failed no longer exits 0, and a gate that could not read its evidence no longer passes** — `phase uat-passed`, `verify artifacts`, `verify plan-structure`, `verify phase-completeness`, `verify references`, `verify commits` and `verify key-links` printed a failing verdict and exited 0, and gates that hit an unreadable plan, directory or COVERAGE.md treated it as empty and passed. Their exit status now follows the verdict: 0 pass, 1 negative verdict, 66 empty scope, 69 could not look (the JSON on stdout is unchanged; `check` verbs and the drift verbs stay payload mode, where a blocking verdict is still exit 0 and only 69 is non-zero). Also: `verify schema-drift` now sees a block-sequence `files_modified`, `verify plan-structure` flags a `! grep` negative gate whose literal appears in the task action, `verify commits` outside a repository exits 69 instead of listing every hash invalid, and the test runner fails a chunk whose registered tests are not all reported, or whose accounting evidence cannot be read. (#5170)

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,8 @@ build/
296296
/gsd-core/bin/lib/gate-ui-plan.cjs
297297
/gsd-core/bin/lib/gate-ui-safety.cjs
298298
/gsd-core/bin/lib/gate-verdict.cjs
299+
/gsd-core/bin/lib/gate-evidence.cjs
300+
/gsd-core/bin/lib/gate-exit.cjs
299301
/gsd-core/bin/lib/gate-verify-command-paths.cjs
300302
/gsd-core/bin/lib/gate-verify-failure-directions.cjs
301303
/gsd-core/bin/lib/verify-command-grounding.cjs

‎CONTEXT.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,18 @@ Module owning the translation of a captured test report into individual results
5353
`SEAM.test-report-adapter.owns=parseTestReport(output) (src/report-parser.cts) is the single owner of turning a test report into individual results; the RED-evidence policy consumes its contract and parses no report text (#4692)`
5454
`SEAM.test-report-adapter.enforced-by=test:tests/report-parser.property.test.cjs`
5555

56+
### Gate Evidence Module
57+
Module owning what a gate found when it looked (ADR-5057 §4 third bullet, epic #5056, #5170). `Evidence<T>` is `found` (`value`; an empty file is `found ''`), `none` (the evidence authoritatively does not exist: `ENOENT`, or `ENOTDIR` because a parent is not a directory) or `unreadable` (`reason` carries the errno code, `span` the path read: `EISDIR`, `EACCES`, `EIO`, an encoding failure). `readTextEvidence` / `readDirEvidence` (`src/gate-evidence.cts`) construct it and never throw; `unreadable` is never coerced to `''`, `false` or an empty list, because a gate that reads "could not look" as "nothing there" passes over content it never saw. `verdictFromEvidence(evidence, {found, none, unreadable})` is the one way a gate maps evidence to a verdict, and its `unreadable` arm is typed to return an `UnreadableVerdict` (`outcome: 'unreadable'`, built by `gateUnreadable` in `src/gate-verdict.cts`), so a passing verdict from that arm does not type-check. Each gate keeps its own policy for `none` and its own `block` decision for `unreadable`; this module changes the outcome, not the policy.
58+
59+
`SEAM.gate-evidence.owns=Evidence<T> / readTextEvidence / readDirEvidence / verdictFromEvidence (src/gate-evidence.cts) is the single owner of found-versus-none-versus-unreadable for a gate read (ADR-5057 §4, #5170)`
60+
`SEAM.gate-evidence.enforced-by=test:tests/gate-evidence.test.cjs`
61+
62+
### Gate Exit Module
63+
Module owning the exit status a gate verdict projects to (ADR-5057 §4 fourth bullet, epic #5056, #5170). `gateExitOutcome(verdict, mode)` (`src/gate-exit.cts`) is a total function onto registered outcome names: `pass`, `skip` and `advisory` are `PASS`; `block` is `PASS` in `payload` mode and `FAIL` in `status` mode; `unreadable` is `UNAVAILABLE` (69) in both modes, so "could not look" never exits 0. `payload` is the `check <verb>` dispatch contract (the verdict is delivered on stdout and read from `.block`; a non-zero status means the command could not run, routed by `onError`); `status` is for verbs whose shell callers branch on the status (`phase uat-passed`, `verify artifacts`: exit 1 is a negative verdict and the JSON on stdout is still authoritative). `declareGateExit(verdict, mode)` declares the outcome through `declareOutcome` in `src/cli-exit.cts` and runs AFTER `output()`, which rewrites the pending-outcome cell on every call; a gate module never imports it, the router or verb adapter calls it. `PASS` is not declared, so a payload that legitimately carries an `error` key keeps its ADR-3889 contract.
64+
65+
`SEAM.gate-exit.owns=gateExitOutcome / declareGateExit (src/gate-exit.cts) is the single owner of the exit status a gate verdict projects to; declareOutcome (src/cli-exit.cts) is the only writer of the pending-outcome cell besides output() (ADR-5057 §4, #5170)`
66+
`SEAM.gate-exit.enforced-by=test:tests/gate-exit.test.cjs`
67+
5668
### Verification Module
5769
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`).
5870

‎agents/gsd-code-reviewer.compact.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ Resolver call (phase number = the leading digits of the `phase_dir` basename; ad
9191
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
9292
gsd_run check evaluation-scope --phase "<phase number>" --raw
9393
```
94-
Use its `files`. A `status` of `unresolvable`, or empty `files`, is the fail-closed case above; `degraded` is usable but say so in REVIEW.md.
94+
Use its `files`. A `status` of `unresolvable` (exit 69, JSON still printed), or empty `files`, is the fail-closed case above; `degraded` is usable but say so in REVIEW.md.
9595

9696
**4. Parse structural findings when present:** `<structural_findings>...</structural_findings>` → parse JSON, cache as `STRUCTURAL_FINDINGS`. Include in `## Structural Findings (fallow)` section of REVIEW.md during `write_review` (verbatim if small; concise summary if large). Optional block — absence means no structural pre-pass.
9797

0 commit comments

Comments
 (0)