peaks-loop 4.0.53 → 4.1.0

package/dist/services/feedback/promotion-artifact-evidence.js

@@ -46,37 +46,12 @@
  * to the category, and this repo documents `commit-boundary-side-effect` beside
  * the union member while the array enforces it.
  */
-/** Is `value` a JSON object (not null, not an array)? */
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function manifestFailure(parsed, id) {
-    if (!isRecord(parsed))
-        return 'not a JSON object';
-    if (parsed.id !== id)
-        return `does not declare id "${id}"`;
-    if (!Array.isArray(parsed.gates))
-        return 'has no "gates" array';
-    return null;
-}
-function registryFailure(parsed, id) {
-    if (!isRecord(parsed))
-        return 'not a JSON object';
-    if (!Array.isArray(parsed.sops))
-        return 'has no "sops" array';
-    const registered = parsed.sops.some((entry) => isRecord(entry) && entry.id === id);
-    return registered ? null : `registry has no SOP entry with id "${id}"`;
-}
-/**
- * A tool selector: `Name` or `Name(pattern)`, one or more separated by `|` —
- * `Bash`, `Write|Edit|MultiEdit`, `Bash(git push:*)`. A segment that is not a
- * tool-name token (a hyphenated rule name, say) makes the selector malformed.
- */
-const MATCHER_SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*\s*(\(.*\))?$/;
-function isToolMatcher(matcher) {
-    const segments = matcher.split('|');
-    return segments.every((segment) => MATCHER_SEGMENT_RE.test(segment.trim()));
-}
+// Slice `b1-filesplit-campaign` (wave 3): the JSON-artifact shape predicates and
+// the comment / vocabulary-member machinery moved VERBATIM into two sibling
+// modules so this file clears the 300 raw-line cap. The two public type names are
+// re-exported from here, so no importer changed.
+import { isRecord, isToolMatcher, manifestFailure, registryFailure } from './promotion-artifact-json-evidence.js';
+import { citedMemories, commentSpans, maskComments, mergeByLiteral } from './promotion-source-comments.js';
 /**
  * Split a hook command the way a shell does: whitespace separates words, and
  * quotes group whitespace INTO a word rather than ending it. So a phrase inside
@@ -175,24 +150,6 @@ function hookFailure(parsed, id) {
     }
     return `no hook registration runs anything named "${id}" (a hook command must invoke a file named after the rule)`;
 }
-/**
- * One pattern, used by BOTH the masker and the doc reader, so a comment can
- * never be blanked by one and read as a doc by the other.
- */
-const COMMENT_RE = /\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
-/** Comments are blanked to spaces, which keeps every offset in the file valid. */
-function maskComments(text) {
-    return text.replace(COMMENT_RE, (comment) => ' '.repeat(comment.length));
-}
-function commentSpans(source) {
-    const spans = [];
-    COMMENT_RE.lastIndex = 0;
-    let match;
-    while ((match = COMMENT_RE.exec(source)) !== null) {
-        spans.push({ start: match.index, end: match.index + match[0].length, text: match[0] });
-    }
-    return spans;
-}
 /**
  * Collect the members of the hard-floor vocabulary, each with the comment text
  * that governs it. `masked` decides where a member STARTS (so a quoted string
@@ -253,40 +210,6 @@ function vocabularyMembers(source) {
     }
     return mergeByLiteral(raw);
 }
-/**
- * R10 — one entry per literal, and `enforcing` is only ever set by the array.
- *
- * Reading the two declarations as one flat member list let a member of the
- * `HardFloorCategory` union ALONE satisfy this check while
- * `isHardFloorCategory` — and therefore `shouldPauseAtGate` — did not recognise
- * it. The gate reported BACKED for a hard floor that paused nothing. Splitting
- * the provenance of `enforcing` out of the member list is what makes the two
- * agree: what the predicate accepts is exactly what the array contains.
- *
- * The docs are joined across occurrences rather than kept per-declaration,
- * because a category's doc belongs to the CATEGORY. This repo's own layer-C
- * promotion cites `.peaks/memory/2026-06-28-full-auto-boundary.md` from the
- * comment beside the UNION member of `commit-boundary-side-effect`, while the
- * ARRAY is what enforces it; reading the doc from one declaration only would
- * make that citation unreadable — a false negative on a file already known good.
- */
-function mergeByLiteral(members) {
-    const merged = new Map();
-    for (const member of members) {
-        const previous = merged.get(member.literal);
-        merged.set(member.literal, {
-            literal: member.literal,
-            doc: [previous?.doc, member.doc].filter((doc) => doc !== undefined && doc !== '').join('\n'),
-            enforcing: (previous?.enforcing ?? false) || member.enforcing
-        });
-    }
-    return [...merged.values()];
-}
-/** A memory cited by path, the way this repo cites one (`mode-gate.ts:41`). */
-const MEMORY_CITATION_RE = /\.peaks\/memory\/([A-Za-z0-9._-]+)\.md/g;
-function citedMemories(doc) {
-    return Array.from(doc.matchAll(MEMORY_CITATION_RE), (match) => match[1]);
-}
 /**
  * Layer C. The rule counts when it IS a member of `HARD_FLOOR_CATEGORIES`, or
  * when one of THAT ARRAY's members has a doc block that CITES it the way this

package/dist/services/feedback/promotion-artifact-json-evidence.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the JSON-artifact
+ * half of `./promotion-artifact-evidence.ts` (the evidence vocabulary and the three
+ * layer-A / layer-B shape predicates) so that module clears the 300 raw-line cap.
+ * No predicate body, no doc comment and no message string changed; the original
+ * module re-exports the two public type names from its own path, so importers are
+ * untouched.
+ */
+export type PromotionEvidence = 
+/** A SOP manifest: a JSON object whose `id` is the SOP's and whose `gates` is an array. */
+'sop-manifest'
+/** An entry with the SOP's `id` inside `<registry>.sops[]` — what `readRegistry()` enumerates. */
+ | 'sop-registry-entry'
+/** A hook registration (hook command) inside `hooks` that runs something named after the rule. */
+ | 'hook-registration'
+/** A member of `HARD_FLOOR_CATEGORIES` — the array `isHardFloorCategory` reads — that names the rule. */
+ | 'hard-floor-category';
+export type PromotionArtifactCheck = {
+    /** Project-relative POSIX path whose CONTENT must carry the evidence. */
+    path: string;
+    evidence: PromotionEvidence;
+    /** The rule id the evidence must name (a SOP id for layer A, a memory name for B and C). */
+    id: string;
+};
+/** Is `value` a JSON object (not null, not an array)? */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function manifestFailure(parsed: unknown, id: string): string | null;
+export declare function registryFailure(parsed: unknown, id: string): string | null;
+export declare function isToolMatcher(matcher: string): boolean;

