code-auditor-mcp 4.1.0 → 5.0.1

package/dist/cli.js

@@ -7,7 +7,6 @@ import './native-bootstrap.js';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { createAuditRunner } from './auditRunner.js';
-import { runAuditDispatch } from './auditRouter.js';
 import { promises as fs } from 'fs';
 import { createInterface } from 'readline';
 import { dirname, isAbsolute, join, relative, resolve } from 'path';
@@ -23,7 +22,6 @@ import { fingerprint, buildFingerprintInput } from './fingerprint.js';
 import { buildDismissalEntry, upsertDismissal } from './dismissals.js';
 import { resolveTelemetryConfig, signatureForFinding, buildTelemetryPayload, formatTelemetryPreview, sendTelemetry, languageHint } from './telemetry.js';
 import { getInstallId } from './installConfig.js';
-import { ALL_ANALYZERS } from './analyzers/ruleRegistry.js';
 import { computeGatingDecision } from './enforcement/gate.js';
 import { BLOCKING_SEVERITIES, SEVERITIES } from './types.js';
 import { rankFilesByPriority, orderFindingsWithinFile } from './nextFile.js';
@@ -36,6 +34,18 @@ const program = new Command();
 // `--fail-on advisory` must fail loudly and name the new tier, not emit a generic
 // "must be one of" list that leaves the user guessing what `advisory` became.
 const LEGACY_SEVERITY_NAMES = { advisory: 'high' };
+// CLI option descriptions, hoisted so the 30+ subcommands' repeated
+// option() / -p,--path descriptions share one source.
+const OPTION_OUTPUT_AS_JSON = 'Output as JSON';
+const OPTION_PROJECT_PATH = 'Project path';
+const OPTION_PROJECT_ROOT_PATH = 'Project root path';
+const OPTION_PROJECT_ROOT = 'Project root';
+const OPTION_CONFIGURATION_NAME = 'Configuration name';
+const UNKNOWN_ERROR = 'Unknown error';
+// "file:line" suffix for a finding row; empty when the finding has no line.
+function lineSuffix(line) {
+    return line ? `:${line}` : '';
+}
 // Spec 44 R4 — file accounting summary line + `--explain-skipped` breakdown.
 // The full per-reason file lists live in the JSON report (`metadata.fileAccounting`);
 // the CLI preview is bounded to the first ~20 files per reason.
@@ -88,23 +98,456 @@ program
     .name('code-auditor')
     .description('TypeScript/JavaScript code quality auditor with AI tool integration')
     .version(`${PACKAGE_VERSION} (sqlite: ${describeSqliteBackend()})`);
