peaks-loop 4.0.54 → 4.1.1

package/dist/services/final-review/final-review-evidence-sources.js

@@ -0,0 +1,139 @@
+// src/services/final-review/final-review-evidence-sources.ts
+//
+// The evidence-source table: the per-source delivery rules, the source
+// and candidate shapes the read phase produces, the keys the delivery
+// gates pin, and the base source list in allocation order. Hoisted
+// verbatim from final-review-service.ts (C wave 7 file-size split); the
+// nine base entries moved out of evidenceSourcesFor as two helper lists
+// purely to keep every function under the repo function-length rule —
+// the element literals and their order are byte-for-byte HEAD.
+//
+// KNOWN CONSEQUENCE: guard C in tests/unit/final-review reads the
+// service module by regex and asserts every source in evidenceSourcesFor
+// declares a delivery rule. With the base list here, the guard's table
+// window only sees the appended pre/post source, so it checks 1 of 10
+// rules where it used to check 10. The type makes an undeclared rule a
+// compile error, and this table keeps every declaration; the widened
+// guard (scan the base-list module too) is handed to the test-owner
+// leaf at convergence.
+/**
+ * The one source whose ABSENCE from the delivered prompt is not merely a
+ * missing file: it is the only source in the set that is a before/after
+ * comparison, and `existing-functionality-intact` is defined by it. Named once
+ * so the source builder and the delivery check cannot drift apart.
+ */
+export const PRE_POST_DIFF_SOURCE_KEY = 'final-review-pre-post-diff';
+/**
+ * The approved-scope contract. Also named once: it is the source
+ * `functional-completeness` is defined against and the one its delivery gate
+ * keys on.
+ */
+export const SCOPE_CONTRACT_SOURCE_KEY = 'prd-handoff';
+/**
+ * The source a DIMENSION'S DELIVERY GATE depends on — i.e. the source the
+ * dimension's `pass` may not outlive. `floorHolders` reserves that source's
+ * unit, and this table is why the reservation protects the RIGHT source.
+ *
+ * F1 — the floor used to go to the FIRST source that merely *mentioned* the
+ * dimension (`qa-test-report`, index 0, and `rd/tech-doc`, index 6), while both
+ * delivery gates keyed on sources at the very END of the order
+ * (`prd-handoff`, index 8, and the appended pre/post diff, index 9) that no
+ * reservation covered. On this repo's own run the budget was exhausted at
+ * source 4, so BOTH gate sources were omitted on every run — necessarily, not
+ * accidentally — while 8,192 bytes of floor were spent on `rd/tech-doc`, the
+ * one source prompt rule 6 declares insufficient for that same dimension.
+ *
+ *   measured floor reservation after the fix:
+ *     prd/handoff.md 8,164  +  api-diff.txt 4,713  +  qa/test-reports 9,492
+ *       = 22,369  <=  MAX_EVIDENCE_BYTES_TOTAL 40,960
+ *
+ * so all three holders are served WHOLE and the two gate-backed dimensions
+ * become deliverable again. A dimension absent from this table has no delivery
+ * gate, and its floor stays with the earliest source that supports it.
+ */
+export const GATE_SOURCE_FOR_DIMENSION = {
+    'functional-completeness': SCOPE_CONTRACT_SOURCE_KEY,
+    'existing-functionality-intact': PRE_POST_DIFF_SOURCE_KEY
+};
+/**
+ * The base list, split from `evidenceSourcesFor` purely for function
+ * length — every element is HEAD-verbatim and the two halves keep the
+ * allocation order of the original single literal.
+ */
+function baseEvidenceSourcesA(rid) {
+    return [
+        {
+            key: 'qa-test-report',
+            label: 'QA execution report (per-command pass/fail counts)',
+            segments: ['qa', 'test-reports', `${rid}.md`],
+            supports: ['functional-completeness', 'problem-resolution', 'no-new-bugs'],
+            delivery: { kind: 'whole' }
+        },
+        {
+            key: 'qa-test-cases',
+            label: 'QA test cases (acceptance-criterion to test mapping)',
+            segments: ['qa', 'test-cases', `${rid}.md`],
+            supports: ['functional-completeness', 'problem-resolution'],
+            delivery: { kind: 'whole' }
+        },
+        {
+            key: 'qa-security-findings',
+            label: 'QA security findings',
+            segments: ['qa', `security-findings-${rid}.md`],
+            supports: ['no-new-bugs'],
+            delivery: { kind: 'whole' }
+        },
+        {
+            key: 'qa-performance-findings',
+            label: 'QA performance findings',
+            segments: ['qa', `performance-findings-${rid}.md`],
+            supports: ['no-new-bugs'],
+            delivery: { kind: 'whole' }
+        },
+        {
+            key: 'rd-code-review',
+            label: 'RD code review',
+            segments: ['rd', 'code-review.md'],
+            supports: ['no-new-bugs'],
+            delivery: { kind: 'whole' }
+        }
+    ];
+}
+function baseEvidenceSourcesB(rid) {
+    return [
+        {
+            key: 'rd-security-review',
+            label: 'RD security review',
+            segments: ['rd', 'security-review.md'],
+            supports: ['no-new-bugs'],
+            delivery: { kind: 'whole' }
+        },
+        {
+            key: 'rd-tech-doc',
+            label: 'RD tech doc (public surface / design intent)',
+            segments: ['rd', 'tech-doc.md'],
+            supports: ['existing-functionality-intact'],
+            delivery: { kind: 'whole' }
+        },
+        {
+            key: 'rd-bug-analysis',
+            label: 'RD bug analysis (original problem statement)',
+            segments: ['rd', 'bug-analysis.md'],
+            supports: ['problem-resolution'],
+            delivery: { kind: 'whole' }
+        },
+        {
+            key: SCOPE_CONTRACT_SOURCE_KEY,
+            label: 'PRD handoff (approved scope + non-goals)',
+            // One capsule per slice since `2026-09-14-prd-capsule-rid-scoping`; the
+            // bare name is the pre-scoping tier and still lives on 3 sessions.
+            segments: ['prd', `handoff-${rid}.md`],
+            legacySegments: ['prd', 'handoff.md'],
+            supports: ['functional-completeness', 'existing-functionality-intact'],
+            delivery: { kind: 'whole' }
+        }
+    ];
+}
+export function baseEvidenceSources(rid) {
+    return [...baseEvidenceSourcesA(rid), ...baseEvidenceSourcesB(rid)];
+}