package/dist/services/feedback/promotion-artifact-json-evidence.js

@@ -0,0 +1,39 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the JSON-artifact
+ * half of `./promotion-artifact-evidence.ts` (the evidence vocabulary and the three
+ * layer-A / layer-B shape predicates) so that module clears the 300 raw-line cap.
+ * No predicate body, no doc comment and no message string changed; the original
+ * module re-exports the two public type names from its own path, so importers are
+ * untouched.
+ */
+/** Is `value` a JSON object (not null, not an array)? */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function manifestFailure(parsed, id) {
+    if (!isRecord(parsed))
+        return 'not a JSON object';
+    if (parsed.id !== id)
+        return `does not declare id "${id}"`;
+    if (!Array.isArray(parsed.gates))
+        return 'has no "gates" array';
+    return null;
+}
+export function registryFailure(parsed, id) {
+    if (!isRecord(parsed))
+        return 'not a JSON object';
+    if (!Array.isArray(parsed.sops))
+        return 'has no "sops" array';
+    const registered = parsed.sops.some((entry) => isRecord(entry) && entry.id === id);
+    return registered ? null : `registry has no SOP entry with id "${id}"`;
+}
+/**
+ * A tool selector: `Name` or `Name(pattern)`, one or more separated by `|` —
+ * `Bash`, `Write|Edit|MultiEdit`, `Bash(git push:*)`. A segment that is not a
+ * tool-name token (a hyphenated rule name, say) makes the selector malformed.
+ */
+const MATCHER_SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*\s*(\(.*\))?$/;
+export function isToolMatcher(matcher) {
+    const segments = matcher.split('|');
+    return segments.every((segment) => MATCHER_SEGMENT_RE.test(segment.trim()));
+}

