peaks-loop 4.1.0 → 4.1.2

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

@@ -4,19 +4,18 @@
 // `config-restore`, `init`, `affected`, plus the commander registration for
 // every codegraph subcommand.
 //
-// D1 (rid 2026-09-17-oversize-and-scale, the 800-line file-size cap) moved
 // the shared invocation runtime to `codegraph-command-runtime.ts` and the
 // `status` integrity gate to `codegraph-status-command.ts`, both verbatim.
 // This path keeps its public surface: `registerCodegraphCommands` is defined
 // here and `rewriteBareCodegraphHints` / `attributeUpstreamUpToDateLine` are
 // re-exported below, so every existing importer still resolves.
 import { InvalidArgumentError } from 'commander';
-import { statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { assertCodegraphDirContained, createCodegraphInvocation, executeCodegraphInvocation, defaultCodegraphInitGuard, resolveProjectRoot, writeCodegraphMarker, writeCodegraphAffectedContext, CodegraphInitConflictError, CODEGRAPH_DIR_NAME } from '../../services/codegraph/codegraph-service.js';
+import { resolve } from 'node:path';
+import { assertCodegraphDirContained, resolveProjectRoot, writeCodegraphAffectedContext } from '../../services/codegraph/codegraph-service.js';
 import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
-import { CODEGRAPH_CONFIG_FILENAME } from '../../services/codegraph/codegraph-exclude-reconciler.js';
+import { resolveCodegraphConfigSource } from '../../services/codegraph/codegraph-project-config.js';
 import { rollbackCodegraphConfig } from '../../services/codegraph/codegraph-config-repair-writer.js';
+import { runCodegraphInitCommand } from './codegraph-init-command.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
 import { printCodegraphFailure, runCodegraphCommand } from './codegraph-command-runtime.js';
@@ -40,31 +39,6 @@ function parsePositiveInteger(value) {
     }
     return parsed;
 }
