code-auditor-mcp 3.6.0 → 3.8.0

package/dist/cli.js

@@ -139,6 +139,20 @@ program
         });
         const violations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
         const baseline = result.metadata?.baseline;
+        // ── 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`));
+        }
         // ── Delta output (Spec 18 R2) ─────────────────────────────────
         if (baseline && !options.full) {
             const newViolations = violations.filter((v) => v.new === true);
@@ -155,7 +169,7 @@ program
                     : '(unchanged)';
             console.log(`\n📊 Delta: +${newViolations.length} new · −${fixedCount} fixed · ${knownCount} known  ${trendIcon} ${trendLabel}`);
             if (newViolations.length > 0) {
-                console.log(chalk.gray(`\n── New Findings (${newViolations.length}) ──────────────────────────`));
+                console.log(chalk.gray(`\n── New readings (${newViolations.length}) ──────────────────────────`));
                 for (const v of newViolations) {
                     const icon = v.severity === 'critical' ? '🔴' :
                         v.severity === 'warning' ? '🟡' : '🔵';
@@ -163,9 +177,9 @@ program
                 }
             }
             else {
-                console.log(chalk.green('\n✓ No new findings since last baseline.'));
+                console.log(chalk.green('\n✓ No new readings since last baseline.'));
                 if (knownCount > 0) {
-                    console.log(chalk.gray(`  ${knownCount} known finding(s) are still open — recorded, not fixed.`));
+                    console.log(chalk.gray(`  ${knownCount} known reading(s) are still open — recorded, not resolved.`));
                 }
             }
             // Debt by analyzer
@@ -195,26 +209,26 @@ program
                 .sort((a, b) => b[1] - a[1])
                 .slice(0, 5);
             for (const [file, count] of topFiles) {
-                console.log(`${file} — ${count} finding${count !== 1 ? 's' : ''}`);
+                console.log(`${file} — ${count} reading${count !== 1 ? 's' : ''}`);
             }
-            console.log(chalk.gray(`\n💡 Run ${chalk.cyan('code-audit --full')} to see all ${currentDebt.toLocaleString()} findings.`));
+            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} violations`);
+            console.log(`\nFound ${result.summary.totalViolations} readings`);
             console.log(`Critical: ${result.summary.criticalIssues}`);
             console.log(`Warnings: ${result.summary.warnings}`);
             console.log(`Suggestions: ${result.summary.suggestions}`);
-            console.log(chalk.gray(`\nEvery finding is a defect to resolve — severity ranks urgency, never whether a finding is real.`));
+            console.log(chalk.gray(`\nEvery reading is a measurement, not a verdict — severity is triage, 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} violations`);
+            console.log(`\nFound ${result.summary.totalViolations} readings`);
             console.log(`Critical: ${result.summary.criticalIssues}`);
             console.log(`Warnings: ${result.summary.warnings}`);
             console.log(`Suggestions: ${result.summary.suggestions}`);
-            console.log(chalk.gray(`\nEvery finding is a defect to resolve — severity ranks urgency, never whether a finding is real.`));
+            console.log(chalk.gray(`\nEvery reading is a measurement, not a verdict — severity is triage, the order to act.`));
         }
         // Spec 44 R4 — file accounting: analyzed/dropped totals + optional breakdown.
         printFileAccounting(result, !!options.explainSkipped);
@@ -296,7 +310,7 @@ program
                     }
                 }
                 if (unassessed.length > 0) {
-                    console.log(chalk.gray(`  ── Unassessed (zero findings, applicability unknown) ──`));
+                    console.log(chalk.gray(`  ── Unassessed (zero readings, applicability unknown) ──`));
                     for (const c of unassessed) {
                         console.log(`    ${c.ruleId} (0)`);
                     }
@@ -308,7 +322,7 @@ program
         const builtinCapped = Object.values(result.analyzerResults)
             .reduce((count, ar) => count + ar.violations.filter(v => v.profile === 'scripts-and-tests').length, 0);
         if (builtinCapped > 0) {
-            console.log(chalk.blue(`\nℹ️  ${builtinCapped.toLocaleString()} findings capped by built-in profile "scripts-and-tests" (scripts/tests/fixtures → suggestion).`));
+            console.log(chalk.blue(`\nℹ️  ${builtinCapped.toLocaleString()} readings capped by built-in profile "scripts-and-tests" (scripts/tests/fixtures → suggestion).`));
             console.log(chalk.gray(`   Set ${chalk.cyan('"builtin": false')} in .codeauditor.json to disable.`));
         }
         // Generate formatted report if --format is specified
@@ -333,7 +347,7 @@ program
             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} findings added without re-baselining.`));
