@nimiplatform/nimi-coding 0.1.0 → 0.2.0

package/cli/lib/topic-lifecycle-artifacts.mjs

@@ -0,0 +1,173 @@
+import { readdir } from "node:fs/promises";
+
+function getTopicWaves(topic) {
+  return Array.isArray(topic.waves) ? topic.waves.map((entry) => ({ ...entry })) : [];
+}
+
+function fileReferencesWave(fileName, waveId) {
+  return fileName.includes(waveId);
+}
+
+function buildObservedLineage(entry) {
+  if (entry.closeouts > 0) return "closed_lineage";
+  if (entry.results > 0) return "result_lineage";
+  if (entry.packets > 0) return "packet_lineage";
+  if (entry.remediations > 0 || entry.exec_packs > 0 || entry.decision_reviews > 0) {
+    return "auxiliary_lineage";
+  }
+  return "declared_only";
+}
+
+function isRecognizedLifecycleArtifactName(fileName) {
+  if (!fileName.endsWith(".md")) return true;
+  if (fileName.startsWith("packet-")) {
+    return /^packet-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName)
+      || /^packet-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName);
+  }
+  if (fileName.startsWith("result-")) {
+    return /^result-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName)
+      || /^result-topic-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName)
+      || /^result-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName);
+  }
+  if (fileName.startsWith("closeout-")) {
+    return /^closeout-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName)
+      || /^closeout-topic(?:-[a-z0-9]+)*\.md$/.test(fileName)
+      || /^closeout-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName);
+  }
+  if (fileName.startsWith("decision-review-")) {
+    return /^decision-review-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName);
+  }
+  if (fileName.startsWith("prompt-")) {
+    return /^prompt-[a-z0-9-]+-(worker|audit)\.md$/.test(fileName);
+  }
+  if (fileName.startsWith("overflow-continuation-")) {
+    return /^overflow-continuation-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName);
+  }
+  return true;
+}
+
+function resolveDeclaredWaveArtifactLineage(fileNames, topicWaveIds) {
+  const declared = Array.from(topicWaveIds);
+  const resolved = [];
+  const unresolved = [];
+  const ambiguous = [];
+
+  for (const fileName of fileNames) {
+    const matches = declared.filter((waveId) => fileReferencesWave(fileName, waveId));
+    if (matches.length === 1) {
+      resolved.push({ fileName, waveId: matches[0] });
+    } else if (matches.length === 0) {
+      unresolved.push(fileName);
+    } else {
+      ambiguous.push({ fileName, waveIds: matches });
+    }
+  }
+
+  return { resolved, unresolved, ambiguous };
+}
+
+function formatLifecycleLineageFailures(lineage) {
+  return [
+    ...lineage.unresolved.map((fileName) => `${fileName}:unresolved`),
+    ...lineage.ambiguous.map((entry) => `${entry.fileName}:ambiguous:${entry.waveIds.join(",")}`),
+  ];
+}
+
+async function analyzeTopicArtifacts(topicDir, topic) {
+  const files = (await readdir(topicDir, { withFileTypes: true }))
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name);
+  const packetFiles = files.filter((name) => name.startsWith("packet-") && name.endsWith(".md"));
+  const resultFiles = files.filter((name) => name.startsWith("result-") && name.endsWith(".md"));
+  const closeoutFiles = files.filter((name) => name.startsWith("closeout-") && name.endsWith(".md"));
+  const decisionReviewFiles = files.filter((name) => name.startsWith("decision-review-") && name.endsWith(".md"));
+  const remediationFiles = files.filter((name) => name.includes("remediation") && name.endsWith(".md"));
+  const overflowFiles = files.filter((name) => name.includes("overflow-continuation") || name.includes("remediation-continuation"));
+  const execPackFiles = files.filter((name) => name.includes("exec-pack-") && name.endsWith(".md"));
+  const trueCloseFiles = files.filter((name) => name === "topic-true-close-audit.md"
+    || name.startsWith("result-topic-true-close")
+    || name === "closeout-topic-true-close.md");
+  const ambiguousLifecycleFiles = files.filter((name) => /^(packet|result|closeout|decision-review|prompt|overflow-continuation)-/.test(name)
+    && !isRecognizedLifecycleArtifactName(name));
+  const topicWaveIds = new Set(getTopicWaves(topic).map((entry) => entry.wave_id));
+  const packetWaveFiles = packetFiles.filter((name) => !name.startsWith("packet-true-close"));
+  const resultWaveFiles = resultFiles.filter((name) => !name.startsWith("result-topic-true-close") && !name.startsWith("result-true-close"));
+  const closeoutWaveFiles = closeoutFiles.filter((name) => !name.startsWith("closeout-topic") && !name.startsWith("closeout-true-close"));
+  const packetLineage = resolveDeclaredWaveArtifactLineage(packetWaveFiles, topicWaveIds);
+  const resultLineage = resolveDeclaredWaveArtifactLineage(resultWaveFiles, topicWaveIds);
+  const closeoutLineage = resolveDeclaredWaveArtifactLineage(closeoutWaveFiles, topicWaveIds);
+  const packetWaveIds = new Set(packetLineage.resolved.map((entry) => entry.waveId));
+  const resultWaveIds = resultLineage.resolved.map((entry) => entry.waveId);
+  const closeoutWaveIds = new Set(closeoutLineage.resolved.map((entry) => entry.waveId));
+  const closeoutWaveIdsArray = Array.from(closeoutWaveIds);
+  const unresolvedPacketWaveRefs = formatLifecycleLineageFailures(packetLineage);
+  const unresolvedResultWaveIds = formatLifecycleLineageFailures(resultLineage);
+  const unresolvedCloseoutWaveRefs = formatLifecycleLineageFailures(closeoutLineage);
+  const activeWaveCloseoutConflicts = getTopicWaves(topic)
+    .filter((entry) => !["closed", "retired", "superseded"].includes(entry.state)
+      && closeoutFiles.some((name) => fileReferencesWave(name, entry.wave_id) || closeoutWaveIds.has(entry.wave_id)))
+    .map((entry) => `${entry.wave_id}:${entry.state}`);
+  const topicHasOpenBlockers = getTopicWaves(topic).some((entry) => !["closed", "retired", "superseded"].includes(entry.state))
+    || (typeof topic.selected_next_target === "string"
+      && topic.selected_next_target.length > 0
+      && topic.selected_next_target !== "topic_design_baseline");
+  const prematureTrueClose = trueCloseFiles.length > 0 && topicHasOpenBlockers;
+  const observedWaveIds = Array.from(new Set([
+    ...Array.from(topicWaveIds),
+    ...Array.from(packetWaveIds),
+    ...closeoutWaveIdsArray,
+    ...resultWaveIds,
+  ])).sort();
+  const observedWaves = observedWaveIds.map((waveId) => {
+    const observed = {
+      wave_id: waveId,
+      packets: packetFiles.filter((name) => fileReferencesWave(name, waveId)).length,
+      results: resultFiles.filter((name) => fileReferencesWave(name, waveId)).length,
+      closeouts: closeoutFiles.filter((name) => fileReferencesWave(name, waveId)).length,
+      decision_reviews: decisionReviewFiles.filter((name) => fileReferencesWave(name, waveId)).length,
+      remediations: remediationFiles.filter((name) => fileReferencesWave(name, waveId)).length,
+      overflow_continuations: overflowFiles.filter((name) => fileReferencesWave(name, waveId)).length,
+      exec_packs: execPackFiles.filter((name) => fileReferencesWave(name, waveId)).length,
+      declared_in_topic_yaml: topicWaveIds.has(waveId),
+    };
+    return { ...observed, observed_lineage: buildObservedLineage(observed) };
+  });
+
+  return {
+    files,
+    counts: {
+      files: files.length,
+      packets: packetFiles.length,
+      results: resultFiles.length,
+      closeouts: closeoutFiles.length,
+      decision_reviews: decisionReviewFiles.length,
+      remediations: remediationFiles.length,
+      overflow_continuations: overflowFiles.length,
+      exec_packs: execPackFiles.length,
+      true_close_artifacts: trueCloseFiles.length,
+    },
+    waveIds: observedWaveIds,
+    observedWaves,
+    featureFlags: {
+      decision_review_lineage: decisionReviewFiles.length > 0,
+      remediation_lineage: remediationFiles.length > 0,
+      overflow_lineage: overflowFiles.length > 0,
+      true_close_lineage: trueCloseFiles.length >= 2,
+      exec_pack_lineage: execPackFiles.length > 0,
+    },
+    unresolvedPacketWaveRefs,
+    unresolvedResultWaveIds,
+    unresolvedCloseoutWaveRefs,
+    closeoutWaveIds: closeoutWaveIdsArray,
+    ambiguousLifecycleFiles,
+    activeWaveCloseoutConflicts,
+    prematureTrueClose,
+  };
+}
+
+export {
+  analyzeTopicArtifacts,
+  fileReferencesWave,
+  isRecognizedLifecycleArtifactName,
+  resolveDeclaredWaveArtifactLineage,
+};