-// " Include now admits 7 of 9 extractor-supported tracked file(s)." — printed
-// only when the ratio reports a SHORTFALL, i.e. when the repair has left
-// files the extractor supports unadmitted. That is the one reading of this
-// sentence an operator can act on.
-//
-// What this used to say, and why it was wrong: the denominator was fed from
-// the reconciler's admitted count — the NUMERATOR's own expression — so the
-// clause could only ever print "N of N", and it was gated on
-// `after > before` with a "(was N)" trailer computed by a second full glob
-// pass. A repo with 10 supported tracked files of which 5 were admitted was
-// told "5 of 5", asserting total coverage that nothing had measured. The
-// denominator is now an independent measurement (see the report field), and
-// the trailer — whose only consumer was this sentence — is gone with the
-// pass that produced it (perf: 11.73 ms of the repair entry's +14.13 ms, on
-// every automatic seam including no-ops).
-//
-// Silence when the ratio is complete is deliberate: "2 of 2" is true but
-// says nothing, and the patterns that changed are already named by the
-// caller's own sentence.
-function admittingClause(report) {
-    if (report.trackedSourceCount === 0 || report.includeAdmittedAfter >= report.trackedSourceCount) {
-        return '';
-    }
-    return ` Include now admits ${report.includeAdmittedAfter} of ${report.trackedSourceCount} extractor-supported tracked file(s).`;
-}
 const REPAIR_MODES = {
     exclude: {
         commandId: 'codegraph.repair-exclude',
@@ -80,32 +54,18 @@ const REPAIR_MODES = {
     }
 };
 // One sentence, the same shape in both modes, because both modes run the
-// same two-axis repair — only the rebuild differs.
+// same repair — only the rebuild differs.
 //
-// A1 (`2026-09-17-codegraph-msg-and-refresh`): EACH COUNT NAMES ITS OWN AXIS.
-// The previous wording ended one sentence about both axes with a single
-// "recovering N tracked source file(s)", fed by `filesRecovered` — the
-// EXCLUDE axis' counter. On this repo it printed "Added 5 include pattern(s)
-// and removed 0 exclude rule(s), recovering 0 tracked source file(s)." while
-// those 5 patterns had just admitted 31 tracked source files (30 `.mjs` + 1
-// `.cjs`): a true statement about the axis that did not move, read as a
-// verdict on the one that did. The `admittingClause` could not correct it
-// either — it is silent when the coverage ratio is complete, which is
-// exactly the state a fresh include repair produces.
-//
-// So: the include clause carries the include axis' own file delta and the
-// exclude clause carries the exclude axis' own count, and a reader cannot
-// attribute either number to the other clause. No combined total is printed,
-// because there is no honest single number here — the two axes recover
-// disjoint sets (one widens admission, the other unblocks admitted files)
-// and only the first of them is cheap enough to measure on every repair.
+// The include clause this sentence used to carry is gone with the include
+// axis (see `codegraph-exclude-repair.ts`), which also removed the reason the
+// sentence was once split in two: there is a single axis left, and its own
+// counter cannot be read as a verdict on another one.
 function appliedRepairNote(report) {
-    return (`Added ${report.includePatternsAdded.length} include pattern(s), newly admitting ${report.includeFilesRecovered} tracked source file(s), and removed ${report.rulesRemoved.length} exclude rule(s), recovering ${report.filesRecovered} tracked source file(s) that a rule had been hiding.` +
-        admittingClause(report) +
+    return (`Removed ${report.rulesRemoved.length} exclude rule(s), recovering ${report.filesRecovered} tracked source file(s) that a rule had been hiding.` +
         ` Config backed up to ${report.backupPath ?? ''}.`);
 }
 /**
- * Explicit repair path: reconcile both config axes → back up the config →
+ * Explicit repair path: reconcile the config's `exclude` rules → back it up →
  * rewrite it → 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.
@@ -141,11 +101,7 @@ async function runCodegraphRepairCommand(io, options, asJson, mode) {
     printResult(io, ok(spec.commandId, {
         applied: report.applied,
         rulesRemoved: report.rulesRemoved,
-        includePatternsAdded: report.includePatternsAdded,
         filesRecovered: report.filesRecovered,
-        includeFilesRecovered: report.includeFilesRecovered,
-        includeAdmittedAfter: report.includeAdmittedAfter,
-        trackedSourceCount: report.trackedSourceCount,
         configPath: report.configPath,
         backupPath: report.backupPath,
         reindexed: report.reindexed,
@@ -264,7 +220,9 @@ async function runCodegraphConfigRestoreCommand(io, options, asJson) {
         // into another. Called for its refusal only — the paths below stay derived
         // from the caller's canonical `projectRoot`.
         assertCodegraphDirContained(projectRoot);
-        configPath = join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME);
+        // The same resolver the repair WRITES through, so a restore puts back the
+        // file the repair replaced — not a same-named file upstream never reads.
+        configPath = resolveCodegraphConfigSource(projectRoot).configPath;
     }
     catch (error) {
         // The PRECONDITION class: nothing below this line ran, so the envelope says
@@ -313,7 +271,6 @@ async function runCodegraphConfigRestoreCommand(io, options, asJson) {
     ]), asJson);
 }
 /**
- * rid-CG-006 — init conflict guard. Resolves the project root and
  * probes `.codegraph/` for the peaks-loop marker before invoking the
  * upstream binary.
  *
@@ -324,140 +281,7 @@ async function runCodegraphConfigRestoreCommand(io, options, asJson) {
  * On a successful upstream init, write the marker so the next run
  * hits the noop branch instead of the conflict branch.
  */
-async function runCodegraphInitCommand(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.init', error, asJson);
-        return;
-    }
-    const guardOutcome = defaultCodegraphInitGuard(projectRoot);
-    if (guardOutcome.status === 'noop-already-peaks-loop') {
-        printResult(io, ok('codegraph.init', {
-            guard: guardOutcome.status,
-            codegraphDir: guardOutcome.codegraphDir,
-            markerPresent: true
-        }, 
-        // 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') {
-        const conflict = new CodegraphInitConflictError(`Refusing to init: ${guardOutcome.codegraphDir} already exists with a non-peaks-loop schema. ` +
-            'Move or rename the foreign directory, then re-run `peaks codegraph init`.', guardOutcome.codegraphDir);
-        printResult(io, fail('codegraph.init', conflict.code, conflict.message, { codegraphDir: conflict.codegraphDir }, [
-            'Move or rename the foreign .codegraph/ directory before retrying.',
-            'Or remove .codegraph/ if you are sure no other tool owns it.',
-            'Or run `peaks codegraph init --project <path> --force` once the foreign-tool safety flag ships (tracked in rid-CG-006).'
-        ]), asJson);
-        process.exitCode = conflict.exitCode;
-        return;
-    }
-    // guardOutcome.status === 'fresh' — proceed.
-    try {
-        const invocation = createCodegraphInvocation({
-            subcommand: 'init',
-            project: options.project
-        });
-        const result = await executeCodegraphInvocation(invocation);
-        const didFail = result.exitCode !== null && result.exitCode !== 0;
-        if (result.stdout.length > 0) {
-            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
-        }
-        if (result.stderr.length > 0) {
-            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
-        }
-        if (didFail) {
-            if (asJson === true) {
-                printCodegraphFailure(io, 'codegraph.init', new Error(result.stderr || result.stdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode ?? 1);
-            }
-            process.exitCode = result.exitCode ?? 1;
-            return;
-        }
-        // Upstream succeeded — stamp the marker so the next run hits the
-        // noop branch. Best-effort: a marker-write failure must NOT undo
-        // the upstream init (peaks-loop still owns the schema logically).
-        try {
-            writeCodegraphMarker(guardOutcome.codegraphDir);
-        }
-        catch {
-            // intentionally swallowed — surface as warning below
-        }
-        // Upstream `init` writes BOTH default templates: a 99-rule `exclude`
-        // list (some rules collide with real source directories in this
-        // project) and a 32-entry `include` list (which omits five extensions
-        // upstream's own extractor supports). 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, append the missing
-        // include patterns, 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 templates).
-        //
-        // Never throws: a failure here is reported as a warning, not a
-        // failed init (the init itself already succeeded).
-        const configRepair = 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 (configRepair.applied) {
-            if (configRepair.includePatternsAdded.length > 0) {
-                // A1 (2026-09-17): the include axis names its OWN file delta here too.
-                // Naming the patterns alone left the same gap the repair note had —
-                // a reader learned which extensions were appended but not how many
-                // tracked files that admitted, and this note is the ONLY place a
-                // fresh `init` reports the include repair.
-                initNotes.push(`Added ${configRepair.includePatternsAdded.length} include pattern(s) upstream's extractor supports but its default template omits, newly admitting ${configRepair.includeFilesRecovered} tracked source file(s) (${configRepair.includePatternsAdded.join(', ')}).${admittingClause(configRepair)}`);
-            }
-            if (configRepair.rulesRemoved.length > 0) {
-                initNotes.push(`Removed ${configRepair.rulesRemoved.length} exclude rule(s) that blocked tracked source files, recovering ${configRepair.filesRecovered} file(s); config backed up to ${configRepair.backupPath ?? ''}.`);
-            }
-            if (configRepair.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: configRepair.applied,
-                rulesRemoved: configRepair.rulesRemoved,
-                includePatternsAdded: configRepair.includePatternsAdded,
-                filesRecovered: configRepair.filesRecovered,
-                includeFilesRecovered: configRepair.includeFilesRecovered,
-                includeAdmittedAfter: configRepair.includeAdmittedAfter,
-                trackedSourceCount: configRepair.trackedSourceCount,
-                reindexed: configRepair.reindexed,
-                backupPath: configRepair.backupPath,
-                warning: configRepair.warning
-            }
-        }, 
-        // Verbatim: `printResult` supplies the `warning: ` prefix, so a
-        // prefix added here would render as `warning: warning: ...`.
-        configRepair.warning === null ? [] : [configRepair.warning], initNotes), asJson);
-    }
-    catch (error) {
-        printCodegraphFailure(io, 'codegraph.init', error, asJson);
-    }
-}
 /**
- * rid-CG-002 — codegraph-affected envelope write.
  *
  * Wraps the generic `runCodegraphCommand` and, after a successful
  * upstream invocation, calls `writeCodegraphAffectedContext` so the
@@ -531,14 +355,17 @@ export function registerCodegraphCommands(program, io) {
         .description('Show codegraph status, including the exclude integrity gate')).action((options) => runCodegraphStatusCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('repair-exclude')
-        .description('Normalize the codegraph include list, drop exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'exclude'));
+        .description('Drop config exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'exclude'));
     addProjectOption(codegraph
         .command('repair-index')
-        .description('Repair both codegraph config axes, then rebuild the index from scratch (drops rows for deleted files)')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'index'));
+        .description('Drop config exclude rules that block tracked source files, then rebuild the index from scratch (drops rows for deleted files)')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'index'));
     addProjectOption(codegraph
         .command('config-restore')
         .description('Restore .codegraph/config.json from the byte-exact .bak a repair left — the explicit undo of a repair')).action((options) => runCodegraphConfigRestoreCommand(io, options, options.peaksJson));
-    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph
+        .command('init')
+        .description('Initialize codegraph for a project')
+        .option('--force', 'delete a foreign (non-peaks-loop) .codegraph/ directory and initialize fresh; never follows a link and never deletes a peaks-loop-managed index')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('index')
         .description('Index a project with codegraph')

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

@@ -0,0 +1,8 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type CommonCodegraphOptions } from './codegraph-command-runtime.js';
+/** `peaks codegraph init`'s own flags. Upstream `init` takes none. */
+export interface CodegraphInitOptions extends CommonCodegraphOptions {
+    force?: boolean;
+}
+declare function runCodegraphInitCommand(io: ProgramIO, options: CodegraphInitOptions, asJson?: boolean): Promise<void>;
+export { runCodegraphInitCommand };

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

@@ -0,0 +1,162 @@
+// src/cli/commands/codegraph-init-command.ts
+//
+// `peaks codegraph init` — the guarded init action.
+//
+// What it guarantees: it never reinitializes over a directory another tool
+// owns (`--force` is the only way past that, and it refuses a link and a
+// peaks-loop-marked directory); a successful init always stamps the peaks-loop
+// marker; the config's exclude rules are reconciled before the command
+// returns; and upstream's own output reaches the reader localized, the same
+// way every other codegraph verb does.
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createCodegraphInvocation, CodegraphInitConflictError, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker } from '../../services/codegraph/codegraph-service.js';
+import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
+import { forcePastForeignConflict } from '../../services/codegraph/codegraph-foreign-removal.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { localizeUpstreamCodegraphText, printCodegraphFailure } from './codegraph-command-runtime.js';
+async function runCodegraphInitCommand(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.init', error, asJson);
+        return;
+    }
+    let guardOutcome = defaultCodegraphInitGuard(projectRoot);
+    // `--force` replaces a FOREIGN `.codegraph/` (never a link, never our own
+    // marked index — codegraph-foreign-removal.ts). Re-running the guard after
+    // the removal means everything below sees an ordinary fresh init.
+    let foreignRemoved = null;
+    if (guardOutcome.status === 'conflict-foreign-schema' && options.force === true) {
+        try {
+            const forced = forcePastForeignConflict(projectRoot);
+            foreignRemoved = forced.removed;
+            guardOutcome = forced.outcome;
+        }
+        catch (error) {
+            printCodegraphFailure(io, 'codegraph.init', error, asJson);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (guardOutcome.status === 'noop-already-peaks-loop') {
+        printResult(io, ok('codegraph.init', {
+            guard: guardOutcome.status,
+            codegraphDir: guardOutcome.codegraphDir,
+            markerPresent: true
+        }, 
+        // 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') {
+        const conflict = new CodegraphInitConflictError(`Refusing to init: ${guardOutcome.codegraphDir} already exists with a non-peaks-loop schema. ` +
+            'Move or rename the foreign directory, then re-run `peaks codegraph init`.', guardOutcome.codegraphDir);
+        printResult(io, fail('codegraph.init', conflict.code, conflict.message, { codegraphDir: conflict.codegraphDir }, [
+            'Move or rename the foreign .codegraph/ directory before retrying.',
+            'Or remove .codegraph/ if you are sure no other tool owns it.',
+            'Or run `peaks codegraph init --project <path> --force` to delete the foreign directory and initialize fresh (no backup; a link or a peaks-loop-marked directory is refused).'
+        ]), asJson);
+        process.exitCode = conflict.exitCode;
+        return;
+    }
+    // guardOutcome.status === 'fresh' — proceed.
+    try {
+        const invocation = createCodegraphInvocation({
+            subcommand: 'init',
+            project: options.project
+        });
+        const result = await executeCodegraphInvocation(invocation);
+        const didFail = result.exitCode !== null && result.exitCode !== 0;
+        // This path forwarded upstream
+        // verbatim, so the SQLite-backend advice for a dependency this project
+        // removed still reached the reader here.
+        const upstreamStdout = localizeUpstreamCodegraphText(result.stdout);
+        const upstreamStderr = localizeUpstreamCodegraphText(result.stderr);
+        if (upstreamStdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(upstreamStdout) : upstreamStdout).trimEnd());
+        }
+        if (upstreamStderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(upstreamStderr) : upstreamStderr).trimEnd());
+        }
+        if (didFail) {
+            if (asJson === true) {
+                printCodegraphFailure(io, 'codegraph.init', new Error(upstreamStderr || upstreamStdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode ?? 1);
+            }
+            process.exitCode = result.exitCode ?? 1;
+            return;
+        }
+        // Upstream succeeded — stamp the marker so the next run hits the
+        // noop branch. Best-effort: a marker-write failure must NOT undo
+        // the upstream init (peaks-loop still owns the schema logically).
+        try {
+            writeCodegraphMarker(guardOutcome.codegraphDir);
+        }
+        catch {
+            // intentionally swallowed — surface as warning below
+        }
+        // A project whose config excludes tracked source from its own index is
+        // left silently short by upstream `init`, while `status` reports the
+        // index 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 whatever the project committed).
+        //
+        // Never throws: a failure here is reported as a warning, not a
+        // failed init (the init itself already succeeded).
+        const configRepair = 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 (foreignRemoved !== null) {
+            initNotes.push(`Removed the foreign ${foreignRemoved} (--force: deleted in place, no backup was kept), then initialized a fresh peaks-loop index.`);
+        }
+        if (configRepair.applied) {
+            if (configRepair.rulesRemoved.length > 0) {
+                initNotes.push(`Removed ${configRepair.rulesRemoved.length} exclude rule(s) that blocked tracked source files, recovering ${configRepair.filesRecovered} file(s); config backed up to ${configRepair.backupPath ?? ''}.`);
+            }
+            if (configRepair.reindexed) {
+                initNotes.push('Rebuilt the codegraph index over the recovered files.');
+            }
+        }
+        printResult(io, ok('codegraph.init', {
+            guard: guardOutcome.status,
+            codegraphDir: guardOutcome.codegraphDir,
+            ...(foreignRemoved === null
+                ? {}
+                : { foreignCodegraphRemoved: foreignRemoved, foreignCodegraphBackedUp: false }),
+            markerWritten: true,
+            excludeRepair: {
+                applied: configRepair.applied,
+                rulesRemoved: configRepair.rulesRemoved,
+                filesRecovered: configRepair.filesRecovered,
+                reindexed: configRepair.reindexed,
+                backupPath: configRepair.backupPath,
+                warning: configRepair.warning
+            }
+        }, 
+        // Verbatim: `printResult` supplies the `warning: ` prefix, so a
+        // prefix added here would render as `warning: warning: ...`.
+        configRepair.warning === null ? [] : [configRepair.warning], initNotes), asJson);
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.init', error, asJson);
+    }
+}
+export { runCodegraphInitCommand };

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

@@ -5,7 +5,6 @@
 // of upstream's `[OK] Index is up to date` line.
 //
 // Extracted verbatim from `codegraph-commands.ts` (rid
-// 2026-09-17-oversize-and-scale, D1 — the 800-line file-size cap). Every moved
 // line is byte-identical and no behaviour changed; `attributeUpstreamUpToDate
 // Line` stays importable from `codegraph-commands.ts`, which re-exports it.
 import { resolve } from 'node:path';
@@ -15,7 +14,7 @@ import { CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE, CODEGRAPH_INDEX_STRICT_ENV_VAR, CO
 import { readCodegraphProjectInputs } from '../../services/codegraph/codegraph-exclude-reconciler.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
-import { printCodegraphFailure, rewriteBareCodegraphHints, runCodegraphCommand } from './codegraph-command-runtime.js';
+import { localizeUpstreamCodegraphText, printCodegraphFailure, runCodegraphCommand } from './codegraph-command-runtime.js';
 const ANSI_SGR_PATTERN = /\x1b\[[0-9;]*m/g;
 /**
  * Upstream `status` answers a different question than peaks-loop's
@@ -96,8 +95,8 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
     }
     const upstream = {
         exitCode: result.exitCode,
-        stdout: rewriteBareCodegraphHints(result.stdout).trimEnd(),
-        stderr: redactSensitiveErrorMessage(rewriteBareCodegraphHints(result.stderr)).trimEnd()
+        stdout: localizeUpstreamCodegraphText(result.stdout).trimEnd(),
+        stderr: redactSensitiveErrorMessage(localizeUpstreamCodegraphText(result.stderr)).trimEnd()
     };
     const upstreamFailed = result.exitCode !== null && result.exitCode !== 0;
     const data = {
@@ -134,12 +133,12 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
         printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_GAP', `codegraph index does not cover the repository: ${indexIntegrity?.includeGap.length ?? 0} extractor-supported tracked file(s) are not admitted by the config's include globs, and ${indexIntegrity?.deadRows.length ?? 0} index row(s) point at files that no longer exist.`, data, strict
             ? [
                 'The index must admit every extractor-supported tracked file and hold no row for a path that is gone.',
-                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to drop the blocking exclude rules and rebuild the index without the stale rows.`
             ]
             : [
                 'Advisory: this gap is reported as a warning and the command exits 0.',
                 `Set ${CODEGRAPH_INDEX_STRICT_ENV_VAR}=1 to make it blocking (exit ${CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE}).`,
-                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to drop the blocking exclude rules and rebuild the index without the stale rows.`
             ]), true);
     }
     else {

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

@@ -0,0 +1,14 @@
+/**
+ * `peaks comments` — the read side of comment hygiene.
+ *
+ * `peaks comments audit` reports which comments in the product scope assert
+ * something the repository no longer supports, and which are development
+ * narrative rather than documentation. It is read-only on purpose: the number it
+ * prints is the number a later ratchet would be seeded from, and a ceiling is
+ * only trustworthy once a human has read a list of what the rule flags.
+ *
+ * Remediation is the next slice's job, not this command's.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCommentsCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,96 @@
+/**
+ * `peaks comments` — the read side of comment hygiene.
+ *
+ * `peaks comments audit` reports which comments in the product scope assert
+ * something the repository no longer supports, and which are development
+ * narrative rather than documentation. It is read-only on purpose: the number it
+ * prints is the number a later ratchet would be seeded from, and a ceiling is
+ * only trustworthy once a human has read a list of what the rule flags.
+ *
+ * Remediation is the next slice's job, not this command's.
+ */
+import { auditComments } from '../../services/comments/comment-audit.js';
+import { pruneComments } from '../../services/comments/comment-prune.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+const KINDS = ['dead-reference', 'narrative'];
+function parseKind(value) {
+    return KINDS.find((kind) => kind === value);
+}
+function nextActions(result) {
+    const lines = [
+        `dead-reference: ${result.deadReferences} comment line(s) cite a path that resolves nowhere.`,
+        `narrative: ${result.narrative} comment line(s) are about the work, not the code.`
+    ];
+    if (result.deadReferences > 0) {
+        lines.push('Fix the citation or delete the claim — a comment that names a deleted file is an instruction to go look for it.');
+    }
+    lines.push('Worst files first: --json carries per-line records with the matched rule.');
+    return lines;
+}
+/** The `prune` action: plan, prove, and only then write. */
+function runPrune(io, options) {
+    const kind = parseKind(options.kind);
+    if (options.kind !== undefined && kind === undefined) {
+        printResult(io, fail('comments.prune', 'INVALID_KIND', `--kind must be one of: ${KINDS.join(', ')}`, { provided: options.kind }, ['Re-run with a supported --kind, or omit it for both categories.']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const result = pruneComments({
+        projectRoot: options.project ?? process.cwd(),
+        ...(kind === undefined ? {} : { kinds: [kind] }),
+        ...(options.file === undefined ? {} : { onlyFile: options.file }),
+        ...(options.apply === true ? { apply: true } : {})
+    });
+    const actions = [
+        result.applied
+            ? `Ledger: ${result.ledgerPath} records every line removed and every refusal.`
+            : 'Dry run: nothing was written. Pass --apply to write, after reading the plan.',
+        result.skipped > 0 ? `${result.skipped} finding(s) refused — see skipped reasons.` : undefined,
+        result.notWritten.length > 0 ? `Files not written: ${result.notWritten.join(', ')}` : undefined
+    ].filter((line) => line !== undefined);
+    printResult(io, ok('comments.prune', result, [], actions), options.json === true);
+}
+/** The `audit` action, named so the registration above stays a registration. */
+function runAudit(io, options) {
+    const projectRoot = options.project ?? process.cwd();
+    const kind = parseKind(options.kind);
+    if (options.kind !== undefined && kind === undefined) {
+        printResult(io, fail('comments.audit', 'INVALID_KIND', `--kind must be one of: ${KINDS.join(', ')}`, { provided: options.kind }, ['Re-run with a supported --kind, or omit it to scan both.']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const limit = options.limit === undefined ? undefined : Number.parseInt(options.limit, 10);
+        const result = auditComments({
+            projectRoot,
+            ...(kind === undefined ? {} : { kind }),
+            ...(limit === undefined || Number.isNaN(limit) ? {} : { limit })
+        });
+        printResult(io, ok('comments.audit', result, [], nextActions(result)), options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('comments.audit', 'COMMENTS_AUDIT_FAILED', getErrorMessage(error), {}, [
+            'Check --project points at a repository root.'
+        ]), options.json === true);
+        process.exitCode = 1;
+    }
+}
+export function registerCommentsCommands(program, io) {
+    const comments = program
+        .command('comments')
+        .description('Measure comment debt in product code: stale references and process narrative.');
+    addJsonOption(comments
+        .command('audit')
+        .description('Read-only scan of src/** and packages/*/src/** comments.')
+        .option('--project <path>', 'project root to scan (default: cwd)')
+        .option('--kind <kind>', `one of: ${KINDS.join(', ')}`)
+        .option('--limit <n>', 'cap the per-line findings printed (totals are never capped)')).action((options) => runAudit(io, options));
+    addJsonOption(comments
+        .command('prune')
+        .description('Remove the comment lines the scan named, and prove the diff is comment-only first. Dry run unless --apply.')
+        .option('--project <path>', 'project root to prune (default: cwd)')
+        .option('--kind <kind>', `one of: ${KINDS.join(', ')}`)
+        .option('--file <path>', 'one repo-relative file, for a narrow first run')
+        .option('--apply', 'write the files (default: plan and prove only)')).action((options) => runPrune(io, options));
+}

package/dist/cli/commands/compact-command.d.ts

@@ -1,7 +1,6 @@
 /**
  * `peaks compact *` — strategic-compact CLI primitives.
  *
- * Slice 2026-07-01-strategic-compact-cli. Five subcommands under a new
  * top-level `peaks compact` group:
  *
  *   - suggest:    PreToolUse-style two-signal suggestion (context size