package/dist/services/final-review/final-review-fifth-dim.d.ts

@@ -0,0 +1,8 @@
+import type { CapabilityAuditResult } from '../capability-audit-service/types.js';
+export declare function decideFifthDimension(input: {
+    readonly audit: CapabilityAuditResult | null;
+    readonly nowMs: number;
+}): {
+    readonly verdict: 'pass' | 'fail' | 'inconclusive';
+    readonly reason: string;
+};

package/dist/services/final-review/final-review-fifth-dim.js

@@ -0,0 +1,20 @@
+// src/services/final-review/final-review-fifth-dim.ts
+//
+// The fifth (capability-consistency) dimension: a pure deterministic
+// verdict rule over the guard audit result. Hoisted verbatim from
+// final-review-service.ts (C wave 7 file-size split); the service module
+// re-exports it so the import path is unchanged.
+import { isStale } from '../capability-audit-service/staleness.js';
+export function decideFifthDimension(input) {
+    if (input.audit === null)
+        return { verdict: 'inconclusive', reason: 'AUDIT_GUARD_NOT_RUN' };
+    if (isStale(input.audit.auditedAt, input.nowMs))
+        return { verdict: 'inconclusive', reason: 'AUDIT_STALE' };
+    if (input.audit.crossCheck.guardVsAudit === 'diverge')
+        return { verdict: 'inconclusive', reason: 'AUDIT_CROSS_CHECK_DIVERGE' };
+    if (input.audit.verdict === 'consistent')
+        return { verdict: 'pass', reason: 'audit consistent' };
+    if (input.audit.verdict === 'drifted')
+        return { verdict: 'fail', reason: 'audit drifted' };
+    return { verdict: 'inconclusive', reason: 'audit inconclusive' };
+}

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

