cclaw-cli 0.5.3 → 0.5.5

package/dist/install.js

@@ -1,6 +1,5 @@
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { COMMAND_FILE_ORDER, REQUIRED_DIRS, RUNTIME_ROOT, UTILITY_COMMANDS } from "./constants.js";
@@ -13,7 +12,7 @@ import { startCommandContract, startCommandSkillMarkdown } from "./content/start
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { sessionStartScript, stopCheckpointScript, opencodePluginJs, claudeHooksJson, cursorHooksJson, codexHooksJson } from "./content/hooks.js";
-import { contextMonitorScript, observeScript, promptGuardScript, workflowGuardScript, summarizeObservationsRuntimeModule, summarizeObservationsScript } from "./content/observe.js";
+import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
 import { stageSkillFolder, stageSkillMarkdown } from "./content/skills.js";
@@ -32,22 +31,6 @@ const execFileAsync = promisify(execFile);
 function runtimePath(projectRoot, ...segments) {
     return path.join(projectRoot, RUNTIME_ROOT, ...segments);
 }
-function resolveGlobalLearningsPath(projectRoot, config) {
-    if (config.globalLearnings !== true) {
-        return null;
-    }
-    const raw = config.globalLearningsPath?.trim() ?? "";
-    if (raw.length === 0) {
-        return path.join(os.homedir(), ".cclaw-global-learnings.jsonl");
-    }
-    if (raw.startsWith("~/")) {
-        return path.join(os.homedir(), raw.slice(2));
-    }
-    if (path.isAbsolute(raw)) {
-        return raw;
-    }
-    return path.join(projectRoot, raw);
-}
 async function resolveGitHooksDir(projectRoot) {
     try {
         const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", "hooks"], {
@@ -497,23 +480,14 @@ async function writeHooks(projectRoot, config) {
     const harnesses = config.harnesses;
     const hooksDir = runtimePath(projectRoot, "hooks");
     await ensureDir(hooksDir);
-    await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript({
-        globalLearningsEnabled: config.globalLearnings === true,
-        globalLearningsPath: config.globalLearningsPath
-    }));
+    await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
     await writeFileSafe(path.join(hooksDir, "prompt-guard.sh"), promptGuardScript({
         strictMode: config.promptGuardMode === "strict"
     }));
     await writeFileSafe(path.join(hooksDir, "workflow-guard.sh"), workflowGuardScript());
     await writeFileSafe(path.join(hooksDir, "context-monitor.sh"), contextMonitorScript());
-    await writeFileSafe(path.join(hooksDir, "observe.sh"), observeScript());
-    await writeFileSafe(path.join(hooksDir, "summarize-observations.sh"), summarizeObservationsScript());
-    await writeFileSafe(path.join(hooksDir, "summarize-observations.mjs"), summarizeObservationsRuntimeModule());
-    const opencodePluginSource = opencodePluginJs({
-        globalLearningsEnabled: config.globalLearnings === true,
-        globalLearningsPath: config.globalLearningsPath
-    });
+    const opencodePluginSource = opencodePluginJs();
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);
     try {
         for (const script of [
@@ -522,9 +496,6 @@ async function writeHooks(projectRoot, config) {
             "prompt-guard.sh",
             "workflow-guard.sh",
             "context-monitor.sh",
-            "observe.sh",
-            "summarize-observations.sh",
-            "summarize-observations.mjs",
             "opencode-plugin.mjs"
         ]) {
             await fs.chmod(path.join(hooksDir, script), 0o755);
@@ -565,20 +536,10 @@ async function writeHooks(projectRoot, config) {
         // OpenCode registration is auto-managed via opencode.json/opencode.jsonc.
     }
 }
-async function ensureLearningsStore(projectRoot) {
-    const storePath = runtimePath(projectRoot, "learnings.jsonl");
+async function ensureKnowledgeStore(projectRoot) {
+    const storePath = runtimePath(projectRoot, "knowledge.md");
     if (!(await exists(storePath))) {
-        await writeFileSafe(storePath, "");
-    }
-}
-async function ensureGlobalLearningsStore(projectRoot, config) {
-    const globalPath = resolveGlobalLearningsPath(projectRoot, config);
-    if (!globalPath) {
-        return;
-    }
-    await ensureDir(path.dirname(globalPath));
-    if (!(await exists(globalPath))) {
-        await writeFileSafe(globalPath, "");
+        await writeFileSafe(storePath, "# Project Knowledge\n\n");
     }
 }
 async function ensureSessionStateFiles(projectRoot) {
@@ -723,6 +684,20 @@ async function cleanLegacyArtifacts(projectRoot) {
             // best-effort cleanup
         }
     }
+    for (const legacyRuntimeFile of [
+        runtimePath(projectRoot, "learnings.jsonl"),
+        runtimePath(projectRoot, "observations.jsonl"),
+        runtimePath(projectRoot, "hooks", "observe.sh"),
+        runtimePath(projectRoot, "hooks", "summarize-observations.sh"),
+        runtimePath(projectRoot, "hooks", "summarize-observations.mjs")
+    ]) {
+        try {
+            await fs.rm(legacyRuntimeFile, { force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
 }
 async function cleanStaleFiles(projectRoot) {
     const expectedShimFiles = new Set([
@@ -766,11 +741,10 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await writeArtifactTemplates(projectRoot);
     await writeRulebook(projectRoot);
     await writeState(projectRoot, forceStateReset);
-    await ensureRunSystem(projectRoot);
+    await ensureRunSystem(projectRoot, { createIfMissing: false });
     await ensureSessionStateFiles(projectRoot);
     await writeAdapterManifest(projectRoot, harnesses);
-    await ensureLearningsStore(projectRoot);
-    await ensureGlobalLearningsStore(projectRoot, config);
+    await ensureKnowledgeStore(projectRoot);
     await writeHooks(projectRoot, config);
     await syncDisabledHarnessArtifacts(projectRoot, harnesses);
     await syncManagedGitHooks(projectRoot, config);
@@ -854,7 +828,7 @@ function stripManagedHookCommands(value) {
 }
 function isManagedRuntimeHookCommand(command) {
     const normalized = command.trim().replace(/\s+/gu, " ");
-    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|prompt-guard|workflow-guard|context-monitor|observe|summarize-observations)\.sh(?:\s|$)/u.test(normalized);
+    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized);
 }
 async function removeManagedHookEntries(hookFilePath) {
     if (!(await exists(hookFilePath)))

package/dist/policy.js

@@ -85,9 +85,8 @@ export async function policyChecks(projectRoot, options = {}) {
     // --- utility skill checks ---
     const runtimeFile = (relativePath) => `${RUNTIME_ROOT}/${relativePath}`;
     const utilitySkillChecks = [
-        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Learning Entry Schema", name: "utility_skill:learnings:schema" },
+        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Entry format (append-only)", name: "utility_skill:learnings:entry_format" },
         { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Subcommands", name: "utility_skill:learnings:subcommands" },
-        { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Confidence Decay", name: "utility_skill:learnings:decay" },
         { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:learnings:hard_gate" },
         { file: runtimeFile("commands/learn.md"), needle: "## Subcommands", name: "utility_command:learn:subcommands" },
         { file: runtimeFile("skills/subagent-dev/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:sdd:hard_gate" },
@@ -152,8 +151,6 @@ export async function policyChecks(projectRoot, options = {}) {
         { file: runtimeFile("hooks/workflow-guard.sh"), needle: "stage_invocation_without_recent_flow_read", name: "hooks:workflow_guard:flow_read_reason" },
         { file: runtimeFile("hooks/workflow-guard.sh"), needle: "stage_jump_", name: "hooks:workflow_guard:stage_jump_reason" },
         { file: runtimeFile("hooks/context-monitor.sh"), needle: "remaining is", name: "hooks:context:threshold_warning" },
-        { file: runtimeFile("hooks/observe.sh"), needle: "stage-activity.jsonl", name: "hooks:observe:activity_write" },
-        { file: runtimeFile("hooks/summarize-observations.mjs"), needle: "frequent-errors-", name: "hooks:summarize:runtime_module" },
         { file: runtimeFile("hooks/opencode-plugin.mjs"), needle: "activeRunId", name: "hooks:opencode:active_run" }
     ];
     if (activeHarnesses.has("opencode")) {

package/dist/runs.d.ts

@@ -3,16 +3,20 @@ export interface CclawRunMeta {
     id: string;
     title: string;
     createdAt: string;
-    archivedAt?: string;
-    stateSnapshot?: Omit<FlowState, "activeRunId">;
+}
+export interface ArchiveRunResult {
+    archiveId: string;
+    archivePath: string;
+    archivedAt: string;
+    featureName: string;
+    resetState: FlowState;
+}
+interface EnsureRunSystemOptions {
+    createIfMissing?: boolean;
 }
 export declare function readFlowState(projectRoot: string): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState): Promise<void>;
+export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
-export declare function ensureRunSystem(projectRoot: string): Promise<FlowState>;
-export declare function startNewFeatureRun(projectRoot: string, title?: string): Promise<CclawRunMeta>;
-export declare function resumeRun(projectRoot: string, runId: string): Promise<CclawRunMeta>;
-export declare function archiveRun(projectRoot: string, runId?: string): Promise<{
-    archived: CclawRunMeta;
-    active: CclawRunMeta;
-}>;
+export declare function archiveRun(projectRoot: string, featureName?: string): Promise<ArchiveRunResult>;
+export {};

package/dist/runs.js

@@ -6,8 +6,6 @@ import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.
 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 RUN_META_FILE = "run.json";
-const RUN_HANDOFF_FILE = "handoff.md";
 const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
 function flowStatePath(projectRoot) {
     return path.join(projectRoot, FLOW_STATE_REL_PATH);
@@ -21,65 +19,6 @@ function runsRoot(projectRoot) {
 function activeArtifactsPath(projectRoot) {
     return path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH);
 }
-function runRoot(projectRoot, runId) {
-    return path.join(runsRoot(projectRoot), requireSafeRunId(runId));
-}
-function runArtifactsPath(projectRoot, runId) {
-    return path.join(runRoot(projectRoot, runId), "artifacts");
-}
-function runMetaPath(projectRoot, runId) {
-    return path.join(runRoot(projectRoot, runId), RUN_META_FILE);
-}
-function runHandoffPath(projectRoot, runId) {
-    return path.join(runRoot(projectRoot, runId), RUN_HANDOFF_FILE);
-}
-function nowIso() {
-    return new Date().toISOString();
-}
-function pad2(value) {
-    return value.toString().padStart(2, "0");
-}
-function buildRunId(date = new Date()) {
-    const yyyy = date.getUTCFullYear();
-    const mm = pad2(date.getUTCMonth() + 1);
-    const dd = pad2(date.getUTCDate());
-    const hh = pad2(date.getUTCHours());
-    const min = pad2(date.getUTCMinutes());
-    const ss = pad2(date.getUTCSeconds());
-    const random = Math.random().toString(36).slice(2, 6);
-    return `run-${yyyy}${mm}${dd}-${hh}${min}${ss}-${random}`;
-}
-function normalizeTitle(title) {
-    const trimmed = (title ?? "").trim();
-    if (trimmed.length === 0) {
-        return "New feature run";
-    }
-    return trimmed;
-}
-function isSafeRunId(value) {
-    return /^[A-Za-z0-9_-]{1,128}$/u.test(value);
-}
-function sanitizeRunId(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return isSafeRunId(trimmed) ? trimmed : undefined;
-}
-function requireSafeRunId(runId) {
-    const safe = sanitizeRunId(runId);
-    if (!safe) {
-        throw new Error(`Invalid run id "${runId}"`);
-    }
-    return safe;
-}
-function snapshotState(state) {
-    return {
-        currentStage: state.currentStage,
-        completedStages: [...state.completedStages],
-        guardEvidence: { ...state.guardEvidence },
-        stageGateCatalog: JSON.parse(JSON.stringify(state.stageGateCatalog))
-    };
-}
 function isFlowStage(value) {
     return typeof value === "string" && FLOW_STAGE_SET.has(value);
 }
@@ -144,296 +83,148 @@ function sanitizeStageGateCatalog(value, fallback) {
     }
     return next;
 }
-function coerceFlowState(parsed, activeRunIdOverride) {
-    const overrideTrim = sanitizeRunId(activeRunIdOverride);
-    const parsedActiveRun = sanitizeRunId(parsed.activeRunId);
-    const seedRunId = overrideTrim ?? parsedActiveRun;
-    const next = createInitialFlowState(seedRunId);
+function coerceFlowState(parsed) {
+    const next = createInitialFlowState();
+    const activeRunIdRaw = parsed.activeRunId;
+    const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
+        ? activeRunIdRaw.trim()
+        : next.activeRunId;
     return {
-        activeRunId: overrideTrim ?? parsedActiveRun ?? next.activeRunId,
+        activeRunId,
         currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
         completedStages: sanitizeCompletedStages(parsed.completedStages),
         guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
         stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog)
     };
 }
-function createdAtFromRunId(runId) {
-    const match = /^run-(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})-[a-z0-9]+$/iu.exec(runId);
-    if (!match) {
-        return null;
+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";
     }
-    const [, year, month, day, hour, minute, second] = match;
-    const date = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second)));
-    return Number.isNaN(date.getTime()) ? null : date.toISOString();
-}
-async function readJsonFile(filePath) {
-    if (!(await exists(filePath)))
-        return null;
     try {
-        return JSON.parse(await fs.readFile(filePath, "utf8"));
+        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 null;
-    }
-}
-async function listImmediateFiles(dirPath) {
-    if (!(await exists(dirPath)))
-        return [];
-    const entries = await fs.readdir(dirPath, { withFileTypes: true });
-    return entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
-}
-async function clearImmediateFiles(dirPath) {
-    if (!(await exists(dirPath)))
-        return;
-    const entries = await fs.readdir(dirPath, { withFileTypes: true });
-    for (const entry of entries) {
-        if (entry.isFile()) {
-            await fs.rm(path.join(dirPath, entry.name), { force: true });
-        }
+        return "feature";
     }
 }
-async function copyImmediateFiles(fromDir, toDir) {
-    await ensureDir(toDir);
-    const fileNames = await listImmediateFiles(fromDir);
-    for (const fileName of fileNames) {
-        const sourcePath = path.join(fromDir, fileName);
-        const targetPath = path.join(toDir, fileName);
-        await fs.copyFile(sourcePath, targetPath);
+async function uniqueArchiveId(projectRoot, baseId) {
+    let index = 1;
+    let candidate = baseId;
+    while (await exists(path.join(runsRoot(projectRoot), candidate))) {
+        index += 1;
+        candidate = `${baseId}-${index}`;
     }
-}
-function handoffMarkdown(runMeta, state) {
-    return `# Run Handoff
-
-## Run
-- ID: ${runMeta.id}
-- Title: ${runMeta.title}
-- Created: ${runMeta.createdAt}
-- Archived: ${runMeta.archivedAt ?? "active"}
-
-## Flow Snapshot
-- Active stage: ${state.currentStage}
-- Completed stages: ${state.completedStages.join(", ") || "(none)"}
-- Active run ID in flow-state: ${state.activeRunId}
-
-## Paths
-- Active artifacts: \`${RUNTIME_ROOT}/artifacts/\`
-- Canonical run artifacts: \`${RUNTIME_ROOT}/runs/${runMeta.id}/artifacts/\`
-
-## Resume
-1. Continue with the stage command for \`${state.currentStage}\`
-2. If needed, sync artifacts from \`${RUNTIME_ROOT}/runs/${runMeta.id}/artifacts/\`
-`;
+    return candidate;
 }
 export async function readFlowState(projectRoot) {
     const statePath = flowStatePath(projectRoot);
-    const parsed = await readJsonFile(statePath);
-    if (!parsed || typeof parsed !== "object") {
+    if (!(await exists(statePath))) {
+        return createInitialFlowState();
+    }
+    try {
+        const parsed = JSON.parse(await fs.readFile(statePath, "utf8"));
+        return coerceFlowState(parsed);
+    }
+    catch {
         return createInitialFlowState();
     }
-    return coerceFlowState(parsed);
 }
 export async function writeFlowState(projectRoot, state) {
     await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
-        const safe = coerceFlowState({ ...state }, state.activeRunId);
+        const safe = coerceFlowState({ ...state });
         await writeFileSafe(flowStatePath(projectRoot), `${JSON.stringify(safe, null, 2)}\n`);
     });
 }
+export async function ensureRunSystem(projectRoot, _options = {}) {
+    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);
+    }
+    return state;
+}
 export async function listRuns(projectRoot) {
     const root = runsRoot(projectRoot);
-    if (!(await exists(root)))
+    if (!(await exists(root))) {
         return [];
-    const dirs = await fs.readdir(root, { withFileTypes: true });
-    const metas = [];
-    for (const dir of dirs) {
-        if (!dir.isDirectory())
-            continue;
-        const runId = dir.name;
-        if (!isSafeRunId(runId))
-            continue;
-        const meta = await readJsonFile(runMetaPath(projectRoot, runId));
-        if (meta && typeof meta.id === "string" && meta.id === runId) {
-            metas.push(meta);
+    }
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const runs = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
             continue;
         }
-        let fallbackCreatedAt = createdAtFromRunId(runId);
-        if (!fallbackCreatedAt) {
-            try {
-                const stat = await fs.stat(path.join(root, runId));
-                fallbackCreatedAt = stat.birthtime?.toISOString?.() ?? stat.mtime.toISOString();
-            }
-            catch {
-                fallbackCreatedAt = null;
-            }
+        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
         }
-        metas.push({
-            id: runId,
-            title: runId,
-            createdAt: fallbackCreatedAt ?? nowIso()
+        runs.push({
+            id: entry.name,
+            title: entry.name,
+            createdAt
         });
     }
-    return metas.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-}
-async function ensureRunMetadata(projectRoot, meta) {
-    await writeFileSafe(runMetaPath(projectRoot, meta.id), `${JSON.stringify(meta, null, 2)}\n`);
-}
-async function persistRunStateSnapshot(projectRoot, runId, state) {
-    const meta = await readJsonFile(runMetaPath(projectRoot, runId));
-    if (!meta)
-        return;
-    const safeState = coerceFlowState({ ...state }, state.activeRunId);
-    await ensureRunMetadata(projectRoot, {
-        ...meta,
-        stateSnapshot: snapshotState(safeState)
-    });
-}
-async function syncActiveArtifactsToRun(projectRoot, runId) {
-    const fromDir = activeArtifactsPath(projectRoot);
-    const toDir = runArtifactsPath(projectRoot, runId);
-    await ensureDir(toDir);
-    await clearImmediateFiles(toDir);
-    await copyImmediateFiles(fromDir, toDir);
-}
-async function loadRunArtifactsToActive(projectRoot, runId) {
-    const fromDir = runArtifactsPath(projectRoot, runId);
-    const toDir = activeArtifactsPath(projectRoot);
-    await ensureDir(toDir);
-    await clearImmediateFiles(toDir);
-    await copyImmediateFiles(fromDir, toDir);
-}
-async function createRun(projectRoot, options) {
-    const runId = buildRunId();
-    const meta = {
-        id: runId,
-        title: normalizeTitle(options?.title),
-        createdAt: nowIso()
-    };
-    await ensureDir(runRoot(projectRoot, runId));
-    await ensureRunMetadata(projectRoot, meta);
-    const runArtifactsDir = runArtifactsPath(projectRoot, runId);
-    await ensureDir(runArtifactsDir);
-    if (options?.seedFromActiveArtifacts && (await exists(activeArtifactsPath(projectRoot)))) {
-        await copyImmediateFiles(activeArtifactsPath(projectRoot), runArtifactsDir);
-    }
-    return meta;
-}
-async function ensureRunHandoff(projectRoot, runId) {
-    const state = await readFlowState(projectRoot);
-    const meta = await readJsonFile(runMetaPath(projectRoot, runId));
-    if (!meta)
-        return;
-    await writeFileSafe(runHandoffPath(projectRoot, runId), handoffMarkdown(meta, state));
+    return runs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }
-export async function ensureRunSystem(projectRoot) {
-    await ensureDir(runsRoot(projectRoot));
-    await ensureDir(activeArtifactsPath(projectRoot));
-    let state = await readFlowState(projectRoot);
-    let activeRunId = state.activeRunId;
-    const activeRunExists = activeRunId.trim().length > 0 && (await exists(runArtifactsPath(projectRoot, activeRunId)));
-    if (!activeRunExists) {
-        const activeHasArtifacts = (await listImmediateFiles(activeArtifactsPath(projectRoot))).length > 0;
-        const initialRun = await createRun(projectRoot, {
-            title: activeHasArtifacts ? "Migrated active run" : "Initial feature run",
-            seedFromActiveArtifacts: activeHasArtifacts
-        });
-        activeRunId = initialRun.id;
-        state = { ...state, activeRunId };
-        await writeFlowState(projectRoot, state);
-    }
-    const runArtifactsDir = runArtifactsPath(projectRoot, activeRunId);
-    await ensureDir(runArtifactsDir);
-    if ((await listImmediateFiles(activeArtifactsPath(projectRoot))).length === 0) {
-        await loadRunArtifactsToActive(projectRoot, activeRunId);
-    }
-    else {
-        await syncActiveArtifactsToRun(projectRoot, activeRunId);
-    }
-    await persistRunStateSnapshot(projectRoot, activeRunId, state);
-    await ensureRunHandoff(projectRoot, activeRunId);
-    return state;
-}
-export async function startNewFeatureRun(projectRoot, title) {
-    await ensureRunSystem(projectRoot);
-    const state = await readFlowState(projectRoot);
-    await syncActiveArtifactsToRun(projectRoot, state.activeRunId);
-    await persistRunStateSnapshot(projectRoot, state.activeRunId, state);
-    await ensureRunHandoff(projectRoot, state.activeRunId);
-    const nextRun = await createRun(projectRoot, {
-        title,
-        seedFromActiveArtifacts: false
-    });
-    const nextState = {
-        ...createInitialFlowState(nextRun.id),
-        activeRunId: nextRun.id
-    };
-    await writeFlowState(projectRoot, nextState);
-    await persistRunStateSnapshot(projectRoot, nextRun.id, nextState);
-    await loadRunArtifactsToActive(projectRoot, nextRun.id);
-    await ensureRunHandoff(projectRoot, nextRun.id);
-    return nextRun;
-}
-export async function resumeRun(projectRoot, runId) {
+export async function archiveRun(projectRoot, featureName) {
     await ensureRunSystem(projectRoot);
-    const safeRunId = requireSafeRunId(runId);
-    const targetMeta = await readJsonFile(runMetaPath(projectRoot, safeRunId));
-    if (!targetMeta) {
-        throw new Error(`Run "${safeRunId}" not found under ${RUNTIME_ROOT}/runs/`);
-    }
-    const state = await readFlowState(projectRoot);
-    await syncActiveArtifactsToRun(projectRoot, state.activeRunId);
-    await persistRunStateSnapshot(projectRoot, state.activeRunId, state);
-    await ensureRunHandoff(projectRoot, state.activeRunId);
-    const nextState = targetMeta.stateSnapshot
-        ? coerceFlowState({
-            ...createInitialFlowState(safeRunId),
-            ...targetMeta.stateSnapshot,
-            activeRunId: safeRunId
-        }, safeRunId)
-        : coerceFlowState({
-            ...createInitialFlowState(safeRunId),
-            activeRunId: safeRunId
-        }, safeRunId);
-    await writeFlowState(projectRoot, nextState);
-    await persistRunStateSnapshot(projectRoot, safeRunId, nextState);
-    await loadRunArtifactsToActive(projectRoot, safeRunId);
-    await ensureRunHandoff(projectRoot, safeRunId);
-    return targetMeta;
-}
-export async function archiveRun(projectRoot, runId) {
-    await ensureRunSystem(projectRoot);
-    const state = await readFlowState(projectRoot);
-    const targetRunId = runId ? requireSafeRunId(runId) : state.activeRunId;
-    const targetMeta = await readJsonFile(runMetaPath(projectRoot, targetRunId));
-    if (!targetMeta) {
-        throw new Error(`Run "${targetRunId}" not found under ${RUNTIME_ROOT}/runs/`);
-    }
-    if (targetRunId === state.activeRunId) {
-        await syncActiveArtifactsToRun(projectRoot, targetRunId);
-        await persistRunStateSnapshot(projectRoot, targetRunId, state);
-    }
-    const archivedMeta = {
-        ...targetMeta,
-        archivedAt: nowIso()
-    };
-    await ensureRunMetadata(projectRoot, archivedMeta);
-    await ensureRunHandoff(projectRoot, targetRunId);
-    if (targetRunId !== state.activeRunId) {
-        const activeMeta = await readJsonFile(runMetaPath(projectRoot, state.activeRunId));
-        if (!activeMeta) {
-            throw new Error(`Active run "${state.activeRunId}" is missing metadata`);
-        }
-        return { archived: archivedMeta, active: activeMeta };
-    }
-    const nextRun = await createRun(projectRoot, {
-        title: "Post-archive run",
-        seedFromActiveArtifacts: false
-    });
-    const nextState = {
-        ...createInitialFlowState(nextRun.id),
-        activeRunId: nextRun.id
+    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");
+    await ensureDir(archivePath);
+    await fs.rename(artifactsDir, archiveArtifactsPath);
+    await ensureDir(artifactsDir);
+    const resetState = createInitialFlowState();
+    await writeFlowState(projectRoot, resetState);
+    const archivedAt = new Date().toISOString();
+    return {
+        archiveId,
+        archivePath,
+        archivedAt,
+        featureName: feature,
+        resetState
     };
-    await writeFlowState(projectRoot, nextState);
-    await persistRunStateSnapshot(projectRoot, nextRun.id, nextState);
-    await loadRunArtifactsToActive(projectRoot, nextRun.id);
-    await ensureRunHandoff(projectRoot, nextRun.id);
-    return { archived: archivedMeta, active: nextRun };
 }