package/dist/services/feedback/promotion-source-comments.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the comment /
+ * vocabulary-member machinery from `./promotion-artifact-evidence.ts` so that
+ * module clears the 300 raw-line cap. These are the declarations the hard-floor
+ * reader is built ON (comment masking, comment spans, the member shape, the
+ * by-literal merge and the memory-citation pattern); the reader itself
+ * (`collectMembers` / `vocabularyMembers` / `hardFloorFailure`) stays where it
+ * was, importing these. No body, doc comment or regex changed.
+ */
+/** Comments are blanked to spaces, which keeps every offset in the file valid. */
+export declare function maskComments(text: string): string;
+export type CommentSpan = {
+    start: number;
+    end: number;
+    text: string;
+};
+export declare function commentSpans(source: string): CommentSpan[];
+export type VocabularyMember = {
+    literal: string;
+    doc: string;
+    /**
+     * R10: does this member sit in the declaration that ENFORCES — the
+     * `HARD_FLOOR_CATEGORIES` array `isHardFloorCategory` reads? A member of the
+     * `HardFloorCategory` union alone is a type; it pauses nothing, so it is not
+     * evidence that a rule is a hard floor.
+     */
+    enforcing: boolean;
+};
+/**
+ * R10 — one entry per literal, and `enforcing` is only ever set by the array.
+ *
+ * Reading the two declarations as one flat member list let a member of the
+ * `HardFloorCategory` union ALONE satisfy this check while
+ * `isHardFloorCategory` — and therefore `shouldPauseAtGate` — did not recognise
+ * it. The gate reported BACKED for a hard floor that paused nothing. Splitting
+ * the provenance of `enforcing` out of the member list is what makes the two
+ * agree: what the predicate accepts is exactly what the array contains.
+ *
+ * The docs are joined across occurrences rather than kept per-declaration,
+ * because a category's doc belongs to the CATEGORY. This repo's own layer-C
+ * promotion cites `.peaks/memory/2026-06-28-full-auto-boundary.md` from the
+ * comment beside the UNION member of `commit-boundary-side-effect`, while the
+ * ARRAY is what enforces it; reading the doc from one declaration only would
+ * make that citation unreadable — a false negative on a file already known good.
+ */
+export declare function mergeByLiteral(members: readonly VocabularyMember[]): VocabularyMember[];
+export declare function citedMemories(doc: string): string[];

package/dist/services/feedback/promotion-source-comments.js

@@ -0,0 +1,61 @@
+/**
+ * Slice `b1-filesplit-campaign` (wave 3) — verbatim extraction of the comment /
+ * vocabulary-member machinery from `./promotion-artifact-evidence.ts` so that
+ * module clears the 300 raw-line cap. These are the declarations the hard-floor
+ * reader is built ON (comment masking, comment spans, the member shape, the
+ * by-literal merge and the memory-citation pattern); the reader itself
+ * (`collectMembers` / `vocabularyMembers` / `hardFloorFailure`) stays where it
+ * was, importing these. No body, doc comment or regex changed.
+ */
+/**
+ * One pattern, used by BOTH the masker and the doc reader, so a comment can
+ * never be blanked by one and read as a doc by the other.
+ */
+const COMMENT_RE = /\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
+/** Comments are blanked to spaces, which keeps every offset in the file valid. */
+export function maskComments(text) {
+    return text.replace(COMMENT_RE, (comment) => ' '.repeat(comment.length));
+}
+export function commentSpans(source) {
+    const spans = [];
+    COMMENT_RE.lastIndex = 0;
+    let match;
+    while ((match = COMMENT_RE.exec(source)) !== null) {
+        spans.push({ start: match.index, end: match.index + match[0].length, text: match[0] });
+    }
+    return spans;
+}
+/**
+ * R10 — one entry per literal, and `enforcing` is only ever set by the array.
+ *
+ * Reading the two declarations as one flat member list let a member of the
+ * `HardFloorCategory` union ALONE satisfy this check while
+ * `isHardFloorCategory` — and therefore `shouldPauseAtGate` — did not recognise
+ * it. The gate reported BACKED for a hard floor that paused nothing. Splitting
+ * the provenance of `enforcing` out of the member list is what makes the two
+ * agree: what the predicate accepts is exactly what the array contains.
+ *
+ * The docs are joined across occurrences rather than kept per-declaration,
+ * because a category's doc belongs to the CATEGORY. This repo's own layer-C
+ * promotion cites `.peaks/memory/2026-06-28-full-auto-boundary.md` from the
+ * comment beside the UNION member of `commit-boundary-side-effect`, while the
+ * ARRAY is what enforces it; reading the doc from one declaration only would
+ * make that citation unreadable — a false negative on a file already known good.
+ */
+export function mergeByLiteral(members) {
+    const merged = new Map();
+    for (const member of members) {
+        const previous = merged.get(member.literal);
+        merged.set(member.literal, {
+            literal: member.literal,
+            doc: [previous?.doc, member.doc].filter((doc) => doc !== undefined && doc !== '').join('\n'),
+            enforcing: (previous?.enforcing ?? false) || member.enforcing
+        });
+    }
+    return [...merged.values()];
+}
+/** A memory cited by path, the way this repo cites one (`mode-gate.ts:41`). */
+const MEMORY_CITATION_RE = /\.peaks\/memory\/([A-Za-z0-9._-]+)\.md/g;
+export function citedMemories(doc) {
+    return Array.from(doc.matchAll(MEMORY_CITATION_RE), (match) => match[1]);
+}

