muonroi-cli 1.3.4 → 1.4.1

package/src/flow/artifact-io.ts

@@ -1,41 +0,0 @@
-/**
- * Read/write .muonroi-flow/ top-level files via atomic-rename.
- *
- * All reads parse heading-delimited markdown via parseSections.
- * All writes serialize via serializeSections then atomicWriteText.
- */
-
-import { promises as fs } from "node:fs";
-import * as path from "node:path";
-import { atomicWriteText } from "../storage/atomic-io.js";
-import type { SectionMap } from "./parser.js";
-import { parseSections, serializeSections } from "./parser.js";
-
-/**
- * Read a .muonroi-flow/ file and parse it into a SectionMap.
- * Returns null if the file does not exist (ENOENT).
- */
-export async function readArtifact(flowDir: string, filename: string): Promise<SectionMap | null> {
-  const filePath = path.join(flowDir, filename);
-  try {
-    const content = await fs.readFile(filePath, "utf8");
-    return parseSections(content);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw err;
-  }
-}
-
-/**
- * Write a SectionMap to a .muonroi-flow/ file using atomic-rename.
- */
-export async function writeArtifact(
-  flowDir: string,
-  filename: string,
-  map: SectionMap,
-  order?: string[],
-): Promise<void> {
-  const filePath = path.join(flowDir, filename);
-  const content = serializeSections(map, order);
-  await atomicWriteText(filePath, content);
-}

package/src/flow/compaction/__tests__/compress.test.ts

@@ -1,69 +0,0 @@
-import type { ModelMessage } from "ai";
-import { describe, expect, it, vi } from "vitest";
-import { compressChat } from "../compress.js";
-
-// Mock the existing compaction engine
-vi.mock("../../../orchestrator/compaction.js", () => ({
-  serializeConversation: (msgs: ModelMessage[]) => {
-    // Simple serialization for tests
-    return msgs
-      .map((m) => {
-        const text = typeof m.content === "string" ? m.content : "";
-        return `[${m.role}]: ${text}`;
-      })
-      .join("\n\n");
-  },
-  estimateMessageTokens: (msg: ModelMessage) => {
-    const text = typeof msg.content === "string" ? msg.content : "";
-    return Math.ceil(text.length / 4);
-  },
-  prepareCompaction: vi.fn().mockReturnValue(null),
-  generateCompactionSummary: vi.fn().mockResolvedValue("Compressed summary"),
-  DEFAULT_RESERVE_TOKENS: 16_384,
-  DEFAULT_KEEP_RECENT_TOKENS: 20_000,
-}));
-
-describe("compressChat", () => {
-  const shortMessages: ModelMessage[] = [
-    { role: "user", content: "Hello" },
-    { role: "assistant", content: "Hi there" },
-  ];
-
-  it("returns messages unchanged when under token budget", async () => {
-    const result = await compressChat(shortMessages, "system prompt", 10000);
-    expect(result.summary).toContain("Hello");
-    expect(result.summary).toContain("Hi there");
-    expect(result.tokensAfter).toBeLessThanOrEqual(10000);
-  });
-
-  it("preserves <!-- preserve --> blocks verbatim in output", async () => {
-    const messages: ModelMessage[] = [
-      {
-        role: "user",
-        content: "Some chat\n<!-- preserve -->\nCritical verbatim block\n<!-- /preserve -->\nMore chat",
-      },
-    ];
-    const result = await compressChat(messages, "system", 10000);
-    expect(result.summary).toContain("<!-- preserve -->");
-    expect(result.summary).toContain("Critical verbatim block");
-    expect(result.summary).toContain("<!-- /preserve -->");
-  });
-
-  it("returns preservedBlocks array", async () => {
-    const messages: ModelMessage[] = [
-      {
-        role: "user",
-        content: "Text\n<!-- preserve -->\nBlock content\n<!-- /preserve -->\nRest",
-      },
-    ];
-    const result = await compressChat(messages, "system", 10000);
-    expect(result.preservedBlocks).toHaveLength(1);
-    expect(result.preservedBlocks[0].content).toBe("\nBlock content\n");
-  });
-
-  it("returns estimated tokensAfter", async () => {
-    const result = await compressChat(shortMessages, "system prompt", 10000);
-    expect(result.tokensAfter).toBeGreaterThan(0);
-    expect(typeof result.tokensAfter).toBe("number");
-  });
-});