+/**
+ * Collapse a receiver-resolution reason to a single line for the cannot-fire
+ * panel. Reasons embed the receiver text (which can span the SQL of a chained
+ * `db.prepare("...").bind(...)`), so newlines must be folded and the result
+ * truncated to stay legible in the per-file rollup.
+ */
+function sanitizeReason(reason) {
+    if (!reason)
+        return '';
+    const collapsed = reason.replace(/\s+/g, ' ').trim();
+    return collapsed.length > 220 ? `${collapsed.slice(0, 217)}…` : collapsed;
+}
+/**
+ * Print the pre-delta diagnostic panels: coverage, skipped analyzers, ignored
+ * config keys, coverage gaps, test coverage, size distributions, and dead
+ * clusters. Pure reporting over `result.metadata`.
+ */
+function printAuditDiagnostics(result) {
+    // ── Coverage panel leads the report (Spec 47 R2) ─────────────
+    const coverage = result.metadata?.coverage;
+    // Spec 69 §10 R4 — the site-level cannot-fire count (unproven DB-access
+    // receiver sites) sits beside the rule-level states, so one line reports
+    // both the per-rule verdict and the per-call-site gap the affected rules
+    // may have under-reported on.
+    const unprovenSiteCount = (result.metadata?.diagnostics ?? [])
+        .filter((d) => d.kind === 'cannot-fire' && d.analyzerName === 'schema')
+        .length;
+    if (coverage && coverage.length > 0) {
+        const covFired = coverage.filter(c => c.state === 'fired').length;
+        const covClean = coverage.filter(c => c.state === 'clean').length;
+        const covIncomplete = coverage.filter(c => c.state === 'incomplete').length;
+        const covNotApplicable = coverage.filter(c => c.state === 'notApplicable').length;
+        const covCannotFire = coverage.filter(c => c.state === 'cannot-fire').length;
+        console.log(chalk.gray(`── Coverage panel ── ${covFired} fired · ${covClean} clean · ` +
+            `${covIncomplete} incomplete · ${covNotApplicable} not-applicable · ` +
+            `${covCannotFire} cannot-fire · ${unprovenSiteCount} unproven sites`));
+    }
+    // ── Skipped analyzers (Spec 61) ──────────────────────────────
+    const skippedAnalyzers = (result.metadata?.diagnostics ?? []).filter((d) => d.kind === 'go-toolchain-missing' ||
+        d.kind === 'go-analyzer-wrong-arch' ||
+        d.kind === 'go-analyzer-build-failed');
+    if (skippedAnalyzers.length > 0) {
+        console.log(chalk.yellow(`── Skipped analyzers ── ${skippedAnalyzers.length}`));
+        for (const d of skippedAnalyzers) {
+            const name = d.analyzerName || 'go';
+            console.log(chalk.yellow(`  ${name} [${d.kind}] — ${d.message}`));
+        }
+    }
+    // ── Ignored config keys (Spec 61 R1.4) ─────────────────────────
+    const ignoredConfigKeys = (result.metadata?.diagnostics ?? []).filter((d) => d.kind === 'config-key-rejected');
+    if (ignoredConfigKeys.length > 0) {
+        console.log(chalk.yellow(`── Ignored config keys ── ${ignoredConfigKeys.length}`));
+        for (const d of ignoredConfigKeys) {
+            console.log(chalk.yellow(`  ${d.message}`));
+        }
+    }
+    // ── Cannot-fire sites (Spec 69 §10) ───────────────────────────
+    // The cannot-fire verdict surface is the release bar: every DB-access call
+    // site whose receiver could not be proven a handle must be *visible with its
+    // reason*, never capped or folded into a silent clean. Grouped by file so a
+    // reader can see exactly which files the table-reference and data-access
+    // rules may have under-reported on.
+    const allDiagnostics = result.metadata?.diagnostics ?? [];
+    const cannotFireSites = allDiagnostics.filter((d) => d.kind === 'cannot-fire');
+    if (cannotFireSites.length > 0) {
+        const byFile = new Map();
+        for (const d of cannotFireSites) {
+            const key = d.file ?? '(unknown)';
+            const entry = byFile.get(key) ?? { lines: [], reasons: new Set() };
+            if (typeof d.line === 'number')
+                entry.lines.push(d.line);
+            const rawReason = typeof d.details?.reason === 'string' ? d.details.reason : d.message;
+            const reason = sanitizeReason(rawReason);
+            if (reason)
+                entry.reasons.add(reason);
+            byFile.set(key, entry);
+        }
+        console.log(chalk.yellow(`── Cannot-fire sites ── ${cannotFireSites.length} unproven DB-access call sites across ${byFile.size} files`));
+        console.log(chalk.yellow(`   Table-reference and data-access rules may report clean on access they could not observe.`));
+        for (const [file, entry] of [...byFile.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+            const reasons = [...entry.reasons];
+            const shown = reasons.slice(0, 2).join(' │ ');
+            const more = reasons.length > 2 ? ` (+${reasons.length - 2} more reasons)` : '';
+            const loc = entry.lines.length === 1 ? ` (line ${entry.lines[0]})` : '';
+            console.log(chalk.yellow(`   ${file} — ${entry.lines.length} site(s)${loc}: ${shown}${more}`));
+        }
+    }
+    // ── Coverage gaps (Spec 58 follow-up) ─────────────────────────
+    const otherCoverageGaps = allDiagnostics.filter((d) => d.kind === 'unresolved-query' || d.kind === 'unresolved-dynamic-import' || d.kind === 'undefined-class-not-found');
+    if (otherCoverageGaps.length > 0) {
+        const byKind = {};
+        for (const d of otherCoverageGaps)
+            byKind[d.kind] = (byKind[d.kind] ?? 0) + 1;
+        const totals = Object.entries(byKind)
+            .map(([kind, n]) => `${n} ${kind}`)
+            .join(' · ');
+        console.log(chalk.gray(`── Coverage gaps ── ${totals}`));
+        for (const d of otherCoverageGaps.slice(0, 20)) {
+            const loc = d.file ? `${d.file}${typeof d.line === 'number' ? `:${d.line}` : ''}` : '(unknown)';
+            console.log(chalk.gray(`  ${loc} [${d.kind}] — ${d.message}`));
+        }
+        if (otherCoverageGaps.length > 20) {
+            console.log(chalk.gray(`  … and ${otherCoverageGaps.length - 20} more`));
+        }
+    }
+    // ── Spec 60 R1 — test coverage (reporting, not detection) ─────
+    const testCoverage = result.metadata?.testCoverage;
+    if (testCoverage) {
+        const pct = testCoverage.total > 0
+            ? ((testCoverage.tested / testCoverage.total) * 100).toFixed(1)
+            : '0.0';
+        let line = `tested ${testCoverage.tested}/${testCoverage.total} (${pct}%)` +
+            ` · untested-live ${testCoverage.untestedLive}` +
+            ` · untested-dead ${testCoverage.untestedDead}`;
+        if (testCoverage.deadDrop > 0) {
+            line += ` (was ${testCoverage.deadPreException} pre-exception; −${testCoverage.deadDrop} entry points exempted)`;
+        }
+        console.log(chalk.gray(`── Test coverage ── ${line}`));
+    }
+    // ── Spec 60 R2 — size distributions (median / p95 / max) ──────
+    const sizeDistributions = result.metadata?.sizeDistributions;
+    if (sizeDistributions && sizeDistributions.length > 0) {
+        console.log(chalk.gray(`── Size distributions ──`));
+        for (const d of sizeDistributions) {
+            const fmt = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1);
+            const tail = d.maxEntry
+                ? ` (${d.maxEntry.name}${d.maxEntry.fileType ? ` · ${d.maxEntry.fileType}` : ''} · ${d.maxEntry.entityType})`
+                : '';
+            const pop = d.population ? `${d.population}, n=${d.count}` : `n=${d.count}`;
+            console.log(chalk.gray(`  ${d.measure} [${pop}]: median ${fmt(d.median)} · p95 ${fmt(d.p95)} · max ${fmt(d.max)}${tail}`));
+        }
+    }
+    // ── Spec 60 R3 — dead-and-duplicated clusters ─────────────────
+    const deadClusters = result.metadata?.deadClusters;
+    if (deadClusters && deadClusters.length > 0) {
+        console.log(chalk.gray(`── Dead-and-duplicated ── ${deadClusters.length} clusters`));
+        for (const c of deadClusters.slice(0, 10)) {
+            console.log(chalk.gray(`  ${c.count} × ${c.basename}`));
+        }
+        if (deadClusters.length > 10) {
+            console.log(chalk.gray(`  … and ${deadClusters.length - 10} more clusters`));
+        }
+    }
+}
+/**
+ * Print the findings summary: the delta view when a baseline exists, or the
+ * absolute summary otherwise. Recomputes the dismissed/gating suffixes so the
+ * summary is self-contained.
+ */
+function printFindingSummary(result, violations, baseline, options) {
+    // Spec 57 — dismissed count is reported alongside the total, never
+    // subtracted from it ("43 findings, 3 dismissed").
+    const dismissedCount = result.summary.dismissed ?? 0;
+    const dismissedSuffix = dismissedCount > 0 ? `, ${dismissedCount} dismissed` : '';
+    const gateExcludedCount = violations.filter((v) => v.gateExcluded).length;
+    const gatingCount = (severity) => violations.filter((v) => v.severity === severity && !v.gateExcluded && !v.dismissed).length;
+    const findingsSuffix = `${dismissedSuffix}${gateExcludedCount > 0 ? ` (${gateExcludedCount.toLocaleString()} excluded from gate)` : ''}`;
+    const summaryLine = (label, total, severity) => gateExcludedCount > 0
+        ? `${label}: ${total} (${gatingCount(severity)} gating)`
+        : `${label}: ${total}`;
+    // ── Delta output (Spec 18 R2) ─────────────────────────────────
+    if (baseline && !options.full) {
+        const newViolations = violations.filter((v) => v.new === true);
+        const knownCount = baseline.knownCount ?? 0;
+        const fixedCount = baseline.fixedCount ?? 0;
+        const previousKnown = baseline.previousKnownCount ?? 0;
+        const currentDebt = newViolations.length + knownCount;
+        const debtDelta = currentDebt - previousKnown;
+        const trendIcon = debtDelta > 0 ? '↑' : debtDelta < 0 ? '↓' : '→';
+        const trendLabel = debtDelta > 0
+            ? `(debt increased since last baseline)`
+            : debtDelta < 0
+                ? `(debt decreased since last baseline)`
+                : '(unchanged)';
+        console.log(`\n📊 Delta: +${newViolations.length} new · −${fixedCount} fixed · ${knownCount} known  ${trendIcon} ${trendLabel}`);
+        if (newViolations.length > 0) {
+            console.log(chalk.gray(`\n── New readings (${newViolations.length}) ──────────────────────────`));
+            for (const v of newViolations) {
+                const icon = v.severity === 'critical' ? '🔴' :
+                    v.severity === 'severe' ? '🟠' : '🟡';
+                console.log(`${icon} ${chalk.bold(v.file)}${lineSuffix(v.line)} [${v.severity}] ${v.message}`);
+            }
+        }
+        else {
+            console.log(chalk.green('\n✓ No new readings since last baseline.'));
+            if (knownCount > 0) {
+                console.log(chalk.gray(`  ${knownCount} known reading(s) are still open — recorded, not resolved.`));
+            }
+        }
+        // Debt by analyzer
+        console.log(chalk.gray(`\n── Debt by Analyzer ──────────────────────────`));
+        const analyzerCounts = {};
+        for (const v of violations) {
+            const a = v.analyzer || 'unknown';
+            if (!analyzerCounts[a])
+                analyzerCounts[a] = { known: 0, new: 0 };
+            if (v.new === false)
+                analyzerCounts[a].known++;
+            else if (v.new === true)
+                analyzerCounts[a].new++;
+        }
+        for (const [analyzer, counts] of Object.entries(analyzerCounts).sort()) {
+            const newPart = counts.new > 0 ? ` (+${counts.new})` : '';
+            console.log(`${analyzer}: ${counts.known.toLocaleString()} known${newPart}`);
+        }
+        // Top files
+        console.log(chalk.gray(`\n── Top Files ─────────────────────────────────`));
+        const fileCounts = new Map();
+        for (const v of violations) {
+            const f = v.file || '';
+            fileCounts.set(f, (fileCounts.get(f) || 0) + 1);
+        }
+        const topFiles = [...fileCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5);
+        for (const [file, count] of topFiles) {
+            console.log(`${file} — ${count} reading${count !== 1 ? 's' : ''}`);
+        }
+        console.log(chalk.gray(`\n💡 Run ${chalk.cyan('code-audit --full')} to see all ${currentDebt.toLocaleString()} readings.`));
+    }
+    else if (!baseline) {
+        // No baseline: current behavior + hint
+        console.log(`\nFound ${result.summary.totalViolations} findings${findingsSuffix}`);
+        console.log(summaryLine('Critical', result.summary.criticalIssues, 'critical'));
+        console.log(summaryLine('Severe', result.summary.severe, 'severe'));
+        console.log(summaryLine('High', result.summary.high, 'high'));
+        console.log(chalk.gray(`\nEvery reading is a defect — severity is urgency, the order to act.`));
+        console.log(chalk.gray(`\n💡 Run ${chalk.cyan('code-audit baseline')} to adopt the ratchet and track changes over time.`));
+    }
+    else {
+        // --full with baseline: full itemized inventory (current behavior)
+        console.log(`\nFound ${result.summary.totalViolations} findings${findingsSuffix}`);
+        console.log(summaryLine('Critical', result.summary.criticalIssues, 'critical'));
+        console.log(summaryLine('Severe', result.summary.severe, 'severe'));
+        console.log(summaryLine('High', result.summary.high, 'high'));
+        console.log(chalk.gray(`\nEvery reading is a defect — severity is urgency, the order to act.`));
+    }
+}
+/**
+ * Print unparsed-file failures and skipped-extension notice.
+ */
+function printUnparsedAndSkipped(result) {
+    // Spec 32 — unparsed files are never silent.
+    const unparsedFiles = result.metadata?.unparsedFiles ?? [];
+    if (unparsedFiles.length > 0) {
+        console.error(chalk.red(`\n⚠️  ${unparsedFiles.length} file${unparsedFiles.length !== 1 ? 's' : ''} failed to parse:`));
+        for (const u of unparsedFiles.slice(0, 20)) {
+            console.error(`    ${u.filePath} — ${u.reason}`);
+        }
+        if (unparsedFiles.length > 20) {
+            console.error(`    … and ${unparsedFiles.length - 20} more`);
+        }
+    }
+    // Spec 43 R5 follow-up — extensions present on disk that discovery skipped.
+    const skippedExtensions = result.metadata?.skippedExtensions ?? [];
+    if (skippedExtensions.length > 0) {
+        console.log(chalk.gray(`\n── Not analyzed (skipped extensions) ────────`));
+        const parts = skippedExtensions.map(s => `${s.ext} (${s.count})`);
+        console.log(`  ${parts.join(', ')}`);
+    }
+}
+/**
+ * Print per-analyzer pipeline activity and the detailed coverage breakdown.
+ */
+function printPipelineStages(result, options) {
+    if (options.json)
+        return;
+    const analyzerFiles = [];
+    for (const [name, ar] of Object.entries(result.analyzerResults)) {
+        const vCount = ar.violations.length;
+        if (isVisitorStatus(ar.status)) {
+            analyzerFiles.push(`${name} [visitor-ran]: ${getFilesProcessed(ar.status)} files, ${vCount} violations`);
+        }
+        else if (isReducerStatus(ar.status)) {
+            analyzerFiles.push(`${name} [reducer-ran]: ${getFactsConsumed(ar.status)} facts, ${vCount} violations`);
+        }
+        else {
+            analyzerFiles.push(`${name} [notRun]: ${vCount} violations`);
+        }
+    }
+    if (analyzerFiles.length > 0) {
+        console.log(chalk.gray(`\n── Pipeline Stages ──────────────────────────`));
+        console.log(analyzerFiles.join('\n'));
+    }
+    // ── Coverage (Spec 27) ──────────────────────────────────────────
+    const coverage = result.metadata?.coverage;
+    if (coverage && coverage.length > 0) {
+        const fired = coverage.filter(c => c.state === 'fired');
+        const clean = coverage.filter(c => c.state === 'clean');
+        const incomplete = coverage.filter(c => c.state === 'incomplete');
+        const notApplicable = coverage.filter(c => c.state === 'notApplicable');
+        const cannotFire = coverage.filter(c => c.state === 'cannot-fire');
+        const firedCount = fired.reduce((s, c) => s + c.count, 0);
+        console.log(chalk.gray(`\n── Coverage ─────────────────────────────────`));
+        console.log(`  ${fired.length} fired (${firedCount.toLocaleString()} violations), ` +
+            `${clean.length} clean, ` +
+            `${incomplete.length} incomplete, ` +
+            `${notApplicable.length} notApplicable, ` +
+            `${cannotFire.length} cannot-fire ` +
+            `(${coverage.length} rules registered)`);
+        if (cannotFire.length > 0) {
+            console.log(chalk.yellow(`  ── Cannot Fire (broken in the tool) ──`));
+            for (const c of cannotFire) {
+                console.log(`    ${c.ruleId}: ${c.reason ?? 'unknown'}`);
+            }
+        }
+        if (notApplicable.length > 0) {
+            console.log(chalk.gray(`  ── Not Applicable ──`));
+            for (const c of notApplicable) {
+                console.log(`    ${c.ruleId}: ${c.reason ?? 'unknown'}`);
+            }
+        }
+        if (clean.length > 0) {
+            console.log(chalk.gray(`  ── Clean ──`));
+            for (const c of clean) {
+                console.log(`    ${c.ruleId} (0)`);
+            }
+        }
+        if (incomplete.length > 0) {
+            console.log(chalk.gray(`  ── Incomplete (missing facts for some files) ──`));
+            for (const c of incomplete) {
+                console.log(`    ${c.ruleId} (0)`);
+            }
+        }
+    }
+}
+/**
+ * Generate and write the formatted report when --format is specified.
+ */
+async function writeReport(result, options) {
+    if (!options.format)
+        return;
+    const validFormats = ['html', 'json', 'csv', 'sarif'];
+    if (!validFormats.includes(options.format)) {
+        console.error(chalk.red(`Unknown format: "${options.format}". Must be one of: ${validFormats.join(', ')}`));
+        process.exit(1);
+    }
+    const { generateReport } = await import('./reporting/reportGenerator.js');
+    const { readVersionControlProvenance } = await import('./reporting/sarifReportGenerator.js');
+    const rootDir = resolve(options.path || process.cwd());
+    const config = options.format === 'sarif'
+        ? { rootDir, ...readVersionControlProvenance(rootDir) }
+        : { rootDir };
+    const report = generateReport(result, options.format, config);
+    const ext = options.format === 'sarif' ? 'sarif' : options.format;
+    if (options.output) {
+        const outputDir = resolve(options.output);
+        const reportPath = join(outputDir, `audit-report.${ext}`);
+        let exists = false;
+        try {
+            await fs.access(reportPath);
+            exists = true;
+        }
+        catch { /* ok */ }
+        if (exists && !options.overwrite) {
+            console.error(chalk.red(`Refusing to overwrite existing report ${reportPath} — pass --overwrite to replace it.`));
+            process.exit(1);
+        }
+        await fs.mkdir(dirname(reportPath), { recursive: true });
+        await fs.writeFile(reportPath, report, 'utf-8');
+        console.log(chalk.green(`\nReport written to ${reportPath}`));
+    }
+    else {
+        // No output path — default to stdout.
+        process.stdout.write(report + '\n');
+    }
+}
+/**
+ * Apply the exit-code gates: fail-on-regression, zero-files, parse-failure,
+ * and --fail-on severity thresholds.
+ */
+function applyFailOnGates(result, violations, baseline, options, failOnSeverity) {
+    // --fail-on-regression: compare total high debt to baseline snapshot
+    if (baseline && options.failOnRegression) {
+        const currentDebt = violations.filter((v) => v.new || v.new === false).length;
+        const snapshotDebt = baseline.previousKnownCount ?? 0;
+        if (currentDebt > snapshotDebt) {
+            console.error(chalk.red(`Debt regression: ${currentDebt - snapshotDebt} readings added without re-baselining.`));
+            process.exit(2);
+        }
+    }
+    // Pipeline-failure gate — the audit pipeline itself threw (schema drift,
+    // DB write failure, …). One error, reported once by the runner; this exits
+    // non-zero (broken tool) so a swallowed pipeline throw can never read as a
+    // clean pass.
+    {
+        const diagnostics = result.metadata?.diagnostics ?? [];
+        const pipelineErrors = diagnostics.filter((d) => d.kind === 'pipeline-error');
+        if (pipelineErrors.length > 0) {
+            console.error(`Pipeline failure: ${pipelineErrors[0].message}`);
+            process.exit(1);
+        }
+    }
+    // Zero-files gate — any enabled analyzer matching zero source files is a
+    // dark-analyzer failure; fail the run so the bug can't hide.
+    {
+        const diagnostics = result.metadata?.diagnostics ?? [];
+        const zeroFileWarnings = diagnostics.filter((d) => d.kind === 'zero-files');
+        if (zeroFileWarnings.length > 0) {
+            const names = zeroFileWarnings.map((d) => d.analyzerName ?? d.analyzer).join(', ');
+            console.error(`Zero-files failure: ${zeroFileWarnings.length} analyzer(s) matched zero source files (${names})`);
+            process.exit(2);
+        }
+    }
+    // Spec 32 — a run where any file failed to parse is incomplete and must
+    // not exit 0.
+    {
+        const unparsedFiles = result.metadata?.unparsedFiles ?? [];
+        if (unparsedFiles.length > 0) {
+            console.error(`Parse-failure: ${unparsedFiles.length} file(s) could not be parsed; analysis is incomplete.`);
+            process.exit(2);
+        }
+    }
+    // --fail-on: evaluate new + invariant findings only (unless --include-baseline)
+    if (failOnSeverity) {
+        const evaluableViolations = (baseline && !options.includeBaseline)
+            ? violations.filter((v) => v.new || v.analyzer === 'invariants')
+            : violations;
+        const severityOrder = SEVERITIES;
+        const failIndex = severityOrder.indexOf(failOnSeverity);
+        const hasAtOrAbove = evaluableViolations.some((v) => {
+            // Spec 57 — a dismissed finding never blocks the gate.
+            if (v.dismissed)
+                return false;
+            // Spec 36 R4 — a finding from a path-profile-excluded file never blocks.
+            if (v.gateExcluded)
+                return false;
+            const vIndex = severityOrder.indexOf(v.severity);
+            return vIndex >= 0 && vIndex <= failIndex;
+        });
+        if (hasAtOrAbove) {
+            process.exit(2);
+        }
+    }
+}
 // Legacy audit command (default behavior)
 program
     .command('audit', { isDefault: true })
     .description('Run code quality audit (default command)')
     .option('-p, --path <path>', 'Path to audit', process.cwd())
-    .option('-c, --config <config>', 'Configuration name')
+    .option('-c, --config <config>', OPTION_CONFIGURATION_NAME)
     .option('-o, --output <dir>', 'Output directory for reports')
     .option('-f, --format <format>', 'Report format: html, json, csv, or sarif')
+    .option('--overwrite', 'Overwrite an existing report file at --output (default: refuse)')
     .option('--fail-on <severity>', 'Exit code 2 when violations at or above this severity exist')
     .option('--full', 'Show full violation inventory (overrides default delta view when baseline exists)')
     .option('--include-baseline', 'Evaluate baseline-known violations in --fail-on checks')
     .option('--fail-on-regression', 'Exit code 2 when total high debt exceeds the baseline snapshot')
     .option('--preset <id>', 'Apply a shareable preset (repeatable)', (v, prev) => prev.concat([v]), [])
     .option('--detach', 'Run the audit in a detached background process and print the job ID')
-    .option('--partition-strategy <strategy>', 'Partition strategy for detached runs: none, auto, or top-level')
-    .option('--max-partitions <n>', 'Maximum number of partition shards (detached runs)')
-    .option('--shard-timeout-ms <ms>', 'Per-shard timeout in milliseconds (detached runs)')
     .option('--explain-skipped', 'Print a per-reason breakdown of files dropped from analysis')
     .action(async (options) => {
     console.log(chalk.blue('🔍 Code Quality Audit Tool'));
@@ -137,302 +580,20 @@ program
                 }
             }
         }
-        const result = await runAuditDispatch({
+        const result = await createAuditRunner({
             projectRoot: options.path,
             configName: options.config,
             outputDirectory: options.output,
             presets: presetIds
-        });
+        }).run();
         const violations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
         const baseline = result.metadata?.baseline;
