peaks-loop 4.0.43 → 4.0.45

package/dist/cli/commands/final-review-commands.js

@@ -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`),
@@ -21,8 +28,18 @@ import { existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
+import { createAnthropicRunner, LlmBindingError, LlmRequestError, resolveAnthropicConfig, } from '../../services/llm/anthropic-runner.js';
+import { IncompleteFinalReviewError, prepareFinalReview, } from '../../services/final-review/final-review-service.js';
 /** Whitelist of supported `--llm-provider` values for `peaks prepare-final-review`. */
-const SUPPORTED_LLM_PROVIDERS = ['stub'];
+const SUPPORTED_LLM_PROVIDERS = ['anthropic', 'stub'];
+/**
+ * Default stays `stub` (unlike `peaks audit goal`, whose default is the real
+ * provider): the scaffold route is what CI and the registered e2e contract
+ * exercise without credentials, and the stub envelope is labelled
+ * `status: 'scaffold-only'` / `providerBinding: 'stub'` so it can never be
+ * read as a review.
+ */
+const DEFAULT_LLM_PROVIDER = 'stub';
 function isSupportedLlmProvider(value) {
     return SUPPORTED_LLM_PROVIDERS.includes(value);
 }
@@ -32,7 +49,7 @@ function isSupportedLlmProvider(value) {
  * "this is a placeholder on a failure" apart from "this is a real
  * scaffold-only success".
  */
-function emptyFinalReviewData(rid, sessionId, auditGoalPath) {
+function emptyFinalReviewData(rid, sessionId, auditGoalPath, missingEnv) {
     return {
         status: 'not-applicable',
         rid,
@@ -40,6 +57,7 @@ function emptyFinalReviewData(rid, sessionId, auditGoalPath) {
         auditGoalPath,
         serviceWired: false,
         providerBinding: 'unknown',
+        ...(missingEnv === undefined ? {} : { missingEnv }),
     };
 }
 function validateProjectRoot(projectArg) {
@@ -95,7 +113,8 @@ export function registerFinalReviewCommands(program, io) {
         .description('Prepare the 4-dimension business review (final-review primitive) for human acceptance (W2 T9 service; CLI surface in W5 M2)')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--session-id <sid>', 'session id whose .peaks/_runtime/<sid>/audit-goal/<rid>.json is the approved goal source')
-        .option('--llm-provider <name>', 'LLM provider name (default: stub)', 'stub')).action(async (rid, options) => {
+        .option('--llm-provider <name>', `LLM provider name: ${SUPPORTED_LLM_PROVIDERS.join(' | ')} (default: ${DEFAULT_LLM_PROVIDER} — performs no review)`, DEFAULT_LLM_PROVIDER)
+        .option('--base <ref>', 'base ref for the pre/post baseline diff (`existing-functionality-intact`); default: merge-base with origin/HEAD, then origin/main, then origin/master, then HEAD~1 — pass this explicitly when none of those resolve')).action(async (rid, options) => {
         // 1. Project root must exist and be a directory.
         const projectValidation = validateProjectRoot(options.project);
         if (!projectValidation.ok) {
@@ -128,34 +147,113 @@ export function registerFinalReviewCommands(program, io) {
             process.exitCode = 1;
             return;
         }
-        // 5. Provider check: only `stub` is wired in this slice.
-        const provider = options.llmProvider ?? 'stub';
+        // 5. Provider check: unknown names fail loudly — a silent fallback to
+        //    `stub` would hand the caller a scaffold envelope that reads as a
+        //    review route, which is the defect class this gate exists to stop.
+        const provider = options.llmProvider ?? DEFAULT_LLM_PROVIDER;
         if (!isSupportedLlmProvider(provider)) {
-            printResult(io, fail('final-review.prepare', 'LLM_PROVIDER_NOT_IMPLEMENTED', `Provider '${provider}' is not yet wired. The CLI surface is in place; real provider binding is a follow-up slice. Use --llm-provider stub to validate the route without invoking the LLM.`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
-                'Re-run with `--llm-provider stub` (default) to validate the route.',
-                'Real provider binding is tracked as a follow-up slice.',
+            printResult(io, fail('final-review.prepare', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
+                `Re-run with \`--llm-provider anthropic\` for a real 4-dim review, or \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for an offline scaffold.`,
             ]), options.json);
             process.exitCode = 1;
             return;
         }
         // 6. Stub path: surface a structured "scaffold ready" envelope.