package/src/flow/compaction/__tests__/extract.test.ts

@@ -1,74 +0,0 @@
-import type { ModelMessage } from "ai";
-import { describe, expect, it } from "vitest";
-import { extractDecisions } from "../extract.js";
-
-describe("extractDecisions", () => {
-  it("extracts Decision: lines from messages", () => {
-    const messages: ModelMessage[] = [
-      { role: "user", content: "Decision: Use JWT for auth" },
-      { role: "assistant", content: "Understood. I'll implement JWT." },
-    ];
-    const result = extractDecisions(messages);
-    expect(result.decisions).toContain("Use JWT for auth");
-  });
-
-  it("extracts Decided: lines", () => {
-    const messages: ModelMessage[] = [{ role: "user", content: "Decided: Go with PostgreSQL" }];
-    const result = extractDecisions(messages);
-    expect(result.decisions).toContain("Go with PostgreSQL");
-  });
-
-  it("extracts Fact: lines", () => {
-    const messages: ModelMessage[] = [{ role: "assistant", content: "Fact: The API rate limit is 100 req/min" }];
-    const result = extractDecisions(messages);
-    expect(result.facts).toContain("The API rate limit is 100 req/min");
-  });
-
-  it("extracts Constraint: lines", () => {
-    const messages: ModelMessage[] = [{ role: "user", content: "Constraint: Must run on Windows and Linux" }];
-    const result = extractDecisions(messages);
-    expect(result.constraints).toContain("Must run on Windows and Linux");
-  });
-
-  it("extracts content inside preserve blocks as decisions", () => {
-    const messages: ModelMessage[] = [
-      {
-        role: "user",
-        content: "Some text\n<!-- preserve -->\nImportant preserved content\n<!-- /preserve -->\nMore text",
-      },
-    ];
-    const result = extractDecisions(messages);
-    expect(result.decisions).toContain("\nImportant preserved content\n");
-  });
-
-  it("returns empty arrays for empty messages", () => {
-    const result = extractDecisions([]);
-    expect(result.decisions).toEqual([]);
-    expect(result.facts).toEqual([]);
-    expect(result.constraints).toEqual([]);
-  });
-
-  it("returns empty arrays when no patterns match", () => {
-    const messages: ModelMessage[] = [
-      { role: "user", content: "Hello, how are you?" },
-      { role: "assistant", content: "I'm doing well!" },
-    ];
-    const result = extractDecisions(messages);
-    expect(result.decisions).toEqual([]);
-    expect(result.facts).toEqual([]);
-    expect(result.constraints).toEqual([]);
-  });
-
-  it("extracts multiple patterns from a single message", () => {
-    const messages: ModelMessage[] = [
-      {
-        role: "user",
-        content: "Decision: Use TypeScript\nFact: Project uses Bun runtime\nConstraint: No new dependencies",
-      },
-    ];
-    const result = extractDecisions(messages);
-    expect(result.decisions).toContain("Use TypeScript");
-    expect(result.facts).toContain("Project uses Bun runtime");
-    expect(result.constraints).toContain("No new dependencies");
-  });
-});

package/src/flow/compaction/__tests__/preserve.test.ts