-        // Spec 57 — dismissed count is reported alongside the total, never
-        // subtracted from it ("43 findings, 3 dismissed").
-        const dismissedCount = result.summary.dismissed ?? 0;
-        const dismissedSuffix = dismissedCount > 0 ? `, ${dismissedCount} dismissed` : '';
-        // Spec 36 R4 — a path-profile-excluded finding reports at its real
-        // severity but never gates. When any finding is gate-excluded, surface
-        // the gating count next to the total so a clean exit doesn't read as
-        // "0 findings" beside a non-zero critical count (e.g. knex: 38 critical,
-        // all test-dir, exit 0). The excluded total still reads in full — the
-        // distinction is gating vs. reporting, never subtraction.
-        const gateExcludedCount = violations.filter((v) => v.gateExcluded).length;
-        const gatingCount = (severity) => violations.filter((v) => v.severity === severity && !v.gateExcluded && !v.dismissed).length;
-        const findingsSuffix = `${dismissedSuffix}${gateExcludedCount > 0 ? ` (${gateExcludedCount.toLocaleString()} excluded from gate)` : ''}`;
-        const summaryLine = (label, total, severity) => gateExcludedCount > 0
-            ? `${label}: ${total} (${gatingCount(severity)} gating)`
-            : `${label}: ${total}`;
-        // ── Coverage panel leads the report (Spec 47 R2) ─────────────
-        // A diagnostic report opens with what was measured before it lists any
-        // readings, so a zero-reading report can't be mistaken for a clean tree.
-        const coverage = result.metadata?.coverage;
-        if (coverage && coverage.length > 0) {
-            const covFired = coverage.filter(c => c.state === 'fired').length;
-            const covClean = coverage.filter(c => c.state === 'clean').length;
-            const covUnassessed = coverage.filter(c => c.state === 'unassessed').length;
-            const covNotApplicable = coverage.filter(c => c.state === 'notApplicable').length;
-            const covCannotFire = coverage.filter(c => c.state === 'cannot-fire').length;
-            console.log(chalk.gray(`── Coverage panel ── ${covFired} fired · ${covClean} clean · ` +
-                `${covUnassessed} unassessed · ${covNotApplicable} not-applicable · ` +
-                `${covCannotFire} cannot-fire`));
-        }
-        // ── Skipped analyzers (Spec 61) ──────────────────────────────
-        // A language present on disk but never analyzed is a stated gap, not a
-        // silent zero. The Go path surfaces a named runtime failure (missing
-        // toolchain, wrong-arch prebuilt binary, failed rebuild) as a
-        // metadata.diagnostics entry; before this section those kinds were
-        // invisible outside --json, so a polyglot repo with .go files and no Go
-        // toolchain printed zero Go findings and exited clean — the silent-zero
-        // failure mode. These lead above coverage gaps: a skipped analyzer is a
-        // whole language unmeasured, more severe than a per-file visibility gap.
-        const skippedAnalyzers = (result.metadata?.diagnostics ?? []).filter((d) => d.kind === 'go-toolchain-missing' ||
-            d.kind === 'go-analyzer-wrong-arch' ||
-            d.kind === 'go-analyzer-build-failed');
-        if (skippedAnalyzers.length > 0) {
-            console.log(chalk.yellow(`── Skipped analyzers ── ${skippedAnalyzers.length}`));
-            for (const d of skippedAnalyzers) {
-                const name = d.analyzerName || 'go';
-                console.log(chalk.yellow(`  ${name} [${d.kind}] — ${d.message}`));
-            }
-        }
-        // ── Ignored config keys (Spec 61 R1.4) ─────────────────────────
-        // Keys dropped by sanitizeProjectFileConfig: undeclared keys (like
-        // `scope`, which previously reached execSync via mergeConfig's raw-key
-        // iteration) and path keys resolving outside the project root. Surfaced
-        // so a silently-ignored config never reads as "loaded fine".
-        const ignoredConfigKeys = (result.metadata?.diagnostics ?? []).filter((d) => d.kind === 'config-key-rejected');
-        if (ignoredConfigKeys.length > 0) {
-            console.log(chalk.yellow(`── Ignored config keys ── ${ignoredConfigKeys.length}`));
-            for (const d of ignoredConfigKeys) {
-                console.log(chalk.yellow(`  ${d.message}`));
-            }
-        }
-        // ── Coverage gaps (Spec 58 follow-up) ─────────────────────────
-        // Coverage diagnostics are the analyzer saying "my visibility ends here",
-        // not "the code is wrong". They lead with counts, then per-occurrence
-        // file:line — visible and counted, never blocking (they never reach the
-        // gate). Rendered alongside the coverage panel that leads the report.
-        const coverageDiagnostics = (result.metadata?.diagnostics ?? []).filter((d) => d.kind === 'unresolved-query' || d.kind === 'unresolved-dynamic-import' || d.kind === 'undefined-class-not-found' || d.kind === 'cannot-fire');
-        if (coverageDiagnostics.length > 0) {
-            const byKind = {};
-            for (const d of coverageDiagnostics)
-                byKind[d.kind] = (byKind[d.kind] ?? 0) + 1;
-            const totals = Object.entries(byKind)
-                .map(([kind, n]) => `${n} ${kind}`)
-                .join(' · ');
-            console.log(chalk.gray(`── Coverage gaps ── ${totals}`));
-            for (const d of coverageDiagnostics.slice(0, 20)) {
-                const loc = d.file ? `${d.file}${typeof d.line === 'number' ? `:${d.line}` : ''}` : '(unknown)';
-                console.log(chalk.gray(`  ${loc} [${d.kind}] — ${d.message}`));
-            }
-            if (coverageDiagnostics.length > 20) {
-                console.log(chalk.gray(`  … and ${coverageDiagnostics.length - 20} more`));
-            }
-        }
-        // ── Spec 60 R1 — test coverage (reporting, not detection) ─────
-        // Classifies every non-test module as tested / untested-live /
-        // untested-dead off the file-level import edges. The dead count is
-        // post-entry-point-exception, with the drop attributed.
-        const testCoverage = result.metadata?.testCoverage;
-        if (testCoverage) {
-            const pct = testCoverage.total > 0
-                ? ((testCoverage.tested / testCoverage.total) * 100).toFixed(1)
-                : '0.0';
-            let line = `tested ${testCoverage.tested}/${testCoverage.total} (${pct}%)` +
-                ` · untested-live ${testCoverage.untestedLive}` +
-                ` · untested-dead ${testCoverage.untestedDead}`;
-            if (testCoverage.deadDrop > 0) {
-                line += ` (was ${testCoverage.deadPreException} pre-exception; −${testCoverage.deadDrop} entry points exempted)`;
-            }
-            console.log(chalk.gray(`── Test coverage ── ${line}`));
-        }
-        // ── Spec 60 R2 — size distributions (median / p95 / max) ──────
-        const sizeDistributions = result.metadata?.sizeDistributions;
-        if (sizeDistributions && sizeDistributions.length > 0) {
-            console.log(chalk.gray(`── Size distributions ──`));
-            for (const d of sizeDistributions) {
-                const fmt = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1);
-                const tail = d.maxEntry
-                    ? ` (${d.maxEntry.name}${d.maxEntry.fileType ? ` · ${d.maxEntry.fileType}` : ''} · ${d.maxEntry.entityType})`
-                    : '';
-                const pop = d.population ? `${d.population}, n=${d.count}` : `n=${d.count}`;
-                console.log(chalk.gray(`  ${d.measure} [${pop}]: median ${fmt(d.median)} · p95 ${fmt(d.p95)} · max ${fmt(d.max)}${tail}`));
-            }
-        }
-        // ── Spec 60 R3 — dead-and-duplicated clusters ─────────────────
-        const deadClusters = result.metadata?.deadClusters;
-        if (deadClusters && deadClusters.length > 0) {
-            console.log(chalk.gray(`── Dead-and-duplicated ── ${deadClusters.length} clusters`));
-            for (const c of deadClusters.slice(0, 10)) {
-                console.log(chalk.gray(`  ${c.count} × ${c.basename}`));
-            }
-            if (deadClusters.length > 10) {
-                console.log(chalk.gray(`  … and ${deadClusters.length - 10} more clusters`));
-            }
-        }
-        // ── Delta output (Spec 18 R2) ─────────────────────────────────
-        if (baseline && !options.full) {
-            const newViolations = violations.filter((v) => v.new === true);
-            const knownCount = baseline.knownCount ?? 0;
-            const fixedCount = baseline.fixedCount ?? 0;
-            const previousKnown = baseline.previousKnownCount ?? 0;
-            const currentDebt = newViolations.length + knownCount;
-            const debtDelta = currentDebt - previousKnown;
-            const trendIcon = debtDelta > 0 ? '↑' : debtDelta < 0 ? '↓' : '→';
-            const trendLabel = debtDelta > 0
-                ? `(debt increased since last baseline)`
-                : debtDelta < 0
-                    ? `(debt decreased since last baseline)`
-                    : '(unchanged)';
-            console.log(`\n📊 Delta: +${newViolations.length} new · −${fixedCount} fixed · ${knownCount} known  ${trendIcon} ${trendLabel}`);
-            if (newViolations.length > 0) {
-                console.log(chalk.gray(`\n── New readings (${newViolations.length}) ──────────────────────────`));
-                for (const v of newViolations) {
-                    const icon = v.severity === 'critical' ? '🔴' :
-                        v.severity === 'severe' ? '🟠' : '🟡';
-                    console.log(`${icon} ${chalk.bold(v.file)}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.message}`);
-                }
-            }
-            else {
-                console.log(chalk.green('\n✓ No new readings since last baseline.'));
-                if (knownCount > 0) {
-                    console.log(chalk.gray(`  ${knownCount} known reading(s) are still open — recorded, not resolved.`));
-                }
-            }
-            // Debt by analyzer
-            console.log(chalk.gray(`\n── Debt by Analyzer ──────────────────────────`));
-            const analyzerCounts = {};
-            for (const v of violations) {
-                const a = v.analyzer || 'unknown';
-                if (!analyzerCounts[a])
-                    analyzerCounts[a] = { known: 0, new: 0 };
-                if (v.new === false)
-                    analyzerCounts[a].known++;
-                else if (v.new === true)
-                    analyzerCounts[a].new++;
-            }
-            for (const [analyzer, counts] of Object.entries(analyzerCounts).sort()) {
-                const newPart = counts.new > 0 ? ` (+${counts.new})` : '';
-                console.log(`${analyzer}: ${counts.known.toLocaleString()} known${newPart}`);
-            }
-            // Top files
-            console.log(chalk.gray(`\n── Top Files ─────────────────────────────────`));
-            const fileCounts = new Map();
-            for (const v of violations) {
-                const f = v.file || '';
-                fileCounts.set(f, (fileCounts.get(f) || 0) + 1);
-            }
-            const topFiles = [...fileCounts.entries()]
-                .sort((a, b) => b[1] - a[1])
-                .slice(0, 5);
-            for (const [file, count] of topFiles) {
-                console.log(`${file} — ${count} reading${count !== 1 ? 's' : ''}`);
-            }
-            console.log(chalk.gray(`\n💡 Run ${chalk.cyan('code-audit --full')} to see all ${currentDebt.toLocaleString()} readings.`));
-        }
-        else if (!baseline) {
-            // No baseline: current behavior + hint
-            console.log(`\nFound ${result.summary.totalViolations} findings${findingsSuffix}`);
-            console.log(summaryLine('Critical', result.summary.criticalIssues, 'critical'));
-            console.log(summaryLine('Severe', result.summary.severe, 'severe'));
-            console.log(summaryLine('High', result.summary.high, 'high'));
-            console.log(chalk.gray(`\nEvery reading is a defect — severity is urgency, the order to act.`));
-            console.log(chalk.gray(`\n💡 Run ${chalk.cyan('code-audit baseline')} to adopt the ratchet and track changes over time.`));
-        }
-        else {
-            // --full with baseline: full itemized inventory (current behavior)
-            console.log(`\nFound ${result.summary.totalViolations} findings${findingsSuffix}`);
-            console.log(summaryLine('Critical', result.summary.criticalIssues, 'critical'));
-            console.log(summaryLine('Severe', result.summary.severe, 'severe'));
-            console.log(summaryLine('High', result.summary.high, 'high'));
-            console.log(chalk.gray(`\nEvery reading is a defect — severity is urgency, the order to act.`));
-        }
+        printAuditDiagnostics(result);
+        printFindingSummary(result, violations, baseline, options);
         // Spec 44 R4 — file accounting: analyzed/dropped totals + optional breakdown.
         printFileAccounting(result, !!options.explainSkipped);
