peaks-loop 4.0.42 → 4.0.44

package/dist/services/doctor/doctor-service/checks/codegraph-exclude-integrity.js

@@ -0,0 +1,88 @@
+/**
+ * Check: codegraph exclude integrity (`capability:codegraph-exclude-integrity`).
+ *
+ * The companion to `capability:codegraph`. That check answers "is the
+ * upstream package resolvable at the pinned version"; this one answers
+ * "does the project's `.codegraph/config.json` exclude rules silently
+ * drop source files git tracks".
+ *
+ * Why it exists: upstream ships a default `exclude` template matched by
+ * *directory name*, and `config.json`'s `exclude` array replaces those
+ * defaults wholesale. Any default rule whose directory name collides
+ * with a real source directory drops tracked files from the index while
+ * `peaks codegraph status` still printed `[OK] Index is up to date`.
+ *
+ * Read-only by construction — it consumes the same inspector
+ * `peaks codegraph status` gates on and never writes the config.
+ *
+ * Failure posture:
+ *   - codegraph not initialized in the inspected root (no
+ *     `.codegraph/config.json`) → `ok: true`; there is nothing to
+ *     reconcile and a fresh clone must not fail the doctor.
+ *   - a confirmed gap → `ok: false` (blocking; the index is provably
+ *     incomplete and the fix is one command).
+ *   - could not evaluate (not a git work tree, malformed config) →
+ *     `ok: false, severity: 'warning'` so the doctor reports the blind
+ *     spot without flipping the exit code on an unrelated failure.
+ */
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent } from '../../../codegraph/codegraph-exclude-integrity.js';
+const CHECK_ID = 'capability:codegraph-exclude-integrity';
+/** How many rules / offending files the message names before eliding. */
+const MAX_NAMED = 5;
+function defaultProbe() {
+    const projectRoot = process.cwd();
+    // No config → codegraph was never initialized here, so no exclude
+    // list is in play and there is nothing to report.
+    return isCodegraphExcludeConfigPresent(projectRoot)
+        ? inspectCodegraphExcludeIntegrity(projectRoot)
+        : null;
+}
+function renderGapMessage(excludedTrackedCount, trackedSourceCount, rulesToRemove, violations) {
+    const namedRules = rulesToRemove.slice(0, MAX_NAMED).join(', ');
+    const elidedRules = rulesToRemove.length > MAX_NAMED ? `, … (+${rulesToRemove.length - MAX_NAMED})` : '';
+    const namedFiles = violations
+        .slice(0, MAX_NAMED)
+        .map((violation) => `${violation.path} <- ${violation.matchedRule}`)
+        .join('; ');
+    const elidedFiles = violations.length > MAX_NAMED ? `; … (+${violations.length - MAX_NAMED})` : '';
+    return `codegraph index is incomplete: ${excludedTrackedCount} of ${trackedSourceCount} tracked source files are blocked by ${rulesToRemove.length} exclude rule(s) [${namedRules}${elidedRules}]. Blocked: ${namedFiles}${elidedFiles}. Run \`peaks codegraph repair-exclude --project <root>\` to drop them and rebuild the index.`;
+}
+function run({ options }) {
+    const probe = options.codegraphIntegrityProbe ?? defaultProbe;
+    let report;
+    try {
+        report = probe();
+    }
+    catch (error) {
+        return [{
+                id: CHECK_ID,
+                ok: false,
+                severity: 'warning',
+                message: `codegraph exclude integrity could not be evaluated: ${getErrorMessage(error)}`
+            }];
+    }
+    if (report === null) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: 'codegraph is not initialized in this project (no .codegraph/config.json); the exclude list is not in play yet'
+            }];
+    }
+    if (!report.gap) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: `codegraph exclude list drops no tracked source file (${report.trackedSourceCount} tracked source file(s) admitted by include)`
+            }];
+    }
+    return [{
+            id: CHECK_ID,
+            ok: false,
+            message: renderGapMessage(report.excludedTrackedCount, report.trackedSourceCount, report.rulesToRemove, report.violations)
+        }];
+}
+export const check = {
+    name: 'codegraph-exclude-integrity',
+    run
+};

