@nimiplatform/nimi-coding 0.2.8 → 0.3.0

package/cli/lib/topic-scaffold.mjs

@@ -1,252 +0,0 @@
-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

@@ -1,403 +0,0 @@
-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,
-    }
-  );
-}