peaks-loop 4.0.44 → 4.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.44",
+  "version": "4.0.45",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -102,10 +102,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.29",
-    "peaks-loop-mut": "0.1.42",
-    "peaks-loop-shared-channel": "0.0.46",
-    "peaks-loop-shared": "0.0.78"
+    "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",

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

@@ -137,40 +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'`).
 
-> **⚠️ This dimension currently cannot pass — read before acting on it (verified 2026-09-12).**
-> `pre-post-diff` is a declared `EvidenceKind`, but **nothing in peaks-loop produces that artifact**.
-> The evidence actually mapped to this dimension is `rd/tech-doc.md` (design intent) and
-> `prd/handoff.md` (scope / non-goals) — neither is a baseline diff, and the model correctly
-> reports that ("the only FOUND source… is a design-intent document, not a regression assessment").
-> `peaks scan api-diff <doc>` is *not* a producer: it diffs an API **document**, not the code surface.
+> **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.
 >
-> **Consequences:** `allPass === true` is **unreachable by construction**, for every workflow.
-> This dimension will return `inconclusive` with an empty `evidence[]` even when the work is
-> perfect. Treat that as a **tooling** state, not as evidence of a regression — and do **not**
-> "fix" it by re-mapping `qa/test-reports` into this dimension's `supports`, which would turn the
-> gate green without producing the baseline diff the definition above requires.
+> **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.
 >
-> **Real fix (unbuilt):** a producer for the pre/post baseline diff (test-count delta, public-API
-> surface snapshot) written to `.peaks/_runtime/<sessionId>/final-review/api-diff.txt`, then mapped
-> into this dimension's `supports`. Until that ships, `needsAttention` always contains this
-> dimension — a permanently-red gate that reviewers will otherwise learn to ignore.
+> **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.
 

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.