@nimiplatform/nimi-coding 0.1.0 → 0.2.1

package/cli/lib/topic-scaffold.mjs

@@ -0,0 +1,252 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+import { pathExists, readTextIfFile } from "./fs-helpers.mjs";
+import { parseYamlText } from "./yaml-helpers.mjs";
+import {
+  TOPIC_ID_PATTERN,
+  TOPIC_ROOT,
+  TOPIC_SLUG_PATTERN,
+  formatDate,
+  loadTopicRuntimeAuthority,
+  toPortableRelativePath,
+} from "./topic-common.mjs";
+
+export function titleFromSlug(slug) {
+  return slug
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+export function deriveTopicId(slug, date = new Date()) {
+  return TOPIC_ID_PATTERN.test(slug) ? slug : `${formatDate(date)}-${slug}`;
+}
+export function getTopicRoot(projectRoot) {
+  return path.join(projectRoot, TOPIC_ROOT);
+}
+export function getTopicStateRoot(projectRoot, state) {
+  return path.join(getTopicRoot(projectRoot), state);
+}
+export function isTopicPathInput(value) {
+  return typeof value == "string" && (value.includes("/") || value.startsWith("."));
+}
+export function buildCreatePayload(options, authority) {
+  return {
+    topic_id: options.topicId,
+    state: "proposal",
+    created_at: options.today,
+    last_transition_at: options.today,
+    last_transition_reason: "topic_created_via_nimicoding_topic_create",
+    title: options.title,
+    mode: options.mode,
+    posture: options.posture,
+    design_policy: options.designPolicy,
+    parallel_truth: options.parallelTruth,
+    layering: options.layering,
+    risk: options.risk,
+    applicability: options.applicability,
+    entry_justification: options.justification,
+    execution_mode: options.executionMode,
+    selected_next_target: "topic_design_baseline",
+    current_true_close_status: "not_started",
+    forbidden_shortcuts: authority.defaultForbiddenShortcuts,
+    waves: [],
+  };
+}
+export function buildReadme(topic) {
+  return `# ${topic.title}
+State: \`${topic.state}\`
+This topic was created by \`nimicoding topic create\`.
+## Purpose
+TODO: explain why this work needs topic-level governance rather than the ordinary non-topic path.
+## Entry Posture
+- mode: \`${topic.mode}\`
+- posture: \`${topic.posture}\`
+- design policy: \`${topic.design_policy}\`
+- applicability: \`${topic.applicability}\`
+- execution mode: \`${topic.execution_mode}\`
+## Current Next Action
+- selected_next_target: \`${topic.selected_next_target}\`
+- TODO: freeze the first bounded wave target before admission
+`;
+}
+export function buildDesign(topicId) {
+  return `# Design
+Topic: \`${topicId}\`
+This file is the index for split design companions.
+- TODO: add subtopic design files as the topic grows
+- TODO: keep this file as an index rather than collapsing the whole topic into one document
+`;
+}
+export function buildSimpleCompanion(title, topicId, bullets) {
+  return `# ${title}
+Topic: \`${topicId}\`
+${bullets.map((item) => `- ${item}`).join(`
+`)}
+`;
+}
+export async function writeTopicScaffold(topicDir, topic) {
+  const files = new Map([
+    ["topic.yaml", YAML.stringify(topic)],
+    ["README.md", buildReadme(topic)],
+    ["design.md", buildDesign(topic.topic_id)],
+    ["preflight.md", buildSimpleCompanion("Preflight", topic.topic_id, ["TODO", "TODO"])],
+    ["waves.md", buildSimpleCompanion("Waves", topic.topic_id, ["TODO", "TODO"])],
+    [
+      "candidate-wave-plan.md",
+      buildSimpleCompanion("Candidate Wave Plan", topic.topic_id, ["TODO", "TODO"]),
+    ],
+    ["closeout.md", buildSimpleCompanion("Closeout", topic.topic_id, ["TODO", "TODO"])],
+    [
+      "implementation-doctrine.md",
+      buildSimpleCompanion("Implementation Doctrine", topic.topic_id, ["TODO", "TODO"]),
+    ],
+    [
+      "admission-checklists.md",
+      buildSimpleCompanion("Admission Checklists", topic.topic_id, ["TODO", "TODO"]),
+    ],
+    [
+      "manager-session-protocol.md",
+      buildSimpleCompanion("Manager Session Protocol", topic.topic_id, ["TODO", "TODO"]),
+    ],
+    ["manager-prompts.md", buildSimpleCompanion("Manager Prompts", topic.topic_id, ["TODO"])],
+  ]);
+  await mkdir(topicDir, { recursive: false });
+  for (const [fileName, contents] of files.entries())
+    await writeFile(path.join(topicDir, fileName), contents, "utf8");
+}
+export function validateTopicSlug(value) {
+  return TOPIC_SLUG_PATTERN.test(value);
+}
+export function validateTopicId(value) {
+  return TOPIC_ID_PATTERN.test(value);
+}
+export async function findTopicDirectory(projectRoot, input = null) {
+  const authority = await loadTopicRuntimeAuthority(projectRoot),
+    topicStatePattern = authority.topicStates.join("|");
+  if (!input) {
+    const current = process.cwd(),
+      match = toPortableRelativePath(path.relative(projectRoot, current)).match(
+        new RegExp(
+          `^\\.nimi/topics/(${topicStatePattern})/(\\d{4}-\\d{2}-\\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*)`,
+        ),
+      );
+    return match
+      ? {
+          ok: true,
+          topicDir: path.join(projectRoot, ".nimi", "topics", match[1], match[2]),
+          topicId: match[2],
+          state: match[1],
+        }
+      : {
+          ok: false,
+          error:
+            "No topic id or topic path was provided, and the current working directory is not inside a topic root.",
+        };
+  }
+  if (isTopicPathInput(input)) {
+    const topicDir = path.resolve(projectRoot, input),
+      match = toPortableRelativePath(path.relative(projectRoot, topicDir)).match(
+        new RegExp(
+          `^\\.nimi/topics/(${topicStatePattern})/(\\d{4}-\\d{2}-\\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*)$`,
+        ),
+      );
+    return match
+      ? { ok: true, topicDir, topicId: match[2], state: match[1] }
+      : { ok: false, error: `Topic path must resolve to .nimi/topics/<state>/<topic-id>: ${input}` };
+  }
+  const matches = [];
+  for (const state of authority.topicStates) {
+    const candidate = path.join(getTopicStateRoot(projectRoot, state), input);
+    (await pathExists(candidate))?.isDirectory() &&
+      matches.push({ state, topicDir: candidate, topicId: input });
+  }
+  return matches.length === 1
+    ? { ok: true, ...matches[0] }
+    : matches.length > 1
+      ? {
+          ok: false,
+          error: `Topic id resolves to multiple lifecycle roots and must be disambiguated by path: ${input}`,
+        }
+      : { ok: false, error: `Topic not found under ${TOPIC_ROOT}: ${input}` };
+}
+export async function resolveTopicProjectRoot(startDir) {
+  let currentDir = path.resolve(startDir);
+  for (;;) {
+    if ((await pathExists(path.join(currentDir, ".nimi")))?.isDirectory()) return currentDir;
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return path.resolve(startDir);
+    currentDir = parentDir;
+  }
+}
+export async function loadTopicReport(projectRoot, input = null) {
+  const resolved = await findTopicDirectory(projectRoot, input);
+  if (!resolved.ok) return resolved;
+  const topicYamlPath = path.join(resolved.topicDir, "topic.yaml"),
+    topicYamlText = await readTextIfFile(topicYamlPath);
+  if (topicYamlText === null)
+    return {
+      ok: false,
+      error: `Missing topic.yaml at ${toPortableRelativePath(path.relative(projectRoot, topicYamlPath))}`,
+    };
+  const topic = parseYamlText(topicYamlText);
+  return !topic || typeof topic != "object"
+    ? {
+        ok: false,
+        error: `topic.yaml is not valid YAML at ${toPortableRelativePath(path.relative(projectRoot, topicYamlPath))}`,
+      }
+    : { ok: true, ...resolved, topicYamlPath, topicYamlText, topic };
+}
+export function getTopicWaves(topic) {
+  return Array.isArray(topic.waves) ? topic.waves.map((entry) => ({ ...entry })) : [];
+}
+export function findDeterministicNextWave(topic) {
+  const waves = getTopicWaves(topic),
+    terminalIds = new Set(
+      waves
+        .filter((entry) => ["closed", "retired", "superseded"].includes(entry.state))
+        .map((entry) => entry.wave_id),
+    ),
+    ready = waves.filter(
+      (entry) =>
+        !["closed", "retired", "superseded"].includes(entry.state) &&
+        ["candidate", "preflight_draft"].includes(entry.state) &&
+        (Array.isArray(entry.deps) ? entry.deps : []).every((dep) => terminalIds.has(dep)),
+    );
+  return ready.length > 0 ? ready[0] : null;
+}
+export async function writeTopicYaml(topicYamlPath, topic) {
+  await writeFile(topicYamlPath, YAML.stringify(topic), "utf8");
+}
+export async function moveTopicDirectoryForState(projectRoot, currentDir, topicId, targetState) {
+  const targetDir = path.join(getTopicStateRoot(projectRoot, targetState), topicId);
+  return currentDir === targetDir
+    ? { topicDir: currentDir, topicYamlPath: path.join(currentDir, "topic.yaml") }
+    : (await mkdir(path.dirname(targetDir), { recursive: true }),
+      await rename(currentDir, targetDir),
+      { topicDir: targetDir, topicYamlPath: path.join(targetDir, "topic.yaml") });
+}
+export function topicHasEnrichedShape(topic, authority) {
+  return authority.enrichedRequiredFields.every((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);
+  });
+}
+export function buildTopicNow() {
+  return formatDate(new Date());
+}
+export function isIsoUtcTimestamp(value) {
+  if (
+    typeof value !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)
+  )
+    return false;
+  const parsed = new Date(value),
+    canonicalValue = value.includes(".") ? value : value.replace("Z", ".000Z");
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === canonicalValue;
+}