package/dist/services/doctor/doctor-service/checks/ecc-hooks-schema-drift.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Check: the third-party ECC plugin ships `hooks/hooks.json` keys that
+ * Claude Code's plugin hook schema ignores
+ * (`integration:ecc-hooks-schema-drift`).
+ *
+ * 2026-09-12 — Claude Code prints this at startup when the ECC plugin
+ * (github.com/affaan-m/ECC) is installed:
+ *
+ *   ecc: hooks.json: unknown keys "$schema", "description" in
+ *   hooks.PreToolUse[0], "id" in hooks.PreToolUse[0], ... and 42 more ignored
+ *
+ * Claude Code's plugin hook schema accepts exactly `{ matcher, hooks }`
+ * on a matcher group, and at the document root `hooks` plus an OPTIONAL
+ * top-level `description`. ECC ships a
+ * root `$schema` plus `description` AND `id` on each of its 23 matcher
+ * groups across 7 events — 47 ignored keys, matching the warning
+ * verbatim. The warning is cosmetic (the 23 hooks still load).
+ *
+ * peaks-loop does NOT write this file, and every ECC release checked
+ * (v2.2.0 / v2.2.1 / main) carries the same keys, so upgrading the
+ * plugin does not clear the warning. This check exists so a user who
+ * hits the startup line does not have to re-investigate it from
+ * scratch.
+ *
+ * Probing is split out of the check so the check itself stays a pure
+ * mapping over `EccHooksDriftProbeResult`. Tests inject the probe to
+ * keep the real `~/.claude/plugins/` tree out of fixtures.
+ */
+import type { DoctorCheckPlugin, EccHooksDriftProbeResult } from '../types.js';
+/**
+ * Unknown keys found in a plugin `hooks.json`. Mirrors the shape of
+ * Claude Code's own startup warning so the doctor message can name the
+ * same things.
+ */
+export type EccHooksDriftFinding = {
+    /** Total ignored keys (`rootKeys` + every unknown key on every matcher group). */
+    readonly unknownKeyCount: number;
+    /** Unknown keys directly under the document root (e.g. `$schema`). */
+    readonly rootKeys: ReadonlyArray<string>;
+    /** Distinct unknown keys seen on matcher groups (e.g. `description`, `id`). */
+    readonly entryKeys: ReadonlyArray<string>;
+    /** Matcher groups carrying at least one unknown key. */
+    readonly entryCount: number;
+};
+/**
+ * Pure mapping over a parsed plugin `hooks.json` payload. Exported so
+ * tests drive the key scan without touching the real plugin tree.
+ */
+export declare function findEccHooksSchemaDrift(payload: unknown): EccHooksDriftFinding;
+/**
+ * Resolve the ECC plugin's install path from Claude Code's plugin
+ * manifest (`~/.claude/plugins/installed_plugins.json`), which is the
+ * only version-agnostic way to find the versioned cache directory
+ * (`…/plugins/cache/ecc/ecc/<version>/`). Exported so tests drive the
+ * lookup with an explicit manifest path.
+ */
+export declare function readEccInstallPath(manifestPath: string): string | null;
+/**
+ * Default probe: reads the ECC plugin manifest + its `hooks/hooks.json`.
+ * `homeDir` is injectable so tests can drive the real probe against a
+ * temp dir; the zero-arg call keeps using the real homedir, so the
+ * function stays assignable to `EccHooksDriftProbe`.
+ */
+export declare function defaultEccHooksDriftProbe(homeDir?: string): EccHooksDriftProbeResult;
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/ecc-hooks-schema-drift.js

