@isaacriehm/cairn-state 0.22.5

package/dist/logger.d.ts

@@ -0,0 +1,13 @@
+/** Minimal logger interface for the state package. */
+export interface StateLogger {
+    debug: (obj: object, msg: string) => void;
+    info: (obj: object, msg: string) => void;
+    warn: (obj: object, msg: string) => void;
+    error: (obj: object, msg: string) => void;
+}
+/** No-op logger as default. */
+export declare const nullLogger: StateLogger;
+/** Set the active logger for the state package. */
+export declare function setStateLogger(l: StateLogger): void;
+/** Get the active logger. */
+export declare function getLogger(): StateLogger;

package/dist/logger.js

@@ -0,0 +1,17 @@
+/** No-op logger as default. */
+export const nullLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+let activeLogger = nullLogger;
+/** Set the active logger for the state package. */
+export function setStateLogger(l) {
+    activeLogger = l;
+}
+/** Get the active logger. */
+export function getLogger() {
+    return activeLogger;
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAQA,+BAA+B;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAgB;IACrC,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAC;AAEF,IAAI,YAAY,GAAgB,UAAU,CAAC;AAE3C,mDAAmD;AACnD,MAAM,UAAU,cAAc,CAAC,CAAc;IAC3C,YAAY,GAAG,CAAC,CAAC;AACnB,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,SAAS;IACvB,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,10 @@
+import type { Manifest } from "./schemas.js";
+export interface BuildManifestOptions {
+    repoRoot: string;
+    generator?: string;
+}
+export declare function buildManifest(opts: BuildManifestOptions): Manifest;
+export declare function writeManifest(opts: BuildManifestOptions): {
+    manifest: Manifest;
+    path: string;
+};

package/dist/manifest.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { getLogger } from "./logger.js";
+import { readFrontmatter } from "./frontmatter.js";
+import { groundDir, manifestPath } from "./paths.js";
+import { walkCanonical } from "./walk.js";
+const log = getLogger();
+export function buildManifest(opts) {
+    const { repoRoot } = opts;
+    const files = walkCanonical(repoRoot);
+    const entries = files.map((rel) => makeEntry(repoRoot, rel));
+    return {
+        version: 1,
+        generated: new Date().toISOString(),
+        ...(opts.generator !== undefined ? { generator: opts.generator } : {}),
+        files: entries,
+    };
+}
+export function writeManifest(opts) {
+    const manifest = buildManifest(opts);
+    const path = manifestPath(opts.repoRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    mkdirSync(groundDir(opts.repoRoot), { recursive: true });
+    writeFileSync(path, stringifyYaml(manifest), "utf8");
+    log.debug({ path, count: manifest.files.length }, "wrote manifest");
+    return { manifest, path };
+}
+function makeEntry(repoRoot, rel) {
+    const abs = resolve(repoRoot, rel);
+    const buf = readFileSync(abs);
+    const sha256 = createHash("sha256").update(buf).digest("hex");
+    const classification = classify(rel);
+    // For markdown, lift audience + verified_at + generator from frontmatter.
+    let audience;
+    let verifiedAt;
+    let generator;
+    let source;
+    if (rel.endsWith(".md")) {
+        const fm = readFrontmatter(abs).frontmatter;
+        if (fm) {
+            audience = fm.audience;
+            verifiedAt = fm["verified-at"];
+            const generatorValue = fm["generator"];
+            generator = typeof generatorValue === "string" ? generatorValue : undefined;
+            const sourceValue = fm["source"];
+            source = typeof sourceValue === "string" ? sourceValue : undefined;
+        }
+    }
+    return {
+        path: rel,
+        sha256,
+        classification,
+        ...(audience !== undefined ? { audience } : {}),
+        ...(verifiedAt !== undefined ? { verified_at: verifiedAt } : {}),
+        ...(generator !== undefined ? { generator } : {}),
+        ...(source !== undefined ? { source } : {}),
+    };
+}
+function classify(rel) {
+    if (rel === "AGENTS.md" || rel === "CLAUDE.md")
+        return "orientation";
+    if (rel.startsWith(".claude/rules/"))
+        return "rule";
+    if (rel.startsWith(".claude/agents/"))
+        return "agent-def";
+    if (rel.startsWith(".claude/skills/"))
+        return "skill";
+    if (rel.startsWith(".cairn/ground/decisions/"))
+        return "decision";
+    if (rel.startsWith(".cairn/ground/invariants/"))
+        return "invariant";
+    if (rel.startsWith(".cairn/config/"))
+        return "cairn-config";
+    if (rel.startsWith(".cairn/ground/"))
+        return "ground";
+    if (rel.startsWith(".cairn/tasks/"))
+        return "task";
+    if (rel.startsWith("docs/"))
+        return "doc";
+    return "other";
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/missions.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Mission-system I/O — schema-validated reads + writes for the
+ * mission surfaces: `.cairn/ground/missions/<id>/roadmap.md`
+ * (committed) and `.cairn/missions/<id>/{state.json,spec.md,journal.jsonl}`
+ * (per-clone).
+ *
+ * Pure low-level I/O; no MCP, no hooks, no LLM calls. The MCP layer in
+ * `cairn-core` composes these primitives into the operator-facing
+ * `cairn_mission_*` tools.
+ */
+import { type MissionExitGate, type MissionJournalEntry, type MissionPhase, type MissionPhaseProgressEntry, MissionPhaseBrief, MissionRoadmapFrontmatter, MissionState } from "./schemas.js";
+export interface ParsedRoadmap {
+    frontmatter: MissionRoadmapFrontmatter;
+    prose: string;
+}
+/**
+ * Parse a roadmap.md source string into validated frontmatter + prose
+ * body. Throws when frontmatter is missing or fails schema validation —
+ * roadmap.md is the contract; an unreadable roadmap is a hard error,
+ * not a soft fallback.
+ */
+export declare function parseRoadmap(source: string): ParsedRoadmap;
+export declare function serializeRoadmap(frontmatter: MissionRoadmapFrontmatter, prose?: string): string;
+export declare function readRoadmap(repoRoot: string, missionId: string): ParsedRoadmap | null;
+export declare function writeRoadmap(repoRoot: string, missionId: string, frontmatter: MissionRoadmapFrontmatter, prose?: string): void;
+export interface ParsedPhaseBrief {
+    frontmatter: MissionPhaseBrief;
+    prose: string;
+}
+export declare function parsePhaseBrief(source: string): ParsedPhaseBrief;
+/**
+ * Render a human-readable brief: YAML frontmatter (the canonical
+ * machine surface) plus a mirrored markdown body so the file reads
+ * cleanly in a diff or editor. The body is derived from the frontmatter
+ * on every write — it is never the source of truth.
+ */
+export declare function serializePhaseBrief(brief: MissionPhaseBrief, prose?: string): string;
+export declare function readPhaseBrief(repoRoot: string, missionId: string, phaseId: string): MissionPhaseBrief | null;
+export declare function writePhaseBrief(repoRoot: string, missionId: string, brief: MissionPhaseBrief, prose?: string): void;
+export declare function readMissionState(repoRoot: string, missionId: string): MissionState | null;
+export declare function writeMissionState(repoRoot: string, missionId: string, state: MissionState): void;
+export declare function readMissionSpec(repoRoot: string, missionId: string): string | null;
+export declare function writeMissionSpec(repoRoot: string, missionId: string, source: string): void;
+export declare function appendMissionJournal(repoRoot: string, missionId: string, entry: MissionJournalEntry): void;
+export declare function readMissionJournal(repoRoot: string, missionId: string): MissionJournalEntry[];
+/** Mission ids present in `.cairn/ground/missions/` (excluding `_done`). */
+export declare function listActiveMissionIds(repoRoot: string): string[];
+/** Mission ids present in `.cairn/ground/missions/_done/`. */
+export declare function listDoneMissionIds(repoRoot: string): string[];
+/**
+ * Find the single active mission id for this clone, if any. v1 enforces
+ * one active mission per repo. When multiple mission dirs exist,
+ * returns the one whose state.json reports `outcome: active` and a
+ * non-null `cursor.active_phase`. Falls back to the lexically first
+ * active id when ambiguous; mismatch is a state corruption operators
+ * surface via `cairn doctor`.
+ */
+export declare function findActiveMission(repoRoot: string): string | null;
+/**
+ * Resolve the effective exit gate for a phase: per-phase override on the
+ * roadmap entry takes precedence, falls through to the mission-level
+ * `frontmatter.exit_gate`.
+ */
+export declare function effectivePhaseExitGate(roadmap: MissionRoadmapFrontmatter, phaseId: string): MissionExitGate | null;
+/**
+ * Compute the next pending phase whose `depends_on` set is fully
+ * satisfied (all listed phases sit at `state: done` in
+ * `phase_progress`). Returns null when no eligible phase exists —
+ * either every phase is done, or all remaining are blocked by
+ * unresolved dependencies (which is a soft conflict surfaced as
+ * mission_drift).
+ *
+ * Walks roadmap order; the first eligible pending phase wins. Operators
+ * can re-order phases by hand-editing roadmap.md.
+ */
+export declare function nextPendingPhase(roadmap: MissionRoadmapFrontmatter, state: MissionState): MissionPhase | null;
+/**
+ * Number of phases at `state: done`. Used by statusline `(N/M)` and the
+ * SessionStart cursor banner.
+ */
+export declare function countDonePhases(state: MissionState): number;
+/**
+ * Initial empty `phase_progress` map for a fresh mission — every
+ * roadmap phase id present at `state: pending` with no task_ids.
+ */
+export declare function initialPhaseProgress(roadmap: MissionRoadmapFrontmatter): Record<string, MissionPhaseProgressEntry>;
+/**
+ * Move a closed mission's ground roadmap dir + per-clone runtime dir
+ * under their respective `_done/` archives. Idempotent on already-
+ * archived missions (returns false).
+ */
+export declare function archiveMission(repoRoot: string, missionId: string): boolean;
+/**
+ * Reverse of `archiveMission` — move the mission's archived dirs back
+ * into the live locations. Returns false if neither archive is
+ * present.
+ */
+export declare function restoreMission(repoRoot: string, missionId: string): boolean;
+/**
+ * Locate a mission id whether it's live or archived. Returns the
+ * matching scope so callers can decide to read from `_done` paths.
+ */
+export declare function locateMission(repoRoot: string, missionId: string): "active" | "done" | null;
+/**
+ * Re-parse the live roadmap and return phase ids the mission's current
+ * `phase_progress` references that no longer appear in roadmap.md.
+ * These are the `mission_drift` candidates — phases the operator
+ * deleted from the roadmap mid-mission. Empty array on no drift.
+ */
+export declare function detectRoadmapDrift(roadmap: MissionRoadmapFrontmatter, state: MissionState): string[];
+/**
+ * Slice the per-clone spec.md by phase heading. Returns the body text
+ * under the `## <phase title>` heading or `## <phase id>` heading,
+ * stopping at the next `##` heading. Returns null if no slice matches.
+ *
+ * Used by cairn_mission_resume to prime fresh chats with only the
+ * relevant phase section instead of the whole spec doc.
+ */
+export declare function slicePhaseSection(spec: string, phase: MissionPhase): string | null;

package/dist/missions.js

@@ -0,0 +1,414 @@
+/**
+ * Mission-system I/O — schema-validated reads + writes for the
+ * mission surfaces: `.cairn/ground/missions/<id>/roadmap.md`
+ * (committed) and `.cairn/missions/<id>/{state.json,spec.md,journal.jsonl}`
+ * (per-clone).
+ *
+ * Pure low-level I/O; no MCP, no hooks, no LLM calls. The MCP layer in
+ * `cairn-core` composes these primitives into the operator-facing
+ * `cairn_mission_*` tools.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { parseFrontmatterRecord } from "./frontmatter.js";
+import { missionBriefPath, missionGroundDir, missionRoadmapPath, missionRuntimeDir, missionSpecPath, missionStatePath, missionJournalPath, missionsGroundDoneRoot, missionsGroundRoot, missionsRuntimeDoneRoot, missionsRuntimeRoot, } from "./paths.js";
+import { MissionPhaseBrief, MissionRoadmapFrontmatter, MissionState, } from "./schemas.js";
+/* -------------------------------------------------------------------------- */
+/* Roadmap (committed `.cairn/ground/missions/<id>/roadmap.md`)               */
+/* -------------------------------------------------------------------------- */
+/**
+ * Parse a roadmap.md source string into validated frontmatter + prose
+ * body. Throws when frontmatter is missing or fails schema validation —
+ * roadmap.md is the contract; an unreadable roadmap is a hard error,
+ * not a soft fallback.
+ */
+export function parseRoadmap(source) {
+    const { fm, body } = parseFrontmatterRecord(source);
+    if (Object.keys(fm).length === 0) {
+        throw new Error("roadmap.md is missing frontmatter");
+    }
+    const result = MissionRoadmapFrontmatter.safeParse(fm);
+    if (!result.success) {
+        throw new Error(`roadmap.md frontmatter invalid: ${result.error.message}`);
+    }
+    return { frontmatter: result.data, prose: body };
+}
+export function serializeRoadmap(frontmatter, prose = "") {
+    const yaml = stringifyYaml(frontmatter);
+    const trimmedProse = prose.replace(/^\n+/, "");
+    return `---\n${yaml}---\n\n${trimmedProse}`;
+}
+export function readRoadmap(repoRoot, missionId) {
+    const path = missionRoadmapPath(repoRoot, missionId);
+    if (!existsSync(path))
+        return null;
+    const source = readFileSync(path, "utf8");
+    return parseRoadmap(source);
+}
+export function writeRoadmap(repoRoot, missionId, frontmatter, prose = "") {
+    const path = missionRoadmapPath(repoRoot, missionId);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serializeRoadmap(frontmatter, prose), "utf8");
+}
+export function parsePhaseBrief(source) {
+    const { fm, body } = parseFrontmatterRecord(source);
+    if (Object.keys(fm).length === 0) {
+        throw new Error("phase brief is missing frontmatter");
+    }
+    const result = MissionPhaseBrief.safeParse(fm);
+    if (!result.success) {
+        throw new Error(`phase brief frontmatter invalid: ${result.error.message}`);
+    }
+    return { frontmatter: result.data, prose: body };
+}
+/**
+ * Render a human-readable brief: YAML frontmatter (the canonical
+ * machine surface) plus a mirrored markdown body so the file reads
+ * cleanly in a diff or editor. The body is derived from the frontmatter
+ * on every write — it is never the source of truth.
+ */
+export function serializePhaseBrief(brief, prose = "") {
+    const yaml = stringifyYaml(brief);
+    const sections = [`# Phase brief — ${brief.phase_id}`, ""];
+    if (brief.decisions.length > 0) {
+        sections.push("## Decisions", "");
+        for (const d of brief.decisions) {
+            sections.push(`- **${d.question}** → ${d.choice}${d.rationale ? ` _(${d.rationale})_` : ""}`);
+        }
+        sections.push("");
+    }
+    if (brief.constraints.length > 0) {
+        sections.push("## Constraints", "");
+        for (const c of brief.constraints)
+            sections.push(`- ${c}`);
+        sections.push("");
+    }
+    if (brief.acceptance.length > 0) {
+        sections.push("## Acceptance", "");
+        for (const a of brief.acceptance)
+            sections.push(`- ${a}`);
+        sections.push("");
+    }
+    const cites = [...brief.cite_decisions, ...brief.cite_invariants];
+    if (cites.length > 0) {
+        sections.push("## In-scope ground state", "");
+        sections.push(cites.map((c) => `\`${c}\``).join(" · "));
+        sections.push("");
+    }
+    const extraProse = prose.replace(/^\n+/, "").trimEnd();
+    const body = extraProse.length > 0
+        ? `${sections.join("\n")}\n${extraProse}\n`
+        : `${sections.join("\n")}\n`;
+    return `---\n${yaml}---\n\n${body}`;
+}
+export function readPhaseBrief(repoRoot, missionId, phaseId) {
+    const path = missionBriefPath(repoRoot, missionId, phaseId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return parsePhaseBrief(readFileSync(path, "utf8")).frontmatter;
+    }
+    catch {
+        return null;
+    }
+}
+export function writePhaseBrief(repoRoot, missionId, brief, prose = "") {
+    const path = missionBriefPath(repoRoot, missionId, brief.phase_id);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serializePhaseBrief(brief, prose), "utf8");
+}
+/* -------------------------------------------------------------------------- */
+/* Mission state (per-clone `.cairn/missions/<id>/state.json`)                */
+/* -------------------------------------------------------------------------- */
+export function readMissionState(repoRoot, missionId) {
+    const path = missionStatePath(repoRoot, missionId);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const result = MissionState.safeParse(parsed);
+    return result.success ? result.data : null;
+}
+export function writeMissionState(repoRoot, missionId, state) {
+    const path = missionStatePath(repoRoot, missionId);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+/* -------------------------------------------------------------------------- */
+/* Spec snapshot (per-clone `.cairn/missions/<id>/spec.md`)                   */
+/* -------------------------------------------------------------------------- */
+export function readMissionSpec(repoRoot, missionId) {
+    const path = missionSpecPath(repoRoot, missionId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function writeMissionSpec(repoRoot, missionId, source) {
+    const path = missionSpecPath(repoRoot, missionId);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, source, "utf8");
+}
+/* -------------------------------------------------------------------------- */
+/* Mission journal (per-clone `.cairn/missions/<id>/journal.jsonl`)           */
+/* -------------------------------------------------------------------------- */
+export function appendMissionJournal(repoRoot, missionId, entry) {
+    const path = missionJournalPath(repoRoot, missionId);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + "\n", "utf8");
+}
+export function readMissionJournal(repoRoot, missionId) {
+    const path = missionJournalPath(repoRoot, missionId);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed === "object" && parsed !== null && typeof parsed.ts === "string") {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return out;
+}
+/* -------------------------------------------------------------------------- */
+/* Discovery + cursor helpers                                                 */
+/* -------------------------------------------------------------------------- */
+function listMissionsIn(rootDir) {
+    if (!existsSync(rootDir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(rootDir, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && e.name.startsWith("MIS-"))
+        .map((e) => e.name);
+}
+/** Mission ids present in `.cairn/ground/missions/` (excluding `_done`). */
+export function listActiveMissionIds(repoRoot) {
+    return listMissionsIn(missionsGroundRoot(repoRoot));
+}
+/** Mission ids present in `.cairn/ground/missions/_done/`. */
+export function listDoneMissionIds(repoRoot) {
+    return listMissionsIn(missionsGroundDoneRoot(repoRoot));
+}
+/**
+ * Find the single active mission id for this clone, if any. v1 enforces
+ * one active mission per repo. When multiple mission dirs exist,
+ * returns the one whose state.json reports `outcome: active` and a
+ * non-null `cursor.active_phase`. Falls back to the lexically first
+ * active id when ambiguous; mismatch is a state corruption operators
+ * surface via `cairn doctor`.
+ */
+export function findActiveMission(repoRoot) {
+    const ids = listActiveMissionIds(repoRoot);
+    for (const id of ids) {
+        const state = readMissionState(repoRoot, id);
+        if (state === null)
+            continue;
+        if (state.outcome === "active")
+            return id;
+    }
+    return null;
+}
+/**
+ * Resolve the effective exit gate for a phase: per-phase override on the
+ * roadmap entry takes precedence, falls through to the mission-level
+ * `frontmatter.exit_gate`.
+ */
+export function effectivePhaseExitGate(roadmap, phaseId) {
+    const phase = roadmap.phases.find((p) => p.id === phaseId);
+    if (phase === undefined)
+        return null;
+    return phase.exit_gate ?? roadmap.exit_gate;
+}
+/**
+ * Compute the next pending phase whose `depends_on` set is fully
+ * satisfied (all listed phases sit at `state: done` in
+ * `phase_progress`). Returns null when no eligible phase exists —
+ * either every phase is done, or all remaining are blocked by
+ * unresolved dependencies (which is a soft conflict surfaced as
+ * mission_drift).
+ *
+ * Walks roadmap order; the first eligible pending phase wins. Operators
+ * can re-order phases by hand-editing roadmap.md.
+ */
+export function nextPendingPhase(roadmap, state) {
+    for (const phase of roadmap.phases) {
+        const progress = state.phase_progress[phase.id];
+        const phaseState = progress?.state ?? "pending";
+        if (phaseState !== "pending")
+            continue;
+        const depsSatisfied = phase.depends_on.every((dep) => {
+            const depProgress = state.phase_progress[dep];
+            return depProgress?.state === "done";
+        });
+        if (depsSatisfied)
+            return phase;
+    }
+    return null;
+}
+/**
+ * Number of phases at `state: done`. Used by statusline `(N/M)` and the
+ * SessionStart cursor banner.
+ */
+export function countDonePhases(state) {
+    let n = 0;
+    for (const entry of Object.values(state.phase_progress)) {
+        if (entry.state === "done")
+            n += 1;
+    }
+    return n;
+}
+/**
+ * Initial empty `phase_progress` map for a fresh mission — every
+ * roadmap phase id present at `state: pending` with no task_ids.
+ */
+export function initialPhaseProgress(roadmap) {
+    const out = {};
+    for (const phase of roadmap.phases) {
+        out[phase.id] = { state: "pending", task_ids: [] };
+    }
+    return out;
+}
+/* -------------------------------------------------------------------------- */
+/* Archive / restore                                                          */
+/* -------------------------------------------------------------------------- */
+/**
+ * Move a closed mission's ground roadmap dir + per-clone runtime dir
+ * under their respective `_done/` archives. Idempotent on already-
+ * archived missions (returns false).
+ */
+export function archiveMission(repoRoot, missionId) {
+    const groundFrom = missionGroundDir(repoRoot, missionId);
+    const runtimeFrom = missionRuntimeDir(repoRoot, missionId);
+    let moved = false;
+    if (existsSync(groundFrom)) {
+        const dest = `${missionsGroundDoneRoot(repoRoot)}/${missionId}`;
+        mkdirSync(missionsGroundDoneRoot(repoRoot), { recursive: true });
+        renameSync(groundFrom, dest);
+        moved = true;
+    }
+    if (existsSync(runtimeFrom)) {
+        const dest = `${missionsRuntimeDoneRoot(repoRoot)}/${missionId}`;
+        mkdirSync(missionsRuntimeDoneRoot(repoRoot), { recursive: true });
+        renameSync(runtimeFrom, dest);
+        moved = true;
+    }
+    return moved;
+}
+/**
+ * Reverse of `archiveMission` — move the mission's archived dirs back
+ * into the live locations. Returns false if neither archive is
+ * present.
+ */
+export function restoreMission(repoRoot, missionId) {
+    const groundFrom = `${missionsGroundDoneRoot(repoRoot)}/${missionId}`;
+    const runtimeFrom = `${missionsRuntimeDoneRoot(repoRoot)}/${missionId}`;
+    let moved = false;
+    if (existsSync(groundFrom)) {
+        mkdirSync(missionsGroundRoot(repoRoot), { recursive: true });
+        renameSync(groundFrom, missionGroundDir(repoRoot, missionId));
+        moved = true;
+    }
+    if (existsSync(runtimeFrom)) {
+        mkdirSync(missionsRuntimeRoot(repoRoot), { recursive: true });
+        renameSync(runtimeFrom, missionRuntimeDir(repoRoot, missionId));
+        moved = true;
+    }
+    return moved;
+}
+/**
+ * Locate a mission id whether it's live or archived. Returns the
+ * matching scope so callers can decide to read from `_done` paths.
+ */
+export function locateMission(repoRoot, missionId) {
+    if (existsSync(missionGroundDir(repoRoot, missionId)))
+        return "active";
+    if (existsSync(`${missionsGroundDoneRoot(repoRoot)}/${missionId}`))
+        return "done";
+    return null;
+}
+/* -------------------------------------------------------------------------- */
+/* Validation helpers                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Re-parse the live roadmap and return phase ids the mission's current
+ * `phase_progress` references that no longer appear in roadmap.md.
+ * These are the `mission_drift` candidates — phases the operator
+ * deleted from the roadmap mid-mission. Empty array on no drift.
+ */
+export function detectRoadmapDrift(roadmap, state) {
+    const liveIds = new Set(roadmap.phases.map((p) => p.id));
+    return Object.keys(state.phase_progress).filter((id) => !liveIds.has(id));
+}
+/**
+ * Slice the per-clone spec.md by phase heading. Returns the body text
+ * under the `## <phase title>` heading or `## <phase id>` heading,
+ * stopping at the next `##` heading. Returns null if no slice matches.
+ *
+ * Used by cairn_mission_resume to prime fresh chats with only the
+ * relevant phase section instead of the whole spec doc.
+ */
+export function slicePhaseSection(spec, phase) {
+    const lines = spec.split(/\r?\n/);
+    const matchTitles = [phase.title, phase.id]
+        .filter((s) => s.length > 0)
+        .map((s) => s.toLowerCase());
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i]?.match(/^##\s+(.+?)\s*$/);
+        if (m === null || m === undefined)
+            continue;
+        const heading = (m[1] ?? "").toLowerCase();
+        if (matchTitles.some((t) => heading.includes(t))) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (lines[i]?.match(/^##\s+/)) {
+            end = i;
+            break;
+        }
+    }
+    return lines.slice(start, end).join("\n").trim();
+}
+//# sourceMappingURL=missions.js.map