@@ -1,69 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { extractPreservedBlocks, PRESERVE_CLOSE, PRESERVE_OPEN, restorePreservedBlocks } from "../preserve.js";
-
-describe("extractPreservedBlocks", () => {
-  it("extracts single preserve block and replaces with placeholder", () => {
-    const text = `Before\n${PRESERVE_OPEN}\nKeep this verbatim\n${PRESERVE_CLOSE}\nAfter`;
-    const { cleaned, blocks } = extractPreservedBlocks(text);
-    expect(blocks).toHaveLength(1);
-    expect(blocks[0].content).toBe("\nKeep this verbatim\n");
-    expect(cleaned).toContain("__PRESERVED_0__");
-    expect(cleaned).not.toContain(PRESERVE_OPEN);
-    expect(cleaned).not.toContain("Keep this verbatim");
-    expect(cleaned).toContain("Before");
-    expect(cleaned).toContain("After");
-  });
-
-  it("extracts multiple preserve blocks", () => {
-    const text = `A\n${PRESERVE_OPEN}\nBlock1\n${PRESERVE_CLOSE}\nB\n${PRESERVE_OPEN}\nBlock2\n${PRESERVE_CLOSE}\nC`;
-    const { cleaned, blocks } = extractPreservedBlocks(text);
-    expect(blocks).toHaveLength(2);
-    expect(blocks[0].content).toBe("\nBlock1\n");
-    expect(blocks[1].content).toBe("\nBlock2\n");
-    expect(cleaned).toContain("__PRESERVED_0__");
-    expect(cleaned).toContain("__PRESERVED_1__");
-  });
-
-  it("returns empty blocks for text without markers", () => {
-    const text = "No markers here";
-    const { cleaned, blocks } = extractPreservedBlocks(text);
-    expect(blocks).toHaveLength(0);
-    expect(cleaned).toBe(text);
-  });
-
-  it("handles empty text", () => {
-    const { cleaned, blocks } = extractPreservedBlocks("");
-    expect(blocks).toHaveLength(0);
-    expect(cleaned).toBe("");
-  });
-
-  it("handles malformed markers gracefully (open without close)", () => {
-    const text = `Before\n${PRESERVE_OPEN}\nUnclosed content`;
-    const { cleaned, blocks } = extractPreservedBlocks(text);
-    // Unclosed marker is NOT extracted
-    expect(blocks).toHaveLength(0);
-    expect(cleaned).toBe(text);
-  });
-});
-
-describe("restorePreservedBlocks", () => {
-  it("round-trips extract + restore", () => {
-    const original = `Start\n${PRESERVE_OPEN}\nVerbatim content\n${PRESERVE_CLOSE}\nEnd`;
-    const { cleaned, blocks } = extractPreservedBlocks(original);
-    const restored = restorePreservedBlocks(cleaned, blocks);
-    expect(restored).toBe(original);
-  });
-
-  it("restores multiple blocks in order", () => {
-    const original = `A\n${PRESERVE_OPEN}\nFirst\n${PRESERVE_CLOSE}\nB\n${PRESERVE_OPEN}\nSecond\n${PRESERVE_CLOSE}\nC`;
-    const { cleaned, blocks } = extractPreservedBlocks(original);
-    const restored = restorePreservedBlocks(cleaned, blocks);
-    expect(restored).toBe(original);
-  });
-
-  it("returns text unchanged when no blocks provided", () => {
-    const text = "No placeholders here";
-    const restored = restorePreservedBlocks(text, []);
-    expect(restored).toBe(text);
-  });
-});

package/src/flow/compaction/compress.ts

