@nimiplatform/nimi-coding 0.1.0

package/cli/lib/audit-sweep.mjs

@@ -0,0 +1,18 @@
+export { createAuditSweepPlan } from "./audit-sweep-runtime/inventory.mjs";
+export {
+  dispatchAuditSweepChunk,
+  reviewAuditSweepChunk,
+  skipAuditSweepChunk,
+} from "./audit-sweep-runtime/chunks.mjs";
+export { ingestAuditSweepChunk } from "./audit-sweep-runtime/ingest.mjs";
+export { runCodexAuditSweepChunk } from "./audit-sweep-runtime/codex-auditor.mjs";
+export { buildAuditSweepLedger } from "./audit-sweep-runtime/ledger.mjs";
+export {
+  admitAuditSweepRemediationMap,
+  buildAuditSweepRemediationMap,
+} from "./audit-sweep-runtime/remediation.mjs";
+export { resolveAuditSweepFinding } from "./audit-sweep-runtime/rerun.mjs";
+export { buildAuditSweepCloseoutImport } from "./audit-sweep-runtime/closeout.mjs";
+export { getAuditSweepStatus } from "./audit-sweep-runtime/status.mjs";
+export { validateAuditSweepArtifacts } from "./audit-sweep-runtime/validators.mjs";
+export { formatAuditSweepPayload } from "./audit-sweep-runtime/format.mjs";

package/cli/lib/authority-convergence.mjs