package/dist/services/final-review/final-review-contract.d.ts

@@ -0,0 +1,26 @@
+export interface LlmRunner {
+    call(systemPrompt: string, userPrompt: string, opts: {
+        maxTokens: number;
+    }): Promise<{
+        output: string;
+        tokens: {
+            input: number;
+            output: number;
+        };
+    }>;
+}
+export interface PrepareFinalReviewOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly llmRunner: LlmRunner;
+    /**
+     * Explicit base ref for the pre/post baseline diff. Unset ⇒ the producer
+     * resolves the merge-base with the upstream default branch itself, and
+     * reports the dimension `unavailable` when it cannot.
+     */
+    readonly baseRef?: string;
+}
+export declare class IncompleteFinalReviewError extends Error {
+    readonly code: "INCOMPLETE_FINAL_REVIEW";
+    constructor(message: string);
+}

package/dist/services/final-review/final-review-contract.js

@@ -0,0 +1,14 @@
+// src/services/final-review/final-review-contract.ts
+//
+// The caller-facing contract of the final-review service: the inline
+// LlmRunner copy, the prepare() options and the incomplete-review error.
+// Hoisted verbatim from final-review-service.ts (C wave 7 file-size
+// split); the service module re-exports all three so no importer's path
+// or symbol changed.
+export class IncompleteFinalReviewError extends Error {
+    code = 'INCOMPLETE_FINAL_REVIEW';
+    constructor(message) {
+        super(message);
+        this.name = 'IncompleteFinalReviewError';
+    }
+}

package/dist/services/final-review/final-review-delivery.d.ts