-        //    We DO NOT call the service in this slice — the service depends
-        //    on an injected `LlmRunner` interface, and no real provider is
-        //    bound yet. The envelope confirms the route is wired end-to-end
-        //    and reports the audit-goal path the service WOULD read.
-        const data = {
-            status: 'scaffold-only',
-            rid,
-            sessionId: sessionValidation.sessionId,
-            auditGoalPath,
-            serviceWired: true,
-            providerBinding: 'pending-follow-up-slice',
-        };
-        const envelope = ok('final-review.prepare', data, [], [
-            'prepareFinalReview() service is wired and reachable. The stub provider returns a scaffold envelope so CI can verify the route without a real LLM.',
-            `Audit-goal file is present at: ${auditGoalPath}`,
-            '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);
+        //    We DO NOT call the service here — the stub runner answers the
+        //    audit-goal shape, not the 4-dim review shape, so running it through
+        //    `prepareFinalReview()` would only manufacture a malformed review.
+        //    The envelope confirms the route is wired end-to-end and reports the
+        //    audit-goal path the service WOULD read.
+        if (provider === 'stub') {
+            const data = {
+                status: 'scaffold-only',
+                rid,
+                sessionId: sessionValidation.sessionId,
+                auditGoalPath,
+                serviceWired: true,
+                providerBinding: 'stub',
+            };
+            const envelope = ok('final-review.prepare', data, [], [
+                'Stub provider: no 4-dim review was performed. This envelope only proves the route is wired and reachable.',
+                `Audit-goal file is present at: ${auditGoalPath}`,
+                'Re-run with `--llm-provider anthropic` to produce a real review.',
+            ]);
+            printResult(io, envelope, options.json);
+            return;
+        }
+        // 7. Real provider path: bind a real `LlmRunner` and run the service.
+        //    Binding happens INSIDE the try so an absent credential surfaces as
+        //    `LlmBindingError`'s own code instead of escaping as a crash. No
+        //    envelope is emitted on that path — a "successful" empty review would
+        //    be worse than an error.
+        try {
+            const config = resolveAnthropicConfig();
+            const llmRunner = createAnthropicRunner(config);
+            const review = await prepareFinalReview(rid, {
+                projectRoot: projectValidation.projectRoot,
+                sessionId: sessionValidation.sessionId,
+                llmRunner,
+                ...(options.base === undefined ? {} : { baseRef: options.base }),
+            });
+            const data = {
+                status: 'review-complete',
+                rid,
+                sessionId: sessionValidation.sessionId,
+                auditGoalPath,
+                serviceWired: true,
+                providerBinding: 'anthropic-messages-api',
+                model: config.model,
+                review,
+            };
+            const envelope = ok('final-review.prepare', data, review.allPass ? [] : [
+                `Dimensions needing human attention: ${review.needsAttention.join(', ') || 'none flagged'}.`,
+            ], [
+                `4-dim review produced by anthropic-messages-api (model: ${config.model}).`,
+                `allPass: ${String(review.allPass)}.`,
+            ]);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            const code = finalReviewErrorCode(error);
+            printResult(io, fail('final-review.prepare', code, getErrorMessage(error), emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath, error instanceof LlmBindingError ? error.missingEnv : undefined), finalReviewNextActions(code)), options.json);
+            process.exitCode = 1;
+        }
     });
 }