package/cli/lib/topic-root-validation.mjs

@@ -0,0 +1,288 @@
+import path from "node:path";
+
+import { pathExists } from "./fs-helpers.mjs";
+import { analyzeTopicArtifacts } from "./topic-lifecycle-artifacts.mjs";
+import { DEFAULT_TOPIC_RUNTIME_AUTHORITY, loadTopicRuntimeAuthority, toPortableRelativePath } from "./topic-common.mjs";
+import {
+  getTopicWaves,
+  loadTopicReport,
+  topicHasEnrichedShape,
+  validateTopicId,
+} from "./topic-scaffold.mjs";
+import {
+  getPendingEntryBlockers,
+  loadPendingNote,
+  loadTopicValidationPolicy,
+} from "./topic-waves.mjs";
+
+export async function validateTopicRoot(projectRoot, input = null) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return { ok: false, error: loaded.error, checks: [], warnings: [] };
+  const { topicDir, topicId, state, topic } = loaded,
+    authority = await loadTopicRuntimeAuthority(projectRoot),
+    validationPolicy = await loadTopicValidationPolicy(projectRoot),
+    ignoredByPolicy = validationPolicy.ignoredTopicIds.get(topicId) ?? null,
+    checks = [],
+    warnings = [],
+    relativeTopicDir = toPortableRelativePath(path.relative(projectRoot, topicDir)),
+    artifactAnalysis = await analyzeTopicArtifacts(topicDir, topic),
+    pendingNoteLoaded = await loadPendingNote(topicDir),
+    topicIdMatchesFolder = topic.topic_id === topicId;
+  checks.push({
+    id: "topic_id_matches_folder",
+    ok: topicIdMatchesFolder,
+    reason: topicIdMatchesFolder
+      ? "topic.yaml topic_id matches the topic folder"
+      : `topic.yaml topic_id does not match folder name (${topic.topic_id ?? "missing"} vs ${topicId})`,
+  });
+  const stateMatchesRoot = topic.state === state;
+  checks.push({
+    id: "state_matches_root",
+    ok: stateMatchesRoot,
+    reason: stateMatchesRoot
+      ? "topic.yaml state matches the lifecycle root"
+      : `topic.yaml state does not match lifecycle root (${topic.state ?? "missing"} vs ${state})`,
+  });
+  const missingMinimalFields = authority.minimalRequiredFields.filter((field) => {
+    const value = topic[field];
+    return value == null || value === "";
+  });
+  checks.push({
+    id: "minimal_state_evidence",
+    ok: missingMinimalFields.length === 0,
+    reason:
+      missingMinimalFields.length === 0
+        ? "topic.yaml contains the required lifecycle evidence fields"
+        : `topic.yaml is missing required lifecycle evidence fields: ${missingMinimalFields.join(", ")}`,
+  });
+  const topicIdFormatValid = validateTopicId(topicId);
+  checks.push({
+    id: "topic_id_format",
+    ok: topicIdFormatValid,
+    reason: topicIdFormatValid
+      ? "topic id remains date-first and sortable"
+      : `topic id is not date-first and sortable: ${topicId}`,
+  });
+  const missingRecommendedFiles = [];
+  for (const fileName of authority.recommendedFiles)
+    (await pathExists(path.join(topicDir, fileName)))?.isFile() ||
+      missingRecommendedFiles.push(fileName);
+  missingRecommendedFiles.length > 0 &&
+    warnings.push(
+      `recommended topic companion files are missing: ${missingRecommendedFiles.join(", ")}`,
+    );
+  const missingEnrichedFields = authority.enrichedRequiredFields.filter((field) => {
+      const value = topic[field];
+      return field === "selected_next_target"
+        ? !(
+            value === null ||
+            value === "topic_design_baseline" ||
+            (typeof value == "string" && value.length > 0)
+          )
+        : value == null || value === "" || (Array.isArray(value) && value.length === 0);
+    }),
+    enumViolations = [];
+  if (
+    (topic.mode !== void 0 &&
+      !authority.topicEnums.mode.includes(topic.mode) &&
+      enumViolations.push(`mode=${topic.mode}`),
+    topic.posture !== void 0 &&
+      !authority.topicEnums.posture.includes(topic.posture) &&
+      enumViolations.push(`posture=${topic.posture}`),
+    topic.design_policy !== void 0 &&
+      !authority.topicEnums.designPolicy.includes(topic.design_policy) &&
+      enumViolations.push(`design_policy=${topic.design_policy}`),
+    topic.parallel_truth !== void 0 &&
+      !authority.topicEnums.parallelTruth.includes(topic.parallel_truth) &&
+      enumViolations.push(`parallel_truth=${topic.parallel_truth}`),
+    topic.layering !== void 0 &&
+      !authority.topicEnums.layering.includes(topic.layering) &&
+      enumViolations.push(`layering=${topic.layering}`),
+    topic.risk !== void 0 &&
+      !authority.topicEnums.risk.includes(topic.risk) &&
+      enumViolations.push(`risk=${topic.risk}`),
+    topic.applicability !== void 0 &&
+      !authority.topicEnums.applicability.includes(topic.applicability) &&
+      enumViolations.push(`applicability=${topic.applicability}`),
+    topic.execution_mode !== void 0 &&
+      !authority.topicEnums.executionMode.includes(topic.execution_mode) &&
+      enumViolations.push(`execution_mode=${topic.execution_mode}`),
+    topic.current_true_close_status !== void 0 &&
+      !authority.topicEnums.trueCloseStatus.includes(topic.current_true_close_status) &&
+      enumViolations.push(`current_true_close_status=${topic.current_true_close_status}`),
+    missingEnrichedFields.length > 0 &&
+      warnings.push(
+        `topic.yaml is using the legacy minimal shape and is missing enriched fields: ${missingEnrichedFields.join(", ")}`,
+      ),
+    enumViolations.length > 0 &&
+      warnings.push(
+        `topic.yaml contains values outside the current enriched enums: ${enumViolations.join(", ")}`,
+      ),
+    checks.push({
+      id: "packet_wave_lineage_resolves",
+      ok: artifactAnalysis.unresolvedPacketWaveRefs.length === 0,
+      reason:
+        artifactAnalysis.unresolvedPacketWaveRefs.length === 0
+          ? "packet artifacts resolve to exactly one declared wave lineage"
+          : `packet artifacts do not resolve to exactly one declared wave lineage: ${artifactAnalysis.unresolvedPacketWaveRefs.join(", ")}`,
+    }),
+    checks.push({
+      id: "result_wave_lineage_resolves",
+      ok: artifactAnalysis.unresolvedResultWaveIds.length === 0,
+      reason:
+        artifactAnalysis.unresolvedResultWaveIds.length === 0
+          ? "result artifacts resolve to exactly one declared wave lineage"
+          : `result artifacts do not resolve to exactly one declared wave lineage: ${artifactAnalysis.unresolvedResultWaveIds.join(", ")}`,
+    }),
+    checks.push({
+      id: "closeout_wave_lineage_resolves",
+      ok: artifactAnalysis.unresolvedCloseoutWaveRefs.length === 0,
+      reason:
+        artifactAnalysis.unresolvedCloseoutWaveRefs.length === 0
+          ? "closeout artifacts resolve to exactly one declared wave lineage"
+          : `closeout artifacts do not resolve to exactly one declared wave lineage: ${artifactAnalysis.unresolvedCloseoutWaveRefs.join(", ")}`,
+    }),
+    topic.state === "pending")
+  ) {
+    const pendingNote = pendingNoteLoaded.ok ? pendingNoteLoaded.note : null;
+    if (
+      (checks.push({
+        id: "pending_note_exists",
+        ok: pendingNoteLoaded.ok,
+        reason: pendingNoteLoaded.ok ? "pending note artifact exists" : pendingNoteLoaded.error,
+      }),
+      pendingNote)
+    ) {
+      const pendingNoteMissingFields = authority.pendingNoteRequiredFields.filter((field) => {
+        const value = pendingNote[field];
+        return value == null || value === "";
+      });
+      (checks.push({
+        id: "pending_note_required_fields",
+        ok: pendingNoteMissingFields.length === 0,
+        reason:
+          pendingNoteMissingFields.length === 0
+            ? "pending note contains required fields"
+            : `pending note is missing required fields: ${pendingNoteMissingFields.join(", ")}`,
+      }),
+        checks.push({
+          id: "pending_note_topic_matches",
+          ok: pendingNote.topic_id === topicId,
+          reason:
+            pendingNote.topic_id === topicId
+              ? "pending note topic_id matches the topic"
+              : `pending note topic_id does not match topic (${pendingNote.topic_id ?? "missing"} vs ${topicId})`,
+        }),
+        checks.push({
+          id: "pending_note_status_active",
+          ok:
+            pendingNote.status === "active" &&
+            authority.pendingNoteStatuses.includes(pendingNote.status),
+          reason:
+            pendingNote.status === "active"
+              ? "pending note remains active while topic is pending"
+              : `pending note status must be active while pending, found ${pendingNote.status ?? "missing"}`,
+        }),
+        checks.push({
+          id: "pending_note_reopen_or_close_defined",
+          ok:
+            typeof pendingNote.reopen_criteria == "string" ||
+            typeof pendingNote.close_trigger == "string",
+          reason:
+            typeof pendingNote.reopen_criteria == "string" ||
+            typeof pendingNote.close_trigger == "string"
+              ? "pending note declares reopen criteria or close trigger"
+              : "pending note must declare reopen criteria or close trigger",
+        }));
+    }
+    const pendingBlockers = getPendingEntryBlockers(topic);
+    checks.push({
+      id: "pending_has_no_active_implementation_wave",
+      ok: pendingBlockers.length === 0,
+      reason:
+        pendingBlockers.length === 0
+          ? "pending topic has no active implementation wave"
+          : `pending topic still has active implementation waves: ${pendingBlockers.join(", ")}`,
+    });
+  }
+  ignoredByPolicy
+    ? (warnings.push(
+        `topic is ignored by default strict validate policy: ${ignoredByPolicy.reason ?? topicId}`,
+      ),
+      checks.push({
+        id: "strict_validate_policy_ignored",
+        ok: true,
+        reason: `strict topic rails skipped by policy (${ignoredByPolicy.posture ?? "ignored"})`,
+      }))
+    : (checks.push({
+        id: "artifact_naming_unambiguous",
+        ok: artifactAnalysis.ambiguousLifecycleFiles.length === 0,
+        reason:
+          artifactAnalysis.ambiguousLifecycleFiles.length === 0
+            ? "lifecycle artifact naming remains unambiguous"
+            : `ambiguous lifecycle artifact names: ${artifactAnalysis.ambiguousLifecycleFiles.join(", ")}`,
+      }),
+      checks.push({
+        id: "no_active_wave_closeout_conflict",
+        ok: artifactAnalysis.activeWaveCloseoutConflicts.length === 0,
+        reason:
+          artifactAnalysis.activeWaveCloseoutConflicts.length === 0
+            ? "no closeout artifact claims closure for an active wave"
+            : `closeout artifacts exist for non-terminal waves: ${artifactAnalysis.activeWaveCloseoutConflicts.join(", ")}`,
+      }),
+      checks.push({
+        id: "true_close_not_premature",
+        ok: !artifactAnalysis.prematureTrueClose,
+        reason: artifactAnalysis.prematureTrueClose
+          ? "true-close artifacts exist while open blockers remain"
+          : "true-close artifacts do not coexist with known open blockers",
+      }));
+  const ok = checks.every((entry) => entry.ok),
+    schemaMode =
+      missingEnrichedFields.length === 0 && enumViolations.length === 0
+        ? "enriched"
+        : "legacy_minimal",
+    migrationPosture =
+      schemaMode === "legacy_minimal" && artifactAnalysis.counts.files > 0
+        ? "explicit_legacy_reconstruction_required"
+        : "not_required",
+    validationDisposition = ignoredByPolicy
+      ? validationPolicy.ignoredTopicValidateSemantics.status
+      : "strict",
+    canonicalValidated = ignoredByPolicy
+      ? validationPolicy.ignoredTopicValidateSemantics.canonicalSuccess
+      : ok;
+  return {
+    ok,
+    topicId,
+    topicDir,
+    topicRef: relativeTopicDir,
+    state,
+    schemaMode,
+    selectedNextTarget:
+      typeof topic.selected_next_target == "string" ? topic.selected_next_target : null,
+    currentTrueCloseStatus:
+      typeof topic.current_true_close_status == "string" ? topic.current_true_close_status : null,
+    title: typeof topic.title == "string" ? topic.title : null,
+    pendingNoteStatus:
+      pendingNoteLoaded.ok && typeof pendingNoteLoaded.note.status == "string"
+        ? pendingNoteLoaded.note.status
+        : null,
+    missingEnrichedFields,
+    artifactSummary: artifactAnalysis.counts,
+    waveIds: artifactAnalysis.waveIds,
+    observedWaves: artifactAnalysis.observedWaves,
+    featureFlags: artifactAnalysis.featureFlags,
+    unresolvedPacketWaveRefs: artifactAnalysis.unresolvedPacketWaveRefs,
+    unresolvedResultWaveIds: artifactAnalysis.unresolvedResultWaveIds,
+    unresolvedCloseoutWaveRefs: artifactAnalysis.unresolvedCloseoutWaveRefs,
+    migrationPosture,
+    validationDisposition,
+    canonicalValidated,
+    ignoredByPolicy: ignoredByPolicy !== null,
+    ignorePolicyReason: ignoredByPolicy?.reason ?? null,
+    ignorePolicyPosture: ignoredByPolicy?.posture ?? null,
+    checks,
+    warnings,
+  };
+}

