@nimiplatform/nimi-coding 0.1.0 → 0.2.0

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

@@ -0,0 +1,138 @@
+import { spawn } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { loadTopicReport } from "./topic.mjs";
+
+function utcNowNoMillis() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function toPortablePath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function projectRef(projectRoot, absolutePath) {
+  return toPortablePath(path.relative(projectRoot, absolutePath));
+}
+
+function safeSegment(value) {
+  return String(value).replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+
+function hasPlaceholder(value) {
+  return /<[^>]+>/.test(value);
+}
+
+function isFilteredPnpmCommand(command) {
+  return /(?:^|\s)pnpm\s+--filter\s+\S+\s+\S+/u.test(command);
+}
+
+export function classifyValidationCommandResult(command, exitCode, stdout = "", stderr = "") {
+  const combinedOutput = `${stdout}\n${stderr}`;
+  if (
+    exitCode === 0
+    && isFilteredPnpmCommand(command)
+    && /No projects matched the filters/u.test(combinedOutput)
+  ) {
+    return {
+      status: "validation_drift",
+      passed: false,
+      summary: "Filtered package command matched no projects; replace with a concrete validation command or admit an explicit no-package evidence rule.",
+    };
+  }
+  if (exitCode === 0) {
+    return { status: "pass", passed: true, summary: "validation command passed" };
+  }
+  const failureLine = combinedOutput
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .find((line) => line.length > 0) ?? "validation command failed";
+  return {
+    status: "fail",
+    passed: false,
+    summary: failureLine.slice(0, 300),
+  };
+}
+
+function runShellCommand(command, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
+    child.on("error", (error) => {
+      resolve({
+        exitCode: 1,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: `${Buffer.concat(stderr).toString("utf8")}${error.message}\n`,
+      });
+    });
+    child.on("close", (code) => {
+      resolve({
+        exitCode: typeof code === "number" ? code : 1,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+      });
+    });
+  });
+}
+
+export async function runValidationCommandEvidence(projectRoot, options) {
+  const loaded = await loadTopicReport(projectRoot, options.topicInput);
+  if (!loaded.ok) {
+    return loaded;
+  }
+  const command = String(options.command ?? "").trim();
+  if (!command || hasPlaceholder(command)) {
+    return {
+      ok: false,
+      error: "topic-runner validation refused: command must be concrete.",
+    };
+  }
+  const cwd = path.resolve(projectRoot, options.cwd ?? ".");
+  const startedAt = options.startedAt ?? utcNowNoMillis();
+  const runResult = await runShellCommand(command, cwd);
+  const completedAt = options.completedAt ?? utcNowNoMillis();
+  const classification = classifyValidationCommandResult(
+    command,
+    runResult.exitCode,
+    runResult.stdout,
+    runResult.stderr,
+  );
+  const validationId = safeSegment(options.validationId ?? command).slice(0, 96) || "validation";
+  const evidencePath = path.join(loaded.topicDir, `evidence-validation-${validationId}.json`);
+  const evidence = {
+    contract: "nimicoding.topic-runner.validation-evidence.v1",
+    topic_id: loaded.topicId,
+    run_id: options.runId ?? null,
+    command,
+    cwd: projectRef(projectRoot, cwd),
+    started_at: startedAt,
+    completed_at: completedAt,
+    exit_code: runResult.exitCode,
+    status: classification.status,
+    stdout: runResult.stdout,
+    stderr: runResult.stderr,
+    remediation: classification.status === "validation_drift"
+      ? "replace with concrete validation command or admit an explicit no-package evidence rule"
+      : null,
+  };
+  await writeFile(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`, "utf8");
+  return {
+    ok: classification.passed,
+    topicId: loaded.topicId,
+    topicRef: projectRef(projectRoot, loaded.topicDir),
+    command,
+    exitCode: runResult.exitCode,
+    status: classification.status,
+    passed: classification.passed,
+    evidenceRef: projectRef(projectRoot, evidencePath),
+    summary: classification.summary,
+  };
+}

package/cli/lib/topic-runner.mjs

@@ -2,6 +2,14 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 import { runNativeCodexSdkPrompt } from "./codex-sdk-runner.mjs";
+import { parseMechanicalCommandRef } from "./topic-runner-commands.mjs";
+export { parseMechanicalCommandRef } from "./topic-runner-commands.mjs";
+import { deferLocalWaveBlocker } from "./topic-runner-deferral.mjs";
+import { maybeResolveStaleHumanGate } from "./topic-runner-stale-gates.mjs";
+export {
+  classifyValidationCommandResult,
+  runValidationCommandEvidence,
+} from "./topic-runner-validation.mjs";
 import {
   admitWaveInTopic,
   buildTopicRunLedger,
@@ -12,6 +20,7 @@ import {
   initTopicRunLedger,
   loadTopicReport,
   readTopicRunLedger,
+  recordTopicResult,
   recordTopicRunEvent,
 } from "./topic.mjs";
 
@@ -65,8 +74,12 @@ function isTerminalWave(wave) {
   return ["closed", "retired", "superseded"].includes(wave?.state);
 }
 
+function getTopicWaves(topic) {
+  return Array.isArray(topic?.waves) ? topic.waves : [];
+}
+
 function findDeterministicNextWave(topic) {
-  const waves = Array.isArray(topic?.waves) ? topic.waves : [];
+  const waves = getTopicWaves(topic);
   const terminalIds = new Set(waves.filter(isTerminalWave).map((wave) => wave.wave_id));
   const ready = waves.filter((wave) => {
     if (isTerminalWave(wave)) return false;
@@ -74,7 +87,7 @@ function findDeterministicNextWave(topic) {
     const deps = Array.isArray(wave.deps) ? wave.deps : [];
     return deps.every((dep) => terminalIds.has(dep));
   });
-  return ready.length === 1 ? ready[0] : null;
+  return ready.length > 0 ? ready[0] : null;
 }
 
 function normalizePhaseTransitionDecision(decisionReport, topic) {
@@ -115,7 +128,7 @@ function normalizePhaseTransitionDecision(decisionReport, topic) {
         reason_code: "deterministic_next_wave_ready",
         requires_human_confirmation: false,
         recommended_decision: "admit_wave",
-        recommendation_rationale: "Exactly one dependency-ready non-terminal wave exists, so selecting the next phase is mechanical.",
+        recommendation_rationale: "The first dependency-ready non-terminal wave in topic.yaml waves[] order is selected mechanically.",
         expected_artifacts: [],
         next_command_ref: `nimicoding topic wave admit ${topic.topic_id} ${nextWave.wave_id}`,
         blocking_checks: [],
@@ -186,153 +199,6 @@ async function rewriteMovedRunEventRef(projectRoot, eventRef, fromTopicRef, toTo
   await writeFile(eventPath, eventText.split(fromRef).join(toRef), "utf8");
 }
 
-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+/);
-  const expectedPrefix = ["nimicoding", "topic"];
-  if (parts[0] !== expectedPrefix[0] || parts[1] !== expectedPrefix[1]) {
-    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 fromFlagIndex = parts.indexOf("--from");
-    const draftPath = fromFlagIndex >= 0 ? parts[fromFlagIndex + 1] : null;
-    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 (["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 packetFlagIndex = parts.indexOf("--packet");
-    const packetId = packetFlagIndex >= 0 ? parts[packetFlagIndex + 1] : null;
-    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 optionValue = (flag) => {
-      const index = parts.indexOf(flag);
-      return index >= 0 ? parts[index + 1] : null;
-    };
-    const authorityClosure = optionValue("--authority");
-    const semanticClosure = optionValue("--semantic");
-    const consumerClosure = optionValue("--consumer");
-    const driftResistanceClosure = optionValue("--drift-resistance");
-    const disposition = optionValue("--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}`,
-  };
-}
-
 async function executeMechanicalCommand(projectRoot, options, parsedCommand) {
   if (parsedCommand.action === "admit_wave") {
     const report = await admitWaveInTopic(projectRoot, options.topicInput, parsedCommand.waveId);
@@ -385,6 +251,29 @@ async function executeMechanicalCommand(projectRoot, options, parsedCommand) {
     };
   }
 
+  if (parsedCommand.action === "record_result") {
+    const report = await recordTopicResult(
+      projectRoot,
+      options.topicInput,
+      parsedCommand.resultKind,
+      parsedCommand.verdict,
+      parsedCommand.fromPath,
+      parsedCommand.verifiedAt,
+    );
+    return {
+      ok: report.ok,
+      action: parsedCommand.action,
+      report,
+      eventKind: "result_recorded",
+      eventSourceRef: report.ok ? report.resultRef : null,
+      summary: report.ok ? `${parsedCommand.resultKind}_result_recorded` : "runner_result_record_failed",
+      artifactRefs: report.ok ? { result_ref: report.resultRef } : {},
+      waveId: report.ok ? report.waveId : null,
+      recordedAt: parsedCommand.verifiedAt,
+      error: report.ok ? null : report.error,
+    };
+  }
+
   return {
     ok: false,
     action: parsedCommand.action,
@@ -466,7 +355,7 @@ export async function runTopicRunnerStep(projectRoot, options, deps = {}) {
   }
 
   const recordedAt = options.verifiedAt ?? utcNowNoMillis();
-  const ledger = await ensureLedger(projectRoot, options.topicInput, options.runId, recordedAt);
+  let ledger = await ensureLedger(projectRoot, options.topicInput, options.runId, recordedAt);
   if (!ledger.ok) {
     return ledger;
   }
@@ -482,6 +371,19 @@ export async function runTopicRunnerStep(projectRoot, options, deps = {}) {
   }
   const decisionReport = normalizePhaseTransitionDecision(rawDecisionReport, loaded.topic);
 
+  const staleGateSync = await maybeResolveStaleHumanGate(
+    projectRoot,
+    options,
+    loaded,
+    ledger,
+    decisionReport.decision,
+    recordedAt,
+  );
+  if (!staleGateSync.ok) {
+    return staleGateSync;
+  }
+  ledger = staleGateSync.ledger;
+
   const decisionRef = await writeDecisionArtifact(
     projectRoot,
     loaded,
@@ -507,6 +409,56 @@ export async function runTopicRunnerStep(projectRoot, options, deps = {}) {
   }
 
   if (decisionReport.decision.stop_class !== "continue") {
+    if (options.allowDeferredLocalBlockers === true) {
+      const deferred = await deferLocalWaveBlocker(
+        projectRoot,
+        loaded,
+        decisionReport.decision,
+        decisionRef,
+        recordedAt,
+      );
+      if (deferred.ok) {
+        const deferredEvent = await recordTopicRunEvent(projectRoot, options.topicInput, {
+          runId: options.runId,
+          eventKind: "runner_blocked",
+          stopClass: "continue",
+          recommendedAction: "admit_wave",
+          sourceRef: deferred.blockerRef,
+          summary: "deferred_local_wave_blocker",
+          recordedAt,
+          waveId: deferred.wave.wave_id,
+          artifactRefs: {
+            decision_ref: decisionRef,
+            evidence_ref: deferred.blockerRef,
+          },
+        });
+        if (!deferredEvent.ok) {
+          return deferredEvent;
+        }
+        return {
+          ok: true,
+          topicId: decisionReport.topicId,
+          topicRef: decisionReport.topicRef,
+          runId: options.runId,
+          adapter: options.adapter,
+          runnerStatus: "continued",
+          executed: true,
+          stopClass: "continue",
+          recommendedAction: "defer_local_wave_blocker",
+          decision: decisionReport.decision,
+          gate: buildGate(decisionReport.decision),
+          decisionRef,
+          deferredBlocker: {
+            waveId: deferred.wave.wave_id,
+            reasonCode: decisionReport.decision.reason_code,
+            blockerRef: deferred.blockerRef,
+            nextWaveId: deferred.nextWave.wave_id,
+          },
+          ledgerRef: deferredEvent.ledgerRef,
+          eventCount: deferredEvent.eventCount,
+        };
+      }
+    }
     return {
       ok: true,
       topicId: decisionReport.topicId,
@@ -549,7 +501,7 @@ export async function runTopicRunnerStep(projectRoot, options, deps = {}) {
     }, parsedCommand.error);
   }
 
-  if (["admit_wave", "freeze_packet", "closeout_wave"].includes(parsedCommand.action)) {
+  if (["admit_wave", "freeze_packet", "closeout_wave", "record_result"].includes(parsedCommand.action)) {
     const commandExecution = await executeMechanicalCommand(projectRoot, { ...options, recordedAt }, parsedCommand);
     if (!commandExecution.ok) {
       const blockedEvent = await recordRunnerBlocked(projectRoot, { ...options, verifiedAt: recordedAt }, {
@@ -595,7 +547,7 @@ export async function runTopicRunnerStep(projectRoot, options, deps = {}) {
       recommendedAction: parsedCommand.action,
       sourceRef: commandExecution.eventSourceRef,
       summary: commandExecution.summary,
-      recordedAt,
+      recordedAt: commandExecution.recordedAt ?? recordedAt,
       waveId: commandExecution.waveId,
       artifactRefs,
     });
@@ -728,7 +680,10 @@ export async function runTopicRunner(projectRoot, options, deps = {}) {
     : 20;
   const steps = [];
   for (let index = 0; index < maxSteps; index += 1) {
-    const step = await runTopicRunnerStep(projectRoot, options, deps);
+    const step = await runTopicRunnerStep(projectRoot, {
+      ...options,
+      allowDeferredLocalBlockers: true,
+    }, deps);
     steps.push(step);
     if (!step.ok || step.runnerStatus !== "continued") {
       return {