+                console.error(chalk.red(`Debt regression: ${currentDebt - snapshotDebt} readings added without re-baselining.`));
                 process.exit(2);
             }
         }
@@ -392,7 +406,6 @@ program
     .option('-p, --path <projectPath>', 'Project root path', process.cwd())
     .action(async (paths, options) => {
     try {
-        await initParsers();
         const fileSet = new Set();
         // Collect paths from stdin if requested
         if (options.stdin) {
@@ -413,18 +426,43 @@ program
         }
         // Resolve scope
         let scope = 'changed';
+        let resolvedPaths = [];
         if (fileSet.size > 0) {
             // Convert to absolute paths
-            const resolved = [...fileSet].map((f) => isAbsolute(f) ? f : resolve(process.cwd(), f));
-            scope = resolved;
+            resolvedPaths = [...fileSet].map((f) => isAbsolute(f) ? f : resolve(process.cwd(), f));
+            scope = resolvedPaths;
+        }
+        // R2 — resolve to a live daemon first (fast path); fall back in-process.
+        // The daemon serves per-file diagnostics for exactly the changed set. It is
+        // only trusted when ready and none of the queried files are stale (R4): a
+        // just-edited file whose re-audit hasn't landed falls through in-process so
+        // the gate never misses a finding. SARIF needs full run metadata, so it
+        // always runs in-process.
+        const projectRoot = resolve(options.path || process.cwd());
+        let result;
+        if (resolvedPaths.length > 0 && options.format !== 'sarif') {
+            const { resolveDaemon, readDaemonDiagnostics } = await import('./daemon/resolve.js');
+            const daemon = await resolveDaemon(projectRoot);
+            if (daemon.mode === 'not-ready') {
+                reportDaemonIndexing(daemon.state, !!options.json);
+                return;
+            }
+            if (daemon.mode === 'ready') {
+                const diag = await readDaemonDiagnostics(daemon.socketPath, resolvedPaths);
+                if (diag && diag.status === 'ready' && diag.staleFiles.length === 0) {
+                    result = await buildChangedResultFromDiagnostics(diag.diagnostics, projectRoot);
+                }
+            }
+        }
+        if (!result) {
+            await initParsers();
+            const runner = createAuditRunner({
+                projectRoot: options.path,
+                scope,
+                analyzerConcurrency: 4
+            });
+            result = await runner.run();
         }
-        // Create runner
-        const runner = createAuditRunner({
-            projectRoot: options.path,
-            scope,
-            analyzerConcurrency: 4
-        });
-        const result = await runner.run();
         // Collect all violations
         const violations = Object.values(result.analyzerResults).flatMap((r) => r.violations || []);
         // Blocking gate decision (Spec 45 R1/R2/R4), computed once so the
@@ -459,7 +497,7 @@ program
                 const col = v.column ?? v.start?.column ?? 1;
                 return {
                     analyzer: v.analyzer || '',
-                    rule: v.rule || v.type || '',
+                    rule: v.rule,
                     severity: v.severity,
                     message: v.message,
                     file: filePath,
@@ -497,7 +535,7 @@ program
                 }
             }
             else {
-                console.log(chalk.green('\n✓ No findings.'));
+                console.log(chalk.green('\n✓ No readings.'));
             }
         }
         // Spec 38 R2/R3 — per-rule timing + gate wall-clock, opt-in by env var.
@@ -572,7 +610,7 @@ function summarizeFindings(violations) {
         bySeverity.set(severity, (bySeverity.get(severity) ?? 0) + 1);
         const analyzer = v.analyzer ?? 'unknown';
         byAnalyzer.set(analyzer, (byAnalyzer.get(analyzer) ?? 0) + 1);
-        const rule = v.rule || v.type || 'unknown';
+        const rule = v.rule;
         byRule.set(rule, (byRule.get(rule) ?? 0) + 1);
     }
     return { bySeverity, byAnalyzer, byRule };
@@ -590,6 +628,32 @@ function printCountSummary(violations) {
     console.log(`by analyzer: ${groupedCounts(byAnalyzer)}`);
     console.log(`by rule: ${groupedCounts(byRule)}`);
 }
+/**
+ * Reconstruct a `changed`-compatible result from daemon-served diagnostics so the
+ * gate/output logic below stays identical to the in-process path. Gate severities
+ * are read from the project config (one JSON file, no parsing) so a custom
+ * `gateSeverities` never diverges from what the in-process run would have used.
+ */
+async function buildChangedResultFromDiagnostics(violations, projectRoot) {
+    const analyzerResults = {};
+    for (const v of violations) {
+        const key = v.analyzer || 'unknown';
+        (analyzerResults[key] = analyzerResults[key] || { violations: [] }).violations.push(v);
+    }
+    let configUsed;
+    try {
+        const { findConfigFileUp, loadConfig } = await import('./config/configLoader.js');
+        const configPath = await findConfigFileUp(projectRoot);
+        const config = await loadConfig({ configPath: configPath ?? undefined });
+        if (Array.isArray(config.gateSeverities) && config.gateSeverities.length > 0) {
+            configUsed = { gateSeverities: config.gateSeverities };
+        }
+    }
+    catch {
+        // No config — the gate falls back to DEFAULT_BLOCKING_SEVERITIES, matching in-process.
+    }
+    return { analyzerResults, metadata: { configUsed, 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
 // *blocking* (critical/warning) findings in the self-audit scope — the same
@@ -621,7 +685,7 @@ function isSelfAuditInScope(file) {
 }
 program
     .command('self-audit [paths...]')
-    .description('Audit the tool\'s own analyzers/ + languages/ source and fail on blocking findings')
+    .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())
@@ -685,7 +749,7 @@ program
                 }
                 return {
                     analyzer: v.analyzer || '',
-                    rule: v.rule || v.type || '',
+                    rule: v.rule,
                     severity: v.severity,
                     message: v.message,
                     file: filePath,
@@ -702,7 +766,7 @@ program
         }
         else if (blocking.length > 0) {
             // Spec 45 A2 — counts plus findings (per analyzer/rule/severity).
-            console.log(chalk.red('\nSelf-audit blocking findings:'));
+            console.log(chalk.red('\nSelf-audit blocking readings:'));
             printCountSummary(blocking);
             for (const v of blocking) {
                 const icon = v.severity === 'critical' ? '🔴' :
@@ -711,7 +775,7 @@ program
             }
         }
         else {
-            console.log(chalk.green('\n✓ Self-audit clean — zero blocking findings in scope.'));
+            console.log(chalk.green('\n✓ Self-audit clean — zero blocking readings in scope.'));
         }
         if (blocking.length > 0)
             process.exit(2);
@@ -732,88 +796,110 @@ program
 // skipping the file.
 program
     .command('next-file')
-    .description('Audit and return the highest-priority file with findings (file-by-file refactor loop)')
+    .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('--json', 'Output a single JSON object (or {done:true}) to stdout')
     .action(async (options) => {
     try {
+        const projectDir = resolve(options.path || process.cwd());
+        // R2 — resolve to a live daemon first; fall back in-process when absent.
+        // The daemon is an optimisation: a ready daemon serves the current ranking
+        // without re-auditing, and an indexing daemon reports its status (R3).
+        const { resolveDaemon, readDaemonFindings } = await import('./daemon/resolve.js');
+        const daemon = await resolveDaemon(projectDir);
+        if (daemon.mode === 'not-ready') {
+            reportDaemonIndexing(daemon.state, !!options.json);
+            return;
+        }
+        if (daemon.mode === 'ready') {
+            const findings = await readDaemonFindings(daemon.socketPath);
+            if (findings && findings.status === 'ready' && findings.staleFiles.length === 0) {
+                const { summarizeViolations } = await import('./nextFileIncremental.js');
+                printNextFile(findings.violations, summarizeViolations(findings.violations), projectDir, !!options.json);
+                return;
+            }
+            // Daemon fell behind (R4) or vanished — fall through to in-process.
+        }
         await initParsers();
         const { violations, summary } = await runNextFile({
             projectRoot: options.path,
             configName: options.config,
         });
-        // Rank files worst-first from the (incrementally-merged) violation set.
-        const ranked = rankFilesByPriority(violations);
-        if (ranked.length === 0) {
-            if (options.json) {
-                process.stdout.write(JSON.stringify({ done: true, summary }, null, 2) + '\n');
-            }
-            else {
-                console.log(chalk.green('\n✓ No findings — nothing left to refactor.'));
-            }
-            return;
-        }
-        const top = ranked[0];
-        // Every issue on the file, ordered critical → warning → suggestion.
-        const ordered = orderFindingsWithinFile(top.violations);
-        const projectDir = resolve(options.path || process.cwd());
-        const relativize = (filePath) => {
-            if (!filePath)
-                return '';
-            if (filePath.startsWith('/') || filePath.startsWith('\\\\')) {
-                const rel = relative(projectDir, filePath);
-                if (!rel.startsWith('..') && !isAbsolute(rel))
-                    return rel;
-            }
-            return filePath;
-        };
-        if (options.json) {
-            const output = {
-                done: false,
-                file: relativize(top.file),
-                remainingFiles: ranked.length - 1,
-                remainingFindings: violations.length - top.count,
-                summary,
-                findings: ordered.map((v) => ({
-                    analyzer: v.analyzer || '',
-                    rule: v.rule || v.type || '',
-                    severity: v.severity,
-                    message: v.message,
-                    file: relativize(v.file || ''),
-                    line: v.line ?? v.start?.line,
-                    column: v.column ?? v.start?.column ?? 1,
-                    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 }),
-                })),
-            };
-            process.stdout.write(JSON.stringify(output, null, 2) + '\n');
-        }
-        else {
-            console.log(chalk.blue('🔍 Next File to Refactor'));
-            console.log(chalk.gray('══════════════════════════════════════════════════'));
-            console.log(`\n${chalk.bold(relativize(top.file))} — ${top.count} finding(s), highest severity ${top.maxSeverity}`);
-            console.log(chalk.gray(`${ranked.length - 1} more file(s) with findings · ${violations.length - top.count} remaining finding(s)`));
-            console.log(chalk.gray('\n── Findings ────────────────────────────────────────'));
-            for (const v of ordered) {
-                const icon = v.severity === 'critical' ? '🔴' : v.severity === 'warning' ? '🟡' : '🔵';
-                console.log(`${icon} ${chalk.bold(relativize(v.file || ''))}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.rule} — ${v.message}`);
-            }
-        }
+        printNextFile(violations, summary, projectDir, !!options.json);
     }
     catch (error) {
         console.error(chalk.red('Error:'), error);
         process.exit(1);
     }
 });
