peaks-loop 4.0.54 → 4.1.1

package/dist/cli/commands/code-runtime-commands.js

@@ -12,7 +12,10 @@
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { detectPostCompactResume, formatPostCompactResumeLogLine } from '../../services/code/post-compact-detector.js';
-import { runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
+import { evaluateCompactTrigger, runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
+import { thresholdFor } from '../../services/code/auto-compact-modes.js';
+import { resolveAutoCompactProfile } from '../../services/mode/mode-status-service.js';
+import { AUTO_COMPACT_SOFT_WARN_RATIO } from '../../services/context/auto-compact-types.js';
 import { auditContext } from '../../services/context/context-audit.js';
 import { syncHarnessWindowForProject } from '../../services/context/auto-compact-reader.js';
 import { describeHarnessWindowSync, harnessWindowSyncWarning } from '../../services/context/harness-window-config.js';
@@ -25,6 +28,43 @@ import { readJobShapeDecision, JobShapeDecisionError } from '../../services/code
 import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
 import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
 import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
+/** The one dispatch verb the action and red-line tiers name. */
+const COMPACT_CMD = 'peaks code auto-compact';
+/**
+ * Slice H4 (rid=h4-context-now-mode-blind) — the ONE mapping from the shared
+ * `CompactTrigger` to this command's `action` vocabulary, so the two cannot
+ * drift: the trigger is `evaluateCompactTrigger`, the same function `peaks
+ * code auto-compact` decides with.
+ *
+ * `auto-fire` maps to `soft-warn` in BOTH modes: that tier is `peaks skill
+ * presence`'s — the every-turn probe, which reads this same table and mode
+ * resolver — so `context-now` has no auto-fire tier of its own (SKILL.md
+ * "two probes, two thresholds"). Reporting it as `auto-compact-now` would
+ * change every non-24h session's output, which slice H4 forbids.
+ */
+export function contextNowActionFor(ratio, mode) {
+    const kind = evaluateCompactTrigger(ratio, mode).kind;
+    if (kind === 'red-line')
+        return { action: 'red-line', next: COMPACT_CMD };
+    if (kind === 'pre-compact')
+        return { action: 'auto-compact-now', next: COMPACT_CMD };
+    return { action: kind === 'none' ? 'ok' : 'soft-warn', next: null };
+}
+/** Slice H4: the labels `context-now` prints, read out of the table for the mode
+ *  in force — the old hard-coded "≥0.85 / ≥0.95 / 50–85%" told a 24h operator
+ *  the wrong lines. `*Ratio` is the `0.85` form `gateModeNotice` uses. */
+function contextNowBandLabels(mode) {
+    const pct = (r) => `${(r * 100).toFixed(0)}`;
+    const pre = thresholdFor(mode, 'preCompact');
+    const red = thresholdFor(mode, 'redLine');
+    return {
+        softWarn: pct(AUTO_COMPACT_SOFT_WARN_RATIO),
+        preCompact: pct(pre),
+        redLine: pct(red),
+        preCompactRatio: pre.toFixed(2),
+        redLineRatio: red.toFixed(2)
+    };
+}
 /**
  * Adapt `runAutoCompact`'s domain result to a `ResultEnvelope`.
  *
@@ -55,7 +95,14 @@ export function buildAutoCompactEnvelope(result) {
     // `fail()` hard-codes `warnings: []`, so the warning is spread back over it —
     // a refused write can disagree with the ratio just as easily on the failure
     // path, and the state does not become less true because the dispatch failed.
-    return { ...fail('code.auto-compact', result.code, result.message, data, [...nextActions]), warnings };
+    return {
+        ...fail('code.auto-compact', result.code, result.message, data, [...nextActions]),
+        warnings
+    };
+}
+function printPostCompactNoActiveSession(io, opts) {
+    printResult(io, fail('code.post-compact-detect', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
+    process.exitCode = 1;
 }
 export function registerCodeRuntimeCommands(code, io) {
     addJsonOption(code
@@ -69,8 +116,7 @@ export function registerCodeRuntimeCommands(code, io) {
         try {
             const sessionId = opts.sessionId ?? readActiveSid(opts.project);
             if (sessionId === null) {
-                printResult(io, fail('code.post-compact-detect', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
-                process.exitCode = 1;
+                printPostCompactNoActiveSession(io, opts);
                 return;
             }
             const probe = await detectPostCompactResume({
@@ -161,7 +207,7 @@ export function registerCodeRuntimeCommands(code, io) {
                             // projects.
                             const out = probeInFlightBatch({ now: new Date().toISOString(), graphs: [] });
                             return out.inFlightBatch === true;
-                        },
+                        }
                     }
                     : {}),
                 force: opts.force === true,
@@ -191,14 +237,14 @@ export function registerCodeRuntimeCommands(code, io) {
     });
     addJsonOption(code
         .command('context-now')
-        .description('v2.13.0 AC-1: read the active IDE adapter\'s context-fill % ' +
+        .description("v2.13.0 AC-1: read the active IDE adapter's context-fill % " +
         'without requiring the LLM to pass --prompt-size <bytes> manually. ' +
         'Adapter-driven (no hard-coded IDE names): Claude Code is the MVP ' +
         'implementation; trae / codex / cursor / qoder / tongyi-lingma / ' +
         'hermes / openclaw register their own env-var via IdeAdapter.compact. ' +
-        'v3.1.2 / 2026-09-12: ≥0.85 emits action=auto-compact-now ' +
-        '(MANDATORY in every mode — single-rid included) and ' +
-        '≥0.95 emits action=red-line (the installed PreToolUse hook re-runs ' +
+        "v3.1.2 / 2026-09-12: the mode's pre-compact line emits " +
+        'action=auto-compact-now (MANDATORY, single-rid included) and ' +
+        'the red line emits action=red-line (the installed PreToolUse hook re-runs ' +
         'this command on the next Bash/Task tool call; nothing is blocked). ' +
         '--enforce-job-mode only changes the reported `jobMode` label; ' +
         'the thresholds are identical. ' +
@@ -296,42 +342,30 @@ export function registerCodeRuntimeCommands(code, io) {
             });
             const witnessNotice = describeHarnessWitness(harnessWitness);
             const ratioPct = (probe.ratio * 100).toFixed(1);
-            let action = 'ok';
-            let next = null;
-            if (probe.ratio >= 0.95) {
-                action = 'red-line';
-                next = 'peaks code auto-compact';
-            }
-            else if (probe.ratio >= 0.85) {
-                // Slice 2026-09-12-compact-band-policy (defect A): the
-                // 0.85–0.95 band is MANDATORY auto-compact for single-rid
-                // sessions too. It used to be downgraded to `soft-warn` here,
-                // which contradicted this command's own help text, the
-                // `pre-compact` action from `peaks skill presence`, the
-                // peaks-code SKILL.md, and the 2026-07-27 user-calibrated
-                // threshold policy — and left an LLM that follows the "single
-                // source of truth" (`context-now`) never compacting in the
-                // zone, violating the zero-pause contract.
-                action = 'auto-compact-now';
-                next = 'peaks code auto-compact';
-            }
-            else if (probe.ratio >= 0.5) {
-                action = 'soft-warn';
-            }
-            const verdict = action === 'red-line' ? 'red-line'
-                : action === 'auto-compact-now' ? 'pre-compact'
-                    : action === 'soft-warn' ? 'soft-warn'
-                        : 'ok';
-            // Slice 2026-09-12-compact-band-policy: the two modes no longer
-            // differ in behaviour ABOVE 0.50 — both auto-fire at ≥0.85 and
-            // both red-line at ≥0.95 — so the old "advisory mode
-            // (single-rid)" notice was a lie the moment the downgrade was
-            // removed. Job mode's remaining difference is that its threshold
-            // policy is recorded up front (`job-shape.json`), which the
-            // `jobMode` field already reports. The notice now says only that.
+            // Slice H4 (rid=h4-context-now-mode-blind): ONE table, ONE mode
+            // resolver. The hard-coded ladder that used to live here (≥0.95 / ≥0.85
+            // / ≥0.5) read no mode at all, so on a 24h run (`partial` =
+            // 0.65/0.70/0.85) it answered `soft-warn` + `next: null` across
+            // [0.70, 0.85) — the band in which `peaks code auto-compact` had
+            // already decided to compact. SKILL.md calls THIS command the "single
+            // source of truth", so an LLM obeying it did nothing.
+            const compactMode = resolveAutoCompactProfile(canonicalProjectRoot);
+            const decided = contextNowActionFor(probe.ratio, compactMode);
+            const action = decided.action;
+            const next = decided.next;
+            const verdict = action === 'red-line'
+                ? 'red-line'
+                : action === 'auto-compact-now'
+                    ? 'pre-compact'
+                    : action;
+            const bands = contextNowBandLabels(compactMode);
+            // Slice H4: the text here used to claim "the two modes no longer differ
+            // in behaviour ABOVE 0.50 — both auto-fire at ≥0.85 and both red-line at
+            // ≥0.95". That was false: `partial` fires at 0.70, red-lines at 0.85.
+            // The lines now come from the table for the mode in force.
             const gateModeNotice = isJobMode
-                ? 'Job mode (job-shape.json isJob=true): the same ≥0.85 / ≥0.95 thresholds apply, and the decision is recorded in job-shape.json.'
-                : 'Single-rid mode: the same ≥0.85 / ≥0.95 thresholds apply — ≥0.85 is MANDATORY auto-compact, not advisory.';
+                ? `Job mode (job-shape.json isJob=true): the same ≥${bands.preCompactRatio} / ≥${bands.redLineRatio} thresholds apply, and the decision is recorded in job-shape.json.`
+                : `Single-rid mode: the same ≥${bands.preCompactRatio} / ≥${bands.redLineRatio} thresholds apply — ≥${bands.preCompactRatio} is MANDATORY auto-compact, not advisory.`;
             printResult(io, ok('code.context-now', {
                 ratio: probe.ratio,
                 ratioPct: `${ratioPct}%`,
@@ -366,12 +400,12 @@ export function registerCodeRuntimeCommands(code, io) {
                 ...(witnessNotice === null ? [] : [witnessNotice])
             ], [
                 action === 'red-line'
-                    ? `RED LINE: ≥ 95%. Next: \`${next}\` — peaks-loop asks the harness to compact and KEEPS WORKING (dispatch is not blocked); re-probe to confirm it landed.`
+                    ? `RED LINE: ≥ ${bands.redLine}%. Next: \`${next}\` — peaks-loop asks the harness to compact and KEEPS WORKING (dispatch is not blocked); re-probe to confirm it landed.`
                     : action === 'auto-compact-now'
-                        ? `MANDATORY auto-compact (≥85%, every mode). Code MUST call \`${next}\` WITHOUT confirmation.`
+                        ? `MANDATORY auto-compact (≥${bands.preCompact}%, every mode). Code MUST call \`${next}\` WITHOUT confirmation.`
                         : action === 'soft-warn'
-                            ? `Soft warn (50–85%). Continue working; the next \`peaks code auto-compact\` will re-check.`
-                            : `Below 50%. No action required.`,
+                            ? `Soft warn (${bands.softWarn}–${bands.preCompact}%). Continue working; the next \`peaks code auto-compact\` will re-check.`
+                            : `Below ${bands.softWarn}%. No action required.`,
                 gateModeNotice,
                 // Single wording, shared with `peaks code auto-compact` — see
                 // `describeHarnessWindowSync`.
@@ -383,7 +417,9 @@ export function registerCodeRuntimeCommands(code, io) {
                 // the same split, and note this one never asks a question.
                 ...(witnessNotice === null
                     ? []
-                    : ['Re-probe with `peaks code context-now` to confirm; this is reported, not blocking.'])
+                    : [
+                        'Re-probe with `peaks code context-now` to confirm; this is reported, not blocking.'
+                    ])
             ]), 
             // Slice 2026-09-13-auto-compact-trigger-ownership: was hard-coded
             // `true`, which made the declared `--json` flag a no-op and left the
@@ -412,10 +448,10 @@ export function registerCodeRuntimeCommands(code, io) {
     // `available:false` with a reason and NEVER sets a non-zero exit code.
     addJsonOption(code
         .command('context-audit')
-        .description('Slice 2026-09-10 Slice A: report what fills the current session\'s ' +
+        .description("Slice 2026-09-10 Slice A: report what fills the current session's " +
         'context window, grouped by tool + short input key (command line / ' +
-        'path tail / pattern), sorted by bytes. Locates the CURRENT session\'s ' +
-        'IDE transcript through the active adapter\'s ' +
+        "path tail / pattern), sorted by bytes. Locates the CURRENT session's " +
+        "IDE transcript through the active adapter's " +
         '`compact.resolveTranscriptPath` (vendor-neutral); emits total bytes, ' +
         'entry count, and the top-N groups ' +
         '(`{tool, key, bytes, pctOfTotal, count}`). Read-only and fail-soft — ' +
@@ -434,13 +470,17 @@ export function registerCodeRuntimeCommands(code, io) {
             const result = auditContext({
                 outerSessionId: outerSessionId ?? null,
                 ...(opts.top !== undefined ? { topN: opts.top } : {}),
-                ...(opts.transcript !== undefined ? { transcriptPath: opts.transcript } : {}),
+                ...(opts.transcript !== undefined ? { transcriptPath: opts.transcript } : {})
             });
             // Fail-soft contract: unavailability is DATA, not an error. The exit
             // code stays 0 so a `context-audit` call can never block a workflow.
             const nextActions = result.available
-                ? [`${result.entryCount} tool result(s) across ${result.groupCount} group(s); showing top ${result.entries.length}.`]
-                : [`context-audit unavailable: ${result.reason ?? 'unknown'} — continue without it (read-only probe).`];
+                ? [
+                    `${result.entryCount} tool result(s) across ${result.groupCount} group(s); showing top ${result.entries.length}.`
+                ]
+                : [
+                    `context-audit unavailable: ${result.reason ?? 'unknown'} — continue without it (read-only probe).`
+                ];
             printResult(io, ok('code.context-audit', { ...result }, [], nextActions), opts.json);
         }
         catch (err) {
@@ -482,9 +522,7 @@ export function registerCodeRuntimeCommands(code, io) {
                     mode: 'no-session',
                     decision: null,
                     nextSlice: null
-                }, [], [
-                    'No active session id; gate passes through (single-rid mode).'
-                ]);
+                }, [], ['No active session id; gate passes through (single-rid mode).']);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -524,10 +562,7 @@ export function registerCodeRuntimeCommands(code, io) {
                     mode: 'single',
                     decision: null,
                     nextSlice: null
-                }, [], [
-                    'job-shape.json says isJob=false; single-rid mode (gate allows).',
-                    ...hintActions
-                ]);
+                }, [], ['job-shape.json says isJob=false; single-rid mode (gate allows).', ...hintActions]);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -584,9 +619,7 @@ export function registerCodeRuntimeCommands(code, io) {
         try {
             const sessionId = opts.sessionId ?? readActiveSid(opts.project);
             if (sessionId === null) {
-                const envelope = ok('code.emit-handoff', { allow: true, mode: 'no-session' }, [], [
-                    'No active session id; gate passes through (single-rid mode).'
-                ]);
+                const envelope = ok('code.emit-handoff', { allow: true, mode: 'no-session' }, [], ['No active session id; gate passes through (single-rid mode).']);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -600,16 +633,12 @@ export function registerCodeRuntimeCommands(code, io) {
                 evalInput.forceUnderJob = true;
             const verdict = evaluateEmitHandoff(evalInput);
             if (verdict.kind === 'allow-not-job') {
-                const envelope = ok('code.emit-handoff', { allow: true, mode: 'single' }, [], [
-                    'job-shape.json says isJob=false (or absent); normal handoff allowed.'
-                ]);
+                const envelope = ok('code.emit-handoff', { allow: true, mode: 'single' }, [], ['job-shape.json says isJob=false (or absent); normal handoff allowed.']);
                 printResult(io, envelope, opts.json);
                 return;
             }
             if (verdict.kind === 'allow-done') {
-                const envelope = ok('code.emit-handoff', { allow: true, mode: 'job-done', remaining: verdict.remaining }, [], [
-                    `Job is complete (remaining=0); handoff allowed.`
-                ]);
+                const envelope = ok('code.emit-handoff', { allow: true, mode: 'job-done', remaining: verdict.remaining }, [], [`Job is complete (remaining=0); handoff allowed.`]);
                 printResult(io, envelope, opts.json);
                 return;
             }
@@ -621,7 +650,9 @@ export function registerCodeRuntimeCommands(code, io) {
                 return;
             }
             if (verdict.kind === 'block-not-initialized') {
-                const envelope = fail('code.emit-handoff', JOB_NOT_INITIALIZED, `Job ${verdict.jobId} has no state.json; peaks job init was skipped.`, { jobId: verdict.jobId }, [`Run \`peaks job init --job-id ${verdict.jobId} --slice-list <...>\` before emitting handoff.`]);
+                const envelope = fail('code.emit-handoff', JOB_NOT_INITIALIZED, `Job ${verdict.jobId} has no state.json; peaks job init was skipped.`, { jobId: verdict.jobId }, [
+                    `Run \`peaks job init --job-id ${verdict.jobId} --slice-list <...>\` before emitting handoff.`
+                ]);
                 printResult(io, envelope, opts.json);
                 process.exitCode = 1;
                 return;
@@ -656,7 +687,8 @@ function readActiveSid(projectRoot) {
             return null;
         return presence.sessionId ?? null;
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         return null;
     }
 }

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

@@ -134,9 +134,7 @@ async function runCodegraphRepairCommand(io, options, asJson, mode) {
     // 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 = [
-        report.applied ? appliedRepairNote(report) : spec.noopNote
-    ];
+    const confirmations = [report.applied ? appliedRepairNote(report) : spec.noopNote];
     if (report.applied || mode === 'index') {
         confirmations.push('Re-run `peaks codegraph status --project <root>` to confirm the gap is closed.');
     }
@@ -525,8 +523,12 @@ 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, including the exclude integrity gate')).action((options) => runCodegraphStatusCommand(io, options, options.peaksJson));
+    const codegraph = program
+        .command('codegraph')
+        .description('Run upstream codegraph commands through the Peaks launcher');
+    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('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'));
@@ -578,7 +580,10 @@ export function registerCodegraphCommands(program, io) {
             ...(options.maxDepth !== undefined ? { maxDepth: options.maxDepth } : {})
         }, options.peaksJson);
     });
-    addProjectOption(codegraph.command('context').description('Build task context with codegraph').argument('<task>', 'task text')).action(async (task, options) => {
+    addProjectOption(codegraph
+        .command('context')
+        .description('Build task context with codegraph')
+        .argument('<task>', 'task text')).action(async (task, options) => {
         await runCodegraphCommand(io, 'codegraph.context', { subcommand: 'context', project: options.project, task }, options.peaksJson);
     });
     addProjectOption(codegraph

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

@@ -113,10 +113,14 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
         indexIntegritySeverity: indexVerdict === 'gap' ? (strict ? 'error' : 'warning') : null
     };
     if (upstreamFailed) {
-        printResult(io, fail('codegraph.status', 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(upstream.stderr || upstream.stdout || `codegraph exited with code ${String(result.exitCode)}`), data, ['Check the codegraph project path before retrying']), true);
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(upstream.stderr ||
+            upstream.stdout ||
+            `codegraph exited with code ${String(result.exitCode)}`), data, ['Check the codegraph project path before retrying']), true);
     }
     else 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).`, data, ['Run `peaks codegraph repair-exclude --project <root>` to drop the offending rules and rebuild the index.']), 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).`, data, [
+            'Run `peaks codegraph repair-exclude --project <root>` to drop the offending rules and rebuild the index.'
+        ]), true);
     }
     else if (indexVerdict === 'not-evaluated') {
         // Distinct from the `ok` branch below on purpose: this axis produced

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));
+}