@@ -1,67 +0,0 @@
-/**
- * Pass 2: Token-budget chat compression using existing compaction engine.
- *
- * Serializes messages, extracts preserved blocks, compresses if over budget,
- * then restores preserved blocks into the output.
- */
-
-import type { ModelMessage } from "ai";
-import { serializeConversation } from "../../orchestrator/compaction.js";
-import { extractPreservedBlocks, type PreservedBlock, restorePreservedBlocks } from "./preserve.js";
-
-export interface CompressResult {
-  summary: string;
-  preservedBlocks: PreservedBlock[];
-  tokensAfter: number;
-}
-
-/**
- * Compress chat messages within a token budget.
- *
- * 1. Serialize messages via serializeConversation().
- * 2. Extract preserved blocks.
- * 3. If under budget, return as-is (with preserved blocks restored).
- * 4. If over budget, truncate/compress and restore preserved blocks.
- */
-export async function compressChat(
-  messages: ModelMessage[],
-  _systemPrompt: string,
-  tokenBudget: number,
-  _provider?: unknown,
-  _modelId?: string,
-): Promise<CompressResult> {
-  const serialized = serializeConversation(messages);
-  const { cleaned, blocks } = extractPreservedBlocks(serialized);
-
-  // Estimate tokens of cleaned text
-  const estimatedTokens = Math.ceil(cleaned.length / 4);
-
-  if (estimatedTokens <= tokenBudget) {
-    // Under budget — restore preserved blocks and return as-is
-    const restored = restorePreservedBlocks(cleaned, blocks);
-    return {
-      summary: restored,
-      preservedBlocks: blocks,
-      tokensAfter: Math.ceil(restored.length / 4),
-    };
-  }
-
-  // Over budget — truncate to fit budget while keeping preserved blocks
-  // Calculate space taken by preserved blocks
-  const preservedTokens = blocks.reduce((sum, b) => sum + Math.ceil(b.content.length / 4), 0);
-  const availableTokens = Math.max(0, tokenBudget - preservedTokens);
-  const availableChars = availableTokens * 4;
-
-  // Truncate the cleaned text to fit
-  const truncated =
-    cleaned.length > availableChars
-      ? `${cleaned.slice(0, availableChars)}\n\n[... ${cleaned.length - availableChars} characters truncated]`
-      : cleaned;
-
-  const restored = restorePreservedBlocks(truncated, blocks);
-  return {
-    summary: restored,
-    preservedBlocks: blocks,
-    tokensAfter: Math.ceil(restored.length / 4),
-  };
-}

package/src/flow/compaction/extract.ts

@@ -1,60 +0,0 @@
-/**
- * Pass 1: Decision/fact/constraint extraction from messages.
- *
- * Deterministic regex-based extraction — no LLM dependency.
- * Scans for "Decision:", "Decided:", "Fact:", "Constraint:" patterns
- * and content inside <!-- preserve --> blocks.
- */
-
-import type { ModelMessage } from "ai";
-import { serializeConversation } from "../../orchestrator/compaction.js";
-import { extractPreservedBlocks } from "./preserve.js";
-
-export interface ExtractedDecisions {
-  decisions: string[];
-  facts: string[];
-  constraints: string[];
-}
-
-const DECISION_RE = /(?:Decision|Decided):\s*(.+)/gi;
-const FACT_RE = /Fact:\s*(.+)/gi;
-const CONSTRAINT_RE = /Constraint:\s*(.+)/gi;
-
-function matchAll(text: string, re: RegExp): string[] {
-  const results: string[] = [];
-  let match: RegExpExecArray | null;
-  // Reset lastIndex for safety
-  re.lastIndex = 0;
-  while ((match = re.exec(text)) !== null) {
-    results.push(match[1].trim());
-  }
-  return results;
-}
-
-/**
- * Extract decisions, facts, and constraints from messages.
- *
- * Scans serialized conversation text for:
- * - Lines matching "Decision:" or "Decided:" -> decisions
- * - Lines matching "Fact:" -> facts
- * - Lines matching "Constraint:" -> constraints
- * - All content inside <!-- preserve --> blocks -> decisions (verbatim)
- */
-export function extractDecisions(messages: ModelMessage[]): ExtractedDecisions {
-  if (messages.length === 0) {
-    return { decisions: [], facts: [], constraints: [] };
-  }
-
-  const serialized = serializeConversation(messages);
-
-  // Extract preserved blocks as decisions
-  const { blocks } = extractPreservedBlocks(serialized);
-  const preservedDecisions = blocks.map((b) => b.content);
-
-  // Pattern-match for explicit markers
-  const decisions = [...matchAll(serialized, DECISION_RE), ...preservedDecisions];
-  const facts = matchAll(serialized, FACT_RE);
-  const constraints = matchAll(serialized, CONSTRAINT_RE);
-
-  return { decisions, facts, constraints };
-}