+/** Rank the violation set and emit the `next-file` result (shared by both paths). */
+function printNextFile(violations, summary, projectDir, json) {
+    // Rank files worst-first from the (incrementally-merged) violation set.
+    const ranked = rankFilesByPriority(violations);
+    if (ranked.length === 0) {
+        if (json) {
+            process.stdout.write(JSON.stringify({ done: true, summary }, null, 2) + '\n');
+        }
+        else {
+            console.log(chalk.green('\n✓ No readings — nothing left to refactor.'));
+        }
+        return;
+    }
+    const top = ranked[0];
+    // Every issue on the file, ordered critical → warning → suggestion.
+    const ordered = orderFindingsWithinFile(top.violations);
+    const relativize = (filePath) => {
+        if (!filePath)
+            return '';
+        if (filePath.startsWith('/') || filePath.startsWith('\\\\')) {
+            const rel = relative(projectDir, filePath);
+            if (!rel.startsWith('..') && !isAbsolute(rel))
+                return rel;
+        }
+        return filePath;
+    };
+    if (json) {
+        const output = {
+            done: false,
+            file: relativize(top.file),
+            remainingFiles: ranked.length - 1,
+            remainingFindings: violations.length - top.count,
+            summary,
+            findings: ordered.map((v) => ({
+                analyzer: v.analyzer || '',
+                rule: v.rule,
+                severity: v.severity,
+                message: v.message,
+                file: relativize(v.file || ''),
+                line: v.line ?? v.start?.line,
+                column: v.column ?? v.start?.column ?? 1,
+                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 }),
+            })),
+        };
+        process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    }
+    else {
+        console.log(chalk.blue('🔍 Next File to Refactor'));
+        console.log(chalk.gray('══════════════════════════════════════════════════'));
+        console.log(`\n${chalk.bold(relativize(top.file))} — ${top.count} reading(s), highest severity ${top.maxSeverity}`);
+        console.log(chalk.gray(`${ranked.length - 1} more file(s) with readings · ${violations.length - top.count} remaining reading(s)`));
+        console.log(chalk.gray('\n── Readings ────────────────────────────────────────'));
+        for (const v of ordered) {
+            const icon = v.severity === 'critical' ? '🔴' : v.severity === 'warning' ? '🟡' : '🔵';
+            console.log(`${icon} ${chalk.bold(relativize(v.file || ''))}${v.line ? `:${v.line}` : ''} [${v.severity}] ${v.rule} — ${v.message}`);
+        }
+    }
+}
 // Baseline command (Spec 18 R1)
 program
     .command('baseline')