@@ -0,0 +1,63 @@
+import type { CollectedEvidence } from './final-review-evidence-sources.js';
+import type { DimensionEvidence, DimensionKind } from './final-review-types.js';
+/**
+ * H2 — the reason a dimension is red PERMANENTLY, as opposed to merely unfed on
+ * this run. Reported per source, so the arithmetic is checkable by the reader.
+ */
+export interface UndeliverableDimensionEvidence {
+    readonly dimension: DimensionKind;
+    readonly sources: readonly {
+        readonly key: string;
+        readonly relativePath: string;
+        readonly totalBytes: number;
+    }[];
+}
+/**
+ * H2 — every required dimension whose verdict is locked to `inconclusive` by
+ * BYTE ARITHMETIC rather than by the reviewer's judgement.
+ *
+ * The defect this exists for: `qa/test-reports/<rid>.md` measured 9,492 bytes
+ * on this repo's own run and is the ONLY source on disk for `problem-resolution`
+ * and `no-new-bugs` (the other sources that support them are absent), against a
+ * per-file cap of 10,240 — a 748-byte margin on a file that is REWRITTEN every
+ * round and only grows. The moment it crosses 10,240 both dimensions go
+ * permanently red, and NOTHING said so: `assertFloorReservationAffordable()`
+ * only checks the constant-level relation (`4 x cap <= total`), never whether
+ * any actual source fits the cap it must live under, so the red handoff read as
+ * "the reviewer was unsure" instead of "no evidence can ever reach the
+ * reviewer". A gate that is always red and never explains itself is noise, and
+ * this is the same "always red" harm the floor reservation was built to remove
+ * — one layer down.
+ *
+ * The conditions, all three of which must hold, are chosen so the report cannot
+ * be noise:
+ *   1. NOTHING on disk can back the dimension (no `isDelivered`), and
+ *   2. there IS something on disk to deliver (a source that was never written
+ *      is not a delivery failure — same reasoning as the scope-contract gate's
+ *      `missing` exemption: a run with no QA phase has no report to lose), and
+ *   3. EVERY one of those on-disk sources is structurally undeliverable — a
+ *      single source that merely did not fit TODAY (budget-exhausted `omitted`)
+ *      is a different, self-correcting state and is left to the allocator.
+ *
+ * The report is consumed by the prompt (stated to the reviewer), by the
+ * envelope (a marker on each dimension's summary) and by `needsAttention`
+ * (which also clears `allPass`) — see `enforceDeliveryReachability` and
+ * `renderDeliveryReachabilityStatus`. It is a LOUD STATEMENT, not a silent
+ * downgrade, and it is deliberately not a throw: a crash would destroy the
+ * evidence for the three dimensions that ARE deliverable, and the honest fact
+ * here is per-dimension, so it is reported per-dimension.
+ */
+export declare function undeliverableDimensions(collected: readonly CollectedEvidence[]): readonly UndeliverableDimensionEvidence[];
+/**
+ * H2 — the envelope half of the same fact. A dimension named by
+ * `undeliverableDimensions()` cannot be `pass` (no source on disk can carry its
+ * conclusion), so this is not where the verdict is decided — that is
+ * `enforceEvidenceBackedVerdicts`, and this gate re-applies it so the property
+ * does not depend on that gate's order. What this adds is the REASON: the
+ * dimension's own summary says it is red by construction. Because the verdict
+ * it leaves behind is non-`pass`, the dimension also reaches `needsAttention`
+ * (and clears `allPass`) through the ordinary verdict route, which is the field
+ * the CLI envelope prints — so the human is told WHY instead of being left to
+ * read a permanent red as the reviewer's uncertainty.
+ */
+export declare function enforceDeliveryReachability(dimensions: readonly DimensionEvidence[], report: readonly UndeliverableDimensionEvidence[]): readonly DimensionEvidence[];

package/dist/services/final-review/final-review-delivery.js