@@ -0,0 +1,186 @@
+/**
+ * Check: the third-party ECC plugin ships `hooks/hooks.json` keys that
+ * Claude Code's plugin hook schema ignores
+ * (`integration:ecc-hooks-schema-drift`).
+ *
+ * 2026-09-12 — Claude Code prints this at startup when the ECC plugin
+ * (github.com/affaan-m/ECC) is installed:
+ *
+ *   ecc: hooks.json: unknown keys "$schema", "description" in
+ *   hooks.PreToolUse[0], "id" in hooks.PreToolUse[0], ... and 42 more ignored
+ *
+ * Claude Code's plugin hook schema accepts exactly `{ matcher, hooks }`
+ * on a matcher group, and at the document root `hooks` plus an OPTIONAL
+ * top-level `description`. ECC ships a
+ * root `$schema` plus `description` AND `id` on each of its 23 matcher
+ * groups across 7 events — 47 ignored keys, matching the warning
+ * verbatim. The warning is cosmetic (the 23 hooks still load).
+ *
+ * peaks-loop does NOT write this file, and every ECC release checked
+ * (v2.2.0 / v2.2.1 / main) carries the same keys, so upgrading the
+ * plugin does not clear the warning. This check exists so a user who
+ * hits the startup line does not have to re-investigate it from
+ * scratch.
+ *
+ * Probing is split out of the check so the check itself stays a pure
+ * mapping over `EccHooksDriftProbeResult`. Tests inject the probe to
+ * keep the real `~/.claude/plugins/` tree out of fixtures.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+const CHECK_ID = 'integration:ecc-hooks-schema-drift';
+/** Claude Code's plugin hook schema accepts exactly these keys on a matcher group. */
+const ALLOWED_MATCHER_GROUP_KEYS = ['matcher', 'hooks'];
+/**
+ * …and at the document root: `hooks`, plus an OPTIONAL top-level
+ * `description` (Claude Code's plugin hooks docs, "Reference scripts by
+ * path", document a top-level `description` for `hooks/hooks.json` and
+ * place it as a sibling of `hooks`). A top-level `description` is
+ * therefore legal — and is exactly the shape an upstream ECC fix would
+ * land on when it consolidates its 23 per-matcher descriptions into one.
+ */
+const ALLOWED_ROOT_KEYS = ['hooks', 'description'];
+const NO_DRIFT = {
+    unknownKeyCount: 0,
+    rootKeys: [],
+    entryKeys: [],
+    entryCount: 0
+};
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Pure mapping over a parsed plugin `hooks.json` payload. Exported so
+ * tests drive the key scan without touching the real plugin tree.
+ */
+export function findEccHooksSchemaDrift(payload) {
+    if (!isPlainObject(payload))
+        return NO_DRIFT;
+    const rootKeys = Object.keys(payload).filter((key) => !ALLOWED_ROOT_KEYS.includes(key));
+    const hooks = payload.hooks;
+    if (!isPlainObject(hooks)) {
+        return { ...NO_DRIFT, unknownKeyCount: rootKeys.length, rootKeys };
+    }
+    const entryKeys = new Set();
+    let entryKeyTotal = 0;
+    let entryCount = 0;
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isPlainObject(group))
+                continue;
+            const unknown = Object.keys(group).filter((key) => !ALLOWED_MATCHER_GROUP_KEYS.includes(key));
+            if (unknown.length === 0)
+                continue;
+            entryCount += 1;
+            entryKeyTotal += unknown.length;
+            for (const key of unknown)
+                entryKeys.add(key);
+        }
+    }
+    return {
+        unknownKeyCount: rootKeys.length + entryKeyTotal,
+        rootKeys,
+        entryKeys: [...entryKeys].sort(),
+        entryCount
+    };
+}
+function readJsonIfPresent(path) {
+    if (!existsSync(path))
+        return null;
+    // Parse errors intentionally propagate to the check's own catch, which
+    // reports them as a `skipping check` message instead of swallowing them.
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/**
+ * Resolve the ECC plugin's install path from Claude Code's plugin
+ * manifest (`~/.claude/plugins/installed_plugins.json`), which is the
+ * only version-agnostic way to find the versioned cache directory
+ * (`…/plugins/cache/ecc/ecc/<version>/`). Exported so tests drive the
+ * lookup with an explicit manifest path.
+ */
+export function readEccInstallPath(manifestPath) {
+    const manifest = readJsonIfPresent(manifestPath);
+    if (!isPlainObject(manifest))
+        return null;
+    const plugins = manifest.plugins;
+    if (!isPlainObject(plugins))
+        return null;
+    for (const [name, records] of Object.entries(plugins)) {
+        if (!name.startsWith('ecc@'))
+            continue;
+        if (!Array.isArray(records))
+            continue;
+        for (const record of records) {
+            if (!isPlainObject(record))
+                continue;
+            const installPath = record.installPath;
+            if (typeof installPath === 'string' && installPath.length > 0)
+                return installPath;
+        }
+    }
+    return null;
+}
+/**
+ * Default probe: reads the ECC plugin manifest + its `hooks/hooks.json`.
+ * `homeDir` is injectable so tests can drive the real probe against a
+ * temp dir; the zero-arg call keeps using the real homedir, so the
+ * function stays assignable to `EccHooksDriftProbe`.
+ */
+export function defaultEccHooksDriftProbe(homeDir = homedir()) {
+    const manifestPath = join(homeDir, '.claude', 'plugins', 'installed_plugins.json');
+    const installPath = readEccInstallPath(manifestPath);
+    if (installPath === null)
+        return { hooksPath: null, hooks: null };
+    const hooksPath = join(installPath, 'hooks', 'hooks.json');
+    return { hooksPath, hooks: readJsonIfPresent(hooksPath) };
+}
+function run({ options }) {
+    const probe = options.eccHooksDriftProbe ?? defaultEccHooksDriftProbe;
+    try {
+        const { hooksPath, hooks } = probe();
+        if (hooksPath === null) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: 'ECC plugin not installed (no `ecc@*` entry in ~/.claude/plugins/installed_plugins.json); no plugin hook schema drift to report'
+                }];
+        }
+        if (hooks === null) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: `No readable ECC plugin hooks.json at ${hooksPath}; no plugin hook schema drift to report`
+                }];
+        }
+        const finding = findEccHooksSchemaDrift(hooks);
+        if (finding.unknownKeyCount === 0) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: `ECC plugin hooks.json at ${hooksPath} carries only the keys Claude Code accepts (matcher/hooks per matcher group); the startup "unknown keys ... ignored" warning will not appear`
+                }];
+        }
+        const rootPart = finding.rootKeys.length === 0 ? '' : `at the root: ${finding.rootKeys.join(', ')}; `;
+        return [{
+                id: CHECK_ID,
+                ok: false,
+                severity: 'warning',
+                message: `ECC plugin hooks.json at ${hooksPath} carries ${finding.unknownKeyCount} key(s) that Claude Code's plugin hook schema ignores (${rootPart}on ${finding.entryCount} matcher group(s): ${finding.entryKeys.join(', ')}). Claude Code prints \`ecc: hooks.json: unknown keys ... ignored\` at startup; every hook still loads, so this warning is cosmetic. Source: the third-party ECC plugin (github.com/affaan-m/ECC) ships these keys in every release (v2.2.0 / v2.2.1 / main) — peaks-loop does NOT write this file. Fix: none inside peaks-loop; upstream ECC must drop them from its hooks/hooks.json (its scripts/ci/validate-hooks.js validates shape only, never a key allow-list, so ECC's own CI stays green). Upgrading ECC will not help.`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: `ECC hooks schema-drift probe failed (${getErrorMessage(error)}); skipping check`
+            }];
+    }
+}
+export const check = {
+    name: 'ecc-hooks-schema-drift',
+    run
+};