package/cli/lib/topic-waves.mjs

@@ -0,0 +1,403 @@
+import { readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { loadAuthorityConvergencePolicy } from "./authority-convergence.mjs";
+import { loadTopicRuntimeContracts } from "./contracts.mjs";
+import { readTextIfFile } from "./fs-helpers.mjs";
+import { fileReferencesWave } from "./topic-lifecycle-artifacts.mjs";
+import {
+  DEFAULT_TOPIC_RUNTIME_AUTHORITY,
+  PENDING_ENTRY_BLOCKER_STATES,
+  WAVE_ID_PATTERN,
+  loadTopicRuntimeAuthority,
+  toPortableRelativePath,
+} from "./topic-common.mjs";
+import { pendingNoteFilename, readFrontmatterObject } from "./topic-artifacts.mjs";
+import {
+  buildTopicNow,
+  findDeterministicNextWave,
+  getTopicWaves,
+  isIsoUtcTimestamp,
+  loadTopicReport,
+  moveTopicDirectoryForState,
+  topicHasEnrichedShape,
+  writeTopicYaml,
+} from "./topic-scaffold.mjs";
+
+export async function collectWaveArtifactEvidence(topicDir, waveId) {
+  const files = (await readdir(topicDir, { withFileTypes: true }))
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name);
+  return {
+    packetRefs: files.filter(
+      (name) => name.startsWith("packet-") && fileReferencesWave(name, waveId),
+    ),
+    resultRefs: files.filter(
+      (name) => name.startsWith("result-") && fileReferencesWave(name, waveId),
+    ),
+    closeoutRefs: files.filter(
+      (name) => name.startsWith("closeout-") && fileReferencesWave(name, waveId),
+    ),
+    remediationRefs: files.filter(
+      (name) => name.includes("remediation") && fileReferencesWave(name, waveId),
+    ),
+    overflowRefs: files.filter(
+      (name) => name.includes("overflow-continuation") && fileReferencesWave(name, waveId),
+    ),
+  };
+}
+export async function loadPendingNote(topicDir) {
+  const notePath = path.join(topicDir, pendingNoteFilename()),
+    noteText = await readTextIfFile(notePath);
+  if (noteText === null)
+    return { ok: false, notePath, error: `Missing pending note artifact: ${pendingNoteFilename()}` };
+  const note = readFrontmatterObject(noteText);
+  return note
+    ? { ok: true, notePath, note }
+    : { ok: false, notePath, error: "Pending note artifact frontmatter is invalid" };
+}
+export function getPendingEntryBlockers(topic) {
+  return getTopicWaves(topic)
+    .filter((entry) => PENDING_ENTRY_BLOCKER_STATES.has(entry.state))
+    .map((entry) => `${entry.wave_id}:${entry.state}`);
+}
+export async function loadTopicValidationPolicy(projectRoot) {
+  const parsed = (await loadTopicRuntimeContracts(projectRoot)).validationPolicy.data,
+    entries = Array.isArray(parsed?.topic_validation_policy?.ignore_for_default_validate)
+      ? parsed.topic_validation_policy.ignore_for_default_validate
+      : [],
+    ignoredTopicIds = new Map();
+  for (const entry of entries)
+    entry &&
+      typeof entry.topic_id == "string" &&
+      entry.topic_id.length > 0 &&
+      ignoredTopicIds.set(entry.topic_id, {
+        reason: typeof entry.reason == "string" ? entry.reason : null,
+        posture: typeof entry.posture == "string" ? entry.posture : null,
+      });
+  const semantics = parsed?.topic_validation_policy?.ignored_topic_validate_semantics ?? {};
+  return {
+    ignoredTopicIds,
+    ignoredTopicValidateSemantics: {
+      status:
+        typeof semantics.status == "string"
+          ? semantics.status
+          : DEFAULT_TOPIC_RUNTIME_AUTHORITY.ignoredTopicValidateSemantics.status,
+      canonicalSuccess:
+        typeof semantics.canonical_success == "boolean"
+          ? semantics.canonical_success
+          : DEFAULT_TOPIC_RUNTIME_AUTHORITY.ignoredTopicValidateSemantics.canonicalSuccess,
+    },
+  };
+}
+export function validateWaveId(value) {
+  return WAVE_ID_PATTERN.test(value);
+}
+export function normalizeDeps(value) {
+  return Array.isArray(value) ? value.map((entry) => String(entry)) : [];
+}
+export function validateGraphFromTopic(topic) {
+  const waves = getTopicWaves(topic),
+    checks = [],
+    warnings = [],
+    waveIds = waves.map((entry) => entry.wave_id),
+    uniqueWaveIds = new Set(waveIds);
+  checks.push({
+    id: "wave_ids_unique",
+    ok: uniqueWaveIds.size === waveIds.length,
+    reason:
+      uniqueWaveIds.size === waveIds.length
+        ? "wave ids are unique"
+        : "duplicate wave ids exist in topic.yaml waves[]",
+  });
+  const invalidWaveIds = waveIds.filter((entry) => !validateWaveId(entry));
+  checks.push({
+    id: "wave_ids_valid",
+    ok: invalidWaveIds.length === 0,
+    reason:
+      invalidWaveIds.length === 0
+        ? "wave ids use the canonical wave-<n>-slug shape"
+        : `invalid wave ids: ${invalidWaveIds.join(", ")}`,
+  });
+  const missingDeps = [],
+    selectedWaveIds = [],
+    retiredSelected = [];
+  for (const wave of waves) {
+    const deps = normalizeDeps(wave.deps);
+    for (const dep of deps) uniqueWaveIds.has(dep) || missingDeps.push(`${wave.wave_id}->${dep}`);
+    (wave.selected === true && selectedWaveIds.push(wave.wave_id),
+      wave.selected === true &&
+        ["retired", "superseded"].includes(wave.state) &&
+        retiredSelected.push(wave.wave_id));
+  }
+  (checks.push({
+    id: "wave_dependencies_resolve",
+    ok: missingDeps.length === 0,
+    reason:
+      missingDeps.length === 0
+        ? "all wave dependencies resolve inside the topic"
+        : `missing dependency refs: ${missingDeps.join(", ")}`,
+  }),
+    checks.push({
+      id: "selected_wave_unique",
+      ok: selectedWaveIds.length <= 1,
+      reason:
+        selectedWaveIds.length <= 1
+          ? "selected wave is unique"
+          : `multiple selected waves exist: ${selectedWaveIds.join(", ")}`,
+    }));
+  const selectedMatchesTopicTarget =
+    selectedWaveIds.length === 0
+      ? topic.selected_next_target === "topic_design_baseline" ||
+        topic.selected_next_target === null
+      : selectedWaveIds[0] === topic.selected_next_target;
+  (checks.push({
+    id: "selected_wave_matches_topic_target",
+    ok: selectedMatchesTopicTarget,
+    reason: selectedMatchesTopicTarget
+      ? "selected wave matches topic.selected_next_target"
+      : `selected wave and topic.selected_next_target diverge (${selectedWaveIds[0] ?? "none"} vs ${topic.selected_next_target ?? "none"})`,
+  }),
+    checks.push({
+      id: "retired_or_superseded_not_selected",
+      ok: retiredSelected.length === 0,
+      reason:
+        retiredSelected.length === 0
+          ? "retired or superseded waves are not selected"
+          : `retired/superseded waves remain selected: ${retiredSelected.join(", ")}`,
+    }));
+  const visiting = new Set(),
+    visited = new Set();
+  let cycleRef = null;
+  const waveMap = new Map(waves.map((wave) => [wave.wave_id, wave]));
+  function dfs(waveId, trail = []) {
+    if (cycleRef) return;
+    if (visiting.has(waveId)) {
+      cycleRef = [...trail, waveId].join(" -> ");
+      return;
+    }
+    if (visited.has(waveId)) return;
+    visiting.add(waveId);
+    const wave = waveMap.get(waveId);
+    if (wave) for (const dep of normalizeDeps(wave.deps)) dfs(dep, [...trail, waveId]);
+    (visiting.delete(waveId), visited.add(waveId));
+  }
+  for (const waveId of waveIds) dfs(waveId);
+  return (
+    checks.push({
+      id: "graph_acyclic",
+      ok: cycleRef === null,
+      reason:
+        cycleRef === null ? "wave graph is acyclic" : `wave graph contains a cycle: ${cycleRef}`,
+    }),
+    waves.length === 0 && warnings.push("topic has no machine wave registry yet"),
+    { ok: checks.every((entry) => entry.ok), checks, warnings, waves }
+  );
+}
+export async function validateTopicGraph(projectRoot, input = null) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return { ok: false, error: loaded.error, checks: [], warnings: [] };
+  const { validateTopicRoot } = await import("./topic-root-validation.mjs");
+  const rootValidation = await validateTopicRoot(projectRoot, input);
+  if (!rootValidation.ok) return rootValidation;
+  const authority = await loadTopicRuntimeAuthority(projectRoot);
+  if (!topicHasEnrichedShape(loaded.topic, authority))
+    return {
+      ...rootValidation,
+      ok: false,
+      checks: [
+        ...rootValidation.checks,
+        {
+          id: "enriched_topic_required_for_wave_graph",
+          ok: false,
+          reason: "wave graph commands require an enriched topic root",
+        },
+      ],
+      warnings: rootValidation.warnings,
+    };
+  const graph = validateGraphFromTopic(loaded.topic);
+  return {
+    ...rootValidation,
+    ok: rootValidation.ok && graph.ok,
+    checks: [...rootValidation.checks, ...graph.checks],
+    warnings: [...rootValidation.warnings, ...graph.warnings],
+    waveCount: graph.waves.length,
+  };
+}
+export async function validateWaveAdmission(projectRoot, input, waveId) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return { ok: false, error: loaded.error, checks: [], warnings: [] };
+  const graphReport = await validateTopicGraph(projectRoot, input),
+    wave = getTopicWaves(loaded.topic).find((entry) => entry.wave_id === waveId) ?? null,
+    checks = [...(graphReport.checks ?? [])],
+    warnings = [...(graphReport.warnings ?? [])];
+  if (
+    (checks.push({
+      id: "wave_exists",
+      ok: wave !== null,
+      reason: wave ? "wave exists in topic.yaml waves[]" : `wave does not exist: ${waveId}`,
+    }),
+    !wave)
+  )
+    return { ...graphReport, ok: false, checks, warnings };
+  const dispatchableState = !["retired", "superseded", "closed", "overflowed"].includes(wave.state);
+  (checks.push({
+    id: "wave_state_dispatchable",
+    ok: dispatchableState,
+    reason: dispatchableState
+      ? "wave state is eligible for admission"
+      : `wave state is not admissible: ${wave.state}`,
+  }),
+    checks.push({
+      id: "wave_selected",
+      ok: wave.selected === true,
+      reason: wave.selected === true ? "wave is selected" : "wave must be selected before admission",
+    }),
+    checks.push({
+      id: "selected_target_matches_wave",
+      ok: loaded.topic.selected_next_target === waveId,
+      reason:
+        loaded.topic.selected_next_target === waveId
+          ? "topic.selected_next_target matches the wave"
+          : `topic.selected_next_target does not match wave (${loaded.topic.selected_next_target ?? "none"} vs ${waveId})`,
+    }));
+  const waveMap = new Map(getTopicWaves(loaded.topic).map((entry) => [entry.wave_id, entry])),
+    unmetDeps = normalizeDeps(wave.deps).filter((dep) => waveMap.get(dep)?.state !== "closed");
+  checks.push({
+    id: "upstream_dependencies_closed",
+    ok: unmetDeps.length === 0,
+    reason:
+      unmetDeps.length === 0
+        ? "all upstream dependencies are closed"
+        : `upstream dependencies are not closed: ${unmetDeps.join(", ")}`,
+  });
+  const waveStateAllowedForAdmit = ["candidate", "preflight_draft", "needs_revision"].includes(
+    wave.state,
+  );
+  return (
+    checks.push({
+      id: "wave_state_allows_preflight_admission",
+      ok: waveStateAllowedForAdmit,
+      reason: waveStateAllowedForAdmit
+        ? "wave state can move to preflight_admitted"
+        : `wave state cannot move to preflight_admitted from ${wave.state}`,
+    }),
+    { ...graphReport, ok: graphReport.ok && checks.every((entry) => entry.ok), checks, warnings }
+  );
+}
+export async function addWaveToTopic(projectRoot, input, wave) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const authority = await loadTopicRuntimeAuthority(projectRoot);
+  if (!topicHasEnrichedShape(loaded.topic, authority))
+    return { ok: false, error: "Wave commands require an enriched topic root." };
+  const waves = getTopicWaves(loaded.topic);
+  if (waves.some((entry) => entry.wave_id === wave.wave_id))
+    return { ok: false, error: `Wave already exists: ${wave.wave_id}` };
+  waves.push(wave);
+  const graphPreview = validateGraphFromTopic({ ...loaded.topic, waves }),
+    failedCheck = graphPreview.checks.find((entry) => !entry.ok);
+  return failedCheck
+    ? {
+        ok: false,
+        error: `Wave add refused: ${failedCheck.reason}`,
+        checks: graphPreview.checks,
+        warnings: graphPreview.warnings,
+      }
+    : ((loaded.topic.waves = waves),
+      await writeTopicYaml(loaded.topicYamlPath, loaded.topic),
+      {
+        ok: true,
+        topicId: loaded.topicId,
+        topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+        waveId: wave.wave_id,
+        waveState: wave.state,
+      });
+}
+export async function selectWaveInTopic(projectRoot, input, waveId) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const authority = await loadTopicRuntimeAuthority(projectRoot);
+  if (!topicHasEnrichedShape(loaded.topic, authority))
+    return { ok: false, error: "Wave commands require an enriched topic root." };
+  const waves = getTopicWaves(loaded.topic),
+    wave = waves.find((entry) => entry.wave_id === waveId);
+  if (!wave) return { ok: false, error: `Wave not found: ${waveId}` };
+  if (["retired", "superseded", "closed", "overflowed"].includes(wave.state))
+    return {
+      ok: false,
+      error: `Wave select refused: ${waveId} is not selectable from state ${wave.state}`,
+    };
+  for (const entry of waves) entry.selected = entry.wave_id === waveId;
+  return (
+    (loaded.topic.waves = waves),
+    (loaded.topic.selected_next_target = waveId),
+    (loaded.topic.last_transition_at = buildTopicNow()),
+    (loaded.topic.last_transition_reason = `selected_${waveId}_as_next_execution_target`),
+    await writeTopicYaml(loaded.topicYamlPath, loaded.topic),
+    {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+      waveId,
+      selectedNextTarget: loaded.topic.selected_next_target,
+    }
+  );
+}
+export async function admitWaveInTopic(projectRoot, input, waveId) {
+  let validation = await validateWaveAdmission(projectRoot, input, waveId);
+  if (!validation.ok) {
+    const loadedForSelection = await loadTopicReport(projectRoot, input),
+      wavesForSelection = getTopicWaves(loadedForSelection.topic),
+      waveForSelection = wavesForSelection.find((entry) => entry.wave_id === waveId),
+      terminalIds = new Set(
+        wavesForSelection
+          .filter((entry) => ["closed", "retired", "superseded"].includes(entry.state))
+          .map((entry) => entry.wave_id),
+      ),
+      depsClosed =
+        waveForSelection &&
+        (Array.isArray(waveForSelection.deps) ? waveForSelection.deps : []).every((dep) =>
+          terminalIds.has(dep),
+        ),
+      canSelectForAdmission =
+        loadedForSelection.ok &&
+        (loadedForSelection.topic.selected_next_target === null ||
+          loadedForSelection.topic.selected_next_target === "topic_design_baseline") &&
+        waveForSelection &&
+        ["candidate", "preflight_draft", "needs_revision"].includes(waveForSelection.state) &&
+        depsClosed;
+    if (canSelectForAdmission) {
+      const selected = await selectWaveInTopic(projectRoot, input, waveId);
+      if (!selected.ok) return selected;
+      validation = await validateWaveAdmission(projectRoot, input, waveId);
+    }
+  }
+  if (!validation.ok) return validation;
+  const loaded = await loadTopicReport(projectRoot, input),
+    waves = getTopicWaves(loaded.topic),
+    wave = waves.find((entry) => entry.wave_id === waveId);
+  ((wave.state = "preflight_admitted"), (loaded.topic.waves = waves));
+  let nextState = loaded.topic.state;
+  (["proposal", "pending"].includes(loaded.topic.state) &&
+    ((nextState = "ongoing"), (loaded.topic.state = nextState)),
+    (loaded.topic.last_transition_at = buildTopicNow()),
+    (loaded.topic.last_transition_reason = `wave_${waveId}_preflight_admitted`));
+  const moved = await moveTopicDirectoryForState(
+    projectRoot,
+    loaded.topicDir,
+    loaded.topicId,
+    nextState,
+  );
+  return (
+    await writeTopicYaml(moved.topicYamlPath, loaded.topic),
+    {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, moved.topicDir)),
+      waveId,
+      waveState: wave.state,
+      state: loaded.topic.state,
+    }
+  );
+}