@nimiplatform/nimi-coding 0.1.0 → 0.2.0

package/README.md

@@ -19,14 +19,14 @@ The primary `nimicoding` path is for an ordinary project with mixed inputs:
 6. close out reconstruction
 7. hand off `doc_spec_audit` and close it out locally
 
-`blueprint-audit`, benchmark parity, and direct-copy helpers remain available,
-but they are support-only or repo-local special cases. They do not define
-default reconstruction completion.
+`blueprint-audit` and benchmark parity remain available, but they are
+support-only package fixtures. They do not define default reconstruction
+completion for a host project.
 
-In this monorepo, `/.nimi/spec/**` is now the repo-wide product authority.
-Pre-cutover authority history now lives in Git rather than a repo-local
-archive tree. Pre-cutover readiness work was evidence only and did not
-authorize the flip by itself.
+In a host project, `/.nimi/spec/**` becomes product authority only after that
+project admits or reconstructs it. `nimicoding` provides the CLI, injected
+`.nimi/{config,contracts,methodology}/**` contracts, and validators; it does
+not make a host read package source paths directly.
 
 ## Current Status
 
@@ -37,7 +37,7 @@ Its completed standalone scope is:
 - package identity
 - repository foundation
 - initial AI-native methodology seed
-- package-owned repo-local support profile source for future governance slices
+- package-owned support profile source for future governance slices
 - machine-readable reconstruction, doc-spec-audit, and high-risk execution result contracts
 - package-owned canonical high-risk admission schema contract
 - seed-only high-risk execution schemas for packet, orchestration-state, prompt, worker-output, and acceptance
@@ -73,8 +73,8 @@ At the current stage it provides:
 - a primary `nimicoding start` entrypoint for bootstrap, resume, and next-stage AI task prep
 - a conservative `nimicoding clear` entrypoint for removing package-managed setup without deleting project-owned truth
 - a bounded `nimicoding doctor`
-- an explicit `nimicoding blueprint-audit` equivalence check for comparing a repo-local blueprint root with the candidate canonical tree under `.nimi/spec`
-- a repo-local `pnpm check:spec-authority-cutover-readiness` gate for pre-cutover readiness validation before authority execution
+- an explicit `nimicoding blueprint-audit` equivalence check for comparing a fixture or host blueprint root with the candidate canonical tree under `.nimi/spec`
+- surface validators for placement, table-family, projection-edge, guidance-body, domain-admission, and tracked-output admission boundaries
 - an explicit `nimicoding handoff` export
 - an explicit `nimicoding admit-high-risk-decision` semantic admission surface
 - a local-only `nimicoding closeout` projection
@@ -91,7 +91,7 @@ Current `nimicoding start` behavior is intentionally narrow:
 - detect the current project state and continue from the right stage
 - create or resume the `.nimi/**` seed by projecting package-owned source into host paths
 - seed AI-native spec-reconstruction guidance inside `.nimi/**`
-- keep repo-local support-only methodology assets package-owned unless a host explicitly opts into them
+- keep support-only methodology assets package-owned unless a host explicitly opts into them
 - seed package-owned machine contracts inside `.nimi/contracts/**`
 - seed package-owned execution schemas for future high-risk methodology artifacts without admitting runtime ownership
 - seed canonical skill-manifest, host-profile, installer, delegated runtime contract, installer result contract, installer operational evidence home, and external handoff truth inside `.nimi/**`
@@ -198,21 +198,20 @@ cross-report navigation harder. Stable machine report artifacts that are meant
 to behave like a current snapshot, such as `blueprint-equivalence-audit.json`,
 should keep their fixed names.
 
-## Canonical Spec Redesign Prep
+## Canonical Spec Surface Model
 
-The package now seeds Phase 0 / Phase 1 canonical-spec redesign contracts under
-`.nimi/spec/_meta/**` together with rewritten `bootstrap-state.yaml` and
-`product-scope.yaml`.
+The package seeds the host-local contracts needed to reconstruct and validate a
+canonical spec tree without putting package methodology or lifecycle state under
+the host product-authority root.
 
 At this stage:
 