@@ -0,0 +1,124 @@
+// src/services/final-review/final-review-delivery.ts
+//
+// H2 — the delivery-reachability analysis and its envelope gate. The
+// judgement itself stays delegated to isDelivered, which remains in the
+// service module (guard C pins it there) — this module asks it.
+// Hoisted verbatim from final-review-service.ts (C wave 7 file-size
+// split).
+import { isDelivered } from './final-review-service.js';
+import { MAX_EVIDENCE_BYTES_PER_FILE, REQUIRED_DIMENSIONS } from './final-review-evidence-budget.js';
+/**
+ * Can this source EVER be delivered, whatever the budget?
+ *
+ * `whole` is the only rule with a structural ceiling. Its test is
+ * `includedBytes === totalBytes`, and the allocator can only ever inline
+ * `min(bytes, MAX_EVIDENCE_BYTES_PER_FILE)` — so a `whole`-rule source LARGER
+ * than the per-file cap can never be delivered: not on this run, not on any
+ * run, not with any budget, because the budget is not what cuts it. Raising
+ * `MAX_EVIDENCE_BYTES_TOTAL` changes nothing either, since the per-file cap is
+ * derived from it and the reservation spends all of it.
+ *
+ * (`conclusion` sources are deliberately NOT covered. A marker missing from the
+ * first cap-sized bytes of an oversize artifact might simply live past the cut,
+ * so "undeliverable forever" is not a claim this module can make about them —
+ * and an over-claiming check is the failure mode this file keeps closing.)
+ */
+function isStructurallyUndeliverable(item) {
+    if (item.source.delivery.kind !== 'whole')
+        return false;
+    return item.totalBytes > MAX_EVIDENCE_BYTES_PER_FILE;
+}
+/**
+ * H2 — every required dimension whose verdict is locked to `inconclusive` by
+ * BYTE ARITHMETIC rather than by the reviewer's judgement.
+ *
+ * The defect this exists for: `qa/test-reports/<rid>.md` measured 9,492 bytes
+ * on this repo's own run and is the ONLY source on disk for `problem-resolution`
+ * and `no-new-bugs` (the other sources that support them are absent), against a
+ * per-file cap of 10,240 — a 748-byte margin on a file that is REWRITTEN every
+ * round and only grows. The moment it crosses 10,240 both dimensions go
+ * permanently red, and NOTHING said so: `assertFloorReservationAffordable()`
+ * only checks the constant-level relation (`4 x cap <= total`), never whether
+ * any actual source fits the cap it must live under, so the red handoff read as
+ * "the reviewer was unsure" instead of "no evidence can ever reach the
+ * reviewer". A gate that is always red and never explains itself is noise, and
+ * this is the same "always red" harm the floor reservation was built to remove
+ * — one layer down.
+ *
+ * The conditions, all three of which must hold, are chosen so the report cannot
+ * be noise:
+ *   1. NOTHING on disk can back the dimension (no `isDelivered`), and
+ *   2. there IS something on disk to deliver (a source that was never written
+ *      is not a delivery failure — same reasoning as the scope-contract gate's
+ *      `missing` exemption: a run with no QA phase has no report to lose), and
+ *   3. EVERY one of those on-disk sources is structurally undeliverable — a
+ *      single source that merely did not fit TODAY (budget-exhausted `omitted`)
+ *      is a different, self-correcting state and is left to the allocator.
+ *
+ * The report is consumed by the prompt (stated to the reviewer), by the
+ * envelope (a marker on each dimension's summary) and by `needsAttention`
+ * (which also clears `allPass`) — see `enforceDeliveryReachability` and
+ * `renderDeliveryReachabilityStatus`. It is a LOUD STATEMENT, not a silent
+ * downgrade, and it is deliberately not a throw: a crash would destroy the
+ * evidence for the three dimensions that ARE deliverable, and the honest fact
+ * here is per-dimension, so it is reported per-dimension.
+ */
+export function undeliverableDimensions(collected) {
+    const report = [];
+    for (const dimension of REQUIRED_DIMENSIONS) {
+        const supporting = collected.filter((item) => item.source.supports.includes(dimension));
+        if (supporting.some((item) => isDelivered(item, dimension)))
+            continue;
+        const onDisk = supporting.filter((item) => item.totalBytes > 0);
+        if (onDisk.length === 0)
+            continue;
+        if (!onDisk.every(isStructurallyUndeliverable))
+            continue;
+        report.push({
+            dimension,
+            sources: onDisk.map((item) => ({
+                key: item.source.key,
+                relativePath: item.relativePath,
+                totalBytes: item.totalBytes
+            }))
+        });
+    }
+    return report;
+}
+/**
+ * H2 — the envelope half of the same fact. A dimension named by
+ * `undeliverableDimensions()` cannot be `pass` (no source on disk can carry its
+ * conclusion), so this is not where the verdict is decided — that is
+ * `enforceEvidenceBackedVerdicts`, and this gate re-applies it so the property
+ * does not depend on that gate's order. What this adds is the REASON: the
+ * dimension's own summary says it is red by construction. Because the verdict
+ * it leaves behind is non-`pass`, the dimension also reaches `needsAttention`
+ * (and clears `allPass`) through the ordinary verdict route, which is the field
+ * the CLI envelope prints — so the human is told WHY instead of being left to
+ * read a permanent red as the reviewer's uncertainty.
+ */
+export function enforceDeliveryReachability(dimensions, report) {
+    if (report.length === 0)
+        return dimensions;
+    const byDimension = new Map(report.map((entry) => [entry.dimension, entry]));
+    return dimensions.map((dimension) => {
+        const entry = byDimension.get(dimension.dimension);
+        if (entry === undefined)
+            return dimension;
+        // The ENVELOPE is not byte-capped, so it names the path as well as the
+        // size: the path is what a human has to act on to fix it.
+        const detail = entry.sources
+            .map((item) => `${item.key} at ${item.relativePath} (${String(item.totalBytes)} bytes)`)
+            .join(', ');
+        const marker = `[delivery-reachability: ${dimension.verdict === 'pass'
+            ? 'verdict downgraded from "pass" to "inconclusive"'
+            : `gate ran; verdict "${dimension.verdict}" is already non-"pass" and is left unchanged`} — EVERY source on disk that supports "${dimension.dimension}" (${detail}) is larger than the per-file delivery cap of ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes, and a source is inlined WHOLE or not at all, so no evidence for this dimension can ever reach the reviewer. The dimension is red by byte arithmetic, not by the reviewer's judgement, and it is listed in needsAttention for that reason.]`;
+        const annotated = {
+            ...dimension,
+            summary: `${dimension.summary} ${marker}`
+        };
+        if (dimension.verdict !== 'pass')
+            return annotated;
+        return { ...annotated, verdict: 'inconclusive', confidence: 'low' };
+    });
+}