package/src/flow/compaction/index.ts

@@ -1,86 +0,0 @@
-/**
- * Two-pass compaction orchestrator.
- *
- * Pass 1: Extract decisions/facts/constraints to decisions.md (deterministic).
- * Pass 2: Compress chat within token budget, preserving verbatim blocks.
- * Snapshot full chat to history/<timestamp>.md before compressing.
- */
-
-import { promises as fs } from "node:fs";
-import * as path from "node:path";
-import type { ModelMessage } from "ai";
-import { estimateConversationTokens, serializeConversation } from "../../orchestrator/compaction.js";
-import { atomicWriteText } from "../../storage/atomic-io.js";
-import { readArtifact, writeArtifact } from "../artifact-io.js";
-import { compressChat } from "./compress.js";
-import { extractDecisions } from "./extract.js";
-
-export interface CompactionResult {
-  decisionsExtracted: number;
-  tokensBeforeCompress: number;
-  tokensAfterCompress: number;
-  historyPath: string;
-}
-
-/**
- * Orchestrate two-pass deliberate compaction.
- *
- * 1. Pass 1: extractDecisions -> append to decisions.md
- * 2. Snapshot: full chat -> history/<ISO-timestamp>.md
- * 3. Pass 2: compressChat -> compressed output
- * 4. Return metrics
- */
-export async function deliberateCompact(
-  flowDir: string,
-  messages: ModelMessage[],
-  systemPrompt: string,
-  tokenBudget: number,
-  provider?: unknown,
-  modelId?: string,
-): Promise<CompactionResult> {
-  // Pass 1: Extract decisions/facts/constraints
-  const extracted = extractDecisions(messages);
-  const totalExtracted = extracted.decisions.length + extracted.facts.length + extracted.constraints.length;
-
-  // Append to decisions.md
-  if (totalExtracted > 0) {
-    let existing = await readArtifact(flowDir, "decisions.md");
-    if (!existing) {
-      existing = { preamble: "", sections: new Map() };
-    }
-
-    const appendItems = (heading: string, items: string[]) => {
-      if (items.length === 0) return;
-      const current = existing!.sections.get(heading) ?? "";
-      const newContent = items.map((i) => `- ${i}`).join("\n");
-      existing!.sections.set(heading, current ? `${current}\n${newContent}` : newContent);
-    };
-
-    appendItems("Decisions", extracted.decisions);
-    appendItems("Facts", extracted.facts);
-    appendItems("Constraints", extracted.constraints);
-
-    await writeArtifact(flowDir, "decisions.md", existing, ["Decisions", "Facts", "Constraints"]);
-  }
-
-  // Snapshot full chat to history/
-  const historyDir = path.join(flowDir, "history");
-  await fs.mkdir(historyDir, { recursive: true });
-  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const historyPath = path.join(historyDir, `${timestamp}.md`);
-  const fullSerialized = serializeConversation(messages);
-  await atomicWriteText(historyPath, fullSerialized);
-
-  // Token estimation before
-  const tokensBefore = estimateConversationTokens(systemPrompt, messages);
-
-  // Pass 2: Compress
-  const compressed = await compressChat(messages, systemPrompt, tokenBudget, provider, modelId);
-
-  return {
-    decisionsExtracted: totalExtracted,
-    tokensBeforeCompress: tokensBefore,
-    tokensAfterCompress: compressed.tokensAfter,
-    historyPath,
-  };
-}

package/src/flow/compaction/preserve.ts