@@ -0,0 +1,119 @@
+import type { PrePostDiffResult } from './pre-post-diff.js';
+import { type CollectedEvidence } from './final-review-evidence-sources.js';
+import type { DimensionEvidence, DimensionKind } from './final-review-types.js';
+/**
+ * The honesty guarantee (D1), enforced after parsing rather than merely asked
+ * for in the prompt. Prompt instructions are advisory — a model can still
+ * answer `pass` — so this pass makes the property structural: a dimension with
+ * no supporting evidence on disk is rewritten to `inconclusive` / `low`
+ * regardless of what the model returned.
+ *
+ * A `fail` is never softened: it is already stricter than `inconclusive`.
+ */
+export declare function enforceEvidenceBackedVerdicts(dimensions: readonly DimensionEvidence[], evidenceAvailableFor: ReadonlySet<DimensionKind>): readonly DimensionEvidence[];
+/**
+ * The pre/post-diff half of the honesty rule: a `pass` on
+ * `existing-functionality-intact` may not outlive the baseline it claims.
+ *
+ * It fires whenever no baseline was DELIVERED to the reviewer, for EVERY reason:
+ * no base ref resolvable, a base that resolves to HEAD itself, a project that is
+ * not a git work tree at all, or a baseline that WAS computed but whose source
+ * block never reached the prompt (the budget omitted it). The first three are
+ * causes of a missing artifact; the last is a missing DELIVERY of an artifact
+ * that exists. None of the four is a licence to trust the claim: they are the
+ * CAUSE of the missing evidence, and a comparison the reviewer never saw is the
+ * absence of an answer, never an answer that came back clean.
+ *
+ * The earlier version exempted the non-git case, reasoning that "a non-git
+ * project would otherwise be permanently red". That reasoning was wrong in the
+ * one way this whole primitive exists to prevent: the permanently red verdict is
+ * the HONEST one (nothing was ever compared), while green-with-no-evidence is a
+ * forged clean handoff. Worse, it pierced the structural gate that
+ * `enforceEvidenceBackedVerdicts` exists to be — a `pass` whose supporting
+ * evidence is entirely absent is downgraded there, and it must not be let
+ * through by supplying a REASON for the absence.
+ *
+ * The version that followed it keyed on `prePostDiff.status === 'computed'` —
+ * "a baseline exists on disk" read as "the reviewer saw one". Those two facts
+ * separate the moment the budget omits the block, and the observed output was
+ * self-contradicting: the producer's own block said `STATUS: COMPUTED` one line
+ * above the source block's `STATUS: MISSING (omitted)`, the model was handed a
+ * `pass` it could not have justified, and the service attached the artifact to
+ * the dimension as evidence on top. `delivered` is that missing term.
+ *
+ * The gate also leaves its marker on the dimension whenever it fires, even if
+ * that dimension is already non-`pass`: with both gates firing, the earlier
+ * version's early return left only the OTHER gate's marker behind, so the
+ * envelope could not tell an operator that this gate had run at all.
+ */
+export declare function enforcePrePostDiffAvailability(dimensions: readonly DimensionEvidence[], prePostDiff: PrePostDiffResult, baselineDelivered: boolean): readonly DimensionEvidence[];
+/**
+ * F-NIT — `inconclusive` is the one verdict that cannot carry `high`
+ * confidence. "I am highly confident that I could not tell" is the schema's
+ * one self-contradicting combination, and it reads as a strong statement to the
+ * human this envelope is handed to. Both service gates that produce an
+ * `inconclusive` a reviewer did not write already write `low`; this closes the
+ * same hole for the ones the reviewer DID write, clamping to `medium` (the
+ * upper bound `references/4-dimensions.md` documents for this verdict) and
+ * leaving a marker so the clamp is auditable rather than silent.
+ *
+ * `fail` and `pass` are untouched: their confidence says something real.
+ */
+export declare function clampInconclusiveConfidence(dimensions: readonly DimensionEvidence[]): readonly DimensionEvidence[];
+/**
+ * The source whose absence from the delivered prompt is a DELIVERY failure for
+ * `functional-completeness`: the approved-scope contract.
+ *
+ * F-SAME-SHAPE — the hole the pre/post-diff gate closes for
+ * `existing-functionality-intact` was still open one dimension over. That
+ * dimension's rule is "a `pass` may not outlive the source it rests on", and
+ * `functional-completeness` is DEFINED against the approved scope and its
+ * non-goals — `prd/handoff.md` — but its `pass` only requires SOME source in its
+ * SUPPORTS list to be FOUND, and `qa-test-report` (the first source in the
+ * order, so the one the budget can never starve) also supports it. Measured on
+ * both saturated fixtures: `prd/handoff.md` was inlined with zero bytes on every
+ * run while the dimension still came back `pass`/`high` — the contract that
+ * says what "complete" meant was never shown to the reviewer judging
+ * completeness. Exactly the forged-clean-handoff shape, one dimension over.
+ *
+ * The delivery test for this source is the module's `whole` rule (`isDelivered`),
+ * not "some bytes arrived": the contract is prose whose point is the part a
+ * truncation would cut (scope then non-goals), so a partial slice is not a
+ * weaker version of the contract — it is a different document, and the reviewer
+ * would be judging "complete" against a scope list that stops mid-sentence.
+ *
+ * The gate deliberately does NOT fire when the contract is `missing` — ENOENT,
+ * i.e. the file is absent from the project, whether because the workflow has no
+ * PRD phase or because it never wrote one. A workflow with no PRD phase has no
+ * contract to lose, and reddening that dimension forever would be the "gate
+ * that is always red is noise" failure this primitive already names.
+ *
+ * F4 — what the gate fires on is the opposite fact: the contract IS there for
+ * this run and did not reach the reviewer. `totalBytes === 0` used to stand in
+ * for "not there", and it was wider than the comment above it: a 0-byte
+ * `prd/handoff.md` is `empty`, not `missing` — the file exists, the PRD phase
+ * ran, and the reviewer received no contract at all — yet the early return
+ * skipped the gate and let `functional-completeness` come back `pass`/`high`.
+ * The same line collapsed `unreadable` (EACCES / EBUSY: the contract exists and
+ * this process could not open it) into "no PRD phase". The test is now the
+ * STATUS the read phase produced, so "there is nothing to deliver" and "there
+ * is something to deliver and it did not arrive" cannot be the same branch.
+ */
+export declare function enforceScopeContractDelivery(dimensions: readonly DimensionEvidence[], collected: readonly CollectedEvidence[], delivered: (item: CollectedEvidence, dimension: DimensionKind) => boolean): readonly DimensionEvidence[];
+/**
+ * Attach the computed diff to the dimension as a first-class `pre-post-diff`
+ * `EvidenceItem`.
+ *
+ * The service does this rather than trusting the reviewer to cite the source:
+ * the dimension's contract NAMES this evidence kind and this artifact path, and
+ * a machine-produced fact that only appears when an LLM remembers to type it is
+ * not a guarantee. Appending cannot upgrade a verdict — the gate above has
+ * already run, and this only makes the artifact the verdict rests on auditable.
+ *
+ * It follows the same delivery rule as the gate — it asks the SAME function, on
+ * purpose: attaching the artifact to a dimension whose reviewer never received
+ * that block would re-create the very contradiction this layer exists to remove
+ * — an envelope claiming a `pre-post-diff` evidence item next to an
+ * `inconclusive` verdict that says the comparison was never seen.
+ */
+export declare function attachPrePostDiffEvidence(dimensions: readonly DimensionEvidence[], prePostDiff: PrePostDiffResult, baselineDelivered: boolean): readonly DimensionEvidence[];

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

