peaks-loop 4.0.43 → 4.0.45

package/dist/services/prd/handoff-service.d.ts

@@ -47,7 +47,15 @@ export declare function writeHandoff(handoff: Handoff, projectRoot: string): Pro
  *  malformed frontmatter. */
 export declare function readHandoff(filePath: string): Promise<Handoff>;
 /** Verify a handoff by re-reading and re-hashing. Returns a probe
- *  (never throws on hash mismatch — that's the outcome). */
+ *  (never throws on hash mismatch — that's the outcome).
+ *
+ *  N1: the two failure classes are reported separately. The previous
+ *  single `catch` folded every read failure into `file-missing`, so a
+ *  handoff that WAS on disk but whose frontmatter the parser refused was
+ *  reported as absent — sending an operator to look for a missing file
+ *  that was right there. Only a genuine read failure (ENOENT, EACCES, …)
+ *  is `file-missing` now; anything the parser rejects is
+ *  `frontmatter-malformed`. */
 export declare function verifyHandoff(filePath: string): Promise<HandoffProbe>;
 /** Return the raw markdown content of a handoff file (frontmatter +
  *  body verbatim). For human display. */

package/dist/services/prd/handoff-service.js

@@ -66,15 +66,30 @@ export async function readHandoff(filePath) {
     return parseHandoffContent(content);
 }
 /** Verify a handoff by re-reading and re-hashing. Returns a probe
- *  (never throws on hash mismatch — that's the outcome). */
+ *  (never throws on hash mismatch — that's the outcome).
+ *
+ *  N1: the two failure classes are reported separately. The previous
+ *  single `catch` folded every read failure into `file-missing`, so a
+ *  handoff that WAS on disk but whose frontmatter the parser refused was
+ *  reported as absent — sending an operator to look for a missing file
+ *  that was right there. Only a genuine read failure (ENOENT, EACCES, …)
+ *  is `file-missing` now; anything the parser rejects is
+ *  `frontmatter-malformed`. */
 export async function verifyHandoff(filePath) {
-    let handoff;
+    let content;
     try {
-        handoff = await readHandoff(filePath);
+        content = await readFile(filePath, 'utf8');
     }
     catch {
         return { ok: false, reason: 'file-missing' };
     }
+    let handoff;
+    try {
+        handoff = parseHandoffContent(content);
+    }
+    catch {
+        return { ok: false, reason: 'frontmatter-malformed' };
+    }
     if (handoff.frontmatter.schemaVersion !== HANDOFF_SCHEMA_VERSION) {
         return {
             ok: false,
@@ -119,20 +134,47 @@ function parseHandoffContent(content) {
     if (!isHandoffFrontmatter(parsed)) {
         throw new Error('handoff: frontmatter shape validation failed');
     }
-    return { frontmatter: parsed, body };
+    // N1: normalize the version to its canonical string form. `schemaVersion: 2`
+    // (bare) is valid YAML that parses to the NUMBER 2; `schemaVersion: '2'` is
+    // what `stringifyYaml` writes. Both mean schema version 2, so the parsed
+    // frontmatter is returned with the canonical `'2'` rather than the raw scalar
+    // — otherwise every downstream `=== '2'` comparison would depend on which
+    // producer wrote the file.
+    return {
+        frontmatter: { ...parsed, schemaVersion: HANDOFF_SCHEMA_VERSION },
+        body
+    };
 }
 function serializeHandoff(handoff) {
     const yamlStr = stringifyYaml(handoff.frontmatter).trimEnd();
     return `---\n${yamlStr}\n---\n${handoff.body}`;
 }
+/**
+ * N1: accept BOTH shapes of `schemaVersion` — the string `'2'` and the bare
+ * YAML number `2` — and reject any other value.
+ *
+ * The reader used to require `typeof v.schemaVersion === 'string'`. That made
+ * `readHandoff` refuse `prd/handoff.md` written by `handoff-auto-regen.ts`,
+ * which emits the unquoted `schemaVersion: 2`, while the
+ * `AUDIT_REQUIRES_HANDOFF` prereq — a SUBSTRING check for `schemaVersion: 2` —
+ * happily passed the same bytes. So the gate that exists to guarantee a
+ * readable handoff was satisfied by a handoff the parser would not read, and
+ * `peaks prd handoff verify` exited 1 on a healthy file.
+ *
+ * Quoting the writer instead is NOT a fix: it would delete the very substring
+ * the prereq pins, turning a broken read into a broken gate. The tolerant read
+ * is the only change that satisfies both consumers.
+ */
+function isSchemaVersion2(value) {
+    return value === HANDOFF_SCHEMA_VERSION || value === 2;
+}
 function isHandoffFrontmatter(value) {
     if (!value || typeof value !== 'object')
         return false;
     const v = value;
     return (typeof v.requestId === 'string' &&
         typeof v.sessionId === 'string' &&
-        typeof v.sessionId === 'string' &&
-        typeof v.schemaVersion === 'string' &&
+        isSchemaVersion2(v.schemaVersion) &&
         typeof v.handoffHash === 'string' &&
         typeof v.writtenAt === 'string' &&
         Array.isArray(v.goals) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.43",
+  "version": "4.0.45",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -99,12 +99,13 @@
     "better-sqlite3": "^12.11.1",
     "commander": "^12.1.0",
     "fzf": "^0.5.2",
+    "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-mut": "0.1.41",
-    "peaks-loop-shared": "0.0.77",
-    "peaks-loop-internal-runtime": "0.0.28",
-    "peaks-loop-shared-channel": "0.0.45"
+    "peaks-loop-mut": "0.1.43",
+    "peaks-loop-shared-channel": "0.0.47",
+    "peaks-loop-internal-runtime": "0.0.30",
+    "peaks-loop-shared": "0.0.79"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",
@@ -114,6 +115,7 @@
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.2",
+    "@types/picomatch": "4.0.3",
     "@typescript-eslint/eslint-plugin": "8.66.0",
     "@typescript-eslint/parser": "8.66.0",
     "@vitest/coverage-istanbul": "^4.1.10",

package/skills/peaks-final-review/SKILL.md

@@ -69,7 +69,9 @@ interface PrepareFinalReviewOptions {
 }
 ```
 
-The service is the **gate primitive** that closes the 10% human / 90% LLM loop. It reads the approved audit-goal JSON from `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`, calls an injected `LlmRunner` exactly once with a 4-dim review prompt, parses the response, and validates that all four required dimensions are present. It throws `IncompleteFinalReviewError` on malformed JSON or missing dimensions — callers MUST treat that as a gate failure (return to human for re-prompting) and never let autonomous work proceed on a partial review.
+The service is the **gate primitive** that closes the 10% human / 90% LLM loop. It reads the approved audit-goal JSON from `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`, **collects real evidence from disk** (`qa/test-reports`, `qa/test-cases`, `qa/security-findings`, `qa/performance-findings`, `rd/{tech-doc,bug-analysis,code-review,security-review}.md`, `prd/handoff.md`), inlines it into the 4-dim review prompt under byte bounds, calls an injected `LlmRunner` exactly once, parses the response, and validates that all four required dimensions are present. It throws `IncompleteFinalReviewError` on malformed JSON or missing dimensions — callers MUST treat that as a gate failure (return to human for re-prompting) and never let autonomous work proceed on a partial review.
+
+> **Evidence-backed verdicts (added 2026-09-12).** The service previously sent the model only `successCriteria` and no evidence at all, so it could not honestly grade anything — a real run returned 4/4 `inconclusive`, and a model willing to confabulate could have returned `pass`. Verdicts are now gated **structurally**, not by prompt wording: any `pass` whose supporting sources were all missing/empty is rewritten to `inconclusive` + `confidence: low` (`fail` is never softened), and `allPass` is derived from the gated verdicts so it can only narrow. Every non-`found` evidence source renders an explicit `STATUS: MISSING (<why>)` in the prompt, so the model always knows what it does not know.
 
 > The `LlmRunner` interface is intentionally minimal so this service reuses the same provider injection seam as `audit-goal-service` and the slice LLMArbitrator (`src/services/audit/audit-goal-service.ts:16`). No provider implementation is baked in at this layer.
 
@@ -85,41 +87,32 @@ All of the following MUST be true before invoking this skill:
 
 If any precondition is missing, **STOP** and route back to the responsible skill. Do not paper over a missing artifact with a hand-written successCriteria — the review must reflect what the human originally approved.
 
-## Invocation (CLI wrapper status — READ FIRST)
-
-> **Pre-flight finding (HARD):** The plan prose at `docs/superpowers/plans/2026-06-25-slice-topology-multipass-phase-4.md:146` documents the invocation as:
->
-> ```bash
-> peaks prepare-final-review --rid <rid> --json
-> ```
->
-> **This CLI command does NOT yet exist.** `prepareFinalReview()` is implemented as a service in `src/services/final-review/final-review-service.ts` and is unit-tested in `tests/unit/final-review/final-review-service.test.ts`, but it is **not wired to a CLI subcommand**. A `peaks prepare-final-review` subcommand is the planned forward-looking surface; the integration sits at the service layer, not the CLI layer, today.
->
-> **Pick for the future CLI wrapper file (audit recommendation):** create a new `src/cli/commands/final-review-commands.ts` matching the `peaks-<group>-commands.ts` naming convention (`qa-commands.ts`, `code-review-commands.ts`, `audit-commands.ts`). A grep of `src/cli/commands/` confirms NO `final-review-commands.ts` and NO `prepareFinalReview` import in any CLI file. Rationale: the 4-dim business review is conceptually distinct from `peaks qa *` (which is autonomous gate verification) — it is the human-acceptance terminator, not an internal gate. A separate command group preserves that boundary.
-
-### Current call path (today, until a CLI wrapper is built)
-
-```ts
-// peaks-code end-of-workflow, peaks-txt, or any other hand-rolled caller
-import { prepareFinalReview } from './src/services/final-review/final-review-service.js';
-import { auditGoalLlmRunner } from './src/services/audit/llm-runner.js'; // or your provider
-
-const out = await prepareFinalReview('<rid>', {
-  projectRoot: '<absolute path>',
-  sessionId: '<sessionId>',
-  llmRunner: auditGoalLlmRunner
-});
-```
+## Invocation
 
-### Planned call path (after the CLI wrapper lands)
+> **Correction (2026-09-12).** An earlier revision of this file claimed `peaks prepare-final-review`
+> "does NOT yet exist" and told callers to hand-roll a `prepareFinalReview()` caller instead.
+> **That was wrong.** The CLI wrapper exists and is registered —
+> `src/cli/commands/final-review-commands.ts` (`W5 Fix M2`), command registered at its line ~130.
+> The hand-rolled snippet that used to sit here also had the wrong flag shape (`--rid <rid>`);
+> **the rid is positional**. Use the CLI.
 
 ```bash
-# Forward-looking — does not work yet. Track under
-#   src/cli/commands/final-review-commands.ts
-peaks prepare-final-review --rid <rid> [--session-id <sid>] --json
+peaks prepare-final-review <rid> [--session-id <sid>] [--project <path>] [--llm-provider <name>] [--json]
 ```
 
-`--rid` is required and resolves to `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. `--json` is required for machine consumption (peaks-code, peaks-txt, downstream CI). The wrapper will resolve `--session-id` from `.peaks/_runtime/current-change` when omitted, matching the workspace binding pattern used by `peaks request *`.
+- `<rid>` is **positional** (not `--rid`). It resolves to `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`.
+- `--session-id` defaults to the active workspace binding when omitted.
+- **`--llm-provider` defaults to `stub`, and `stub` is the only provider that works today.**
+  `stub` runs no real review — it returns a scaffold envelope so CI can prove the route is reachable.
+  Verified 2026-09-12: passing a real provider (`--llm-provider anthropic`) returns
+  `status: not-applicable` / `serviceWired: false` / `providerBinding: unknown` and tells you to re-run
+  with `stub`; the CLI's own nextAction calls real-provider binding "a follow-up slice". So there is
+  currently **no reachable path to a real 4-dim review** — confirming the route works is all `stub`
+  can do.
+- `--json` is required for machine consumption (peaks-code, peaks-txt, downstream CI).
+
+Calling the service directly (`prepareFinalReview(rid, { projectRoot, sessionId, llmRunner })`) remains
+valid for callers that need a custom `LlmRunner` injection seam, but it is no longer the only path.
 
 ## Output
 
@@ -144,22 +137,73 @@ Each `DimensionEvidence` carries:
 - `evidence` — list of `EvidenceItem` (`{ kind, description, artifact?, link? }`) with `EvidenceKind` ∈ `test-result | test-coverage | manual-spot-check | pre-post-diff | regression-suite | ac-mapping`
 - `confidence` — `high | medium | low`
 
-The service enforces that **all 4 dimensions are present**; a missing dimension throws `IncompleteFinalReviewError` and the call is a gate failure. Treat `allPass === true` + empty `needsAttention` as a clean handoff to the human. Anything else — `allPass === false`, a `fail` verdict, or an `inconclusive` verdict — must come back to the LLM loop with a re-prompt (do not ask the human to interpret raw LLM output).
+The service enforces that **all 4 dimensions are present**; a missing dimension throws `IncompleteFinalReviewError` and the call is a gate failure. Treat `allPass === true` + empty `needsAttention` as a clean handoff to the human **only where it is reachable at all**: if the pre/post baseline for dimension 4 cannot be **computed** at all (see dimension 4 below), that dimension is permanently `inconclusive` and `allPass` is structurally `false` on every run — a `false` there means "no comparison was shown to the reviewer", not "the work regressed". The same delivery rule applies to **dimension 1's approved-scope contract** (`prd/handoff.md`): a contract that is absent, empty, unreadable, or too large to reach the reviewer costs that dimension its `pass` (a `scope-contract-gate` marker says so in the summary). Read both as "the reviewer was not given the document this verdict needs", never as "the work regressed". A computed baseline or a present contract is no longer at the mercy of the byte budget: both sources hold a floor in the allocator, so the budget-starved delivery failures left are the ones with no document behind them. One failure is NOT the budget's to fix, and the service says so in as many words: when **every** source on disk that supports a dimension is larger than the per-file cap (`MAX_EVIDENCE_BYTES_PER_FILE`, 10,240 bytes — derived from the total, so raising the total does not raise it), that dimension can never be delivered — not on this run and not on any run. The reviewer gets a `## Evidence delivery reachability (structural)` block naming the source and its size, and the dimension's summary carries a `delivery-reachability` marker with the same arithmetic. Read that `inconclusive` as "no evidence for this dimension can reach the reviewer", never as "the reviewer was unsure". Two cases worth naming: `needsAttention` is populated by the SERVICE too, not only by the verdicts — a delivered baseline whose own `VERDICT: ` line reports `STRUCTURAL DRIFT DETECTED` puts dimension 4 in `needsAttention` and clears `allPass` even when the reviewer passed it, because a detected removal is not "nothing needs attention"; and every dimension named by the reachability block above lands there too (it can never be `pass`), so the field tells you *why* it is red. And anything else — `allPass === false`, a `fail` verdict, or an `inconclusive` verdict — must come back to the LLM loop with a re-prompt (do not ask the human to interpret raw LLM output).
 
 ## The 4 dimensions (one-line summary)
 
 Full evidence contract per dimension: `references/4-dimensions.md`.
 
-1. **functional-completeness** — every AC from the approved audit-goal maps to a passing test (`evidence.kind === 'ac-mapping'` + `test-result`).
+1. **functional-completeness** — every AC from the approved audit-goal maps to a passing test (`evidence.kind === 'ac-mapping'` + `test-result`), and the approved-scope contract (`prd/handoff.md`) was delivered to the reviewer in full.
 2. **problem-resolution** — there is a targeted test for the original problem case (`evidence.kind === 'test-result'` against the original repro).
 3. **no-new-bugs** — the regression suite is green AND the LLM surfaces 0 net-new failures (`evidence.kind === 'regression-suite'` + `manual-spot-check`).
 4. **existing-functionality-intact** — a pre/post baseline diff (test count, public API surface, key behavior) shows no unintended drift (`evidence.kind === 'pre-post-diff'`).
 
+> **Status of this dimension — updated 2026-09-12 (the `pre-post-diff` producer now ships).**
+> The producer exists. `peaks prepare-final-review` runs a read-only git comparison of a base ref
+> against the working tree and writes `.peaks/_runtime/<sessionId>/final-review/api-diff.txt`
+> — the test-file and non-test `.ts` / `.tsx` source-file lists, the `it(` / `test(` case counts
+> before/after, and the added/removed top-level `export` names over changed `.ts` / `.tsx` files —
+> and maps that artifact into this dimension's `supports`. The service also attaches it to the
+> dimension as an `EvidenceItem` of kind `pre-post-diff` whose `artifact` points at that file.
+> The dimension can reach `pass` — when a baseline could actually be computed **and was delivered to the
+> reviewer**. Both halves are required. The source holds a floor in the evidence allocation, so a
+> budget that runs out no longer drops it; if it ever is dropped the reviewer's prompt says
+> `STATUS: COMPUTED ON DISK, NOT DELIVERED`
+> instead of claiming a comparison it does not carry, the dimension's `pass` is downgraded to
+> `inconclusive`, and no `pre-post-diff` `EvidenceItem` is attached to it. A baseline the reviewer never
+> saw is not evidence, exactly as a baseline that was never computed is not — the verdict may not
+> outlive the evidence that was actually handed over. Two properties make that judgement structural
+> rather than arithmetic: a source is delivered only when the bytes the reviewer received carry its
+> conclusion (for this artifact, its opening `VERDICT:` line), and the delivered conclusion is then
+> READ — a `STRUCTURAL DRIFT DETECTED` line puts this dimension in `needsAttention` and clears
+> `allPass` even when the reviewer answered `pass`, because a detected removal is a question for a
+> human, not a clean handoff.
+>
+> **A baseline that cannot be computed is never invented.** No base ref resolving, a base ref that
+> resolves to HEAD itself (an empty range — what a shallow clone's `merge-base` produces on its
+> default path), or a project that is not a git work tree, all mean the same thing: no artifact is
+> written, the reviewer is told why in the prompt, and a `pass` on this dimension is downgraded to
+> `inconclusive` — for EVERY one of those causes, with no exemptions. "This project keeps no
+> baseline" is the CAUSE of the missing evidence; it is not a reason to trust the claim the
+> evidence was supposed to support, and a permanently-`inconclusive` dimension is the honest
+> reading of a comparison that never happened. The base ref comes from `--base <ref>`; the default
+> is the merge-base with `origin/HEAD`, then `origin/main`, then `origin/master`, then `HEAD~1`,
+> and when none of those resolve the reason says so and names `--base` as the way out.
+>
+> **What that means for `allPass`.** On a project that is not a git work tree — or where no base ref
+> resolves — this dimension is permanently `inconclusive`, so `allPass === true` can never be reached
+> there, however complete the other nine evidence sources are. That is the intended reading and not a
+> bug to work around: nothing was ever compared, so there is no answer to hand over. Likewise, a
+> project whose evidence set outgrows the reviewer's input budget leaves this block OMITTED, and the
+> honest envelope then says `inconclusive` rather than asserting a comparison the reviewer was never
+> shown.
+>
+> **Boundary:** the export comparison is a line-anchored regex, not a type checker — it detects a
+> removed or renamed export and cannot detect a changed signature. Type-only exports count, both
+> spellings (`export type { T }` and `export { type T }`). File-level DELETION is visible, because
+> it is read from the file lists rather than inferred from the counts — a module with no
+> `export ` line and no `it(` is still reported when it is deleted. And the reverse direction is
+> guarded too: a name that appears on both sides of the diff, a `git mv`, and an `it(` ->
+> `test.each(` conversion are reported as changes, not as removals. The artifact carries a
+> wall-clock timestamp, so two runs over the same base differ on that line and on nothing else.
+> And still do **not** "fix" a red dimension by re-mapping `qa/test-reports` into its `supports`:
+> that turns the gate green without producing the baseline diff the definition above requires.
+
 ## Human's role
 
 The human reviews evidence, **judges business outcomes (NOT code)**. The LLM produces structured evidence; the human's job is to:
 
-- confirm that `allPass === true` corresponds to the business outcome they actually want (not just "tests are green");
+- confirm that `allPass === true` corresponds to the business outcome they actually want (not just "tests are green", and — for dimension 4 — not just "a diff file exists somewhere on disk");
 - decide what to do with `needsAttention` items — accept the LLM's verdict, override a `pass` to `fail` when the evidence is weak, or send the slice back to RD with a re-prompt;
 - gate the release / archive action based on `allPass` + their own business review, not just on the LLM signal.
 
@@ -185,7 +229,7 @@ When handing off, emit: rid, `allPass`, `needsAttention[]`, output path, source
 | `src/services/final-review/final-review-service.ts` | Authoritative service implementation. |
 | `src/services/final-review/final-review-types.ts` | `FinalReviewOutput`, `DimensionEvidence`, verdict/evidence/confidence enums. |
 | `src/services/audit/audit-goal-service.ts:16` | Line of evidence that `LlmRunner` is reusable across audit + final-review (service-level integration). |
-| `tests/unit/final-review/final-review-service.test.ts` | Existing service-level unit tests (5 cases). |
+| `tests/unit/final-review/final-review-service.test.ts` | Service-level unit tests (8 cases: evidence inlining, the no-evidence⇒no-`pass` gate, prompt bounds, plus contract guards). |
 | `docs/superpowers/plans/2026-06-25-slice-topology-multipass-phase-4.md:127` | Phase-4 plan prose (Task 14). |
 | `skills/peaks-qa/SKILL.md` | Upstream QA skill — 4-dim review is downstream of all QA gates. |
 | `skills/peaks-audit/SKILL.md` | Sibling skill — produces the `audit-goal` JSON that this skill consumes. |

package/skills/peaks-final-review/references/4-dimensions.md

@@ -20,10 +20,26 @@ Every acceptance criterion in the approved audit-goal at `.peaks/_runtime/<sessi
 
 ### Verdict semantics
 
-- `pass` — every AC has a passing test and the test suite is green.
+- `pass` — every AC has a passing test, the test suite is green, **and the approved-scope contract was delivered**: the `prd/handoff.md` source block reached the reviewer with its WHOLE byte count (`FOUND at … — N bytes`), because "complete" is defined against the approved scope and its non-goals, and a test report alone shows only that *something* was built.
 - `fail` — one or more ACs are unmapped, the targeted test is failing, or the suite is red on a non-flaky ground.
 - `inconclusive` (needs-human) — the mapping is plausible but the human needs to confirm that a passing test truly reflects the business intent of an AC. Example: a test exists for "config-service splits into 3 modules" but the human must decide whether the *seam* the test exercises is the seam they actually wanted.
 
+### When the scope contract does not arrive — same rule as dimension 4
+
+The service keys this dimension's `pass` on the **delivery** of its scope contract, not on its existence on disk, for the same reason dimension 4 keys its `pass` on the delivered baseline:
+
+| Situation | What the reviewer is told | Verdict the service allows |
+|---|---|---|
+| `prd/handoff.md` inlined in full | `STATUS: FOUND at … — N bytes` | `pass` is available |
+| `prd/handoff.md` present but the budget did not reach it, or the read was truncated | `STATUS: MISSING (omitted)`, or `TRUNCATED, showing the first N of M bytes` | `pass` is downgraded to `inconclusive`, with a `scope-contract-gate` marker in the summary |
+| `prd/handoff.md` exists for this run but carries nothing (0 bytes / whitespace) | `STATUS: MISSING (empty)` | Same downgrade: the PRD phase ran and the reviewer was given no contract. An empty contract is a delivery failure, not an absent phase. |
+| `prd/handoff.md` exists but this process could not read it (EACCES / EBUSY / EISDIR) | `STATUS: UNREADABLE` | Same downgrade. Deliberately NOT reported as "no PRD phase": the file is there, the read failed, and only one of those two facts is fixable. |
+| No `prd/handoff.md` in this project at all — ENOENT (no PRD phase) | `STATUS: MISSING (missing)` | Not a delivery failure — the dimension is judged on the evidence that exists. Absence is not the same fact as non-delivery. |
+
+The delivery rule is deliberately not "some bytes arrived": `qa-test-report` also supports this dimension, which is exactly how a `pass` used to survive while the contract that defines the dimension was inlined with **zero** bytes. See `enforceScopeContractDelivery()` in `src/services/final-review/final-review-service.ts`.
+
+The contract source holds a **floor** in the byte allocator: its whole unit is reserved for this dimension, so a saturated run can no longer drop it as a side effect of the allocation order. The downgrade rows above are therefore about a document that is genuinely absent, empty or unreadable — not about a contract that merely happened to sit last in the order.
+
 ### Example
 
 > `dimension: "functional-completeness"`, `verdict: "pass"`, `summary: "All 3 success criteria from the approved goal are covered by passing tests. AC-1 covered by config-service.modules.test.ts; AC-2 covered by config-service.api.test.ts (public API snapshot unchanged); AC-3 covered by coverage report at 100% lines/branches for the changed files."`, `evidence: [...]`, `confidence: "high"`.
@@ -92,10 +108,30 @@ A pre/post baseline diff shows no unintended drift in the test surface, public A
 
 ### Verdict semantics
 
-- `pass` — every measured dimension (tests, API, behavior) is unchanged or changed only in ways that the slice was explicitly authorized to change (e.g. AC-2 says "add a new exported helper `resolveWithSchema()`" — that IS the authorized change).
+- `pass` — the baseline was **compared and delivered**: the pre/post diff block reached the reviewer **with its conclusion** (`STATUS: FOUND`, and the `VERDICT:` line is in the delivered bytes — the verdict is the first thing in the artifact, so an over-cap slice still carries it), and every measured dimension (tests, API, behavior) is unchanged or changed only in ways that the slice was explicitly authorized to change (e.g. AC-2 says "add a new exported helper `resolveWithSchema()`" — that IS the authorized change).
 - `fail` — an unauthorized change slipped in: an exported symbol disappeared, a test was deleted rather than updated, a behavior baseline drifted without a corresponding AC.
 - `inconclusive` (needs-human) — a change is present that *could* be authorized drift or *could* be an unintentional regression. The human rules.
 
+### When the baseline itself is missing — the one case where no verdict can be earned
+
+A `pass` here rests on a **comparison**, so two things must both be true: the producer had to *compute* a baseline, and that baseline had to *reach the reviewer's prompt* — conclusion included. Neither substitutes for the other.
+
+| Situation | What the reviewer is told | Verdict the service allows |
+|---|---|---|
+| Baseline computed and inlined | `STATUS: COMPUTED` + the diff block | `pass` is available |
+| Baseline computed, dropped by the evidence budget | `STATUS: COMPUTED ON DISK, NOT DELIVERED` + the block marked `MISSING (omitted)` | `pass` is downgraded to `inconclusive` |
+| Baseline inlined but larger than the per-file cap | `STATUS: FOUND … TRUNCATED, showing the first N of M bytes` — the slice still opens with the `VERDICT:` line | `pass` is available (the conclusion is in the delivered bytes) |
+| No base ref resolves / base resolves to HEAD (empty range) | `STATUS: UNAVAILABLE` + the reason | `pass` is downgraded to `inconclusive` |
+| The project is not a git work tree | `STATUS: UNAVAILABLE` + the reason | `pass` is downgraded to `inconclusive` — permanently, on every run |
+
+The "dropped by the evidence budget" row is now a defensive branch rather than the expected failure: this source holds a **floor** in the allocator — its whole unit is reserved for this dimension — so when a baseline IS computed it is delivered, and the reviewer is never asked to judge this dimension against a comparison it was not shown. The rows that still fire are the ones where no baseline exists to deliver.
+
+Three consequences worth stating plainly, because all three read like defects and are not:
+
+- **A non-git project can never reach `allPass === true`.** Dimension 4 is permanently `inconclusive` there: no comparison exists to hand over, so there is no honest way to have it green. The service does not invent one, and a design-intent document (`rd/tech-doc.md`, `prd/handoff.md`) is not a substitute — it states what was intended, not what changed. There is no CLI way out either: `--base <ref>` names a COMMIT to compare against, so it cannot help a project that has no git history to resolve a ref in — the reason the reviewer is given is the project's state, not a missing argument.
+- **A dimension whose evidence was omitted does not get a pass "because the file exists".** If the block is not in the prompt, the reviewer never saw it; the service downgrades the verdict and does **not** attach the artifact as an `EvidenceItem`, because an envelope citing evidence the reviewer never received is the forged clean handoff this gate exists to prevent.
+- **A saturated run can redden more than one dimension, and that is the honest reading.** The evidence budget allocates each source WHOLE or not at all (never a partial slice), so a run whose sources do not all fit drops whole sources — and each dimension whose contract source was dropped loses its `pass`: dimension 4 when the baseline goes, dimension 1 when the approved-scope contract does.
+
 ### Example
 
 > `dimension: "existing-functionality-intact"`, `verdict: "pass"`, `summary: "Public API snapshot: 0 symbols removed, 1 symbol added (resolveWithSchema — authorized by AC-2). Test count: +12 (new tests for resolveWithSchema), -3 (deleted tests for the old monolithic resolve that resolveWithSchema supersedes). CLI help text byte-identical to pre-fix golden."`, `evidence: [{ kind: "pre-post-diff", description: "Public API surface diff: +resolveWithSchema, -3 obsolete test files, no other deltas", artifact: ".peaks/_runtime/<sessionId>/final-review/api-diff.txt" }]`, `confidence: "high"`.
@@ -106,12 +142,13 @@ A pre/post baseline diff shows no unintended drift in the test surface, public A
 
 The service contract (`src/services/final-review/final-review-service.ts:23-31` and `:88-93`):
 
-- `allPass === true` iff every dimension's `verdict === 'pass'`.
-- `needsAttention` is the list of dimension names whose verdict is `fail` or `inconclusive`. The LLM does NOT need to populate it — the service enforces presence of all 4 dimensions and the human-facing summarizer (in peaks-code or peaks-txt) computes `needsAttention` for display.
+- `allPass === true` iff every dimension's `verdict === 'pass'` **and** the service itself has nothing to flag. The two fields are derived from the verdicts, never copied from the model's own summary: a model that wrote a fabricated `pass` plus a matching `allPass: true` cannot hand over an unsupported clean review.
+- `needsAttention` is the list of dimension names whose verdict is `fail` or `inconclusive`, **plus** any dimension the service has to flag mechanically even though the reviewer passed it. The one such flag today is a delivered pre/post baseline whose own `VERDICT:` line reports `STRUCTURAL DRIFT DETECTED` (or a verdict line the service cannot classify): a detected structural removal may well be authorized, but a review that says "4/4 pass, nothing needs attention" directly above a diff that reports a removal it attached itself is self-contradicting, so that dimension is listed and `allPass` is `false`. The dimension's verdict is left as the reviewer wrote it — the call on whether a removal was authorized stays with the reviewer and the human. A second, related case is NOT a mechanical flag but a structural red the service explains: when **every** source on disk supporting a dimension is larger than the per-file cap (10,240 bytes, derived from `MAX_EVIDENCE_BYTES_TOTAL`), no source can ever be delivered under the `whole` rule, so the reviewer is told so in a `## Evidence delivery reachability (structural)` block and the dimension's summary carries a `delivery-reachability` marker naming the source and its byte count. Such a dimension is `inconclusive` by byte arithmetic — never by having passed and been overruled — and it appears in `needsAttention` through the ordinary non-`pass` route, which is what makes the CLI envelope state the reason instead of leaving a permanent red unexplained.
+- The LLM does NOT need to populate `needsAttention` — the service enforces presence of all 4 dimensions and derives the field.
 - An `IncompleteFinalReviewError` is thrown when JSON is malformed or any required dimension is missing. That is a **gate failure**, not a `fail` verdict — the LLM call is invalid and must be re-prompted, not surfaced to the human.
 
 ## Confidence and what it means
 
 - `high` — evidence is concrete (named test file, named artifact, deterministic run).
 - `medium` — evidence is concrete but covers only part of the dimension; the LLM is being honest about coverage gaps.
-- `inconclusive` verdicts should always be `medium` or `low` confidence; `high` confidence on `inconclusive` is a contradiction and the LLM should be re-prompted.
+- `inconclusive` verdicts should always be `medium` or `low` confidence; `high` confidence on `inconclusive` is a contradiction and the LLM should be re-prompted. The service does not rely on the re-prompt alone: it clamps a `high` on an `inconclusive` verdict to `medium` and marks the summary, so the contradiction cannot reach the human in the envelope even if the model keeps producing it.