peaks-loop 4.0.43 → 4.0.45

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 4.0.45 — 2026-09-12 (一个永远无法通过的维度 + 一个验代理的守卫)
+
+**Highlights**:
+
+1. **4 维验收闸里有一维从构造上就不可能通过。** `existing-functionality-intact` 的契约要求一份 `pre-post-diff`（前后结构对比：测试面 / 公开 API 面），而**全仓没有任何东西生产它**。于是它被喂的是 `rd/tech-doc.md`（设计意图）与 `prd/handoff.md`（批准范围）—— 而这个模块自己的文件头注释，把"拿设计意图文档当回归评估"列为它存在的理由。结果：`allPass === true` 对**任何**工作流都不可达。
+
+   本版补上生产者（`pre-post-diff.ts`）：以 base ref 对比工作树，报**测试面**（文件数 / 用例数）、**源文件清单**、**公开 API 面**（顶层 `export` 语句数与名字集合），写入 `.peaks/_runtime/<sessionId>/final-review/api-diff.txt`。**诚实边界写在产物里**：export 检测是行锚定的近似，能发现"少了一个导出"这类结构丢失，**发现不了签名变更**。算不出 baseline 时**不产出 artifact、不编造 diff** —— 该维保持 `inconclusive`。
+
+2. **消费它的那个闸，键在"送达"，不在"产物存在"。** 独立复核连做七轮，每轮都在下一层找到同一个形状 —— 一个接受**代理**的闸（"评审者看到了吗"被替换成"磁盘上有吗"）：
+
+   | 轮 | 被判为"检查过了"的东西 |
+   |---|---|
+   | 1 | `status === 'computed'`（磁盘上有文件） |
+   | 2 | `status === 'found'`（≥1 字节送达） |
+   | 3 | `totalBytes === 0`（把 missing 与 empty 混为一谈） |
+
+   共同根因是：一个源**可以被部分内联**，于是"送达了吗"永远有一个律师式答案。现在分配器是 **per-source 全有或全无**（要么整份、要么 omitted，不存在截在中间），且 `isDelivered` 是这个问题**唯一的家** —— 每个源声明自己的送达规则：`whole`（整份文档；被截断过的文档是另一份文档）或 `conclusion`（一个**就是结论本身**的字面量）。
+
+3. **随之而来的两处实质变化，都要求诚实。**
+   - 证据预算改为**推导**（`10,240 = 总额 / 4`）而不是常量 —— 因为走 `whole` 规则的源一旦超过它，就**永远送不到**。
+   - 一个维度若其全部支撑源都装不下，现在会被**响亮报出**（prompt 里出 `## Evidence delivery reachability` 段、维度 summary 挂 `[delivery-reachability: …]` 标记、并进 `needsAttention`），而不是**静默地永远红**。**故意不抛错** —— 抛错会连带毁掉那三个本来可送达的维度。
+
+4. **反回归守卫本身，就是同一个形状的第 7 个实例 —— 且它一开始是坏的。** 初版守卫按**语法形状**切分源码（只认行首 `function name`），于是**箭头函数、生成器、`export default function`、类方法**一律不被扫描：**8 种等价写法全部放行**，端到端实测"顶层箭头里放 2 个代理字面量"仍 `3 passed EXIT=0`。**一个能放行 8/8 的守卫比没有守卫更糟** —— 它把"没人在看"变成"有东西在看"。
+
+   现在它用仓库自带的 `typescript` 解析 AST、读**函数体内**的 token，于是那 4 种形状绕过全部关闭（实测：往真实源码注入箭头式代理 → 守卫转红）。剩下 4 种**不含该字面量**的改写（拆变量 `const F='found'`、`==`、`item['status']`、字符串拼接）**仍然放行** —— 这一点被**固定成一条通过的测试**，让守卫**陈述自己的边界**而不是暗示一个。
+
+5. **`peaks codegraph status` 在真有缺口时会同时印出两行互相矛盾的话。** 退出码（74）与 `[FAIL]` 细节都是对的，但人第一眼看到的是：
+
+   ```
+   [OK] Index is up to date
+   [FAIL] codegraph index is incomplete: 2 of 1133 tracked source files are excluded …
+   ```
+
+   两个闸在回答不同的问题：上游答"图与上次扫描一致"（确实一致），peaks 答"图覆盖了仓库吗"（没有）。**都对，并排印出来就是矛盾。** 现在上游那行被**归因而非抑制**（措辞与统计保留，只是把它的适用范围说明白），只在这一行、且只在缺口门**确实触发**时改动；无缺口路径逐字节不变（含 ANSI），机器可读 envelope 未动。
+
+**验证**:三个版本常量一致(**4.0.45**);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **214 files / 2165 passed / 3 skipped / 0 failed**;`pnpm build` 的 `build-integrity` OK。
+
+**已知未修 / 边界**:`conclusion` 规则下超大的源不算"不可送达"（结论标记可能在截断点之后）;单一可送达源的**穿越前余量**（本 session 实测 748 B）**没有**告警，只报"已经不可能"的状态;4 维中的 `existing-functionality-intact` 在**非 git 项目**里永久 `inconclusive`（这是诚实结果，已写进 SKILL.md 与 `4-dimensions.md`）。
+
+**备注**:本版的 `prepare-final-review` 闸**未经过独立复核**（前六轮每一轮都经过并各找到 1 个 HIGH;第 7 轮由 orchestrator 自行验证,含箭头注入实测),这一点如实记录以便日后回溯。
+
+## 4.0.44 — 2026-09-12 (被静默排除的源文件 + 一个验错东西的验收闸)
+
+**Highlights**:
+
+1. **`peaks codegraph status` 报"索引是最新的",而 26 个 git 跟踪的源文件根本不在索引里。** 上游默认 exclude 表**按目录名**匹配,而本仓库恰好把 `artifacts/` `release/` `vendor/` `bin/` `publish/` 用作了源码目录名,于是 5 条默认规则把 26 个真实源文件挡在门外。`status` 说的是"图与上次扫描一致",不是"图覆盖了仓库" —— 所以这个洞是隐形的。
+
+   本版按**一条原则**建了 reconcile / repair / verify:被 git 跟踪的源文件不得被 exclude 规则挡住。
+
+   - 对账用 `picomatch`(从传递依赖提升为直接依赖),与上游**同一个匹配引擎**;此前自实现的 glob 对 `{}` 模式**漏报**,且会灾难性回溯
+   - `status` 现在**失败(exit 74)**并指名违规规则与文件,而不是报 OK;doctor 也报这个缺口
+   - `init` 自愈,且 preflight / autorefresh 走**同一个 helper** —— 它们此前会跑上游 init 并盖 marker 却**不做修复**,使"全新 clone 自愈"在真实流程里**不可达**
+   - 匹配不到任何 tracked 文件的规则**永不删除**;未跟踪文件仍被排除(原语义不变)
+
+2. **4 维人工验收闸干不了活 —— 四层独立失效,每一层都只有真机跑才看得见。**
+
+   - **(a)** 服务只把目标的 `successCriteria` 喂给模型,**一条证据都不给**,却要求它产出**带证据的裁决**。现在从磁盘收集真实证据(有界),并用**结构而非提示词措辞**保证:支撑源全部缺失的 `pass` 一律降级为 `inconclusive`
+   - **(b)** CLI 只能跑 `stub`;`--llm-provider anthropic` 现在真的构造 runner,`providerBinding` 如实上报
+   - **(c)** `maxTokens` 硬编码 3000,低于一份完整证据包所需,回复被**截在 JSON 中间**;预算随内联证据量伸缩,截断被诊断为"输出预算失败"而非"JSON 非法",并给出 `PEAKS_FINAL_REVIEW_MAX_OUTPUT_TOKENS` 逃生阀
+   - **(d)** 证据预算是**先到先得**,于是最后排序的源 —— 也就是四个维度里的一个 —— 被**永久饿死**;现在每个维度有保留配额
+
+   ⚠️ **`existing-functionality-intact` 仍然无法通过**:它要求的 `pre-post-diff` 产物**全仓没有任何生产者**。这是缺功能,不是 bug;已在 SKILL.md 记为**工具状态**,而**不是**把一个不相关的源重映射进去把闸弄绿。
+
+3. **同一个"闸门验代理而非性质"的形状,又抓到三处。**
+
+   - `handoff-auto-regen` 把 `sessionId` **写了两遍**,产出的 frontmatter 仓库自己的 YAML 解析器**拒绝** —— 而 `AUDIT_REQUIRES_HANDOFF` 只做**子串**检查,所以放行
+   - `sub-agent finalize --request-id` 扫会话目录下**所有** `.json`,读到 `active-dispatches.json` 就抛;两个分支现在都容忍坏记录,且 `--request-id` 与 `--batch` 共用**优先 queued** 的选择逻辑,并报出选了哪条、为何跳过其它
+   - `skills/peaks-final-review/SKILL.md` 断言它自己的 CLI "**尚不存在**",让调用方去手写 service 调用 —— 而它存在且已注册。这句话在本版开发中**真实地浪费了工作**:orchestrator 为一个早已存在的命令手写了一个调用脚本
+
+**验证**:三个版本常量一致(**4.0.44**);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **213 files / 2116 passed / 3 skipped / 0 failed**;`pnpm build` 的 `build-integrity` OK。
+
+**已知未修**:`existing-functionality-intact` 缺证据生产者(见第 2 条);`RUNTIME_NPM_VERSION`(0.0.21)与 internal-runtime 包版本已不同步(4.0.43 起即如此)。
+
 ## 4.0.43 — 2026-09-12 (一个从来拦不住东西的闸门 + 前端接口防腐层)
 
 **Highlights**:

package/README-en.md

@@ -140,7 +140,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.43 (2026-09-12) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.45 (2026-09-12) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -140,7 +140,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.43(2026-09-12) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.45(2026-09-12) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

package/dist/cli/commands/codegraph-commands.d.ts

@@ -10,4 +10,5 @@ import { type ProgramIO } from '../cli-helpers.js';
  * untouched.
  */
 export declare function rewriteBareCodegraphHints(text: string): string;
+export declare function attributeUpstreamUpToDateLine(stdout: string): string;
 export declare function registerCodegraphCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/codegraph-commands.js

@@ -2,6 +2,8 @@ import { InvalidArgumentError } from 'commander';
 import { statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createCodegraphInvocation, executeCodegraphInvocation, defaultCodegraphInitGuard, writeCodegraphMarker, writeCodegraphAffectedContext, CodegraphInitConflictError } from '../../services/codegraph/codegraph-service.js';
+import { CODEGRAPH_INTEGRITY_EXIT_CODE, inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent, renderCodegraphExcludeIntegrityLines } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
 function addPeaksJsonOption(command) {
@@ -36,7 +38,48 @@ function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
 export function rewriteBareCodegraphHints(text) {
     return text.replace(/(?<![\w-])(?<!peaks\s)codegraph(?=\s+(?:status|init|index|query|files|context|affected)\b)/g, 'peaks codegraph');
 }
-async function runCodegraphCommand(io, command, options, asJson) {
+const ANSI_SGR_PATTERN = /\x1b\[[0-9;]*m/g;
+/**
+ * Upstream `status` answers a different question than peaks-loop's
+ * integrity gate: upstream says "the on-disk graph matches the last scan"
+ * (true), peaks says "that graph covers the repository" (false when rules
+ * exclude tracked files). Both verdicts are correct, but an unqualified
+ * `[OK] Index is up to date` printed above our `[FAIL] ...` reads as
+ * "nothing to see here" — and the OK is the line the eye lands on first.
+ * The exit code and the JSON envelope are already right; only this line
+ * lies by juxtaposition.
+ *
+ * So: keep upstream's wording — the line stays recognizable, and the
+ * Files/Nodes counts around it are untouched — but drop the bare OK
+ * marker and name the only question it answers. Clean runs never reach
+ * this, so their output stays byte-identical.
+ *
+ * The match is anchored to THAT line. An earlier version keyed on
+ * `includes('up to date')`, which is content-blind: upstream prints other
+ * `[OK] ... are up to date` lines (a language-server or watcher line is the
+ * observed one), and each of those was rewritten into a claim about the
+ * INDEX — a misattribution introduced by a change whose entire purpose was
+ * to stop misleading output. Anything that is not the index line is passed
+ * through byte-for-byte, tail note and all.
+ */
+const INDEX_UP_TO_DATE_RE = /^\[OK\]\s+Index is up to date\b/i;
+export function attributeUpstreamUpToDateLine(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => {
+        const visible = line.replace(ANSI_SGR_PATTERN, '').trim();
+        if (!INDEX_UP_TO_DATE_RE.test(visible)) {
+            return line;
+        }
+        // Only the OK marker is downgraded and the attribution appended: the
+        // rest of the line — including whatever upstream wrote after it — is
+        // preserved, so nothing upstream actually said is replaced.
+        const withoutOk = visible.replace(/^\[OK\]\s*/, '');
+        return `[i] ${withoutOk} (upstream: matches the last scan only; repository coverage is answered below)`;
+    })
+        .join('\n');
+}
+async function runCodegraphCommand(io, command, options, asJson, attributeStdout) {
     try {
         const invocation = createCodegraphInvocation(options);
         const result = await executeCodegraphInvocation(invocation);
@@ -45,7 +88,8 @@ async function runCodegraphCommand(io, command, options, asJson) {
             return;
         }
         const didFail = result.exitCode !== null && result.exitCode !== 0;
-        const stdout = rewriteBareCodegraphHints(result.stdout);
+        const rewritten = rewriteBareCodegraphHints(result.stdout);
+        const stdout = attributeStdout === undefined ? rewritten : attributeStdout(rewritten);
         const stderr = rewriteBareCodegraphHints(result.stderr);
         if (stdout.length > 0) {
             io.stdout((didFail ? redactSensitiveErrorMessage(stdout) : stdout).trimEnd());
@@ -61,6 +105,144 @@ async function runCodegraphCommand(io, command, options, asJson) {
         printCodegraphFailure(io, command, error, asJson);
     }
 }
+/**
+ * `--peaks-json` machine report for `status`. Carries the upstream
+ * result AND the peaks-loop integrity verdict as one JSON document so a
+ * CI job can gate on `data.integrity.gap` / `data.integrity.rulesToRemove`
+ * without scraping human text.
+ */
+async function runCodegraphStatusJson(io, options, integrity, integrityWarning) {
+    let result;
+    try {
+        result = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'status', project: options.project }));
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.status', error, true);
+        return;
+    }
+    const upstream = {
+        exitCode: result.exitCode,
+        stdout: rewriteBareCodegraphHints(result.stdout).trimEnd(),
+        stderr: redactSensitiveErrorMessage(rewriteBareCodegraphHints(result.stderr)).trimEnd()
+    };
+    const upstreamFailed = result.exitCode !== null && result.exitCode !== 0;
+    if (integrity?.gap === true) {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_INCOMPLETE', `codegraph index is incomplete: ${integrity.excludedTrackedCount} of ${integrity.trackedSourceCount} tracked source files are excluded by ${integrity.rulesToRemove.length} rule(s).`, { upstream, integrity, integrityWarning }, ['Run `peaks codegraph repair-exclude --project <root>` to drop the offending rules and rebuild the index.']), true);
+    }
+    else if (upstreamFailed) {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(upstream.stderr || upstream.stdout || `codegraph exited with code ${String(result.exitCode)}`), { upstream, integrity, integrityWarning }, ['Check the codegraph project path before retrying']), true);
+    }
+    else {
+        printResult(io, ok('codegraph.status', { upstream, integrity, integrityWarning }), true);
+    }
+    if (upstreamFailed) {
+        process.exitCode = result.exitCode ?? 1;
+    }
+}
+/**
+ * `peaks codegraph status` with an integrity gate.
+ *
+ * The upstream status is still proxied verbatim (that is what the
+ * command has always done), but a clean upstream "index is up to date"
+ * is no longer sufficient: when git-tracked source files are being
+ * excluded by the config, the command says so, names the rules and
+ * files, and exits non-zero.
+ *
+ * Read-only by construction — it imports the integrity inspector, never
+ * the repair writer. Fixing the config is `peaks codegraph init`
+ * (fresh) or `peaks codegraph repair-exclude` (explicit).
+ */
+async function runCodegraphStatusCommand(io, options, asJson) {
+    let integrity = null;
+    let integrityWarning = null;
+    const projectRoot = resolve(options.project);
+    try {
+        // Never initialized here → no exclude list is in play, so there is
+        // nothing to report. Staying silent keeps `status` honest and
+        // unchanged for projects that do not use codegraph at all.
+        integrity = isCodegraphExcludeConfigPresent(projectRoot)
+            ? inspectCodegraphExcludeIntegrity(projectRoot)
+            : null;
+    }
+    catch (error) {
+        // Not a git work tree, no config yet, malformed config — the
+        // upstream status is still worth printing, so degrade to a warning
+        // instead of failing the whole command.
+        integrityWarning = getErrorMessage(error);
+    }
+    if (asJson === true) {
+        await runCodegraphStatusJson(io, options, integrity, integrityWarning);
+    }
+    else {
+        // Only when the gate found a gap: upstream's `[OK] Index is up to
+        // date` answers "consistent with the last scan", and printing it
+        // unqualified right above our `[FAIL]` tells the reader two opposite
+        // things at once. Clean runs get no transform and stay byte-identical.
+        await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, false, integrity?.gap === true ? attributeUpstreamUpToDateLine : undefined);
+        if (integrityWarning !== null) {
+            io.stdout(`[WARN] codegraph exclude integrity not evaluated: ${integrityWarning}`);
+        }
+        else if (integrity !== null) {
+            for (const line of renderCodegraphExcludeIntegrityLines(integrity)) {
+                io.stdout(line);
+            }
+        }
+    }
+    if (integrity?.gap === true) {
+        process.exitCode = CODEGRAPH_INTEGRITY_EXIT_CODE;
+    }
+}
+/**
+ * Explicit repair path: reconcile → drop offending rules → back up the
+ * config → rebuild the index. Mirrors the automatic step `init` runs
+ * after a fresh upstream init, for workspaces that were already
+ * initialized before the integrity gate existed.
+ */
+async function runCodegraphRepairExcludeCommand(io, options, asJson) {
+    let projectRoot;
+    try {
+        const candidate = resolve(options.project);
+        if (!statSync(candidate).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
+        projectRoot = candidate;
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.repair-exclude', error, asJson);
+        return;
+    }
+    const report = await repairCodegraphExcludeFromProject(projectRoot);
+    // Where the notes go matters: `printResult` renders every `warnings`
+    // entry to stderr with a `warning: ` prefix, so a confirmation parked
+    // in the third slot reads as a problem — and a real warning parked
+    // there double-prefixes. Confirmations go to `nextActions`; only a
+    // genuine `report.warning` reaches `warnings`, verbatim.
+    const confirmations = [];
+    if (report.applied) {
+        confirmations.push(`Removed ${report.rulesRemoved.length} exclude rule(s), recovering ${report.filesRecovered} tracked source file(s). Config backed up to ${report.backupPath}.`);
+    }
+    else {
+        confirmations.push('No tracked source file is excluded by the codegraph config; nothing to repair.');
+    }
+    if (report.applied) {
+        confirmations.push('Re-run `peaks codegraph status --project <root>` to confirm the gap is closed.');
+    }
+    printResult(io, ok('codegraph.repair-exclude', {
+        applied: report.applied,
+        rulesRemoved: report.rulesRemoved,
+        filesRecovered: report.filesRecovered,
+        trackedSourceCount: report.trackedSourceCount,
+        configPath: report.configPath,
+        backupPath: report.backupPath,
+        reindexed: report.reindexed,
+        warning: report.warning
+    }, report.warning === null ? [] : [report.warning], confirmations), asJson);
+    // A repair that could not run to completion (or could not reindex)
+    // must not report success to a shell.
+    if (report.warning !== null) {
+        process.exitCode = 1;
+    }
+}
 /**
  * rid-CG-006 — init conflict guard. Resolves the project root and
  * probes `.codegraph/` for the peaks-loop marker before invoking the
@@ -92,7 +274,14 @@ async function runCodegraphInitCommand(io, options, asJson) {
             guard: guardOutcome.status,
             codegraphDir: guardOutcome.codegraphDir,
             markerPresent: true
-        }, [`.codegraph/ is already managed by peaks-loop; init is a no-op. Marker: ${guardOutcome.codegraphDir}/.peaks-loop-marker`], ['Run `peaks codegraph index` to (re)build the index without touching the schema.']), asJson);
+        }, 
+        // A no-op init is a SUCCESS. This message used to sit in the
+        // `warnings` slot and was therefore printed as
+        // `warning: .codegraph/ is already managed by peaks-loop...`.
+        [], [
+            `.codegraph/ is already managed by peaks-loop; init is a no-op. Marker: ${guardOutcome.codegraphDir}/.peaks-loop-marker`,
+            'Run `peaks codegraph index` to (re)build the index without touching the schema.'
+        ]), asJson);
         return;
     }
     if (guardOutcome.status === 'conflict-foreign-schema') {
@@ -110,8 +299,7 @@ async function runCodegraphInitCommand(io, options, asJson) {
     try {
         const invocation = createCodegraphInvocation({
             subcommand: 'init',
-            project: options.project,
-            ...(options.yes === true ? { yes: true } : {})
+            project: options.project
         });
         const result = await executeCodegraphInvocation(invocation);
         const didFail = result.exitCode !== null && result.exitCode !== 0;
@@ -137,7 +325,47 @@ async function runCodegraphInitCommand(io, options, asJson) {
         catch {
             // intentionally swallowed — surface as warning below
         }
-        printResult(io, ok('codegraph.init', { guard: guardOutcome.status, codegraphDir: guardOutcome.codegraphDir, markerWritten: true }, [], [`Stamped peaks-loop marker at ${guardOutcome.codegraphDir}/.peaks-loop-marker`]), asJson);
+        // Upstream `init` writes its 99-rule default `exclude` template,
+        // some of which collide with real source directories in this
+        // project. Left alone, a fresh clone / new machine gets an index
+        // that silently omits tracked source files while `status` says it
+        // is up to date. Reconcile now, drop the offending rules, and
+        // rebuild the index — a fresh init is the one moment this is both
+        // safe (nothing has been indexed yet) and necessary (`.codegraph/`
+        // is gitignored, so every clone starts from the default template).
+        //
+        // Never throws: a failure here is reported as a warning, not a
+        // failed init (the init itself already succeeded).
+        const excludeRepair = await repairCodegraphExcludeFromProject(projectRoot);
+        // These are confirmations, not warnings: `printResult` renders every
+        // `warnings` entry to stderr behind a `warning: ` prefix, so a fully
+        // successful init used to print a wall of `warning:` lines for what
+        // were plain success messages.
+        const initNotes = [
+            `Stamped peaks-loop marker at ${guardOutcome.codegraphDir}/.peaks-loop-marker`
+        ];
+        if (excludeRepair.applied) {
+            initNotes.push(`Removed ${excludeRepair.rulesRemoved.length} exclude rule(s) that blocked tracked source files, recovering ${excludeRepair.filesRecovered} file(s); config backed up to ${excludeRepair.backupPath}.`);
+            if (excludeRepair.reindexed) {
+                initNotes.push('Rebuilt the codegraph index over the recovered files.');
+            }
+        }
+        printResult(io, ok('codegraph.init', {
+            guard: guardOutcome.status,
+            codegraphDir: guardOutcome.codegraphDir,
+            markerWritten: true,
+            excludeRepair: {
+                applied: excludeRepair.applied,
+                rulesRemoved: excludeRepair.rulesRemoved,
+                filesRecovered: excludeRepair.filesRecovered,
+                reindexed: excludeRepair.reindexed,
+                backupPath: excludeRepair.backupPath,
+                warning: excludeRepair.warning
+            }
+        }, 
+        // Verbatim: `printResult` supplies the `warning: ` prefix, so a
+        // prefix added here would render as `warning: warning: ...`.
+        excludeRepair.warning === null ? [] : [excludeRepair.warning], initNotes), asJson);
     }
     catch (error) {
         printCodegraphFailure(io, 'codegraph.init', error, asJson);
@@ -211,8 +439,11 @@ async function runCodegraphAffectedCommand(io, files, options, asJson) {
 }
 export function registerCodegraphCommands(program, io) {
     const codegraph = program.command('codegraph').description('Run upstream codegraph commands through the Peaks launcher');
-    addProjectOption(codegraph.command('status').description('Show codegraph status')).action((options) => runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, options.peaksJson));
-    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project').option('--yes', 'answer yes to upstream prompts')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph.command('status').description('Show codegraph status, including the exclude integrity gate')).action((options) => runCodegraphStatusCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph
+        .command('repair-exclude')
+        .description('Drop codegraph exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairExcludeCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('index')
         .description('Index a project with codegraph')

package/dist/cli/commands/final-review-commands.d.ts

@@ -1,14 +1,21 @@
 /**
- * W5 Fix M2 — `peaks prepare-final-review <rid>` CLI wrapper.
+ * `peaks prepare-final-review <rid>` CLI wrapper (W5 Fix M2; real provider
+ * binding added by the S3 defect-remediation slice).
  *
- * Exposes the `prepareFinalReview()` service (added in W2 T9 on
+ * Exposes the `prepareFinalReview()` service (W2 T9 on
  * `feature/slice-topology-multipass`) via the CLI surface. The service
- * depends on an injected `LlmRunner`; this slice wires the CLI route
- * with a `stub` provider that returns a structured "scaffold ready"
- * envelope so CI can verify the route without a real LLM. A follow-up
- * slice will bind a real provider. Until then, non-stub providers fail
- * loudly with `LLM_PROVIDER_NOT_IMPLEMENTED` so callers cannot silently
- * no-op.
+ * depends on an injected `LlmRunner`; this file owns the binding:
+ *   - `--llm-provider stub` (default) returns a structured "scaffold ready"
+ *     envelope WITHOUT calling the service, so CI can verify the route
+ *     offline. It performs no review, and says so in every hint it emits.
+ *   - `--llm-provider anthropic` binds the real Messages-API runner
+ *     (`resolveAnthropicConfig()` + `createAnthropicRunner()`) and runs the
+ *     service for real, carrying the 4-dim result back in the envelope.
+ *     An absent credential or model raises `LlmBindingError`, reported under
+ *     its own error code — never degraded into a scaffold a caller could
+ *     mistake for a review.
+ * Unknown provider names still fail loudly with
+ * `LLM_PROVIDER_NOT_IMPLEMENTED` rather than silently falling back to stub.
  *
  * Per the dev-preference "Default-no on new CLI commands" rule and the
  * W4 T14 spec, this is a NEW top-level command (`prepare-final-review`),
@@ -19,13 +26,30 @@
  */
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-export type FinalReviewStatus = 'scaffold-only' | 'not-applicable';
+import type { FinalReviewOutput } from '../../services/final-review/final-review-types.js';
+export type FinalReviewStatus = 'scaffold-only' | 'review-complete' | 'not-applicable';
+/**
+ * Which LLM produced this envelope. `unknown` is reserved for failure
+ * envelopes, where no binding was ever established.
+ */
+export type FinalReviewProviderBinding = 'stub' | 'anthropic-messages-api' | 'unknown';
 export interface FinalReviewData {
     readonly status: FinalReviewStatus;
     readonly rid: string;
     readonly sessionId: string;
     readonly auditGoalPath: string;
     readonly serviceWired: boolean;
-    readonly providerBinding: 'pending-follow-up-slice' | 'unknown';
+    readonly providerBinding: FinalReviewProviderBinding;
+    /** Model id the bound provider answered with (real-provider runs only). */
+    readonly model?: string;
+    /** The 4-dim review the service produced (real-provider runs only). */
+    readonly review?: FinalReviewOutput;
+    /**
+     * Environment variables that were absent when binding failed. Surfaced on
+     * `data` because `fail()` redacts `message` through
+     * `redactSensitiveErrorMessage`, whose catch-all pattern matches the words
+     * `token` / `api_key` and would blank out the very names an operator needs.
+     */
+    readonly missingEnv?: readonly string[];
 }
 export declare function registerFinalReviewCommands(program: Command, io: ProgramIO): void;