@@ -1,48 +0,0 @@
-/**
- * Preserve-verbatim marker handling for two-pass compaction.
- *
- * Content between <!-- preserve --> and <!-- /preserve --> markers
- * survives compaction regardless of token budget.
- */
-
-export const PRESERVE_OPEN = "<!-- preserve -->";
-export const PRESERVE_CLOSE = "<!-- /preserve -->";
-
-export interface PreservedBlock {
-  id: string;
-  content: string;
-}
-
-const PRESERVE_RE = /<!-- preserve -->([\s\S]*?)<!-- \/preserve -->/g;
-
-/**
- * Extract content between preserve markers, replacing with placeholders.
- * Unmatched (unclosed) markers are left as-is.
- */
-export function extractPreservedBlocks(text: string): {
-  cleaned: string;
-  blocks: PreservedBlock[];
-} {
-  const blocks: PreservedBlock[] = [];
-  let index = 0;
-
-  const cleaned = text.replace(PRESERVE_RE, (_match, content: string) => {
-    const id = `__PRESERVED_${index}__`;
-    blocks.push({ id, content });
-    index++;
-    return id;
-  });
-
-  return { cleaned, blocks };
-}
-
-/**
- * Replace placeholders with original content wrapped in preserve markers.
- */
-export function restorePreservedBlocks(text: string, blocks: PreservedBlock[]): string {
-  let result = text;
-  for (const block of blocks) {
-    result = result.replace(block.id, `${PRESERVE_OPEN}${block.content}${PRESERVE_CLOSE}`);
-  }
-  return result;
-}

package/src/flow/index.ts

@@ -1,18 +0,0 @@
-/**
- * Flow module — .muonroi-flow/ artifact system.
- *
- * Re-exports public API from parser, scaffold, artifact-io, run-manager, migration.
- */
-
-// Artifact I/O
-export { readArtifact, writeArtifact } from "./artifact-io.js";
-// Migration
-export { detectLegacyFlow, migrateQuickCodexFlow } from "./migration.js";
-export type { SectionMap } from "./parser.js";
-// Parser
-export { getSection, parseSections, serializeSections } from "./parser.js";
-export type { RunState } from "./run-manager.js";
-// Run manager
-export { createRun, getActiveRunId, loadRun, setActiveRunId, updateRunFile } from "./run-manager.js";
-// Scaffold
-export { ensureFlowDir, FLOW_DIR_NAME } from "./scaffold.js";

package/src/flow/migration.ts