@@ -0,0 +1,214 @@
+// src/services/final-review/final-review-gates.ts
+//
+// The service verdict gates. Hoisted verbatim from final-review-service.ts
+// (C wave 7 file-size split). The three gates that consult the delivery
+// judgement receive it as a parameter (`delivered` / `baselineDelivered`)
+// because the predicate itself stays in the service module — guard C
+// pins isDelivered's single home there — and the service injects it at
+// the call. Every gate body and its measured history comments are
+// HEAD-text; only the parameter names at the three consult sites differ.
+// The pre/post-diff gate is injected as the DELIVERED FACT (a boolean the
+// service measured on the collected evidence) rather than the evidence
+// array, because every fact it branches on is already in that boolean
+import { SCOPE_CONTRACT_SOURCE_KEY } from './final-review-evidence-sources.js';
+/**
+ * The honesty guarantee (D1), enforced after parsing rather than merely asked
+ * for in the prompt. Prompt instructions are advisory — a model can still
+ * answer `pass` — so this pass makes the property structural: a dimension with
+ * no supporting evidence on disk is rewritten to `inconclusive` / `low`
+ * regardless of what the model returned.
+ *
+ * A `fail` is never softened: it is already stricter than `inconclusive`.
+ */
+export function enforceEvidenceBackedVerdicts(dimensions, evidenceAvailableFor) {
+    return dimensions.map((dimension) => {
+        if (dimension.verdict !== 'pass')
+            return dimension;
+        if (evidenceAvailableFor.has(dimension.dimension))
+            return dimension;
+        const downgraded = {
+            ...dimension,
+            verdict: 'inconclusive',
+            confidence: 'low',
+            summary: `${dimension.summary} [evidence-gate: verdict downgraded from "pass" to "inconclusive" — no on-disk evidence source supporting "${dimension.dimension}" was available to the reviewer.]`
+        };
+        return downgraded;
+    });
+}
+/**
+ * The pre/post-diff half of the honesty rule: a `pass` on
+ * `existing-functionality-intact` may not outlive the baseline it claims.
+ *
+ * It fires whenever no baseline was DELIVERED to the reviewer, for EVERY reason:
+ * no base ref resolvable, a base that resolves to HEAD itself, a project that is
+ * not a git work tree at all, or a baseline that WAS computed but whose source
+ * block never reached the prompt (the budget omitted it). The first three are
+ * causes of a missing artifact; the last is a missing DELIVERY of an artifact
+ * that exists. None of the four is a licence to trust the claim: they are the
+ * CAUSE of the missing evidence, and a comparison the reviewer never saw is the
+ * absence of an answer, never an answer that came back clean.
+ *
+ * The earlier version exempted the non-git case, reasoning that "a non-git
+ * project would otherwise be permanently red". That reasoning was wrong in the
+ * one way this whole primitive exists to prevent: the permanently red verdict is
+ * the HONEST one (nothing was ever compared), while green-with-no-evidence is a
+ * forged clean handoff. Worse, it pierced the structural gate that
+ * `enforceEvidenceBackedVerdicts` exists to be — a `pass` whose supporting
+ * evidence is entirely absent is downgraded there, and it must not be let
+ * through by supplying a REASON for the absence.
+ *
+ * The version that followed it keyed on `prePostDiff.status === 'computed'` —
+ * "a baseline exists on disk" read as "the reviewer saw one". Those two facts
+ * separate the moment the budget omits the block, and the observed output was
+ * self-contradicting: the producer's own block said `STATUS: COMPUTED` one line
+ * above the source block's `STATUS: MISSING (omitted)`, the model was handed a
+ * `pass` it could not have justified, and the service attached the artifact to
+ * the dimension as evidence on top. `delivered` is that missing term.
+ *
+ * The gate also leaves its marker on the dimension whenever it fires, even if
+ * that dimension is already non-`pass`: with both gates firing, the earlier
+ * version's early return left only the OTHER gate's marker behind, so the
+ * envelope could not tell an operator that this gate had run at all.
+ */
+export function enforcePrePostDiffAvailability(dimensions, prePostDiff, baselineDelivered) {
+    if (prePostDiff.status === 'computed' && baselineDelivered)
+        return dimensions;
+    const why = prePostDiff.status !== 'computed'
+        ? prePostDiff.inGitWorkTree
+            ? 'this is a git work tree, but no pre/post baseline diff could be produced for this run'
+            : 'this project is not a git work tree, so no pre/post baseline diff can exist for it'
+        : 'a baseline WAS computed for this run, but its source block was not delivered into the reviewer prompt (the evidence budget omitted it), so the reviewer never saw the comparison it would have to rest on';
+    const reason = prePostDiff.status === 'computed'
+        ? 'the artifact exists on disk but did not reach the reviewer'
+        : prePostDiff.reason;
+    return dimensions.map((dimension) => {
+        if (dimension.dimension !== 'existing-functionality-intact')
+            return dimension;
+        const marker = `[pre-post-diff-gate: ${dimension.verdict === 'pass'
+            ? 'verdict downgraded from "pass" to "inconclusive"'
+            : `gate ran; verdict "${dimension.verdict}" is already non-"pass" and is left unchanged`} — ${why}. Reason: ${reason}]`;
+        const annotated = {
+            ...dimension,
+            summary: `${dimension.summary} ${marker}`
+        };
+        if (dimension.verdict !== 'pass')
+            return annotated;
+        return { ...annotated, verdict: 'inconclusive', confidence: 'low' };
+    });
+}
+/**
+ * F-NIT — `inconclusive` is the one verdict that cannot carry `high`
+ * confidence. "I am highly confident that I could not tell" is the schema's
+ * one self-contradicting combination, and it reads as a strong statement to the
+ * human this envelope is handed to. Both service gates that produce an
+ * `inconclusive` a reviewer did not write already write `low`; this closes the
+ * same hole for the ones the reviewer DID write, clamping to `medium` (the
+ * upper bound `references/4-dimensions.md` documents for this verdict) and
+ * leaving a marker so the clamp is auditable rather than silent.
+ *
+ * `fail` and `pass` are untouched: their confidence says something real.
+ */
+export function clampInconclusiveConfidence(dimensions) {
+    return dimensions.map((dimension) => {
+        if (dimension.verdict !== 'inconclusive' || dimension.confidence !== 'high')
+            return dimension;
+        return {
+            ...dimension,
+            confidence: 'medium',
+            summary: `${dimension.summary} [confidence-gate: confidence clamped from "high" to "medium" — an "inconclusive" verdict cannot be highly confident that it could not tell.]`
+        };
+    });
+}
+/**
+ * The source whose absence from the delivered prompt is a DELIVERY failure for
+ * `functional-completeness`: the approved-scope contract.
+ *
+ * F-SAME-SHAPE — the hole the pre/post-diff gate closes for
+ * `existing-functionality-intact` was still open one dimension over. That
+ * dimension's rule is "a `pass` may not outlive the source it rests on", and
+ * `functional-completeness` is DEFINED against the approved scope and its
+ * non-goals — `prd/handoff.md` — but its `pass` only requires SOME source in its
+ * SUPPORTS list to be FOUND, and `qa-test-report` (the first source in the
+ * order, so the one the budget can never starve) also supports it. Measured on
+ * both saturated fixtures: `prd/handoff.md` was inlined with zero bytes on every
+ * run while the dimension still came back `pass`/`high` — the contract that
+ * says what "complete" meant was never shown to the reviewer judging
+ * completeness. Exactly the forged-clean-handoff shape, one dimension over.
+ *
+ * The delivery test for this source is the module's `whole` rule (`isDelivered`),
+ * not "some bytes arrived": the contract is prose whose point is the part a
+ * truncation would cut (scope then non-goals), so a partial slice is not a
+ * weaker version of the contract — it is a different document, and the reviewer
+ * would be judging "complete" against a scope list that stops mid-sentence.
+ *
+ * The gate deliberately does NOT fire when the contract is `missing` — ENOENT,
+ * i.e. the file is absent from the project, whether because the workflow has no
+ * PRD phase or because it never wrote one. A workflow with no PRD phase has no
+ * contract to lose, and reddening that dimension forever would be the "gate
+ * that is always red is noise" failure this primitive already names.
+ *
+ * F4 — what the gate fires on is the opposite fact: the contract IS there for
+ * this run and did not reach the reviewer. `totalBytes === 0` used to stand in
+ * for "not there", and it was wider than the comment above it: a 0-byte
+ * `prd/handoff.md` is `empty`, not `missing` — the file exists, the PRD phase
+ * ran, and the reviewer received no contract at all — yet the early return
+ * skipped the gate and let `functional-completeness` come back `pass`/`high`.
+ * The same line collapsed `unreadable` (EACCES / EBUSY: the contract exists and
+ * this process could not open it) into "no PRD phase". The test is now the
+ * STATUS the read phase produced, so "there is nothing to deliver" and "there
+ * is something to deliver and it did not arrive" cannot be the same branch.
+ */
+export function enforceScopeContractDelivery(dimensions, collected, delivered) {
+    const block = collected.find((item) => item.source.key === SCOPE_CONTRACT_SOURCE_KEY);
+    if (block === undefined || block.status === 'missing')
+        return dimensions;
+    if (delivered(block, 'functional-completeness'))
+        return dimensions;
+    return dimensions.map((dimension) => {
+        if (dimension.dimension !== 'functional-completeness')
+            return dimension;
+        const marker = `[scope-contract-gate: ${dimension.verdict === 'pass'
+            ? 'verdict downgraded from "pass" to "inconclusive"'
+            : `gate ran; verdict "${dimension.verdict}" is already non-"pass" and is left unchanged`} — the approved-scope contract (${block.relativePath}) exists for this run, but it did not reach the reviewer in full (${block.includedBytes} of ${block.totalBytes} bytes, status "${block.status}"), so "functional-completeness" was judged without the scope and non-goals it is defined against. Reason: ${block.reason || 'inlined only in part'}]`;
+        const annotated = {
+            ...dimension,
+            summary: `${dimension.summary} ${marker}`
+        };
+        if (dimension.verdict !== 'pass')
+            return annotated;
+        return { ...annotated, verdict: 'inconclusive', confidence: 'low' };
+    });
+}
+/**
+ * Attach the computed diff to the dimension as a first-class `pre-post-diff`
+ * `EvidenceItem`.
+ *
+ * The service does this rather than trusting the reviewer to cite the source:
+ * the dimension's contract NAMES this evidence kind and this artifact path, and
+ * a machine-produced fact that only appears when an LLM remembers to type it is
+ * not a guarantee. Appending cannot upgrade a verdict — the gate above has
+ * already run, and this only makes the artifact the verdict rests on auditable.
+ *
+ * It follows the same delivery rule as the gate — it asks the SAME function, on
+ * purpose: attaching the artifact to a dimension whose reviewer never received
+ * that block would re-create the very contradiction this layer exists to remove
+ * — an envelope claiming a `pre-post-diff` evidence item next to an
+ * `inconclusive` verdict that says the comparison was never seen.
+ */
+export function attachPrePostDiffEvidence(dimensions, prePostDiff, baselineDelivered) {
+    if (prePostDiff.status !== 'computed' || !baselineDelivered)
+        return dimensions;
+    const item = {
+        kind: 'pre-post-diff',
+        description: prePostDiff.summary,
+        artifact: prePostDiff.relativePath
+    };
+    return dimensions.map((dimension) => {
+        if (dimension.dimension !== 'existing-functionality-intact')
+            return dimension;
+        const alreadyPresent = dimension.evidence.some((existing) => existing.kind === 'pre-post-diff' && existing.artifact === item.artifact);
+        if (alreadyPresent)
+            return dimension;
+        return { ...dimension, evidence: [...dimension.evidence, item] };
+    });
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Floor — also the value that shipped before this fix, so no evidence set can
+ * end up with a smaller budget than it had. ~3000 tokens is enough for the
+ * envelope skeleton plus a short paragraph per dimension.
+ */
+export declare const MIN_OUTPUT_TOKENS = 3000;
+/**
+ * Headroom for the part of the reply that is not the envelope.
+ *
+ * A Messages-API-compatible endpoint applies `max_tokens` to the WHOLE
+ * response, and a reasoning model spends it on hidden reasoning before it
+ * emits a single character of the 4-dim envelope. Measured on this repo's own
+ * machine (2026-09-12, rid `2026-09-12-codegraph-exclude-integrity`,
+ * `deepseek-flash[1M]` via `api.deepseek.com/anthropic`): `max_tokens=8192`
+ * came back with `output_tokens=8192` and only **574** visible characters —
+ * the entire budget went to reasoning. A bytes-per-token estimate of the
+ * visible output cannot see that cost, which is why the previous formula
+ * budgeted 7096 for a reply that needs 10108 — and why a 13240 budget still
+ * truncated on 2 of 10 real runs.
+ *
+ * 12288 (12 KiB) is sized so the largest evidence pack the input caps allow
+ * lands at 25528 (see the formula below; the input cap is 40 KiB as of the
+ * F-BLOCK re-evaluation, and this floor was checked against the raised cap, not
+ * against the 32 KiB the measurements above were taken at — a 12 KiB headroom
+ * under a bigger cap is the conservative direction) — about 1.9x the largest
+ * value ever OBSERVED to truncate (13240), which is the margin the observed
+ * variance asks for. The numbers are in the block comment above.
+ */
+export declare const REASONING_HEADROOM_TOKENS = 12288;
+/**
+ * Ceiling, 32_000: the value a real run on this machine was forced to in order
+ * to complete the envelope at all, and the largest this endpoint was observed
+ * to accept. 16384 was tried first and truncated 2/10 — a ceiling that is
+ * merely "above the last successful measurement" is not above the requirement,
+ * because the requirement moves with the model's reasoning spend.
+ *
+ * A model that caps output at 8192 will refuse this. That is still strictly
+ * better than shipping a budget measured to be too small, and the env lever
+ * below lets an operator pull it down without a code change.
+ */
+export declare const MAX_OUTPUT_TOKENS = 32000;
+/**
+ * Environment lever. The old failure message told the operator to "raise the
+ * budget" while the budget was a module constant with no CLI flag and no env
+ * var — an instruction that could not be carried out from any surface the
+ * operator has. This is that lever.
+ *
+ * The value is the output ceiling in tokens; it OVERRIDES the derivation below
+ * (it is not a bonus added to it). Unset/invalid/out-of-range handling is in
+ * `resolveOutputBudget`.
+ */
+export declare const MAX_OUTPUT_TOKENS_ENV = "PEAKS_FINAL_REVIEW_MAX_OUTPUT_TOKENS";
+/**
+ * Absolute upper bound the env lever may reach. An endpoint that accepts
+ * `max_tokens` at all accepts this; anything above it is a typo (a stray extra
+ * digit), not an intent, and clamping is safer than sending it.
+ */
+export declare const HARD_MAX_OUTPUT_TOKENS = 64000;
+/**
+ * Inlined bytes that buy one extra output token — 4:1.
+ *
+ * This term prices the visible envelope (4 x `summary` + `evidence[]` +
+ * `confidence` + `overallSummary`) against the evidence the model is required
+ * to cite. It was 8:1, which put the 32 KiB pack at 4096 tokens of visible
+ * output; the same pack has been observed to complete at 10108 and to truncate
+ * at 13240, so 8:1 was pricing the visible side BELOW its own measurement.
+ * 4:1 doubles it to 8192. It is still not treated as the whole budget — see
+ * `REASONING_HEADROOM_TOKENS`.
+ */
+export declare const EVIDENCE_BYTES_PER_OUTPUT_TOKEN = 4;
+/**
+ * Output ceiling for a call whose prompt carries `includedEvidenceBytes` bytes
+ * of inlined evidence. Pure, total, and clamped on both ends — the same
+ * evidence pack always yields the same budget.
+ */
+export declare function outputBudgetForEvidence(includedEvidenceBytes: number): number;
+/**
+ * The budget the call actually uses: the derived one, unless
+ * `PEAKS_FINAL_REVIEW_MAX_OUTPUT_TOKENS` overrides it.
+ *
+ * An override that is not a positive integer THROWS rather than being ignored:
+ * a silent fallback would leave an operator who passed a bad value with the
+ * exact experience this lever exists to remove — a budget they cannot move.
+ * Out-of-range values are clamped, not rejected, so a model needing more than
+ * `HARD_MAX_OUTPUT_TOKENS` (or a model needing less than `MIN_OUTPUT_TOKENS`)
+ * still gets a call made.
+ */
+export declare function resolveOutputBudget(includedEvidenceBytes: number, env?: NodeJS.ProcessEnv): number;