+/**
+ * Map a thrown error to the CLI's error code. The LLM-layer errors already
+ * carry codes precise enough to act on (`LLM_CREDENTIAL_MISSING`,
+ * `LLM_REQUEST_FAILED`, …), so they are passed through rather than flattened
+ * into one opaque failure.
+ */
+function finalReviewErrorCode(error) {
+    if (error instanceof LlmBindingError ||
+        error instanceof LlmRequestError ||
+        error instanceof IncompleteFinalReviewError) {
+        return error.code;
+    }
+    return 'FINAL_REVIEW_FAILED';
+}
+function finalReviewNextActions(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 a review, re-run with `--llm-provider stub` — it performs NO review.',
+            ];
+        case 'LLM_MODEL_MISSING':
+            return [
+                'Export ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) in the environment that launches peaks, then re-run.',
+            ];
+        case 'LLM_REQUEST_FAILED':
+            return [
+                'Check ANTHROPIC_BASE_URL and network reachability, then re-run — a transport failure produces no review.',
+            ];
+        case 'INCOMPLETE_FINAL_REVIEW':
+            return [
+                'The LLM reply was not valid JSON or omitted a required dimension; re-run so the gate is never read as complete.',
+            ];
+        default:
+            return ['Re-run with `--llm-provider stub` to validate the CLI route without a real LLM.'];
+    }
+}

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

@@ -12,6 +12,55 @@
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * A `dispatch-*.json` candidate for `finalize --request-id`, as read off disk.
+ * The record's own `createdAt` is carried as the recency key — NOT the file's
+ * mtime, which any heartbeat or finalize rewrites, so a `done` record can look
+ * newer than the `queued` one that superseded it. Keeping the key on the
+ * candidate makes the selection rule a pure function of the records and
+ * testable without a filesystem.
+ */
+export interface FinalizeCandidate {
+    readonly recordPath: string;
+    readonly requestId: string;
+    readonly status: string;
+    readonly createdAt: string;
+}
+/**
+ * What `--request-id` actually did, reported in the envelope. N3: the branch
+ * used to resolve silently and could not say WHY a record was or was not the
+ * one finalized.
+ */
+export interface FinalizeSelection {
+    readonly requestId: string;
+    readonly rule: string;
+    readonly matched: number;
+    readonly chosen: string | null;
+    readonly rejected: readonly {
+        readonly recordPath: string;
+        readonly status: string;
+        readonly reason: string;
+    }[];
+}
+/** The one selection rule `--request-id` and `--batch` now share. */
+export declare const FINALIZE_SELECTION_RULE: string;
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * (this session holds six records for `2026-09-12-defect-remediation`) it
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export declare function selectFinalizeTarget(candidates: readonly FinalizeCandidate[]): FinalizeCandidate | null;
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export declare function describeFinalizeRejection(candidate: FinalizeCandidate, chosen: FinalizeCandidate | null): string;
 export declare function registerShareCommand(parent: Command, io: ProgramIO): void;
 export declare function registerSharedReadCommand(parent: Command, io: ProgramIO): void;
 export declare function registerAwaitCommand(parent: Command, io: ProgramIO): void;

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

@@ -5,6 +5,36 @@ import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } f
 import { writeLogEntry } from '../../services/log/logger.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { summarizeBatchResults } from './sub-agent-shared.js';
