@nimiplatform/nimi-coding 0.1.0 → 0.2.0

package/cli/lib/topic-decisions.mjs

@@ -0,0 +1,332 @@
+import {
+  buildDispatchPrompt,
+  buildPostUpdateReviewDecision,
+  buildPreImplementationDecision,
+  loadAuthorityConvergencePolicy,
+} from "./authority-convergence.mjs";
+import path from "node:path";
+
+import { findUniqueFreezableDraftPacket } from "./topic-draft-packets.mjs";
+import { loadTopicRuntimeAuthority, toPortableRelativePath } from "./topic-common.mjs";
+import { findDeterministicNextWave, getTopicWaves, loadTopicReport } from "./topic-scaffold.mjs";
+import { validateTopicGraph, validateWaveAdmission } from "./topic-waves.mjs";
+import { listWavePackets, listWaveResults } from "./topic-artifacts.mjs";
+
+export function buildTopicStepDecision(topic, wave, values) {
+  const waveId = wave?.wave_id ?? null;
+  return {
+    decision_id: `${topic.topic_id}:${waveId ?? "topic"}:${values.reasonCode}`,
+    topic_id: topic.topic_id,
+    wave_id: waveId,
+    decision_kind: "topic_next_step",
+    stop_class: values.stopClass,
+    recommended_action: values.recommendedAction,
+    reason_code: values.reasonCode,
+    requires_human_confirmation: values.stopClass === "require_human_confirmation",
+    recommended_decision: values.recommendedDecision,
+    recommendation_rationale: values.recommendationRationale,
+    expected_artifacts: values.expectedArtifacts ?? [],
+    next_command_ref: values.nextCommandRef ?? null,
+    blocking_checks: values.blockingChecks ?? [],
+  };
+}
+export function commandRef(parts) {
+  return ["nimicoding", "topic", ...parts].join(" ");
+}
+export async function buildDecisionForSelectedWave(projectRoot, loaded, graphReport, wave) {
+  const failedGraphChecks = (graphReport.checks ?? []).filter((entry) => !entry.ok);
+  if (!graphReport.ok)
+    return buildTopicStepDecision(loaded.topic, wave, {
+      stopClass: "blocked",
+      recommendedAction: "no_action",
+      reasonCode: "topic_graph_validation_failed",
+      recommendedDecision: "fix_topic_graph_before_continuing",
+      recommendationRationale:
+        "The wave graph is the dispatch authority for topic execution and must validate before any next step is emitted.",
+      blockingChecks: failedGraphChecks,
+    });
+  if (["closed", "retired", "superseded"].includes(wave.state))
+    return buildTopicStepDecision(loaded.topic, wave, {
+      stopClass: "blocked",
+      recommendedAction: "no_action",
+      reasonCode: "selected_wave_is_terminal",
+      recommendedDecision: "select_a_non_terminal_wave_or_close_the_topic",
+      recommendationRationale: `Selected wave ${wave.wave_id} is ${wave.state} and cannot be dispatched.`,
+    });
+  if (wave.state === "needs_revision")
+    return buildTopicStepDecision(loaded.topic, wave, {
+      stopClass: "blocked",
+      recommendedAction: "open_remediation",
+      reasonCode: "revise",
+      recommendedDecision: "fix",
+      recommendationRationale: "Block.",
+    });
+  if (["candidate", "preflight_draft"].includes(wave.state)) {
+    const admission = await validateWaveAdmission(projectRoot, loaded.topicId, wave.wave_id);
+    return admission.ok
+      ? buildTopicStepDecision(loaded.topic, wave, {
+          stopClass: "continue",
+          recommendedAction: "admit_wave",
+          reasonCode: "wave_admission_ready",
+          recommendedDecision: "admit_wave",
+          recommendationRationale: "Admission is mechanical.",
+          nextCommandRef: commandRef(["wave", "admit", loaded.topicId, wave.wave_id]),
+        })
+      : buildTopicStepDecision(loaded.topic, wave, {
+          stopClass: "blocked",
+          recommendedAction: "admit_wave",
+          reasonCode: "wave_admission_validation_failed",
+          recommendedDecision: "repair_admission_blockers",
+          recommendationRationale:
+            "The selected wave cannot be admitted until its admission checks pass.",
+          nextCommandRef: commandRef([
+            "validate",
+            "admission",
+            loaded.topicId,
+            wave.wave_id,
+            "--json",
+          ]),
+          blockingChecks: (admission.checks ?? []).filter((entry) => !entry.ok),
+        });
+  }
+  if (
+    ["preflight_admitted", "implementation_admitted", "continuation_packet_open"].includes(
+      wave.state,
+    )
+  )
+    return buildTopicStepDecision(
+      loaded.topic,
+      wave,
+      await buildPreImplementationDecision({
+        projectRoot,
+        loaded,
+        wave,
+        commandRef,
+        listWavePackets,
+        listWaveResults,
+        findUniqueFreezableDraftPacket,
+        loadTopicRuntimeAuthority,
+      }),
+    );
+  if (wave.state === "implementation_active") {
+    const waveResults = await listWaveResults(loaded.topicDir, wave.wave_id),
+      implementationResult = waveResults.find(
+        (entry) => entry.result?.result_kind === "implementation",
+      );
+    if (!implementationResult)
+      return buildTopicStepDecision(loaded.topic, wave, {
+        stopClass: "await_external_evidence",
+        recommendedAction: "record_result",
+        reasonCode: "awaiting_implementation_result",
+        recommendedDecision: "ingest_the_implementation_result_when_available",
+        recommendationRationale:
+          "The wave is active, but closeout requires explicit implementation result lineage.",
+        expectedArtifacts: ["result-<wave-id>-implementation.md"],
+        nextCommandRef: commandRef([
+          "result",
+          "record",
+          loaded.topicId,
+          "--kind",
+          "implementation",
+          "--verdict",
+          "<verdict>",
+          "--from",
+          "<path>",
+          "--verified-at",
+          "<utc>",
+        ]),
+      });
+    const postUpdateReviewDecision = await buildPostUpdateReviewDecision({
+      projectRoot,
+      topicDir: loaded.topicDir,
+      topicId: loaded.topicId,
+      wave,
+      packets: await listWavePackets(loaded.topicDir, wave.wave_id),
+      results: waveResults,
+      policy: await loadAuthorityConvergencePolicy(projectRoot),
+      commandRef,
+    });
+    return postUpdateReviewDecision
+      ? buildTopicStepDecision(loaded.topic, wave, postUpdateReviewDecision)
+      : buildTopicStepDecision(loaded.topic, wave, {
+          stopClass: "continue",
+          recommendedAction: "closeout_wave",
+          reasonCode: "wave_has_result_lineage_ready_for_closeout",
+          recommendedDecision: "closeout_wave",
+          recommendationRationale:
+            "Wave closeout is a deterministic phase transition once lineage-backed result evidence exists.",
+          nextCommandRef: commandRef([
+            "closeout",
+            "wave",
+            loaded.topicId,
+            wave.wave_id,
+            "--authority",
+            "closed",
+            "--semantic",
+            "closed",
+            "--consumer",
+            "closed",
+            "--drift-resistance",
+            "closed",
+            "--disposition",
+            "complete",
+          ]),
+        });
+  }
+  return wave.state === "overflowed"
+    ? buildTopicStepDecision(loaded.topic, wave, {
+        stopClass: "require_human_confirmation",
+        recommendedAction: "continue_overflow",
+        reasonCode: "overflow_requires_manager_judgement",
+        recommendedDecision: "approve_continuation_only_if_the_same_owner_domain_rule_still_holds",
+        recommendationRationale:
+          "Overflow is not pass or rollback; continuation requires explicit manager judgement.",
+        nextCommandRef: commandRef([
+          "overflow",
+          "continue",
+          loaded.topicId,
+          "--packet",
+          "<continuation-packet-id>",
+          "--overflowed-packet",
+          "<packet-id>",
+          "--manager-judgement",
+          "<text>",
+          "--same-owner-domain",
+        ]),
+      })
+    : buildTopicStepDecision(loaded.topic, wave, {
+        stopClass: "blocked",
+        recommendedAction: "no_action",
+        reasonCode: "unsupported_wave_state",
+        recommendedDecision: "repair_or_review_the_selected_wave_state",
+        recommendationRationale: `No next-step rule is defined for wave state ${wave.state}.`,
+      });
+}
+export async function decideTopicNextStep(projectRoot, input = null) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const { validateTopicRoot } = await import("./topic-root-validation.mjs");
+  const rootValidation = await validateTopicRoot(projectRoot, input),
+    selectedWave =
+      getTopicWaves(loaded.topic).find(
+        (entry) => entry.wave_id === loaded.topic.selected_next_target,
+      ) ?? null;
+  if (!rootValidation.ok)
+    return {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+      decision: buildTopicStepDecision(loaded.topic, selectedWave, {
+        stopClass: "blocked",
+        recommendedAction: "no_action",
+        reasonCode: "topic_root_validation_failed",
+        recommendedDecision: "repair_topic_root_before_continuing",
+        recommendationRationale:
+          "The topic root must validate before a next execution step can be selected.",
+        blockingChecks: (rootValidation.checks ?? []).filter((entry) => !entry.ok),
+      }),
+    };
+  if (loaded.topic.state === "pending")
+    return {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+      decision: buildTopicStepDecision(loaded.topic, selectedWave, {
+        stopClass: "await_external_evidence",
+        recommendedAction: "resume_topic",
+        reasonCode: "topic_pending_wait",
+        recommendedDecision: "resume_only_when_the_pending_note_reopen_criteria_are_met",
+        recommendationRationale:
+          "Pending is an explicit wait state and must not be bypassed by the loop.",
+        nextCommandRef: commandRef(["resume", loaded.topicId, "--criteria-met", "<text>"]),
+      }),
+    };
+  if (
+    !loaded.topic.selected_next_target ||
+    loaded.topic.selected_next_target === "topic_design_baseline"
+  ) {
+    const allWavesTerminal =
+        getTopicWaves(loaded.topic).filter(
+          (entry) => !["closed", "retired", "superseded"].includes(entry.state),
+        ).length === 0 && getTopicWaves(loaded.topic).length > 0,
+      deterministicNextWave = allWavesTerminal ? null : findDeterministicNextWave(loaded.topic);
+    return {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+      decision: buildTopicStepDecision(
+        loaded.topic,
+        deterministicNextWave,
+        allWavesTerminal
+          ? {
+              stopClass: "completed",
+              recommendedAction: "closeout_topic",
+              reasonCode: "all_waves_terminal",
+              recommendedDecision: "run_topic_closeout_and_true_close_checks",
+              recommendationRationale:
+                "All waves are terminal, so the next step is topic-level closeout review.",
+              nextCommandRef: commandRef([
+                "closeout",
+                "topic",
+                loaded.topicId,
+                "--authority",
+                "closed",
+                "--semantic",
+                "closed",
+                "--consumer",
+                "closed",
+                "--drift-resistance",
+                "closed",
+                "--disposition",
+                "complete",
+              ]),
+            }
+          : deterministicNextWave
+            ? {
+                stopClass: "continue",
+                recommendedAction: "admit_wave",
+                reasonCode: "deterministic_next_wave_ready",
+                recommendedDecision: "admit_wave",
+                recommendationRationale:
+                  "The first dependency-ready non-terminal wave in topic.yaml waves[] order is selected mechanically.",
+                nextCommandRef: commandRef([
+                  "wave",
+                  "admit",
+                  loaded.topicId,
+                  deterministicNextWave.wave_id,
+                ]),
+              }
+            : {
+                stopClass: "require_human_confirmation",
+                recommendedAction: "admit_wave",
+                reasonCode: "no_selected_next_target",
+                recommendedDecision: "select_the_next_wave_or_hold_the_topic",
+                recommendationRationale:
+                  "The loop cannot choose among possible next waves without manager judgement.",
+                nextCommandRef: commandRef(["wave", "select", loaded.topicId, "<wave-id>"]),
+              },
+      ),
+    };
+  }
+  if (!selectedWave)
+    return {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+      decision: buildTopicStepDecision(loaded.topic, null, {
+        stopClass: "blocked",
+        recommendedAction: "no_action",
+        reasonCode: "selected_next_target_does_not_resolve",
+        recommendedDecision: "repair_topic_selected_next_target",
+        recommendationRationale: `selected_next_target does not resolve to a declared wave: ${loaded.topic.selected_next_target}`,
+      }),
+    };
+  const graphReport = await validateTopicGraph(projectRoot, input);
+  return {
+    ok: true,
+    topicId: loaded.topicId,
+    topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+    decision: await buildDecisionForSelectedWave(projectRoot, loaded, graphReport, selectedWave),
+  };
+}
+const RUN_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