-        // Spec 32 — unparsed files are never silent. A run where any file failed
-        // to parse (WASM abort, read error, …) must surface the count + reasons.
-        const unparsedFiles = result.metadata?.unparsedFiles ?? [];
-        if (unparsedFiles.length > 0) {
-            console.error(chalk.red(`\n⚠️  ${unparsedFiles.length} file${unparsedFiles.length !== 1 ? 's' : ''} failed to parse:`));
-            for (const u of unparsedFiles.slice(0, 20)) {
-                console.error(`    ${u.filePath} — ${u.reason}`);
-            }
-            if (unparsedFiles.length > 20) {
-                console.error(`    … and ${unparsedFiles.length - 20} more`);
-            }
-        }
-        // Spec 43 R5 follow-up — extensions present on disk that discovery skipped.
-        // Informational: surfaces "what isn't being analyzed here" so an unlisted
-        // extension (e.g. `.mdx`) never vanishes silently at discovery. Not an
-        // error — a skipped extension is not necessarily a defect (`.md`/`.svg`
-        // are legitimately not source), unlike `unparsedFiles` above.
-        const skippedExtensions = result.metadata?.skippedExtensions ?? [];
-        if (skippedExtensions.length > 0) {
-            console.log(chalk.gray(`\n── Not analyzed (skipped extensions) ────────`));
-            const parts = skippedExtensions.map(s => `${s.ext} (${s.count})`);
-            console.log(`  ${parts.join(', ')}`);
-        }
-        // Per-analyzer activity (read from result data, not serialized summary)
-        // — surfaces zero-scan failures that would otherwise be invisible.
-        if (!options.json) {
-            const analyzerFiles = [];
-            for (const [name, ar] of Object.entries(result.analyzerResults)) {
-                const vCount = ar.violations.length;
-                if (isVisitorStatus(ar.status)) {
-                    analyzerFiles.push(`${name} [visitor-ran]: ${getFilesProcessed(ar.status)} files, ${vCount} violations`);
-                }
-                else if (isReducerStatus(ar.status)) {
-                    analyzerFiles.push(`${name} [reducer-ran]: ${getFactsConsumed(ar.status)} facts, ${vCount} violations`);
-                }
-                else {
-                    analyzerFiles.push(`${name} [notRun]: ${vCount} violations`);
-                }
-            }
-            if (analyzerFiles.length > 0) {
-                console.log(chalk.gray(`\n── Pipeline Stages ──────────────────────────`));
-                console.log(analyzerFiles.join('\n'));
-            }
-            // ── Coverage (Spec 27) ──────────────────────────────────────────
-            const coverage = result.metadata?.coverage;
-            if (coverage && coverage.length > 0) {
-                const fired = coverage.filter(c => c.state === 'fired');
-                const clean = coverage.filter(c => c.state === 'clean');
-                const unassessed = coverage.filter(c => c.state === 'unassessed');
-                const notApplicable = coverage.filter(c => c.state === 'notApplicable');
-                const cannotFire = coverage.filter(c => c.state === 'cannot-fire');
-                const firedCount = fired.reduce((s, c) => s + c.count, 0);
-                console.log(chalk.gray(`\n── Coverage ─────────────────────────────────`));
-                console.log(`  ${fired.length} fired (${firedCount.toLocaleString()} violations), ` +
-                    `${clean.length} clean, ` +
-                    `${unassessed.length} unassessed, ` +
-                    `${notApplicable.length} notApplicable, ` +
-                    `${cannotFire.length} cannot-fire ` +
-                    `(${coverage.length} rules registered)`);
-                if (cannotFire.length > 0) {
-                    console.log(chalk.yellow(`  ── Cannot Fire (broken in the tool) ──`));
-                    for (const c of cannotFire) {
-                        console.log(`    ${c.ruleId}: ${c.reason ?? 'unknown'}`);
-                    }
-                }
-                if (notApplicable.length > 0) {
-                    console.log(chalk.gray(`  ── Not Applicable ──`));
-                    for (const c of notApplicable) {
-                        console.log(`    ${c.ruleId}: ${c.reason ?? 'unknown'}`);
-                    }
-                }
-                if (clean.length > 0) {
-                    console.log(chalk.gray(`  ── Clean ──`));
-                    for (const c of clean) {
-                        console.log(`    ${c.ruleId} (0)`);
-                    }
-                }
-                if (unassessed.length > 0) {
-                    console.log(chalk.gray(`  ── Unassessed (zero readings, applicability unknown) ──`));
-                    for (const c of unassessed) {
-                        console.log(`    ${c.ruleId} (0)`);
-                    }
-                }
-            }
-        }
+        printUnparsedAndSkipped(result);
+        printPipelineStages(result, options);
         // Spec-20 R4: built-in profile visibility — silent behavior changes
         // are never acceptable. Notify when scripts-and-tests excludes findings
         // from the blocking gate.
@@ -442,82 +603,8 @@ program
             console.log(chalk.blue(`\nℹ️  ${builtinCapped.toLocaleString()} readings excluded from the blocking gate by built-in profile "scripts-and-tests" (scripts/tests/fixtures).`));
             console.log(chalk.gray(`   Set ${chalk.cyan('"builtin": false')} in .codeauditor.json to disable.`));
         }