+/** The one selection rule `--request-id` and `--batch` now share. */
+export const FINALIZE_SELECTION_RULE = 'prefer status=queued; among those, newest by record createdAt (then filename); ' +
+    'no queued match means nothing is finalized';
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * (this session holds six records for `2026-09-12-defect-remediation`) it
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export function selectFinalizeTarget(candidates) {
+    const queued = candidates.filter(candidate => candidate.status === 'queued');
+    if (queued.length === 0)
+        return null;
+    return [...queued].sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.recordPath.localeCompare(a.recordPath))[0];
+}
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export function describeFinalizeRejection(candidate, chosen) {
+    if (candidate.status !== 'queued' || chosen === null) {
+        return 'status is ' + candidate.status;
+    }
+    return 'superseded by the newer queued record ' + chosen.recordPath;
+}
 export function registerShareCommand(parent, io) {
     addJsonOption(parent
         .command('share')
@@ -329,6 +359,31 @@ export function registerFinalizeCommand(parent, io) {
                 const finalized = [];
                 const skipped = [];
                 const errors = [];
+                let selection = null;
+                /**
+                 * N2 — one unreadable record must not abort the sweep.
+                 *
+                 * Skipping `active-dispatches.json` and `batch-*.counter.json` by
+                 * FILENAME removed the two non-record files that happened to be in the
+                 * directory, but a single stale or foreign `dispatch-*.json` (an old
+                 * `version`, hand-edited JSON, a truncated write) still made
+                 * `readRecord` throw from OUTSIDE any try/catch — and the throw
+                 * escaped to the action's outer handler, so `--request-id` AND
+                 * `--batch` both died with `FINALIZE_ERROR` and exit 1 without
+                 * touching a single healthy record.
+                 *
+                 * A record that cannot be read is now reported in `errors[]` and
+                 * skipped; every other record is processed as before.
+                 */
+                const tryReadRecord = (recordPath) => {
+                    try {
+                        return readRecord(recordPath);
+                    }
+                    catch (e) {
+                        errors.push({ recordPath, error: getErrorMessage(e) });
+                        return null;
+                    }
+                };
                 const applyOutcome = (recordPath, rid) => {
                     markCompleted({ recordPath, now: () => new Date(), status: mapped.status, outcome: mapped.outcome, projectRoot });
                     finalized.push({ recordPath, requestId: rid, status: mapped.status });
@@ -352,29 +407,59 @@ export function registerFinalizeCommand(parent, io) {
                     const fs2 = await import('node:fs');
                     const path2 = await import('node:path');
                     const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
-                    let resolvedPath = null;
+                    const candidates = [];
                     if (fs2.existsSync(dir)) {
                         for (const f of fs2.readdirSync(dir)) {
-                            if (!f.endsWith('.json'))
+                            // Only dispatch records are readable records. The session
+                            // directory also holds `active-dispatches.json` (an index)
+                            // and `batch-<uuid>.counter.json` (batch counters); neither
+                            // carries a `version` field, so `readRecord` on them throws
+                            // `Dispatch record version mismatch ... got undefined`. The
+                            // `--batch` branch below has always used this same filter.
+                            if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
                             const p = path2.join(dir, f);
-                            const r = readRecord(p);
-                            if (r.requestId === options.requestId) {
-                                resolvedPath = p;
-                                break;
-                            }
+                            const r = tryReadRecord(p);
+                            if (r === null || r.requestId !== options.requestId)
+                                continue;
+                            candidates.push({
+                                recordPath: p,
+                                requestId: r.requestId,
+                                status: r.status,
+                                createdAt: r.createdAt
+                            });
                         }
                     }
-                    if (!resolvedPath) {
+                    if (candidates.length === 0) {
                         printResult(io, fail('sub-agent.finalize', 'RECORD_NOT_FOUND', 'No dispatch record for requestId=' + options.requestId, { ok: false }, ['Check --request-id matches the dispatch envelope.']), asJson);
                         process.exitCode = 1;
                         return;
                     }
-                    try {
-                        applyOutcome(resolvedPath, options.requestId);
+                    // N3: same rule as `--batch` — see `selectFinalizeTarget`.
+                    const chosen = selectFinalizeTarget(candidates);
+                    selection = {
+                        requestId: options.requestId,
+                        rule: FINALIZE_SELECTION_RULE,
+                        matched: candidates.length,
+                        chosen: chosen?.recordPath ?? null,
+                        rejected: candidates
+                            .filter(candidate => candidate !== chosen)
+                            .map(candidate => ({
+                            recordPath: candidate.recordPath,
+                            status: candidate.status,
+                            reason: describeFinalizeRejection(candidate, chosen)
+                        }))
+                    };
+                    for (const rejected of selection.rejected) {
+                        skipped.push({ recordPath: rejected.recordPath, reason: rejected.reason });
                     }
-                    catch (e) {
-                        errors.push({ recordPath: resolvedPath, error: getErrorMessage(e) });
+                    if (chosen !== null) {
+                        try {
+                            applyOutcome(chosen.recordPath, chosen.requestId);
+                        }
+                        catch (e) {
+                            errors.push({ recordPath: chosen.recordPath, error: getErrorMessage(e) });
+                        }
                     }
                 }
                 else {
@@ -386,7 +471,9 @@ export function registerFinalizeCommand(parent, io) {
                             if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
                             const p = path2.join(dir, f);
-                            const r = readRecord(p);
+                            const r = tryReadRecord(p);
+                            if (r === null)
+                                continue;
                             if (r.batchId !== options.batch)
                                 continue;
                             if (r.status !== 'queued') {
@@ -402,7 +489,20 @@ export function registerFinalizeCommand(parent, io) {
                         }
                     }
                 }
-                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], errors.length > 0 ? ['Re-run after fixing.'] : ['All targeted records transitioned out of queued.']), asJson);
+                const hints = [];
+                if (errors.length > 0) {
+                    hints.push('Re-run after fixing; unreadable records are listed in errors[] and were skipped, not fatal.');
+                }
+                else if (finalized.length === 0 && skipped.length > 0) {
+                    hints.push('Nothing was finalized: every matching record had already left `queued`. See skipped[] for each record\'s status.');
+                }
+                else {
+                    hints.push('All targeted records transitioned out of queued.');
+                }
+                if (selection !== null) {
+                    hints.push(`--request-id selection (${selection.rule}): chose ${selection.chosen ?? '(none)'} of ${selection.matched} matching record(s); ${selection.rejected.length} rejected.`);
+                }
+                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, selection, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], hints), asJson);
                 if (errors.length > 0)
                     process.exitCode = 1;
             }

package/dist/services/codegraph/codegraph-autorefresh.js

@@ -38,6 +38,7 @@
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized, } from './codegraph-service.js';
+import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
 /**
  * True when `<projectRoot>/.codegraph/` exists and is a directory.
  * Pure fs probe; never throws.
@@ -107,6 +108,17 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
                     note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
                 };
             }
+            // That init just wrote upstream's 99-rule default `exclude`
+            // template, some of which block tracked source files — the same
+            // self-heal the CLI's `peaks codegraph init` performs, via the
+            // same shared helper. Skipped, this path would stamp the
+            // peaks-loop marker over an incomplete index that no later
+            // `init` (it would no-op) could ever repair.
+            //
+            // Never throws (the helper catches everything), and
+            // `reindex: false` because the index call below covers the
+            // recovered files.
+            await repairCodegraphExcludeFromProject(projectRoot, runner, { reindex: false });
         }
         const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
         const result = await executeCodegraphInvocation(invocation, runner);

package/dist/services/codegraph/codegraph-exclude-integrity.d.ts

@@ -0,0 +1,61 @@
+import { type CodegraphExcludeViolation } from './codegraph-exclude-reconciler.js';
+/**
+ * Exit code `peaks codegraph status` uses when the index is
+ * demonstrably incomplete. Distinct from the upstream pass-through
+ * exit code and from `CODEGRAPH_INIT_CONFLICT_EXIT_CODE` (73) so a CI
+ * job can tell "codegraph said no" apart from "peaks-loop found a
+ * tracked source file the index silently dropped".
+ */
+export declare const CODEGRAPH_INTEGRITY_EXIT_CODE = 74;
+export type CodegraphExcludeRuleImpact = {
+    /** The `exclude` rule that must be dropped. */
+    readonly rule: string;
+    /** Distinct tracked source files this single rule blocks. */
+    readonly blockedCount: number;
+};
+export type CodegraphExcludeIntegrityReport = {
+    /** Absolute path of the reconciled `.codegraph/config.json`. */
+    readonly configPath: string;
+    /** True when at least one tracked source file is blocked. */
+    readonly gap: boolean;
+    /** Tracked files that pass the config's `include` filter at all. */
+    readonly trackedSourceCount: number;
+    /** Distinct tracked source files blocked by at least one rule. */
+    readonly excludedTrackedCount: number;
+    /** One entry per (file, rule) pair — see S1's reconciler. */
+    readonly violations: readonly CodegraphExcludeViolation[];
+    /** Rules that must be dropped; empty exactly when `gap` is false. */
+    readonly rulesToRemove: readonly string[];
+    /** Per-rule blocked-file counts, in `rulesToRemove` order. */
+    readonly ruleImpacts: readonly CodegraphExcludeRuleImpact[];
+};
+/**
+ * True when `<projectRoot>/.codegraph/config.json` exists, i.e. when an
+ * exclude list is actually in play here. Both consumers use this to
+ * stay SILENT on a project that never ran `peaks codegraph init`: there
+ * is no exclusion to report, and a missing config is not a finding.
+ *
+ * Note the difference from `isCodegraphInitialized` in
+ * `codegraph-service.ts`, which probes `codegraph.db` (upstream's own
+ * definition of "initialized"). The exclude list is written by upstream
+ * init, so its presence is the narrower question this module asks.
+ */
+export declare function isCodegraphExcludeConfigPresent(projectRoot: string): boolean;
+/**
+ * Read the project's git-tracked files + `.codegraph/config.json` and
+ * fold the reconciliation into a report.
+ *
+ * Throws (never silently degrades) when the project is not a git work
+ * tree, when the config is missing, or when it is malformed — callers
+ * that must stay alive (doctor, `status`) catch and surface the reason.
+ */
+export declare function inspectCodegraphExcludeIntegrity(projectRoot: string): CodegraphExcludeIntegrityReport;
+/**
+ * Human-readable detail lines for a gapped report: the headline count,
+ * then the offending rules, then a sample of the blocked files so an
+ * operator can point at a concrete path without re-running anything.
+ *
+ * Returns an empty array for a clean report — the caller decides
+ * whether "clean" is worth printing at all.
+ */
+export declare function renderCodegraphExcludeIntegrityLines(report: CodegraphExcludeIntegrityReport): readonly string[];