package/cli/lib/topic-draft-packets.mjs

@@ -1,7 +1,13 @@
-import { readdir } from "node:fs/promises";
+import { readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import YAML from "yaml";
 
 import { readTextIfFile } from "./fs-helpers.mjs";
+import {
+  packetAuthorityCoverage,
+  packetAuthorityCoverageError,
+  sourceSweepDesignAuthorityRefs,
+} from "./topic-authority-coverage.mjs";
 import { parseYamlText } from "./yaml-helpers.mjs";
 
 function toPortableRelativePath(filePath) {
@@ -19,6 +25,105 @@ function parsePacketDraft(text) {
   return parseYamlText(text);
 }
 
+function nonEmptyStringArray(value) {
+  return Array.isArray(value)
+    ? value.filter((entry) => typeof entry === "string" && entry.length > 0)
+    : [];
+}
+
+function singleStringList(value) {
+  return typeof value === "string" && value.length > 0 ? [value] : nonEmptyStringArray(value);
+}
+
+function missingSweepDraftFields(wave) {
+  const source = wave?.source_sweep_design;
+  if (!source || typeof source !== "object") {
+    return ["source_sweep_design"];
+  }
+  const missing = [];
+  if (singleStringList(source.authority_owner).length === 0) missing.push("source_sweep_design.authority_owner");
+  if (nonEmptyStringArray(source.validation_commands).length === 0) missing.push("source_sweep_design.validation_commands");
+  if (nonEmptyStringArray(source.negative_checks).length === 0) missing.push("source_sweep_design.negative_checks");
+  if (nonEmptyStringArray(source.closeout_criteria).length === 0) missing.push("source_sweep_design.closeout_criteria");
+  if (nonEmptyStringArray(source.source_design_packet_refs).length === 0) missing.push("source_sweep_design.source_design_packet_refs");
+  if (nonEmptyStringArray(source.design_auditor_result_refs).length === 0) missing.push("source_sweep_design.design_auditor_result_refs");
+  if (nonEmptyStringArray(source.revision_ledger_entry_refs).length === 0) missing.push("source_sweep_design.revision_ledger_entry_refs");
+  if (nonEmptyStringArray(source.blocked_gate_refs).length > 0) missing.push("source_sweep_design.blocked_gate_refs_empty");
+  return missing;
+}
+
+async function maybeGenerateSweepFixDraft(projectRoot, loaded, wave) {
+  const missing = missingSweepDraftFields(wave);
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      reasonCode: missing.includes("source_sweep_design.blocked_gate_refs_empty")
+        ? "admitted_wave_has_blocked_gate_refs"
+        : missing.includes("source_sweep_design.validation_commands")
+          ? "admitted_wave_missing_validation_commands"
+          : "admitted_wave_requires_packet",
+      missing,
+    };
+  }
+
+  const draftPath = path.join(loaded.topicDir, `draft-${wave.wave_id}-implementation.yaml`);
+  if (await readTextIfFile(draftPath) !== null) {
+    return {
+      ok: false,
+      reasonCode: "admitted_wave_has_ambiguous_draft_packets",
+    };
+  }
+
+  const source = wave.source_sweep_design;
+  const sourceAuthorityRefs = sourceSweepDesignAuthorityRefs(source);
+  const packet = {
+    packet_id: `${wave.wave_id}-implementation`,
+    topic_id: loaded.topicId,
+    wave_id: wave.wave_id,
+    packet_kind: "implementation",
+    status: "draft",
+    authority_owner: sourceAuthorityRefs.length > 0 ? sourceAuthorityRefs : singleStringList(source.authority_owner),
+    canonical_seams: [
+      ...(sourceAuthorityRefs.length > 0 ? sourceAuthorityRefs : singleStringList(source.authority_owner)),
+      ...nonEmptyStringArray(source.source_design_packet_refs),
+      ...nonEmptyStringArray(source.design_auditor_result_refs),
+      ...nonEmptyStringArray(source.revision_ledger_entry_refs),
+    ],
+    forbidden_shortcuts: nonEmptyStringArray(loaded.topic?.forbidden_shortcuts),
+    acceptance_invariants: [
+      ...nonEmptyStringArray(source.closeout_criteria),
+      ...nonEmptyStringArray(source.validation_commands).map((command) => `validation command required: ${command}`),
+    ],
+    negative_tests: nonEmptyStringArray(source.negative_checks),
+    reopen_conditions: [
+      ...nonEmptyStringArray(source.drift_resistance_checks),
+      "source_sweep_design provenance changes require packet regeneration",
+    ],
+    source_sweep_design_run_id: source.run_id ?? null,
+    source_authority_refs: sourceAuthorityRefs,
+    source_authority_coverage_policy: "authority_owner_and_canonical_seams_cover_union_of_source_sweep_design_authority_refs",
+    source_design_packet_refs: nonEmptyStringArray(source.source_design_packet_refs),
+    design_auditor_result_refs: nonEmptyStringArray(source.design_auditor_result_refs),
+    revision_ledger_entry_refs: nonEmptyStringArray(source.revision_ledger_entry_refs),
+    validation_commands: nonEmptyStringArray(source.validation_commands),
+    closeout_criteria: nonEmptyStringArray(source.closeout_criteria),
+  };
+  if (packet.forbidden_shortcuts.length === 0) {
+    return {
+      ok: false,
+      reasonCode: "admitted_wave_requires_packet",
+      missing: ["topic.forbidden_shortcuts"],
+    };
+  }
+  await writeFile(draftPath, YAML.stringify(packet), "utf8");
+  return {
+    ok: true,
+    packet,
+    draftRef: toPortableRelativePath(path.relative(projectRoot, draftPath)),
+    generated: true,
+  };
+}
+
 export async function findUniqueFreezableDraftPacket(projectRoot, loaded, wave, authority) {
   const matches = [];
   for (const entry of await readdir(loaded.topicDir, { withFileTypes: true })) {
@@ -32,17 +137,31 @@ export async function findUniqueFreezableDraftPacket(projectRoot, loaded, wave,
       const value = packet[field];
       return value == null || value === "" || (Array.isArray(value) && value.length === 0);
     })) continue;
+    const coverage = packetAuthorityCoverage(packet, wave);
+    if (!coverage.ok) {
+      return {
+        ok: false,
+        reasonCode: "admitted_wave_packet_authority_coverage_incomplete",
+        missing: [
+          ...coverage.missingAuthorityOwnerRefs.map((ref) => `authority_owner:${ref}`),
+          ...coverage.missingCanonicalSeamRefs.map((ref) => `canonical_seams:${ref}`),
+        ],
+        error: packetAuthorityCoverageError(coverage),
+      };
+    }
     matches.push({
       packet,
       draftRef: toPortableRelativePath(path.relative(projectRoot, draftPath)),
     });
   }
-  return matches.length === 1
-    ? { ok: true, ...matches[0] }
-    : {
+  if (matches.length === 1) {
+    return { ok: true, ...matches[0] };
+  }
+  if (matches.length > 1) {
+    return {
       ok: false,
-      reasonCode: matches.length === 0
-        ? "admitted_wave_requires_packet"
-        : "admitted_wave_has_ambiguous_draft_packets",
+      reasonCode: "admitted_wave_has_ambiguous_draft_packets",
     };
+  }
+  return maybeGenerateSweepFixDraft(projectRoot, loaded, wave);
 }