peaks-loop 4.1.3 → 4.1.4

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

@@ -0,0 +1,159 @@
+// src/cli/commands/codegraph-proxy-commands.ts
+//
+// The `peaks codegraph` verbs that proxy one upstream invocation: `index`,
+// `query`, `files`, `context` and `affected`. Split out of
+// `codegraph-commands.ts`; the verb names, options and envelopes are
+// unchanged.
+import { resolve } from 'node:path';
+import { writeCodegraphAffectedContext } from '../../services/codegraph/codegraph-service.js';
+import { runCodegraphCommand } from './codegraph-command-runtime.js';
+import { addProjectOption, parsePositiveInteger } from './codegraph-command-options.js';
+/**
+ * The payload written into the codegraph-context envelope: the captured
+ * upstream stdout, parsed as JSON when `--json` asked for JSON and the text
+ * is parseable. A parse failure keeps the raw string, which the envelope
+ * renderer handles cleanly.
+ */
+function resolveAffectedPayload(json, rawStdout) {
+    if (json !== true || rawStdout.length === 0) {
+        return rawStdout;
+    }
+    try {
+        return JSON.parse(rawStdout);
+    }
+    catch {
+        return rawStdout;
+    }
+}
+/** Report the envelope write on stdout, unless `--json` owns stdout. */
+function reportAffectedEnvelope(io, envelope, asJson) {
+    if (asJson === true)
+        return;
+    io.stdout(envelope.written
+        ? `[codegraph-context] wrote ${envelope.path}\n`
+        : `[codegraph-context] skipped: ${envelope.warning}\n`);
+}
+/**
+ * Probes `.codegraph/` for the peaks-loop marker before invoking the
+ * upstream binary.
+ *
+ *   - fresh                          → proceed to upstream init
+ *   - noop-already-peaks-loop        → skip upstream, emit warning
+ *   - conflict-foreign-schema        → exit 73 + CODEGRAPH_INIT_CONFLICT envelope
+ *
+ * On a successful upstream init, write the marker so the next run
+ * hits the noop branch instead of the conflict branch.
+ *
+ * Wraps the generic `runCodegraphCommand` and, after a successful
+ * upstream invocation, calls `writeCodegraphAffectedContext` so the
+ * RD / QA handoff can pick up `.peaks/_runtime/<sid>/rd/codegraph-context.md`
+ * without re-running the (5-30 s) codegraph query.
+ *
+ * The envelope write is gated by `--write-envelope` (default off) so
+ * ad-hoc CLI invocations don't silently mutate the user's session
+ * directory. peaks-code's RD dispatch hook flips the flag on.
+ *
+ * On no-session-binding, we surface a `warning` field instead of
+ * throwing — the upstream result is still printed so the caller
+ * always sees the affected list.
+ */
+async function runCodegraphAffectedCommand(io, files, options, asJson) {
+    // Capture stdout so we can re-emit it into the envelope payload.
+    // We still forward every line to the original `io.stdout` so the
+    // user sees the affected list as if the wrapper were transparent.
+    const capturedLines = [];
+    const captureIo = {
+        stdout: (chunk) => {
+            capturedLines.push(chunk);
+            io.stdout(chunk);
+        },
+        stderr: (chunk) => io.stderr(chunk)
+    };
+    await runCodegraphCommand(captureIo, 'codegraph.affected', {
+        subcommand: 'affected',
+        project: options.project,
+        files,
+        ...(options.json === true ? { json: true } : {})
+    }, asJson);
+    if (!options.writeEnvelope) {
+        return;
+    }
+    // The user opted in via --write-envelope. Run the envelope writer
+    // unconditionally (graceful fallback when no session binding).
+    const envelope = writeCodegraphAffectedContext({
+        projectRoot: resolve(options.project),
+        rid: options.rid ?? process.env.PEAKS_RD_RID ?? 'unknown-rid',
+        files,
+        affectedPayload: resolveAffectedPayload(options.json, capturedLines.join('\n'))
+    });
+    reportAffectedEnvelope(io, envelope, asJson);
+}
+export function registerCodegraphIndexCommands(codegraph, io) {
+    addProjectOption(codegraph
+        .command('index')
+        .description('Index a project with codegraph')
+        .option('--force', 'force reindexing')
+        .option('--quiet', 'reduce upstream output')).action(async (options) => {
+        // `runCodegraphCommand` returns "upstream failed" for the one caller
+        // that ranks exit-code precedence (`status`); every other command just
+        // awaits it, so it is discarded here rather than leaked to commander.
+        await runCodegraphCommand(io, 'codegraph.index', {
+            subcommand: 'index',
+            project: options.project,
+            ...(options.force === true ? { force: true } : {}),
+            ...(options.quiet === true ? { quiet: true } : {})
+        }, options.peaksJson);
+    });
+    addProjectOption(codegraph
+        .command('query')
+        .description('Query codegraph')
+        .argument('<search>', 'search text')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--limit <n>', 'maximum result count', parsePositiveInteger)).action(async (search, options) => {
+        await runCodegraphCommand(io, 'codegraph.query', {
+            subcommand: 'query',
+            project: options.project,
+            search,
+            ...(options.json === true ? { json: true } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {})
+        }, options.peaksJson);
+    });
+}
+export function registerCodegraphFileCommands(codegraph, io) {
+    addProjectOption(codegraph
+        .command('files')
+        .description('List codegraph files')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--max-depth <n>', 'maximum traversal depth', parsePositiveInteger)).action(async (options) => {
+        await runCodegraphCommand(io, 'codegraph.files', {
+            subcommand: 'files',
+            project: options.project,
+            ...(options.json === true ? { json: true } : {}),
+            ...(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) => {
+        await runCodegraphCommand(io, 'codegraph.context', { subcommand: 'context', project: options.project, task }, options.peaksJson);
+    });
+}
+export function registerCodegraphAffectedCommand(codegraph, io) {
+    addProjectOption(codegraph
+        .command('affected')
+        .description('Find code affected by files')
+        .argument('<files...>', 'project-relative file paths')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--rid <rid>', 'request id for the codegraph-context envelope (default: env PEAKS_RD_RID or "unknown-rid")')
+        .option('--write-envelope', 'write codegraph-context.md into the active session')).action((files, options) => runCodegraphAffectedCommand(io, files, options, options.peaksJson));
+}
+/**
+ * The proxy verbs in registration order. `index` / `query` and `files` /
+ * `context` are paired because each pair shares a module-level helper set.
+ */
+export function registerCodegraphProxyCommands(codegraph, io) {
+    registerCodegraphIndexCommands(codegraph, io);
+    registerCodegraphFileCommands(codegraph, io);
+    registerCodegraphAffectedCommand(codegraph, io);
+}

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

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodegraphRepairCommands(codegraph: Command, io: ProgramIO): void;

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

@@ -0,0 +1,94 @@
+// src/cli/commands/codegraph-repair-commands.ts
+//
+// `peaks codegraph repair-exclude` and `peaks codegraph repair-index` — the
+// explicit repair path, plus the registration of both verbs. Split out of
+// `codegraph-commands.ts`; names, options and envelopes are unchanged.
+import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
+import { resolveProjectRoot } from '../../services/codegraph/codegraph-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { printCodegraphFailure } from './codegraph-command-runtime.js';
+import { addProjectOption } from './codegraph-command-options.js';
+const REPAIR_MODES = {
+    exclude: {
+        commandId: 'codegraph.repair-exclude',
+        reindex: true,
+        noopNote: 'Nothing to repair in the codegraph config; nothing was written.'
+    },
+    index: {
+        commandId: 'codegraph.repair-index',
+        // 'force' is upstream's `clear()` + full re-index — the only documented
+        // way to drop rows for files deleted in an earlier commit.
+        reindex: 'force',
+        noopNote: 'The codegraph config already admits every supported tracked file and blocks none; the index was still rebuilt from scratch.'
+    }
+};
+// One sentence, the same shape in both modes, because both modes run the
+// same repair — only the rebuild differs.
+//
+// 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 (`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 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.
+ */
+async function runCodegraphRepairCommand(io, options, asJson, mode) {
+    const spec = REPAIR_MODES[mode];
+    let projectRoot;
+    try {
+        // `resolveProjectRoot`, not a hand-rolled `resolve` + `statSync`: it is
+        // the canonicalizer every codegraph invocation already goes through
+        // (`createCodegraphInvocation`), so the config path this verb reports
+        // and writes names the SAME directory the spawn and the other verbs use
+        // even when `--project` is a symlink, a short name or a differently
+        // cased alias. The error path is unchanged.
+        projectRoot = resolveProjectRoot(options.project);
+    }
+    catch (error) {
+        printCodegraphFailure(io, spec.commandId, error, asJson);
+        return;
+    }
+    const report = await repairCodegraphExcludeFromProject(projectRoot, undefined, {
+        reindex: spec.reindex
+    });
+    // Where the notes go matters: `printResult` renders every `warnings`
+    // entry to stderr with a `warning: ` prefix, so a confirmation parked
+    // in the third slot reads as a problem — and a real warning parked
+    // there double-prefixes. Confirmations go to `nextActions`; only a
+    // genuine `report.warning` reaches `warnings`, verbatim.
+    const confirmations = [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.');
+    }
+    printResult(io, ok(spec.commandId, {
+        applied: report.applied,
+        rulesRemoved: report.rulesRemoved,
+        filesRecovered: report.filesRecovered,
+        configPath: report.configPath,
+        backupPath: report.backupPath,
+        reindexed: report.reindexed,
+        forcedRebuild: report.forcedRebuild,
+        warning: report.warning
+    }, report.warning === null ? [] : [report.warning], confirmations), asJson);
+    // A repair that could not run to completion (or could not reindex)
+    // must not report success to a shell.
+    if (report.warning !== null) {
+        process.exitCode = 1;
+    }
+}
+export function registerCodegraphRepairCommands(codegraph, io) {
+    addProjectOption(codegraph
+        .command('repair-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('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'));
+}

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

@@ -1,5 +1,5 @@
-import { type ProgramIO } from '../cli-helpers.js';
 import { type CommonCodegraphOptions } from './codegraph-command-runtime.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function attributeUpstreamUpToDateLine(stdout: string): string;
 /**
  * `peaks codegraph status` with an integrity gate.

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

@@ -4,17 +4,16 @@
 // index coverage), its `--peaks-json` machine envelope, and the attribution
 // of upstream's `[OK] Index is up to date` line.
 //
-// Extracted verbatim from `codegraph-commands.ts` (rid
-// line is byte-identical and no behaviour changed; `attributeUpstreamUpToDate
+// Extracted verbatim from `codegraph-commands.ts`; `attributeUpstreamUpToDate
 // Line` stays importable from `codegraph-commands.ts`, which re-exports it.
+// The axis evaluation lives in `codegraph-status-integrity.ts` and the
+// machine report in `codegraph-status-json.ts`.
 import { resolve } from 'node:path';
-import { createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized } from '../../services/codegraph/codegraph-service.js';
-import { CODEGRAPH_INTEGRITY_EXIT_CODE, inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent, renderCodegraphExcludeIntegrityLines } from '../../services/codegraph/codegraph-exclude-integrity.js';
-import { CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE, CODEGRAPH_INDEX_STRICT_ENV_VAR, CODEGRAPH_REPAIR_INDEX_COMMAND, codegraphIndexIntegrityExitCode, inspectCodegraphIndexIntegrity, isCodegraphIndexStrictMode, renderCodegraphIndexIntegrityLines, resolveCodegraphIndexIntegrityVerdict } from '../../services/codegraph/codegraph-index-integrity.js';
-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 { localizeUpstreamCodegraphText, printCodegraphFailure, runCodegraphCommand } from './codegraph-command-runtime.js';
+import { CODEGRAPH_INTEGRITY_EXIT_CODE } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { codegraphIndexIntegrityExitCode } from '../../services/codegraph/codegraph-index-integrity.js';
+import { runCodegraphCommand } from './codegraph-command-runtime.js';
+import { emitIntegrityText, readStatusAxes } from './codegraph-status-integrity.js';
+import { runCodegraphStatusJson } from './codegraph-status-json.js';
 const ANSI_SGR_PATTERN = /\x1b\[[0-9;]*m/g;
 /**
  * Upstream `status` answers a different question than peaks-loop's
@@ -57,97 +56,20 @@ export function attributeUpstreamUpToDateLine(stdout) {
         .join('\n');
 }
 /**
- * `--peaks-json` machine report for `status`. Carries the upstream
- * result AND the peaks-loop integrity verdict as one JSON document so a
- * CI job can gate on `data.integrity.gap` / `data.integrity.rulesToRemove`
- * without scraping human text.
- *
- * EXIT-CODE PRECEDENCE (decided here, mirrored on the human path, pinned
- * by tests on BOTH axes):
- *
- *   1. upstream failed      → upstream's exit code. Ranked FIRST because
- *      every gate's remedy assumes upstream can run, and because the
- *      gate's own branches would otherwise MASK a real command failure:
- *      under the advisory default a gap exits 0, so a "gate first" order
- *      would turn "upstream failed + gap" into exit 0 — the gate hiding a
- *      failure. The gate verdicts stay in `data` verbatim, so ranking
- *      them lower hides nothing.
- *   2. exclude gap          → 74 (`CODEGRAPH_INDEX_INCOMPLETE`).
- *   3. index not evaluated  → 76 (`CODEGRAPH_INDEX_NOT_EVALUATED`): the
- *      axis was attempted and failed, which is NOT "verified clean".
- *   4. index gap            → 75 (`CODEGRAPH_INDEX_GAP`) in strict mode,
- *      0 in the advisory default.
- *
- * The envelope still reports the finding in case 4 (`ok:false`, the same
- * `code`, plus `indexIntegritySeverity: 'warning'`) — the policy governs
- * the EXIT CODE, not whether the finding is visible. This mirrors the
- * doctor's established convention: `ok:false` + `severity:'warning'`
- * surfaces the finding without escalating the exit code.
+ * Gate precedence: exclude wins when both fire (it is the upstream cause,
+ * and repairing it also rebuilds the index the staleness axis is about).
+ * Then "not evaluated" outranks "gap", because an unmeasured axis must
+ * never be reported with the same status as a measured one. See
+ * `codegraphIndexIntegrityExitCode`.
  */
-async function runCodegraphStatusJson(io, options, integrity, integrityWarning, indexIntegrity, indexIntegrityWarning, indexVerdict, strict) {
-    let result;
-    try {
-        result = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'status', project: options.project }));
-    }
-    catch (error) {
-        printCodegraphFailure(io, 'codegraph.status', error, true);
-        return true;
-    }
-    const upstream = {
-        exitCode: result.exitCode,
-        stdout: localizeUpstreamCodegraphText(result.stdout).trimEnd(),
-        stderr: redactSensitiveErrorMessage(localizeUpstreamCodegraphText(result.stderr)).trimEnd()
-    };
-    const upstreamFailed = result.exitCode !== null && result.exitCode !== 0;
-    const data = {
-        upstream,
-        integrity,
-        integrityWarning,
-        indexIntegrity,
-        indexIntegrityWarning,
-        indexIntegrityVerdict: indexVerdict,
-        // Only meaningful where there IS a finding: a `clean` or `not-applicable`
-        // axis has no severity, and reporting `'warning'` there would read as
-        // "something was wrong but advisory".
-        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);
-    }
-    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);
-    }
-    else if (indexVerdict === 'not-evaluated') {
-        // Distinct from the `ok` branch below on purpose: this axis produced
-        // NO verdict, and the envelope must not read as "index verified".
-        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_NOT_EVALUATED', `codegraph index integrity could not be evaluated: ${indexIntegrityWarning ?? 'unknown cause'}`, data, [
-            'The index was NOT measured — this is not a statement that the index is correct.',
-            'Re-run once the cause above is resolved.'
-        ]), true);
-    }
-    else if (indexVerdict === 'gap') {
-        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 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 drop the blocking exclude rules and rebuild the index without the stale rows.`
-            ]), true);
-    }
-    else {
-        printResult(io, ok('codegraph.status', data), true);
+function applyStatusExitCode(integrityGap, indexVerdict, strict) {
+    const indexExitCode = codegraphIndexIntegrityExitCode(indexVerdict, strict);
+    if (integrityGap) {
+        process.exitCode = CODEGRAPH_INTEGRITY_EXIT_CODE;
     }
-    if (upstreamFailed) {
-        process.exitCode = result.exitCode ?? 1;
+    else if (indexExitCode !== null) {
+        process.exitCode = indexExitCode;
     }
-    return upstreamFailed;
 }
 /**
  * `peaks codegraph status` with an integrity gate.
@@ -168,135 +90,26 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
  * (fresh) or `peaks codegraph repair-exclude` (explicit).
  */
 export async function runCodegraphStatusCommand(io, options, asJson) {
-    let integrity = null;
-    let integrityWarning = null;
-    let indexIntegrity = null;
-    let indexIntegrityWarning = null;
-    const projectRoot = resolve(options.project);
-    const strict = isCodegraphIndexStrictMode();
-    // R12-1: the two axes have DIFFERENT applicability predicates, and folding
-    // them into the config's alone is how a db-present / config-absent project
-    // came to exit 0 in SILENCE — under `PEAKS_CODEGRAPH_INDEX_STRICT=1` too.
-    // "Could not evaluate" is a verdict; it may not be spelled the same way as
-    // "verified clean" merely because the read happened to be gated out.
-    //
-    //   - exclude axis: applicable iff `.codegraph/config.json` exists. The
-    //     config IS the subject of that axis, so with no config there is no
-    //     exclusion list in play — `not-applicable`, silent, as before.
-    //   - index axis: applicable iff `.codegraph/codegraph.db` exists — the
-    //     SAME predicate the doctor's `defaultProbe` uses
-    //     (`isCodegraphInitialized` in
-    //     `doctor-service/checks/codegraph-index-integrity.ts`), so the two
-    //     consumers now agree about when the axis is evaluable at all. The
-    //     index is the subject here and the config is only an INPUT it reads,
-    //     so a missing config is "could not evaluate" (exit 76, `[FAIL]`),
-    //     not "nothing to evaluate".
-    //
-    // The user's constraint holds either way: an absent config is LEGITIMATE
-    // for a project that never ran `peaks codegraph init` — with no db BOTH
-    // predicates are false and the command stays silent exactly as before.
-    const configPresent = isCodegraphExcludeConfigPresent(projectRoot);
-    const indexPresent = isCodegraphInitialized(projectRoot);
-    // The two axes are evaluated INDEPENDENTLY: an unreadable index must not
-    // blind the exclude verdict, and a malformed exclude list must not hide a
-    // stale index. Each failure degrades to its own warning.
-    if (configPresent || indexPresent) {
-        // Perf audit F1: both axes need the SAME tracked-file list and the SAME
-        // config, and reading them per-axis spawned `git ls-files` twice per
-        // command and re-ran the identical 32-glob `include` filter. Read once
-        // and hand the values to both inspectors through their deps seam.
-        let sharedInputs = null;
-        try {
-            sharedInputs = readCodegraphProjectInputs(projectRoot);
-        }
-        catch (error) {
-            // One read, two blind axes — they consume exactly these two inputs,
-            // so a failure here blinds both. Report it on both, rather than
-            // letting the second axis re-run the same failing read to find out.
-            // Each axis claims the failure only where it was applicable at all:
-            // an unreadable CONFIG is not an exclude-axis finding on a project
-            // that has no config by design.
-            if (configPresent) {
-                integrityWarning = getErrorMessage(error);
-            }
-            if (indexPresent) {
-                indexIntegrityWarning = getErrorMessage(error);
-            }
-        }
-        if (sharedInputs !== null) {
-            if (configPresent) {
-                try {
-                    integrity = inspectCodegraphExcludeIntegrity(projectRoot, sharedInputs);
-                }
-                catch (error) {
-                    integrityWarning = getErrorMessage(error);
-                }
-            }
-            // The index axis needs an index. A config without `codegraph.db` is a
-            // pre-init / dangling state, not a defect: there are no rows to be
-            // stale and nothing `include` withheld from a graph that does not exist.
-            if (indexPresent) {
-                try {
-                    indexIntegrity = inspectCodegraphIndexIntegrity(projectRoot, sharedInputs);
-                }
-                catch (error) {
-                    indexIntegrityWarning = getErrorMessage(error);
-                }
-            }
-        }
-    }
-    const indexVerdict = resolveCodegraphIndexIntegrityVerdict(indexIntegrity, indexIntegrityWarning);
-    const indexGap = indexVerdict === 'gap';
+    const axes = readStatusAxes(resolve(options.project));
+    const integrityGap = axes.integrity?.gap === true;
+    const indexGap = axes.indexVerdict === 'gap';
     if (asJson === true) {
-        const upstreamFailed = await runCodegraphStatusJson(io, options, integrity, integrityWarning, indexIntegrity, indexIntegrityWarning, indexVerdict, strict);
         // Upstream failure outranks both gates — and it already set the exit
         // code to upstream's (see `runCodegraphStatusJson`).
-        if (upstreamFailed) {
+        if (await runCodegraphStatusJson(io, options, axes))
             return;
-        }
     }
     else {
         // Only when a gate found a gap: upstream's `[OK] Index is up
         // to date` answers "consistent with the last scan", and printing it
         // unqualified right above our verdict tells the reader two opposite
         // things at once. Clean runs get no transform and stay byte-identical.
-        const upstreamFailed = await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, false, integrity?.gap === true || indexGap ? attributeUpstreamUpToDateLine : undefined);
-        if (integrityWarning !== null) {
-            io.stdout(`[WARN] codegraph exclude integrity not evaluated: ${integrityWarning}`);
-        }
-        else if (integrity !== null) {
-            for (const line of renderCodegraphExcludeIntegrityLines(integrity)) {
-                io.stdout(line);
-            }
-        }
-        if (indexVerdict === 'not-evaluated') {
-            // `[FAIL]`, in every mode, because the command exits non-zero in
-            // every mode: the axis was attempted and failed, so this is not a
-            // statement about the index. Distinct wording from the gap line so
-            // the two can never be confused.
-            io.stdout(`[FAIL] codegraph index integrity could not be evaluated (the index was NOT measured): ${indexIntegrityWarning ?? 'unknown cause'}`);
-        }
-        else if (indexIntegrity !== null) {
-            for (const line of renderCodegraphIndexIntegrityLines(indexIntegrity, strict)) {
-                io.stdout(line);
-            }
-        }
+        const upstreamFailed = await runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, false, integrityGap || indexGap ? attributeUpstreamUpToDateLine : undefined);
+        emitIntegrityText(io, axes);
         // Upstream failure outranks both gates — and it already set the exit
         // code to upstream's.