@@ -0,0 +1,309 @@
+import { loadTopicRuntimeContracts } from "./contracts.mjs";
+
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.length > 0) : [];
+}
+
+function normalizeAuthorityConvergencePolicy(parsed) {
+  const policy = parsed?.authority_convergence_policy ?? {};
+  const postUpdateReview = policy.post_update_review ?? {};
+  return {
+    triggerPacketKinds: stringList(policy.trigger_packet_kinds),
+    triggerRefPrefixes: stringList(policy.trigger_ref_prefixes),
+    triggerWorkTypes: stringList(policy.trigger_topic_fields?.work_type),
+    requiredResultKind: typeof policy.required_result?.result_kind === "string"
+      ? policy.required_result.result_kind
+      : "audit",
+    passVerdict: typeof policy.required_result?.pass_verdict === "string"
+      ? policy.required_result.pass_verdict
+      : "PASS",
+    blockedVerdicts: stringList(policy.blocked_verdicts),
+    postUpdateReview: {
+      triggerPacketKinds: stringList(postUpdateReview.trigger_packet_kinds),
+      triggerRefPrefixes: stringList(postUpdateReview.trigger_ref_prefixes),
+      requiredResultKind: typeof postUpdateReview.required_result?.result_kind === "string"
+        ? postUpdateReview.required_result.result_kind
+        : "judgement",
+      passVerdict: typeof postUpdateReview.required_result?.pass_verdict === "string"
+        ? postUpdateReview.required_result.pass_verdict
+        : "PASS",
+    },
+  };
+}
+
+export async function loadAuthorityConvergencePolicy(projectRoot) {
+  const loaded = await loadTopicRuntimeContracts(projectRoot);
+  return normalizeAuthorityConvergencePolicy(loaded.authorityConvergencePolicy.data);
+}
+
+export function needsAuthorityConvergenceAudit(topic, packet, policy) {
+  if (policy.triggerPacketKinds.includes(String(packet.packet_kind ?? ""))) return true;
+  if (policy.triggerWorkTypes.includes(String(topic.work_type ?? ""))) return true;
+  const refs = [
+    ...stringList(packet.authority_owner),
+    ...stringList(packet.canonical_seams),
+  ];
+  return refs.some((ref) => policy.triggerRefPrefixes.some((prefix) => (
+    ref === prefix.slice(0, -1) || ref.startsWith(prefix) || ref.includes(prefix)
+  )));
+}
+
+export function needsPostUpdateReview(packet, policy) {
+  const reviewPolicy = policy.postUpdateReview ?? {};
+  if (reviewPolicy.triggerPacketKinds?.includes(String(packet.packet_kind ?? ""))) return true;
+  const refs = [
+    ...stringList(packet.authority_owner),
+    ...stringList(packet.canonical_seams),
+  ];
+  return refs.some((ref) => reviewPolicy.triggerRefPrefixes?.some((prefix) => (
+    ref === prefix.slice(0, -1) || ref.startsWith(prefix) || ref.includes(prefix)
+  )));
+}
+
+export function latestResultOfKind(results, kind) {
+  return [...results].reverse().find((entry) => entry.result?.result_kind === kind) ?? null;
+}
+
+function verifiedAtMs(resultEntry) {
+  const value = resultEntry?.result?.verified_at;
+  if (typeof value !== "string" || value.length === 0) return Number.NaN;
+  return Date.parse(value);
+}
+
+export function hasFreshPassingPostUpdateReview(results, implementationResult, policy) {
+  const reviewPolicy = policy.postUpdateReview ?? {};
+  const implementationVerifiedAt = verifiedAtMs(implementationResult);
+  if (!Number.isFinite(implementationVerifiedAt)) return false;
+  return [...results].reverse().some((entry) => (
+    entry.result?.result_kind === reviewPolicy.requiredResultKind
+    && entry.result?.verdict === reviewPolicy.passVerdict
+    && verifiedAtMs(entry) >= implementationVerifiedAt
+  ));
+}
+
+export function buildPostUpdateReviewDecision({ topicId, wave, packets, results, policy, commandRef }) {
+  const specUpdatingPacket = packets.find((entry) => needsPostUpdateReview(entry.packet, policy));
+  const implementationResult = latestResultOfKind(results, "implementation");
+  if (
+    !specUpdatingPacket
+    || implementationResult?.result?.verdict !== "PASS"
+    || hasFreshPassingPostUpdateReview(results, implementationResult, policy)
+  ) {
+    return null;
+  }
+  const reviewPolicy = policy.postUpdateReview ?? {};
+  return {
+    stopClass: "require_human_confirmation",
+    recommendedAction: "record_result",
+    reasonCode: "spec_update_review_required",
+    recommendedDecision: "record_post_spec_update_judgement_before_wave_closeout",
+    recommendationRationale: "This wave updated spec/authority truth; manager judgement is required before automatic wave closeout.",
+    expectedArtifacts: [`result-${wave.wave_id}-${reviewPolicy.requiredResultKind}.md`],
+    nextCommandRef: commandRef([
+      "result",
+      "record",
+      topicId,
+      "--kind",
+      reviewPolicy.requiredResultKind,
+      "--verdict",
+      "<verdict>",
+      "--from",
+      "<path>",
+      "--verified-at",
+      "<utc>",
+    ]),
+  };
+}
+
+export function authorityConvergenceAuditInstructions(role) {
+  return role === "audit"
+    ? `
+Authority Convergence Audit:
+- Check implementation readiness, owner split, parallel truth, canonical vocabulary, and blocking deferred scope.
+- Do not implement code, edit spec, or decide semantic acceptance.
+- Return PASS, NEEDS_REVISION, or FAIL with blocking_findings, concerns, deferred_non_blockers, authority_refs, and ready_for_implementation.
+`
+    : "";
+}
+
+export function buildAuthorityConvergenceDecision({ topicId, wave, packet, auditResult, policy, commandRef }) {
+  if (packet.status !== "dispatched") {
+    return {
+      stopClass: "continue",
+      recommendedAction: "dispatch_audit",
+      reasonCode: "authority_convergence_audit_required",
+      recommendedDecision: "dispatch_authority_convergence_auditor",
+      recommendationRationale: "This packet changes or anchors authority/spec truth.",
+      expectedArtifacts: [`prompt-${packet.packet_id}-audit.md`],
+      nextCommandRef: commandRef(["audit", "dispatch", topicId, "--packet", packet.packet_id]),
+    };
+  }
+  if (auditResult?.result?.verdict === policy.passVerdict) {
+    return {
+      stopClass: "continue",
+      recommendedAction: "dispatch_worker",
+      reasonCode: "authority_convergence_audit_passed",
+      recommendedDecision: "dispatch_the_selected_packet_to_the_worker",
+      recommendationRationale: "The authority convergence audit passed.",
+      expectedArtifacts: [`prompt-${packet.packet_id}-worker.md`],
+      nextCommandRef: commandRef(["worker", "dispatch", topicId, "--packet", packet.packet_id]),
+    };
+  }
+  if (auditResult && policy.blockedVerdicts.includes(auditResult.result?.verdict)) {
+    return {
+      stopClass: "blocked",
+      recommendedAction: "open_remediation",
+      reasonCode: "authority_convergence_audit_failed",
+      recommendedDecision: "revise_authority_packet_before_implementation_dispatch",
+      recommendationRationale: "The latest authority convergence audit result blocks implementation dispatch.",
+      blockingChecks: [{
+        id: "authority_convergence_audit_verdict",
+        ok: false,
+        reason: `audit verdict is ${auditResult.result?.verdict}`,
+      }],
+      nextCommandRef: commandRef([
+        "remediation",
+        "open",
+        topicId,
+        "--kind",
+        "a",
+        "--reason",
+        "authority-convergence",
+      ]),
+    };
+  }
+  return {
+    stopClass: "await_external_evidence",
+    recommendedAction: "record_result",
+    reasonCode: "awaiting_authority_convergence_audit_result",
+    recommendedDecision: "record_the_authority_convergence_audit_result_when_available",
+    recommendationRationale: "The authority convergence audit must be recorded before implementation dispatch.",
+    expectedArtifacts: [`result-${wave.wave_id}-${policy.requiredResultKind}.md`],
+    nextCommandRef: commandRef([
+      "result",
+      "record",
+      topicId,
+      "--kind",
+      policy.requiredResultKind,
+      "--verdict",
+      "<verdict>",
+      "--from",
+      "<path>",
+      "--verified-at",
+      "<utc>",
+    ]),
+  };
+}
+
+function dispatchWorkerDecision(topicId, packet) {
+  return {
+    stopClass: "continue",
+    recommendedAction: "dispatch_worker",
+    reasonCode: "dispatchable_packet_available",
+    recommendedDecision: "dispatch_the_selected_packet_to_the_worker",
+    recommendationRationale: "A dispatchable packet exists for the admitted wave, so the next operational step is mechanical.",
+    expectedArtifacts: [`prompt-${packet.packet_id}-worker.md`],
+    nextCommandRef: null,
+  };
+}
+
+function dispatchablePacketRank(packet) {
+  const ranks = {
+    candidate: 0,
+    admitted: 1,
+    preflight: 2,
+    dispatched: 3,
+  };
+  return ranks[packet.status] ?? 99;
+}
+
+export async function buildPreImplementationDecision({
+  projectRoot,
+  loaded,
+  wave,
+  commandRef,
+  listWavePackets,
+  listWaveResults,
+  findUniqueFreezableDraftPacket,
+  loadTopicRuntimeAuthority,
+}) {
+  const packets = await listWavePackets(loaded.topicDir, wave.wave_id);
+  const dispatchable = packets
+    .filter((entry) => ["candidate", "admitted", "preflight", "dispatched"].includes(entry.packet.status))
+    .sort((left, right) => (
+      dispatchablePacketRank(left.packet) - dispatchablePacketRank(right.packet)
+      || left.packetRefName.localeCompare(right.packetRefName)
+    ))[0];
+  if (dispatchable) {
+    const policy = await loadAuthorityConvergencePolicy(projectRoot);
+    if (wave.state === "preflight_admitted" && needsAuthorityConvergenceAudit(loaded.topic, dispatchable.packet, policy)) {
+      const auditResult = latestResultOfKind(await listWaveResults(loaded.topicDir, wave.wave_id), policy.requiredResultKind);
+      return buildAuthorityConvergenceDecision({
+        topicId: loaded.topicId,
+        wave,
+        packet: dispatchable.packet,
+        auditResult,
+        policy,
+        commandRef,
+      });
+    }
+    const decision = dispatchWorkerDecision(loaded.topicId, dispatchable.packet);
+    decision.nextCommandRef = commandRef(["worker", "dispatch", loaded.topicId, "--packet", dispatchable.packet.packet_id]);
+    return decision;
+  }
+
+  const autoDraft = await findUniqueFreezableDraftPacket(
+    projectRoot,
+    loaded,
+    wave,
+    await loadTopicRuntimeAuthority(projectRoot),
+  );
+  return autoDraft.ok
+    ? {
+      stopClass: "continue",
+      recommendedAction: "freeze_packet",
+      reasonCode: "draft_packet_ready",
+      recommendedDecision: "freeze_packet",
+      recommendationRationale: "One draft is freezeable.",
+      expectedArtifacts: [`packet-${autoDraft.packet.packet_id}.md`],
+      nextCommandRef: commandRef(["packet", "freeze", loaded.topicId, "--from", autoDraft.draftRef]),
+    }
+    : {
+      stopClass: "require_human_confirmation",
+      recommendedAction: "freeze_packet",
+      reasonCode: autoDraft.reasonCode,
+      recommendedDecision: "select_or_create_draft",
+      recommendationRationale: "Draft packet is missing or ambiguous.",
+      expectedArtifacts: ["packet-<packet-id>.md"],
+      nextCommandRef: commandRef(["packet", "freeze", loaded.topicId, "--from", "<draft-packet>"]),
+    };
+}
+
+export function buildDispatchPrompt(packet, topicId, role) {
+  const auditInstructions = authorityConvergenceAuditInstructions(role);
+  return `# ${role === "worker" ? "Worker" : "Audit"} Dispatch
+Topic: \`${topicId}\`
+Packet: \`${packet.packet_id}\`
+Wave: \`${packet.wave_id}\`
+Packet Kind: \`${packet.packet_kind}\`
+Role: \`${role}\`
+Authority Owner:
+${(Array.isArray(packet.authority_owner) ? packet.authority_owner : []).map((entry) => `- ${entry}`).join(`
+`)}
+Canonical Seams:
+${(Array.isArray(packet.canonical_seams) ? packet.canonical_seams : []).map((entry) => `- ${entry}`).join(`
+`)}
+Forbidden Shortcuts:
+${(Array.isArray(packet.forbidden_shortcuts) ? packet.forbidden_shortcuts : []).map((entry) => `- ${entry}`).join(`
+`)}
+Acceptance Invariants:
+${(Array.isArray(packet.acceptance_invariants) ? packet.acceptance_invariants : []).map((entry) => `- ${entry}`).join(`
+`)}
+Negative Tests:
+${(Array.isArray(packet.negative_tests) ? packet.negative_tests : []).map((entry) => `- ${entry}`).join(`
+`)}
+Reopen Conditions:
+${(Array.isArray(packet.reopen_conditions) ? packet.reopen_conditions : []).map((entry) => `- ${entry}`).join(`
+`)}
+${auditInstructions}`;
+}