package/dist/services/doctor/doctor-service/plugin-registry.js

@@ -42,10 +42,12 @@ import { check as workspaceInit } from './checks/workspace-init.js';
 import { check as statuslineInstall } from './checks/statusline-install.js';
 import { check as statuslineRuntime } from './checks/statusline-runtime.js';
 import { check as codegraphCapability } from './checks/codegraph-capability.js';
+import { check as codegraphExcludeIntegrity } from './checks/codegraph-exclude-integrity.js';
 import { check as distSourceVersion } from './checks/dist-source-version.js';
 import { check as multiBinaryDrift } from './checks/multi-binary-drift.js';
 import { check as workspaceLayout } from './checks/workspace-layout.js';
 import { check as gateguardConflict } from './checks/gateguard-conflict.js';
+import { check as eccHooksSchemaDrift } from './checks/ecc-hooks-schema-drift.js';
 import { check as checkIdSchema } from './checks/check-id-schema.js';
 import { check as l3OrphanSessions } from './checks/l3-orphan-sessions.js';
 import { check as l3MemoryHealth } from './checks/l3-memory-health.js';
@@ -69,10 +71,12 @@ export const PLUGINS = [
     statuslineInstall, // id "statusline:install"
     statuslineRuntime, // id "statusline:runtime"
     codegraphCapability, // id "capability:codegraph"
+    codegraphExcludeIntegrity, // id "capability:codegraph-exclude-integrity"
     distSourceVersion, // id "build:dist-version-matches-source"
     multiBinaryDrift, // id "build:multi-binary-drift"
     workspaceLayout, // id "build:workspace-layout-canonical"
     gateguardConflict, // id "integration:gateguard-peaks-conflict"
+    eccHooksSchemaDrift, // id "integration:ecc-hooks-schema-drift"
     checkIdSchema, // id "doctor-self:check-id-pattern"
     l3OrphanSessions, // id "L3:l3-orphan-sessions"
     l3MemoryHealth, // id "L3:l3-memory-health"

package/dist/services/doctor/doctor-service/types.d.ts

@@ -75,6 +75,25 @@ export type CodegraphCapabilityProbe = {
      */
     managedPath: CodegraphManagedPathInfo | null;
 };
+/**
+ * Structural shape of the codegraph exclude-integrity report the
+ * `capability:codegraph-exclude-integrity` check gates on. Declared
+ * structurally (rather than imported from the codegraph service) to
+ * keep this type module dependency-free — the default probe returns a
+ * `CodegraphExcludeIntegrityReport`, which is assignable here.
+ */
+export type CodegraphExcludeIntegrityProbe = {
+    readonly configPath: string;
+    readonly gap: boolean;
+    readonly trackedSourceCount: number;
+    readonly excludedTrackedCount: number;
+    readonly rulesToRemove: readonly string[];
+    /** One entry per (file, rule) pair. */
+    readonly violations: readonly {
+        readonly path: string;
+        readonly matchedRule: string;
+    }[];
+};
 export type DistVersionComparison = {
     dist: string | null;
     source: string;
@@ -165,6 +184,24 @@ export type GateguardProbeResult = {
     projectSettings: unknown;
 };
 export type GateguardProbe = () => GateguardProbeResult;
+/**
+ * 2026-09-12 — the third-party ECC plugin (github.com/affaan-m/ECC)
+ * ships `$schema` at the root of its `hooks/hooks.json` plus
+ * `description` + `id` on every matcher group. Claude Code's plugin
+ * hook schema accepts only `{ matcher, hooks }` per matcher group, and
+ * at the root `hooks` plus an OPTIONAL top-level `description`, so it
+ * prints an `unknown keys ... ignored`
+ * line at startup for the 47 extra keys (cosmetic — the hooks still
+ * load). The probe is injected so tests never read the real
+ * `~/.claude/plugins/` tree.
+ */
+export type EccHooksDriftProbeResult = {
+    /** Absolute path to the ECC plugin's `hooks/hooks.json` (null when the plugin is not installed). */
+    hooksPath: string | null;
+    /** Parsed `hooks/hooks.json` payload (null when missing / unreadable). */
+    hooks: unknown;
+};
+export type EccHooksDriftProbe = () => EccHooksDriftProbeResult;
 /**
  * Subset of SkillPresence consumed by the doctor (slice-3b: the full
  * `SkillPresence` type lives in `src/services/skills/skill-presence-service.ts`;
@@ -211,6 +248,14 @@ export type DoctorOptions = {
      * `process.cwd()`.
      */
     codegraphManagedPathProbe?: () => CodegraphManagedPathInfo | null;
+    /**
+     * Optional override for the `capability:codegraph-exclude-integrity`
+     * check. Returns the integrity report, or `null` when codegraph is
+     * not initialized in the inspected root (nothing to reconcile). When
+     * omitted, the check inspects `process.cwd()`. Throwing is allowed
+     * and reported as a non-blocking warning.
+     */
+    codegraphIntegrityProbe?: () => CodegraphExcludeIntegrityProbe | null;
     skillPresenceProbe?: () => DoctorSkillPresence | null;
     skillPresenceFreshnessThresholdMs?: number;
     statusLineInstalledProbe?: () => boolean;
@@ -230,6 +275,8 @@ export type DoctorOptions = {
     workspaceLayoutProbe?: WorkspaceLayoutProbe;
     /** Injected for the integration:gateguard-peaks-conflict check (defaults to defaultGateguardProbe on disk). */
     gateguardProbe?: GateguardProbe;
+    /** Injected for the integration:ecc-hooks-schema-drift check (defaults to defaultEccHooksDriftProbe on disk). */
+    eccHooksDriftProbe?: EccHooksDriftProbe;
     /**
      * Slice 2026-06-13-repair-pre-existing-test-failures: injected
      * root for the L3:l3-memory-health check (defaults to

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

@@ -20,6 +20,160 @@ export declare class IncompleteFinalReviewError extends Error {
     readonly code: "INCOMPLETE_FINAL_REVIEW";
     constructor(message: string);
 }
+/**
+ * N4 — the reply carried no text block at all.
+ *
+ * Measured 2/3 on this repo's own machine, and it is NOT truncation: the
+ * provider answered with a response whose `content` has no `text` block (a
+ * reasoning-only turn, a refusal, or a content filter), so there is no JSON to
+ * parse and no budget to raise — an operator sent to "raise the budget" for
+ * this failure would be sent the wrong way. It gets its own class, its own
+ * `code`, and a message that says so, so it is diagnosable instead of being
+ * flattened into "not valid JSON".
+ */
+export declare class EmptyReviewReplyError extends Error {
+    readonly code: "EMPTY_FINAL_REVIEW_REPLY";
+    constructor(message: string);
+}
+/**
+ * How many times an empty reply is retried before it is reported. The failure
+ * was 2/3 on the observed machine — intermittent, not systematic — so a small
+ * bounded retry converts most of it into a completed review, while 3 attempts
+ * keeps a genuinely broken provider from being hammered.
+ */
+export declare const MAX_EMPTY_REPLY_ATTEMPTS = 3;
+/**
+ * Per-file evidence cap. Real evidence artifacts in this repo run 11–18 KB
+ * (`rd/tech-doc.md`, `rd/code-review.md`, `qa/*-findings-*.md`); 8 KB keeps the
+ * head of every file (header + verdict + first tables) without letting one
+ * verbose artifact crowd out the other sources. Enforced in BYTES against the
+ * raw buffer, so multi-byte (CJK) content cannot slip past the cap.
+ */
+export declare const MAX_EVIDENCE_BYTES_PER_FILE: number;
+/**
+ * Total evidence budget across all sources. 32 KB ≈ 8k 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. 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.
+ */
+export declare const MAX_EVIDENCE_BYTES_TOTAL: number;
+/**
+ * Reserved floor per dimension — the anti-starvation guarantee.
+ *
+ * The allocator below used to be strictly first-come-first-served: each source
+ * took `min(perFileCap, budgetLeft)` in source order. With this repo's own
+ * 9-source evidence set (`2026-09-12-session-e37ef0`, measured) sources 1-4
+ * consumed the whole 32 KiB — 4 x 8,192 = 32,768, the cap to the byte — before
+ * source 5 was even opened. `existing-functionality-intact` is supplied ONLY by
+ * `rd/tech-doc.md` (6th) and `prd/handoff.md` (9th), so that one dimension
+ * reached the reviewer with zero evidence on every run and its verdict was
+ * structurally locked to `inconclusive` no matter how good the work was. A gate
+ * that is always red is noise, and an operator trained to ignore noise has no
+ * gate at all — the same harm as a gate that never fires, only quieter.
+ *
+ * So each dimension with at least one readable source on disk gets one floor
+ * reserved for the FIRST such source, and no source that is not that holder may
+ * spend it. The reservation is a floor, never a quota: it is released the
+ * instant its holder is served, and whatever the holder does not use flows back
+ * into the sequential allocation unchanged.
+ *
+ * Why 4 KiB: the per-file cap exists to keep the "header + verdict + first
+ * tables" — the part a reviewer actually cites. Measured on the same run's
+ * artifacts (9 files, 8,164-20,543 bytes each): every one of them states its
+ * verdict inside the first ~700 bytes. 4 KiB is ~5x that, so a floor holder is
+ * not there for depth — it is there so its dimension is not blind. Four
+ * dimensions x 4 KiB = 16 KiB of the 32 KiB cap, so at least half the budget
+ * still flows through the sequential path below.
+ */
+export declare const MIN_EVIDENCE_BYTES_PER_DIMENSION: number;
+/**
+ * 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 23480 (see the formula below) — about 1.8x 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: number;
+/**
+ * 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;
 export declare function prepareFinalReview(rid: string, opts: PrepareFinalReviewOptions): Promise<FinalReviewOutput>;
 export declare function decideFifthDimension(input: {
     readonly audit: CapabilityAuditResult | null;