-    .description('Snapshot current advisory findings as the baseline (excludes invariants)')
+    .description('Snapshot current advisory readings as the baseline (excludes invariants)')
     .option('-p, --path <path>', 'Project path', process.cwd())
     .option('--json', 'Output as JSON')
     .action(async (options) => {
@@ -864,7 +950,7 @@ program
             const absorbed = diff?.absorbed ?? newBaseline.entries.length;
             const fixed = diff?.fixed ?? 0;
             const totalKnown = newBaseline.entries.length;
-            console.log(chalk.green(`\n✓ Baseline updated: ${absorbed} finding${absorbed !== 1 ? 's' : ''} absorbed, ${fixed} fixed, ${totalKnown} total known.`));
+            console.log(chalk.green(`\n✓ Baseline updated: ${absorbed} reading${absorbed !== 1 ? 's' : ''} absorbed, ${fixed} fixed, ${totalKnown} total known.`));
             console.log(chalk.gray('Invariants excluded (they always enforce).'));
             if (totalKnown > 0) {
                 console.log(chalk.gray(`\nRun ${chalk.cyan('code-audit')} to see your delta view.`));
@@ -2030,7 +2116,7 @@ ledgerCmd
 });
 ledgerCmd
     .command('trends')
-    .description('Compare consecutive full-audit runs and report new vs fixed findings per rule')
+    .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')
     .action(async (options) => {
@@ -2948,9 +3034,9 @@ program
 // tracked count, no state that can drift from the code.
 program
     .command('outstanding')
-    .description('List outstanding findings, re-derived from the codebase (never a stored list)')
+    .description('List outstanding readings, re-derived from the codebase (never a stored list)')
     .option('-p, --path <path>', 'Path to audit', process.cwd())
-    .option('--json', 'Output findings as machine-readable JSON')
+    .option('--json', 'Output readings as machine-readable JSON')
     .action(async (options) => {
     try {
         await initParsers();
@@ -2985,7 +3071,7 @@ program
                         filePath = rel;
                 }
                 return {
-                    rule: v.rule || v.type || '',
+                    rule: v.rule,
                     analyzer: v.analyzer || '',
                     severity: v.severity,
                     file: filePath,
@@ -3020,6 +3106,143 @@ function renderBar(value, width) {
     const color = value > 0.8 ? chalk.green : value > 0.5 ? chalk.yellow : chalk.red;
     return color('█'.repeat(filled) + '░'.repeat(empty));
 }
+// ── Daemon command (Spec 50) ────────────────────────────────────────────
+// The daemon is an optimisation, never a dependency (R2). These commands start,
+// stop, and inspect it. The hot-path reads — `changed` (the hook gate) and
+// `next-file` (the refactor loop) — resolve to a live daemon and fall back
+// in-process when it is absent. `audit` stays in-process on purpose: it emits
+// full reports (baseline, recommendations, per-category SARIF/HTML) that need
+// the complete analyzer results, which the daemon does not serve over its
+// findings face (it serves the flattened violation set).
+const DAEMON_NOT_READY_EXIT_CODE = 3;
+/** R3 — a query while the seed is still running: the status is the answer. */
+function reportDaemonIndexing(state, json) {
+    const progress = state?.progress;
+    const filesIndexed = progress?.filesIndexed ?? 0;
+    const filesTotal = progress?.filesTotal ?? 0;
+    const phase = progress?.phase ?? 'files';
+    const retryAfterMs = state?.retryAfterMs ?? null;
+    const throughputUnknown = state?.throughputUnknown ?? false;
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            status: 'indexing',
+            progress: { filesIndexed, filesTotal, phase },
+            retryAfterMs,
+            throughputUnknown,
+        }, null, 2) + '\n');
+    }
+    else {
+        const retry = retryAfterMs != null
+            ? `try again in ~${Math.max(1, Math.round(retryAfterMs / 1000))}s`
+            : 'check back shortly';
+        const phaseDetail = phase === 'files'
+            ? `${filesIndexed} of ${filesTotal} files`
+            : `${phase} phase`;
+        console.log(chalk.yellow(`⏳ Daemon indexing — ${phaseDetail}; ${retry}.`));
+    }
+    process.exit(DAEMON_NOT_READY_EXIT_CODE);
+}
+const daemonCmd = program
+    .command('daemon')
+    .description('Manage the per-project code-auditor daemon (Spec 50)')
+    .action(() => {
+    console.log(chalk.yellow('Use a daemon subcommand:'));
+    console.log(chalk.gray('  code-audit daemon start [--foreground]   Start the daemon for this project'));
+    console.log(chalk.gray('  code-audit daemon stop                   Ask the daemon to shut down'));
+    console.log(chalk.gray('  code-audit daemon status                 Show daemon status'));
+});
+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('--foreground', 'Run in the foreground (blocking; useful for debugging)')
+    .action(async (options) => {
+    try {
+        const { resolveDaemonSocketPath } = await import('./dataPaths.js');
+        const { isDaemonListening } = await import('./daemon/socketClient.js');
+        const projectRoot = resolve(options.path);
+        const socketPath = resolveDaemonSocketPath(projectRoot);
+        if (await isDaemonListening(socketPath)) {
+            console.log(chalk.green('✓ Daemon already running.'));
+            return;
+        }
+        if (options.foreground) {
+            const { runDaemonForeground } = await import('./daemon/main.js');
+            await runDaemonForeground({ projectRoot, configName: options.config, foreground: true });
+            return;
+        }
+        const { startDaemonDetached } = await import('./daemon/resolve.js');
+        startDaemonDetached(projectRoot, options.config);
+        console.log(chalk.green('✓ Daemon started (detached).'));
+        console.log(chalk.gray(`  Socket: ${socketPath}`));
+        console.log(chalk.gray('  It indexes on startup — `code-audit daemon status` to watch.'));
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+daemonCmd
+    .command('stop')
+    .description('Ask the daemon to shut down')
+    .option('-p, --path <path>', 'Project root', process.cwd())
+    .action(async (options) => {
+    try {
+        const { resolveDaemonSocketPath } = await import('./dataPaths.js');
+        const { isDaemonListening } = await import('./daemon/socketClient.js');
+        const { requestDaemonShutdown } = await import('./daemon/resolve.js');
+        const socketPath = resolveDaemonSocketPath(resolve(options.path));
+        if (!(await isDaemonListening(socketPath))) {
+            console.log(chalk.gray('No daemon running.'));
+            return;
+        }
+        await requestDaemonShutdown(socketPath);
+        console.log(chalk.green('✓ Shutdown requested.'));
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
+daemonCmd
+    .command('status')
+    .description('Show daemon status')
+    .option('-p, --path <path>', 'Project root', process.cwd())
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+    try {
+        const { resolveDaemon } = await import('./daemon/resolve.js');
+        const { resolveDaemonSocketPath } = await import('./dataPaths.js');
+        const projectRoot = resolve(options.path);
+        const resolved = await resolveDaemon(projectRoot);
+        const socketPath = resolveDaemonSocketPath(projectRoot);
+        if (options.json) {
+            process.stdout.write(JSON.stringify({
+                running: resolved.mode !== 'absent',
+                mode: resolved.mode,
+                socketPath,
+                ...(resolved.state && { state: resolved.state }),
+            }, null, 2) + '\n');
+            return;
+        }
+        if (resolved.mode === 'absent') {
+            console.log(chalk.gray('No daemon running.'));
+            console.log(chalk.gray('Start one: code-audit daemon start'));
+            return;
+        }
+        if (resolved.mode === 'not-ready') {
+            reportDaemonIndexing(resolved.state, false);
+            return;
+        }
+        console.log(chalk.green('✓ Daemon ready.'));
+        console.log(chalk.gray(`  Socket: ${socketPath}`));
+    }
+    catch (error) {
+        console.error(chalk.red('Error:'), error);
+        process.exit(1);
+    }
+});
 // Parse command line arguments
 program.parse(process.argv);
 // If no command was provided, show help
@@ -3174,7 +3397,7 @@ async function generateConfigurations(options) {
     console.log(chalk.blue('\nNext steps:'));
     console.log(chalk.gray('  1. Edit .codeauditor.json to match your codebase conventions'));
     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 findings)'));
+    console.log(chalk.gray('  3. Use ') + chalk.cyan('code-audit changed') + chalk.gray(' in your agent hook (gating rules block on new readings)'));
 }
 /**
  * Interactive rule builder — walks the user through adding rules one at a time.