@nimiplatform/nimi-coding 0.1.0

package/cli/lib/audit-sweep-runtime/risk-budget.mjs

@@ -0,0 +1,300 @@
+import path from "node:path";
+
+import { SEVERITY_RANK, sha256Object } from "./common.mjs";
+import { isPlainObject } from "../value-helpers.mjs";
+
+const RISK_BUDGET_LIMIT_FIELDS = [
+  "maxSweepFindings",
+  "maxDomainFindings",
+  "maxSweepHighRiskFindings",
+  "maxDomainHighRiskFindings",
+];
+
+function positiveIntegerOrNull(value) {
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function buildRiskBudgetPolicy(options = {}) {
+  const hasLimit = RISK_BUDGET_LIMIT_FIELDS.some((field) => positiveIntegerOrNull(options[field]) !== null);
+  if (!hasLimit) {
+    return null;
+  }
+
+  return {
+    mode: "root_cause_aware",
+    duplicate_symptoms_count_as_remediation_obligations: false,
+    high_risk_unique_root_causes_are_canonical: true,
+    accepted_cluster_resume_skip: true,
+    max_sweep_findings: positiveIntegerOrNull(options.maxSweepFindings),
+    max_domain_findings: positiveIntegerOrNull(options.maxDomainFindings),
+    max_sweep_high_risk_findings: positiveIntegerOrNull(options.maxSweepHighRiskFindings),
+    max_domain_high_risk_findings: positiveIntegerOrNull(options.maxDomainHighRiskFindings),
+  };
+}
+
+export function highRiskFinding(finding) {
+  return finding?.severity === "critical" || finding?.severity === "high";
+}
+
+function evidenceRootForFile(chunk, fileRef) {
+  for (const rootRef of chunk.evidence_roots ?? []) {
+    const normalized = String(rootRef).replace(/\\/g, "/").replace(/\/$/, "");
+    if (fileRef === normalized || fileRef.startsWith(`${normalized}/`)) {
+      return normalized;
+    }
+  }
+  return path.posix.dirname(fileRef) || ".";
+}
+
+function normalizeRootCauseField(rawFinding, name) {
+  const rootCause = isPlainObject(rawFinding.root_cause) ? rawFinding.root_cause : {};
+  const value = rootCause[name] ?? rawFinding[name];
+  return nonEmptyString(value) ? String(value).trim().replace(/\\/g, "/") : null;
+}
+
+function normalizeEvidenceRootForChunk(chunk, evidenceRoot) {
+  if (!evidenceRoot) {
+    return null;
+  }
+  if (evidenceRoot === "packet:evidence_inventory") {
+    return null;
+  }
+  for (const rootRef of chunk.evidence_roots ?? []) {
+    const normalized = String(rootRef).replace(/\\/g, "/").replace(/\/$/, "");
+    if (evidenceRoot === normalized || evidenceRoot.startsWith(`${normalized}/`)) {
+      return normalized;
+    }
+  }
+  return null;
+}
+
+export function deriveFindingCluster(rawFinding, finding, chunk, plan) {
+  const authorityRef = normalizeRootCauseField(rawFinding, "authority_ref")
+    ?? chunk.authority_refs?.[0]
+    ?? chunk.files?.[0]
+    ?? finding.location.file;
+  const allowedAuthorityRefs = new Set([...(chunk.authority_refs ?? []), ...(chunk.files ?? [])]);
+  if (chunk.planning_basis === "spec_authority" && !allowedAuthorityRefs.has(authorityRef)) {
+    return { ok: false, error: "root_cause.authority_ref must belong to chunk authority refs" };
+  }
+
+  const explicitEvidenceRoot = normalizeRootCauseField(rawFinding, "evidence_root");
+  const normalizedExplicitEvidenceRoot = normalizeEvidenceRootForChunk(chunk, explicitEvidenceRoot);
+  const packetInventoryRootSentinel = explicitEvidenceRoot === "packet:evidence_inventory";
+  if (explicitEvidenceRoot && !packetInventoryRootSentinel && chunk.planning_basis === "spec_authority" && !normalizedExplicitEvidenceRoot) {
+    return { ok: false, error: "root_cause.evidence_root must belong to chunk evidence roots or a descendant of one" };
+  }
+
+  const rootCauseKey = normalizeRootCauseField(rawFinding, "key") ?? normalizeRootCauseField(rawFinding, "id");
+  const evidenceRoot = normalizedExplicitEvidenceRoot ?? evidenceRootForFile(chunk, finding.location.file);
+  const contractSeam = normalizeRootCauseField(rawFinding, "contract_seam") ?? finding.category;
+  const repairTarget = normalizeRootCauseField(rawFinding, "repair_target") ?? finding.location.file;
+  const fallbackUniqueKey = `${finding.title}:${finding.description}:${finding.location.file}`;
+  const seed = {
+    sweep_id: finding.sweep_id,
+    authority_context: {
+      inventory_hash: plan.inventory_hash,
+      evidence_inventory_hash: plan.evidence_inventory_hash ?? null,
+    },
+    owner_domain: finding.owner_domain,
+    category: finding.category,
+    actionability: finding.actionability,
+    authority_ref: authorityRef,
+    evidence_root: evidenceRoot,
+    contract_seam: contractSeam,
+    repair_target: repairTarget,
+    root_cause_key: rootCauseKey ?? fallbackUniqueKey,
+  };
+
+  return {
+    ok: true,
+    cluster: {
+      cluster_id: `cluster-${sha256Object(seed).slice(0, 16)}`,
+      cluster_key: sha256Object(seed),
+      root_cause_key: rootCauseKey,
+      authority_ref: authorityRef,
+      evidence_root: evidenceRoot,
+      contract_seam: contractSeam,
+      repair_target: repairTarget,
+      authority_context: seed.authority_context,
+    },
+  };
+}
+
+export function ensureClusterStore(store) {
+  if (!Array.isArray(store.clusters)) {
+    store.clusters = [];
+  }
+  if (!Number.isInteger(store.clustered_symptom_count)) {
+    store.clustered_symptom_count = 0;
+  }
+  if (!Number.isInteger(store.accepted_cluster_skip_count)) {
+    store.accepted_cluster_skip_count = 0;
+  }
+  store.remediation_obligation_count = store.findings.length;
+  return store;
+}
+
+function severityRank(value) {
+  return SEVERITY_RANK[value] ?? 99;
+}
+
+export function findingRequiresCanonicalInCluster(finding, cluster) {
+  const currentRank = severityRank(cluster.max_severity);
+  const incomingRank = severityRank(finding.severity);
+  return incomingRank < currentRank;
+}
+
+export function clusterAcceptanceMatchesPlan(cluster, plan) {
+  const acceptance = cluster.acceptance;
+  if (!isPlainObject(acceptance)) {
+    return false;
+  }
+  return acceptance.source_inventory_hash === plan.inventory_hash
+    && (acceptance.source_evidence_inventory_hash ?? null) === (plan.evidence_inventory_hash ?? null);
+}
+
+export function buildDuplicateSymptom(finding, fingerprint, classification) {
+  return {
+    fingerprint,
+    classification,
+    chunk_id: finding.chunk_id,
+    evidence_ref: finding.evidence_ref,
+    severity: finding.severity,
+    title: finding.title,
+    location: finding.location,
+    detected_at: finding.detected_at,
+  };
+}
+
+export function updateClusterWithCanonical(cluster, finding) {
+  if (!cluster.canonical_finding_ids.includes(finding.id)) {
+    cluster.canonical_finding_ids.push(finding.id);
+    cluster.canonical_finding_ids.sort();
+  }
+  if (severityRank(finding.severity) < severityRank(cluster.max_severity)) {
+    cluster.max_severity = finding.severity;
+    cluster.representative_finding_id = finding.id;
+  }
+  cluster.source_chunks = [...new Set([...cluster.source_chunks, finding.chunk_id])].sort();
+  cluster.files = [...new Set([...cluster.files, finding.location.file])].sort();
+  cluster.updated_at = finding.detected_at;
+}
+
+export function createCluster(clusterSeed, finding) {
+  return {
+    ...clusterSeed,
+    representative_finding_id: finding.id,
+    canonical_finding_ids: [finding.id],
+    owner_domain: finding.owner_domain,
+    category: finding.category,
+    actionability: finding.actionability,
+    max_severity: finding.severity,
+    source_chunks: [finding.chunk_id],
+    files: [finding.location.file],
+    duplicate_symptom_count: 0,
+    duplicate_symptoms: [],
+    created_at: finding.detected_at,
+    updated_at: finding.detected_at,
+  };
+}
+
+export function buildRiskBudgetStatus(plan, store, verifiedAt) {
+  const policy = plan.risk_budget_policy;
+  if (!isPlainObject(policy)) {
+    return null;
+  }
+
+  const findings = Array.isArray(store.findings) ? store.findings : [];
+  const clusters = Array.isArray(store.clusters) ? store.clusters : [];
+  const domains = new Map();
+  for (const finding of findings) {
+    const ownerDomain = finding.owner_domain ?? "root";
+    const domain = domains.get(ownerDomain) ?? {
+      owner_domain: ownerDomain,
+      finding_count: 0,
+      high_risk_finding_count: 0,
+      cluster_count: 0,
+      clustered_symptom_count: 0,
+      state: "within_budget",
+      reasons: [],
+    };
+    domain.finding_count += 1;
+    if (highRiskFinding(finding)) {
+      domain.high_risk_finding_count += 1;
+    }
+    domains.set(ownerDomain, domain);
+  }
+  for (const cluster of clusters) {
+    const ownerDomain = cluster.owner_domain ?? "root";
+    const domain = domains.get(ownerDomain) ?? {
+      owner_domain: ownerDomain,
+      finding_count: 0,
+      high_risk_finding_count: 0,
+      cluster_count: 0,
+      clustered_symptom_count: 0,
+      state: "within_budget",
+      reasons: [],
+    };
+    domain.cluster_count += 1;
+    domain.clustered_symptom_count += cluster.duplicate_symptom_count ?? 0;
+    domains.set(ownerDomain, domain);
+  }
+
+  const sweep = {
+    finding_count: findings.length,
+    high_risk_finding_count: findings.filter(highRiskFinding).length,
+    cluster_count: clusters.length,
+    clustered_symptom_count: store.clustered_symptom_count ?? 0,
+    state: "within_budget",
+    reasons: [],
+  };
+
+  if (policy.max_sweep_findings && sweep.finding_count >= policy.max_sweep_findings) {
+    sweep.state = "paused";
+    sweep.reasons.push(`max_sweep_findings:${policy.max_sweep_findings}`);
+  }
+  if (policy.max_sweep_high_risk_findings && sweep.high_risk_finding_count >= policy.max_sweep_high_risk_findings) {
+    sweep.state = "paused";
+    sweep.reasons.push(`max_sweep_high_risk_findings:${policy.max_sweep_high_risk_findings}`);
+  }
+
+  for (const domain of domains.values()) {
+    if (policy.max_domain_findings && domain.finding_count >= policy.max_domain_findings) {
+      domain.state = "paused";
+      domain.reasons.push(`max_domain_findings:${policy.max_domain_findings}`);
+    }
+    if (policy.max_domain_high_risk_findings && domain.high_risk_finding_count >= policy.max_domain_high_risk_findings) {
+      domain.state = "paused";
+      domain.reasons.push(`max_domain_high_risk_findings:${policy.max_domain_high_risk_findings}`);
+    }
+  }
+
+  const domainStatuses = [...domains.values()].sort((left, right) => left.owner_domain.localeCompare(right.owner_domain));
+  return {
+    policy,
+    state: sweep.state === "paused" || domainStatuses.some((domain) => domain.state === "paused") ? "paused" : "within_budget",
+    sweep,
+    domains: domainStatuses,
+    updated_at: verifiedAt,
+  };
+}
+
+export function budgetBlockForChunk(plan, chunk) {
+  const status = plan.risk_budget_status;
+  if (!isPlainObject(status)) {
+    return null;
+  }
+  if (status.sweep?.state === "paused") {
+    return `sweep risk budget paused (${(status.sweep.reasons ?? []).join(", ") || "budget reached"})`;
+  }
+  const domain = (status.domains ?? []).find((entry) => entry.owner_domain === chunk.owner_domain);
+  if (domain?.state === "paused") {
+    return `domain risk budget paused for ${chunk.owner_domain} (${(domain.reasons ?? []).join(", ") || "budget reached"})`;
+  }
+  return null;
+}

package/cli/lib/audit-sweep-runtime/status.mjs

@@ -0,0 +1,62 @@
+import {
+  ACTIVE_CHUNK_STATES,
+  inputError,
+  loadFindings,
+  loadLatestLedger,
+  loadPlan,
+  safeSweepId,
+} from "./common.mjs";
+import { buildCoverageQuality } from "./coverage-quality.mjs";
+import { ensureClusterStore } from "./risk-budget.mjs";
+
+export async function getAuditSweepStatus(projectRoot, options) {
+  const sweepId = safeSweepId(options.sweepId);
+  if (!sweepId) {
+    return inputError("nimicoding audit-sweep refused: --sweep-id is required.\n");
+  }
+
+  const planResult = await loadPlan(projectRoot, sweepId);
+  if (!planResult.ok) {
+    return inputError(planResult.error);
+  }
+  const { findingsRef, store } = await loadFindings(projectRoot, sweepId);
+  ensureClusterStore(store);
+  const latestLedger = await loadLatestLedger(projectRoot, sweepId);
+  const chunks = Array.isArray(planResult.plan.chunks) ? planResult.plan.chunks : [];
+  const coverageQuality = latestLedger.ok
+    ? latestLedger.ledger.coverage_quality ?? buildCoverageQuality(planResult.plan, chunks, planResult.plan.coverage)
+    : buildCoverageQuality(planResult.plan, chunks, planResult.plan.coverage);
+  const auditValidity = latestLedger.ok ? latestLedger.ledger.audit_validity ?? null : null;
+
+  return {
+    ok: true,
+    exitCode: 0,
+    sweepId,
+    planRef: planResult.planRef,
+    findingsRef,
+    latestLedgerRef: latestLedger.ok ? latestLedger.ledgerRef : null,
+    coverage: {
+      totalFiles: planResult.plan.coverage?.total_files ?? 0,
+      includedFiles: planResult.plan.coverage?.included_files ?? 0,
+      ...(planResult.plan.planning_basis?.mode === "spec_authority" ? {
+        authorityFiles: planResult.plan.coverage?.authority_files ?? 0,
+        evidenceFiles: planResult.plan.coverage?.evidence_files ?? 0,
+        unmappedEvidenceFiles: planResult.plan.coverage?.unmapped_evidence_files ?? 0,
+      } : {}),
+      frozenChunks: chunks.filter((chunk) => chunk.state === "frozen").length,
+      activeChunks: chunks.filter((chunk) => ACTIVE_CHUNK_STATES.has(chunk.state)).length,
+      chunks: chunks.reduce((acc, chunk) => {
+        acc[chunk.state] = (acc[chunk.state] ?? 0) + 1;
+        return acc;
+      }, {}),
+    },
+    findingCount: store.findings.length,
+    findingClusterCount: store.clusters.length,
+    clusteredSymptomCount: store.clustered_symptom_count ?? 0,
+    remediationObligationCount: store.remediation_obligation_count ?? store.findings.length,
+    unresolvedFindingCount: store.findings.filter((finding) => finding.disposition === "open").length,
+    riskBudgetStatus: planResult.plan.risk_budget_status ?? null,
+    coverageQuality,
+    auditValidity,
+  };
+}

package/cli/lib/audit-sweep-runtime/validators-ledger.mjs

@@ -0,0 +1,215 @@
+import {
+  ACTIVE_CHUNK_STATES,
+  artifactPath,
+  ledgerRef,
+  loadLatestLedger,
+  loadYamlRef,
+  remediationMapRef,
+  sha256Object,
+} from "./common.mjs";
+import { pathExists } from "../fs-helpers.mjs";
+import { isPlainObject } from "../value-helpers.mjs";
+
+function check(checks, id, ok, reason) {
+  checks.push({ id, ok, reason });
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+async function refExists(projectRoot, ref) {
+  const info = await pathExists(artifactPath(projectRoot, ref));
+  return Boolean(info?.isFile());
+}
+
+async function validateEvidenceRefs(projectRoot, refs, checks, prefix) {
+  for (const ref of refs.filter((entry) => typeof entry === "string" && entry.trim())) {
+    check(checks, `${prefix}_${ref.replace(/[^a-zA-Z0-9]+/g, "_")}_exists`, await refExists(projectRoot, ref), `referenced artifact exists: ${ref}`);
+  }
+}
+
+export function deriveLedgerSnapshotId(sweepId, plan, chunks, findings, clusters = []) {
+  const snapshotSeed = {
+    sweepId,
+    inventoryHash: plan.inventory_hash,
+    evidenceInventoryHash: plan.evidence_inventory_hash ?? null,
+    chunkStates: chunks.map((chunk) => ({
+      chunk_id: chunk.chunk_id,
+      state: chunk.state,
+      evidence_ref: chunk.evidence_ref ?? null,
+      finding_count: chunk.finding_count ?? 0,
+    })),
+    findings: findings.map((finding) => ({
+      id: finding.id,
+      fingerprint: finding.fingerprint,
+      disposition: finding.disposition,
+      resolution_evidence_ref: finding.resolution?.evidence_ref ?? null,
+    })),
+    clusters: clusters.map((cluster) => ({
+      cluster_id: cluster.cluster_id,
+      canonical_finding_ids: cluster.canonical_finding_ids,
+      duplicate_symptom_count: cluster.duplicate_symptom_count ?? 0,
+    })),
+  };
+  return `ledger-${sha256Object(snapshotSeed).slice(0, 16)}`;
+}
+
+export function validateClusterShape(cluster, findingIds, checks) {
+  check(checks, `cluster_${cluster?.cluster_id ?? "unknown"}_required_fields`, isPlainObject(cluster)
+    && nonEmptyString(cluster.cluster_id)
+    && nonEmptyString(cluster.cluster_key)
+    && nonEmptyString(cluster.representative_finding_id)
+    && Array.isArray(cluster.canonical_finding_ids)
+    && Array.isArray(cluster.duplicate_symptoms), "audit finding cluster has required fields");
+  if (!isPlainObject(cluster)) {
+    return;
+  }
+  check(checks, `cluster_${cluster.cluster_id}_findings_known`, findingIds.has(cluster.representative_finding_id)
+    && cluster.canonical_finding_ids.every((findingId) => findingIds.has(findingId)), "audit finding cluster references known canonical findings");
+  check(checks, `cluster_${cluster.cluster_id}_symptom_count_matches`, (cluster.duplicate_symptom_count ?? 0) === cluster.duplicate_symptoms.length, "audit finding cluster duplicate symptom count matches symptoms");
+}
+
+function buildLedgerExpectedCounts(plan, chunks, findings, clusters = []) {
+  const frozenChunks = chunks.filter((chunk) => chunk.state === "frozen");
+  const lifecycleCoverage = {
+    frozen_chunks: frozenChunks.length,
+    failed_chunks: chunks.filter((chunk) => chunk.state === "failed").length,
+    skipped_chunks: chunks.filter((chunk) => chunk.state === "skipped").length,
+    active_chunks: chunks.filter((chunk) => ACTIVE_CHUNK_STATES.has(chunk.state)).length,
+  };
+  const coverage = plan.planning_basis?.mode === "spec_authority"
+    ? buildSpecAuthorityCoverage(plan, frozenChunks, lifecycleCoverage)
+    : buildFileCoverage(plan, frozenChunks, lifecycleCoverage);
+  const findingPosture = {
+    open: findings.filter((finding) => finding.disposition === "open").length,
+    remediated: findings.filter((finding) => finding.disposition === "remediated").length,
+    accepted_risk: findings.filter((finding) => finding.disposition === "accepted-risk").length,
+    false_positive: findings.filter((finding) => finding.disposition === "false-positive").length,
+    deferred_backlog: findings.filter((finding) => finding.disposition === "deferred-backlog").length,
+  };
+  return {
+    coverage,
+    findingPosture,
+    findingClusterCount: clusters.length,
+    clusteredSymptomCount: clusters.reduce((total, cluster) => total + (cluster.duplicate_symptom_count ?? 0), 0),
+  };
+}
+
+function buildSpecAuthorityCoverage(plan, frozenChunks, lifecycleCoverage) {
+  const authorityTotal = plan.coverage?.authority_files ?? plan.coverage?.included_files ?? 0;
+  const evidenceTotal = plan.coverage?.evidence_files ?? plan.evidence_inventory?.length ?? 0;
+  const emptyEvidenceChunks = plan.coverage?.authority_chunks_without_evidence_inventory
+    ?? (Array.isArray(plan.chunks) ? plan.chunks.filter((chunk) => (chunk.evidence_inventory ?? []).length === 0).length : 0)
+    ?? 0;
+  const auditedAuthorityFiles = new Set(frozenChunks.flatMap((chunk) => chunk.files));
+  const auditedEvidenceFiles = new Set(frozenChunks.flatMap((chunk) => chunk.evidence_inventory ?? []));
+  return {
+    total_files: authorityTotal + evidenceTotal,
+    included_files: authorityTotal + evidenceTotal,
+    audited_files: auditedAuthorityFiles.size + auditedEvidenceFiles.size,
+    authority_coverage: {
+      total_files: authorityTotal,
+      audited_files: auditedAuthorityFiles.size,
+      chunks_without_evidence_inventory: emptyEvidenceChunks,
+    },
+    evidence_coverage: {
+      total_files: evidenceTotal,
+      audited_files: auditedEvidenceFiles.size,
+      unmapped_files: plan.coverage?.unmapped_evidence_files ?? plan.unmapped_evidence_files?.length ?? 0,
+    },
+    ...lifecycleCoverage,
+  };
+}
+
+function buildFileCoverage(plan, frozenChunks, lifecycleCoverage) {
+  const auditedFiles = new Set(frozenChunks.flatMap((chunk) => chunk.files));
+  return {
+    total_files: plan.coverage.total_files,
+    included_files: plan.coverage.included_files,
+    audited_files: auditedFiles.size,
+    ...lifecycleCoverage,
+  };
+}
+
+export async function validateLatestLedger(projectRoot, sweepId, plan, chunks, findings, clusters, checks) {
+  const latest = await loadLatestLedger(projectRoot, sweepId);
+  check(checks, "latest_ledger_loadable", latest.ok, "latest ledger pointer and ledger are loadable");
+  if (!latest.ok) {
+    return null;
+  }
+  const ledger = latest.ledger;
+  const expectedSnapshotId = deriveLedgerSnapshotId(sweepId, plan, chunks, findings, clusters);
+  check(checks, "ledger_snapshot_id_content_hash", ledger.snapshot_id === expectedSnapshotId && latest.ledgerRef === ledgerRef(sweepId, expectedSnapshotId), "ledger snapshot id is content-derived and current");
+  const expected = buildLedgerExpectedCounts(plan, chunks, findings, clusters);
+  check(checks, "ledger_coverage_counts_match", JSON.stringify(ledger.coverage) === JSON.stringify(expected.coverage), "ledger coverage counts match plan and chunks");
+  check(checks, "ledger_finding_counts_match", ledger.finding_count === findings.length
+    && ledger.unresolved_finding_count === expected.findingPosture.open
+    && JSON.stringify(ledger.finding_posture) === JSON.stringify(expected.findingPosture), "ledger finding counts match findings store");
+  check(checks, "ledger_cluster_counts_match", (ledger.finding_cluster_count ?? 0) === expected.findingClusterCount
+    && (ledger.clustered_symptom_count ?? 0) === expected.clusteredSymptomCount
+    && (ledger.remediation_obligation_count ?? findings.length) === findings.length, "ledger cluster counts match findings store");
+  check(checks, "ledger_latest_pointer_matches", latest.ledgerRef === ledgerRef(sweepId, ledger.snapshot_id), "latest pointer references the immutable ledger snapshot");
+  check(checks, "ledger_status_valid", ["candidate_ready", "partial", "blocked", "blocked_evidence_incomplete", "partial_authority_only"].includes(ledger.status), "ledger status is valid");
+  checkLedgerSpecCoverage(plan, ledger, checks);
+  await validateEvidenceRefs(projectRoot, [
+    ledger.plan_ref,
+    ...(Array.isArray(ledger.chunk_refs) ? ledger.chunk_refs : []),
+    ledger.findings_ref,
+    ...(Array.isArray(ledger.evidence_refs) ? ledger.evidence_refs : []),
+    ledger.report_ref,
+    ledger.run_ledger_ref,
+  ], checks, "ledger_ref");
+  return { ledger, ledger_ref: latest.ledgerRef, snapshot_id: ledger.snapshot_id };
+}
+
+function checkLedgerSpecCoverage(plan, ledger, checks) {
+  check(checks, "ledger_candidate_ready_strict", ledger.status !== "candidate_ready"
+    || (ledger.coverage.included_files > 0 && ledger.coverage.audited_files === ledger.coverage.included_files && ledger.coverage.active_chunks === 0 && ledger.coverage.failed_chunks === 0 && ledger.coverage.skipped_chunks === 0), "candidate_ready requires all included files audited and all chunks frozen");
+  if (plan.planning_basis?.mode !== "spec_authority") {
+    return;
+  }
+  const authorityFull = ledger.coverage.authority_coverage?.total_files > 0
+    && ledger.coverage.authority_coverage.audited_files === ledger.coverage.authority_coverage.total_files;
+  const evidenceFull = ledger.coverage.evidence_coverage?.audited_files === ledger.coverage.evidence_coverage?.total_files
+    && ledger.coverage.evidence_coverage?.unmapped_files === 0;
+  check(checks, "ledger_spec_coverage_split_present", isPlainObject(ledger.coverage.authority_coverage)
+    && isPlainObject(ledger.coverage.evidence_coverage), "spec-authority ledger splits authority and evidence coverage");
+  check(checks, "ledger_spec_coverage_quality_present", isPlainObject(ledger.coverage_quality), "spec-authority ledger exposes coverage_quality");
+  check(checks, "ledger_spec_audit_validity_present", isPlainObject(ledger.audit_validity), "spec-authority ledger exposes audit_validity");
+  check(checks, "ledger_spec_candidate_ready_requires_evidence", ledger.status !== "candidate_ready"
+    || (authorityFull && evidenceFull), "candidate_ready requires full authority and evidence coverage");
+  check(checks, "ledger_spec_no_full_with_unmapped_evidence", ledger.status !== "candidate_ready"
+    || ledger.coverage.evidence_coverage?.unmapped_files === 0, "candidate_ready requires zero unmapped evidence files");
+}
+
+export async function validateRemediationMap(projectRoot, sweepId, ledgerInfo, findings, clusters, checks) {
+  if (!ledgerInfo) {
+    check(checks, "remediation_map_ledger_available", false, "remediation map validation requires latest ledger");
+    return null;
+  }
+  const mapRef = remediationMapRef(sweepId, ledgerInfo.snapshot_id);
+  const remediationMap = await loadYamlRef(projectRoot, mapRef);
+  const openFindings = findings.filter((finding) => finding.disposition === "open");
+  if (!isPlainObject(remediationMap)) {
+    check(checks, "remediation_map_required", false, "remediation map exists for the latest ledger");
+    return null;
+  }
+  check(checks, "remediation_map_identity", remediationMap.kind === "audit-remediation-map" && remediationMap.sweep_id === sweepId && remediationMap.source_ledger_ref === ledgerInfo.ledger_ref, "remediation map references latest ledger");
+  const findingIds = new Set(findings.map((finding) => finding.id));
+  const clusterIds = new Set(clusters.map((cluster) => cluster.cluster_id));
+  const mappedIds = new Set();
+  const wavesOk = Array.isArray(remediationMap.waves) && remediationMap.waves.every((wave) => {
+    if (!isPlainObject(wave) || !nonEmptyString(wave.wave_id) || !Array.isArray(wave.finding_ids) || !Array.isArray(wave.write_set)) {
+      return false;
+    }
+    for (const findingId of wave.finding_ids) {
+      mappedIds.add(findingId);
+    }
+    return wave.finding_ids.every((findingId) => findingIds.has(findingId))
+      && (!Array.isArray(wave.cluster_ids) || wave.cluster_ids.every((clusterId) => clusterIds.has(clusterId)));
+  });
+  check(checks, "remediation_map_waves_valid", wavesOk, "remediation map waves reference known findings");
+  check(checks, "remediation_map_open_findings_covered", openFindings.every((finding) => mappedIds.has(finding.id)), "all open findings are covered by remediation map waves");
+  return { remediationMap, remediation_map_ref: mapRef };
+}