package/dist/services/final-review/final-review-evidence-budget.d.ts

@@ -0,0 +1,125 @@
+import type { DimensionKind } from './final-review-types.js';
+import type { EvidenceCandidate } from './final-review-evidence-sources.js';
+export declare const REQUIRED_DIMENSIONS: readonly DimensionKind[];
+/**
+ * Total evidence budget across all sources. 40 KB ≈ 10k tokens of input, which
+ * keeps the prompt far inside any modern context window. Sources that do not
+ * fit are reported as OMITTED — never dropped silently.
+ *
+ * This is an INPUT cap and stays fixed per run. The output ceiling that has to
+ * sit opposite it is derived per call by `outputBudgetForEvidence()` below —
+ * the two used to drift apart, and that drift was the defect.
+ *
+ * RE-EVALUATED 2026-09-12 (F-BLOCK) — 32 KiB did NOT hold once the tenth
+ * source (`final-review-pre-post-diff`) was appended. Measured on this repo's
+ * own run (`2026-09-12-session-e37ef0`, rid
+ * `2026-09-12-codegraph-exclude-integrity`), the ten sources are 2,621 / 8,164
+ * / 9,492 / 10,839 / 11,422 / 13,050 / 13,462 / 13,852 / 17,745 / 20,543
+ * bytes — 121,190 bytes on disk, 76,321 bytes once the 8 KiB per-file cap is
+ * applied. Four sources at the cap spent the old 32,768 to the byte, so the
+ * appended tenth (added LAST, by design) was the first block the budget
+ * dropped — on every run, and on the compact set QA measured too (9 x 3.8 KB
+ * ≈ 34 KB, which the old cap already could not hold).
+ *
+ * 40 KiB is a budget that fits the measured ten-source set at the allocator's
+ * per-source unit (5 x 8 KiB units + the smaller ones), and it is the largest
+ * this budget may grow to today: the derived output ceiling is
+ * `3000 + 12288 + bytes/4`, so it reaches MAX_OUTPUT_TOKENS (32,000) at exactly
+ * 66,848 bytes of inlined evidence and is clamped from there on — a cap at or
+ * above that point buys the reviewer no more output room at all.
+ *
+ * F-CAP — an earlier version of this comment claimed 40 KiB (40,960 =
+ * 10 x 4,096) was "the smallest cap that affords one floor-sized slice to EVERY
+ * source in the ten-source set". That was arithmetic about a budget, not a
+ * statement about the allocator: sources are capped at
+ * MAX_EVIDENCE_BYTES_PER_FILE (10 KiB each, derived — see below) while a floor
+ * is per DIMENSION (four of them), so 10 x 4,096 was never what any source
+ * received. Re-measured on
+ * the same two saturated fixtures (QA round 4: the 9 x 40 KB fixture and this
+ * repo's own file sizes), raising the cap from 32 KiB to 40 KiB left **4 of the
+ * 10 sources inlined with zero bytes** — `rd/security-review`,
+ * `rd/bug-analysis`, `prd/handoff` and the appended
+ * `final-review-pre-post-diff` — and it did not deliver the baseline either;
+ * all it did was change WHICH source was starved (at 32 KiB that source was
+ * `rd/code-review`).
+ *
+ * So read this constant as "how much evidence fits", never as "which sources
+ * arrive". Arrival is decided by the allocator below (one whole unit per source,
+ * with a dimension's floor reserving its holder's unit) and, for the two sources
+ * a dimension's verdict may not outlive, by the delivery gates on top of it.
+ * And note the honest consequence, stated rather than papered over: on a
+ * saturated run the allocator still omits sources, so `prd/handoff.md` and the
+ * pre/post diff can be dropped — which is exactly why
+ * `enforceScopeContractDelivery()` and `enforcePrePostDiffAvailability()` exist
+ * and why a `pass` on those two dimensions is keyed on delivery, not on
+ * existence.
+ */
+export declare const MAX_EVIDENCE_BYTES_TOTAL = 40960;
+/**
+ * Per-file evidence cap — and the allocator's UNIT. DERIVED, never typed.
+ *
+ * F5 — this used to be the literal `8 * 1024`, and the whole floor guarantee
+ * below was silently conditioned on `4 x perFile <= total`: the reservation
+ * promises every pending holder its own unit, and that promise holds only while
+ * the four units fit the budget together. At `8 * 1024` the inequality held by
+ * coincidence (4 x 8,192 = 32,768 <= 40,960) and nothing in the code said so —
+ * raising the cap past 10,240 would have starved all four dimensions in the
+ * same run, which reads as four independent red gates rather than one broken
+ * constant. The cap is therefore DIVIDED OUT OF the total: the relation is
+ * definitional instead of remembered, and `assertFloorReservationAffordable()`
+ * still checks it at the point of use (the division must also be exact).
+ *
+ * The value is 10,240 because that is `40,960 / 4` — the largest unit the
+ * four-dimension reservation can afford. It is also the smallest cap at which
+ * the decisive evidence source of this repo's own run can be delivered WHOLE:
+ * `qa/test-reports/<rid>.md` measured 9,492 bytes there, and `whole` is the
+ * delivery rule for every source whose producer publishes no conclusion literal
+ * (see `isDelivered`), so a cap under 9,492 makes `problem-resolution` and
+ * `no-new-bugs` undeliverable on every run — the always-red gate this module
+ * refuses to ship. Enforced in BYTES against the raw buffer, so multi-byte
+ * (CJK) content cannot slip past the cap.
+ *
+ * A source is inlined as `min(bytes, this cap)` — its whole unit — or not at
+ * all. So a `TRUNCATED` source block can only ever mean "the FILE is bigger
+ * than this cap"; it can no longer mean "the budget ran out while this file was
+ * being copied in". That distinction is the point of the all-or-nothing
+ * allocator below: the second reading is what let one byte of a 4,226-byte
+ * artifact be counted as delivered evidence (F-BLOCK-1BYTE).
+ */
+export declare const MAX_EVIDENCE_BYTES_PER_FILE: number;
+/**
+ * The unit the allocator hands out: one source's WHOLE slice — its bytes up to
+ * the per-file cap — or nothing at all.
+ *
+ * F-BLOCK-1BYTE — the allocator used to take `min(perFileCap, budgetLeft)`, so
+ * the last source the budget reached was cut wherever the budget ran out.
+ * `status: 'found'` then meant "at least one byte arrived", and every gate that
+ * asked "did the reviewer see this source?" was answering a question with a
+ * continuum of possible answers. The observed output (QA round 4, 9 x 4,551 B
+ * sources, `api-diff.txt` at 4,226 B): the pre/post diff was inlined as **1
+ * byte** — the character `#` — while the producer block still said
+ * `STATUS: COMPUTED … cite it`, the dimension kept its `pass`/`high`, the
+ * artifact was attached as evidence, and the envelope returned `allPass: true`.
+ * Each earlier fix had moved the threshold that separated "some bytes" from
+ * "the evidence"; this removes the continuum instead, so no predicate can be
+ * re-tuned into the same hole a fifth time.
+ */
+export declare function sourceUnit(candidate: EvidenceCandidate): number;
+/**
+ * F5 — the floor promise, checked where it is relied on instead of remembered.
+ *
+ * The allocator's loop invariant is `budgetLeft >= sum(units of pending
+ * holders)`, and its INITIAL condition is
+ * `REQUIRED_DIMENSIONS.length x MAX_EVIDENCE_BYTES_PER_FILE <=
+ * MAX_EVIDENCE_BYTES_TOTAL`. While that holds, every holder is served when it
+ * is reached and the reservation is a guarantee; the moment it fails, all four
+ * dimensions are starved in the same run — which surfaces as four independent
+ * red gates rather than as one broken constant, and is therefore the kind of
+ * breakage nobody diagnoses correctly.
+ *
+ * The cap is derived from the total so the inequality cannot be typed wrong,
+ * and this check covers the two ways a derivation can still go bad: a
+ * non-integer quotient (a fifth dimension, say) and a future re-typing of
+ * either constant. It is exported because a test asserts it directly.
+ */
+export declare function assertFloorReservationAffordable(): void;