muonroi-cli 1.2.0

package/src/flow/compaction/extract.ts

@@ -0,0 +1,60 @@
+/**
+ * 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

@@ -0,0 +1,86 @@
+/**
+ * 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

@@ -0,0 +1,48 @@
+/**
+ * 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

@@ -0,0 +1,18 @@
+/**
+ * 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

@@ -0,0 +1,139 @@
+/**
+ * .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 };
+}

package/src/flow/parser.ts

@@ -0,0 +1,78 @@
+/**
+ * Heading-delimited section parser/writer for .muonroi-flow/ markdown files.
+ *
+ * All reads are tolerant: missing sections return undefined, empty input returns
+ * empty map, malformed input never throws. All writes are deterministic: same
+ * sections produce same output.
+ */
+
+export interface SectionMap {
+  sections: Map<string, string>;
+  preamble: string;
+}
+
+/**
+ * Parse heading-delimited markdown into a SectionMap.
+ * Splits on `## Heading` lines. Content before the first heading is the preamble.
+ * Empty or malformed input returns empty map with empty preamble (never throws).
+ */
+export function parseSections(markdown: string): SectionMap {
+  const sections = new Map<string, string>();
+  let preamble = "";
+  let currentHeading: string | null = null;
+  let currentLines: string[] = [];
+
+  const lines = markdown.split("\n");
+
+  for (const line of lines) {
+    const match = line.match(/^##\s+(.+)$/);
+    if (match) {
+      if (currentHeading !== null) {
+        sections.set(currentHeading, currentLines.join("\n").trim());
+      } else {
+        preamble = currentLines.join("\n").trim();
+      }
+      currentHeading = match[1].trim();
+      currentLines = [];
+    } else {
+      currentLines.push(line);
+    }
+  }
+
+  // Flush last section or preamble
+  if (currentHeading !== null) {
+    sections.set(currentHeading, currentLines.join("\n").trim());
+  } else {
+    preamble = currentLines.join("\n").trim();
+  }
+
+  return { sections, preamble };
+}
+
+/**
+ * Serialize a SectionMap back to heading-delimited markdown.
+ * Preamble comes first, then headings in the specified order.
+ * Headings not in the order array are appended at the end.
+ */
+export function serializeSections(map: SectionMap, order?: string[]): string {
+  const parts: string[] = [];
+  if (map.preamble) parts.push(map.preamble);
+
+  const headings = order ? [...new Set([...order, ...map.sections.keys()])] : [...map.sections.keys()];
+
+  for (const h of headings) {
+    const content = map.sections.get(h);
+    if (content !== undefined) {
+      parts.push(`## ${h}\n\n${content}`);
+    }
+  }
+
+  return `${parts.join("\n\n")}\n`;
+}
+
+/**
+ * Tolerant getter — returns undefined for missing sections, never throws.
+ */
+export function getSection(map: SectionMap, heading: string): string | undefined {
+  return map.sections.get(heading);
+}

package/src/flow/run-manager.ts

@@ -0,0 +1,129 @@
+/**
+ * Create/load/update runs/<run-id>/ subdirectories in .muonroi-flow/.
+ *
+ * Run IDs are sortable (Date.now().toString(36)) + collision-safe
+ * (randomBytes(2).toString('hex')).
+ */
+
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { readArtifact, writeArtifact } from "./artifact-io.js";
+import type { SectionMap } from "./parser.js";
+
+export interface RunState {
+  id: string;
+  roadmap: SectionMap;
+  state: SectionMap;
+  delegations: SectionMap;
+  grayAreas: SectionMap;
+}
+
+const RUN_FILES = ["roadmap.md", "state.md", "delegations.md", "gray-areas.md"] as const;
+
+/**
+ * Generate a sortable, human-readable, collision-safe run ID.
+ * Format: Date.now().toString(36) + randomBytes(2).toString('hex')
+ */
+function generateRunId(): string {
+  return Date.now().toString(36) + randomBytes(2).toString("hex");
+}
+
+/**
+ * Create a new run directory with 4 empty .md files.
+ * Initializes state.md with Resume Digest and Experience Snapshot headings.
+ */
+export async function createRun(flowDir: string): Promise<RunState> {
+  const id = generateRunId();
+  const runDir = path.join(flowDir, "runs", id);
+  await fs.mkdir(runDir, { recursive: true });
+
+  // Create empty files
+  for (const file of RUN_FILES) {
+    await fs.writeFile(path.join(runDir, file), "", "utf8");
+  }
+
+  // Initialize state.md with required headings
+  const stateMap: SectionMap = {
+    preamble: "",
+    sections: new Map([
+      ["Resume Digest", ""],
+      ["Experience Snapshot", ""],
+    ]),
+  };
+  await writeArtifact(path.join(flowDir, "runs", id), "state.md", stateMap);
+
+  // Return the initial RunState
+  const emptyMap: SectionMap = { preamble: "", sections: new Map() };
+  return {
+    id,
+    roadmap: emptyMap,
+    state: stateMap,
+    delegations: emptyMap,
+    grayAreas: emptyMap,
+  };
+}
+
+/**
+ * Load a run by ID. Returns null if the run directory does not exist.
+ */
+export async function loadRun(flowDir: string, runId: string): Promise<RunState | null> {
+  const runDir = path.join(flowDir, "runs", runId);
+
+  try {
+    await fs.access(runDir);
+  } catch {
+    return null;
+  }
+
+  const roadmap = (await readArtifact(runDir, "roadmap.md")) ?? {
+    preamble: "",
+    sections: new Map(),
+  };
+  const state = (await readArtifact(runDir, "state.md")) ?? {
+    preamble: "",
+    sections: new Map(),
+  };
+  const delegations = (await readArtifact(runDir, "delegations.md")) ?? {
+    preamble: "",
+    sections: new Map(),
+  };
+  const grayAreas = (await readArtifact(runDir, "gray-areas.md")) ?? {
+    preamble: "",
+    sections: new Map(),
+  };
+
+  return { id: runId, roadmap, state, delegations, grayAreas };
+}
+
+/**
+ * Read the active run ID from the top-level state.md "Active Run" section.
+ * Returns null if no active run is set or section is missing/empty.
+ */
+export async function getActiveRunId(flowDir: string): Promise<string | null> {
+  const stateMap = await readArtifact(flowDir, "state.md");
+  if (!stateMap) return null;
+  const section = stateMap.sections.get("Active Run");
+  if (!section?.trim()) return null;
+  return section.trim();
+}
+
+/**
+ * Write the active run ID to the top-level state.md "Active Run" section.
+ */
+export async function setActiveRunId(flowDir: string, id: string): Promise<void> {
+  let stateMap = await readArtifact(flowDir, "state.md");
+  if (!stateMap) {
+    stateMap = { preamble: "", sections: new Map() };
+  }
+  stateMap.sections.set("Active Run", id);
+  await writeArtifact(flowDir, "state.md", stateMap);
+}
+
+/**
+ * Write a run file atomically.
+ */
+export async function updateRunFile(flowDir: string, runId: string, filename: string, map: SectionMap): Promise<void> {
+  const runDir = path.join(flowDir, "runs", runId);
+  await writeArtifact(runDir, filename, map);
+}

package/src/flow/scaffold.ts

@@ -0,0 +1,52 @@
+/**
+ * Directory scaffolding for .muonroi-flow/.
+ *
+ * Creates the locked directory structure on first access. Idempotent —
+ * second call does not overwrite existing files.
+ */
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+export const FLOW_DIR_NAME = ".muonroi-flow";
+
+const TOP_LEVEL_FILES = ["roadmap.md", "state.md", "backlog.md", "decisions.md"];
+const SUBDIRS = ["history", "runs"];
+
+/**
+ * Ensure the .muonroi-flow/ directory exists with the locked structure:
+ *
+ * .muonroi-flow/
+ * ├── roadmap.md
+ * ├── state.md
+ * ├── backlog.md
+ * ├── decisions.md
+ * ├── history/
+ * └── runs/
+ *
+ * Returns the absolute path to the .muonroi-flow/ directory.
+ * Only creates files if they do NOT already exist (idempotent).
+ */
+export async function ensureFlowDir(cwd: string): Promise<string> {
+  const flowDir = path.join(cwd, FLOW_DIR_NAME);
+
+  // Create the root directory and subdirectories
+  await fs.mkdir(flowDir, { recursive: true });
+  for (const sub of SUBDIRS) {
+    await fs.mkdir(path.join(flowDir, sub), { recursive: true });
+  }
+
+  // Create top-level files only if absent (idempotent)
+  for (const file of TOP_LEVEL_FILES) {
+    const filePath = path.join(flowDir, file);
+    try {
+      await fs.access(filePath);
+      // File exists — do not overwrite
+    } catch {
+      // ENOENT — create empty file
+      await fs.writeFile(filePath, "", "utf8");
+    }
+  }
+
+  return flowDir;
+}