package/cli/lib/topic-runner-commands.mjs

@@ -0,0 +1,174 @@
+function hasPlaceholder(value) {
+  return /<[^>]+>/.test(value);
+}
+
+function commandOptionValue(parts, flag) {
+  const index = parts.indexOf(flag);
+  return index >= 0 ? parts[index + 1] : null;
+}
+
+function commandRequiredOption(parts, flag, commandRef, actionLabel) {
+  const value = commandOptionValue(parts, flag);
+  if (!value || value.startsWith("--")) {
+    return {
+      ok: false,
+      error: `topic-runner refused: ${actionLabel} command is missing ${flag}: ${commandRef}`,
+    };
+  }
+  return { ok: true, value };
+}
+
+export function parseMechanicalCommandRef(commandRef, topicId) {
+  if (typeof commandRef !== "string" || commandRef.trim().length === 0) {
+    return {
+      ok: false,
+      error: "topic-runner refused: decision.next_command_ref is empty",
+    };
+  }
+  if (hasPlaceholder(commandRef)) {
+    return {
+      ok: false,
+      error: `topic-runner refused: decision.next_command_ref contains a placeholder: ${commandRef}`,
+    };
+  }
+
+  const parts = commandRef.trim().split(/\s+/);
+  if (parts[0] !== "nimicoding" || parts[1] !== "topic") {
+    return {
+      ok: false,
+      error: `topic-runner refused: next command is not a package-owned topic command: ${commandRef}`,
+    };
+  }
+
+  const [domain, action, commandTopicId] = parts.slice(2, 5);
+  if (domain === "wave" && action === "admit") {
+    const waveId = parts[5] ?? null;
+    if (commandTopicId !== topicId) {
+      return {
+        ok: false,
+        error: `topic-runner refused: next command topic ${commandTopicId} does not match ${topicId}`,
+      };
+    }
+    if (!waveId || waveId.startsWith("--")) {
+      return {
+        ok: false,
+        error: `topic-runner refused: wave admit command is missing wave id: ${commandRef}`,
+      };
+    }
+    return { ok: true, action: "admit_wave", waveId };
+  }
+
+  if (domain === "packet" && action === "freeze") {
+    if (commandTopicId !== topicId) {
+      return {
+        ok: false,
+        error: `topic-runner refused: next command topic ${commandTopicId} does not match ${topicId}`,
+      };
+    }
+    const draftPath = commandOptionValue(parts, "--from");
+    if (!draftPath || draftPath.startsWith("--")) {
+      return {
+        ok: false,
+        error: `topic-runner refused: packet freeze command is missing --from: ${commandRef}`,
+      };
+    }
+    return { ok: true, action: "freeze_packet", draftPath };
+  }
+
+  if (domain === "result" && action === "record") {
+    if (commandTopicId !== topicId) {
+      return {
+        ok: false,
+        error: `topic-runner refused: next command topic ${commandTopicId} does not match ${topicId}`,
+      };
+    }
+    const required = [
+      ["--kind", "result record"],
+      ["--verdict", "result record"],
+      ["--from", "result record"],
+      ["--verified-at", "result record"],
+    ].map(([flag, label]) => [flag, commandRequiredOption(parts, flag, commandRef, label)]);
+    const failed = required.find(([, check]) => !check.ok);
+    if (failed) return failed[1];
+    const values = Object.fromEntries(required.map(([flag, check]) => [flag, check.value]));
+    return {
+      ok: true,
+      action: "record_result",
+      resultKind: values["--kind"],
+      verdict: values["--verdict"],
+      fromPath: values["--from"],
+      verifiedAt: values["--verified-at"],
+    };
+  }
+
+  if (["worker", "audit"].includes(domain) && action === "dispatch") {
+    if (commandTopicId !== topicId) {
+      return {
+        ok: false,
+        error: `topic-runner refused: next command topic ${commandTopicId} does not match ${topicId}`,
+      };
+    }
+    const packetId = commandOptionValue(parts, "--packet");
+    if (!packetId || packetId.startsWith("--")) {
+      return {
+        ok: false,
+        error: `topic-runner refused: dispatch command is missing --packet: ${commandRef}`,
+      };
+    }
+    return {
+      ok: true,
+      action: domain === "audit" ? "dispatch_audit" : "dispatch_worker",
+      role: domain,
+      packetId,
+    };
+  }
+
+  if (domain === "closeout" && action === "wave") {
+    if (commandTopicId !== topicId) {
+      return {
+        ok: false,
+        error: `topic-runner refused: next command topic ${commandTopicId} does not match ${topicId}`,
+      };
+    }
+    const waveId = parts[5] ?? null;
+    if (!waveId || waveId.startsWith("--")) {
+      return {
+        ok: false,
+        error: `topic-runner refused: closeout wave command is missing wave id: ${commandRef}`,
+      };
+    }
+    const authorityClosure = commandOptionValue(parts, "--authority");
+    const semanticClosure = commandOptionValue(parts, "--semantic");
+    const consumerClosure = commandOptionValue(parts, "--consumer");
+    const driftResistanceClosure = commandOptionValue(parts, "--drift-resistance");
+    const disposition = commandOptionValue(parts, "--disposition");
+    if (
+      !authorityClosure || authorityClosure.startsWith("--") ||
+      !semanticClosure || semanticClosure.startsWith("--") ||
+      !consumerClosure || consumerClosure.startsWith("--") ||
+      !driftResistanceClosure || driftResistanceClosure.startsWith("--") ||
+      !disposition || disposition.startsWith("--")
+    ) {
+      return {
+        ok: false,
+        error: `topic-runner refused: closeout wave command is missing required closure flags: ${commandRef}`,
+      };
+    }
+
+    return {
+      ok: true,
+      action: "closeout_wave",
+      waveId,
+      authorityClosure,
+      semanticClosure,
+      consumerClosure,
+      driftResistanceClosure,
+      disposition,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `topic-runner refused: unsupported mechanical next command: ${commandRef}`,
+  };
+}