package/dist/services/codegraph/codegraph-exclude-integrity.js

@@ -0,0 +1,98 @@
+// src/services/codegraph/codegraph-exclude-integrity.ts
+//
+// Slice S2 of `2026-09-12-codegraph-exclude-integrity` — the READ-ONLY
+// integrity report shared by `peaks codegraph status` and the
+// `capability:codegraph-exclude-integrity` doctor check.
+//
+// S1's reconciler computes the raw truth (`violations` /
+// `rulesToRemove`). This module folds it into a verdict-shaped report
+// that both consumers can render and gate on, so neither of them has
+// to re-derive "is there a gap, how big, and which rules cause it".
+//
+// It NEVER writes `.codegraph/config.json`. The only write path is
+// `codegraph-exclude-repair.ts`, reachable from `peaks codegraph init`
+// (fresh-initialization self-heal) and the explicit
+// `peaks codegraph repair-exclude` command. Read stays read.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CODEGRAPH_CONFIG_FILENAME, reconcileCodegraphExcludeFromProject } from './codegraph-exclude-reconciler.js';
+import { CODEGRAPH_DIR_NAME } from './codegraph-service.js';
+/**
+ * Exit code `peaks codegraph status` uses when the index is
+ * demonstrably incomplete. Distinct from the upstream pass-through
+ * exit code and from `CODEGRAPH_INIT_CONFLICT_EXIT_CODE` (73) so a CI
+ * job can tell "codegraph said no" apart from "peaks-loop found a
+ * tracked source file the index silently dropped".
+ */
+export const CODEGRAPH_INTEGRITY_EXIT_CODE = 74;
+/** How many offending rules and blocked files we name on the human path. */
+const MAX_REPORTED_RULES = 10;
+const MAX_REPORTED_FILES = 10;
+/**
+ * True when `<projectRoot>/.codegraph/config.json` exists, i.e. when an
+ * exclude list is actually in play here. Both consumers use this to
+ * stay SILENT on a project that never ran `peaks codegraph init`: there
+ * is no exclusion to report, and a missing config is not a finding.
+ *
+ * Note the difference from `isCodegraphInitialized` in
+ * `codegraph-service.ts`, which probes `codegraph.db` (upstream's own
+ * definition of "initialized"). The exclude list is written by upstream
+ * init, so its presence is the narrower question this module asks.
+ */
+export function isCodegraphExcludeConfigPresent(projectRoot) {
+    return existsSync(join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME));
+}
+/**
+ * Read the project's git-tracked files + `.codegraph/config.json` and
+ * fold the reconciliation into a report.
+ *
+ * Throws (never silently degrades) when the project is not a git work
+ * tree, when the config is missing, or when it is malformed — callers
+ * that must stay alive (doctor, `status`) catch and surface the reason.
+ */
+export function inspectCodegraphExcludeIntegrity(projectRoot) {
+    const result = reconcileCodegraphExcludeFromProject(projectRoot);
+    const blockedCounts = new Map();
+    for (const violation of result.violations) {
+        blockedCounts.set(violation.matchedRule, (blockedCounts.get(violation.matchedRule) ?? 0) + 1);
+    }
+    return {
+        configPath: join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME),
+        gap: result.excludedTrackedCount > 0,
+        trackedSourceCount: result.trackedSourceCount,
+        excludedTrackedCount: result.excludedTrackedCount,
+        violations: result.violations,
+        rulesToRemove: result.rulesToRemove,
+        ruleImpacts: result.rulesToRemove.map((rule) => ({ rule, blockedCount: blockedCounts.get(rule) ?? 0 }))
+    };
+}
+/**
+ * Human-readable detail lines for a gapped report: the headline count,
+ * then the offending rules, then a sample of the blocked files so an
+ * operator can point at a concrete path without re-running anything.
+ *
+ * Returns an empty array for a clean report — the caller decides
+ * whether "clean" is worth printing at all.
+ */
+export function renderCodegraphExcludeIntegrityLines(report) {
+    if (!report.gap) {
+        return [];
+    }
+    const lines = [
+        `[FAIL] codegraph index is incomplete: ${report.excludedTrackedCount} of ${report.trackedSourceCount} tracked source files are excluded by ${report.rulesToRemove.length} rule(s).`
+    ];
+    for (const impact of report.ruleImpacts.slice(0, MAX_REPORTED_RULES)) {
+        lines.push(`  rule ${impact.rule} blocks ${impact.blockedCount} tracked file(s)`);
+    }
+    if (report.ruleImpacts.length > MAX_REPORTED_RULES) {
+        lines.push(`  … and ${report.ruleImpacts.length - MAX_REPORTED_RULES} more rule(s)`);
+    }
+    for (const violation of report.violations.slice(0, MAX_REPORTED_FILES)) {
+        lines.push(`  excluded: ${violation.path} <- ${violation.matchedRule}`);
+    }
+    if (report.violations.length > MAX_REPORTED_FILES) {
+        lines.push(`  … and ${report.violations.length - MAX_REPORTED_FILES} more file/rule pair(s)`);
+    }
+    lines.push('Run `peaks codegraph repair-exclude --project <root>` to drop these rules, back up the config, and rebuild the index.');
+    return lines;
+}