package/cli/lib/blueprint-audit.mjs

@@ -0,0 +1,370 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+import { loadBlueprintReference, loadSpecGenerationInputsConfig, loadSpecTreeModelContract } from "./contracts.mjs";
+import { pathExists } from "./fs-helpers.mjs";
+import {
+  localize,
+  styleHeading,
+  styleLabel,
+  styleStatus,
+} from "./ui.mjs";
+
+const BLUEPRINT_AUDIT_CONTRACT_VERSION = "nimicoding.blueprint-audit.v1";
+const DEFAULT_REPORT_PATH = ".nimi/local/report/blueprint-equivalence-audit.json";
+
+async function collectFiles(rootPath, relativePrefix = "") {
+  const info = await pathExists(rootPath);
+  if (!info || !info.isDirectory()) {
+    return [];
+  }
+
+  const entries = await readdir(rootPath, { withFileTypes: true });
+  const collected = [];
+  for (const entry of entries) {
+    const absoluteChildPath = path.join(rootPath, entry.name);
+    const relativeChildPath = relativePrefix ? path.posix.join(relativePrefix, entry.name) : entry.name;
+    if (entry.isDirectory()) {
+      collected.push(...await collectFiles(absoluteChildPath, relativeChildPath));
+    } else if (entry.isFile()) {
+      collected.push(relativeChildPath.split(path.sep).join(path.posix.sep));
+    }
+  }
+
+  return collected.sort();
+}
+
+async function collectDomainInventory(rootPath) {
+  const info = await pathExists(rootPath);
+  if (!info || !info.isDirectory()) {
+    return {
+      domains: [],
+      hasIndex: false,
+      files: [],
+    };
+  }
+
+  const entries = await readdir(rootPath, { withFileTypes: true });
+  const domains = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const kernelPath = path.join(rootPath, entry.name, "kernel");
+    const kernelInfo = await pathExists(kernelPath);
+    if (kernelInfo?.isDirectory()) {
+      domains.push(entry.name);
+    }
+  }
+
+  const indexInfo = await pathExists(path.join(rootPath, "INDEX.md"));
+  const files = await collectFiles(rootPath);
+
+  return {
+    domains: domains.sort(),
+    hasIndex: Boolean(indexInfo?.isFile()),
+    files,
+  };
+}
+
+function categorizeBlueprintFiles(files) {
+  const kernelMarkdown = [];
+  const kernelTables = [];
+  const kernelGenerated = [];
+  const domainGuides = [];
+
+  for (const relativePath of files) {
+    if (/^([^/]+)\/kernel\/[^/]+\.md$/.test(relativePath)) {
+      kernelMarkdown.push(relativePath);
+      continue;
+    }
+
+    if (/^([^/]+)\/kernel\/tables\/.+\.(ya?ml)$/.test(relativePath)) {
+      kernelTables.push(relativePath);
+      continue;
+    }
+
+    if (/^([^/]+)\/kernel\/generated\/.+\.md$/.test(relativePath)) {
+      kernelGenerated.push(relativePath);
+      continue;
+    }
+
+    if (/^[^/]+\/[^/]+\.md$/.test(relativePath)) {
+      domainGuides.push(relativePath);
+    }
+  }
+
+  return {
+    kernelMarkdown,
+    kernelTables,
+    kernelGenerated,
+    domainGuides,
+  };
+}
+
+function compareFileSets(blueprintFiles, canonicalFiles) {
+  const canonicalSet = new Set(canonicalFiles);
+  const blueprintSet = new Set(blueprintFiles);
+
+  return {
+    present: blueprintFiles.filter((filePath) => canonicalSet.has(filePath)),
+    missing: blueprintFiles.filter((filePath) => !canonicalSet.has(filePath)),
+    extra: canonicalFiles.filter((filePath) => !blueprintSet.has(filePath)),
+  };
+}
+
+function buildSummarySection(compareResult) {
+  return {
+    present: compareResult.present.length,
+    missing: compareResult.missing.length,
+    extra: compareResult.extra.length,
+  };
+}
+
+function collectIds(value, ids = []) {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectIds(entry, ids);
+    }
+    return ids;
+  }
+
+  if (value && typeof value === "object") {
+    if (typeof value.id === "string") {
+      ids.push(value.id);
+    }
+    for (const nestedValue of Object.values(value)) {
+      collectIds(nestedValue, ids);
+    }
+  }
+
+  return ids;
+}
+
+async function compareRuleIds(blueprintAbsoluteRoot, canonicalAbsoluteRoot, presentTablePaths) {
+  const files = [];
+  const aggregateMissing = new Set();
+  const aggregateExtra = new Set();
+  const parseErrors = [];
+
+  for (const relativePath of presentTablePaths) {
+    try {
+      const blueprintText = await readFile(path.join(blueprintAbsoluteRoot, relativePath), "utf8");
+      const canonicalText = await readFile(path.join(canonicalAbsoluteRoot, relativePath), "utf8");
+      const blueprintIds = Array.from(new Set(collectIds(YAML.parse(blueprintText)))).sort();
+      const canonicalIds = Array.from(new Set(collectIds(YAML.parse(canonicalText)))).sort();
+      const missingIds = blueprintIds.filter((entry) => !canonicalIds.includes(entry));
+      const extraIds = canonicalIds.filter((entry) => !blueprintIds.includes(entry));
+
+      missingIds.forEach((entry) => aggregateMissing.add(entry));
+      extraIds.forEach((entry) => aggregateExtra.add(entry));
+
+      files.push({
+        path: relativePath,
+        blueprintIds: blueprintIds.length,
+        canonicalIds: canonicalIds.length,
+        missingIds,
+        extraIds,
+      });
+    } catch (error) {
+      parseErrors.push({
+        path: relativePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    comparedFiles: files.length,
+    files,
+    parseErrors,
+    missingRuleIds: Array.from(aggregateMissing).sort(),
+    extraRuleIds: Array.from(aggregateExtra).sort(),
+  };
+}
+
+export async function buildBlueprintAuditPayload(projectRoot, options = {}) {
+  const specTreeModel = await loadSpecTreeModelContract(projectRoot);
+  const blueprintReference = await loadBlueprintReference(projectRoot);
+  const specGenerationInputs = await loadSpecGenerationInputsConfig(projectRoot);
+
+  const canonicalRoot = options.canonicalRoot
+    ?? specTreeModel.canonicalRoot
+    ?? ".nimi/spec";
+  const blueprintRoot = options.blueprintRoot
+    ?? blueprintReference.root
+    ?? specGenerationInputs.benchmarkBlueprintRoot
+    ?? null;
+
+  if (!blueprintRoot) {
+    return {
+      ok: false,
+      exitCode: 2,
+      inputError: true,
+      error: `${localize(
+        "nimicoding blueprint-audit refused: no blueprint root is declared; pass --blueprint-root or add project-local blueprint reference metadata.",
+        "nimicoding blueprint-audit 已拒绝：没有声明 blueprint root；请传入 --blueprint-root，或补充项目本地 blueprint reference 元数据。",
+      )}\n`,
+    };
+  }
+
+  const blueprintAbsoluteRoot = path.resolve(projectRoot, blueprintRoot);
+  const canonicalAbsoluteRoot = path.resolve(projectRoot, canonicalRoot);
+  const blueprintInventory = await collectDomainInventory(blueprintAbsoluteRoot);
+  const canonicalInventory = await collectDomainInventory(canonicalAbsoluteRoot);
+
+  const missingDomains = blueprintInventory.domains.filter((domainId) => !canonicalInventory.domains.includes(domainId));
+  const extraDomains = canonicalInventory.domains.filter((domainId) => !blueprintInventory.domains.includes(domainId));
+  const blueprintFiles = categorizeBlueprintFiles(blueprintInventory.files);
+  const canonicalFiles = categorizeBlueprintFiles(canonicalInventory.files);
+
+  const kernelMarkdown = compareFileSets(blueprintFiles.kernelMarkdown, canonicalFiles.kernelMarkdown);
+  const kernelTables = compareFileSets(blueprintFiles.kernelTables, canonicalFiles.kernelTables);
+  const kernelGenerated = compareFileSets(blueprintFiles.kernelGenerated, canonicalFiles.kernelGenerated);
+  const domainGuides = compareFileSets(blueprintFiles.domainGuides, canonicalFiles.domainGuides);
+  const ruleIdPreservation = await compareRuleIds(
+    blueprintAbsoluteRoot,
+    canonicalAbsoluteRoot,
+    kernelTables.present,
+  );
+
+  const indexPresent = blueprintInventory.hasIndex ? canonicalInventory.hasIndex : true;
+  const ok = missingDomains.length === 0
+    && kernelMarkdown.missing.length === 0
+    && kernelTables.missing.length === 0
+    && kernelGenerated.missing.length === 0
+    && domainGuides.missing.length === 0
+    && ruleIdPreservation.missingRuleIds.length === 0
+    && ruleIdPreservation.parseErrors.length === 0
+    && indexPresent;
+
+  const reportPath = path.join(projectRoot, DEFAULT_REPORT_PATH);
+  const nextSteps = [];
+  if (missingDomains.length > 0 || kernelMarkdown.missing.length > 0 || kernelTables.missing.length > 0 || !indexPresent) {
+    nextSteps.push("Copy the missing blueprint structure into `/.nimi/spec/**` before attempting authority cutover.");
+  }
+  if (kernelGenerated.missing.length > 0) {
+    nextSteps.push("Regenerate derived kernel docs after canonical blueprint content is built out.");
+  }
+  if (domainGuides.missing.length > 0) {
+    nextSteps.push("Thin and map domain guides only after kernel coverage is in place.");
+  }
+  if (ruleIdPreservation.missingRuleIds.length > 0 || ruleIdPreservation.parseErrors.length > 0) {
+    nextSteps.push("Preserve benchmark rule IDs in canonical kernel tables before treating the canonical tree as benchmark-equivalent.");
+  }
+
+  return {
+    contractVersion: BLUEPRINT_AUDIT_CONTRACT_VERSION,
+    ok,
+    exitCode: ok ? 0 : 1,
+    projectRoot,
+    blueprintRoot,
+    canonicalRoot,
+    blueprintReference,
+    specTreeModel: {
+      ok: specTreeModel.ok,
+      profile: specTreeModel.profile,
+      canonicalRoot: specTreeModel.canonicalRoot,
+      authorityMode: specTreeModel.authorityMode,
+    },
+    specGenerationInputs: {
+      ok: specGenerationInputs.ok,
+      mode: specGenerationInputs.mode,
+      acceptanceMode: specGenerationInputs.acceptanceMode,
+      benchmarkBlueprintRoot: specGenerationInputs.benchmarkBlueprintRoot,
+    },
+    inventory: {
+      blueprintDomains: blueprintInventory.domains,
+      canonicalDomains: canonicalInventory.domains,
+      missingDomains,
+      extraDomains,
+      indexPresent,
+    },
+    comparison: {
+      kernelMarkdown: {
+        ...buildSummarySection(kernelMarkdown),
+        missingPaths: kernelMarkdown.missing,
+      },
+      kernelTables: {
+        ...buildSummarySection(kernelTables),
+        missingPaths: kernelTables.missing,
+      },
+      kernelGenerated: {
+        ...buildSummarySection(kernelGenerated),
+        missingPaths: kernelGenerated.missing,
+      },
+      domainGuides: {
+        ...buildSummarySection(domainGuides),
+        missingPaths: domainGuides.missing,
+      },
+    },
+    structuralGaps: {
+      missingDomains,
+      missingKernelMarkdown: kernelMarkdown.missing,
+      missingKernelTables: kernelTables.missing,
+      indexMissing: !indexPresent,
+    },
+    semanticMappingGaps: {
+      ruleIdPreservation,
+    },
+    derivedViewGaps: {
+      missingKernelGenerated: kernelGenerated.missing,
+      missingDomainGuides: domainGuides.missing,
+    },
+    artifactPath: reportPath,
+    nextSteps,
+  };
+}
+
+export function formatBlueprintAuditPayload(payload) {
+  const lines = [
+    styleHeading(`nimicoding blueprint-audit: ${payload.projectRoot}`),
+    "",
+    styleLabel(localize("Summary:", "摘要：")),
+    `  - ${localize("status", "状态")}: ${styleStatus(payload.ok ? "ok" : "needs_attention")}`,
+    `  - ${localize("blueprint root", "blueprint root")}: ${payload.blueprintRoot}`,
+    `  - ${localize("canonical root", "canonical root")}: ${payload.canonicalRoot}`,
+    `  - ${localize("missing domains", "缺失域")}: ${payload.inventory.missingDomains.length}`,
+    `  - ${localize("kernel markdown missing", "缺失 kernel markdown")}: ${payload.comparison.kernelMarkdown.missing}`,
+    `  - ${localize("kernel tables missing", "缺失 kernel tables")}: ${payload.comparison.kernelTables.missing}`,
+    `  - ${localize("generated views missing", "缺失 generated 视图")}: ${payload.comparison.kernelGenerated.missing}`,
+    `  - ${localize("guide mappings missing", "缺失 guide 映射")}: ${payload.comparison.domainGuides.missing}`,
+    `  - ${localize("rule ids missing", "缺失 rule id")}: ${payload.semanticMappingGaps.ruleIdPreservation.missingRuleIds.length}`,
+    "",
+    styleLabel(localize("Coverage:", "覆盖情况：")),
+    `  - ${localize("blueprint domains", "blueprint 域")}: ${payload.inventory.blueprintDomains.length}`,
+    `  - ${localize("canonical domains", "canonical 域")}: ${payload.inventory.canonicalDomains.length}`,
+    `  - ${localize("INDEX present", "INDEX 已存在")}: ${payload.inventory.indexPresent ? "true" : "false"}`,
+  ];
+
+  if (payload.inventory.missingDomains.length > 0) {
+    lines.push(`  - ${localize("missing domain ids", "缺失域 ID")}: ${payload.inventory.missingDomains.join(", ")}`);
+  }
+
+  if (payload.semanticMappingGaps.ruleIdPreservation.missingRuleIds.length > 0) {
+    lines.push(`  - ${localize("missing rule ids", "缺失 rule id")}: ${payload.semanticMappingGaps.ruleIdPreservation.missingRuleIds.join(", ")}`);
+  }
+
+  if (payload.semanticMappingGaps.ruleIdPreservation.parseErrors.length > 0) {
+    lines.push(`  - ${localize("rule-id parse errors", "rule-id 解析错误")}: ${payload.semanticMappingGaps.ruleIdPreservation.parseErrors.length}`);
+  }
+
+  if (payload.nextSteps.length > 0) {
+    lines.push("", styleLabel(localize("Next:", "下一步：")));
+    for (const step of payload.nextSteps) {
+      lines.push(`  - ${localize(step, step)}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeBlueprintAuditArtifact(projectRoot, payload) {
+  await mkdir(path.dirname(payload.artifactPath), { recursive: true });
+  await writeFile(payload.artifactPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return {
+    jsonRef: path.relative(projectRoot, payload.artifactPath).split(path.sep).join(path.posix.sep),
+  };
+}