@nimiplatform/nimi-coding 0.1.0 → 0.2.1

package/cli/lib/internal/validators-spec.mjs

@@ -19,6 +19,11 @@ import {
   makeValidatorRefusal,
   VALIDATOR_NATIVE_REFUSAL_CODES,
 } from "./validators-shared.mjs";
+import {
+  validateDomainAdmission,
+  validatePlacement,
+  validateTableFamily,
+} from "./surface-taxonomy-validators.mjs";
 import {
   classifyAuditCoveredFiles,
   classifySpecTreeFiles,
@@ -27,13 +32,136 @@ import {
   isSourceRefWithinDeclaredRoots,
 } from "./validators-spec-helpers.mjs";
 
+async function loadV2RequiredFiles(projectRoot) {
+  const text = await readTextIfFile(path.join(projectRoot, ".nimi", "methodology", "spec-reconstruction.yaml"));
+  const parsed = parseYamlText(text);
+  return Array.isArray(parsed?.reconstruction?.target_tree_shape?.minimal_required_outputs)
+    ? parsed.reconstruction.target_tree_shape.minimal_required_outputs.map(String)
+    : [];
+}
+
+function isV2SpecGenerationInputs(specGenerationInputs) {
+  return specGenerationInputs.ok && specGenerationInputs.mode === "class_filtered";
+}
+
+async function validateSpecTreeV2(rootPath, projectRoot, specGenerationInputs) {
+  const errors = [];
+  const warnings = [];
+  const expectedRoot = path.resolve(projectRoot, specGenerationInputs.canonicalTargetRoot ?? ".nimi/spec");
+  const targetRoot = path.resolve(rootPath);
+
+  if (targetRoot !== expectedRoot) {
+    errors.push(`spec tree root mismatch: expected ${expectedRoot} but received ${targetRoot}`);
+  }
+
+  const files = await collectTreeFiles(targetRoot);
+  if (files.length === 0) {
+    return {
+      ok: false,
+      errors: errors.length > 0 ? errors : [`missing spec tree root: ${targetRoot}`],
+      warnings,
+      refusal: makeValidatorRefusal(
+        VALIDATOR_NATIVE_REFUSAL_CODES.SPEC_TREE_MISSING,
+        "spec tree root is missing or empty",
+      ),
+    };
+  }
+
+  const requiredFiles = await loadV2RequiredFiles(projectRoot);
+  const canonicalRoot = specGenerationInputs.canonicalTargetRoot ?? ".nimi/spec";
+  const missingRequired = requiredFiles
+    .map((entry) => path.posix.relative(canonicalRoot, entry))
+    .filter((entry) => !files.includes(entry));
+  if (missingRequired.length > 0) {
+    errors.push(`missing required canonical files: ${missingRequired.join(", ")}`);
+  }
+
+  const rootRef = path.relative(projectRoot, targetRoot).split(path.sep).join(path.posix.sep) || ".";
+  const placement = await validatePlacement(projectRoot, { rootRef });
+  const domainAdmission = await validateDomainAdmission(projectRoot, { rootRef });
+  const tableFamily = await validateTableFamily(projectRoot, { rootRef });
+  errors.push(...(placement.errors ?? []), ...(domainAdmission.errors ?? []), ...(tableFamily.errors ?? []));
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    refusal: errors.length === 0
+      ? null
+      : makeValidatorRefusal(
+        VALIDATOR_NATIVE_REFUSAL_CODES.SPEC_TREE_INVALID,
+        `spec tree is invalid: ${path.basename(targetRoot)}`,
+      ),
+    summary: {
+      profile: "surface_taxonomy_v1",
+      canonicalRoot,
+      totalFiles: files.length,
+      requiredFiles: requiredFiles.length,
+      missingRequired,
+      classifiedFiles: placement.summary?.total ?? files.length,
+      unexpectedFiles: [],
+      conflictingFiles: [],
+    },
+  };
+}
+
+function toPortableProjectPath(projectRoot, absolutePath) {
+  return path.relative(projectRoot, absolutePath).split(path.sep).join(path.posix.sep);
+}
+
+function pathStartsWithRoot(candidate, root) {
+  return candidate === root || candidate.startsWith(`${root}/`);
+}
+
+function generatedOutputNormativeRootOverlaps(specTreeModel) {
+  const normativeRoots = specTreeModel.domains.map((domain) => domain.normativeRoot).filter(Boolean);
+  const overlaps = [];
+  for (const pipeline of specTreeModel.generatedPipelines) {
+    for (const outputRoot of pipeline.outputRoots) {
+      for (const normativeRoot of normativeRoots) {
+        if (pathStartsWithRoot(outputRoot, normativeRoot) || pathStartsWithRoot(normativeRoot, outputRoot)) {
+          overlaps.push({
+            pipelineId: pipeline.id,
+            outputRoot,
+            normativeRoot,
+          });
+        }
+      }
+    }
+  }
+  return overlaps;
+}
+
+function normalizeAuditFileClass(entry) {
+  const explicitSurfaceClass = typeof entry.surface_class === "string" ? entry.surface_class : null;
+  if (explicitSurfaceClass) {
+    return explicitSurfaceClass;
+  }
+
+  switch (String(entry.file_class ?? "")) {
+    case "kernel_markdown":
+      return "product_authority";
+    case "kernel_tables":
+      return "product_authority_table";
+    case "domain_guides":
+    case "kernel_generated":
+      return "thin_guidance";
+    default:
+      return String(entry.file_class ?? "");
+  }
+}
+
 export async function validateSpecTree(rootPath, options = {}) {
   const projectRoot = options.projectRoot ?? process.cwd();
   const specTreeModel = await loadSpecTreeModelContract(projectRoot);
+  const specGenerationInputs = await loadSpecGenerationInputsConfig(projectRoot);
   const errors = [];
   const warnings = [];
 
   if (!specTreeModel.ok) {
+    if (isV2SpecGenerationInputs(specGenerationInputs)) {
+      return validateSpecTreeV2(rootPath, projectRoot, specGenerationInputs);
+    }
     return {
       ok: false,
       errors: [`invalid spec tree model contract: ${specTreeModel.path}`],
@@ -74,6 +202,13 @@ export async function validateSpecTree(rootPath, options = {}) {
     errors.push(`missing required canonical files: ${missingRequired.join(", ")}`);
   }
 
+  const generatedOutputOverlaps = generatedOutputNormativeRootOverlaps(specTreeModel);
+  if (generatedOutputOverlaps.length > 0) {
+    errors.push(
+      `generated output roots overlap normative roots: ${generatedOutputOverlaps.map((entry) => `${entry.pipelineId}:${entry.outputRoot}->${entry.normativeRoot}`).join(", ")}`,
+    );
+  }
+
   for (const domain of specTreeModel.domains) {
     const domainRoot = path.posix.relative(specTreeModel.canonicalRoot, domain.root);
     const normativeRoot = path.posix.relative(specTreeModel.canonicalRoot, domain.normativeRoot);
@@ -132,10 +267,11 @@ export async function validateSpecAudit(auditPath, options = {}) {
   const specGenerationInputs = await loadSpecGenerationInputsConfig(projectRoot);
   const blueprintReference = await loadBlueprintReference(projectRoot);
   const auditContract = await loadSpecGenerationAuditContract(projectRoot);
+  const usesV2SurfaceModel = isV2SpecGenerationInputs(specGenerationInputs);
   const errors = [];
   const warnings = [];
 
-  if (!specTreeModel.ok) {
+  if (!specTreeModel.ok && !usesV2SurfaceModel) {
     return {
       ok: false,
       errors: [`invalid spec tree model contract: ${specTreeModel.path}`],
@@ -199,8 +335,8 @@ export async function validateSpecAudit(auditPath, options = {}) {
     };
   }
 
-  if (parsed.version !== 1) {
-    errors.push("spec generation audit version must be 1");
+  if (![1, 2].includes(parsed.version)) {
+    errors.push("spec generation audit version must be 1 or 2");
   }
 
   if (String(parsed.contract_ref ?? "") !== SPEC_GENERATION_AUDIT_CONTRACT_REF) {
@@ -224,20 +360,27 @@ export async function validateSpecAudit(auditPath, options = {}) {
         : null,
   };
 
-  if (String(audit.generation_mode ?? "") !== "mixed") {
+  if (usesV2SurfaceModel) {
+    if (!["mixed", "class_filtered"].includes(String(audit.generation_mode ?? ""))) {
+      errors.push("spec generation audit generation_mode must be `mixed` or `class_filtered`");
+    }
+  } else if (String(audit.generation_mode ?? "") !== "mixed") {
     errors.push("spec generation audit generation_mode must be `mixed`");
   }
-  if (String(audit.canonical_target_root ?? "") !== specTreeModel.canonicalRoot) {
-    errors.push(`spec generation audit canonical_target_root must be ${specTreeModel.canonicalRoot}`);
+
+  const canonicalRoot = specTreeModel.ok ? specTreeModel.canonicalRoot : specGenerationInputs.canonicalTargetRoot ?? ".nimi/spec";
+  const declaredProfile = specTreeModel.ok ? specTreeModel.profile : "surface_taxonomy_v1";
+  if (String(audit.canonical_target_root ?? "") !== canonicalRoot) {
+    errors.push(`spec generation audit canonical_target_root must be ${canonicalRoot}`);
   }
-  if (String(audit.declared_profile ?? "") !== specTreeModel.profile) {
-    errors.push(`spec generation audit declared_profile must be ${specTreeModel.profile}`);
+  if (String(audit.declared_profile ?? "") !== declaredProfile) {
+    errors.push(`spec generation audit declared_profile must be ${declaredProfile}`);
   }
   if (!isDeclaredInputsCompatibleWithConfig(declaredInputs, specGenerationInputs, blueprintReference)) {
     errors.push("spec generation audit input_roots must stay within the declared generation inputs and optional benchmark root");
   }
 
-  const canonicalRootPath = path.resolve(projectRoot, specTreeModel.canonicalRoot);
+  const canonicalRootPath = path.resolve(projectRoot, canonicalRoot);
   const treeFiles = await collectTreeFiles(canonicalRootPath);
   if (treeFiles.length === 0) {
     return {
@@ -251,7 +394,14 @@ export async function validateSpecAudit(auditPath, options = {}) {
     };
   }
 
-  const { auditedFiles, classifications } = classifyAuditCoveredFiles(treeFiles, specTreeModel);
+  const { auditedFiles, classifications } = specTreeModel.ok
+    ? classifyAuditCoveredFiles(treeFiles, specTreeModel)
+    : {
+      auditedFiles: treeFiles
+        .filter((entry) => !entry.startsWith("_meta/"))
+        .map((entry) => ({ path: entry, category: "surface_taxonomy_v1" })),
+      classifications: { unexpected: [], conflicts: [] },
+    };
   if (classifications.unexpected.length > 0) {
     errors.push(`spec tree contains unexpected files outside declared spec classes: ${classifications.unexpected.join(", ")}`);
   }
@@ -263,27 +413,82 @@ export async function validateSpecAudit(auditPath, options = {}) {
   if (!Array.isArray(audit.files)) {
     errors.push("spec generation audit files must be an array");
   }
+  const fileEntryRefs = audit.file_entry_refs === undefined
+    ? []
+    : Array.isArray(audit.file_entry_refs)
+      ? audit.file_entry_refs.map(String)
+      : null;
+  if (fileEntryRefs === null) {
+    errors.push("spec generation audit file_entry_refs must be an array when present");
+  }
+
+  const referencedFileEntries = [];
+  for (const entryRef of fileEntryRefs ?? []) {
+    if (entryRef.length === 0 || path.isAbsolute(entryRef)) {
+      errors.push(`spec generation audit file_entry_refs must be non-empty repository-relative paths: ${entryRef}`);
+      continue;
+    }
+    const absoluteEntryRef = path.resolve(projectRoot, entryRef);
+    const relativeEntryRef = path.relative(projectRoot, absoluteEntryRef).split(path.sep).join(path.posix.sep);
+    const expectedPrefix = usesV2SurfaceModel
+      ? ".nimi/local/state/spec-generation/spec-generation-audit/"
+      : `${specTreeModel.canonicalRoot}/_meta/spec-generation-audit/`;
+    if (relativeEntryRef !== entryRef || !relativeEntryRef.startsWith(expectedPrefix)) {
+      errors.push(`spec generation audit file_entry_ref must stay under ${expectedPrefix}: ${entryRef}`);
+      continue;
+    }
+    const entryText = await readTextIfFile(absoluteEntryRef);
+    if (entryText === null) {
+      errors.push(`spec generation audit file_entry_ref is missing: ${entryRef}`);
+      continue;
+    }
+    const entryParsed = parseYamlText(entryText);
+    const entryPayload = entryParsed?.spec_generation_audit_file_entries;
+    if (!isPlainObject(entryParsed) || !isPlainObject(entryPayload)) {
+      errors.push(`spec generation audit file_entry_ref is not a valid entry shard: ${entryRef}`);
+      continue;
+    }
+    const expectedShardVersion = usesV2SurfaceModel ? 2 : 1;
+    if (entryParsed.version !== expectedShardVersion) {
+      errors.push(`spec generation audit file_entry_ref version must be ${expectedShardVersion}: ${entryRef}`);
+    }
+    if (String(entryParsed.contract_ref ?? "") !== SPEC_GENERATION_AUDIT_CONTRACT_REF) {
+      errors.push(`spec generation audit file_entry_ref contract_ref must be ${SPEC_GENERATION_AUDIT_CONTRACT_REF}: ${entryRef}`);
+    }
+    if (String(entryPayload.parent_ref ?? "") !== toPortableProjectPath(projectRoot, absoluteAuditPath)) {
+      errors.push(`spec generation audit file_entry_ref parent_ref must point to ${toPortableProjectPath(projectRoot, absoluteAuditPath)}: ${entryRef}`);
+    }
+    if (!Array.isArray(entryPayload.files)) {
+      errors.push(`spec generation audit file_entry_ref files must be an array: ${entryRef}`);
+      continue;
+    }
+    referencedFileEntries.push(...entryPayload.files);
+  }
+  const allFileEntries = [...fileEntries, ...referencedFileEntries];
 
   const auditEntryByRelativePath = new Map();
-  for (const entry of fileEntries) {
+  for (const entry of allFileEntries) {
     if (!isPlainObject(entry)) {
       errors.push("spec generation audit file entries must be mappings");
       continue;
     }
 
-    const missingEntryFields = SPEC_GENERATION_AUDIT_FILE_REQUIRED_FIELDS.filter((field) => !(field in entry));
+    const requiredEntryFields = auditContract.requiredFileEntryFields?.length > 0
+      ? auditContract.requiredFileEntryFields
+      : SPEC_GENERATION_AUDIT_FILE_REQUIRED_FIELDS;
+    const missingEntryFields = requiredEntryFields.filter((field) => !(field in entry));
     if (missingEntryFields.length > 0) {
       errors.push(`spec generation audit file entry is missing required fields: ${missingEntryFields.join(", ")}`);
       continue;
     }
 
     const canonicalPath = String(entry.canonical_path ?? "");
-    if (!canonicalPath.startsWith(`${specTreeModel.canonicalRoot}/`) && canonicalPath !== `${specTreeModel.canonicalRoot}/INDEX.md`) {
-      errors.push(`spec generation audit canonical_path must stay under ${specTreeModel.canonicalRoot}: ${canonicalPath}`);
+    if (!canonicalPath.startsWith(`${canonicalRoot}/`) && canonicalPath !== `${canonicalRoot}/INDEX.md`) {
+      errors.push(`spec generation audit canonical_path must stay under ${canonicalRoot}: ${canonicalPath}`);
       continue;
     }
 
-    const relativePath = path.posix.relative(specTreeModel.canonicalRoot, canonicalPath);
+    const relativePath = path.posix.relative(canonicalRoot, canonicalPath);
     if (relativePath.startsWith("_meta/")) {
       errors.push(`spec generation audit must not record _meta files as generated canonical files: ${canonicalPath}`);
       continue;
@@ -331,8 +536,11 @@ export async function validateSpecAudit(auditPath, options = {}) {
   }
 
   const missingAuditEntries = [];
-  const requiredFiles = (specTreeModel.requiredFilesByProfile[specTreeModel.profile] ?? [])
-    .map((entry) => path.posix.relative(specTreeModel.canonicalRoot, entry))
+  const requiredFileRefs = specTreeModel.ok
+    ? (specTreeModel.requiredFilesByProfile[specTreeModel.profile] ?? [])
+    : await loadV2RequiredFiles(projectRoot);
+  const requiredFiles = requiredFileRefs
+    .map((entry) => path.posix.relative(canonicalRoot, entry))
     .filter((entry) => !entry.startsWith("_meta/"));
 
   for (const classifiedFile of auditedFiles) {
@@ -342,7 +550,8 @@ export async function validateSpecAudit(auditPath, options = {}) {
       continue;
     }
 
-    if (auditEntry.file_class !== classifiedFile.classId && !(classifiedFile.path === "INDEX.md" && auditEntry.file_class === "index")) {
+    const auditFileClass = normalizeAuditFileClass(auditEntry);
+    if (classifiedFile.classId && auditFileClass !== classifiedFile.classId && !(classifiedFile.path === "INDEX.md" && auditFileClass === "index")) {
       errors.push(`spec generation audit file_class does not match canonical tree classification for ${classifiedFile.path}: expected ${classifiedFile.classId}`);
     }
   }
@@ -395,8 +604,8 @@ export async function validateSpecAudit(auditPath, options = {}) {
         `spec generation audit is invalid: ${path.basename(absoluteAuditPath)}`,
       ),
     summary: {
-      canonicalRoot: specTreeModel.canonicalRoot,
-      declaredProfile: specTreeModel.profile,
+      canonicalRoot,
+      declaredProfile,
       auditedFiles: auditEntryByRelativePath.size,
       requiredAuditedFiles: requiredFiles.length,
       missingAuditEntries,

package/cli/lib/sweep-design-runtime/common.mjs

@@ -0,0 +1,246 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import YAML from "yaml";
+
+import { pathExists } from "../fs-helpers.mjs";
+import { isPlainObject } from "../value-helpers.mjs";
+
+export const DESIGN_ROOT = ".nimi/local/sweep-design";
+export const DESIGN_STATES = new Set([
+  "raw",
+  "confirmed",
+  "duplicate",
+  "superseded",
+  "false_positive",
+  "needs_more_audit",
+  "needs_user_decision",
+  "needs_authority_alignment",
+  "needs_design",
+  "ready_for_implementation_wave",
+  "blocked",
+]);
+export const TERMINAL_STATES = new Set(["duplicate", "superseded", "false_positive"]);
+export const TRANSIENT_STATES = new Set(["raw", "confirmed", "needs_design"]);
+export const FINAL_OUTCOME_STATES = new Set([
+  "duplicate",
+  "superseded",
+  "false_positive",
+  "needs_more_audit",
+  "needs_user_decision",
+  "needs_authority_alignment",
+  "ready_for_implementation_wave",
+  "blocked",
+]);
+export const AUDITOR_FAMILIES = new Set([
+  "anthropic_claude",
+  "openai_gpt",
+  "openai_codex",
+  "google_gemini",
+  "xai_grok",
+  "meta_llama",
+  "mistral",
+  "other",
+]);
+export const AUDITOR_MODES = new Set(["focused", "all", "degraded"]);
+export const AUDITOR_RESULT_ORIGINS = new Set(["llm_session", "external_llm_session", "synthetic_trial"]);
+export const LLM_AUDITOR_RESULT_ORIGINS = new Set(["llm_session", "external_llm_session"]);
+export const PRIOR_DESIGN_STATE_MARKERS = new Set([
+  "empty",
+  "present",
+  "partial",
+  "superseded_by_later_audit",
+  "evidence_gap",
+]);
+export const REVISION_TYPES = new Set([
+  "finding_state_revision",
+  "duplicate_judgement",
+  "superseded_judgement",
+  "cluster_create",
+  "cluster_merge",
+  "cluster_split",
+  "cluster_retire",
+  "cluster_reopen",
+  "finding_move",
+  "wave_create",
+  "wave_merge",
+  "wave_split",
+  "wave_retract",
+  "wave_demote",
+  "wave_block",
+  "wave_implementation_ready",
+  "wave_dependency_rewrite",
+  "wave_validation_or_closeout_strengthening",
+  "decision_packet_create",
+  "extra_audit_request_create",
+  "extra_audit_request_close",
+  "human_decision_request_create",
+  "human_decision_request_resolve",
+  "final_state_projection_update",
+  "user_decision_queue_rewrite",
+]);
+
+export function toPosix(filePath) {
+  return filePath.split(path.sep).join(path.posix.sep);
+}
+
+export function relPath(projectRoot, absolutePath) {
+  return toPosix(path.relative(projectRoot, absolutePath));
+}
+
+export function safeDesignId(value) {
+  if (typeof value !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{2,140}$/.test(value)) {
+    return null;
+  }
+  return value;
+}
+
+export function deriveRunId(sweepId) {
+  return `sweep-design-${String(sweepId).replace(/[^a-zA-Z0-9._-]+/g, "-")}`;
+}
+
+export function designRef(runId, ...parts) {
+  return path.posix.join(DESIGN_ROOT, runId, ...parts);
+}
+
+export function artifactPath(projectRoot, ref) {
+  return path.join(projectRoot, ...ref.split("/"));
+}
+
+export function inputError(error) {
+  return { ok: false, inputError: true, exitCode: 2, error };
+}
+
+export async function loadYamlPath(filePath) {
+  try {
+    const text = await readFile(filePath, "utf8");
+    return YAML.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function sha256Text(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+export function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function sha256Object(value) {
+  return sha256Text(stableStringify(value));
+}
+
+export async function loadYamlRef(projectRoot, ref) {
+  return loadYamlPath(artifactPath(projectRoot, ref));
+}
+
+export async function writeYamlRef(projectRoot, ref, value) {
+  const destination = artifactPath(projectRoot, ref);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await writeFile(destination, YAML.stringify(value, { aliasDuplicateObjects: false }), "utf8");
+  return ref;
+}
+
+export async function assertDesignArtifact(projectRoot, ref, kind, label) {
+  const value = await loadYamlRef(projectRoot, ref);
+  if (!isPlainObject(value) || value.kind !== kind) {
+    return inputError(`nimicoding sweep design refused: ${label} is missing or malformed.\n`);
+  }
+  return { ok: true, value, ref };
+}
+
+export function auditFindingsRef(sweepId) {
+  return `.nimi/local/audit/evidence/${sweepId}/findings.yaml`;
+}
+
+export async function loadAuditFindings(projectRoot, sweepId) {
+  const ref = auditFindingsRef(sweepId);
+  const sourcePath = artifactPath(projectRoot, ref);
+  const info = await pathExists(sourcePath);
+  if (!info || !info.isFile()) {
+    return inputError(`nimicoding sweep design refused: audit findings not found for ${sweepId}.\n`);
+  }
+  const sourceText = await readFile(sourcePath, "utf8");
+  const store = YAML.parse(sourceText);
+  if (!isPlainObject(store) || store.kind !== "audit-findings" || store.sweep_id !== sweepId || !Array.isArray(store.findings)) {
+    return inputError(`nimicoding sweep design refused: audit findings are malformed for ${sweepId}.\n`);
+  }
+  return { ok: true, ref, store, sourceSha256: sha256Text(sourceText) };
+}
+
+export function findingOwnerDomain(finding) {
+  if (typeof finding.owner_domain === "string" && finding.owner_domain.length > 0) {
+    return finding.owner_domain;
+  }
+  const file = finding.location?.file;
+  if (typeof file === "string" && file.includes("/")) {
+    return file.split("/")[0];
+  }
+  return "root";
+}
+
+export function findingAuthorityRef(finding) {
+  return finding.root_cause?.authority_ref ?? finding.authority_ref ?? null;
+}
+
+export function findingRepairTarget(finding) {
+  return finding.root_cause?.repair_target ?? finding.location?.file ?? null;
+}
+
+export function findingCodeRefs(finding) {
+  return [
+    finding.location?.file,
+    ...(Array.isArray(finding.implementation_refs) ? finding.implementation_refs : []),
+  ].filter((value, index, array) => typeof value === "string" && value.length > 0 && array.indexOf(value) === index);
+}
+
+export function normalizeFindingForDesign(finding, sourceFindingsRef) {
+  return {
+    finding_id: finding.id,
+    source_audit_sweep_id: finding.sweep_id,
+    source_chunk_id: finding.chunk_id ?? null,
+    source_finding_ref: `${sourceFindingsRef}#${finding.id}`,
+    fingerprint: finding.fingerprint ?? null,
+    severity: finding.severity ?? null,
+    category: finding.category ?? null,
+    actionability: finding.actionability ?? null,
+    confidence: finding.confidence ?? null,
+    title: finding.title ?? null,
+    owner_domain: findingOwnerDomain(finding),
+    authority_ref: findingAuthorityRef(finding),
+    evidence_refs: Array.isArray(finding.implementation_refs) ? finding.implementation_refs : [],
+    repair_target: findingRepairTarget(finding),
+    location: finding.location ?? null,
+    root_cause_key: finding.root_cause?.key ?? null,
+    contract_seam: finding.root_cause?.contract_seam ?? null,
+    impact: finding.impact ?? null,
+  };
+}
+
+export function requireRunId(options) {
+  const runId = safeDesignId(options.runId);
+  if (!runId) {
+    return inputError("nimicoding sweep design refused: --run-id is required.\n");
+  }
+  return { ok: true, runId };
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function slug(value) {
+  return String(value ?? "item")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "item";
+}