peaks-loop 4.0.42 → 4.0.44

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 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**:
+
+1. **`peaks audit goal` 是门面 —— 现在是真的了。** 它是所有 peaks-* 工作流的入口闸门:把一个需求变成 6 维审计加一个目标,并在审计不完整时**拒绝**让自主工作继续。而它无论输入什么都返回同一个 `scaffold-only` 空壳,所以它什么都没拦。校验服务本身是好的,**缺的只是 provider 绑定**。本版建了 peaks-loop 的第一个 LLM 客户端:读会话已经带着的环境(`ANTHROPIC_BASE_URL`;`ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_API_KEY`;`ANTHROPIC_MODEL` 或 `CLAUDE_CODE_SUBAGENT_MODEL`),走全局 `fetch`,**零新增运行时依赖**。
+
+   - **一个静默回退会让这个闸门和以前一样假**,所以凭据缺失时它响亮失败:exit 1,并指名缺失的那个变量。`stub` 保留给 CI,且明确标注自己是 stub。
+   - 真机跑出的第一份审计暴露了第二个洞:**提示词从没写过 `severity` 的合法取值**,模型于是自己发明了 `high` —— 而闸门放它过去了。也就是说它验了**覆盖**和**字段存在**,没验**取值合法**。现在提示词明写合法值,解析器真校验,并**从不规整坏值**:把坏值改写成好值,正是让枚举变成装饰品的做法。
+
+2. **同一个项目开两个窗口会互相串 session —— 已修。** `getCurrentSessionId` 只读一个项目级全局文件,最后开窗口的赢;而 **17 个命令**从它解析 session(job / dispatch / worktree / share / vm / web / slice-* …)。报出来的症状只是无害的那一半(`peaks job status` 报 `JOB_NOT_IN_SESSION`);有害的一半是**两个窗口各有同名 job 或 slice 时,写入落到另一个窗口的目录树里,而且不报错**。现在 caller 优先 —— 由 `peaks session info --active` 用的同一个来源解析 —— 没有绑定时回退全局文件,所以 CI 与非 IDE 调用的行为逐字节不变,且**17 个调用点一行未改**。
+
+   - 对抗 QA 随后发现底下的信任模型没有防护:绑定指向的 session 目录已不存在时仍被信任,而轮转从不清理绑定,于是轮转后 `peaks job init` 会解析到旧 id、并在其下重建 job 目录树。现在绑定分 `bound | stale | absent`,目录不存在即视为陈旧,且**回落这件事是可观测的**。
+   - `lastActivityAt` **删除而非启用**,理由值得记下:它的写入侧本来就是坏的(只在首次绑定和显式重绑时写、复用时不写),所以时间戳在一个**活着的**窗口上照常变老 —— 做 TTL 反而会把"活着但空闲"的窗口解绑,复活刚修掉的那个串档。而时钟也看不见它报的两个缺陷(目录没了、轮转)。
+
+3. **前端/全栈的接口防腐层。** 新增 `peaks scan api-diff <doc>`:解析 OpenAPI 3.x 文档,与项目**已经**产出的三份东西对账(mock-plan、`*-api.types.ts`、TXT handoff 端点清单),输出分成**精确段**(两侧都解析过)与**候选段**(名字 grep,明标会过报漏报)。不建新产物、不做 codegen、不加运行时依赖。
+
+   - 关键取舍写在**输出里**而不是文档里:**生成的类型只能保证"文档↔代码",永远保证不了"文档↔服务器"。** 如果文档本身过时,类型、客户端、mapper 会从**同一份错文档**重新生成、**编译干净通过**、页面渲染 `undefined` —— 而"文档到手"正是这个需求的触发点。所以**诚实的边界是功能的一部分**,不是免责声明。
+   - 两侧遵循同一条规则:**读不全就不说。** 任何无法完整读取的接口或位置都被压制,并附一条能定位到文件/接口/操作 + 原因的 note。这条规则必须同时应用在记录侧**和**文档侧 —— 两者不对称是最后被发现的那处结构性缺口。
+   - 配套:项目扫描新增**三态**集成模式(`full-stack` / `prd-plus-interface-doc` / `prd-only`,从已有信号确定性推导,不新增探测)、缺失的 `## API` 扫描节、RD **按模式路由**(否则三态只是个没人读的死字段)、以及读取 hook **内容**并报告观察到的约定,以**不一致**为信号。
+   - 明确**不做**的事:不检测"组件直接消费 DTO"。那是**类型流**性质,正则表达式只会命中唯一合法的 mapper import、却漏掉真正的违规 —— 一条会打偏的规则比没有规则更糟。
+
+4. **`peaks test <file>` 在 Windows 上从来就没跑通过。** 它 spawn 裸名 `vitest`,而 Windows 上 runner 是 `node_modules/.bin/vitest.cmd` —— 而**这个命令自己的文档**写着"会替你解析本地二进制,Windows 感知"。现在解析项目本地 runner。两种形式都是**实测而非猜测**:直接 spawn `.CMD` 返回 `EINVAL`,而那个"显然的修法" `{shell:true}` 会**破坏 argv**(`tests/a b/x.test.ts` 会变成 3 个参数),所以走显式 `cmd.exe`。找不到 runner 时列出**每一条探过的路径**加修法,而不是抛裸 `ENOENT`。
+
+5. **一处三方分歧:生成的 `frontendOnly` 写在一个标题下、模板写在另一个、读取方从第三个读。** 实际是**四方** —— 找出来的第四方是一份**写入指令**,不改它,下一次 LLM 写的扫描就会重新制造这个漂移。生成器已对齐,新守卫**同时断言该行存在、且在旧位置缺席**(只断言存在的守卫,正是这一整类缺陷反复出厂的原因)。
+
+**验证**:三个版本常量一致(**4.0.43**);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **201 files / 1975 passed / 3 skipped / 0 failed**;`pnpm build` 的 `build-integrity` OK。
+
 ## 4.0.42 — 2026-09-12 (peaks 自己的钩子在每次编辑时报错)
 
 **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.42 (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.44 (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.42(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.44(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/_register.js

@@ -60,6 +60,7 @@ import { registerReviewerCommands } from './reviewer-commands.js';
 import { registerRoleCommands } from './role-commands.js';
 import { registerRuntimeCommands } from './runtime-commands.js';
 import { registerScanCommands } from './scan-commands.js';
+import { registerApiDiffCommands } from './api-diff-commands.js';
 import { registerShadcnCommands } from './shadcn-commands.js';
 import { registerSecurityAuditCommands } from './security-audit-commands.js';
 import { registerSedimentCommands } from './sediment-commands.js';
@@ -99,6 +100,9 @@ const REGISTRATIONS = [
     ['project-commands', registerProjectCommands], ['prd-commands', registerPrdCommands],
     ['request-commands', registerRequestCommands], ['retrospective-commands', registerRetrospectiveCommands],
     ['scan-commands', registerScanCommands], ['shadcn-commands', registerShadcnCommands],
+    // Registered after `scan-commands` on purpose: it attaches `scan api-diff`
+    // to the existing parent instead of creating a second `scan` command.
+    ['api-diff-commands', registerApiDiffCommands],
     ['slice-commands', registerSliceCommands],
     ['sop-commands', registerSopCommands], ['feedback-commands', registerFeedbackCommands],
     ['fork-commands', registerForkCommands], ['impact-commands', registerImpactCommands],

package/dist/cli/commands/api-diff-commands.d.ts

@@ -0,0 +1,16 @@
+/**
+ * S1 / rid=api-diff-report — `peaks scan api-diff <doc>`.
+ *
+ * Group choice: `scan`, not a new top-level `api` group. `scan` already hosts
+ * `api-surface` — a read-only, `--project`-scoped API analysis that writes no
+ * artifact — so `api-diff` is a sibling of an existing command with identical
+ * semantics and an identical option shape. A new `peaks api` group would be a
+ * brand-new verb family whose cost the design (docs/superpowers/specs/
+ * 2026-09-12-frontend-acl-contract-design.md §3/§5) records as medium and
+ * acknowledged; nothing about this slice needs it.
+ *
+ * The command is read-only: it creates no contract artifact and writes no file.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerApiDiffCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/api-diff-commands.js

@@ -0,0 +1,55 @@
+/**
+ * S1 / rid=api-diff-report — `peaks scan api-diff <doc>`.
+ *
+ * Group choice: `scan`, not a new top-level `api` group. `scan` already hosts
+ * `api-surface` — a read-only, `--project`-scoped API analysis that writes no
+ * artifact — so `api-diff` is a sibling of an existing command with identical
+ * semantics and an identical option shape. A new `peaks api` group would be a
+ * brand-new verb family whose cost the design (docs/superpowers/specs/
+ * 2026-09-12-frontend-acl-contract-design.md §3/§5) records as medium and
+ * acknowledged; nothing about this slice needs it.
+ *
+ * The command is read-only: it creates no contract artifact and writes no file.
+ */
+import { ApiDiffInputError, diffApiDocument, formatApiDiffText } from '../../services/scan/api-diff-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerApiDiffCommands(program, io) {
+    // Reuse the existing `scan` parent — the add-a-new-subcommand-check-for-
+    // existing-top-level-first rule (same guard as bee-commands / asset-commands).
+    const scan = program.commands.find((c) => c.name() === 'scan') ?? program
+        .command('scan')
+        .description('Read-only project scans for tech-doc and RD handoffs');
+    addJsonOption(scan
+        .command('api-diff')
+        .description('Diff an OpenAPI 3.x document (.json/.yaml/.yml) against what this project already recorded — ' +
+        'the mock-plan, the recorded *-api.types.ts interfaces, and the TXT handoff endpoint list. ' +
+        'Read-only: creates no contract artifact. Output separates an Exact section (both sides parsed) ' +
+        'from a Candidate mentions section (name-grep, may over- and under-report), and always prints ' +
+        'what this command cannot detect.')
+        .argument('<doc>', 'path to the OpenAPI 3.x document (relative to --project, or absolute)')
+        .option('--project <path>', 'consumer project root (default: cwd)')).action((doc, options) => {
+        const projectRoot = options.project ?? process.cwd();
+        const asJson = options.json ?? false;
+        try {
+            const report = diffApiDocument({ projectRoot, docPath: doc });
+            const nextActions = report.notes.length > 0
+                ? ['Read the notes: at least one recorded source was missing, so the Exact section is partial by construction.']
+                : [];
+            if (asJson) {
+                printResult(io, ok('scan.api-diff', report, [], nextActions), true);
+                return;
+            }
+            io.stdout(`${formatApiDiffText(report)}\n`);
+        }
+        catch (error) {
+            // A non-OpenAPI input must exit non-zero AND produce no diff output — a
+            // silent empty report is the exact failure this command exists to prevent.
+            const code = error instanceof ApiDiffInputError ? error.code : 'API_DIFF_FAILED';
+            printResult(io, fail('scan.api-diff', code, error.message, { document: doc }, [
+                'Pass a path to an OpenAPI 3.x document: a top-level `openapi: 3.x` string plus a non-empty `paths` object.'
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -10,14 +10,27 @@
 import { Command } from 'commander';
 import { type AgentShieldState } from '../../services/audit/static-service.js';
 import { type ProgramIO } from '../cli-helpers.js';
+import type { AuditGoalOutput } from '../../services/audit/audit-goal-types.js';
 import type { RedLineAudit } from '../../services/audit/types.js';
 import { type AuditDecisionRecord } from '../../services/audit/decision-writer.js';
+/** `audit-failed` is a failure envelope's status — never a scaffold, never a success. */
+export type AuditGoalStatus = 'audit-complete' | 'scaffold-only' | 'audit-failed';
 export interface AuditGoalData {
-    readonly status: 'scaffold-only';
-    readonly serviceWired: true;
-    readonly providerBinding: 'pending-follow-up-slice';
+    readonly status: AuditGoalStatus;
+    /** Which LLM produced (or failed to produce) the audit. `unresolved` = rejected before binding. */
+    readonly providerBinding: 'anthropic-messages-api' | 'stub' | 'unresolved';
     readonly need: string;
     readonly projectRoot: string;
+    /** The validated 6-dimension audit. Present on success only. */
+    readonly result?: AuditGoalOutput;
+    /** The bound model. Present on a real run only. */
+    readonly model?: string;
+    /**
+     * Environment variables the binding needed and did not find. Present on a
+     * binding failure only, and verbatim: `fail()` redacts `message`, so this
+     * is the channel that reliably names what the operator must set.
+     */
+    readonly missingEnv?: readonly string[];
 }
 export interface StaticAuditData {
     readonly audit: RedLineAudit;

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

@@ -11,6 +11,9 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { runRedLinesAudit } from '../../services/audit/red-lines-service.js';
 import { runStaticAudit } from '../../services/audit/static-service.js';
+import { auditGoal, IncompleteAuditError } from '../../services/audit/audit-goal-service.js';
+import { createAnthropicRunner, LlmBindingError, LlmRequestError, resolveAnthropicConfig, } from '../../services/llm/anthropic-runner.js';
+import { createStubRunner } from '../../services/llm/stub-runner.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { writeAuditDecision } from '../../services/audit/decision-writer.js';
@@ -26,7 +29,13 @@ function isSupportedArtifactKind(value) {
     return SUPPORTED_ARTIFACT_KINDS.includes(value);
 }
 /** Whitelist of supported `--llm-provider` values for `peaks audit goal`. */
-const SUPPORTED_LLM_PROVIDERS = ['stub'];
+const SUPPORTED_LLM_PROVIDERS = ['anthropic', 'stub'];
+/**
+ * The real provider is the default: `peaks audit goal` is the entry gate for
+ * every peaks-* workflow, so it must audit by default and only scaffold when
+ * a caller explicitly asks for `stub`.
+ */
+const DEFAULT_LLM_PROVIDER = 'anthropic';
 function isSupportedLlmProvider(value) {
     return SUPPORTED_LLM_PROVIDERS.includes(value);
 }
@@ -195,47 +204,69 @@ export function registerAuditCommands(program, io) {
             process.exitCode = 1;
         }
     });
-    // Fix M1 (W5) — `peaks audit goal` CLI wrapper around `auditGoal()`.
-    // The service is correctly implemented but is NOT yet wired to a real
-    // LLM provider; this CLI exposes the route with a `stub` provider that
-    // returns a scaffold envelope. 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.
+    // Slice 2026-09-12-llm-provider-binding — `peaks audit goal` now runs the
+    // gate it advertises. `auditGoal()` was already correct (one `LlmRunner`
+    // call, 6-dimension validation, `IncompleteAuditError` on a partial audit);
+    // what was missing was a provider binding, so the command answered with a
+    // fixed `scaffold-only` envelope no matter what it was asked.
+    //
+    // `anthropic` is now the default and reads the session's own environment
+    // (see `resolveAnthropicConfig`). `stub` stays for CI/tests but is
+    // reported as a scaffold, and a missing credential fails loudly — a silent
+    // fall back to the scaffold envelope would leave the gate exactly as fake
+    // as it was before this slice.
     addJsonOption(audit
         .command('goal')
         .description('Audit a human need across 6 dimensions and propose a goal (peaks-audit primitive)')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--need <text>', 'the human need to audit (becomes input.need for auditGoal())')
-        .option('--llm-provider <name>', 'LLM provider name (default: stub)', 'stub')).action(async (options) => {
+        .option('--llm-provider <name>', `LLM provider (${SUPPORTED_LLM_PROVIDERS.join(' | ')}); stub performs no audit`, DEFAULT_LLM_PROVIDER)).action(async (options) => {
         const validation = validateProjectRoot(options.project);
         if (!validation.ok) {
-            printResult(io, fail('audit.goal', validation.code, validation.message, emptyAuditGoalData(options.need, options.project), ['Verify the project path exists and is a directory']), options.json);
+            printResult(io, fail('audit.goal', validation.code, validation.message, auditGoalFailureData(options.need, options.project), ['Verify the project path exists and is a directory']), options.json);
             process.exitCode = 1;
             return;
         }
-        const provider = options.llmProvider ?? 'stub';
+        const provider = options.llmProvider ?? DEFAULT_LLM_PROVIDER;
         if (!isSupportedLlmProvider(provider)) {
-            printResult(io, fail('audit.goal', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, emptyAuditGoalData(options.need, validation.projectRoot), [
-                'Re-run with `--llm-provider stub` (default) to exercise the wired route.',
-                'Real provider binding is tracked as a follow-up slice; see peaks-audit skill notes.'
+            printResult(io, fail('audit.goal', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, auditGoalFailureData(options.need, validation.projectRoot), [
+                `Re-run with \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for a real audit, or \`--llm-provider stub\` for an offline scaffold.`
             ]), options.json);
             process.exitCode = 1;
             return;
         }
-        // Stub provider: surface a structured "scaffold ready" envelope so the
-        // CLI route is wired and a CI test can verify it without a real LLM.
-        const data = {
-            status: 'scaffold-only',
-            serviceWired: true,
-            providerBinding: 'pending-follow-up-slice',
-            need: options.need,
-            projectRoot: validation.projectRoot,
-        };
-        const envelope = ok('audit.goal', data, [], [
-            'auditGoal() service is wired and reachable. The stub provider returns a scaffold envelope so CI can verify the route without a real LLM.',
-            'A follow-up slice will bind a real LLM provider; until then, non-stub providers fail loudly with `LLM_PROVIDER_NOT_IMPLEMENTED`.'
-        ]);
-        printResult(io, envelope, options.json);
+        const isStub = provider === 'stub';
+        const providerBinding = isStub ? 'stub' : 'anthropic-messages-api';
+        try {
+            let model;
+            let llmRunner;
+            if (isStub) {
+                llmRunner = createStubRunner();
+            }
+            else {
+                const config = resolveAnthropicConfig();
+                model = config.model;
+                llmRunner = createAnthropicRunner(config);
+            }
+            const result = await auditGoal({ need: options.need }, llmRunner);
+            const data = {
+                status: isStub ? 'scaffold-only' : 'audit-complete',
+                providerBinding,
+                need: options.need,
+                projectRoot: validation.projectRoot,
+                result,
+                ...(model === undefined ? {} : { model }),
+            };
+            const envelope = ok('audit.goal', data, [], isStub
+                ? [`Stub provider: the 6 dimensions below are placeholders, not findings. Re-run with \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for a real audit.`]
+                : [`Audit produced by ${providerBinding}${model === undefined ? '' : ` (model: ${model})`}.`]);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            const code = auditGoalErrorCode(error);
+            printResult(io, fail('audit.goal', code, getErrorMessage(error), auditGoalFailureData(options.need, validation.projectRoot, providerBinding, error instanceof LlmBindingError ? error.missingEnv : undefined), auditGoalNextActions(code)), options.json);
+            process.exitCode = 1;
+        }
     });
     // ---------------------------------------------------------------------------
     // peaks audit artifact write — Slice 2026-06-26-audit-artifact-writer-generalization
@@ -387,15 +418,37 @@ function emptyStaticAuditData() {
         },
     };
 }
-function emptyAuditGoalData(need, projectRoot) {
+function auditGoalFailureData(need, projectRoot, providerBinding = 'unresolved', missingEnv) {
     return {
-        status: 'scaffold-only',
-        serviceWired: true,
-        providerBinding: 'pending-follow-up-slice',
+        status: 'audit-failed',
+        providerBinding,
         need,
         projectRoot,
+        ...(missingEnv === undefined ? {} : { missingEnv }),
     };
 }
+/** The slice-owned error codes are carried verbatim so callers can gate on them. */
+function auditGoalErrorCode(error) {
+    if (error instanceof IncompleteAuditError || error instanceof LlmBindingError || error instanceof LlmRequestError) {
+        return error.code;
+    }
+    return 'AUDIT_GOAL_FAILED';
+}
+function auditGoalNextActions(code) {
+    switch (code) {
+        case 'LLM_CREDENTIAL_MISSING':
+            return [
+                'Export ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) in the environment that launches peaks, then re-run.',
+                'For an offline scaffold instead of an audit, re-run with `--llm-provider stub` — it performs NO audit.',
+            ];
+        case 'LLM_MODEL_MISSING':
+            return ['Export ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) in the environment that launches peaks, then re-run.'];
+        case 'INCOMPLETE_AUDIT':
+            return ['The LLM reply omitted a required dimension; re-run so autonomous work never proceeds on a partial audit.'];
+        default:
+            return ['Inspect the failure above, then re-run with the same --need.'];
+    }
+}
 function emptyProseRatioResult() {
     return {
         totalRedLines: 0,

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) {
@@ -61,6 +63,140 @@ 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 {
+        await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project });
+        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 +228,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 +253,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 +279,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 +393,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')