-- these files are machine contracts and implementation authority for canonical spec generation
-- active repository authority now lives under `/.nimi/spec/**`
-- `start`, `doctor`, `handoff`, `closeout`, and high-risk gating already read the canonical tree lifecycle instead of treating the old five-file compact model as authoritative completion
+- `config/**`, `contracts/**`, `methodology/**`, and `spec/**` are package source for the npm package
+- generated host projects receive injected `.nimi/{config,contracts,methodology}/**` projections and own their `.nimi/spec/**` product authority
+- `start`, `doctor`, `handoff`, `closeout`, and high-risk gating read host-local `.nimi/**` projections instead of requiring access to package source paths
 - `nimicoding blueprint-audit` remains the explicit audit surface for benchmark-vs-canonical equivalence checks; it does not perform routing changes on its own
-- `pnpm check:spec-authority-cutover-readiness` remains a pre-cutover readiness aggregator; after cutover it is historical/preflight-only rather than the active authority source
 - canonical spec generation now reads mixed inputs from `.nimi/config/spec-generation-inputs.yaml` and treats any blueprint root as an optional benchmark rather than a universal host assumption
-- completed canonical reconstruction now requires both structural validity and file-level auditability under `.nimi/spec/_meta/spec-generation-audit.yaml`
+- completed canonical reconstruction now requires structural validity and may carry file-level auditability under `.nimi/local/state/spec-generation/spec-generation-audit.yaml`
 - `nimicoding validate-spec-tree` checks canonical tree structure, while `nimicoding validate-spec-audit` checks per-file grounding, inference, and unresolved-gap tracking
 
 Current `nimicoding doctor` behavior is intentionally narrow:

package/adapters/oh-my-codex/README.md

@@ -97,8 +97,8 @@ nimicoding handoff --skill spec_reconstruction --json
 Use the JSON payload as OMX's machine contract. `--prompt` may still be used
 as a host briefing, but it is not the authoritative surface. OMX should
 return only the declared canonical tree outputs and must not invent new semantic
-owners. In this monorepo the explicit cutover batch has already made
-`.nimi/spec/**` the current authority root; OMX still must not redefine that
+owners. In a host project, `.nimi/spec/**` is current authority only when the
+host has admitted or reconstructed it; OMX still must not redefine that
 authority or promote its own runtime state into semantic truth.
 
 Then project the closeout locally:
@@ -152,13 +152,12 @@ For now, treat OMX output as execution candidate material:
 
 In practice, this means the first real user can use OMX as the execution host
 today, while standalone `nimicoding` remains the host-agnostic semantic and
-interop boundary package. The promoted internal
-[`nimi-coding`](/Users/snwozy/nimi-realm/nimi/nimi-coding) still owns
-packet-bound runtime, provider-backed execution, scheduler, notification, and
-automation surfaces, even though standalone
-`nimicoding closeout` can now import a fail-closed local-only execution
-summary and `nimicoding ingest-high-risk-execution` can mechanically validate
-the referenced packet/prompt/output candidates while
+interop boundary package. The standalone package intentionally does not own
+packet-bound runtime, provider-backed execution, scheduler, notification, or
+automation surfaces yet, even though `nimicoding closeout` can import a
+fail-closed local-only execution summary and
+`nimicoding ingest-high-risk-execution` can mechanically validate the
+referenced packet/prompt/output candidates while
 `nimicoding review-high-risk-execution` can project a manager-ready local
 attachment bundle, `nimicoding decide-high-risk-execution` can record a
 manager-owned local disposition, and `nimicoding admit-high-risk-decision`

package/cli/commands/audit-sweep.mjs

@@ -22,8 +22,8 @@ function readRequiredValue(args, index, optionName, commandName) {
     return {
       ok: false,
       error: `${localize(
-        `nimicoding audit-sweep ${commandName} refused: ${optionName} requires a value.`,
-        `nimicoding audit-sweep ${commandName} 已拒绝：${optionName} 需要一个值。`,
+        `nimicoding sweep audit ${commandName} refused: ${optionName} requires a value.`,
+        `nimicoding sweep audit ${commandName} 已拒绝：${optionName} 需要一个值。`,
       )}\n`,
     };
   }
