@fraction12/deepclean 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/cli.js

@@ -1,27 +1,47 @@
 #!/usr/bin/env node
+import { execFile } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagBoolean, flagString } from "./args.js";
 import { candidatesFromEvidence, rankCandidates, reassignCandidateIds } from "./candidates.js";
 import { buildClusters, unclusteredCandidateIds } from "./clusters.js";
 import { discoverSourceFiles } from "./discovery.js";
 import { runEvidenceAdapters } from "./evidence.js";
+import { mapSemanticFeatures } from "./features.js";
+import { attachStableIdentity } from "./identity.js";
 import { fail, ok } from "./json.js";
+import { LockContentionError, lockRecoveryCommand, readLockStatuses, recoverStaleLocks, withStateWriteLock, } from "./locks.js";
 import { buildCandidatePlan, buildClusterPlan } from "./plans.js";
+import { classifyRevalidation } from "./revalidation.js";
 import { buildHandoff, buildReportRecord, renderMarkdownReport, renderMarkdownReportWithClusters, } from "./reporting.js";
-import { ensureState, latestRunId, readLatestCandidates, readLatestClusters, readLatestEvidence, resolveStatePaths, updateLatestCandidates, writeCandidates, writeClusters, writeEvidence, writeHandoff, writePlan, writeReport, writeRun, writeTriage, } from "./state.js";
+import { ensureState, latestRunId, readConfig, readCandidates, readFindings, readLatestCandidates, readLatestClusters, readLatestEvidence, readLatestFeatures, readLatestSynthesisAttempt, readLifecycleEvents, resolveStatePaths, updateLatestCandidates, writeCandidates, writeCandidateObservations, writeCiRun, writeClusters, writeEvidence, writeFeatures, writeFindings, writeFixAttempt, writeHandoff, writeLifecycleEvents, writePlan, writeReport, writeRetentionManifest, writeRevalidation, writeRun, writeSynthesisAttempt, writeTriage, } from "./state.js";
 import { candidateStatuses, schemaVersion, } from "./types.js";
 import { timestampId } from "./ids.js";
 import { synthesizeWithCodex } from "./synthesis.js";
 import { inferVerificationProfile } from "./verification.js";
