muonroi-cli 1.2.2 → 1.3.1

package/src/product-loop/artifact-io.ts

@@ -0,0 +1,239 @@
+import * as path from "node:path";
+import { readArtifact, writeArtifact } from "../flow/artifact-io.js";
+import type { IterationState, ProductRunManifest } from "./types.js";
+
+/**
+ * Write the product manifest to manifest.md.
+ */
+export async function writeManifest(flowDir: string, runId: string, m: ProductRunManifest): Promise<void> {
+  const runDir = path.join(flowDir, "runs", runId);
+  const manifestMap = (await readArtifact(runDir, "manifest.md")) ?? { preamble: "", sections: new Map() };
+
+  const lines = [
+    `Idea: ${m.idea}`,
+    `CapUsd: ${m.capUsd}`,
+    `MaxSprints: ${m.maxSprints}`,
+    `DoneThreshold: ${m.doneThreshold}`,
+    `CreatedAt: ${m.createdAt.toISOString()}`,
+  ];
+
+  if (m.stack) lines.push(`Stack: ${m.stack}`);
+  if (m.doneAt) lines.push(`DoneAt: ${m.doneAt.toISOString()}`);
+  if (m.aborted) lines.push(`Aborted: ${m.aborted}`);
+  if (m.verdict) {
+    lines.push(`VerdictPass: ${m.verdict.pass}`);
+    lines.push(`VerdictScore: ${m.verdict.score}`);
+    if (m.verdict.failedCondition) lines.push(`VerdictFailedCondition: ${m.verdict.failedCondition}`);
+    if (m.verdict.reason) lines.push(`VerdictReason: ${m.verdict.reason}`);
+  }
+
+  manifestMap.sections.set("Manifest", lines.join("\n"));
+  await writeArtifact(runDir, "manifest.md", manifestMap);
+}
+
+/**
+ * Read the product manifest from manifest.md.
+ */
+export async function readManifest(flowDir: string, runId: string): Promise<ProductRunManifest | null> {
+  const runDir = path.join(flowDir, "runs", runId);
+  const manifestMap = await readArtifact(runDir, "manifest.md");
+  const content = manifestMap?.sections.get("Manifest");
+  if (!content?.trim()) return null;
+
+  const lines = content.split("\n");
+  const data: any = {};
+  for (const line of lines) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const val = line.slice(idx + 1).trim();
+    data[key] = val;
+  }
+
+  const m: ProductRunManifest = {
+    idea: data.Idea,
+    capUsd: Number.parseFloat(data.CapUsd),
+    maxSprints: Number.parseInt(data.MaxSprints, 10),
+    doneThreshold: Number.parseFloat(data.DoneThreshold),
+    createdAt: new Date(data.CreatedAt),
+  };
+
+  if (data.Stack) m.stack = data.Stack;
+  if (data.DoneAt) m.doneAt = new Date(data.DoneAt);
+  if (data.Aborted) m.aborted = data.Aborted === "true";
+  if (data.VerdictPass !== undefined) {
+    m.verdict = {
+      pass: data.VerdictPass === "true",
+      score: Number.parseFloat(data.VerdictScore),
+      failedCondition: data.VerdictFailedCondition,
+      reason: data.VerdictReason,
+    };
+  }
+
+  return m;
+}
+
+/**
+ * Append a new iteration entry to iterations.md.
+ */
+export async function appendIteration(flowDir: string, runId: string, entry: IterationState): Promise<void> {
+  const runDir = path.join(flowDir, "runs", runId);
+  let iterationsMap = await readArtifact(runDir, "iterations.md");
+  if (!iterationsMap) {
+    iterationsMap = { preamble: "", sections: new Map([["Iterations", ""]]) };
+  }
+
+  const lines = [
+    `Sprint: ${entry.sprintN}`,
+    `Stage: ${entry.stage}`,
+    `ScoreBefore: ${entry.scoreBefore.toFixed(2)}`,
+    `ScoreAfter: ${entry.scoreAfter.toFixed(2)}`,
+    `Cost: ${entry.costUsd.toFixed(3)}`,
+    `Verify: ${entry.lastVerifyResult}`,
+    `CriteriaMet: ${entry.criteriaMet}`,
+    `CriteriaPartial: ${entry.criteriaPartial}`,
+    `CriteriaUnmet: ${entry.criteriaUnmet}`,
+  ];
+
+  if (entry.crashed) lines.push("Crashed: true");
+  if (entry.retryOf !== undefined) lines.push(`RetryOf: ${entry.retryOf}`);
+
+  iterationsMap.sections.set(`Sprint ${entry.sprintN}`, lines.join("\n"));
+  await writeArtifact(runDir, "iterations.md", iterationsMap);
+}
+
+/**
+ * Read all iterations from iterations.md.
+ */
+export async function readIterations(flowDir: string, runId: string): Promise<IterationState[]> {
+  const runDir = path.join(flowDir, "runs", runId);
+  const iterationsMap = await readArtifact(runDir, "iterations.md");
+  if (!iterationsMap) return [];
+
+  const results: IterationState[] = [];
+  // Sections are ordered by parse order, which matches append order for this file.
+  for (const [heading, content] of iterationsMap.sections.entries()) {
+    if (!heading.startsWith("Sprint ")) continue;
+
+    const lines = content.split("\n");
+    const data: any = {};
+    for (const line of lines) {
+      const idx = line.indexOf(":");
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim();
+      const val = line.slice(idx + 1).trim();
+      data[key] = val;
+    }
+
+    const iter: IterationState = {
+      sprintN: Number.parseInt(data.Sprint, 10),
+      stage: data.Stage,
+      scoreBefore: Number.parseFloat(data.ScoreBefore),
+      scoreAfter: Number.parseFloat(data.ScoreAfter),
+      criteriaMet: Number.parseInt(data.CriteriaMet, 10),
+      criteriaPartial: Number.parseInt(data.CriteriaPartial, 10),
+      criteriaUnmet: Number.parseInt(data.CriteriaUnmet, 10),
+      costUsd: Number.parseFloat(data.Cost),
+      lastVerifyResult: data.Verify,
+    };
+
+    if (data.Crashed === "true") iter.crashed = true;
+    if (data.RetryOf !== undefined) iter.retryOf = Number.parseInt(data.RetryOf, 10);
+
+    results.push(iter);
+  }
+
+  return results.sort((a, b) => a.sprintN - b.sprintN);
+}
+
+/**
+ * Mark a specific iteration as crashed.
+ */
+export async function markIterationCrashed(flowDir: string, runId: string, sprintN: number): Promise<void> {
+  const runDir = path.join(flowDir, "runs", runId);
+  const iterationsMap = await readArtifact(runDir, "iterations.md");
+  if (!iterationsMap) return;
+
+  const heading = `Sprint ${sprintN}`;
+  const content = iterationsMap.sections.get(heading);
+  if (content) {
+    if (!content.includes("Crashed: true")) {
+      iterationsMap.sections.set(heading, `${content}\nCrashed: true`);
+      await writeArtifact(runDir, "iterations.md", iterationsMap);
+    }
+  }
+}
+
+export interface Criterion {
+  id: string;
+  status: "met" | "partial" | "unmet";
+  evidence?: string;
+  sprint?: number;
+}
+
+/**
+ * Read all criteria from gray-areas.md.
+ */
+export async function readCriteria(flowDir: string, runId: string): Promise<Criterion[]> {
+  const runDir = path.join(flowDir, "runs", runId);
+  const grayMap = await readArtifact(runDir, "gray-areas.md");
+  if (!grayMap) return [];
+
+  const results: Criterion[] = [];
+  for (const [heading, content] of grayMap.sections.entries()) {
+    if (heading === "Resume Digest" || heading === "Manual Answers") continue;
+
+    const lines = content.split("\n");
+    const data: any = { status: "unmet" };
+    for (const line of lines) {
+      const idx = line.indexOf(":");
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim().toLowerCase();
+      const val = line.slice(idx + 1).trim();
+      data[key] = val;
+    }
+
+    results.push({
+      id: heading,
+      status: data.status as "met" | "partial" | "unmet",
+      evidence: data.evidence,
+      sprint: data.sprint ? Number.parseInt(data.sprint, 10) : undefined,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Update criteria in gray-areas.md.
+ * P8: also mirror to criteria.json (machine-readable snapshot for downstream
+ * consumers like /review and /execute). Markdown remains source of truth;
+ * the JSON snapshot is regenerated on every write so the two cannot drift.
+ */
+export async function updateCriteria(flowDir: string, runId: string, criteria: Criterion[]): Promise<void> {
+  const runDir = path.join(flowDir, "runs", runId);
+  const grayMap = (await readArtifact(runDir, "gray-areas.md")) ?? { preamble: "", sections: new Map() };
+
+  for (const c of criteria) {
+    const lines = [`Status: ${c.status}`];
+    if (c.evidence) lines.push(`Evidence: ${c.evidence}`);
+    if (c.sprint !== undefined) lines.push(`Sprint: ${c.sprint}`);
+
+    grayMap.sections.set(c.id, lines.join("\n"));
+  }
+
+  await writeArtifact(runDir, "gray-areas.md", grayMap);
+
+  // P8 mirror — non-fatal on failure since markdown above is canonical.
+  try {
+    const { syncCriteriaSnapshot } = await import("./typed-artifacts.js");
+    await syncCriteriaSnapshot(flowDir, runId, criteria);
+  } catch {
+    /* non-critical */
+  }
+}
+
+// P-B+C: project-context.md helpers re-exported for outer modules
+export { readProjectContext, writeProjectContext } from "./discovery-persistence.js";
+export { readPhasePlan, writePhasePlan } from "./phase-plan.js";
+export { appendCustomerDecision, markPhaseStatus, readPhaseStatus } from "./phase-runner.js";

package/src/product-loop/assumption-ledger.ts

@@ -0,0 +1,270 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import type { CouncilLLM, DebateState } from "../council/types.js";
+import { atomicWriteText } from "../storage/atomic-io.js";
+
+/**
+ * P6 - Assumption ledger.
+ *
+ * Council debate surfaces concerns and assumptions, but they get buried in
+ * prose. Sprint-runner then has no structured way to know "concern X is
+ * still unverified after sprint 3". This is how products ship with
+ * critical foundational assumptions never validated.
+ *
+ * The ledger captures every load-bearing claim a stance treats as fact,
+ * persists it to assumptions.json with a status enum, surfaces unverified
+ * high-confidence assumptions into each sprint's context, and adds done-gate
+ * condition #6 blocking the ship gate when high-confidence assumptions
+ * remain unverified.
+ *
+ * Storage shape (assumptions.json):
+ * {
+ *   "version": 1,
+ *   "assumptions": [
+ *     { id, claim, raisedBy, raisedAt, confidence, validationMethod,
+ *       status, evidence?, resolvedAt? }
+ *   ]
+ * }
+ */
+
+export type AssumptionConfidence = "high" | "medium" | "low";
+export type AssumptionStatus = "unverified" | "validated" | "refuted" | "deferred";
+
+export interface Assumption {
+  id: string;
+  claim: string;
+  raisedBy: string;
+  raisedAt: { phase: "research" | "scoping" | "sprint"; sprint?: number };
+  confidence: AssumptionConfidence;
+  validationMethod: string;
+  status: AssumptionStatus;
+  evidence?: string;
+  resolvedAt?: { sprint: number; reason: string };
+}
+
+export interface AssumptionLedger {
+  version: 1;
+  assumptions: Assumption[];
+}
+
+const LEDGER_VERSION = 1;
+
+function ledgerPath(flowDir: string, runId: string): string {
+  return path.join(flowDir, "runs", runId, "assumptions.json");
+}
+
+/**
+ * Read the current ledger. Returns an empty v1 ledger when missing.
+ */
+export async function readLedger(flowDir: string, runId: string): Promise<AssumptionLedger> {
+  const filePath = ledgerPath(flowDir, runId);
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw) as AssumptionLedger;
+    if (parsed.version !== LEDGER_VERSION) {
+      return { version: LEDGER_VERSION, assumptions: [] };
+    }
+    return parsed;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { version: LEDGER_VERSION, assumptions: [] };
+    }
+    throw err;
+  }
+}
+
+async function writeLedger(flowDir: string, runId: string, ledger: AssumptionLedger): Promise<void> {
+  const filePath = ledgerPath(flowDir, runId);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await atomicWriteText(filePath, JSON.stringify(ledger, null, 2));
+}
+
+/**
+ * Deterministic id from claim text: short hash of normalized claim so
+ * re-extraction of the same claim produces the same id (idempotent merge).
+ */
+function makeAssumptionId(claim: string): string {
+  const normalized = claim.toLowerCase().replace(/\s+/g, " ").trim();
+  let hash = 0;
+  for (let i = 0; i < normalized.length; i++) {
+    hash = ((hash << 5) - hash + normalized.charCodeAt(i)) | 0;
+  }
+  return "a_" + Math.abs(hash).toString(36).padStart(6, "0");
+}
+
+/**
+ * Extract assumptions from a completed debate via the leader LLM.
+ *
+ * Strategy: feed the leader the running summary plus the full archive of
+ * stance positions, ask for a JSON array of claims that are stated as fact
+ * but unverified. We accept JSON parse failure as "0 new assumptions" rather
+ * than throwing — the ledger is additive and can be filled retroactively
+ * by sprint feedback if extraction fails.
+ */
+export async function extractAssumptionsFromDebate(opts: {
+  debateState: DebateState;
+  leaderModelId: string;
+  llm: CouncilLLM;
+  phase: "research" | "scoping";
+}): Promise<Assumption[]> {
+  const archiveText = (opts.debateState.archive ?? [])
+    .map((a) => "[" + (a.stanceName ?? a.role) + "] " + (a.excerpt ?? ""))
+    .join("\n\n")
+    .slice(0, 8192);
+  const summary = (opts.debateState.runningSummary ?? "").slice(0, 2048);
+
+  const system =
+    "You are a software architect reviewing a multi-expert debate. " +
+    "Extract assumptions stated as fact by participants that are NOT yet verified. " +
+    "An assumption is a load-bearing claim about performance, behavior, " +
+    "compatibility, or external system contracts that the plan depends on. " +
+    "Output ONLY a JSON array (no markdown, no preamble): " +
+    '[{"claim":"...","raisedBy":"role or stance name","confidence":"high|medium|low",' +
+    '"validationMethod":"how to verify (one short sentence)"}]. ' +
+    "Confidence reflects how load-bearing the claim is: high = whole architecture depends on it; " +
+    "medium = section-level; low = nice-to-know. " +
+    "Skip opinions, preferences, and trivially-true statements. " +
+    "Return [] when no unverified claims appear in the debate.";
+
+  const prompt = "## Debate Summary\n" + summary + "\n\n## Stance Excerpts\n" + archiveText;
+
+  let raw: string;
+  try {
+    raw = await opts.llm.generate(opts.leaderModelId, system, prompt, 2048);
+  } catch {
+    return [];
+  }
+
+  const arr = parseAssumptionsJson(raw);
+  return arr.map((item) => ({
+    id: makeAssumptionId(item.claim),
+    claim: item.claim.trim(),
+    raisedBy: (item.raisedBy ?? "unknown").toString().trim() || "unknown",
+    raisedAt: { phase: opts.phase },
+    confidence: normalizeConfidence(item.confidence),
+    validationMethod: (item.validationMethod ?? "manual review").toString().trim() || "manual review",
+    status: "unverified",
+  }));
+}
+
+function parseAssumptionsJson(raw: string): Array<{
+  claim: string;
+  raisedBy?: string;
+  confidence?: string;
+  validationMethod?: string;
+}> {
+  const trimmed = raw.trim();
+  // Strip code fences if the LLM ignored "no markdown" instruction.
+  const stripped = trimmed
+    .replace(/^```(?:json)?\s*/i, "")
+    .replace(/```\s*$/i, "")
+    .trim();
+  try {
+    const parsed = JSON.parse(stripped);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (x: unknown): x is { claim: string } =>
+        typeof x === "object" && x !== null && typeof (x as { claim?: unknown }).claim === "string",
+    );
+  } catch {
+    return [];
+  }
+}
+
+function normalizeConfidence(raw: unknown): AssumptionConfidence {
+  if (raw === "high" || raw === "medium" || raw === "low") return raw;
+  return "medium";
+}
+
+/**
+ * Merge new assumptions into the ledger. Existing assumptions keyed by id are
+ * NOT overwritten — we keep the earliest raisedAt + raisedBy and any
+ * status/evidence already recorded.
+ */
+export async function mergeAssumptions(
+  flowDir: string,
+  runId: string,
+  newAssumptions: Assumption[],
+): Promise<AssumptionLedger> {
+  const ledger = await readLedger(flowDir, runId);
+  const byId = new Map(ledger.assumptions.map((a) => [a.id, a]));
+  for (const a of newAssumptions) {
+    if (!byId.has(a.id)) byId.set(a.id, a);
+  }
+  ledger.assumptions = Array.from(byId.values());
+  await writeLedger(flowDir, runId, ledger);
+  return ledger;
+}
+
+/**
+ * Update one assumption's status (validated / refuted / deferred) with
+ * evidence + resolving sprint. No-op when the id is missing.
+ */
+export async function resolveAssumption(opts: {
+  flowDir: string;
+  runId: string;
+  id: string;
+  status: AssumptionStatus;
+  evidence?: string;
+  sprintN: number;
+  reason: string;
+}): Promise<AssumptionLedger> {
+  const ledger = await readLedger(opts.flowDir, opts.runId);
+  const target = ledger.assumptions.find((a) => a.id === opts.id);
+  if (target) {
+    target.status = opts.status;
+    if (opts.evidence) target.evidence = opts.evidence;
+    target.resolvedAt = { sprint: opts.sprintN, reason: opts.reason };
+    await writeLedger(opts.flowDir, opts.runId, ledger);
+  }
+  return ledger;
+}
+
+/**
+ * Filter ledger for assumptions still blocking ship. The default policy
+ * blocks on high-confidence + unverified only — medium/low can ship as
+ * warnings.
+ */
+export function blockingAssumptions(ledger: AssumptionLedger): Assumption[] {
+  return ledger.assumptions.filter((a) => a.status === "unverified" && a.confidence === "high");
+}
+
+/**
+ * Format unverified assumptions for injection into sprint conversationContext.
+ * Sprint planners use this to prioritize validation work over feature work
+ * when foundational assumptions remain unchecked.
+ */
+export function formatUnverifiedForSprintContext(ledger: AssumptionLedger): string {
+  const unverified = ledger.assumptions.filter((a) => a.status === "unverified");
+  if (unverified.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push("## Unverified Assumptions (validate before adding features)");
+  for (const a of unverified) {
+    const tag = a.confidence === "high" ? "[CRITICAL]" : a.confidence === "medium" ? "[IMPORTANT]" : "[MINOR]";
+    lines.push("- " + tag + " " + a.claim);
+    lines.push("  validation: " + a.validationMethod);
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Render the ledger as a markdown summary for done-gate / verdict reports.
+ */
+export function renderLedgerSummary(ledger: AssumptionLedger): string {
+  if (ledger.assumptions.length === 0) return "_(no assumptions recorded)_";
+  const counts = { unverified: 0, validated: 0, refuted: 0, deferred: 0 };
+  for (const a of ledger.assumptions) counts[a.status]++;
+  return (
+    "Total: " +
+    ledger.assumptions.length +
+    " | unverified=" +
+    counts.unverified +
+    " validated=" +
+    counts.validated +
+    " refuted=" +
+    counts.refuted +
+    " deferred=" +
+    counts.deferred
+  );
+}

package/src/product-loop/circuit-breakers.ts

@@ -0,0 +1,76 @@
+import type { VerifyRecipe } from "../types/index.js";
+
+/**
+ * CB-1 Cost Projection
+ * formula: ewma = recent.reduce((avg, c) => avg * 0.7 + c * 0.3, recent[0])
+ * projection = ewma * 1.2
+ * halt if projection > (capUsd - spentUsd) * 1.5
+ */
+export function CB1_costProjection(
+  history: { actualCost: number }[],
+  capUsd: number,
+  spentUsd: number,
+  baselineCost?: number,
+): { halt: boolean; projection: number; headroom: number } {
+  const recent = history.slice(-3).map((s) => s.actualCost);
+
+  let ewma: number;
+  if (recent.length === 0) {
+    ewma = baselineCost ?? 0;
+  } else {
+    ewma = recent.reduce((avg, c) => avg * 0.7 + c * 0.3, recent[0]);
+  }
+
+  const projection = ewma * 1.2;
+  const remaining = capUsd - spentUsd;
+  const halt = projection > remaining * 1.5;
+
+  return { halt, projection, headroom: remaining };
+}
+
+/**
+ * CB-2 Oscillation
+ * halt = sprintN >= 3 && delta_t <= 0 && delta_t_minus_1 <= 0
+ * where delta_t = sprint[t].score - sprint[t-1].score
+ */
+export function CB2_oscillation(
+  history: { score: number }[],
+  sprintN: number,
+): { halt: boolean; delta_t: number; delta_t_minus_1: number } {
+  if (sprintN < 3 || history.length < 3) {
+    return { halt: false, delta_t: 0, delta_t_minus_1: 0 };
+  }
+
+  const t = history.length - 1;
+  const delta_t = history[t].score - history[t - 1].score;
+  const delta_t_minus_1 = history[t - 1].score - history[t - 2].score;
+
+  const halt = delta_t <= 0 && delta_t_minus_1 <= 0;
+
+  return { halt, delta_t, delta_t_minus_1 };
+}
+
+/**
+ * CB-3 Verify Blank
+ * halt = sprintN === 1 && (recipe === null || recipe.coverage === 0)
+ */
+export function CB3_verifyBlank(
+  sprintN: number,
+  recipe: VerifyRecipe | null,
+): { halt: boolean; reason?: "no_recipe" | "zero_coverage" } {
+  if (sprintN !== 1) {
+    return { halt: false };
+  }
+
+  if (recipe === null) {
+    return { halt: true, reason: "no_recipe" };
+  }
+
+  // recipe.coverage can be undefined, null, or 0.
+  // CONTEXT.md says: recipe.coverage === 0
+  if (recipe.coverage === 0) {
+    return { halt: true, reason: "zero_coverage" };
+  }
+
+  return { halt: false };
+}