@@ -34,8 +34,8 @@ function unknownOption(commandName, arg) {
   return {
     ok: false,
     error: `${localize(
-      `nimicoding audit-sweep ${commandName} refused: unknown option ${arg}.`,
-      `nimicoding audit-sweep ${commandName} 已拒绝：未知选项 ${arg}。`,
+      `nimicoding sweep audit ${commandName} refused: unknown option ${arg}.`,
+      `nimicoding sweep audit ${commandName} 已拒绝：未知选项 ${arg}。`,
     )}\n`,
   };
 }
@@ -65,8 +65,8 @@ function parseOptions(args, commandName, spec) {
         return {
           ok: false,
           error: `${localize(
-            `nimicoding audit-sweep ${commandName} refused: ${arg} must be a positive integer.`,
-            `nimicoding audit-sweep ${commandName} 已拒绝：${arg} 必须是正整数。`,
+            `nimicoding sweep audit ${commandName} refused: ${arg} must be a positive integer.`,
+            `nimicoding sweep audit ${commandName} 已拒绝：${arg} 必须是正整数。`,
           )}\n`,
         };
       }
@@ -85,8 +85,8 @@ function parseOptions(args, commandName, spec) {
     return {
       ok: false,
       error: `${localize(
-        `nimicoding audit-sweep ${commandName} refused: missing required options: ${missing.join(", ")}.`,
-        `nimicoding audit-sweep ${commandName} 已拒绝：缺少必填选项：${missing.join(", ")}。`,
+        `nimicoding sweep audit ${commandName} refused: missing required options: ${missing.join(", ")}.`,
+        `nimicoding sweep audit ${commandName} 已拒绝：缺少必填选项：${missing.join(", ")}。`,
       )}\n`,
     };
   }
@@ -269,8 +269,8 @@ function parseAuditSweepOptions(args) {
   return {
     ok: false,
     error: `${localize(
-      "nimicoding audit-sweep refused: expected one of `plan`, `chunk dispatch`, `chunk audit-codex`, `chunk ingest`, `chunk review`, `chunk skip`, `ledger build`, `remediation-map build`, `remediation-map admit`, `finding resolve`, `closeout summary`, `status`, or `validate`.",
-      "nimicoding audit-sweep 已拒绝：需要使用 `plan`、`chunk dispatch`、`chunk ingest`、`chunk review`、`chunk skip`、`ledger build`、`remediation-map build`、`remediation-map admit`、`finding resolve`、`closeout summary`、`status` 或 `validate`。",
+      "nimicoding sweep audit refused: expected one of `plan`, `chunk dispatch`, `chunk audit-codex`, `chunk ingest`, `chunk review`, `chunk skip`, `ledger build`, `remediation-map build`, `remediation-map admit`, `finding resolve`, `closeout summary`, `status`, or `validate`.",
+      "nimicoding sweep audit 已拒绝：需要使用 `plan`、`chunk dispatch`、`chunk ingest`、`chunk review`、`chunk skip`、`ledger build`、`remediation-map build`、`remediation-map admit`、`finding resolve`、`closeout summary`、`status` 或 `validate`。",
     )}\n`,
   };
 }

package/cli/commands/classify-spec-tree.mjs

@@ -0,0 +1,5 @@
+import { runSurfaceValidatorCommand } from "./surface-validator-command.mjs";
+
+export function runClassifySpecTree(args) {
+  return runSurfaceValidatorCommand(args, "classify-spec-tree");
+}

package/cli/commands/closeout.mjs