+const execFileAsync = promisify(execFile);
 const commands = [
     "init",
+    "doctor",
+    "status",
+    "ci",
+    "map",
     "scan",
     "report",
     "next",
+    "list",
+    "findings",
     "show",
+    "explain",
+    "history",
+    "revalidate",
+    "unlock",
+    "prune",
+    "scrub",
+    "fix",
     "cluster",
     "plan",
     "triage",
@@ -29,25 +49,71 @@ const commands = [
     "export",
 ];
 function printHelp() {
-    console.log(`deepclean: agent-first cleanup reports for working-but-sloppy codebases
+    console.log(`deepclean: local structure reports and agent-ready plans
 
 Usage:
   deepclean <command> [args] [flags]
 
 Commands:
   init                         Create or validate .deepclean state
+  doctor                       Check environment, config, state, git, provider, and privacy readiness
+  status                       Summarize current project-local Deepclean state
+  ci                           Run non-interactive scan and policy gates for CI
+  map                          Write semantic feature records without producing candidates
   scan                         Collect local evidence and generate candidates
-    --synthesize               Run local Codex synthesis over evidence
+    --synthesize               Run local Codex synthesis over evidence (default)
+    --evidence-only            Skip synthesis and produce local evidence candidates only
     --allow-source-in-model    Include source samples in Codex prompt
+    --offline                  Skip provider calls and network-style analyzers
+    --local-only               Alias for --offline
+    --provider <provider>      Provider adapter, currently codex
     --model <model>            Override Codex model for synthesis
+    --effort <effort>          Record provider reasoning effort
+    --timeout <seconds>        Provider timeout in seconds
+    --retries <n>              Provider retry attempts
+    --rpm <n>                  Provider request-per-minute budget
+    --concurrency <n>          Provider concurrency budget
+    --token-budget <n>         Provider token budget metadata
+    --excerpt-budget <n>       Source excerpt budget; 0 keeps prompts metadata-only
+    --privacy-mode <mode>      local-only, metadata, or source-ok
+    --since <ref>              Scan files changed since a git ref
+    --merge-base <ref>         Use merge-base with ref for changed-file scope
+    --include-dirty            Include uncommitted and untracked files in scope
+    --paths <a,b>              Restrict scan to paths or path prefixes
+    --categories <a,b>         Restrict emitted candidates to categories
+    --reviewers <a,b>          Record reviewer-surface scope for synthesis/metadata
+    --only-existing            Keep only findings previously known to Deepclean
+    --new-only                 Keep only newly discovered findings
   report                       Write and print a ranked report
   next                         Show the highest-priority open candidate
+  list                         List findings with shared filters
+  findings                     Alias for list
   show <candidate-or-theme>    Show one candidate or cleanup theme with evidence
+  explain <candidate-or-finding>
+                               Explain evidence, validation, and fix-readiness for a finding
+  history <finding-or-candidate-id>
+                               Show lifecycle history for a finding
+  revalidate <finding-id|candidate-id|all>
+                               Freshly recheck whether findings still hold
+  unlock --stale               Remove stale project-local writer locks
+  prune                       Remove stale Deepclean artifacts with retention safety
+    --dry-run                  Persist a manifest without deleting files
+    --keep-runs <n>            Keep latest n runs, defaults to 5
+    --keep-days <n>            Also keep runs newer than n days
+  scrub                        Emit source-safe generated-state export
+  fix <finding-or-candidate>   Preview or apply a guarded local patch
+    --patch <file>             Patch file to preview/apply
+    --dry-run                  Persist preview without changing source
+    --apply                    Apply the patch locally
+    --allow-source-mutation    Required with --apply
+    --allow-dirty              Allow dirty files inside target scope
+    --verification-command <c> Override verification command
   cluster [theme-id]           Group related candidates into cleanup themes
   plan <candidate-or-theme>    Generate an agent-ready cleanup plan
   triage <candidate-id>        Update candidate status with --status and --note
   handoff <candidate-id>       Generate an agent-ready handoff packet
   export <candidate-id>        Alias for handoff
+  export --source-safe         Alias for scrub
 
 Global flags:
   --json                       Emit JSON envelope
@@ -58,6 +124,8 @@ Global flags:
   --config <path>              Config file, defaults to .deepclean/config.json
   --quiet                      Suppress human success output
   --debug                      Include stack traces for unexpected errors
+  --wait-lock                  Wait for an active writer lock instead of failing immediately
+  --lock-timeout-ms <ms>       Maximum time to wait for --wait-lock
   -h, --help                   Show help
   --version                    Show version`);
 }
@@ -94,28 +162,64 @@ export async function main(argv, cwd = process.cwd()) {
         switch (command) {
             case "init":
                 return await initCommand(context);
+            case "doctor":
+                return await doctorCommand(context);
+            case "status":
+                return await statusCommand(context);
+            case "ci":
+                return await withWriteLock(context, () => ciCommand(context));
+            case "map":
+                return await withWriteLock(context, () => mapCommand(context));
             case "scan":
-                return await scanCommand(context);
+                return await withWriteLock(context, () => scanCommand(context));
             case "report":
-                return await reportCommand(context);
+                return await withWriteLock(context, () => reportCommand(context));
             case "next":
                 return await nextCommand(context);
+            case "list":
+            case "findings":
+                return await listCommand(context);
             case "show":
                 return await showCommand(context);
+            case "explain":
+                return await explainCommand(context);
+            case "history":
+                return await historyCommand(context);
+            case "revalidate":
+                return await withWriteLock(context, () => revalidateCommand(context));
+            case "unlock":
+                return await unlockCommand(context);
+            case "prune":
+                return await withWriteLock(context, () => pruneCommand(context));
+            case "scrub":
+                return await scrubCommand(context);
+            case "fix":
+                return await withWriteLock(context, () => fixCommand(context));
             case "cluster":
-                return await clusterCommand(context);
+                return await withWriteLock(context, () => clusterCommand(context));
             case "plan":
-                return await planCommand(context);
+                return await withWriteLock(context, () => planCommand(context));
             case "triage":
-                return await triageCommand(context);
+                return await withWriteLock(context, () => triageCommand(context));
             case "handoff":
+                return await withWriteLock(context, () => handoffCommand(context));
             case "export":
-                return await handoffCommand(context);
+                if (flagBoolean(context.parsed.flags, "source-safe")) {
+                    return await scrubCommand(context);
+                }
+                return await withWriteLock(context, () => handoffCommand(context));
         }
         emit(json, fail(command, "unknown_command", `Unknown command: ${command}`));
         return 2;
     }
     catch (error) {
+        if (error instanceof LockContentionError) {
+            emit(json, fail(command, "lock_contention", error.message, [error.diagnostic]));
+            if (!json && !quiet) {
+                console.error(error.message);
+            }
+            return 4;
+        }
         const message = error instanceof Error ? error.message : String(error);
         emit(json, fail(command, "command_failed", debug && error instanceof Error && error.stack ? error.stack : message));
         return 1;
@@ -135,12 +239,546 @@ async function initCommand(context) {
     }
     return 0;
 }
+async function doctorCommand(context) {
+    const diagnostics = [];
+    const initialized = await pathExists(context.paths.stateDir);
+    const missingDirs = initialized ? await missingStateDirectories(context.paths) : [];
+    const locks = initialized ? await readLockStatuses(context.paths, {
+        staleAfterMs: staleLockMsFromFlags(context),
+    }) : [];
+    const staleLocks = locks.filter((lock) => lock.stale);
+    const configResult = await readConfigForDoctor(context.paths);
+    diagnostics.push(...configResult.diagnostics);
+    if (missingDirs.length > 0) {
+        diagnostics.push({
+            level: "warning",
+            code: "state_dirs_missing",
+            message: `Missing state directories: ${missingDirs.join(", ")}`,
+        });
+    }
+    if (staleLocks.length > 0) {
+        diagnostics.push({
+            level: "warning",
+            code: "stale_locks",
+            message: `Found ${staleLocks.length} stale writer lock${staleLocks.length === 1 ? "" : "s"}. Run \`${lockRecoveryCommand(context.paths)}\` before the next write command.`,
+        });
+    }
+    const git = await gitDoctor(context.paths.root);
+    if (!git.available) {
+        diagnostics.push({
+            level: "warning",
+            code: "git_unavailable",
+            message: git.error ?? "Git is unavailable for this repository.",
+        });
+    }
+    const provider = configResult.config
+        ? await providerDoctor(context.paths.root, configResult.config.reviewSynthesis.command)
+        : { command: undefined, available: false, error: "Config is unavailable." };
+    if (configResult.config && !provider.available) {
+        diagnostics.push({
+            level: "warning",
+            code: "provider_unavailable",
+            message: provider.error ?? `Provider command is unavailable: ${provider.command}`,
+        });
+    }
+    const data = {
+        root: context.paths.root,
+        stateDir: context.paths.stateDir,
+        initialized,
+        packageVersion: await packageVersion(),
+        config: {
+            path: context.paths.configPath,
+            valid: configResult.valid,
+            error: configResult.error,
+        },
+        state: {
+            valid: initialized && missingDirs.length === 0,
+            missingDirs,
+        },
+        locks: {
+            active: locks.filter((lock) => !lock.stale).length,
+            stale: staleLocks.length,
+            records: locks.map((lock) => ({
+                id: lock.record?.id,
+                owner: lock.record?.owner,
+                pid: lock.record?.pid,
+                command: lock.record?.command,
+                statePath: lock.record?.statePath,
+                createdAt: lock.record?.createdAt,
+                stale: lock.stale,
+                reason: lock.reason,
+                recoveryCommand: lock.recoveryCommand,
+            })),
+        },
+        git,
+        provider,
+        privacy: configResult.config?.privacy,
+        supportedSurfaces: await supportedSurfaces(context.paths.root),
+    };
+    emit(context.json, ok("doctor", data, diagnostics));
+    if (!context.json && !context.quiet) {
+        console.log(`Deepclean ${data.packageVersion}`);
+        console.log(`root: ${data.root}`);
+        console.log(`state: ${data.state.valid ? "ok" : initialized ? "incomplete" : "not initialized"}`);
+        console.log(`config: ${data.config.valid ? "ok" : "invalid"}`);
+        console.log(`git: ${git.available ? git.dirty ? "dirty" : "clean" : "unavailable"}`);
+        console.log(`provider: ${provider.available ? "ok" : "unavailable"}`);
+        console.log(`locks: ${data.locks.active} active / ${data.locks.stale} stale`);
+        printDiagnostics(diagnostics);
+    }
+    return 0;
+}
+async function statusCommand(context) {
+    const diagnostics = [];
+    const initialized = await pathExists(context.paths.stateDir);
+    const latest = initialized ? await latestRunId(context.paths) : undefined;
+    const candidates = latest ? await readLatestCandidates(context.paths) : [];
+    const clusters = latest ? await readLatestClusters(context.paths) : [];
+    const evidence = latest ? await readLatestEvidence(context.paths) : [];
+    const features = initialized ? await readLatestFeatures(context.paths) : [];
+    const git = await gitDoctor(context.paths.root);
+    if (!git.available) {
+        diagnostics.push({
+            level: "warning",
+            code: "git_unavailable",
+            message: git.error ?? "Git is unavailable for this repository.",
+        });
+    }
+    const artifactCounts = await stateArtifactCounts(context.paths);
+    const locks = initialized ? await readLockStatuses(context.paths, {
+        staleAfterMs: staleLockMsFromFlags(context),
+    }) : [];
+    const statusCounts = countBy(candidates, (candidate) => candidate.status);
+    const data = {
+        root: context.paths.root,
+        stateDir: context.paths.stateDir,
+        initialized,
+        latestRunId: latest,
+        git: {
+            branch: git.branch,
+            dirty: git.dirty,
+            available: git.available,
+        },
+        queue: {
+            total: candidates.length,
+            open: candidates.filter((candidate) => candidate.status === "open").length,
+            byStatus: statusCounts,
+            themes: clusters.length,
+            evidence: evidence.length,
+            features: features.length,
+        },
+        locks: {
+            active: locks.filter((lock) => !lock.stale).length,
+            stale: locks.filter((lock) => lock.stale).length,
+            records: locks.map((lock) => ({
+                id: lock.record?.id,
+                owner: lock.record?.owner,
+                pid: lock.record?.pid,
+                command: lock.record?.command,
+                statePath: lock.record?.statePath,
+                createdAt: lock.record?.createdAt,
+                stale: lock.stale,
+                reason: lock.reason,
+                recoveryCommand: lock.recoveryCommand,
+            })),
+        },
+        pendingRevalidation: candidates.filter((candidate) => candidate.lifecycleState === "stale").length,
+        artifacts: artifactCounts,
+    };
+    emit(context.json, ok("status", data, diagnostics));
+    if (!context.json && !context.quiet) {
+        console.log(`root: ${data.root}`);
+        console.log(`state: ${initialized ? "initialized" : "not initialized"}`);
+        console.log(`latest run: ${latest ?? "none"}`);
+        console.log(`queue: ${data.queue.open} open / ${data.queue.total} total`);
+        console.log(`git: ${git.available ? git.dirty ? "dirty" : "clean" : "unavailable"}`);
+        console.log(`locks: ${data.locks.active} active / ${data.locks.stale} stale`);
+        printDiagnostics(diagnostics);
+    }
+    return 0;
+}
+async function unlockCommand(context) {
+    if (!flagBoolean(context.parsed.flags, "stale")) {
+        emit(context.json, fail("unlock", "stale_required", "Only stale lock recovery is supported. Rerun with --stale."));
+        return 2;
+    }
+    const result = await recoverStaleLocks(context.paths, {
+        staleAfterMs: staleLockMsFromFlags(context),
+    });
+    emit(context.json, ok("unlock", {
+        removed: result.removed.map(lockStatusPayload),
+        active: result.active.map(lockStatusPayload),
+        recoveryCommand: lockRecoveryCommand(context.paths),
+    }));
+    if (!context.json && !context.quiet) {
+        console.log(`Removed ${result.removed.length} stale lock${result.removed.length === 1 ? "" : "s"}.`);
+        if (result.active.length > 0) {
+            console.log(`${result.active.length} active lock${result.active.length === 1 ? "" : "s"} left in place.`);
+        }
+    }
+    return result.active.length > 0 ? 4 : 0;
+}
+async function pruneCommand(context) {
+    await ensureState(context.paths);
+    const manifest = await buildRetentionManifest(context);
+    if (!manifest.dryRun) {
+        for (const relativePath of manifest.deletePaths) {
+            await rm(path.resolve(context.paths.root, relativePath), { force: true });
+        }
+    }
+    const manifestPath = await writeRetentionManifest(context.paths, manifest);
+    emit(context.json, ok("prune", {
+        dryRun: manifest.dryRun,
+        manifest,
+        manifestPath,
+        deleteCount: manifest.deletePaths.length,
+        retainedCount: manifest.retainedPaths.length,
+        blockedCount: manifest.blockedPaths.length,
+    }));
+    if (!context.json && !context.quiet) {
+        console.log(`${manifest.dryRun ? "Would delete" : "Deleted"} ${manifest.deletePaths.length} artifact${manifest.deletePaths.length === 1 ? "" : "s"}.`);
+        console.log(`Retention manifest written to ${path.relative(context.paths.root, manifestPath)}`);
+    }
+    return 0;
+}
+async function scrubCommand(context) {
+    const [candidates, clusters, evidence, features] = await Promise.all([
+        readLatestCandidates(context.paths),
+        readLatestClusters(context.paths),
+        readLatestEvidence(context.paths),
+        readLatestFeatures(context.paths),
+    ]);
+    const latest = await latestRunId(context.paths);
+    const output = {
+        schemaVersion,
+        sourceSafe: true,
+        generatedAt: new Date().toISOString(),
+        project: path.basename(context.paths.root),
+        latestRunId: latest,
+        counts: {
+            candidates: candidates.length,
+            clusters: clusters.length,
+            evidence: evidence.length,
+            features: features.length,
+        },
+        candidates: rankCandidates(candidates).map((candidate) => ({
+            id: candidate.id,
+            findingId: candidate.findingId,
+            title: candidate.title,
+            category: candidate.category,
+            status: candidate.status,
+            lifecycleState: candidate.lifecycleState,
+            priority: candidate.priority,
+            confidence: candidate.confidence,
+            impact: candidate.impact,
+            effort: candidate.effort,
+            risk: candidate.risk,
+            baselineStatus: candidate.baselineStatus,
+            evidenceIds: candidate.evidenceIds,
+            files: candidate.files.map((file) => sourceSafeFile(context.paths.root, file)),
+            verification: candidate.verification,
+        })),
+        clusters: clusters.map((cluster) => ({
+            id: cluster.id,
+            title: cluster.title,
+            category: cluster.category,
+            priority: cluster.priority,
+            confidence: cluster.confidence,
+            candidateIds: cluster.candidateIds,
+            evidenceIds: cluster.evidenceIds,
+            files: cluster.files.map((file) => sourceSafeFile(context.paths.root, file)),
+            actionability: cluster.actionability,
+            warnings: cluster.warnings,
+        })),
+        evidence: evidence.map((record) => ({
+            id: record.id,
+            kind: record.kind,
+            title: record.title,
+            files: record.files.map((file) => sourceSafeFile(context.paths.root, file)),
+        })),
+        features: features.map((feature) => ({
+            featureId: feature.featureId,
+            title: feature.title,
+            kind: feature.kind,
+            confidence: feature.confidence,
+            ownedFiles: feature.ownedFiles.map((file) => sourceSafeFile(context.paths.root, file)),
+            testFiles: feature.testFiles.map((file) => sourceSafeFile(context.paths.root, file)),
+            verification: feature.verification,
+            tags: feature.tags,
+        })),
+        privacyNotes: [
+            "Source-safe export omits source excerpts, model prompts, provider payloads, absolute state paths, and generated handoff/plan prose.",
+            "Repository-relative paths are retained so findings remain actionable.",
+        ],
+    };
+    const outputPath = flagString(context.parsed.flags, "output");
+    if (outputPath) {
+        const resolved = path.resolve(context.paths.root, outputPath);
+        await mkdir(path.dirname(resolved), { recursive: true });
+        await writeFile(resolved, `${JSON.stringify(output, null, 2)}\n`, "utf8");
+    }
+    emit(context.json, ok("scrub", {
+        export: output,
+        ...(outputPath ? { outputPath: path.resolve(context.paths.root, outputPath) } : {}),
+    }));
+    if (!context.json && !context.quiet) {
+        console.log(`Source-safe export: ${output.counts.candidates} candidates, ${output.counts.features} features, ${output.counts.evidence} evidence references`);
+        if (outputPath) {
+            console.log(`Export written to ${outputPath}`);
+        }
+    }
+    return 0;
+}
+async function fixCommand(context) {
+    const target = requireCandidateId(context);
+    if (target.startsWith("theme-")) {
+        emit(context.json, fail("fix", "fix_target_too_broad", "Fix execution requires one stable finding or candidate, not a broad theme."));
+        return 2;
+    }
+    const patch = flagString(context.parsed.flags, "patch");
+    if (!patch) {
+        emit(context.json, fail("fix", "patch_required", "--patch is required so Deepclean can preview/apply an explicit local patch."));
+        return 2;
+    }
+    const dryRun = flagBoolean(context.parsed.flags, "dry-run") || !flagBoolean(context.parsed.flags, "apply");
+    const config = await ensureState(context.paths);
+    if (!dryRun && (!config.fixExecution.enabled || !flagBoolean(context.parsed.flags, "allow-source-mutation"))) {
+        emit(context.json, fail("fix", "fix_opt_in_required", "Applying fixes requires fixExecution.enabled=true and --allow-source-mutation."));
+        return 2;
+    }
+    const resolved = await resolveFixTarget(context.paths, target);
+    if (!resolved) {
+        emit(context.json, fail("fix", "finding_not_found", `Finding or candidate not found: ${target}`));
+        return 1;
+    }
+    const blocked = fixReadinessBlocker(resolved.candidate);
+    if (blocked) {
+        emit(context.json, fail("fix", blocked.code, blocked.message));
+        return 2;
+    }
+    const plan = await latestPlanForTarget(context.paths, resolved.candidate.id);
+    if (!plan) {
+        emit(context.json, fail("fix", "fix_plan_required", "Generate a current plan before fixing this finding."));
+        return 2;
+    }
+    const revalidation = await latestRevalidationForFinding(context.paths, resolved.findingId);
+    if (!revalidation || !["unchanged", "changed"].includes(revalidation.outcome)) {
+        emit(context.json, fail("fix", "fix_revalidation_required", "Run revalidation before applying or previewing this fix."));
+        return 2;
+    }
+    const patchPath = path.resolve(context.paths.root, patch);
+    const patchContent = await readFile(patchPath, "utf8");
+    const changedFiles = changedFilesFromPatch(patchContent);
+    if (changedFiles.length === 0) {
+        emit(context.json, fail("fix", "patch_empty", "Patch preview did not contain changed files."));
+        return 2;
+    }
+    const dirty = await dirtyFiles(context.paths.root);
+    const targetPaths = new Set(resolved.candidate.files.map((file) => file.path));
+    const statePrefix = `${relativeStatePath(context.paths, context.paths.stateDir).replace(/\/$/, "")}/`;
+    const patchRelativePath = relativeStatePath(context.paths, patchPath);
+    const dirtyOutsideTarget = dirty.filter((file) => (!targetPaths.has(file)
+        && file !== patchRelativePath
+        && !file.startsWith(statePrefix)));
+    if (!dryRun && dirtyOutsideTarget.length > 0 && !flagBoolean(context.parsed.flags, "allow-dirty")) {
+        emit(context.json, fail("fix", "dirty_tree", `Dirty files outside target scope: ${dirtyOutsideTarget.join(", ")}`));
+        return 2;
+    }
+    const attemptId = timestampId("fix");
+    const patchPreviewPath = path.join(context.paths.fixesDir, `${attemptId}.patch`);
+    await mkdir(context.paths.fixesDir, { recursive: true });
+    await writeFile(patchPreviewPath, patchContent, "utf8");
+    const verificationCommands = verificationCommandsForFix(context, config, resolved.candidate);
+    let status = dryRun ? "previewed" : "unverified";
+    let verificationResults = [];
+    const diagnostics = [];
+    if (!dryRun) {
+        const apply = await execFileAsync("git", ["apply", patchPath], { cwd: context.paths.root, timeout: 30_000 })
+            .then(() => ({ ok: true, error: undefined }))
+            .catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+        if (!apply.ok) {
+            diagnostics.push({ level: "error", code: "patch_apply_failed", message: apply.error ?? "Patch failed to apply." });
+            status = "failed";
+        }
+        else if (verificationCommands.length > 0) {
+            verificationResults = await runFixVerification(context.paths, attemptId, verificationCommands);
+            status = verificationResults.every((result) => result.passed) ? "passed" : "failed";
+        }
+    }
+    const now = new Date().toISOString();
+    const attempt = {
+        schemaVersion,
+        recordType: "fix_attempt",
+        id: attemptId,
+        findingId: resolved.findingId,
+        planId: plan.id,
+        status,
+        dryRun,
+        changedFiles,
+        patchPreviewPath,
+        verificationCommands,
+        verificationResults,
+        diagnostics,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const attemptPath = await writeFixAttempt(context.paths, attempt);
+    await writeLifecycleEvents(context.paths, [
+        {
+            schemaVersion,
+            recordType: "lifecycle_event",
+            id: timestampId("event"),
+            targetType: "fix_attempt",
+            targetId: attempt.id,
+            findingId: resolved.findingId,
+            kind: "fix-attempted",
+            command: "fix",
+            createdAt: now,
+            data: { dryRun, status, changedFiles },
+        },
+        ...(status === "passed" || status === "failed"
+            ? [{
+                    schemaVersion,
+                    recordType: "lifecycle_event",
+                    id: timestampId("event"),
+                    targetType: "fix_attempt",
+                    targetId: attempt.id,
+                    findingId: resolved.findingId,
+                    kind: status === "passed" ? "verification-passed" : "verification-failed",
+                    command: "fix",
+                    createdAt: now,
+                    data: { verificationResults },
+                }]
+            : []),
+    ]);
+    emit(context.json, ok("fix", {
+        attempt,
+        attemptPath,
+        patchPreviewPath,
+        changedFiles,
+        externalSideEffects: [],
+        next: status === "passed" ? "Review local changes and open a PR manually if desired." : "Inspect the fix attempt artifact before continuing.",
+    }, diagnostics));
+    if (!context.json && !context.quiet) {
+        console.log(`${dryRun ? "Previewed" : "Applied"} fix ${attempt.id}: ${status}`);
+    }
+    return status === "failed" ? 3 : 0;
+}
+async function mapCommand(context) {
+    const result = await executeFeatureMap(context);
+    emit(context.json, ok("map", result));
+    if (!context.json && !context.quiet) {
+        console.log(`Mapped ${result.featureCount} semantic feature${result.featureCount === 1 ? "" : "s"}.`);
+        console.log(`Features written to ${path.relative(context.paths.root, result.path)}`);
+    }
+    return 0;
+}
+async function executeFeatureMap(context) {
+    const createdAt = new Date().toISOString();
+    const mapId = timestampId("map");
+    const config = await ensureState(context.paths);
+    const verificationProfile = await inferVerificationProfile(context.paths.root);
+    const discoveredFiles = await discoverSourceFiles(context.paths.root, config.exclude);
+    const scope = await resolveScanScope(context, discoveredFiles);
+    const files = discoveredFiles.filter((file) => fileInScope(file, scope));
+    const features = await mapSemanticFeatures({
+        root: context.paths.root,
+        runId: mapId,
+        createdAt,
+        files,
+        verificationProfile,
+        excludes: config.exclude,
+    });
+    const featurePath = await writeFeatures(context.paths, mapId, features);
+    return {
+        mapId,
+        root: context.paths.root,
+        sourceFileCount: files.length,
+        featureCount: features.length,
+        features,
+        scope,
+        path: featurePath,
+    };
+}
+async function ciCommand(context) {
+    const requireSynthesis = flagBoolean(context.parsed.flags, "require-synthesis");
+    const config = await ensureState(context.paths);
+    if (requireSynthesis && synthesisDisabledByPolicy(context, config)) {
+        const diagnostic = {
+            level: "error",
+            code: "ci_synthesis_required",
+            message: "CI policy requires synthesis; rerun without evidence-only/local-only flags and with a configured provider.",
+        };
+        emit(context.json, fail("ci", "ci_synthesis_required", diagnostic.message, [diagnostic]));
+        return 2;
+    }
+    const scan = await executeScan(context, {});
+    const synthesisFailure = requireSynthesis ? requiredSynthesisFailure(scan) : undefined;
+    if (synthesisFailure) {
+        const diagnostics = [
+            synthesisFailure,
+            ...scan.diagnostics.filter((diagnostic) => !sameSynthesisFailure(diagnostic, synthesisFailure)),
+        ];
+        emit(context.json, fail("ci", "ci_synthesis_failed", synthesisFailure.message, diagnostics));
+        return 2;
+    }
+    const policy = ciPolicyFromFlags(context);
+    const gate = evaluateCiPolicy(scan.data.candidates, policy);
+    const createdAt = new Date().toISOString();
+    const artifactPaths = await writeCiArtifacts(context, scan.data, gate);
+    const ciRun = {
+        schemaVersion,
+        recordType: "ci_run",
+        id: timestampId("ci"),
+        runId: scan.runId,
+        baselineRef: scan.data.scope.since ?? scan.data.scope.mergeBase,
+        status: gate.blockingFindingIds.length > 0 ? "policy-failed" : "passed",
+        policy,
+        blockingFindingIds: gate.blockingFindingIds,
+        artifactPaths,
+        diagnostics: scan.diagnostics,
+        createdAt,
+    };
+    await writeCiRun(context.paths, ciRun);
+    emit(context.json, ok("ci", {
+        ciRun,
+        policy,
+        result: gate,
+        scan: scan.data,
+    }, scan.diagnostics));
+    if (!context.json && !context.quiet) {
+        console.log(`CI ${ciRun.status}: ${gate.blockingFindingIds.length} blocking finding${gate.blockingFindingIds.length === 1 ? "" : "s"}`);
+    }
+    return gate.blockingFindingIds.length > 0 ? 3 : 0;
+}
 async function scanCommand(context) {
+    const result = await executeScan(context, {});
+    emit(context.json, ok("scan", result.data, result.diagnostics));
+    if (!context.json && !context.quiet) {
+        const synthesisText = result.data.synthesis.requested
+            ? `, ${result.data.synthesis.candidateCount} synthesized`
+            : "";
+        console.log(`Scan complete: ${result.data.evidenceCount} evidence records, ${result.data.candidateCount} candidates, ${result.data.clusterCount} clusters${synthesisText}`);
+        printCandidateSummary(result.data.candidates);
+    }
+    return 0;
+}
+async function executeScan(context, options) {
     const startedAt = new Date().toISOString();
     const runId = timestampId("run");
     const config = await ensureState(context.paths);
     const verificationProfile = await inferVerificationProfile(context.paths.root);
-    const files = await discoverSourceFiles(context.paths.root, config.exclude);
+    const discoveredFiles = await discoverSourceFiles(context.paths.root, config.exclude);
+    const scope = await resolveScanScope(context, discoveredFiles);
+    const files = discoveredFiles.filter((file) => fileInScope(file, scope));
+    const features = await mapSemanticFeatures({
+        root: context.paths.root,
+        runId,
+        createdAt: startedAt,
+        files,
+        verificationProfile,
+        excludes: config.exclude,
+    });
     const adapterResult = await runEvidenceAdapters(config.enabledAdapters, {
         root: context.paths.root,
         runId,
@@ -148,32 +786,56 @@ async function scanCommand(context) {
         files,
         config,
     });
+    const evidence = markDirtyTreeEvidence(adapterResult.evidence, scope);
     const completedAt = new Date().toISOString();
-    const localCandidates = candidatesFromEvidence(runId, adapterResult.evidence, completedAt, config.candidateCaps, verificationProfile);
-    const synthesisRequested = flagBoolean(context.parsed.flags, "synthesize")
-        || config.reviewSynthesis.enabled;
-    const synthesisResult = synthesisRequested
+    const localCandidates = candidatesFromEvidence(runId, evidence, completedAt, config.candidateCaps, verificationProfile);
+    const synthesisRequested = options.synthesize ?? true;
+    const runtime = providerRuntimeControls(context, config);
+    if (synthesisRequested && runtime.offline) {
+        adapterResult.diagnostics.push({
+            level: "info",
+            code: "synthesis_skipped_by_policy",
+            message: "Provider synthesis was skipped because evidence-only/offline/local-only mode is active.",
+            adapter: "codex-synthesis",
+        });
+    }
+    const shouldSynthesize = synthesisRequested && !runtime.offline;
+    const synthesisResult = shouldSynthesize
         ? await synthesizeWithCodex({
             root: context.paths.root,
             runId,
             createdAt: completedAt,
-            evidence: adapterResult.evidence,
+            evidence,
             config,
             existingCandidates: localCandidates,
-            includeSource: flagBoolean(context.parsed.flags, "allow-source-in-model")
-                || config.privacy.allowSourceInModel,
-            model: flagString(context.parsed.flags, "model"),
+            includeSource: runtime.allowSourceInModel,
+            runtime,
             verificationProfile,
         })
         : { candidates: [], diagnostics: [] };
     const diagnostics = [...adapterResult.diagnostics, ...synthesisResult.diagnostics];
-    const candidates = reassignCandidateIds(rankCandidates([
+    const rankedCandidates = reassignCandidateIds(rankCandidates([
         ...localCandidates,
         ...synthesisResult.candidates,
     ]));
-    const clusters = buildClusters(runId, candidates, adapterResult.evidence, completedAt, config.clusters);
-    await writeEvidence(context.paths, runId, adapterResult.evidence);
+    const identity = attachStableIdentity({
+        runId,
+        candidates: rankedCandidates,
+        evidence,
+        existingFindings: await readFindings(context.paths),
+        observedAt: completedAt,
+    });
+    const candidates = filterCandidatesByScanScope(identity.candidates, scope);
+    const clusters = buildClusters(runId, candidates, evidence, completedAt, config.clusters);
+    await writeFeatures(context.paths, runId, features);
+    await writeEvidence(context.paths, runId, evidence);
+    if (synthesisResult.attempt) {
+        await writeSynthesisAttempt(context.paths, remapSynthesisAttemptCandidateIds(synthesisResult.attempt, candidates));
+    }
     await writeCandidates(context.paths, runId, candidates);
+    await writeFindings(context.paths, identity.findings);
+    await writeCandidateObservations(context.paths, runId, identity.observations);
+    await writeLifecycleEvents(context.paths, identity.lifecycleEvents);
     await writeClusters(context.paths, runId, clusters);
     await writeRun(context.paths, {
         schemaVersion,
@@ -183,44 +845,66 @@ async function scanCommand(context) {
         root: context.paths.root,
         startedAt,
         completedAt,
-        evidenceCount: adapterResult.evidence.length,
+        featureCount: features.length,
+        evidenceCount: evidence.length,
         candidateCount: candidates.length,
         clusterCount: clusters.length,
         synthesis: {
-            requested: synthesisRequested,
-            provider: synthesisRequested ? "codex" : undefined,
+            requested: shouldSynthesize,
+            provider: shouldSynthesize ? runtime.provider : undefined,
             candidateCount: synthesisResult.candidates.length,
+            attemptId: synthesisResult.attempt?.id,
+            acceptedCandidateCount: synthesisResult.attempt?.acceptedCandidateCount,
+            rejectedCandidateCount: synthesisResult.attempt?.rejectedCandidateCount,
+            runtime: providerRuntimeSummary(runtime),
         },
+        scope,
         diagnostics,
     });
     const data = {
         runId,
         root: context.paths.root,
         sourceFileCount: files.length,
-        evidenceCount: adapterResult.evidence.length,
+        featureCount: features.length,
+        evidenceCount: evidence.length,
         candidateCount: candidates.length,
         clusterCount: clusters.length,
         synthesis: {
-            requested: synthesisRequested,
+            requested: shouldSynthesize,
             candidateCount: synthesisResult.candidates.length,
+            attemptId: synthesisResult.attempt?.id,
+            acceptedCandidateCount: synthesisResult.attempt?.acceptedCandidateCount,
+            rejectedCandidateCount: synthesisResult.attempt?.rejectedCandidateCount,
+            runtime: providerRuntimeSummary(runtime),
         },
         candidates,
         clusters,
+        features,
+        scope,
+    };
+    return { runId, diagnostics, data };
+}
+function remapSynthesisAttemptCandidateIds(attempt, candidates) {
+    const candidateIdByValidationId = new Map(candidates
+        .filter((candidate) => candidate.provenance.source === "model-synthesis")
+        .flatMap((candidate) => candidate.provenance.validationId
+        ? [[candidate.provenance.validationId, candidate.id]]
+        : []));
+    return {
+        ...attempt,
+        validations: attempt.validations.map((validation) => ({
+            ...validation,
+            candidateId: candidateIdByValidationId.get(validation.id),
+        })),
     };
-    emit(context.json, ok("scan", data, diagnostics));
-    if (!context.json && !context.quiet) {
-        const synthesisText = synthesisRequested
-            ? `, ${synthesisResult.candidates.length} synthesized`
-            : "";
-        console.log(`Scan complete: ${adapterResult.evidence.length} evidence records, ${candidates.length} candidates, ${clusters.length} clusters${synthesisText}`);
-        printCandidateSummary(candidates);
-    }
-    return 0;
 }
 async function reportCommand(context) {
     const { candidates, evidence, runId } = await latestState(context.paths);
     const config = await ensureState(context.paths);
-    const ranked = rankCandidates(candidates);
+    const latestClusters = await readLatestClusters(context.paths);
+    const filter = queryFilterFromFlags(context);
+    const filtered = filterCandidatesForQuery(candidates, latestClusters, filter);
+    const ranked = rankCandidates(filtered);
     const clusters = buildClusters(runId, ranked, evidence, new Date().toISOString(), config.clusters);
     await writeClusters(context.paths, runId, clusters);
     const report = buildReportRecord(runId, ranked, clusters);
@@ -236,6 +920,7 @@ async function reportCommand(context) {
         jsonPath: paths.jsonPath,
         candidates: ranked,
         clusters,
+        filters: filter,
         evidenceCount: evidence.length,
     }));
     if (!context.json && !context.quiet) {
@@ -246,8 +931,13 @@ async function reportCommand(context) {
     return 0;
 }
 async function nextCommand(context) {
-    const candidates = rankCandidates(await readLatestCandidates(context.paths));
-    const candidate = candidates.find((item) => item.status === "open");
+    const [candidates, clusters] = await Promise.all([
+        readLatestCandidates(context.paths),
+        readLatestClusters(context.paths),
+    ]);
+    const filtered = filterCandidatesForQuery(candidates, clusters, queryFilterFromFlags(context));
+    const ranked = rankCandidates(filtered);
+    const candidate = ranked.find((item) => item.status === "open");
     emit(context.json, ok("next", { candidate: candidate ?? null }));
     if (!context.json && !context.quiet) {
         if (!candidate) {
@@ -259,6 +949,28 @@ async function nextCommand(context) {
     }
     return 0;
 }
+async function listCommand(context) {
+    const [candidates, clusters] = await Promise.all([
+        readLatestCandidates(context.paths),
+        readLatestClusters(context.paths),
+    ]);
+    const filter = queryFilterFromFlags(context);
+    const filtered = rankCandidates(filterCandidatesForQuery(candidates, clusters, filter));
+    const format = flagString(context.parsed.flags, "format");
+    const queue = format === "codex" ? filtered.map(candidateQueueItem) : undefined;
+    emit(context.json, ok("list", {
+        filters: filter,
+        count: filtered.length,
+        candidates: filtered,
+        ...(queue ? { queue } : {}),
+    }));
+    if (!context.json && !context.quiet) {
+        for (const candidate of filtered) {
+            console.log(`${candidate.findingId ?? candidate.id} ${candidate.priority} ${candidate.title}`);
+        }
+    }
+    return 0;
+}
 async function showCommand(context) {
     const id = requireCandidateId(context);
     const { candidates, evidence, clusters, runId } = await latestState(context.paths);
@@ -292,6 +1004,180 @@ async function showCommand(context) {
     }
     return 0;
 }
+async function explainCommand(context) {
+    const id = requireCandidateId(context);
+    const { candidates, evidence } = await latestState(context.paths);
+    const attempt = await readLatestSynthesisAttempt(context.paths);
+    const candidate = candidates.find((item) => item.id === id || item.findingId === id);
+    if (!candidate) {
+        emit(context.json, fail("explain", "candidate_not_found", `Candidate or finding not found: ${id}`));
+        return 1;
+    }
+    const supportingEvidence = evidenceForIds(evidence, candidate.evidenceIds);
+    const validation = validationForCandidate(candidate, attempt);
+    const diagnostics = validation?.diagnostics ?? [];
+    const explanation = {
+        candidate,
+        evidence: supportingEvidence,
+        synthesisAttempt: attempt ? {
+            id: attempt.id,
+            runId: attempt.runId,
+            provider: attempt.provider,
+            model: attempt.model,
+            promptVersion: attempt.promptVersion,
+            promptBytes: attempt.promptBytes,
+            rawCandidateCount: attempt.rawCandidateCount,
+            acceptedCandidateCount: attempt.acceptedCandidateCount,
+            rejectedCandidateCount: attempt.rejectedCandidateCount,
+            evidenceManifest: attempt.evidenceManifest,
+        } : undefined,
+        validation,
+        fixReadiness: candidate.fixReadiness,
+        verification: candidate.verification,
+        diagnostics,
+    };
+    emit(context.json, ok("explain", explanation, diagnostics));
+    if (!context.json && !context.quiet) {
+        printCandidate(candidate);
+        console.log("");
+        console.log("Why this exists:");
+        console.log(`  ${candidate.whyItMatters}`);
+        console.log("");
+        console.log("Evidence:");
+        for (const record of supportingEvidence) {
+            console.log(`  ${record.id} ${record.kind}: ${record.summary}`);
+            for (const file of record.files) {
+                console.log(`    ${formatFileRef(file)}`);
+            }
+        }
+        if (validation) {
+            console.log("");
+            console.log(`Validation: ${validation.status} (${validation.id})`);
+            if (validation.diagnostics.length === 0) {
+                console.log("  All cited evidence IDs, file paths, line ranges, and quotes passed validation.");
+            }
+            else {
+                for (const diagnostic of validation.diagnostics) {
+                    console.log(`  ${diagnostic.code}: ${diagnostic.message}`);
+                }
+            }
+        }
+        if (candidate.fixReadiness) {
+            console.log("");
+            console.log("Fix readiness:");
+            console.log(`  scope: ${candidate.fixReadiness.minimumFixScope}`);
+            console.log(`  regression: ${candidate.fixReadiness.suggestedRegressionTest}`);
+            console.log(`  test gap: ${candidate.fixReadiness.whyCurrentTestsMissIt}`);
+            for (const reason of candidate.fixReadiness.confidenceDowngradeReasons) {
+                console.log(`  confidence note: ${reason}`);
+            }
+        }
+        console.log("");
+        console.log(`Verification: ${candidate.verification.join("; ") || "n/a"}`);
+    }
+    return 0;
+}
+async function historyCommand(context) {
+    const id = requireCandidateId(context);
+    const runId = flagString(context.parsed.flags, "run");
+    const [findings, events] = await Promise.all([
+        readFindings(context.paths),
+        readLifecycleEvents(context.paths),
+    ]);
+    const candidate = id.startsWith("candidate-")
+        ? await candidateForHistoryLookup(context.paths, id, runId)
+        : undefined;
+    const findingId = candidate?.findingId ?? id;
+    const finding = findings.find((item) => item.id === findingId);
+    if (!finding) {
+        emit(context.json, fail("history", "finding_not_found", `Finding not found: ${id}`));
+        return 1;
+    }
+    const history = events.filter((event) => event.findingId === finding.id || event.targetId === finding.id);
+    emit(context.json, ok("history", { finding, candidate, events: history }));
+    if (!context.json && !context.quiet) {
+        console.log(`${finding.id}: ${finding.title}`);
+        for (const event of history) {
+            console.log(`${event.createdAt} ${event.kind}${event.toState ? ` -> ${event.toState}` : ""}`);
+        }
+    }
+    return 0;
+}
+async function revalidateCommand(context) {
+    const target = requireCandidateId(context);
+    const beforeFindings = await readFindings(context.paths);
+    const targetFindings = await resolveRevalidationTargets(context.paths, target, beforeFindings);
+    if (targetFindings.length === 0 && target !== "all") {
+        emit(context.json, fail("revalidate", "finding_not_found", `Finding not found: ${target}`));
+        return 1;
+    }
+    const scan = await executeScan(context, { synthesize: false });
+    const now = new Date().toISOString();
+    const records = [];
+    for (const finding of target === "all" ? beforeFindings : targetFindings) {
+        records.push(await classifyRevalidation({
+            root: context.paths.root,
+            finding,
+            currentCandidates: scan.data.candidates,
+            runId: scan.runId,
+            createdAt: now,
+        }));
+    }
+    if (target === "all" && beforeFindings.length === 0) {
+        records.push(await classifyRevalidation({
+            root: context.paths.root,
+            finding: undefined,
+            currentCandidates: scan.data.candidates,
+            runId: scan.runId,
+            createdAt: now,
+        }));
+    }
+    for (const record of records) {
+        await writeRevalidation(context.paths, record);
+    }
+    const updatedFindings = beforeFindings.map((finding) => {
+        const record = records.find((item) => item.targetId === finding.id);
+        if (!record) {
+            return finding;
+        }
+        const state = revalidationOutcomeToLifecycleState(record.outcome);
+        return {
+            ...finding,
+            lifecycleState: state,
+            status: revalidationOutcomeToStatus(record.outcome, finding.status),
+            updatedAt: record.createdAt,
+        };
+    });
+    await writeFindings(context.paths, updatedFindings);
+    await writeLifecycleEvents(context.paths, records.flatMap((record) => (record.targetId
+        ? [{
+                schemaVersion,
+                recordType: "lifecycle_event",
+                id: timestampId("event"),
+                targetType: "finding",
+                targetId: record.targetId,
+                findingId: record.targetId,
+                runId: record.runId,
+                kind: "revalidated",
+                toState: record.outcome,
+                command: "revalidate",
+                createdAt: record.createdAt,
+                data: { revalidationId: record.id, outcome: record.outcome },
+            }]
+        : [])));
+    emit(context.json, ok("revalidate", {
+        target,
+        runId: scan.runId,
+        revalidations: records,
+        candidates: scan.data.candidates,
+    }, scan.diagnostics));
+    if (!context.json && !context.quiet) {
+        for (const record of records) {
+            console.log(`${record.targetId ?? "all"}: ${record.outcome}`);
+        }
+    }
+    return 0;
+}
 async function clusterCommand(context) {
     const id = context.parsed.positional[0];
     const { candidates, evidence, runId } = await latestState(context.paths);
@@ -417,6 +1303,24 @@ async function triageCommand(context) {
         createdAt: now,
     };
     await writeTriage(context.paths, triage);
+    if (updated.findingId) {
+        await writeLifecycleEvents(context.paths, [{
+                schemaVersion,
+                recordType: "lifecycle_event",
+                id: timestampId("event"),
+                targetType: "finding",
+                targetId: updated.findingId,
+                findingId: updated.findingId,
+                runId: updated.runId,
+                kind: "triaged",
+                fromState: existing.status,
+                toState: updated.status,
+                note: note ?? "",
+                command: "triage",
+                createdAt: now,
+                data: { candidateId: id, triageId: triage.id },
+            }]);
+    }
     emit(context.json, ok("triage", { candidate: updated, triage }));
     if (!context.json && !context.quiet) {
         console.log(`${id}: ${existing.status} -> ${updated.status}`);
@@ -435,8 +1339,12 @@ async function handoffCommand(context) {
     const supportingEvidence = evidenceForIds(evidence, candidate.evidenceIds);
     const handoff = buildHandoff(candidate, supportingEvidence, format);
     const handoffPath = await writeHandoff(context.paths, handoff);
-    emit(context.json, ok("handoff", { handoff, path: handoffPath }));
+    const warnings = handoffFreshnessWarnings(candidate);
+    emit(context.json, ok("handoff", { handoff, path: handoffPath, warnings }));
     if (!context.json && !context.quiet) {
+        for (const warning of warnings) {
+            console.log(`warning: ${warning}`);
+        }
         console.log(handoff.content);
         console.log("");
         console.log(`Handoff written to ${path.relative(context.paths.root, handoffPath)}`);
@@ -455,6 +1363,149 @@ async function latestState(paths) {
     ]);
     return { runId, candidates, clusters, evidence };
 }
+async function resolveFixTarget(paths, target) {
+    const candidates = await readLatestCandidates(paths);
+    const candidate = candidates.find((item) => item.id === target || item.findingId === target);
+    if (!candidate) {
+        return undefined;
+    }
+    return { findingId: candidate.findingId ?? candidate.id, candidate };
+}
+function fixReadinessBlocker(candidate) {
+    if (candidate.confidence === "low") {
+        return { code: "fix_low_confidence", message: "Low-confidence findings must be confirmed before fix execution." };
+    }
+    const lifecycleState = candidate.lifecycleState ?? "open";
+    if (["stale", "fixed", "superseded", "inconclusive", "suppressed"].includes(lifecycleState)) {
+        return { code: "fix_not_current", message: `Finding lifecycle state is ${lifecycleState}; revalidate or choose another finding.` };
+    }
+    if (candidate.risk === "design-needed") {
+        return { code: "fix_ambiguous", message: "Design-needed findings are too ambiguous for guarded fix execution." };
+    }
+    return undefined;
+}
+async function latestPlanForTarget(paths, candidateId) {
+    const files = await filesWithExtension(paths.plansDir, "json");
+    const plans = [];
+    for (const file of files) {
+        try {
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            if (typeof parsed.id === "string" && typeof parsed.targetId === "string") {
+                plans.push({
+                    id: parsed.id,
+                    targetId: parsed.targetId,
+                    createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
+                });
+            }
+        }
+        catch {
+            // Ignore malformed historical plan records here; schema validation handles them elsewhere.
+        }
+    }
+    return plans
+        .filter((plan) => plan.targetId === candidateId)
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+        .at(-1);
+}
+async function latestRevalidationForFinding(paths, findingId) {
+    const files = await filesWithExtension(paths.revalidationsDir, "json");
+    const records = [];
+    for (const file of files) {
+        try {
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            if (parsed.targetId === findingId && typeof parsed.outcome === "string") {
+                records.push({
+                    targetId: findingId,
+                    outcome: parsed.outcome,
+                    createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
+                });
+            }
+        }
+        catch {
+            // Ignore malformed historical revalidation records.
+        }
+    }
+    return records.sort((a, b) => a.createdAt.localeCompare(b.createdAt)).at(-1);
+}
+function changedFilesFromPatch(patchContent) {
+    const files = new Set();
+    for (const line of patchContent.split(/\r?\n/)) {
+        const match = line.match(/^\+\+\+ b\/(.+)$/);
+        if (match?.[1] && match[1] !== "/dev/null") {
+            files.add(match[1]);
+        }
+    }
+    return [...files].sort();
+}
+async function dirtyFiles(root) {
+    try {
+        const { stdout } = await execFileAsync("git", ["status", "--short"], { cwd: root, timeout: 5000 });
+        return stdout.split(/\r?\n/)
+            .map((line) => line.slice(3).trim())
+            .filter(Boolean)
+            .map((line) => line.split(" -> ").at(-1) ?? line)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function verificationCommandsForFix(context, config, candidate) {
+    const override = flagString(context.parsed.flags, "verification-command");
+    if (override) {
+        return [override];
+    }
+    if (config.fixExecution.verificationCommands.length > 0) {
+        return config.fixExecution.verificationCommands;
+    }
+    return candidate.verification;
+}
+async function runFixVerification(paths, attemptId, commandsToRun) {
+    const results = [];
+    for (const [index, command] of commandsToRun.entries()) {
+        const outputPath = path.join(paths.fixesDir, `${attemptId}-verification-${String(index + 1).padStart(2, "0")}.txt`);
+        const result = await execFileAsync("sh", ["-lc", command], { cwd: paths.root, timeout: 120_000 })
+            .then((output) => ({ exitCode: 0, output: `${output.stdout}${output.stderr}` }))
+            .catch((error) => ({
+            exitCode: typeof error === "object" && error && "code" in error && typeof error.code === "number" ? error.code : 1,
+            output: error instanceof Error ? error.message : String(error),
+        }));
+        await writeFile(outputPath, result.output, "utf8");
+        results.push({
+            command,
+            exitCode: result.exitCode,
+            passed: result.exitCode === 0,
+            outputPath,
+        });
+    }
+    return results;
+}
+async function candidateForHistoryLookup(paths, id, runId) {
+    if (runId) {
+        return (await readCandidates(paths, runId)).find((candidate) => candidate.id === id);
+    }
+    return (await readLatestCandidates(paths)).find((candidate) => candidate.id === id);
+}
+async function resolveRevalidationTargets(paths, target, findings) {
+    if (target === "all") {
+        return findings;
+    }
+    if (target.startsWith("candidate-")) {
+        const candidate = await candidateForHistoryLookup(paths, target, undefined);
+        return candidate?.findingId
+            ? findings.filter((finding) => finding.id === candidate.findingId)
+            : [];
+    }
+    return findings.filter((finding) => finding.id === target);
+}
+async function withWriteLock(context, fn) {
+    return withStateWriteLock(context.paths, {
+        command: context.parsed.command ?? "unknown",
+        wait: flagBoolean(context.parsed.flags, "wait-lock"),
+        timeoutMs: numberFlag(context, "lock-timeout-ms") ?? 0,
+        staleAfterMs: staleLockMsFromFlags(context),
+    }, fn);
+}
 function requireCandidateId(context) {
     const id = context.parsed.positional[0];
     if (!id) {
@@ -462,6 +1513,19 @@ function requireCandidateId(context) {
     }
     return id;
 }
+function lockStatusPayload(lock) {
+    return {
+        id: lock.record?.id,
+        owner: lock.record?.owner,
+        pid: lock.record?.pid,
+        command: lock.record?.command,
+        statePath: lock.record?.statePath,
+        createdAt: lock.record?.createdAt,
+        stale: lock.stale,
+        reason: lock.reason,
+        recoveryCommand: lock.recoveryCommand,
+    };
+}
 function emit(json, value) {
     if (json) {
         console.log(JSON.stringify(value, null, 2));
@@ -503,6 +1567,856 @@ function evidenceForIds(evidence, ids) {
     const wanted = new Set(ids);
     return evidence.filter((item) => wanted.has(item.id));
 }
+function validationForCandidate(candidate, attempt) {
+    const validationId = candidate.provenance.validationId;
+    if (!attempt || !validationId) {
+        return undefined;
+    }
+    return attempt.validations.find((validation) => validation.id === validationId);
+}
+function formatFileRef(file) {
+    if (file.startLine !== undefined && file.endLine !== undefined) {
+        return `${file.path}:${file.startLine}-${file.endLine}`;
+    }
+    if (file.startLine !== undefined) {
+        return `${file.path}:${file.startLine}`;
+    }
+    return file.path;
+}
+function printDiagnostics(diagnostics) {
+    for (const diagnostic of diagnostics) {
+        console.log(`${diagnostic.level}: ${diagnostic.code}: ${diagnostic.message}`);
+    }
+}
+async function pathExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function missingStateDirectories(paths) {
+    const expected = [
+        ["runs", paths.runsDir],
+        ["findings", paths.findingsDir],
+        ["observations", paths.observationsDir],
+        ["features", paths.featuresDir],
+        ["evidence", paths.evidenceDir],
+        ["candidates", paths.candidatesDir],
+        ["clusters", paths.clustersDir],
+        ["reports", paths.reportsDir],
+        ["triage", paths.triageDir],
+        ["handoffs", paths.handoffsDir],
+        ["plans", paths.plansDir],
+        ["lifecycle", paths.lifecycleDir],
+        ["revalidations", paths.revalidationsDir],
+        ["ci", paths.ciDir],
+        ["locks", paths.locksDir],
+        ["retention", paths.retentionDir],
+        ["fixes", paths.fixesDir],
+        ["synthesis", paths.synthesisDir],
+    ];
+    const missing = [];
+    for (const [name, dir] of expected) {
+        if (!(await pathExists(dir))) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+async function readConfigForDoctor(paths) {
+    if (!(await pathExists(paths.configPath))) {
+        return {
+            valid: false,
+            error: "Config file is missing.",
+            diagnostics: [{
+                    level: "info",
+                    code: "config_missing",
+                    message: "Run `deepclean init` to create project-local configuration.",
+                }],
+        };
+    }
+    try {
+        return {
+            valid: true,
+            config: await readConfig(paths),
+            diagnostics: [],
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : String(error),
+            diagnostics: [{
+                    level: "error",
+                    code: "config_invalid",
+                    message: error instanceof Error ? error.message : String(error),
+                }],
+        };
+    }
+}
+async function gitDoctor(root) {
+    try {
+        const { stdout: statusOutput } = await execFileAsync("git", ["status", "--short"], { cwd: root, timeout: 5000 });
+        const branchOutput = await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: root, timeout: 5000 })
+            .then((result) => result.stdout.trim())
+            .catch(() => undefined);
+        const result = {
+            available: true,
+            dirty: statusOutput.trim().length > 0,
+        };
+        if (branchOutput) {
+            result.branch = branchOutput;
+        }
+        return result;
+    }
+    catch (error) {
+        return {
+            available: false,
+            dirty: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function providerDoctor(root, command) {
+    try {
+        await execFileAsync(command, ["--version"], { cwd: root, timeout: 5000 });
+        return { command, available: true };
+    }
+    catch (error) {
+        return {
+            command,
+            available: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function resolveScanScope(context, files) {
+    const since = flagString(context.parsed.flags, "since");
+    const mergeBaseRef = flagString(context.parsed.flags, "merge-base");
+    const includeDirty = flagBoolean(context.parsed.flags, "include-dirty");
+    const paths = csvFlag(context, "paths");
+    const categories = csvFlag(context, "categories");
+    const reviewers = csvFlag(context, "reviewers");
+    const dirtyPaths = includeDirty ? await gitChangedPaths(context.paths.root, ["diff", "--name-only"]) : [];
+    const untrackedPaths = includeDirty ? await gitChangedPaths(context.paths.root, ["ls-files", "--others", "--exclude-standard"]) : [];
+    const committedChangedPaths = mergeBaseRef
+        ? await gitMergeBaseChangedPaths(context.paths.root, mergeBaseRef)
+        : since
+            ? await gitChangedPaths(context.paths.root, ["diff", "--name-only", `${since}...HEAD`])
+            : [];
+    const changedPaths = uniqueNormalized([
+        ...committedChangedPaths,
+        ...dirtyPaths,
+        ...untrackedPaths,
+    ]).filter((filePath) => files.some((file) => file.path === filePath));
+    return {
+        incremental: Boolean(since || mergeBaseRef || includeDirty || paths.length > 0),
+        ...(since ? { since } : {}),
+        ...(mergeBaseRef ? { mergeBase: mergeBaseRef } : {}),
+        includeDirty,
+        paths,
+        changedPaths,
+        categories,
+        reviewers,
+        onlyExisting: flagBoolean(context.parsed.flags, "only-existing"),
+        newOnly: flagBoolean(context.parsed.flags, "new-only"),
+        dirtyPaths: uniqueNormalized([...dirtyPaths, ...untrackedPaths]),
+    };
+}
+function fileInScope(file, scope) {
+    const pathMatched = scope.paths.length === 0
+        || scope.paths.some((prefix) => file.path === prefix || file.path.startsWith(`${prefix.replace(/\/$/, "")}/`));
+    if (!pathMatched) {
+        return false;
+    }
+    if (scope.changedPaths.length === 0) {
+        return true;
+    }
+    return scope.changedPaths.includes(file.path);
+}
+function filterCandidatesByScanScope(candidates, scope) {
+    return candidates.filter((candidate) => {
+        if (scope.categories.length > 0 && !scope.categories.includes(candidate.category)) {
+            return false;
+        }
+        if (scope.onlyExisting && candidate.baselineStatus !== "existing") {
+            return false;
+        }
+        if (scope.newOnly && candidate.baselineStatus !== "new") {
+            return false;
+        }
+        return true;
+    });
+}
+function markDirtyTreeEvidence(evidence, scope) {
+    if (scope.dirtyPaths.length === 0) {
+        return evidence;
+    }
+    const dirty = new Set(scope.dirtyPaths);
+    return evidence.map((record) => {
+        const dirtyTree = record.files.some((file) => dirty.has(file.path));
+        return dirtyTree
+            ? {
+                ...record,
+                data: {
+                    ...record.data,
+                    dirtyTree: true,
+                    freshness: "dirty",
+                },
+            }
+            : record;
+    });
+}
+function queryFilterFromFlags(context) {
+    const filter = {};
+    const entries = [
+        ["status", "status"],
+        ["priority", "priority"],
+        ["category", "category"],
+        ["risk", "risk"],
+        ["source", "source"],
+        ["theme", "theme"],
+        ["path", "path"],
+        ["lifecycleState", "lifecycle-state"],
+        ["revalidationState", "revalidation-state"],
+        ["baselineStatus", "baseline-status"],
+    ];
+    for (const [property, flag] of entries) {
+        const value = flagString(context.parsed.flags, flag);
+        if (value) {
+            filter[property] = value;
+        }
+    }
+    return filter;
+}
+function filterCandidatesForQuery(candidates, clusters, filter) {
+    const themeCandidateIds = filter.theme
+        ? new Set(clusters.find((cluster) => cluster.id === filter.theme)?.candidateIds ?? [])
+        : undefined;
+    return candidates.filter((candidate) => {
+        if (filter.status && candidate.status !== filter.status) {
+            return false;
+        }
+        if (filter.priority && candidate.priority !== filter.priority.toUpperCase()) {
+            return false;
+        }
+        if (filter.category && candidate.category !== filter.category) {
+            return false;
+        }
+        if (filter.risk && candidate.risk !== filter.risk) {
+            return false;
+        }
+        if (filter.source && candidate.provenance.source !== filter.source) {
+            return false;
+        }
+        if (themeCandidateIds && !themeCandidateIds.has(candidate.id)) {
+            return false;
+        }
+        if (filter.path && !candidate.files.some((file) => file.path === filter.path || file.path.startsWith(`${filter.path}/`))) {
+            return false;
+        }
+        if (filter.lifecycleState && (candidate.lifecycleState ?? "open") !== filter.lifecycleState) {
+            return false;
+        }
+        if (filter.revalidationState && (candidate.lifecycleState ?? "open") !== filter.revalidationState) {
+            return false;
+        }
+        if (filter.baselineStatus && (candidate.baselineStatus ?? "unknown") !== filter.baselineStatus) {
+            return false;
+        }
+        return true;
+    });
+}
+function candidateQueueItem(candidate) {
+    return {
+        findingId: candidate.findingId ?? candidate.id,
+        candidateId: candidate.id,
+        title: candidate.title,
+        priority: candidate.priority,
+        category: candidate.category,
+        risk: candidate.risk,
+        status: candidate.status,
+        lifecycleState: candidate.lifecycleState ?? "open",
+        baselineStatus: candidate.baselineStatus ?? "unknown",
+        problem: candidate.whyItMatters,
+        evidenceIds: candidate.evidenceIds,
+        files: candidate.files,
+        constraints: [
+            "Keep changes scoped to this finding.",
+            "Preserve behavior unless verification proves current behavior is wrong.",
+        ],
+        verification: candidate.verification,
+    };
+}
+function handoffFreshnessWarnings(candidate) {
+    const warnings = [];
+    const lifecycleState = candidate.lifecycleState ?? "open";
+    if (["stale", "fixed", "superseded", "inconclusive"].includes(lifecycleState)) {
+        warnings.push(`Finding lifecycle state is ${lifecycleState}; revalidate before assigning implementation work.`);
+    }
+    if (candidate.confidence === "low") {
+        warnings.push("Finding confidence is low; confirm evidence before implementation.");
+    }
+    return warnings;
+}
+function ciPolicyFromFlags(context) {
+    const policy = {};
+    for (const key of [
+        "max-p0",
+        "max-p1",
+        "max-p2",
+        "max-p3",
+        "max-new-p0",
+        "max-new-p1",
+        "max-new-p2",
+        "max-new-p3",
+        "max-stale",
+    ]) {
+        const value = flagString(context.parsed.flags, key);
+        if (value !== undefined && value !== "") {
+            policy[key] = Number(value);
+        }
+    }
+    const minConfidence = flagString(context.parsed.flags, "min-confidence");
+    if (minConfidence) {
+        policy["min-confidence"] = minConfidence;
+    }
+    const failCategory = csvFlag(context, "fail-category");
+    if (failCategory.length > 0) {
+        policy["fail-category"] = failCategory;
+    }
+    return policy;
+}
+async function buildRetentionManifest(context) {
+    const keepRuns = numberFlag(context, "keep-runs") ?? 5;
+    const keepDays = numberFlag(context, "keep-days");
+    const dryRun = flagBoolean(context.parsed.flags, "dry-run");
+    const now = new Date();
+    const runRecords = await readRunRetentionRecords(context.paths);
+    const sortedRuns = [...runRecords].sort((a, b) => a.id.localeCompare(b.id));
+    const retainedRunIds = new Set();
+    for (const run of sortedRuns.slice(Math.max(0, sortedRuns.length - keepRuns))) {
+        retainedRunIds.add(run.id);
+    }
+    const latest = sortedRuns.at(-1);
+    if (latest) {
+        retainedRunIds.add(latest.id);
+    }
+    if (keepDays !== undefined) {
+        const cutoff = now.getTime() - keepDays * 24 * 60 * 60 * 1000;
+        for (const run of sortedRuns) {
+            if (Date.parse(run.createdAt) >= cutoff) {
+                retainedRunIds.add(run.id);
+            }
+        }
+    }
+    const retainedPaths = new Set();
+    const deletePaths = new Set();
+    const blockedPaths = [{
+            path: relativeStatePath(context.paths, context.paths.configPath),
+            reason: "config is never pruned",
+        }];
+    const activeLocks = (await readLockStatuses(context.paths)).filter((lock) => !lock.stale);
+    for (const lock of activeLocks) {
+        blockedPaths.push({
+            path: relativeStatePath(context.paths, lock.filePath),
+            reason: "active locks are never pruned",
+        });
+    }
+    for (const [dir, extension] of [
+        [context.paths.runsDir, "json"],
+        [context.paths.featuresDir, "json"],
+        [context.paths.evidenceDir, "json"],
+        [context.paths.candidatesDir, "json"],
+        [context.paths.clustersDir, "json"],
+        [context.paths.observationsDir, "json"],
+        [context.paths.synthesisDir, "json"],
+    ]) {
+        const files = await filesWithExtension(dir, extension);
+        for (const file of files) {
+            const runId = path.basename(file, `.${extension}`);
+            const relativePath = relativeStatePath(context.paths, file);
+            if (retainedRunIds.has(runId)) {
+                retainedPaths.add(relativePath);
+            }
+            else {
+                deletePaths.add(relativePath);
+            }
+        }
+    }
+    const retainedCandidateIds = await candidateIdsForRuns(context.paths, retainedRunIds);
+    await classifyRunLinkedArtifacts(context.paths, context.paths.reportsDir, retainedRunIds, retainedPaths, deletePaths, ["json", "md"]);
+    await classifyRunLinkedArtifacts(context.paths, context.paths.plansDir, retainedRunIds, retainedPaths, deletePaths, ["json"]);
+    await classifyHandoffArtifacts(context.paths, retainedCandidateIds, retainedPaths, deletePaths);
+    return {
+        schemaVersion,
+        recordType: "retention_manifest",
+        id: timestampId("retention"),
+        dryRun,
+        keepRuns,
+        ...(keepDays !== undefined ? { keepDays } : {}),
+        deletePaths: [...deletePaths].sort(),
+        retainedPaths: [...retainedPaths].sort(),
+        blockedPaths,
+        privacyNotes: [
+            "Prune never deletes .deepclean/config.json.",
+            "Active locks and latest retained run artifacts are preserved.",
+            "Source-safe sharing should use deepclean scrub or export --source-safe before attaching generated state outside the local machine.",
+        ],
+        createdAt: now.toISOString(),
+    };
+}
+async function readRunRetentionRecords(paths) {
+    const files = await filesWithExtension(paths.runsDir, "json");
+    const records = [];
+    for (const file of files) {
+        try {
+            const raw = JSON.parse(await readFile(file, "utf8"));
+            const id = typeof raw.id === "string" ? raw.id : path.basename(file, ".json");
+            const createdAt = typeof raw.completedAt === "string"
+                ? raw.completedAt
+                : typeof raw.startedAt === "string"
+                    ? raw.startedAt
+                    : "1970-01-01T00:00:00.000Z";
+            records.push({ id, createdAt });
+        }
+        catch {
+            records.push({ id: path.basename(file, ".json"), createdAt: "1970-01-01T00:00:00.000Z" });
+        }
+    }
+    return records;
+}
+async function candidateIdsForRuns(paths, retainedRunIds) {
+    const ids = new Set();
+    for (const runId of retainedRunIds) {
+        for (const candidate of await readCandidates(paths, runId).catch(() => [])) {
+            ids.add(candidate.id);
+        }
+    }
+    return ids;
+}
+async function classifyRunLinkedArtifacts(paths, dir, retainedRunIds, retainedPaths, deletePaths, extensions) {
+    const jsonFiles = await filesWithExtension(dir, "json");
+    for (const jsonFile of jsonFiles) {
+        let runId;
+        try {
+            const raw = JSON.parse(await readFile(jsonFile, "utf8"));
+            runId = typeof raw.runId === "string" ? raw.runId : undefined;
+        }
+        catch {
+            runId = undefined;
+        }
+        const id = path.basename(jsonFile, ".json");
+        for (const extension of extensions) {
+            const artifact = path.join(dir, `${id}.${extension}`);
+            if (!(await pathExists(artifact))) {
+                continue;
+            }
+            const relativePath = relativeStatePath(paths, artifact);
+            if (runId && retainedRunIds.has(runId)) {
+                retainedPaths.add(relativePath);
+            }
+            else {
+                deletePaths.add(relativePath);
+            }
+        }
+    }
+}
+async function classifyHandoffArtifacts(paths, retainedCandidateIds, retainedPaths, deletePaths) {
+    const jsonFiles = await filesWithExtension(paths.handoffsDir, "json");
+    for (const file of jsonFiles) {
+        let candidateId;
+        try {
+            const raw = JSON.parse(await readFile(file, "utf8"));
+            candidateId = typeof raw.candidateId === "string" ? raw.candidateId : undefined;
+        }
+        catch {
+            candidateId = undefined;
+        }
+        const relativePath = relativeStatePath(paths, file);
+        if (candidateId && retainedCandidateIds.has(candidateId)) {
+            retainedPaths.add(relativePath);
+        }
+        else {
+            deletePaths.add(relativePath);
+        }
+    }
+}
+async function filesWithExtension(dir, extension) {
+    try {
+        return (await readdir(dir))
+            .filter((file) => file.endsWith(`.${extension}`))
+            .map((file) => path.join(dir, file))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function relativeStatePath(paths, filePath) {
+    return path.relative(paths.root, filePath).split(path.sep).join("/");
+}
+function sourceSafeFile(root, file) {
+    const normalized = path.isAbsolute(file.path)
+        ? path.relative(root, file.path)
+        : file.path;
+    return {
+        path: normalized.split(path.sep).join("/"),
+        ...(file.startLine ? { startLine: file.startLine } : {}),
+        ...(file.endLine ? { endLine: file.endLine } : {}),
+    };
+}
+function evaluateCiPolicy(candidates, policy) {
+    const blockers = new Map();
+    const byPriority = countBy(candidates, (candidate) => candidate.priority.toLowerCase());
+    for (const priority of ["p0", "p1", "p2", "p3"]) {
+        const max = numberPolicy(policy, `max-${priority}`);
+        if (max !== undefined && (byPriority[priority] ?? 0) > max) {
+            for (const candidate of candidates.filter((item) => item.priority.toLowerCase() === priority).slice(max)) {
+                blockers.set(candidate.findingId ?? candidate.id, `max-${priority}`);
+            }
+        }
+        const maxNew = numberPolicy(policy, `max-new-${priority}`);
+        if (maxNew !== undefined) {
+            const newCandidates = candidates.filter((item) => (item.priority.toLowerCase() === priority
+                && item.baselineStatus === "new"));
+            if (newCandidates.length > maxNew) {
+                for (const candidate of newCandidates.slice(maxNew)) {
+                    blockers.set(candidate.findingId ?? candidate.id, `max-new-${priority}`);
+                }
+            }
+        }
+    }
+    const maxStale = numberPolicy(policy, "max-stale");
+    if (maxStale !== undefined) {
+        const stale = candidates.filter((candidate) => candidate.lifecycleState === "stale" || candidate.status === "stale");
+        if (stale.length > maxStale) {
+            for (const candidate of stale.slice(maxStale)) {
+                blockers.set(candidate.findingId ?? candidate.id, "max-stale");
+            }
+        }
+    }
+    const categories = Array.isArray(policy["fail-category"]) ? policy["fail-category"] : [];
+    for (const candidate of candidates) {
+        if (categories.includes(candidate.category)) {
+            blockers.set(candidate.findingId ?? candidate.id, `fail-category:${candidate.category}`);
+        }
+    }
+    const minConfidence = typeof policy["min-confidence"] === "string" ? policy["min-confidence"] : undefined;
+    if (minConfidence) {
+        const order = ["low", "medium", "high"];
+        const minimum = order.indexOf(minConfidence);
+        if (minimum >= 0) {
+            for (const candidate of candidates) {
+                if (order.indexOf(candidate.confidence) < minimum) {
+                    blockers.set(candidate.findingId ?? candidate.id, `min-confidence:${minConfidence}`);
+                }
+            }
+        }
+    }
+    return {
+        blockingFindingIds: [...blockers.keys()].sort(),
+        reasons: [...blockers.entries()].map(([findingId, reason]) => ({ findingId, reason })),
+    };
+}
+async function writeCiArtifacts(context, scan, gate) {
+    const artifactPaths = {};
+    const output = flagString(context.parsed.flags, "output");
+    if (output) {
+        const markdownPath = path.resolve(context.paths.root, output);
+        await mkdir(path.dirname(markdownPath), { recursive: true });
+        await writeFile(markdownPath, renderCiMarkdown(scan, gate), "utf8");
+        artifactPaths.markdown = markdownPath;
+    }
+    const sarif = flagString(context.parsed.flags, "sarif");
+    if (sarif) {
+        const sarifPath = path.resolve(context.paths.root, sarif);
+        await mkdir(path.dirname(sarifPath), { recursive: true });
+        await writeFile(sarifPath, JSON.stringify(renderCiSarif(scan.candidates), null, 2) + "\n", "utf8");
+        artifactPaths.sarif = sarifPath;
+    }
+    return artifactPaths;
+}
+function renderCiMarkdown(scan, gate) {
+    return [
+        "# Deepclean CI",
+        "",
+        `Run: ${scan.runId}`,
+        `Candidates: ${scan.candidateCount}`,
+        `Blocking: ${gate.blockingFindingIds.length}`,
+        "",
+        "## Blocking Findings",
+        "",
+        ...(gate.reasons.length > 0
+            ? gate.reasons.map((reason) => `- ${reason.findingId}: ${reason.reason}`)
+            : ["None"]),
+        "",
+    ].join("\n");
+}
+function renderCiSarif(candidates) {
+    return {
+        version: "2.1.0",
+        runs: [{
+                tool: { driver: { name: "Deepclean" } },
+                results: candidates.map((candidate) => ({
+                    ruleId: `deepclean/${candidate.category}`,
+                    level: candidate.priority === "P0" || candidate.priority === "P1" ? "warning" : "note",
+                    message: { text: `${candidate.id}: ${candidate.title}` },
+                    locations: candidate.files.slice(0, 1).map((file) => ({
+                        physicalLocation: {
+                            artifactLocation: { uri: file.path },
+                            region: { startLine: file.startLine ?? 1, endLine: file.endLine ?? file.startLine ?? 1 },
+                        },
+                    })),
+                    properties: {
+                        findingId: candidate.findingId,
+                        priority: candidate.priority,
+                        confidence: candidate.confidence,
+                        baselineStatus: candidate.baselineStatus,
+                    },
+                })),
+            }],
+    };
+}
+function numberPolicy(policy, key) {
+    const value = policy[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+async function gitMergeBaseChangedPaths(root, ref) {
+    try {
+        const { stdout } = await execFileAsync("git", ["merge-base", ref, "HEAD"], { cwd: root, timeout: 5000 });
+        const mergeBase = stdout.trim();
+        return mergeBase ? gitChangedPaths(root, ["diff", "--name-only", `${mergeBase}...HEAD`]) : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function gitChangedPaths(root, args) {
+    try {
+        const { stdout } = await execFileAsync("git", args, { cwd: root, timeout: 5000 });
+        return stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+function csvFlag(context, key) {
+    const value = flagString(context.parsed.flags, key);
+    if (!value) {
+        return [];
+    }
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function staleLockMsFromFlags(context) {
+    return numberFlag(context, "stale-lock-ms");
+}
+function providerRuntimeControls(context, config) {
+    const provider = flagString(context.parsed.flags, "provider");
+    if (provider && provider !== "codex") {
+        throw new Error(`Unsupported provider: ${provider}. Only codex is currently supported.`);
+    }
+    const timeoutSeconds = numberFlag(context, "timeout");
+    const timeoutMs = numberFlag(context, "timeout-ms") ?? (timeoutSeconds !== undefined ? timeoutSeconds * 1000 : config.reviewSynthesis.timeoutMs);
+    const privacyMode = privacyModeFromFlag(flagString(context.parsed.flags, "privacy-mode"))
+        ?? config.reviewSynthesis.privacyMode;
+    const offline = flagBoolean(context.parsed.flags, "offline")
+        || flagBoolean(context.parsed.flags, "local-only")
+        || flagBoolean(context.parsed.flags, "evidence-only")
+        || config.reviewSynthesis.offline
+        || privacyMode === "local-only";
+    const excerptBudget = numberFlag(context, "excerpt-budget") ?? config.reviewSynthesis.excerptBudget;
+    const allowSourceInModel = !offline && (flagBoolean(context.parsed.flags, "allow-source-in-model")
+        || config.privacy.allowSourceInModel
+        || privacyMode === "source-ok") && excerptBudget > 0;
+    const runtime = {
+        provider: "codex",
+        command: config.reviewSynthesis.command,
+        timeoutMs,
+        retries: numberFlag(context, "retries") ?? config.reviewSynthesis.retries,
+        rpm: numberFlag(context, "rpm") ?? config.reviewSynthesis.rpm,
+        concurrency: numberFlag(context, "concurrency") ?? config.reviewSynthesis.concurrency,
+        tokenBudget: numberFlag(context, "token-budget") ?? config.reviewSynthesis.tokenBudget,
+        excerptBudget,
+        offline,
+        privacyMode,
+        allowSourceInModel,
+    };
+    const model = flagString(context.parsed.flags, "model") ?? config.reviewSynthesis.model;
+    if (model) {
+        runtime.model = model;
+    }
+    const effort = flagString(context.parsed.flags, "effort") ?? config.reviewSynthesis.effort;
+    if (effort) {
+        runtime.effort = effort;
+    }
+    return runtime;
+}
+function synthesisDisabledByPolicy(context, config) {
+    const privacyMode = privacyModeFromFlag(flagString(context.parsed.flags, "privacy-mode"))
+        ?? config.reviewSynthesis.privacyMode;
+    return flagBoolean(context.parsed.flags, "offline")
+        || flagBoolean(context.parsed.flags, "local-only")
+        || flagBoolean(context.parsed.flags, "evidence-only")
+        || config.reviewSynthesis.offline
+        || privacyMode === "local-only";
+}
+const requiredSynthesisFailureCodes = new Set([
+    "codex_provider_unavailable",
+    "codex_synthesis_timeout",
+    "codex_synthesis_failed",
+    "codex_synthesis_error",
+]);
+function requiredSynthesisFailure(scan) {
+    if (!scan.data.synthesis.requested) {
+        return {
+            level: "error",
+            code: "ci_synthesis_required",
+            message: "CI policy requires synthesis, but the scan did not run provider synthesis.",
+            adapter: "codex-synthesis",
+        };
+    }
+    const diagnostic = scan.diagnostics.find((item) => (item.adapter === "codex-synthesis"
+        && requiredSynthesisFailureCodes.has(item.code)));
+    if (!diagnostic) {
+        return undefined;
+    }
+    return {
+        ...diagnostic,
+        level: "error",
+        message: `CI policy requires synthesis, but provider synthesis failed: ${diagnostic.message}`,
+    };
+}
+function sameSynthesisFailure(diagnostic, failure) {
+    return diagnostic.adapter === failure.adapter
+        && diagnostic.code === failure.code
+        && requiredSynthesisFailureCodes.has(diagnostic.code);
+}
+function providerRuntimeSummary(runtime) {
+    return {
+        provider: runtime.provider,
+        model: runtime.model,
+        effort: runtime.effort,
+        timeoutMs: runtime.timeoutMs,
+        retries: runtime.retries,
+        rpm: runtime.rpm,
+        concurrency: runtime.concurrency,
+        tokenBudget: runtime.tokenBudget,
+        excerptBudget: runtime.excerptBudget,
+        offline: runtime.offline,
+        privacyMode: runtime.privacyMode,
+        allowSourceInModel: runtime.allowSourceInModel,
+    };
+}
+function privacyModeFromFlag(value) {
+    if (value === "local-only" || value === "metadata" || value === "source-ok") {
+        return value;
+    }
+    return undefined;
+}
+function numberFlag(context, key) {
+    const value = flagString(context.parsed.flags, key);
+    if (value === undefined || value === "") {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+function uniqueNormalized(values) {
+    return [...new Set(values.map((value) => value.split(path.sep).join("/")))].sort();
+}
+async function supportedSurfaces(root) {
+    const checks = [
+        ["node", "package.json"],
+        ["typescript", "tsconfig.json"],
+        ["python", "pyproject.toml"],
+        ["python", "requirements.txt"],
+        ["make", "Makefile"],
+    ];
+    const found = new Set();
+    for (const [surface, file] of checks) {
+        if (await pathExists(path.join(root, file))) {
+            found.add(surface);
+        }
+    }
+    return [...found].sort();
+}
+async function stateArtifactCounts(paths) {
+    const dirs = [
+        ["runs", paths.runsDir],
+        ["findings", paths.findingsDir],
+        ["observations", paths.observationsDir],
+        ["features", paths.featuresDir],
+        ["evidence", paths.evidenceDir],
+        ["candidates", paths.candidatesDir],
+        ["clusters", paths.clustersDir],
+        ["reports", paths.reportsDir],
+        ["triage", paths.triageDir],
+        ["handoffs", paths.handoffsDir],
+        ["plans", paths.plansDir],
+        ["lifecycle", paths.lifecycleDir],
+        ["revalidations", paths.revalidationsDir],
+        ["ci", paths.ciDir],
+        ["locks", paths.locksDir],
+        ["retention", paths.retentionDir],
+        ["fixes", paths.fixesDir],
+        ["synthesis", paths.synthesisDir],
+    ];
+    const counts = {};
+    for (const [name, dir] of dirs) {
+        counts[name] = await countJsonFiles(dir);
+    }
+    return counts;
+}
+async function countJsonFiles(dir) {
+    try {
+        const files = await readdir(dir);
+        return files.filter((file) => file.endsWith(".json")).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function countBy(items, keyFor) {
+    const counts = {};
+    for (const item of items) {
+        const key = keyFor(item);
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return counts;
+}
+function revalidationOutcomeToLifecycleState(outcome) {
+    switch (outcome) {
+        case "fixed":
+            return "fixed";
+        case "stale":
+            return "stale";
+        case "superseded":
+            return "superseded";
+        case "inconclusive":
+            return "inconclusive";
+        case "changed":
+        case "unchanged":
+            return "open";
+    }
+}
+function revalidationOutcomeToStatus(outcome, fallback) {
+    switch (outcome) {
+        case "fixed":
+            return "fixed";
+        case "stale":
+            return "stale";
+        case "superseded":
+            return "superseded";
+        case "inconclusive":
+        case "changed":
+        case "unchanged":
+            return fallback === "fixed" || fallback === "stale" || fallback === "superseded" ? "open" : fallback;
+    }
+}
 async function packageVersion() {
     try {
         const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");