-        // Generate formatted report if --format is specified
-        if (options.format) {
-            const validFormats = ['html', 'json', 'csv', 'sarif'];
-            if (!validFormats.includes(options.format)) {
-                console.error(chalk.red(`Unknown format: "${options.format}". Must be one of: ${validFormats.join(', ')}`));
-                process.exit(1);
-            }
-            const { generateReport } = await import('./reporting/reportGenerator.js');
-            const { readVersionControlProvenance } = await import('./reporting/sarifReportGenerator.js');
-            const rootDir = resolve(options.path || process.cwd());
-            const config = options.format === 'sarif'
-                ? { rootDir, ...readVersionControlProvenance(rootDir) }
-                : { rootDir };
-            const report = generateReport(result, options.format, config);
-            const outputDir = options.output || process.cwd();
-            const ext = options.format === 'sarif' ? 'sarif' : options.format;
-            const reportPath = join(outputDir, `audit-report.${ext}`);
-            await fs.mkdir(dirname(reportPath), { recursive: true });
-            await fs.writeFile(reportPath, report, 'utf-8');
-            console.log(chalk.green(`\nReport written to ${reportPath}`));
-        }
-        // ── Fail-on logic (Spec 18 R3) ───────────────────────────────
-        // --fail-on-regression: compare total high debt to baseline snapshot
-        if (baseline && options.failOnRegression) {
-            const currentDebt = violations.filter((v) => v.new || v.new === false).length;
-            const snapshotDebt = baseline.previousKnownCount ?? 0;
-            if (currentDebt > snapshotDebt) {
-                console.error(chalk.red(`Debt regression: ${currentDebt - snapshotDebt} readings added without re-baselining.`));
-                process.exit(2);
-            }
-        }
-        // Zero-files gate — any enabled analyzer matching zero source files is a
-        // dark-analyzer failure; fail the run so the bug can't hide.
-        {
-            const diagnostics = result.metadata?.diagnostics ?? [];
-            const zeroFileWarnings = diagnostics.filter((d) => d.kind === 'zero-files');
-            if (zeroFileWarnings.length > 0) {
-                const names = zeroFileWarnings.map((d) => d.analyzerName ?? d.analyzer).join(', ');
-                console.error(`Zero-files failure: ${zeroFileWarnings.length} analyzer(s) matched zero source files (${names})`);
-                process.exit(2);
-            }
-        }
-        // Spec 32 — a run where any file failed to parse is incomplete and must
-        // not exit 0. This mirrors the zero-files gate: a silent dark-analyzer
-        // failure at file granularity is a hard failure.
-        {
-            const unparsedFiles = result.metadata?.unparsedFiles ?? [];
-            if (unparsedFiles.length > 0) {
-                console.error(`Parse-failure: ${unparsedFiles.length} file(s) could not be parsed; analysis is incomplete.`);
-                process.exit(2);
-            }
-        }
-        // --fail-on: evaluate new + invariant findings only (unless --include-baseline)
-        if (failOnSeverity) {
-            const evaluableViolations = (baseline && !options.includeBaseline)
-                ? violations.filter((v) => v.new || v.analyzer === 'invariants')
-                : violations;
-            const severityOrder = SEVERITIES;
-            const failIndex = severityOrder.indexOf(failOnSeverity);
-            const hasAtOrAbove = evaluableViolations.some((v) => {
-                // Spec 57 — a dismissed finding never blocks the gate.
-                if (v.dismissed)
-                    return false;
-                // Spec 36 R4 — a finding from a path-profile-excluded file (e.g. a
-                // test/script under "scripts-and-tests") never blocks the gate,
-                // whatever its severity. The file is doing its job; a hardcoded
-                // connection string in a stress-test script is not a defect to block on.
-                if (v.gateExcluded)
-                    return false;
-                const vIndex = severityOrder.indexOf(v.severity);
-                return vIndex >= 0 && vIndex <= failIndex;
-            });
-            if (hasAtOrAbove) {
-                process.exit(2);
-            }
-        }
+        await writeReport(result, options);
+        applyFailOnGates(result, violations, baseline, options, failOnSeverity);
     }
     catch (error) {
         console.error(chalk.red('Error:'), error);
@@ -534,7 +621,7 @@ program
     .option('--fail-on-zero-files', 'Exit code 2 when any enabled analyzer matches zero source files', true)
     .option('--stdin', 'Read file paths from stdin (one per line)')
     .option('--explain-skipped', 'Print a per-reason breakdown of files dropped from analysis')
-    .option('-p, --path <projectPath>', 'Project root path', process.cwd())
+    .option('-p, --path <projectPath>', OPTION_PROJECT_ROOT_PATH, process.cwd())
     .action(async (paths, options) => {
     try {
         const fileSet = new Set();
@@ -570,11 +657,17 @@ program
         // the gate never misses a finding. SARIF needs full run metadata, so it
         // always runs in-process.
         const projectRoot = resolve(options.path || process.cwd());
+        const hookMode = process.env.CODE_AUDITOR_HOOK === '1' || process.env.CODE_AUDITOR_HOOK === 'true';
         let result;
         if (resolvedPaths.length > 0 && options.format !== 'sarif') {
-            const { resolveDaemon, readDaemonDiagnostics } = await import('./daemon/resolve.js');
+            const { resolveDaemon, readDaemonDiagnostics, startDaemonDetached } = await import('./daemon/resolve.js');
             const daemon = await resolveDaemon(projectRoot);
             if (daemon.mode === 'not-ready') {
+                // Hook mode (Spec 68 §hook-contract): never block the edit on an audit the
+                // daemon can't serve yet — it is still indexing, and the finding arrives on
+                // a later edit. Say nothing, exit clean. A non-hook caller gets the status.
+                if (hookMode)
+                    process.exit(0);
                 reportDaemonIndexing(daemon.state, !!options.json);
                 return;
             }
@@ -583,14 +676,27 @@ program
                 if (diag && diag.status === 'ready' && diag.staleFiles.length === 0) {
                     result = await buildChangedResultFromDiagnostics(diag.diagnostics, projectRoot);
                 }
+                else if (hookMode) {
+                    // A just-edited file whose re-audit hasn't landed is not trustworthy from
+                    // cache. Report nothing; the finding arrives on the next edit.
+                    process.exit(0);
+                }
+            }
+            else if (hookMode) {
+                // No daemon: enqueue by starting one detached, then exit. The hook reads
+                // results from the daemon's cache on later edits — it never computes them.
+                startDaemonDetached(projectRoot);
+                process.exit(0);
             }
         }
         if (!result) {
+            // Hook mode never falls back to an in-process audit (Spec 68 §hook-contract).
+            if (hookMode)
+                process.exit(0);
             await initParsers();
             const runner = createAuditRunner({
                 projectRoot: options.path,
                 scope,
-                analyzerConcurrency: 4
             });
             result = await runner.run();
         }
@@ -599,7 +705,7 @@ program
         // Spec 57 — dismissed count is reported alongside the total, never
         // subtracted from it. The hook surface (`changed`) is agent-facing, so it
         // must show the same "N findings, M dismissed" figure as the full report.
-        const dismissedCount = result.summary.dismissed ?? 0;
+        const dismissedCount = result.summary?.dismissed ?? 0;
         // Blocking gate decision (Spec 45 R1/R4, Spec 54 R3), computed once so the
         // agent-facing before/after count (Spec 45 A2) and the exit code agree on
         // the same number. Every registered rule participates (R1); enforcement is
@@ -607,98 +713,21 @@ program
         // {critical, severe, high} — every finding is a defect and every finding
         // blocks; there is no configurable gate.
         const { blocking, resolutionGaps } = computeGatingDecision(violations, BLOCKING_SEVERITIES);
-        // JSON output
-        if (options.format === 'sarif') {
-            const { generateSARIFReport, readVersionControlProvenance } = await import('./reporting/sarifReportGenerator.js');
-            const projectDir = resolve(options.path || process.cwd());
-            const sarifOutput = generateSARIFReport(result, { rootDir: projectDir, ...readVersionControlProvenance(projectDir) });
-            process.stdout.write(sarifOutput + '\n');
-        }
-        else if (options.json) {
-            const projectDir = resolve(options.path || process.cwd());
-            const jsonViolations = violations.map((v) => {
-                // Compute relative path if file resolves inside the project
-                let filePath = v.file || '';
-                if (filePath.startsWith('/') || filePath.startsWith('\\\\')) {
-                    const rel = relative(projectDir, filePath);
-                    // Only use relative path if it doesn't escape the project
-                    if (!rel.startsWith('..') && !isAbsolute(rel)) {
-                        filePath = rel;
-                    }
-                }
-                // Find column: prefer explicit column, then start.column, then default to 1
-                const col = v.column ?? v.start?.column ?? 1;
-                return {
-                    analyzer: v.analyzer || '',
-                    rule: v.rule,
-                    severity: v.severity,
-                    message: v.message,
-                    file: filePath,
-                    line: v.line ?? v.start?.line,
-                    column: col,
-                    endLine: v.end?.line,
-                    endColumn: v.end?.column,
-                    enclosingSymbol: v.symbol || v.enclosingFunction || '',
-                    suggestion: v.suggestion || '',
-                    details: v.details || '',
-                    ...(v.new !== undefined && { new: v.new }),
-                    ...(v.dismissed !== undefined && { dismissed: v.dismissed }),
-                    fingerprint: fingerprint(buildFingerprintInput(v))
-                };
-            });
-            // Coverage diagnostics ride alongside violations so an agent sees "the
-            // analyzer couldn't resolve this" without a metadata flag — and without
-            // it ever gating (diagnostics never reach computeGatingDecision).
-            const jsonDiagnostics = (result.metadata?.diagnostics ?? []).map((d) => ({
-                analyzer: d.analyzerName ?? d.analyzer ?? '',
-                kind: d.kind,
-                message: d.message,
-                ...(d.file ? { file: d.file } : {}),
-                ...(typeof d.line === 'number' ? { line: d.line } : {}),
-                ...(d.details ? { details: d.details } : {}),
-            }));
-            const jsonOutput = { violations: jsonViolations, diagnostics: jsonDiagnostics };
-            process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
-        }
-        else if (!options.quiet || violations.length > 0) {
-            // Console output — Spec 45 A2: agent-facing output emits counts (per
-            // analyzer/rule/severity, plus the before/after gate figure) alongside
-            // findings. The hook and the `changed` command are the agent's surface.
-            console.log(chalk.blue('🔍 Diff-Scoped Code Audit'));
-            console.log(chalk.gray('══════════════════════════════════════════════════'));
-            printFileAccounting(result, !!options.explainSkipped);
-            if (violations.length > 0) {
-                console.log('');
-                printCountSummary(violations);
-                console.log(chalk.bold(`gate before/after: ${violations.length} → ${blocking.length} blocking`));
-                if (dismissedCount > 0) {
-                    console.log(chalk.dim(`  ${dismissedCount} dismissed — still counted above, excluded from the gate`));
-                }
-                console.log(chalk.gray('── Violations ────────────────────────────────────'));
-                for (const v of violations) {
-                    const icon = v.severity === 'critical' ? '🔴' :
-                        v.severity === 'severe' ? '🟠' : '🟡';
-                    const statusTag = v.new === false
-                        ? chalk.dim(' [known — still open]')
-                        : '';
-                    const dismissedTag = v.dismissed
-                        ? chalk.dim(' [dismissed]')
-                        : '';
-                    console.log(`${icon} ${chalk.bold(v.file)}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.message}${statusTag}${dismissedTag}`);
-                }
-            }
-            else {
-                console.log(chalk.green('\n✓ No readings.'));
-            }
-        }
-        // Spec 38 R2/R3 — per-rule timing + gate wall-clock, opt-in by env var.
+        await emitChangedOutput(result, violations, blocking, dismissedCount, options);
+        // Spec 38 R2/R3 — per-rule timing + gate cpu-time, opt-in by env var.
         // Emitted to stderr so it never corrupts --json stdout. Slowest rule first.
+        // The gate metric is CPU time (auditCpuMs), not wall clock: the budget is
+        // about a slow *rule*, and CPU time isolates that from a slow machine.
         if (process.env.CODE_AUDIT_RULE_TIMING === '1') {
             const ruleTiming = result.metadata?.ruleTiming;
-            const gateMs = result.metadata?.auditDuration;
+            const gateMs = result.metadata?.auditCpuMs;
+            const gateWallMs = result.metadata?.auditDuration;
             const lines = [];
             lines.push('');
-            lines.push(`⏱  gate wall-clock: ${(gateMs ?? 0).toFixed(1)} ms (budget 300 ms)`);
+            // §16 criterion 16 — report both wall-clock (what the hook's user feels)
+            // and CPU (what the rule actually burned); the budget asserts on CPU.
+            lines.push(`⏱  gate wall-clock: ${(gateWallMs ?? 0).toFixed(1)} ms`);
+            lines.push(`⏱  gate cpu-time: ${(gateMs ?? 0).toFixed(1)} ms (budget 400 ms)`);
             lines.push('── per-rule timing (slowest first) ──');
             if (ruleTiming && ruleTiming.length > 0) {
                 for (const t of ruleTiming) {
@@ -731,6 +760,17 @@ program
                 process.exit(2);
             }
         }
+        // Pipeline-failure gate — the audit pipeline itself threw. One error,
+        // reported once by the runner; exit non-zero (broken tool) so a swallowed
+        // pipeline throw can never read as a clean pass.
+        {
+            const diagnostics = result.metadata?.diagnostics ?? [];
+            const pipelineErrors = diagnostics.filter((d) => d.kind === 'pipeline-error');
+            if (pipelineErrors.length > 0) {
+                console.error(`Pipeline failure: ${pipelineErrors[0].message}`);
+                process.exit(1);
+            }
+        }
         // Exit code based on --no-fail-on-zero-files (default-on in v3.4.8)
         // Any enabled analyzer matching zero source files is a failure — a >50%
         // threshold lets the exact bug (3/9 analyzers dark) pass silently.
@@ -749,6 +789,96 @@ program
         process.exit(1);
     }
 });
+/**
+ * Emit the changed-audit output (SARIF, JSON, or console) for the hook surface.
+ * The SARIF branch dynamically imports its generator, so this is async.
+ */
+async function emitChangedOutput(result, violations, blocking, dismissedCount, options) {
+    // JSON output
+    if (options.format === 'sarif') {
+        const { generateSARIFReport, readVersionControlProvenance } = await import('./reporting/sarifReportGenerator.js');
+        const projectDir = resolve(options.path || process.cwd());
+        const sarifOutput = generateSARIFReport(result, { rootDir: projectDir, ...readVersionControlProvenance(projectDir) });
+        process.stdout.write(sarifOutput + '\n');
+    }
+    else if (options.json) {
+        const projectDir = resolve(options.path || process.cwd());
+        const jsonViolations = violations.map((v) => {
+            // Compute relative path if file resolves inside the project
+            let filePath = v.file || '';
+            if (filePath.startsWith('/') || filePath.startsWith('\\\\')) {
+                const rel = relative(projectDir, filePath);
+                // Only use relative path if it doesn't escape the project
+                if (!rel.startsWith('..') && !isAbsolute(rel)) {
+                    filePath = rel;
+                }
+            }
+            // Find column: prefer explicit column, then start.column, then default to 1
+            const col = v.column ?? v.start?.column ?? 1;
+            return {
+                analyzer: v.analyzer || '',
+                rule: v.rule,
+                severity: v.severity,
+                message: v.message,
+                file: filePath,
+                line: v.line ?? v.start?.line,
+                column: col,
+                endLine: v.end?.line,
+                endColumn: v.end?.column,
+                enclosingSymbol: v.symbol || v.enclosingFunction || '',
+                suggestion: v.suggestion || '',
+                details: v.details || '',
+                ...(v.new !== undefined && { new: v.new }),
+                ...(v.dismissed !== undefined && { dismissed: v.dismissed }),
+                fingerprint: fingerprint(buildFingerprintInput(v))
+            };
+        });
+        // Coverage diagnostics ride alongside violations so an agent sees "the
+        // analyzer couldn't resolve this" without a metadata flag — and without
+        // it ever gating (diagnostics never reach computeGatingDecision).
+        const jsonDiagnostics = (result.metadata?.diagnostics ?? []).map((d) => ({
+            analyzer: d.analyzerName ?? d.analyzer ?? '',
+            kind: d.kind,
+            message: d.message,
+            ...(d.file ? { file: d.file } : {}),
+            ...(typeof d.line === 'number' ? { line: d.line } : {}),
+            ...(d.details ? { details: d.details } : {}),
+        }));
+        const jsonOutput = { violations: jsonViolations, diagnostics: jsonDiagnostics };
+        process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
+    }
+    else if (!options.quiet || violations.length > 0) {
+        // Console output — Spec 45 A2: agent-facing output emits counts (per
+        // analyzer/rule/severity, plus the before/after gate figure) alongside
+        // findings. The hook and the `changed` command are the agent's surface.
+        console.log(chalk.blue('🔍 Diff-Scoped Code Audit'));
+        console.log(chalk.gray('══════════════════════════════════════════════════'));
+        printFileAccounting(result, !!options.explainSkipped);
+        if (violations.length > 0) {
+            console.log('');
+            printCountSummary(violations);
+            console.log(chalk.bold(`gate before/after: ${violations.length} → ${blocking.length} blocking`));
+            if (dismissedCount > 0) {
+                console.log(chalk.dim(`  ${dismissedCount} dismissed — still counted above, excluded from the gate`));
+            }
+            console.log(chalk.gray('── Violations ────────────────────────────────────'));
+            for (const v of violations) {
+                const icon = v.severity === 'critical' ? '🔴' :
+                    v.severity === 'severe' ? '🟠' : '🟡';
+                const statusTag = v.new === false
+                    ? chalk.dim(' [known — still open]')
+                    : '';
+                const dismissedTag = v.dismissed
+                    ? chalk.dim(' [dismissed]')
+                    : '';
+                console.log(`${icon} ${chalk.bold(v.file)}${lineSuffix(v.line)} [${v.severity}] ${v.message}${statusTag}${dismissedTag}`);
+            }
+        }
+        else {
+            console.log(chalk.green('\n✓ No readings.'));
+        }
+    }
+}
 // Spec 45 A2 — counts are emitted where useful (per analyzer, per rule, per
 // severity), on agent-facing surfaces as well as human ones. This reverts Spec
 // 36 R3's "no bare counts": an agent now sees the shape of what fired instead
@@ -788,11 +918,61 @@ function printCountSummary(violations) {
  */
 async function buildChangedResultFromDiagnostics(violations, projectRoot) {
     const analyzerResults = {};
+    const byAnalyzer = {};
+    let totalViolations = 0;
+    let criticalIssues = 0;
+    let severe = 0;
+    let high = 0;
+    let dismissed = 0;
+    const violationsByCategory = {};
     for (const v of violations) {
         const key = v.analyzer || 'unknown';
         (analyzerResults[key] = analyzerResults[key] || { violations: [] }).violations.push(v);
+        totalViolations++;
+        switch (v.severity) {
+            case 'critical':
+                criticalIssues++;
+                break;
+            case 'severe':
+                severe++;
+                break;
+            case 'high':
+                high++;
+                break;
+        }
+        const rule = v.rule || 'unknown';
+        violationsByCategory[rule] = (violationsByCategory[rule] ?? 0) + 1;
+        const bucket = byAnalyzer[key] ?? (byAnalyzer[key] = { violations: 0 });
+        bucket.violations++;
+        if (v.dismissed)
+            dismissed++;
     }
-    return { analyzerResults, metadata: { configUsed: undefined, diagnostics: [] } };
+    const topIssues = Object.entries(violationsByCategory)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 5)
+        .map(([type, count]) => ({ type, count }));
+    // A *real* summary derived from the diagnostics the daemon served — not a
+    // zero-filled placeholder (a stub satisfying the type, with a `dismissed: 0`
+    // that was never measured). Every field here is computed from the actual
+    // findings: severity/category/byAnalyzer rollups, plus `dismissed` from each
+    // diagnostic's own `dismissed` flag. `totalFiles` and the per-analyzer
+    // `filesProcessed`/`fatalErrors`/`unprovenSites` are not derivable from a flat
+    // per-file diagnostic list, so they are omitted; the guarded read
+    // (`result.summary?.dismissed ?? 0`) tolerates their absence.
+    return {
+        analyzerResults,
+        summary: {
+            totalViolations,
+            criticalIssues,
+            severe,
+            high,
+            violationsByCategory,
+            topIssues,
+            byAnalyzer,
+            dismissed,
+        },
+        metadata: { configUsed: undefined, diagnostics: [] },
+    };
 }
 // Self-audit gate (Spec 33 Item 15 + Spec 44 remediation). Runs the full
 // analyzer pipeline over the tool's own production source and asserts zero
@@ -828,7 +1008,7 @@ program
     .description('Audit the tool\'s own analyzers/ + languages/ source and fail on blocking readings')
     .option('--json', 'Output violations as machine-readable JSON to stdout')
     .option('--stdin', 'Read file paths from stdin (one per line)')
-    .option('-p, --path <projectPath>', 'Project root path', process.cwd())
+    .option('-p, --path <projectPath>', OPTION_PROJECT_ROOT_PATH, process.cwd())
     .option('--fail-on <severity>', 'Blocking severity floor: critical, severe, or high', 'high')
     .action(async (paths, options) => {
     try {
@@ -867,7 +1047,6 @@ program
         const runner = createAuditRunner({
             projectRoot: options.path,
             scope,
-            analyzerConcurrency: 4
         });
         const result = await runner.run();
         const violations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
@@ -912,7 +1091,7 @@ program
             for (const v of blocking) {
                 const icon = v.severity === 'critical' ? '🔴' :
                     v.severity === 'severe' ? '🟠' : '🟡';
-                console.log(`${icon} ${v.file}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.message}`);
+                console.log(`${icon} ${v.file}${lineSuffix(v.line)} [${v.severity}] ${v.message}`);
             }
         }
         else {
@@ -938,8 +1117,8 @@ program
 program
     .command('next-file')
     .description('Audit and return the highest-priority file with readings (file-by-file refactor loop)')
-    .option('-p, --path <projectPath>', 'Project root path', process.cwd())
-    .option('-c, --config <config>', 'Configuration name')
+    .option('-p, --path <projectPath>', OPTION_PROJECT_ROOT_PATH, process.cwd())
+    .option('-c, --config <config>', OPTION_CONFIGURATION_NAME)
     .option('--json', 'Output a single JSON object (or {done:true}) to stdout')
     .action(async (options) => {
     try {
@@ -1037,7 +1216,7 @@ function printNextFile(violations, summary, projectDir, json) {
         console.log(chalk.gray('\n── Readings ────────────────────────────────────────'));
         for (const v of ordered) {
             const icon = v.severity === 'critical' ? '🔴' : v.severity === 'severe' ? '🟠' : '🟡';
-            console.log(`${icon} ${chalk.bold(relativize(v.file || ''))}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.rule} — ${v.message}`);
+            console.log(`${icon} ${chalk.bold(relativize(v.file || ''))}${lineSuffix(v.line)} [${v.severity}] ${v.rule} — ${v.message}`);
         }
     }
 }
@@ -1045,8 +1224,8 @@ function printNextFile(violations, summary, projectDir, json) {
 program
     .command('baseline')
     .description('Snapshot current advisory readings as the baseline (excludes invariants)')
-    .option('-p, --path <path>', 'Project path', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('-p, --path <path>', OPTION_PROJECT_PATH, process.cwd())
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         await initParsers();
@@ -1112,9 +1291,9 @@ program
     .command('dismiss <fingerprint>')
     .description('Dismiss one finding by fingerprint — a written reason is required')
     .requiredOption('--reason <reason>', 'Why this finding is dismissed (required — a dismissal without a reason is a config error)')
-    .option('-p, --path <path>', 'Project path', process.cwd())
+    .option('-p, --path <path>', OPTION_PROJECT_PATH, process.cwd())
     .option('--telemetry-endpoint <url>', 'Feedback service endpoint override (defaults to the opt-in endpoint recorded by the telemetry tool)')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (fingerprintArg, options) => {
     try {
         const reason = (options.reason ?? '').trim();
@@ -1198,8 +1377,9 @@ program
     .description('Generate a .codeauditor.json scaffold with invariant rules')
     .option('-o, --output <dir>', 'Output directory', '.')
     .option('-i, --interactive', 'Interactive rule builder')
-    .option('-f, --force', 'Force overwrite existing file without confirmation')
-    .option('-y, --yes', 'Skip confirmation prompts (same as --force)')
+    .option('--overwrite', 'Overwrite an existing .codeauditor.json without confirmation')
+    .option('-f, --force', 'Alias for --overwrite')
+    .option('-y, --yes', 'Alias for --overwrite')
     .action(async (options) => {
     console.log(chalk.blue('🛠️  Code Auditor Config Generator'));
     console.log(chalk.gray('════════════════════════════════════════════════════'));
@@ -1225,7 +1405,7 @@ indexCmd
     .command('sync')
     .description('Synchronize index from source files')
     .option('--path <path>', 'Path to a specific file or directory', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         await initParsers();
@@ -1266,64 +1446,65 @@ indexCmd
         process.exit(1);
     }
 });
-indexCmd
-    .command('cleanup')
-    .description('Remove index entries for deleted files')
-    .option('--json', 'Output as JSON')
-    .action(async (options) => {
-    try {
-        const db = CodeIndexDB.getInstance();
-        await db.initialize();
-        const result = await db.bulkCleanup();
-        if (options.json) {
-            process.stdout.write(JSON.stringify({ mode: 'cleanup', success: true, ...result }) + '\n');
+/** Register a simple `index` subcommand that runs one mutation on the
+ *  initialized index and prints the outcome (JSON or console). `cleanup` and
+ *  `reset` share the get-instance/initialize/json-vs-console/try-catch
+ *  scaffolding; only the mutation and its result prose differ, so they live
+ *  here once and each command is a thin `defineIndexMutationCommand(...)` call. */
+function defineIndexMutationCommand(name, description, work) {
+    indexCmd
+        .command(name)
+        .description(description)
+        .option('--json', OPTION_OUTPUT_AS_JSON)
+        .action(async (options) => {
+        try {
+            const db = CodeIndexDB.getInstance();
+            await db.initialize();
+            const { extra, greenLine, grayLine } = await work(db);
+            if (options.json) {
+                process.stdout.write(JSON.stringify({ mode: name, success: true, ...extra }) + '\n');
+            }
+            else {
+                console.log(chalk.green(greenLine));
+                console.log(chalk.gray(grayLine));
+            }
         }
-        else {
-            console.log(chalk.green('✓ Cleanup complete'));
-            console.log(chalk.gray(`Removed ${result.removedCount} entries from ${result.removedFiles.length} deleted files`));
+        catch (error) {
+            console.error(chalk.red('Error:'), error);
+            process.exit(1);
         }
-    }
-    catch (error) {
-        console.error(chalk.red('Error:'), error);
-        process.exit(1);
-    }
+    });
+}
+defineIndexMutationCommand('cleanup', 'Remove index entries for deleted files', async (db) => {
+    const result = await db.bulkCleanup();
+    return {
+        extra: result,
+        greenLine: '✓ Cleanup complete',
+        grayLine: `Removed ${result.removedCount} entries from ${result.removedFiles.length} deleted files`,
+    };
 });
-indexCmd
-    .command('reset')
-    .description('Clear all analysis data (preserves tasks, config, whitelist)')
-    .option('--json', 'Output as JSON')
-    .action(async (options) => {
-    try {
-        const db = CodeIndexDB.getInstance();
-        await db.initialize();
-        await db.clearIndex();
-        if (options.json) {
-            process.stdout.write(JSON.stringify({ mode: 'reset', success: true, message: 'All analysis data cleared' }) + '\n');
-        }
-        else {
-            console.log(chalk.green('✓ Index reset complete'));
-            console.log(chalk.gray('All analysis-derived data cleared (tasks, config, and whitelist preserved)'));
-        }
-    }
-    catch (error) {
-        console.error(chalk.red('Error:'), error);
-        process.exit(1);
-    }
+defineIndexMutationCommand('reset', 'Clear all analysis data (preserves tasks, config, whitelist)', async (db) => {
+    await db.clearIndex();
+    return {
+        extra: { message: 'All analysis data cleared' },
+        greenLine: '✓ Index reset complete',
+        grayLine: 'All analysis-derived data cleared (tasks, config, and whitelist preserved)',
+    };
 });
 // ── Index status command (Spec 14 R1) ──────────────────────────
 indexCmd
     .command('status')
     .description('Show index health and graph statistics')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const db = CodeIndexDB.getInstance();
         await db.initialize();
-        const stats = await db.getStats();
+        const stats = await db.functionIndex.getStats();
         // Graph stats — non-fatal if graph cache is empty
         let graphStats = null;
         try {
-            graphStats = db.getGraphStats();
+            graphStats = db.graph.getGraphStats();
         }
         catch {
             // No graph data yet — ok
@@ -1394,7 +1575,7 @@ configCmd
     .command('rules-list')
     .description('List all configured invariant rules from .codeauditor.json')
     .option('--config-path <path>', 'Path to .codeauditor.json')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const pathModule = await import('path');
@@ -1404,7 +1585,9 @@ configCmd
         try {
             const raw = readFileSync(configPath, 'utf-8');
             const config = JSON.parse(raw);
-            const rules = config?.rules ?? [];
+            // `rules` is an array by schema; tolerate the `{}` shorthand some fixtures
+            // and hand-edited configs use for "no rules" — `.map` on `{}` would throw.
+            const rules = Array.isArray(config?.rules) ? config.rules : [];
             if (options.json) {
                 process.stdout.write(JSON.stringify({
                     rules: rules.map((r) => ({ id: r.id, kind: r.kind, severity: r.severity, message: r.message || null })),
@@ -1442,7 +1625,7 @@ configCmd
     .command('rules-check')
     .description('Validate the current .codeauditor.json rules')
     .option('--config-path <path>', 'Path to .codeauditor.json')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const pathModule = await import('path');
@@ -1490,9 +1673,9 @@ configCmd
 configCmd
     .command('profiles')
     .description('Show active path profiles and resolve per-file matching')
-    .option('-p, --path <path>', 'Project path', process.cwd())
+    .option('-p, --path <path>', OPTION_PROJECT_PATH, process.cwd())
     .option('--file <file>', 'Resolve profiles for a specific file')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const fs = await import('fs/promises');
@@ -1590,8 +1773,8 @@ configCmd
 configCmd
     .command('detection')
     .description('Show DB-provenanced and inferred receiver identifiers with per-entry evidence')
-    .option('-p, --path <path>', 'Project path', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('-p, --path <path>', OPTION_PROJECT_PATH, process.cwd())
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .option('--mode <mode>', 'Detection mode filter (hybrid, provenance, names)')
     .action(async (options) => {
     try {
@@ -1643,9 +1826,7 @@ configCmd
                 // Build provenance context using schema analyzer config (most complete)
                 const ctx = buildProvenanceContext(ast, adapter, sourceCode, {
                     mode: detectionMode,
-                    dbReceiverNames: schemaCfg.dbReceiverNames ?? daCfg.dbReceiverNames,
                     dbBindingNames: schemaCfg.dbBindingNames ?? daCfg.dbBindingNames,
-                    dbCallMethods: schemaCfg.dbCallMethods ?? daCfg.dbCallMethods,
                 });
                 // Collect DB-provenanced
                 for (const [id, evidence] of ctx.dbProvenanced) {
@@ -1698,70 +1879,84 @@ configCmd
                 entry.validatorProvenanced.push(v);
             }
             for (const [file, data] of byFile) {
-                db.storeFileProvenance(file, data);
+                db.provenance.storeFileProvenance(file, data);
             }
             // Store inferred receivers
-            db.storeInferredReceivers(inferred);
+            db.inferredReceivers.storeInferredReceivers(inferred);
         }
         catch {
             // Index not available — skip persistence
         }
-        if (options.json) {
-            process.stdout.write(JSON.stringify({
-                mode: detectionMode,
-                projectRoot,
-                filesScanned: files.slice(0, 500).length,
-                dbProvenanced: provenanced,
-                validatorProvenanced: validatorIdentifiers,
-                inferred,
-            }, null, 2) + '\n');
-        }
-        else {
-            console.log(chalk.bold(`Detection mode: ${chalk.cyan(detectionMode)}`));
-            console.log(chalk.gray(`Scanned ${files.slice(0, 500).length} files`));
-            console.log();
-            if (provenanced.length > 0) {
-                console.log(chalk.bold('DB-Provenanced Identifiers:'));
-                for (const p of provenanced) {
-                    const reasonColor = p.reason === 'fallback'
-                        ? chalk.yellow
-                        : p.reason === 'package'
-                            ? chalk.green
-                            : chalk.cyan;
-                    console.log(`  ${chalk.white(p.identifier)} ${chalk.gray(`(${p.file})`)}`);
-                    console.log(`    ${reasonColor(`reason: ${p.reason}`)} — ${chalk.gray(p.source)}`);
-                    if (p.chain) {
-                        console.log(`    ${chalk.gray(`chain: ${p.chain.join(' → ')}`)}`);
-                    }
-                }
-                console.log();
-            }
-            if (inferred.length > 0) {
-                console.log(chalk.bold('Inferred Receivers:'));
-                for (const i of inferred) {
-                    console.log(`  ${chalk.white(i.identifier)} ${chalk.gray(`(${i.file})`)}`);
-                    console.log(`    ${chalk.magenta(i.reason)}`);
-                }
-                console.log();
-            }
-            if (validatorIdentifiers.length > 0) {
-                console.log(chalk.bold('Validator-Provenanced Identifiers:'));
-                for (const v of validatorIdentifiers) {
-                    console.log(`  ${chalk.white(v.identifier)} ${chalk.gray(`(${v.file})`)}`);
-                    console.log(`    ${chalk.green(`reason: ${v.reason}`)} — ${chalk.gray(v.source)}`);
-                }
-                console.log();
-            }
-            if (provenanced.length === 0 && inferred.length === 0 && validatorIdentifiers.length === 0) {
-                console.log(chalk.gray('No DB-provenanced, inferred, or validator-provenanced identifiers found.'));
-            }
-        }
+        printDetectionResults({
+            json: options.json,
+            mode: detectionMode,
+            projectRoot,
+            filesScanned: files.slice(0, 500).length,
+            dbProvenanced: provenanced,
+            validatorProvenanced: validatorIdentifiers,
+            inferred,
+        });
     }
     catch (error) {
         console.error(chalk.red('Error:'), error);
         process.exit(1);
     }
 });
+// Renders the `config detection` results — pulled out of the `.action` handler so
+// the scan/persist logic stays short and the two output shapes (JSON vs human) are
+// isolated from the provenance collection.
+function printDetectionResults(params) {
+    const { json, mode, projectRoot, filesScanned, dbProvenanced, validatorProvenanced, inferred } = params;
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            mode,
+            projectRoot,
+            filesScanned,
+            dbProvenanced,
+            validatorProvenanced,
+            inferred,
+        }, null, 2) + '\n');
+        return;
+    }
+    console.log(chalk.bold(`Detection mode: ${chalk.cyan(mode)}`));
+    console.log(chalk.gray(`Scanned ${filesScanned} files`));
+    console.log();
+    if (dbProvenanced.length > 0) {
+        console.log(chalk.bold('DB-Provenanced Identifiers:'));
+        for (const p of dbProvenanced) {
+            const reasonColor = p.reason === 'fallback'
+                ? chalk.yellow
+                : p.reason === 'package'
+                    ? chalk.green
+                    : chalk.cyan;
+            console.log(`  ${chalk.white(p.identifier)} ${chalk.gray(`(${p.file})`)}`);
+            console.log(`    ${reasonColor(`reason: ${p.reason}`)} — ${chalk.gray(p.source)}`);
+            if (p.chain) {
+                console.log(`    ${chalk.gray(`chain: ${p.chain.join(' → ')}`)}`);
+            }
+        }
+        console.log();
+    }
+    if (inferred.length > 0) {
+        console.log(chalk.bold('Inferred Receivers:'));
+        for (const i of inferred) {
+            console.log(`  ${chalk.white(i.identifier)} ${chalk.gray(`(${i.file})`)}`);
+            console.log(`    ${chalk.magenta(i.reason)}`);
+        }
+        console.log();
+    }
+    if (validatorProvenanced.length > 0) {
+        console.log(chalk.bold('Validator-Provenanced Identifiers:'));
+        for (const v of validatorProvenanced) {
+            console.log(`  ${chalk.white(v.identifier)} ${chalk.gray(`(${v.file})`)}`);
+            console.log(`    ${chalk.green(`reason: ${v.reason}`)} — ${chalk.gray(v.source)}`);
+        }
+        console.log();
+    }
+    if (dbProvenanced.length === 0 && inferred.length === 0 && validatorProvenanced.length === 0) {
+        console.log(chalk.gray('No DB-provenanced, inferred, or validator-provenanced identifiers found.'));
+    }
+}
 // Search command
 program
     .command('search <query>')
@@ -1795,6 +1990,7 @@ program
     .option('--no-unused-imports', 'Hide unused import warnings')
     .option('--min-complexity <threshold>', 'Minimum complexity threshold for warnings', '7')
     .option('-o, --output <file>', 'Save output to file instead of displaying')
+    .option('--overwrite', 'Overwrite an existing output file (default: refuse)')
     .action(async (options) => {
     console.log(chalk.blue('🗺️  Codebase Map Generator'));
     console.log(chalk.gray('════════════════════════════════════════════════════'));
@@ -1828,7 +2024,7 @@ tasksCmd
     .option('--priority <priority>', 'Filter by priority (low, medium, high)')
     .option('--label <label>', 'Filter by label')
     .option('--limit <limit>', 'Result limit', '50')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const args = { action: 'list' };
@@ -1863,7 +2059,7 @@ tasksCmd
             }
         }
         else {
-            console.error(chalk.red(result.error || 'Unknown error'));
+            console.error(chalk.red(result.error || UNKNOWN_ERROR));
             process.exit(1);
         }
     }
@@ -1880,7 +2076,7 @@ tasksCmd
     .option('--priority <priority>', 'Priority (low, medium, high)')
     .option('--status <status>', 'Status (open, in_progress)')
     .option('--labels <labels>', 'Comma-separated labels')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const args = {
@@ -1905,7 +2101,7 @@ tasksCmd
             console.log(chalk.green(`✓ Task created: ${task.title || task.taskId || 'unknown'}`));
         }
         else {
-            console.error(chalk.red(result.error || 'Unknown error'));
+            console.error(chalk.red(result.error || UNKNOWN_ERROR));
             process.exit(1);
         }
     }
@@ -1917,7 +2113,7 @@ tasksCmd
 tasksCmd
     .command('get <taskId>')
     .description('Get a task by ID')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (taskId, options) => {
     try {
         const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
@@ -1943,7 +2139,7 @@ tasksCmd
                 console.log(chalk.dim(`\nfingerprint: ${t.fingerprint}`));
         }
         else {
-            console.error(chalk.red(result.error || 'Unknown error'));
+            console.error(chalk.red(result.error || UNKNOWN_ERROR));
             process.exit(1);
         }
     }
@@ -1960,7 +2156,7 @@ tasksCmd
     .option('--status <status>', 'New status (open, in_progress, completed)')
     .option('--priority <priority>', 'New priority (low, medium, high)')
     .option('--labels <labels>', 'Comma-separated labels')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (taskId, options) => {
     try {
         const patch = {};
@@ -1987,7 +2183,7 @@ tasksCmd
             console.log(chalk.green(`✓ Task updated`));
         }
         else {
-            console.error(chalk.red(result.error || 'Unknown error'));
+            console.error(chalk.red(result.error || UNKNOWN_ERROR));
             process.exit(1);
         }
     }
@@ -1996,60 +2192,45 @@ tasksCmd
         process.exit(1);
     }
 });
-tasksCmd
-    .command('complete <taskId>')
-    .description('Mark a task as completed')
-    .option('--json', 'Output as JSON')
-    .action(async (taskId, options) => {
-    try {
-        const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
-        const result = await handleProjectTasks({ action: 'complete_task', taskId });
-        if (options.json) {
-            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-        }
-        else if (result.success) {
-            console.log(chalk.green(`✓ Task completed`));
+/** Run a single-taskId tasks subcommand and print its result. */
+function makeTaskIdAction(action, successLabel) {
+    return async (taskId, options) => {
+        try {
+            const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
+            const result = await handleProjectTasks({ action, taskId });
+            if (options.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            }
+            else if (result.success) {
+                console.log(chalk.green(`✓ ${successLabel}`));
+            }
+            else {
+                console.error(chalk.red(result.error || UNKNOWN_ERROR));
+                process.exit(1);
+            }
         }
-        else {
-            console.error(chalk.red(result.error || 'Unknown error'));
+        catch (error) {
+            console.error(chalk.red('Error:'), error);
             process.exit(1);
         }
-    }
-    catch (error) {
-        console.error(chalk.red('Error:'), error);
-        process.exit(1);
-    }
-});
+    };
+}
+tasksCmd
+    .command('complete <taskId>')
+    .description('Mark a task as completed')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
+    .action(makeTaskIdAction('complete_task', 'Task completed'));
 tasksCmd
     .command('delete <taskId>')
     .description('Delete a task')
-    .option('--json', 'Output as JSON')
-    .action(async (taskId, options) => {
-    try {
-        const { handleProjectTasks } = await import('./mcp-tools/projectTasks.js');
-        const result = await handleProjectTasks({ action: 'delete', taskId });
-        if (options.json) {
-            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-        }
-        else if (result.success) {
-            console.log(chalk.green(`✓ Task deleted`));
-        }
-        else {
-            console.error(chalk.red(result.error || 'Unknown error'));
-            process.exit(1);
-        }
-    }
-    catch (error) {
-        console.error(chalk.red('Error:'), error);
-        process.exit(1);
-    }
-});
+    .option('--json', OPTION_OUTPUT_AS_JSON)
+    .action(makeTaskIdAction('delete', 'Task deleted'));
 tasksCmd
     .command('from-audit')
     .description('Populate tasks from audit violations')
     .option('--auditJobId <id>', 'Specific audit result ID')
     .option('--severities <severities>', 'Comma-separated severities (critical,severe,high)', 'critical,severe,high')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const args = { action: 'from_audit' };
@@ -2076,7 +2257,7 @@ tasksCmd
             console.log(chalk.yellow(result.error));
         }
         else {
-            console.error(chalk.red(result.error || 'Unknown error'));
+            console.error(chalk.red(result.error || UNKNOWN_ERROR));
             process.exit(1);
         }
     }
@@ -2092,7 +2273,7 @@ program
     .description('Rank files and functions by hotspot score (churn × complexity)')
     .option('--limit <n>', 'Max entries to show')
     .option('--path <dir>', 'Target directory (triggers spot churn extraction if index is empty)')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const db = CodeIndexDB.getInstance();
@@ -2167,8 +2348,8 @@ program
     .command('risk')
     .description('Rank functions by architectural risk (PageRank × betweenness × complexity × untested)')
     .option('--limit <n>', 'Max entries to show', '20')
-    .option('--path <dir>', 'Project path', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('--path <dir>', OPTION_PROJECT_PATH, process.cwd())
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .option('--format <format>', 'Output format: dot (call-graph neighborhood of top functions)')
     .action(async (options) => {
     try {
@@ -2183,10 +2364,13 @@ program
         if (options.format === 'dot') {
             // DOT output: call-graph neighborhood of top-N risk functions
             const { callGraphToDot } = await import('./graph/outputFormatter.js');
-            // Collect IDs for top risk functions
+            // Collect IDs for top risk functions — one query for the whole top-N
+            // set, not one query per function (loop-query).
             const topIds = new Set();
-            for (const e of top) {
-                const rows = rawDb.prepare('SELECT id FROM functions WHERE name = ? AND file_path = ?').all(e.functionName, e.filePath);
+            if (top.length > 0) {
+                const orClause = top.map(() => '(name = ? AND file_path = ?)').join(' OR ');
+                const params = top.flatMap((e) => [e.functionName, e.filePath]);
+                const rows = rawDb.prepare(`SELECT id FROM functions WHERE ${orClause}`).all(...params);
                 for (const r of rows)
                     topIds.add(r.id);
             }
@@ -2243,7 +2427,7 @@ ledgerCmd
     .command('list')
     .description('List recent audit runs')
     .option('--limit <n>', 'Max runs to show', '20')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const { listRuns } = await import('./ledger.js');
@@ -2292,7 +2476,7 @@ ledgerCmd
 ledgerCmd
     .command('stats')
     .description('Show aggregated ledger statistics')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const { getLedgerStats } = await import('./ledger.js');
@@ -2325,7 +2509,7 @@ ledgerCmd
     .command('trends')
     .description('Compare consecutive full-audit runs and report new vs fixed readings per rule')
     .option('--since <runId>', 'Only consider runs after this run ID')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const { getTrends } = await import('./ledger.js');
@@ -2388,9 +2572,6 @@ ledgerCmd
 // `audit --detach` forks workers/auditJobRunner; `status`/`result`/`jobs` read
 // the persisted ledger. One job model (the ledger run), one write path — these
 // are thin wrappers over ledger.ts + mcpAuditJobs.ts, not a second store.
-/** Full analyzer set — derives from createAuditRunner's registry so `--detach`
- *  produces the same per-rule coverage as a synchronous `audit`. */
-const DETACHED_DEFAULT_ANALYZERS = [...ALL_ANALYZERS];
 /** Lease TTL used by read-path reclaim, mirroring mcpAuditJobs.jobLeaseTtlMs. */
 const CLI_JOB_LEASE_TTL_MS = Number(process.env.CODE_AUDITOR_JOB_LEASE_TTL_MS) || 30_000;
 function spec41StatusBadge(status) {
@@ -2472,12 +2653,8 @@ async function runDetachedAudit(options) {
     const logFd = openSync(logPath, 'a');
     const argsJson = JSON.stringify({
         path: auditPath,
-        ...(options.partitionStrategy && { partitionStrategy: options.partitionStrategy }),
-        ...(options.maxPartitions && { maxPartitions: Number(options.maxPartitions) }),
-        ...(options.shardTimeoutMs && { shardTimeoutMs: Number(options.shardTimeoutMs) }),
     });
     const defaultsJson = JSON.stringify({
-        defaultAnalyzers: DETACHED_DEFAULT_ANALYZERS,
         defaultMinSeverity: 'high',
         defaultGenerateCodeMap: false,
     });
@@ -2497,7 +2674,7 @@ program
     .command('status <jobId>')
     .description('Show a detached audit job status, progress, and staleness')
     .option('-p, --path <path>', 'Project root containing the job (default: cwd)', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (jobId, options) => {
     try {
         const { getLedgerRun, reclaimStaleRunning, computeStaleness } = await import('./ledger.js');
@@ -2560,12 +2737,12 @@ program
     .option('--analyzer <analyzer>', 'Filter by analyzer')
     .option('--file <file>', 'Filter by file path (substring match)')
     .option('--severity <severity>', 'Filter by severity (critical|severe|high)')
-    .option('--state [state]', 'Query coverage by state (fired|clean|notApplicable|cannot-fire|unassessed); omit value for all')
+    .option('--state [state]', 'Query coverage by state (fired|clean|notApplicable|cannot-fire|incomplete); omit value for all')
     .option('--count', 'Group findings by analyzer/rule with counts')
     .option('--limit <n>', 'Max findings to return (0 = unbounded)', '50')
     .option('--offset <n>', 'Findings offset', '0')
     .option('--stale', 'Force full content re-hash for staleness')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (jobId, options) => {
     try {
         const { getLedgerRun, queryLedgerFindings, queryLedgerCoverage, computeStaleness } = await import('./ledger.js');
@@ -2658,7 +2835,7 @@ program
     .option('--prune', 'Delete all but the newest runs for this project')
     .option('--keep <n>', 'Runs to keep when --prune is set', '10')
     .option('--limit <n>', 'Runs to display (staleness computed for these)', '20')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const { listLedgerRuns, reclaimStaleRunning, pruneLedgerRuns, computeStaleness } = await import('./ledger.js');
@@ -2714,7 +2891,7 @@ conventionsCmd
     .command('list')
     .description('List mined conventions from the code index')
     .option('--domain <domain>', 'Filter by domain: usage-pair, import-form, error-handling, export-shape, naming')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const db = CodeIndexDB.getInstance();
@@ -2778,7 +2955,7 @@ conventionsCmd
     .command('propose')
     .description('Emit ready-to-paste .codeauditor.json rules from mined conventions')
     .option('--domain <domain>', 'Filter by domain: naming or import-form (other domains do not map to rule kinds)')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const db = CodeIndexDB.getInstance();
@@ -2888,8 +3065,8 @@ program
 program
     .command('architecture')
     .description('Analyze import graph: community detection, directory purity, Martin instability metrics')
-    .option('--path <dir>', 'Project path', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('--path <dir>', OPTION_PROJECT_PATH, process.cwd())
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .option('--format <format>', 'Output format: dot or mermaid (import graph colored by community)')
     .action(async (options) => {
     try {
@@ -3087,7 +3264,7 @@ coverageCmd
 coverageCmd
     .command('by-risk', { isDefault: true })
     .description('Show coverage rate by risk decile')
-    .option('--json', 'Output as JSON')
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const { generateCoverageReport } = await import('./coverage/coverageService.js');
@@ -3136,8 +3313,8 @@ coverageCmd
 program
     .command('print-config <file>')
     .description('Print the effective config for a file, naming the source of every value')
-    .option('-p, --path <path>', 'Project path', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('-p, --path <path>', OPTION_PROJECT_PATH, process.cwd())
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .option('--preset <id>', 'Apply a shareable preset (repeatable)', (v, prev) => prev.concat([v]), [])
     .action(async (file, options) => {
     try {
@@ -3155,9 +3332,6 @@ program
         // normalizes the real config, so path keys compare cleanly instead of
         // reading as "user-set" because one side is absolute and the other is not.
         const pristine = { ...getDefaultConfig(), codeIndex: { ...DEFAULT_CODE_INDEX_CONFIG } };
-        if (pristine.outputDirectory) {
-            pristine.outputDirectory = pathModule.resolve(projectRoot, pristine.outputDirectory);
-        }
         pristine.includePaths = (pristine.includePaths ?? []).map((p) => pathModule.isAbsolute(p) ? p : pathModule.resolve(projectRoot, p));
         pristine.excludePaths = (pristine.excludePaths ?? []).map((p) => pathModule.isAbsolute(p) ? p : pathModule.resolve(projectRoot, p));
         // Load the project config (defaults when no config file exists).
@@ -3171,7 +3345,6 @@ program
         }
         const analyzerConfigs = (config.analyzerConfigs ?? {});
         const pathProfiles = (config.pathProfiles ?? []);
-        const enabledAnalyzers = (config.enabledAnalyzers ?? []);
         // Resolve --preset ids to ordered preset objects (Spec 38 R4). Unknown
         // ids are a hard error, not a silent skip.
         const presetIds = Array.isArray(options.preset) ? options.preset : (options.preset ? [options.preset] : []);
@@ -3191,7 +3364,6 @@ program
             projectRoot,
             analyzerConfigs,
             pathProfiles,
-            enabledAnalyzers,
             presets,
             lintConfig,
         });
@@ -3304,7 +3476,7 @@ program
         for (const v of sorted) {
             const icon = v.severity === 'critical' ? '🔴' :
                 v.severity === 'severe' ? '🟠' : '🟡';
-            console.log(`${icon} ${chalk.bold(v.file)}${v.line ? `:${v.line}` : ''} [${v.rule || v.severity}] ${v.message}`);
+            console.log(`${icon} ${chalk.bold(v.file)}${lineSuffix(v.line)} [${v.rule || v.severity}] ${v.message}`);
         }
     }
     catch (error) {
@@ -3369,8 +3541,8 @@ const daemonCmd = program
 daemonCmd
     .command('start')
     .description('Start the daemon for this project (detached by default)')
-    .option('-p, --path <path>', 'Project root', process.cwd())
-    .option('-c, --config <config>', 'Configuration name')
+    .option('-p, --path <path>', OPTION_PROJECT_ROOT, process.cwd())
+    .option('-c, --config <config>', OPTION_CONFIGURATION_NAME)
     .option('--foreground', 'Run in the foreground (blocking; useful for debugging)')
     .action(async (options) => {
     try {
@@ -3401,7 +3573,7 @@ daemonCmd
 daemonCmd
     .command('stop')
     .description('Ask the daemon to shut down')
-    .option('-p, --path <path>', 'Project root', process.cwd())
+    .option('-p, --path <path>', OPTION_PROJECT_ROOT, process.cwd())
     .action(async (options) => {
     try {
         const { resolveDaemonSocketPath } = await import('./dataPaths.js');
@@ -3423,8 +3595,8 @@ daemonCmd
 daemonCmd
     .command('status')
     .description('Show daemon status')
-    .option('-p, --path <path>', 'Project root', process.cwd())
-    .option('--json', 'Output as JSON')
+    .option('-p, --path <path>', OPTION_PROJECT_ROOT, process.cwd())
+    .option('--json', OPTION_OUTPUT_AS_JSON)
     .action(async (options) => {
     try {
         const { resolveDaemon } = await import('./daemon/resolve.js');
@@ -3534,6 +3706,9 @@ const SCAFFOLD_CONFIG = {
 async function generateConfigurations(options) {
     const outputDir = resolve(options.output || '.');
     const outputPath = join(outputDir, '.codeauditor.json');
+    // One consent spelling across the CLI: `--overwrite`. `--force`/`--yes` are
+    // retained as aliases for back-compat.
+    const overwrite = Boolean(options.overwrite || options.force || options.yes);
     let config;
     if (options.interactive) {
         // --- Interactive rule builder ---
@@ -3553,7 +3728,7 @@ async function generateConfigurations(options) {
             config = await buildRulesInteractively();
         }
         // Confirm output directory
-        if (!options.force && !options.yes) {
+        if (!overwrite) {
             const { dir } = await inquirer.prompt({
                 dir: {
                     type: 'input',
@@ -3598,12 +3773,12 @@ async function generateConfigurations(options) {
             exists = true;
         }
         catch { /* ok */ }
-        if (exists && !options.force && !options.yes) {
+        if (exists && !overwrite) {
             console.log(chalk.yellow(`.codeauditor.json already exists at ${outputPath}`));
-            console.log(chalk.gray('Use --force or --yes to overwrite, or --interactive to build a custom config.'));
+            console.log(chalk.gray('Use --overwrite to replace it, or --interactive to build a custom config.'));
             return;
         }
-        if (exists && (options.force || options.yes)) {
+        if (exists && overwrite) {
             console.log(chalk.yellow('Overwriting existing .codeauditor.json...'));
         }
         config = SCAFFOLD_CONFIG;
@@ -3614,6 +3789,136 @@ async function generateConfigurations(options) {
     console.log(chalk.gray('  2. Run ') + chalk.cyan('code-audit') + chalk.gray(' to enforce your rules'));
     console.log(chalk.gray('  3. Use ') + chalk.cyan('code-audit changed') + chalk.gray(' in your agent hook (gating rules block on new readings)'));
 }
+async function promptKindSpecificFields(kind, rule) {
+    switch (kind) {
+        case 'import-ban': {
+            const { module } = await inquirer.prompt({
+                module: {
+                    type: 'input',
+                    message: 'Banned module specifier (e.g. "lodash" or "@old-lib/*"):',
+                    validate: (input) => input.trim() ? true : 'Module specifier is required',
+                },
+            });
+            rule.module = module;
+            const { addExcept } = await inquirer.prompt({
+                addExcept: {
+                    type: 'confirm',
+                    message: 'Add exception paths (files allowed to import it)?',
+                    default: false,
+                },
+            });
+            if (addExcept) {
+                const { except } = await inquirer.prompt({
+                    except: {
+                        type: 'input',
+                        message: 'Exception globs (comma-separated, e.g. "src/migration/**"):',
+                    },
+                });
+                const exceptList = except.split(',').map((s) => s.trim()).filter(Boolean);
+                if (exceptList.length > 0)
+                    rule.except = exceptList;
+            }
+            break;
+        }
+        case 'call-constraint': {
+            const { callee } = await inquirer.prompt({
+                callee: {
+                    type: 'input',
+                    message: 'Callee (function name, optionally path-qualified as "path/glob#name"):',
+                    validate: (input) => input.trim() ? true : 'Callee is required',
+                },
+            });
+            rule.callee = callee;
+            const { mode } = await inquirer.prompt({
+                mode: {
+                    type: 'list',
+                    message: 'Restriction mode:',
+                    choices: [
+                        { name: 'Allow only specific callers (allowFrom)', value: 'allow' },
+                        { name: 'Deny specific callers (denyFrom)', value: 'deny' },
+                    ],
+                },
+            });
+            const { paths } = await inquirer.prompt({
+                paths: {
+                    type: 'input',
+                    message: `Path globs (comma-separated) for ${mode === 'allow' ? 'allowFrom' : 'denyFrom'}:`,
+                    validate: (input) => input.trim() ? true : 'At least one path glob is required',
+                },
+            });
+            const pathList = paths.split(',').map((s) => s.trim()).filter(Boolean);
+            if (mode === 'allow') {
+                rule.allowFrom = pathList;
+            }
+            else {
+                rule.denyFrom = pathList;
+            }
+            break;
+        }
+        case 'module-boundary': {
+            const { from, to } = await inquirer.prompt({
+                from: {
+                    type: 'input',
+                    message: 'From (path glob for files that must not import):',
+                    validate: (input) => input.trim() ? true : '"from" path glob is required',
+                },
+                to: {
+                    type: 'input',
+                    message: 'To (path glob for files that must not be imported):',
+                    validate: (input) => input.trim() ? true : '"to" path glob is required',
+                },
+            });
+            rule.from = from;
+            rule.to = to;
+            break;
+        }
+        case 'naming': {
+            const { path, exports: exportPattern } = await inquirer.prompt({
+                path: {
+                    type: 'input',
+                    message: 'Path (glob for files this rule applies to):',
+                    validate: (input) => input.trim() ? true : 'Path glob is required',
+                },
+                exports: {
+                    type: 'input',
+                    message: 'Exports regex (exported symbols must match, e.g. "^use[A-Z]"):',
+                    validate: (input) => input.trim() ? true : 'Exports regex is required',
+                },
+            });
+            rule.path = path;
+            rule.exports = exportPattern;
+            break;
+        }
+        case 'ast-pattern': {
+            const { pattern } = await inquirer.prompt({
+                pattern: {
+                    type: 'input',
+                    message: 'AST pattern (ast-grep syntax, e.g. "new Function($$$)"):',
+                    validate: (input) => input.trim() ? true : 'Pattern is required',
+                },
+            });
+            rule.pattern = pattern;
+            const { addLanguage } = await inquirer.prompt({
+                addLanguage: {
+                    type: 'confirm',
+                    message: 'Restrict to a specific language? (default: typescript)',
+                    default: false,
+                },
+            });
+            if (addLanguage) {
+                const { language } = await inquirer.prompt({
+                    language: {
+                        type: 'list',
+                        message: 'Language:',
+                        choices: ['typescript', 'javascript', 'go'],
+                    },
+                });
+                rule.language = language;
+            }
+            break;
+        }
+    }
+}
 /**
  * Interactive rule builder — walks the user through adding rules one at a time.
  */
@@ -3672,134 +3977,7 @@ async function buildRulesInteractively() {
             message: common.message,
         };
         // Kind-specific fields
-        switch (kind) {
-            case 'import-ban': {
-                const { module } = await inquirer.prompt({
-                    module: {
-                        type: 'input',
-                        message: 'Banned module specifier (e.g. "lodash" or "@old-lib/*"):',
-                        validate: (input) => input.trim() ? true : 'Module specifier is required',
-                    },
-                });
-                rule.module = module;
-                const { addExcept } = await inquirer.prompt({
-                    addExcept: {
-                        type: 'confirm',
-                        message: 'Add exception paths (files allowed to import it)?',
-                        default: false,
-                    },
-                });
-                if (addExcept) {
-                    const { except } = await inquirer.prompt({
-                        except: {
-                            type: 'input',
-                            message: 'Exception globs (comma-separated, e.g. "src/migration/**"):',
-                        },
-                    });
-                    const exceptList = except.split(',').map((s) => s.trim()).filter(Boolean);
-                    if (exceptList.length > 0)
-                        rule.except = exceptList;
-                }
-                break;
-            }
-            case 'call-constraint': {
-                const { callee } = await inquirer.prompt({
-                    callee: {
-                        type: 'input',
-                        message: 'Callee (function name, optionally path-qualified as "path/glob#name"):',
-                        validate: (input) => input.trim() ? true : 'Callee is required',
-                    },
-                });
-                rule.callee = callee;
-                const { mode } = await inquirer.prompt({
-                    mode: {
-                        type: 'list',
-                        message: 'Restriction mode:',
-                        choices: [
-                            { name: 'Allow only specific callers (allowFrom)', value: 'allow' },
-                            { name: 'Deny specific callers (denyFrom)', value: 'deny' },
-                        ],
-                    },
-                });
-                const { paths } = await inquirer.prompt({
-                    paths: {
-                        type: 'input',
-                        message: `Path globs (comma-separated) for ${mode === 'allow' ? 'allowFrom' : 'denyFrom'}:`,
-                        validate: (input) => input.trim() ? true : 'At least one path glob is required',
-                    },
-                });
-                const pathList = paths.split(',').map((s) => s.trim()).filter(Boolean);
-                if (mode === 'allow') {
-                    rule.allowFrom = pathList;
-                }
-                else {
-                    rule.denyFrom = pathList;
-                }
-                break;
-            }
-            case 'module-boundary': {
-                const { from, to } = await inquirer.prompt({
-                    from: {
-                        type: 'input',
-                        message: 'From (path glob for files that must not import):',
-                        validate: (input) => input.trim() ? true : '"from" path glob is required',
-                    },
-                    to: {
-                        type: 'input',
-                        message: 'To (path glob for files that must not be imported):',
-                        validate: (input) => input.trim() ? true : '"to" path glob is required',
-                    },
-                });
-                rule.from = from;
-                rule.to = to;
-                break;
-            }
-            case 'naming': {
-                const { path, exports: exportPattern } = await inquirer.prompt({
-                    path: {
-                        type: 'input',
-                        message: 'Path (glob for files this rule applies to):',
-                        validate: (input) => input.trim() ? true : 'Path glob is required',
-                    },
-                    exports: {
-                        type: 'input',
-                        message: 'Exports regex (exported symbols must match, e.g. "^use[A-Z]"):',
-                        validate: (input) => input.trim() ? true : 'Exports regex is required',
-                    },
-                });
-                rule.path = path;
-                rule.exports = exportPattern;
-                break;
-            }
-            case 'ast-pattern': {
-                const { pattern } = await inquirer.prompt({
-                    pattern: {
-                        type: 'input',
-                        message: 'AST pattern (ast-grep syntax, e.g. "new Function($$$)"):',
-                        validate: (input) => input.trim() ? true : 'Pattern is required',
-                    },
-                });
-                rule.pattern = pattern;
-                const { addLanguage } = await inquirer.prompt({
-                    addLanguage: {
-                        type: 'confirm',
-                        message: 'Restrict to a specific language? (default: typescript)',
-                        default: false,
-                    },
-                });
-                if (addLanguage) {
-                    const { language } = await inquirer.prompt({
-                        language: {
-                            type: 'list',
-                            message: 'Language:',
-                            choices: ['typescript', 'javascript', 'go'],
-                        },
-                    });
-                    rule.language = language;
-                }
-                break;
-            }
-        }
+        await promptKindSpecificFields(kind, rule);
         rules.push(rule);
         console.log(chalk.green(`  ✓ Added rule "${rule.id}" [${rule.kind}]`));
         const { cont } = await inquirer.prompt({
@@ -3877,9 +4055,22 @@ async function generateCodeMap(options) {
         const textOutput = mapGenerator.formatAsText(completeCodeMap, mapOptions);
         // Output results
         if (options.output) {
-            // Save to file
-            await fs.writeFile(options.output, textOutput);
-            console.log(chalk.green(`✓ Code map saved to: ${options.output}`));
+            // Save to file. Refuse to clobber an existing file unless --overwrite is
+            // passed — same guard as the report writer, so `map -o` cannot silently
+            // destroy a file the developer did not consent to replacing.
+            const outPath = resolve(options.output);
+            let exists = false;
+            try {
+                await fs.access(outPath);
+                exists = true;
+            }
+            catch { /* ok */ }
+            if (exists && !options.overwrite) {
+                console.error(chalk.red(`Refusing to overwrite existing file ${outPath} — pass --overwrite to replace it.`));
+                process.exit(1);
+            }
+            await fs.writeFile(outPath, textOutput);
+            console.log(chalk.green(`✓ Code map saved to: ${outPath}`));
             // Show summary
             console.log('');
             console.log(chalk.blue('Summary:'));
@@ -3919,7 +4110,7 @@ async function runSearch(query, options) {
     await db.initialize();
     // --definition: look up a specific symbol
     if (options.definition) {
-        const func = await db.findDefinition(query);
+        const func = await db.functionIndex.findDefinition(query);
         if (!func) {
             console.log(chalk.yellow(`No definition found for "${query}"`));
             return;
@@ -3931,9 +4122,6 @@ async function runSearch(query, options) {
             console.log(chalk.blue(`\nDefinition: ${func.name}`));
             console.log(chalk.gray('──────────────────────────────────────────'));
             console.log(`${chalk.bold('File:')} ${func.filePath}${func.lineNumber ? `:${func.lineNumber}` : ''}`);
-            if (func.signature) {
-                console.log(`${chalk.bold('Signature:')} ${func.signature}`);
-            }
             if (func.purpose) {
                 console.log(`${chalk.bold('Purpose:')} ${func.purpose}`);
             }
@@ -3965,7 +4153,7 @@ async function runSearch(query, options) {
         }
         searchOptions.filters.language = options.language;
     }
-    const result = await db.searchFunctions(searchOptions);
+    const result = await db.search.searchFunctions(searchOptions);
     if (options.json) {
         process.stdout.write(JSON.stringify({
             query,
@@ -3988,9 +4176,6 @@ async function runSearch(query, options) {
                 const lang = func.language ? chalk.dim(` [${func.language}]`) : '';
                 const lineInfo = func.lineNumber ? chalk.dim(`:${func.lineNumber}`) : '';
                 console.log(`${chalk.bold(func.name)}${lang} — ${chalk.green(func.filePath)}${lineInfo}`);
-                if (func.signature) {
-                    console.log(chalk.dim(`  ${func.signature}`));
-                }
                 if (func.purpose) {
                     console.log(chalk.dim(`  ${func.purpose}`));
                 }