-        if (upstreamFailed) {
+        if (upstreamFailed)
             return;
-        }
-    }
-    // Gate precedence: exclude wins when both fire (it is the upstream cause,
-    // and repairing it also rebuilds the index the staleness axis is about).
-    // Then "not evaluated" outranks "gap", because an unmeasured axis must
-    // never be reported with the same status as a measured one. See
-    // `codegraphIndexIntegrityExitCode`.
-    const indexExitCode = codegraphIndexIntegrityExitCode(indexVerdict, strict);
-    if (integrity?.gap === true) {
-        process.exitCode = CODEGRAPH_INTEGRITY_EXIT_CODE;
-    }
-    else if (indexExitCode !== null) {
-        process.exitCode = indexExitCode;
     }
+    applyStatusExitCode(integrityGap, axes.indexVerdict, axes.strict);
 }

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

@@ -0,0 +1,44 @@
+import { type CodegraphExcludeIntegrityReport } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { type CodegraphIndexIntegrityReport, type CodegraphIndexIntegrityVerdict } from '../../services/codegraph/codegraph-index-integrity.js';
+import { type ProgramIO } from '../cli-helpers.js';
+/** Everything both the human and the machine branches of `status` report. */
+export type CodegraphStatusAxes = {
+    readonly integrity: CodegraphExcludeIntegrityReport | null;
+    readonly integrityWarning: string | null;
+    readonly indexIntegrity: CodegraphIndexIntegrityReport | null;
+    readonly indexIntegrityWarning: string | null;
+    readonly indexVerdict: CodegraphIndexIntegrityVerdict;
+    readonly strict: boolean;
+};
+/**
+ * Read both axes for a project root.
+ *
+ * R12-1: the two axes have DIFFERENT applicability predicates, and folding
+ * them into the config's alone is how a db-present / config-absent project
+ * came to exit 0 in SILENCE — under `PEAKS_CODEGRAPH_INDEX_STRICT=1` too.
+ * "Could not evaluate" is a verdict; it may not be spelled the same way as
+ * "verified clean" merely because the read happened to be gated out.
+ *
+ *   - exclude axis: applicable iff `.codegraph/config.json` exists. The
+ *     config IS the subject of that axis, so with no config there is no
+ *     exclusion list in play — `not-applicable`, silent, as before.
+ *   - index axis: applicable iff `.codegraph/codegraph.db` exists — the
+ *     SAME predicate the doctor's `defaultProbe` uses
+ *     (`isCodegraphInitialized` in
+ *     `doctor-service/checks/codegraph-index-integrity.ts`), so the two
+ *     consumers now agree about when the axis is evaluable at all. The
+ *     index is the subject here and the config is only an INPUT it reads,
+ *     so a missing config is "could not evaluate" (exit 76, `[FAIL]`),
+ *     not "nothing to evaluate".
+ *
+ * The user's constraint holds either way: an absent config is LEGITIMATE
+ * for a project that never ran `peaks codegraph init` — with no db BOTH
+ * predicates are false and the command stays silent exactly as before.
+ *
+ * The two axes are evaluated INDEPENDENTLY: an unreadable index must not
+ * blind the exclude verdict, and a malformed exclude list must not hide a
+ * stale index. Each failure degrades to its own warning.
+ */
+export declare function readStatusAxes(projectRoot: string): CodegraphStatusAxes;
+/** The human-readable axis report, printed only by the non-JSON branch. */
+export declare function emitIntegrityText(io: ProgramIO, axes: CodegraphStatusAxes): void;