@@ -1,139 +0,0 @@
-/**
- * .quick-codex-flow/ -> .muonroi-flow/ migration.
- *
- * Detects legacy QC flow directory and migrates it one-shot to the new format.
- * Original .quick-codex-flow/ is NOT deleted after migration.
- */
-
-import { promises as fs } from "node:fs";
-import * as path from "node:path";
-import { atomicWriteText } from "../storage/atomic-io.js";
-import type { SectionMap } from "./parser.js";
-import { parseSections, serializeSections } from "./parser.js";
-import { ensureFlowDir } from "./scaffold.js";
-
-/** QC top-level file -> muonroi-flow file mapping */
-const TOP_LEVEL_MAP: Record<string, string> = {
-  "STATE.md": "state.md",
-  "PROJECT-ROADMAP.md": "roadmap.md",
-  "BACKLOG.md": "backlog.md",
-};
-
-/** QC run section heading -> target file in runs/<id>/ */
-const SECTION_TO_FILE: Record<string, string> = {
-  "Delivery Roadmap": "roadmap.md",
-  "Delegation State": "delegations.md",
-  "Gray Area Register": "gray-areas.md",
-};
-
-/** Sections that go into runs/<id>/state.md */
-const _STATE_SECTIONS = new Set(["Resume Digest", "Compact-Safe Summary", "Experience Snapshot", "Workflow State"]);
-
-/** Sections that go into the top-level decisions.md */
-const DECISIONS_SECTIONS = new Set(["Decision Register"]);
-
-/**
- * Detect whether a legacy .quick-codex-flow/ directory exists.
- */
-export async function detectLegacyFlow(cwd: string): Promise<boolean> {
-  try {
-    const stat = await fs.stat(path.join(cwd, ".quick-codex-flow"));
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Migrate .quick-codex-flow/ to .muonroi-flow/.
- *
- * - Top-level: STATE.md -> state.md, PROJECT-ROADMAP.md -> roadmap.md, BACKLOG.md -> backlog.md
- * - Run files (non-top-level .md): split by heading into per-aspect files
- * - Decision Register sections -> appended to decisions.md
- * - Unknown sections -> preserved in runs/<id>/state.md
- * - Original .quick-codex-flow/ is NOT deleted
- */
-export async function migrateQuickCodexFlow(cwd: string): Promise<{ runsCreated: number; filesCopied: number }> {
-  const qcDir = path.join(cwd, ".quick-codex-flow");
-  const flowDir = await ensureFlowDir(cwd);
-
-  let runsCreated = 0;
-  let filesCopied = 0;
-
-  // 1. Copy top-level files with renames
-  for (const [qcName, flowName] of Object.entries(TOP_LEVEL_MAP)) {
-    const srcPath = path.join(qcDir, qcName);
-    try {
-      const content = await fs.readFile(srcPath, "utf8");
-      await atomicWriteText(path.join(flowDir, flowName), content);
-      filesCopied++;
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-      // Missing top-level file is OK — skip
-    }
-  }
-
-  // 2. Find and split run files (non-top-level .md files)
-  const topLevelNames = new Set(Object.keys(TOP_LEVEL_MAP));
-  const entries = await fs.readdir(qcDir);
-  const runFiles = entries.filter((e) => e.endsWith(".md") && !topLevelNames.has(e));
-
-  // Accumulate decisions from all run files
-  let decisionsContent = "";
-
-  for (const runFile of runFiles) {
-    const content = await fs.readFile(path.join(qcDir, runFile), "utf8");
-    const parsed = parseSections(content);
-
-    // Derive run ID from filename slug (lowercase, dashes, no extension)
-    const runId = runFile
-      .replace(/\.md$/i, "")
-      .toLowerCase()
-      .replace(/[^a-z0-9-]/g, "-");
-    const runDir = path.join(flowDir, "runs", runId);
-    await fs.mkdir(runDir, { recursive: true });
-
-    // Buckets for per-file sections
-    const roadmapSections = new Map<string, string>();
-    const delegationsSections = new Map<string, string>();
-    const grayAreasSections = new Map<string, string>();
-    const stateSections = new Map<string, string>();
-
-    for (const [heading, body] of parsed.sections) {
-      if (SECTION_TO_FILE[heading] === "roadmap.md") {
-        roadmapSections.set(heading, body);
-      } else if (SECTION_TO_FILE[heading] === "delegations.md") {
-        delegationsSections.set(heading, body);
-      } else if (SECTION_TO_FILE[heading] === "gray-areas.md") {
-        grayAreasSections.set(heading, body);
-      } else if (DECISIONS_SECTIONS.has(heading)) {
-        decisionsContent += `## ${heading}\n\n${body}\n\n`;
-      } else {
-        // STATE_SECTIONS + unknown sections -> state.md (tolerant)
-        stateSections.set(heading, body);
-      }
-    }
-
-    // Write per-aspect files
-    const writeMap = async (filePath: string, sections: Map<string, string>) => {
-      const map: SectionMap = { preamble: "", sections };
-      await atomicWriteText(filePath, serializeSections(map));
-    };
-
-    await writeMap(path.join(runDir, "roadmap.md"), roadmapSections);
-    await writeMap(path.join(runDir, "state.md"), stateSections);
-    await writeMap(path.join(runDir, "delegations.md"), delegationsSections);
-    await writeMap(path.join(runDir, "gray-areas.md"), grayAreasSections);
-
-    runsCreated++;
-    filesCopied += 4;
-  }
-
-  // 3. Append decisions to top-level decisions.md
-  if (decisionsContent) {
-    const existingDecisions = await fs.readFile(path.join(flowDir, "decisions.md"), "utf8").catch(() => "");
-    await atomicWriteText(path.join(flowDir, "decisions.md"), existingDecisions + decisionsContent);
-  }
-
-  return { runsCreated, filesCopied };
-}