@@ -163,6 +163,9 @@ export async function runCloseout(args) {
   const payload = await buildCloseoutPayload(process.cwd(), effectiveOptions);
   if (payload.inputError) {
     process.stderr.write(payload.error);
+    if (parsed.options.json) {
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    }
     return payload.exitCode;
   }
 

package/cli/commands/generate-spec-derived-docs.mjs

@@ -1,6 +1,13 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { localize } from "../lib/ui.mjs";
 import { loadGovernanceConfig, requireProfile } from "../lib/internal/governance/config.mjs";
 import { runCommand } from "../lib/internal/governance/runner.mjs";
+import { parseSpecGenerationInputsConfig } from "../lib/internal/contracts-parse.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
 function parseOptions(args) {
   const options = {
@@ -100,6 +107,19 @@ export async function runGenerateSpecDerivedDocs(args) {
     return 2;
   }
 
+  const packageInputsText = await readFile(
+    path.join(PACKAGE_ROOT, "config", "spec-generation-inputs.yaml"),
+    "utf8",
+  );
+  const packageInputs = parseSpecGenerationInputsConfig(packageInputsText);
+  if (!packageInputs.ok || !packageInputs.generationOrder.includes("validate_placement")) {
+    process.stderr.write(localize(
+      "nimicoding generate-spec-derived-docs refused: package spec generation inputs must be class-filtered and include placement validation.\n",
+      "nimicoding generate-spec-derived-docs 已拒绝：package spec generation inputs 必须按 surface class 过滤并包含 placement validation。\n",
+    ));
+    return 2;
+  }
+
   let failed = false;
   for (const scope of scopeResolution.scopes) {
     const commands = governance.config.specGovernance.generateCommands[scope] || [];

package/cli/commands/generate-spec-migration-plan.mjs

@@ -0,0 +1,30 @@
+import {
+  generateSpecMigrationPlan,
+  parseSurfaceValidatorOptions,
+  writeMigrationPlanIfRequested,
+} from "../lib/internal/surface-taxonomy-validators.mjs";
+import { localize } from "../lib/ui.mjs";
+
+export async function runGenerateSpecMigrationPlan(args) {
+  const parsed = parseSurfaceValidatorOptions(args);
+  if (!parsed.ok) {
+    process.stderr.write(localize(
+      `nimicoding generate-spec-migration-plan refused: ${parsed.error}\n`,
+      `nimicoding generate-spec-migration-plan 已拒绝：${parsed.error}\n`,
+    ));
+    return 2;
+  }
+
+  try {
+    const report = await generateSpecMigrationPlan(process.cwd(), parsed.options);
+    await writeMigrationPlanIfRequested(report, parsed.options.emit, process.cwd());
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report.ok ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(localize(
+      `nimicoding generate-spec-migration-plan refused: ${error.message}\n`,
+      `nimicoding generate-spec-migration-plan 已拒绝：${error.message}\n`,
+    ));
+    return 2;
+  }
+}

package/cli/commands/start.mjs

@@ -343,8 +343,12 @@ function buildTaskStageLines(mode) {
 }
 
 function canonicalTreeReady(doctorResult) {
-  return doctorResult.lifecycleState?.treeState === "canonical_tree_ready"
+  const v2Ready = doctorResult.specGenerationInputs?.mode === "class_filtered"
+    && doctorResult.canonicalTree?.requiredFilesValid === true
+    && doctorResult.specGenerationAudit?.ok === true;
+  const legacyReady = doctorResult.lifecycleState?.treeState === "canonical_tree_ready"
     && doctorResult.canonicalTree?.requiredFilesValid === true;
+  return v2Ready || legacyReady;
 }
 
 function determineWizardStage(doctorResult) {

package/cli/commands/surface-validator-command.mjs

@@ -0,0 +1,49 @@
+import {
+  classifySpecSurface,
+  parseSurfaceValidatorOptions,
+  validateDomainAdmission,
+  validateGuidanceBodies,
+  validatePlacement,
+  validateProjectionEdges,
+  validateTableFamily,
+  validateTrackedOutputAdmission,
+  writeInventoryIfRequested,
+} from "../lib/internal/surface-taxonomy-validators.mjs";
+import { localize } from "../lib/ui.mjs";
+
+const VALIDATORS = {
+  "classify-spec-tree": classifySpecSurface,
+  "validate-placement": validatePlacement,
+  "validate-table-family": validateTableFamily,
+  "validate-projection-edges": validateProjectionEdges,
+  "validate-guidance-bodies": validateGuidanceBodies,
+  "validate-domain-admission": validateDomainAdmission,
+  "validate-tracked-output-admission": validateTrackedOutputAdmission,
+};
+
+export async function runSurfaceValidatorCommand(args, validatorName) {
+  const parsed = parseSurfaceValidatorOptions(args);
+  if (!parsed.ok) {
+    process.stderr.write(localize(
+      `nimicoding ${validatorName} refused: ${parsed.error}\n`,
+      `nimicoding ${validatorName} 已拒绝：${parsed.error}\n`,
+    ));
+    return 2;
+  }
+
+  const validator = VALIDATORS[validatorName];
+  if (!validator) {
+    process.stderr.write(localize(
+      `nimicoding ${validatorName} refused: unknown surface validator.\n`,
+      `nimicoding ${validatorName} 已拒绝：未知 surface validator。\n`,
+    ));
+    return 2;
+  }
+
+  const report = await validator(process.cwd(), parsed.options);
+  if (validatorName === "classify-spec-tree") {
+    await writeInventoryIfRequested(report, parsed.options.emit, process.cwd());
+  }
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  return report.ok ? 0 : 1;
+}

package/cli/commands/sweep-design.mjs

@@ -0,0 +1,295 @@
+import {
+  runAuditorPrompt,
+  runFinalize,
+  runFixTopic,
+  runIntake,
+  runLedgerValidate,
+  runPacketBuild,
+  runPacketBuildBatch,
+  runResultIngest,
+  runWavePlan,
+} from "../lib/sweep-design.mjs";
+import { localize } from "../lib/ui.mjs";
+
+function readRequiredValue(args, index, optionName, commandName) {
+  const next = args[index + 1];
+  if (!next || next.startsWith("--")) {
+    return {
+      ok: false,
+      error: `${localize(
+        `nimicoding sweep design ${commandName} refused: ${optionName} requires a value.`,
+        `nimicoding sweep design ${commandName} 已拒绝：${optionName} 需要一个值。`,
+      )}\n`,
+    };
+  }
+  return { ok: true, value: next };
+}
+
+function unknownOption(commandName, arg) {
+  return {
+    ok: false,
+    error: `${localize(
+      `nimicoding sweep design ${commandName} refused: unknown option ${arg}.`,
+      `nimicoding sweep design ${commandName} 已拒绝：未知选项 ${arg}。`,
+    )}\n`,
+  };
+}
+
+function parseOptions(args, commandName, spec) {
+  const options = Object.fromEntries(Object.entries(spec).map(([name, config]) => [name, config.default ?? null]));
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    const entry = Object.entries(spec).find(([, config]) => config.flag === arg);
+    if (!entry) {
+      return unknownOption(commandName, arg);
+    }
+    const [name] = entry;
+    if (entry[1].type === "boolean") {
+      options[name] = true;
+      continue;
+    }
+    const value = readRequiredValue(args, index, arg, commandName);
+    if (!value.ok) return value;
+    options[name] = value.value;
+    index += 1;
+  }
+  const missing = Object.entries(spec)
+    .filter(([, config]) => config.required)
+    .filter(([name]) => !options[name])
+    .map(([, config]) => config.flag);
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      error: `${localize(
+        `nimicoding sweep design ${commandName} refused: missing required options: ${missing.join(", ")}.`,
+        `nimicoding sweep design ${commandName} 已拒绝：缺少必填选项：${missing.join(", ")}。`,
+      )}\n`,
+    };
+  }
+  return { ok: true, options };
+}
+
+function parseSweepDesignOptions(args) {
+  const [phase] = args;
+  if (phase === "intake") {
+    return {
+      ok: true,
+      action: "intake",
+      parsed: parseOptions(args.slice(1), "intake", {
+        sweepId: { flag: "--sweep-id", required: true },
+        runId: { flag: "--run-id" },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "packet-build") {
+    return {
+      ok: true,
+      action: "packet-build",
+      parsed: parseOptions(args.slice(1), "packet-build", {
+        runId: { flag: "--run-id", required: true },
+        packetId: { flag: "--packet-id", required: true },
+        findingId: { flag: "--finding-id" },
+        findingIds: { flag: "--finding-ids" },
+        explicitQuestion: { flag: "--explicit-question" },
+        explicitQuestions: { flag: "--explicit-questions" },
+        priorDesignStateRefs: { flag: "--prior-design-state-refs" },
+        priorDesignStateMarker: { flag: "--prior-design-state-marker" },
+        currentClusterRefs: { flag: "--current-cluster-refs" },
+        currentWaveRefs: { flag: "--current-wave-refs" },
+        authorityOnly: { flag: "--authority-only", type: "boolean", default: false },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "packet-build-batch") {
+    return {
+      ok: true,
+      action: "packet-build-batch",
+      parsed: parseOptions(args.slice(1), "packet-build-batch", {
+        runId: { flag: "--run-id", required: true },
+        batchSize: { flag: "--batch-size", required: true },
+        findingIds: { flag: "--finding-ids" },
+        packetPrefix: { flag: "--packet-prefix" },
+        manifestId: { flag: "--manifest-id" },
+        explicitQuestion: { flag: "--explicit-question" },
+        explicitQuestions: { flag: "--explicit-questions" },
+        priorDesignStateRefs: { flag: "--prior-design-state-refs" },
+        priorDesignStateMarker: { flag: "--prior-design-state-marker" },
+        currentClusterRefs: { flag: "--current-cluster-refs" },
+        currentWaveRefs: { flag: "--current-wave-refs" },
+        authorityOnly: { flag: "--authority-only", type: "boolean", default: false },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "result-ingest") {
+    return {
+      ok: true,
+      action: "result-ingest",
+      parsed: parseOptions(args.slice(1), "result-ingest", {
+        runId: { flag: "--run-id", required: true },
+        from: { flag: "--from", required: true },
+        mode: { flag: "--mode", default: "focused" },
+        allowSyntheticTrial: { flag: "--allow-synthetic-trial", type: "boolean", default: false },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "auditor-prompt") {
+    return {
+      ok: true,
+      action: "auditor-prompt",
+      parsed: parseOptions(args.slice(1), "auditor-prompt", {
+        runId: { flag: "--run-id", required: true },
+        packetId: { flag: "--packet-id", required: true },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "finalize") {
+    return {
+      ok: true,
+      action: "finalize",
+      parsed: parseOptions(args.slice(1), "finalize", {
+        runId: { flag: "--run-id", required: true },
+        allowSyntheticCloseout: { flag: "--allow-synthetic-closeout", type: "boolean", default: false },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "ledger-validate") {
+    return {
+      ok: true,
+      action: "ledger-validate",
+      parsed: parseOptions(args.slice(1), "ledger-validate", {
+        runId: { flag: "--run-id", required: true },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "wave-plan") {
+    return {
+      ok: true,
+      action: "wave-plan",
+      parsed: parseOptions(args.slice(1), "wave-plan", {
+        runId: { flag: "--run-id", required: true },
+        topicId: { flag: "--topic-id", required: true },
+        allowSyntheticTrial: { flag: "--allow-synthetic-trial", type: "boolean", default: false },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  if (phase === "fix-topic") {
+    return {
+      ok: true,
+      action: "fix-topic",
+      parsed: parseOptions(args.slice(1), "fix-topic", {
+        runId: { flag: "--run-id", required: true },
+        slug: { flag: "--slug" },
+        title: { flag: "--title" },
+        admitFirstWave: { flag: "--admit-first-wave", type: "boolean", default: false },
+        admitWaveId: { flag: "--admit-wave-id" },
+        verifiedAt: { flag: "--verified-at" },
+        json: { default: false },
+      }),
+    };
+  }
+  return {
+    ok: false,
+    error: `${localize(
+      "nimicoding sweep design refused: expected intake, packet-build, packet-build-batch, auditor-prompt, result-ingest, ledger-validate, finalize, wave-plan, or fix-topic.",
+      "nimicoding sweep design 已拒绝：需要 intake、packet-build、packet-build-batch、auditor-prompt、result-ingest、ledger-validate、finalize、wave-plan 或 fix-topic。",
+    )}\n`,
+  };
+}
+
+function emitResult(result, json) {
+  if (result.inputError) {
+    process.stderr.write(result.error);
+    return result.exitCode ?? 2;
+  }
+  if (!result.ok) {
+    process.stderr.write(result.error ?? "nimicoding sweep design failed.\n");
+    return result.exitCode ?? 1;
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ command: "sweep.design", ...result }, null, 2)}\n`);
+  } else {
+    const lines = ["sweep design result"];
+    for (const [label, value] of [
+      ["run", result.runId],
+      ["inventory", result.inventoryRef],
+      ["ledger", result.ledgerRef],
+      ["packet", result.packetRef],
+      ["auditor prompt", result.promptRef],
+      ["auditor result", result.resultRef],
+      ["decision queue", result.decisionQueueRef],
+      ["final state report", result.finalStateReportRef],
+      ["wave plan", result.wavePlanRef],
+      ["topic", result.topicRef],
+      ["sweep fix source", result.sourceRef],
+      ["wave catalog", result.waveCatalogRef],
+    ]) {
+      if (value !== undefined && value !== null) {
+        lines.push(`${label}: ${value}`);
+      }
+    }
+    for (const [label, value] of [
+      ["findings", result.findingCount],
+      ["finding outcomes", result.findingOutcomeCount],
+      ["revision entries", result.revisionEntryCount],
+      ["total findings", result.totalFindingCount],
+      ["final findings", result.finalFindingCount],
+      ["transient findings", result.transientFindingCount],
+      ["waves", result.waveCount],
+      ["admitted wave", result.admittedWaveId],
+      ["stop class", result.stopClass],
+      ["stop reason", result.stopReason],
+    ]) {
+      if (value !== undefined && value !== null) {
+        lines.push(`${label}: ${value}`);
+      }
+    }
+    process.stdout.write(`${lines.join("\n")}\n`);
+  }
+  return result.exitCode ?? 0;
+}
+
+export async function runSweepDesign(args) {
+  const parsedAction = parseSweepDesignOptions(args);
+  if (!parsedAction.ok) {
+    process.stderr.write(parsedAction.error);
+    return 2;
+  }
+  if (!parsedAction.parsed.ok) {
+    process.stderr.write(parsedAction.parsed.error);
+    return 2;
+  }
+  const options = parsedAction.parsed.options;
+  const projectRoot = process.cwd();
+  const actions = {
+    intake: runIntake,
+    "packet-build": runPacketBuild,
+    "packet-build-batch": runPacketBuildBatch,
+    "auditor-prompt": runAuditorPrompt,
+    "result-ingest": runResultIngest,
+    "ledger-validate": runLedgerValidate,
+    finalize: runFinalize,
+    "wave-plan": runWavePlan,
+    "fix-topic": runFixTopic,
+  };
+  return emitResult(await actions[parsedAction.action](projectRoot, options), options.json);
+}

package/cli/commands/sweep.mjs

@@ -0,0 +1,22 @@
+import { runAuditSweep } from "./audit-sweep.mjs";
+import { runSweepDesign } from "./sweep-design.mjs";
+import { localize } from "../lib/ui.mjs";
+
+export async function runSweep(args) {
+  const [command] = args;
+  const rest = args.slice(1);
+
+  if (command === "audit") {
+    return runAuditSweep(rest);
+  }
+
+  if (command === "design") {
+    return runSweepDesign(rest);
+  }
+
+  process.stderr.write(localize(
+    "nimicoding sweep refused: expected `audit` or `design`.\n",
+    "nimicoding sweep 已拒绝：需要使用 `audit` 或 `design`。\n",
+  ));
+  return 2;
+}