cclaw-cli 0.46.7 → 0.46.9

package/dist/runs.js

@@ -1,710 +1,2 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
-import { canTransition, createInitialCloseoutState, createInitialFlowState, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
-import { ensureFeatureSystem, readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.js";
-import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
-export class InvalidStageTransitionError extends Error {
-    from;
-    to;
-    constructor(from, to, message) {
-        super(message);
-        this.from = from;
-        this.to = to;
-        this.name = "InvalidStageTransitionError";
-    }
-}
-function validateFlowTransition(prev, next) {
-    if (prev.activeRunId !== next.activeRunId) {
-        // New run — only reset paths may change the runId, but those set allowReset.
-        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change activeRunId from "${prev.activeRunId}" to "${next.activeRunId}" without allowReset.`);
-    }
-    for (const completed of prev.completedStages) {
-        if (!next.completedStages.includes(completed)) {
-            throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage "${completed}" was previously completed but is missing from the new state.`);
-        }
-    }
-    if (prev.currentStage === next.currentStage) {
-        return;
-    }
-    if (!canTransition(prev.currentStage, next.currentStage)) {
-        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `no transition rule allows "${prev.currentStage}" -> "${next.currentStage}". Use /cc-next to advance stages or archive the run to reset.`);
-    }
-}
-const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
-const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
-const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
-const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
-const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
-/** State filenames explicitly excluded from the archive snapshot. */
-const STATE_SNAPSHOT_EXCLUDE = new Set([
-    ".flow-state.lock",
-    ".delegation.lock"
-]);
-function flowStatePath(projectRoot) {
-    return path.join(projectRoot, FLOW_STATE_REL_PATH);
-}
-function flowStateLockPath(projectRoot) {
-    return path.join(projectRoot, RUNTIME_ROOT, "state", ".flow-state.lock");
-}
-function runsRoot(projectRoot) {
-    return path.join(projectRoot, RUNS_DIR_REL_PATH);
-}
-function activeArtifactsPath(projectRoot) {
-    return path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH);
-}
-function stateDirPath(projectRoot) {
-    return path.join(projectRoot, STATE_DIR_REL_PATH);
-}
-async function snapshotStateDirectory(projectRoot, destinationRoot) {
-    const sourceDir = stateDirPath(projectRoot);
-    if (!(await exists(sourceDir))) {
-        return [];
-    }
-    await ensureDir(destinationRoot);
-    const copied = [];
-    let entries;
-    try {
-        entries = await fs.readdir(sourceDir, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    for (const entry of entries) {
-        if (STATE_SNAPSHOT_EXCLUDE.has(entry.name))
-            continue;
-        if (entry.name.startsWith(".") && !entry.name.endsWith(".json"))
-            continue;
-        const from = path.join(sourceDir, entry.name);
-        const to = path.join(destinationRoot, entry.name);
-        try {
-            if (entry.isDirectory()) {
-                await fs.cp(from, to, { recursive: true });
-                copied.push(`${entry.name}/`);
-            }
-            else if (entry.isFile()) {
-                await fs.copyFile(from, to);
-                copied.push(entry.name);
-            }
-        }
-        catch {
-            // best-effort snapshot; continue on individual failures
-        }
-    }
-    return copied.sort((a, b) => a.localeCompare(b));
-}
-function isFlowStage(value) {
-    return typeof value === "string" && FLOW_STAGE_SET.has(value);
-}
-function sanitizeStringArray(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
-}
-function sanitizeCompletedStages(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    const unique = new Set();
-    const stages = [];
-    for (const item of value) {
-        if (isFlowStage(item) && !unique.has(item)) {
-            unique.add(item);
-            stages.push(item);
-        }
-    }
-    return stages;
-}
-function sanitizeGuardEvidence(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return {};
-    }
-    const next = {};
-    for (const [key, raw] of Object.entries(value)) {
-        if (typeof raw === "string") {
-            next[key] = raw;
-        }
-    }
-    return next;
-}
-function sanitizeStageGateCatalog(value, fallback) {
-    const uniqueStrings = (items) => [...new Set(items)];
-    const next = {};
-    for (const stage of COMMAND_FILE_ORDER) {
-        const base = fallback[stage];
-        next[stage] = {
-            required: [...base.required],
-            recommended: [...base.recommended],
-            conditional: [...base.conditional],
-            triggered: [...base.triggered],
-            passed: [...base.passed],
-            blocked: [...base.blocked]
-        };
-    }
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return next;
-    }
-    const rawCatalog = value;
-    for (const stage of COMMAND_FILE_ORDER) {
-        const rawStage = rawCatalog[stage];
-        if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
-            continue;
-        }
-        const typed = rawStage;
-        const stageState = next[stage];
-        const allowedGateIds = new Set([
-            ...stageState.required,
-            ...stageState.recommended,
-            ...stageState.conditional
-        ]);
-        const conditionalGateIds = new Set(stageState.conditional);
-        const passed = sanitizeStringArray(typed.passed).filter((gate) => allowedGateIds.has(gate));
-        const blocked = sanitizeStringArray(typed.blocked).filter((gate) => allowedGateIds.has(gate));
-        const triggeredFromState = sanitizeStringArray(typed.triggered).filter((gate) => conditionalGateIds.has(gate));
-        const touchedConditionals = [...passed, ...blocked].filter((gate) => conditionalGateIds.has(gate));
-        next[stage] = {
-            required: [...stageState.required],
-            recommended: [...stageState.recommended],
-            conditional: [...stageState.conditional],
-            triggered: uniqueStrings([...triggeredFromState, ...touchedConditionals]),
-            passed,
-            blocked
-        };
-    }
-    return next;
-}
-function coerceTrack(value) {
-    return isFlowTrack(value) ? value : "standard";
-}
-function sanitizeSkippedStages(value, track) {
-    const trackDefault = skippedStagesForTrack(track);
-    if (!Array.isArray(value)) {
-        return trackDefault;
-    }
-    const seen = new Set();
-    const out = [];
-    for (const raw of value) {
-        if (isFlowStage(raw) && !seen.has(raw)) {
-            seen.add(raw);
-            out.push(raw);
-        }
-    }
-    return out.length > 0 ? out : trackDefault;
-}
-function sanitizeStaleStages(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return {};
-    }
-    const out = {};
-    for (const [stage, raw] of Object.entries(value)) {
-        if (!isFlowStage(stage))
-            continue;
-        if (!raw || typeof raw !== "object" || Array.isArray(raw))
-            continue;
-        const typed = raw;
-        const rewindId = typeof typed.rewindId === "string" ? typed.rewindId : "";
-        const reason = typeof typed.reason === "string" ? typed.reason : "";
-        const markedAt = typeof typed.markedAt === "string" ? typed.markedAt : "";
-        const acknowledgedAt = typeof typed.acknowledgedAt === "string" ? typed.acknowledgedAt : undefined;
-        if (!rewindId || !reason || !markedAt) {
-            continue;
-        }
-        out[stage] = {
-            rewindId,
-            reason,
-            markedAt,
-            acknowledgedAt
-        };
-    }
-    return out;
-}
-function sanitizeRewinds(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    const out = [];
-    for (const raw of value) {
-        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-            continue;
-        }
-        const typed = raw;
-        if (typeof typed.id !== "string" ||
-            !isFlowStage(typed.fromStage) ||
-            !isFlowStage(typed.toStage) ||
-            typeof typed.reason !== "string" ||
-            typeof typed.timestamp !== "string") {
-            continue;
-        }
-        const invalidatedStages = Array.isArray(typed.invalidatedStages)
-            ? typed.invalidatedStages.filter((stage) => isFlowStage(stage))
-            : [];
-        out.push({
-            id: typed.id,
-            fromStage: typed.fromStage,
-            toStage: typed.toStage,
-            reason: typed.reason,
-            timestamp: typed.timestamp,
-            invalidatedStages
-        });
-    }
-    return out;
-}
-function sanitizeRetroState(value) {
-    const fallback = {
-        required: false,
-        completedAt: undefined,
-        compoundEntries: 0
-    };
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return fallback;
-    }
-    const typed = value;
-    const required = typeof typed.required === "boolean" ? typed.required : false;
-    const completedAt = typeof typed.completedAt === "string" ? typed.completedAt : undefined;
-    const compoundEntriesRaw = typed.compoundEntries;
-    const compoundEntries = typeof compoundEntriesRaw === "number" && Number.isFinite(compoundEntriesRaw) && compoundEntriesRaw >= 0
-        ? Math.floor(compoundEntriesRaw)
-        : 0;
-    return {
-        required,
-        completedAt,
-        compoundEntries
-    };
-}
-function isShipSubstate(value) {
-    return typeof value === "string" && SHIP_SUBSTATES.includes(value);
-}
-function sanitizeCloseoutState(value) {
-    const fallback = createInitialCloseoutState();
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return fallback;
-    }
-    const typed = value;
-    const shipSubstate = isShipSubstate(typed.shipSubstate) ? typed.shipSubstate : fallback.shipSubstate;
-    const retroDraftedAt = typeof typed.retroDraftedAt === "string" ? typed.retroDraftedAt : undefined;
-    const retroAcceptedAt = typeof typed.retroAcceptedAt === "string" ? typed.retroAcceptedAt : undefined;
-    const retroSkipped = typeof typed.retroSkipped === "boolean" ? typed.retroSkipped : undefined;
-    const retroSkipReason = typeof typed.retroSkipReason === "string" ? typed.retroSkipReason : undefined;
-    const compoundCompletedAt = typeof typed.compoundCompletedAt === "string" ? typed.compoundCompletedAt : undefined;
-    const compoundSkipped = typeof typed.compoundSkipped === "boolean" ? typed.compoundSkipped : undefined;
-    const promotedRaw = typed.compoundPromoted;
-    const compoundPromoted = typeof promotedRaw === "number" && Number.isFinite(promotedRaw) && promotedRaw >= 0
-        ? Math.floor(promotedRaw)
-        : 0;
-    return {
-        shipSubstate,
-        retroDraftedAt,
-        retroAcceptedAt,
-        retroSkipped,
-        retroSkipReason,
-        compoundCompletedAt,
-        compoundSkipped,
-        compoundPromoted
-    };
-}
-function coerceFlowState(parsed) {
-    const track = coerceTrack(parsed.track);
-    const next = createInitialFlowState("active", track);
-    const activeRunIdRaw = parsed.activeRunId;
-    const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
-        ? activeRunIdRaw.trim()
-        : next.activeRunId;
-    return {
-        activeRunId,
-        currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
-        completedStages: sanitizeCompletedStages(parsed.completedStages),
-        guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
-        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog),
-        track,
-        skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
-        staleStages: sanitizeStaleStages(parsed.staleStages),
-        rewinds: sanitizeRewinds(parsed.rewinds),
-        retro: sanitizeRetroState(parsed.retro),
-        closeout: sanitizeCloseoutState(parsed.closeout)
-    };
-}
-function toArchiveDate(date = new Date()) {
-    const yyyy = date.getFullYear().toString();
-    const mm = (date.getMonth() + 1).toString().padStart(2, "0");
-    const dd = date.getDate().toString().padStart(2, "0");
-    return `${yyyy}-${mm}-${dd}`;
-}
-function slugifyFeatureName(value) {
-    const slug = value
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/gu, "-")
-        .replace(/^-+/u, "")
-        .replace(/-+$/u, "");
-    if (slug.length === 0) {
-        return "feature";
-    }
-    return slug.slice(0, 64);
-}
-async function inferFeatureNameFromArtifacts(projectRoot) {
-    const ideaPath = path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH, "00-idea.md");
-    if (!(await exists(ideaPath))) {
-        return "feature";
-    }
-    try {
-        const raw = await fs.readFile(ideaPath, "utf8");
-        const firstMeaningful = raw
-            .split(/\r?\n/gu)
-            .map((line) => line.trim())
-            .find((line) => line.length > 0);
-        if (!firstMeaningful) {
-            return "feature";
-        }
-        return firstMeaningful.replace(/^[-#*\s]+/u, "").trim() || "feature";
-    }
-    catch {
-        return "feature";
-    }
-}
-async function uniqueArchiveId(projectRoot, baseId) {
-    let index = 1;
-    let candidate = baseId;
-    while (await exists(path.join(runsRoot(projectRoot), candidate))) {
-        index += 1;
-        candidate = `${baseId}-${index}`;
-    }
-    return candidate;
-}
-function retroArtifactPath(projectRoot) {
-    return path.join(activeArtifactsPath(projectRoot), "09-retro.md");
-}
-function parseIsoTimestamp(value) {
-    if (!value || value.trim().length === 0)
-        return null;
-    const parsed = Date.parse(value);
-    return Number.isFinite(parsed) ? parsed : null;
-}
-function inInclusiveWindow(timestamp, windowStartMs, windowEndMs) {
-    if (windowStartMs !== null && timestamp < windowStartMs)
-        return false;
-    if (windowEndMs !== null && timestamp > windowEndMs)
-        return false;
-    return true;
-}
-async function evaluateRetroGate(projectRoot, state) {
-    const required = state.completedStages.includes("ship");
-    const artifactFile = retroArtifactPath(projectRoot);
-    let hasRetroArtifact = false;
-    if (await exists(artifactFile)) {
-        try {
-            const raw = await fs.readFile(artifactFile, "utf8");
-            hasRetroArtifact = raw.trim().length > 0;
-        }
-        catch {
-            hasRetroArtifact = false;
-        }
-    }
-    let compoundEntries = state.retro.compoundEntries;
-    const windowStartMs = parseIsoTimestamp(state.closeout.retroDraftedAt);
-    const windowEndMs = parseIsoTimestamp(state.closeout.retroAcceptedAt) ?? parseIsoTimestamp(state.retro.completedAt);
-    const shouldFallbackScan = compoundEntries <= 0 && (windowStartMs !== null || windowEndMs !== null);
-    const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
-    if (shouldFallbackScan && (await exists(knowledgeFile))) {
-        try {
-            const raw = await fs.readFile(knowledgeFile, "utf8");
-            compoundEntries = 0;
-            for (const line of raw.split(/\r?\n/)) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                try {
-                    const parsed = JSON.parse(trimmed);
-                    if (parsed.type !== "compound") {
-                        continue;
-                    }
-                    const created = typeof parsed.created === "string" ? parseIsoTimestamp(parsed.created) : null;
-                    if (created === null || !inInclusiveWindow(created, windowStartMs, windowEndMs)) {
-                        continue;
-                    }
-                    const source = typeof parsed.source === "string"
-                        ? parsed.source.trim().toLowerCase()
-                        : null;
-                    const legacyRetroStage = parsed.stage === "retro";
-                    if (source === "retro" || legacyRetroStage) {
-                        compoundEntries += 1;
-                    }
-                }
-                catch {
-                    // ignore malformed lines for retro gate calculation
-                }
-            }
-        }
-        catch {
-            compoundEntries = 0;
-        }
-    }
-    const completed = required ? (hasRetroArtifact && compoundEntries > 0) : true;
-    return {
-        required,
-        completed,
-        compoundEntries,
-        hasRetroArtifact
-    };
-}
-export class CorruptFlowStateError extends Error {
-    statePath;
-    quarantinedPath;
-    constructor(statePath, quarantinedPath, cause) {
-        super(`Corrupt flow-state.json detected at ${statePath}. ` +
-            `Quarantined to ${quarantinedPath}. ` +
-            `Inspect the quarantined file, reconcile by hand, then re-run your command ` +
-            `or delete ${statePath} to start over. ` +
-            `Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`);
-        this.name = "CorruptFlowStateError";
-        this.statePath = statePath;
-        this.quarantinedPath = quarantinedPath;
-        if (cause instanceof Error) {
-            this.cause = cause;
-        }
-    }
-}
-function quarantineTimestamp(date = new Date()) {
-    return date.toISOString().replace(/[:.]/gu, "-");
-}
-async function quarantineCorruptState(statePath, cause) {
-    const quarantinedPath = `${statePath}.corrupt-${quarantineTimestamp()}.json`;
-    try {
-        await fs.rename(statePath, quarantinedPath);
-    }
-    catch (renameErr) {
-        try {
-            const raw = await fs.readFile(statePath, "utf8");
-            await fs.writeFile(quarantinedPath, raw, "utf8");
-            await fs.unlink(statePath).catch(() => undefined);
-        }
-        catch {
-            throw new CorruptFlowStateError(statePath, quarantinedPath, renameErr);
-        }
-    }
-    throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
-}
-export async function readFlowState(projectRoot) {
-    await ensureFeatureSystem(projectRoot);
-    const statePath = flowStatePath(projectRoot);
-    if (!(await exists(statePath))) {
-        return createInitialFlowState();
-    }
-    let raw;
-    try {
-        raw = await fs.readFile(statePath, "utf8");
-    }
-    catch (readErr) {
-        throw new CorruptFlowStateError(statePath, statePath, readErr);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (parseErr) {
-        await quarantineCorruptState(statePath, parseErr);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        await quarantineCorruptState(statePath, new Error("flow-state.json did not deserialize to a JSON object"));
-    }
-    return coerceFlowState(parsed);
-}
-export async function writeFlowState(projectRoot, state, options = {}) {
-    await ensureFeatureSystem(projectRoot);
-    await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
-        const statePath = flowStatePath(projectRoot);
-        if (!options.allowReset && (await exists(statePath))) {
-            try {
-                const raw = await fs.readFile(statePath, "utf8");
-                const parsed = JSON.parse(raw);
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    const prev = coerceFlowState(parsed);
-                    validateFlowTransition(prev, state);
-                }
-            }
-            catch (err) {
-                if (err instanceof InvalidStageTransitionError) {
-                    throw err;
-                }
-                // A corrupt prior file is surfaced by readFlowState elsewhere; don't
-                // block a legitimate write attempt on parse errors here.
-            }
-        }
-        const safe = coerceFlowState({ ...state });
-        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`);
-    });
-    await syncActiveFeatureSnapshot(projectRoot);
-}
-export async function ensureRunSystem(projectRoot, _options = {}) {
-    await ensureFeatureSystem(projectRoot);
-    await ensureDir(runsRoot(projectRoot));
-    await ensureDir(activeArtifactsPath(projectRoot));
-    const statePath = flowStatePath(projectRoot);
-    const state = await readFlowState(projectRoot);
-    if (!(await exists(statePath))) {
-        await writeFlowState(projectRoot, state, { allowReset: true });
-    }
-    await syncActiveFeatureSnapshot(projectRoot);
-    return state;
-}
-export async function listRuns(projectRoot) {
-    const root = runsRoot(projectRoot);
-    if (!(await exists(root))) {
-        return [];
-    }
-    const entries = await fs.readdir(root, { withFileTypes: true });
-    const runs = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory()) {
-            continue;
-        }
-        const runPath = path.join(root, entry.name);
-        let createdAt = new Date().toISOString();
-        try {
-            const stat = await fs.stat(runPath);
-            createdAt = stat.birthtime?.toISOString?.() ?? stat.mtime.toISOString();
-        }
-        catch {
-            // keep fallback timestamp
-        }
-        runs.push({
-            id: entry.name,
-            title: entry.name,
-            createdAt
-        });
-    }
-    return runs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-}
-export async function archiveRun(projectRoot, featureName, options = {}) {
-    await ensureRunSystem(projectRoot);
-    const activeFeature = await readActiveFeature(projectRoot);
-    const artifactsDir = activeArtifactsPath(projectRoot);
-    const runsDir = runsRoot(projectRoot);
-    await ensureDir(runsDir);
-    await ensureDir(artifactsDir);
-    const feature = (featureName?.trim() && featureName.trim().length > 0)
-        ? featureName.trim()
-        : await inferFeatureNameFromArtifacts(projectRoot);
-    const archiveBaseId = `${toArchiveDate()}-${slugifyFeatureName(feature)}`;
-    const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
-    const archivePath = path.join(runsDir, archiveId);
-    const archiveArtifactsPath = path.join(archivePath, "artifacts");
-    let sourceState = await readFlowState(projectRoot);
-    const retroGate = await evaluateRetroGate(projectRoot, sourceState);
-    const shipCompleted = sourceState.completedStages.includes("ship");
-    const skipRetro = options.skipRetro === true;
-    const skipRetroReason = options.skipRetroReason?.trim();
-    if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
-        throw new Error("archive --skip-retro requires --retro-reason=<text>.");
-    }
-    const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
-        typeof sourceState.closeout.retroSkipReason === "string" &&
-        sourceState.closeout.retroSkipReason.trim().length > 0;
-    const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
-    if (shipCompleted && !readyForArchive && !skipRetro) {
-        throw new Error("Archive blocked: closeout is not ready_to_archive. " +
-            "Resume /cc-next until closeout reaches ready_to_archive, " +
-            "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
-    }
-    if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
-        throw new Error("Archive blocked: retro gate is required after ship completion. " +
-            "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
-    }
-    if (retroGate.completed) {
-        const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();
-        sourceState = {
-            ...sourceState,
-            retro: {
-                required: retroGate.required,
-                completedAt,
-                compoundEntries: retroGate.compoundEntries
-            }
-        };
-        await writeFlowState(projectRoot, sourceState, { allowReset: true });
-    }
-    const retroSummary = {
-        required: retroGate.required,
-        completed: retroGate.completed,
-        skipped: skipRetro || retroSkippedInCloseout,
-        skipReason: skipRetro
-            ? skipRetroReason
-            : retroSkippedInCloseout
-                ? sourceState.closeout.retroSkipReason
-                : undefined,
-        compoundEntries: retroGate.compoundEntries
-    };
-    await ensureDir(archivePath);
-    await fs.rename(artifactsDir, archiveArtifactsPath);
-    await ensureDir(artifactsDir);
-    const archiveStatePath = path.join(archivePath, "state");
-    const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
-    const resetState = createInitialFlowState();
-    await writeFlowState(projectRoot, resetState, { allowReset: true });
-    const archivedAt = new Date().toISOString();
-    const manifest = {
-        version: 1,
-        archiveId,
-        archivedAt,
-        featureName: feature,
-        activeFeature,
-        sourceRunId: sourceState.activeRunId,
-        sourceCurrentStage: sourceState.currentStage,
-        sourceCompletedStages: sourceState.completedStages,
-        snapshottedStateFiles,
-        retro: retroSummary
-    };
-    await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-    const knowledgeStats = await readKnowledgeStats(projectRoot);
-    await syncActiveFeatureSnapshot(projectRoot);
-    return {
-        archiveId,
-        archivePath,
-        archivedAt,
-        featureName: feature,
-        activeFeature,
-        resetState,
-        snapshottedStateFiles,
-        knowledge: knowledgeStats,
-        retro: retroSummary
-    };
-}
-const KNOWLEDGE_SOFT_THRESHOLD = 50;
-async function readKnowledgeStats(projectRoot) {
-    const knowledgePath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
-    let activeEntryCount = 0;
-    if (await exists(knowledgePath)) {
-        const text = await fs.readFile(knowledgePath, "utf8");
-        activeEntryCount = countActiveKnowledgeEntries(text);
-    }
-    return {
-        activeEntryCount,
-        softThreshold: KNOWLEDGE_SOFT_THRESHOLD,
-        overThreshold: activeEntryCount > KNOWLEDGE_SOFT_THRESHOLD,
-        knowledgePath: `${RUNTIME_ROOT}/knowledge.jsonl`
-    };
-}
-/**
- * Counts entries in the canonical JSONL knowledge store. An "active" entry is one
- * non-empty line that parses as JSON with the required `type` field belonging to the
- * allowed set. Malformed lines are ignored (not counted) but do not throw so that a
- * hand-edited file cannot break doctor/archive flows.
- */
-export function countActiveKnowledgeEntries(text) {
-    const allowed = new Set(["rule", "pattern", "lesson", "compound"]);
-    let count = 0;
-    for (const raw of text.split(/\r?\n/)) {
-        const line = raw.trim();
-        if (line.length === 0)
-            continue;
-        try {
-            const parsed = JSON.parse(line);
-            if (typeof parsed.type === "string" && allowed.has(parsed.type)) {
-                count += 1;
-            }
-        }
-        catch {
-            // Skip malformed lines silently; curation surfaces them separately.
-        }
-    }
-    return count;
-}
+export { CorruptFlowStateError, InvalidStageTransitionError, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
+export { archiveRun, countActiveKnowledgeEntries, listRuns } from "./run-archive.js";