@ionivetech/mugiwara 0.6.5 → 0.7.0

package/src/mission.ts

@@ -1,18 +1,55 @@
 // src/mission.ts
-// Mission-state helpers for the mugiwara CLI (installer + reset only).
-import { existsSync, rmSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
+// Mission-state helpers for the mugiwara CLI.
+import { existsSync, rmSync, readFileSync, readdirSync, mkdirSync, writeFileSync, renameSync, openSync, writeSync, closeSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
+import { checkTrail, formatIssues } from './integrity.ts';
+import { generateRollback } from './rollback.ts';
+import { writeProvenance } from './provenance.ts';
+import { rankFiles, renderRouting } from './routing.ts';
+import { formatFootprint, measureContextChars, readBudgetConfig } from './budget.ts';
+
+function isStateFile(f: string): boolean {
+  // state.json (solo) or <member>.json (team) — never continue*.json
+  const stem = f.replace(/\.json$/, '');
+  return f.endsWith('.json') && stem !== 'continue' && !stem.startsWith('continue-');
+}
+
+/** Primary state for closure artifacts: solo state.json wins over members. */
+function primaryState(dir: string, files: string[]): Record<string, unknown> | null {
+  const name = files.includes('state.json') ? 'state.json' : files.find((f) => f.endsWith('.json') && f !== 'continue.json' && !f.startsWith('continue-'));
+  if (!name) return null;
+  try {
+    return JSON.parse(readFileSync(join(dir, name), 'utf8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/** Files the mission changed, base..branch. Empty on any git failure — routing is best-effort. */
+function changedFiles(projectDir: string, state: Record<string, unknown> | null): string[] {
+  const base = typeof state?.base_sha === 'string' ? state.base_sha : '';
+  const branch = typeof state?.branch === 'string' ? state.branch : '';
+  if (!base || base === 'unknown' || !branch) return [];
+  try {
+    return execFileSync('git', ['diff', '--name-only', base, branch], {
+      cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 
 function activeActor(projectDir: string): string | null {
-  // state now lives at .mugiwara/state/<mission>/[member].json — scan the
+  // state now lives at .mugiwara/missions/<mission>/[member].json — scan the
   // latest state file for its actor
-  const stateDir = join(projectDir, '.mugiwara', 'state');
-  if (!existsSync(stateDir)) return null;
-  const missions = readdirSync(stateDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
+  const missionsDir = join(projectDir, '.mugiwara', 'missions');
+  if (!existsSync(missionsDir)) return null;
+  const missions = readdirSync(missionsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
   let latest: { actor: string; updated: number } | null = null;
   for (const mission of missions) {
-    const d = join(stateDir, mission);
-    for (const f of readdirSync(d).filter(f => f.endsWith('.json'))) {
+    const d = join(missionsDir, mission);
+    for (const f of readdirSync(d).filter(isStateFile)) {
       try {
         const s = JSON.parse(readFileSync(join(d, f), 'utf8'));
         const t = Date.parse(s.updated_at || '') || 0;
@@ -37,12 +74,9 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
 
   const removed: string[] = [];
   const kept: string[] = [];
-  for (const dir of ['spec', 'plans', 'results', 'review', 'issues', 'reports']) {
-    const p = join(root, dir);
-    if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(dir); }
-  }
-  // mission state + continue folders — state/<mission>/, continue/<mission>/
-  for (const dir of ['state', 'continue']) {
+  // current layout: everything lives in missions/. Legacy pre-0.7 dirs are
+  // removed too so an upgraded project ends up with one layout, not two.
+  for (const dir of ['missions', 'spec', 'plans', 'results', 'review', 'issues', 'reports', 'state', 'continue']) {
     const p = join(root, dir);
     if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(dir); }
   }
@@ -53,11 +87,14 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
       if (existsSync(p)) { rmSync(p); removed.push(f); }
     }
   }
+  // lessons.md moved to the .mugiwara root; legacy home was logs/
   if (!keepLogs) {
-    const p = join(root, 'logs');
-    if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push('logs'); }
-  } else if (existsSync(join(root, 'logs'))) {
-    kept.push('logs');
+    for (const p of [join(root, 'lessons.md'), join(root, 'logs')]) {
+      if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(p.startsWith(join(root, 'logs')) ? 'logs' : 'lessons.md'); }
+    }
+  } else {
+    if (existsSync(join(root, 'lessons.md'))) kept.push('lessons.md');
+    else if (existsSync(join(root, join('logs', 'lessons.md')))) kept.push(join('logs', 'lessons.md'));
   }
   for (const f of ['config', 'manifest.json', 'backup']) {
     if (existsSync(join(root, f))) kept.push(f);
@@ -68,108 +105,204 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
 export function archiveMission(projectDir: string, mission: string, opts: { dryRun?: boolean } = {}): { report: string | null; removed: string[]; kept: string[]; index?: string } {
   const { dryRun = false } = opts;
   const root = join(projectDir, '.mugiwara');
-  // mission allowlist — same as savepoint.sh / mission-report.sh. Dot-only
+  // mission allowlist — same as savepoint.sh. Dot-only
   // names (".", "..") would resolve upward through join(...,"..") and let
   // rmSync reach state.json/config outside the mission dir.
   if (!mission || /[^a-zA-Z0-9._-]/.test(mission) || /^\.+$/.test(mission)) throw new Error(`invalid mission name "${mission}" (allowlist: [a-zA-Z0-9._-], not a dot-path)`);
   const removed: string[] = [];
   const kept: string[] = [];
 
-  // A file belongs to this mission when stripping the optional YYYY-MM-DD-
-  // prefix leaves `<mission>.md` or `<mission>-<suffix>.md`. Covers both the
-  // bare names and the date-prefixed names the prose writes (audit-trail.md).
-  const belongs = (f: string): boolean => {
-    const base = f.replace(/^\d{4}-\d{2}-\d{2}-/, '');
-    return base === `${mission}.md` || base.startsWith(`${mission}-`);
-  };
-
-  // locate the report (the archive target that must survive). Reports are
-  // date-prefixed (`reports/YYYY-MM-DD-<mission>.md`); compare the stripped
-  // mission name so `bar-foo.md` is not mistaken for mission `foo`.
-  let report: string | null = null;
-  const reportsDir = join(root, 'reports');
-  if (existsSync(reportsDir)) {
-    const f = readdirSync(reportsDir).find(n => {
-      const m = n.match(/^(\d{4}-\d{2}-\d{2})-(.+)\.md$/);
-      return !!m && m[2] === mission;
-    });
-    if (f) report = join('reports', f);
-  }
+  const dir = join(root, 'missions', mission);
+  if (!existsSync(dir)) return { report: null, removed, kept };
 
-  // step results 01..05 + todos.md are evidence — kept; archive removes
-  // step results 01..05 + todos.md are evidence — kept; archive removes
-  // only spec/review/issues/logs + continue/<mission>/ + state/<mission>/
-  const resultsDir = join(root, 'results', mission);
-  if (existsSync(resultsDir)) {
-    for (const f of readdirSync(resultsDir)) {
-      kept.push(join('results', mission, f));
+  // Closure integrity gate: the trail validates itself before it
+  // folds. Dangling links, secrets, or missing evidence fail the archive.
+  if (!dryRun) {
+    const issues = checkTrail(dir, projectDir);
+    if (issues.length) {
+      throw new Error(`closure integrity gate failed — fix these before archiving:\n${formatIssues(issues)}`);
     }
   }
 
-  // spec, review, issues, per-mission decision log — bare + date-prefixed
-  const specDir = join(root, 'spec');
-  if (existsSync(specDir)) {
-    for (const f of readdirSync(specDir)) {
-      if (!belongs(f)) continue;
-      const p = join(specDir, f);
-      if (!dryRun) rmSync(p);
-      removed.push(join('spec', f));
-    }
-  }
+  const files = readdirSync(dir);
+  const state = primaryState(dir, files);
+  // unique models across every stage's state file (A4) — collected HERE,
+  // before the fold deletes the .json files; team members and solo
+  // re-savepoints each record the model that ran their stage.
+  const stageModels = [...new Set(files.filter(isStateFile).map((f) => {
+    try {
+      const s = JSON.parse(readFileSync(join(dir, f), 'utf8')) as Record<string, unknown>;
+      return typeof s.model === 'string' ? s.model : '';
+    } catch { return ''; }
+  }).filter(Boolean))];
 
-  for (const dir of ['review', 'issues']) {
-    const d = join(root, dir);
-    if (!existsSync(d)) continue;
-    for (const f of readdirSync(d)) {
-      if (!belongs(f)) continue;
-      const p = join(d, f);
-      if (!dryRun) rmSync(p, { force: true });
-      removed.push(join(dir, f));
+  // Cost surface — always readable section for the report (T8)
+  let costSection = '';
+  if (!dryRun && state) {
+    const chars = measureContextChars(dir);
+    const budget = readBudgetConfig(projectDir);
+    const footprintLine = formatFootprint(chars, budget);
+    if (budget && chars > budget) {
+      throw new Error(`closure context budget failed — ${footprintLine}. Trim the trail or raise context_budget_chars.`);
     }
-  }
-
-  const logsDir = join(root, 'logs');
-  if (existsSync(logsDir)) {
-    for (const f of readdirSync(logsDir)) {
-      if (!belongs(f)) continue;
-      const p = join(logsDir, f);
-      if (!dryRun) rmSync(p);
-      removed.push(join('logs', f));
+    const est = typeof state.tokens_est === 'number' ? state.tokens_est : 0;
+    const src = typeof state.tokens_source === 'string' ? state.tokens_source : 'computed';
+    const lane = typeof state.lane === 'string' ? state.lane : 'unknown';
+    // lane budgets for readable delta (from lane-base.sh, mirrored here for display only)
+    const laneBudget = lane === 'lean' ? 12000 : lane === 'standard' ? 25000 : lane === 'full' ? 50000 : lane === 'spike' ? 3000 : 0;
+    const effBudget = budget || laneBudget;
+    const pct = effBudget ? Math.round((est / effBudget) * 100) : 0;
+    const delta = effBudget ? (est <= effBudget ? `${(effBudget - est).toLocaleString()} under` : `${(est - effBudget).toLocaleString()} over`) : 'no budget configured';
+    const srcLabel = src === 'reported' ? 'provider-reported' : 'estimator';
+    // provider-reported rollup when any stage reported
+    let reportedTotal = 0;
+    let hasReported = false;
+    for (const f of files.filter(isStateFile)) {
+      try {
+        const s = JSON.parse(readFileSync(join(dir, f), 'utf8')) as Record<string, unknown>;
+        if (s.tokens_source === 'reported' && typeof s.tokens_est === 'number') {
+          reportedTotal += s.tokens_est;
+          hasReported = true;
+        }
+      } catch { /* corrupt — skip */ }
+    }
+    if (!hasReported && src === 'reported' && est > 0) {
+      reportedTotal = est;
+      hasReported = true;
     }
+    costSection = [
+      '## Cost',
+      '',
+      '| Metric | Value |',
+      '|--------|-------|',
+      `| **Tokens used** | ${est.toLocaleString()} (${srcLabel}) |`,
+      `| **Lane** | ${lane} (budget ${effBudget ? effBudget.toLocaleString() : '—'} · warn ${effBudget ? Math.round(effBudget * 1.5).toLocaleString() : '—'} · stop ${effBudget ? (effBudget * 3).toLocaleString() : '—'}) |`,
+      `| **Budget status** | ${effBudget ? `${pct}% of budget · ${delta} · ${est >= effBudget * 3 ? 'STOP' : est >= effBudget * 1.5 ? 'WARN' : 'OK'}` : 'no lane budget'} |`,
+      `| **Context footprint** | ${chars.toLocaleString()} chars${budget ? ` (budget ${budget.toLocaleString()})` : ' (no context budget configured)'} |`,
+    ].join('\n');
+    if (hasReported) {
+      costSection += `\n| **Provider total** | ${reportedTotal.toLocaleString()} (provider-reported — sum of reported stages) |`;
+    }
+    costSection += '\n';
   }
 
-  // continue/<mission>/ is a session handoff — remove this mission's folder
-  const contDir = join(root, 'continue', mission);
-  if (existsSync(contDir)) {
-    if (!dryRun) rmSync(contDir, { recursive: true, force: true });
-    removed.push(join('continue', mission));
+  // Fold order: narrative artifacts first, wave evidence last (chronological).
+  const FOLD_TOP = ['decisions.md', 'blockers.md', 'review.md', 'security.md', 'spec.md'];
+  const fold: string[] = [];
+  for (const f of FOLD_TOP) {
+    if (files.includes(f)) fold.push(f);
   }
-  // state/<mission>/ — remove this mission's computed state (archived)
-  const stateDir = join(root, 'state', mission);
-  if (existsSync(stateDir)) {
-    if (!dryRun) rmSync(stateDir, { recursive: true, force: true });
-    removed.push(join('state', mission));
+  // Flow artifacts: flows/ is the current layout; a legacy mission that still
+  // keeps waves/ folds from there so an upgrade never strands a trail.
+  const flowsDir = join(dir, 'flows');
+  const legacyWavesDir = join(dir, 'waves');
+  const artDir = existsSync(flowsDir) ? flowsDir : existsSync(legacyWavesDir) ? legacyWavesDir : flowsDir;
+  const artRel = artDir === legacyWavesDir ? 'waves' : 'flows';
+  if (existsSync(artDir)) {
+    for (const f of readdirSync(artDir).sort()) fold.push(join(artRel, f));
   }
 
-  // kept: report + the audit-trail survivors
-  if (report) kept.push(report);
-  for (const k of ['plans', 'config', join('logs', 'lessons.md')]) {
-    if (existsSync(join(root, k))) kept.push(k);
+  // The report survives: an existing report.md wins; otherwise the closure
+  // wave seeds it; otherwise it starts empty.
+  let report = '';
+  const reportPath = join(dir, 'report.md');
+  if (files.includes('report.md')) report = readFileSync(reportPath, 'utf8');
+  else if (existsSync(join(artDir, '06-closure.md'))) report = readFileSync(join(artDir, '06-closure.md'), 'utf8');
+
+  if (!dryRun) {
+    mkdirSync(dir, { recursive: true });
+    if (fold.length) {
+      const sections = fold.map((f) => {
+        const body = readFileSync(join(dir, f), 'utf8').trim();
+        const name = f.includes('/') ? (f.split('/').pop() ?? f) : f;
+        return `\n\n## Archived: ${name}\n\n${body}`;
+      }).join('');
+      // atomic: write the folded report to a temp file, then rename over the
+      // target. A crash mid-write must never leave a truncated report — the
+      // fold deletes the wave files right after, so a partial write loses them.
+      const tmp = `${reportPath}.tmp`;
+      const routingSection = state
+        ? renderRouting(rankFiles(changedFiles(projectDir, state), {
+            mission,
+            evidence: Array.isArray(state.evidence) ? (state.evidence as string[]) : [],
+            sensitive_paths: Array.isArray(state.sensitive_paths) ? (state.sensitive_paths as string[]) : [],
+          } as never), mission)
+        : '';
+      writeFileSync(tmp, report.trimEnd() + sections + (routingSection || '') + (costSection ? `\n${costSection}\n` : '') + '\n');
+      renameSync(tmp, reportPath);
+    }
+    for (const f of fold) {
+      rmSync(join(dir, f), { force: true, recursive: true });
+      removed.push(join('missions', mission, f));
+    }
+    // session state dies with the mission
+    for (const f of files.filter((f) => f.endsWith('.json'))) rmSync(join(dir, f), { force: true });
+    // flows/ may now be empty — remove the folder
+    if (existsSync(artDir) && readdirSync(artDir).length === 0) rmSync(artDir, { recursive: true, force: true });
+    // report.md must exist after archive — the closed marker `mugiwara clean`
+    // filters on. A stale in-flight mission folds nothing, so seed a stub.
+    if (!existsSync(reportPath)) {
+      writeFileSync(reportPath, `# Mission: ${mission}\n\nArchived before closure — no wave artifacts were present.\n`);
+    }
+    // Closure artifacts: executable rollback map and the
+    // two-layer provenance record. Best-effort — absent git/base degrades.
+    if (state && typeof state.branch === 'string') {
+      const rb = generateRollback(projectDir, dir, {
+        mission,
+        branch: state.branch,
+        baseSha: typeof state.base_sha === 'string' ? state.base_sha : 'unknown',
+      });
+      if (rb) kept.push(join('missions', mission, rb.file));
+      try {
+        writeProvenance(projectDir, dir, {
+          mission,
+          actor: typeof state.actor === 'string' ? state.actor : '',
+          lane: typeof state.lane === 'string' ? state.lane : '',
+          mode: typeof state.mode === 'string' ? state.mode : '',
+          branch: state.branch,
+          tasks_done: Number(state.tasks_done) || 0,
+          tasks_total: Number(state.tasks_total) || 0,
+          evidence: Array.isArray(state.evidence) ? (state.evidence as string[]) : [],
+          models: stageModels,
+        });
+        kept.push(join('missions', mission, 'provenance.md'));
+      } catch { /* provenance is additive; archive proceeds */ }
+    }
+  } else {
+    for (const f of fold) removed.push(join('missions', mission, f));
   }
+  removed.push(join('missions', mission, '<session state>'));
+  if (files.includes('plan.md')) kept.push(join('missions', mission, 'plan.md'));
+  if (files.includes('handoff.md')) kept.push(join('missions', mission, 'handoff.md'));
+  kept.push(join('missions', mission, 'report.md'));
 
-  // summary index: append one line per archived mission (retention aid),
-  // idempotently — never duplicate a line for an already-indexed mission.
+  // summary index: append one line per archived mission (retention aid).
+  // Atomic-append contract (finding A3): the line is written as ONE write()
+  // on an O_APPEND fd — POSIX positions O_APPEND writes atomically, so
+  // concurrent archivers never overwrite each other's bytes, and a small
+  // (<4k) single write does not interleave in practice. The pre-read
+  // idempotency check below still has a benign race window under true
+  // concurrency: two racers may both see the line missing and both append.
+  // That is a duplicate line, not a lost one — duplicates are the preferred
+  // failure mode; any future consumer of index.md must dedupe lines on read.
+  // Header creation stays racy-but-safe: two first-appends may each prepend
+  // "# Mission index\n\n", and header-only-plus-lines remains valid markdown
+  // either way.
   let index: string | undefined;
-  const indexFile = join(root, 'reports', 'index.md');
-  const line = `- ${mission} — ${new Date().toISOString().slice(0, 10)}${report ? ` → ${report}` : ''}\n`;
+  const indexFile = join(root, 'index.md');
+  const line = `- ${mission} — ${new Date().toISOString().slice(0, 10)}\n`;
   if (!dryRun) {
-    mkdirSync(join(root, 'reports'), { recursive: true });
     const existing = existsSync(indexFile) ? readFileSync(indexFile, 'utf8') : '';
     if (!existing.split(/\r?\n/).some(l => l.startsWith(`- ${mission} —`))) {
       const header = existing ? '' : '# Mission index\n\n';
-      appendFileSync(indexFile, header + line);
+      const fd = openSync(indexFile, 'a');
+      try {
+        writeSync(fd, header + line);
+      } finally {
+        closeSync(fd);
+      }
     }
-    index = join('reports', 'index.md');
+    index = 'index.md';
   }
-  return { report, removed, kept, index };
+  return { report: join('missions', mission, 'report.md'), removed, kept, index };
 }

package/src/policy.ts

@@ -0,0 +1,156 @@
+// src/policy.ts
+// mugiwara.policy.yml — org rules that override crew judgement.
+//
+// One optional file at the repo root; absent means today's
+// behavior everywhere. Policy only ever pushes UP (more scrutiny), never down:
+// lanes forced to full, coverage thresholds raised, paths flagged for human
+// approval.
+//
+// The parser is a deliberate YAML subset — nested maps, string arrays,
+// scalars — enough for the documented schema and nothing more. No dependency:
+// a governance file that needs an npm install to read would not be read.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type MugiwaraPolicy = {
+  lanes?: { force_full?: string[] };
+  gates?: {
+    coverage?: { new?: number; modified?: number };
+    require_human_approval?: string[];
+  };
+  evidence?: { required?: string[] };
+};
+
+const POLICY_FILES = ['mugiwara.policy.yml', 'mugiwara.policy.yaml'];
+const KNOWN_ROOTS = ['lanes', 'gates', 'evidence'];
+
+/**
+ * Minimal YAML subset: maps, `- item` string lists, scalars.
+ *
+ * A `key:` with no value stays pending on its scope until a deeper line turns
+ * it into a map (first mapping child) or a list (first `- ` child). Scopes are
+ * keyed by the indent of their own key line; any line at indent <= a scope's
+ * key indent leaves that scope. Enough for the documented schema, nothing more.
+ */
+export function parsePolicyYaml(text: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  type Scope = { keyIndent: number; obj: Record<string, unknown>; pending?: { key: string; indent: number } };
+  const stack: Scope[] = [{ keyIndent: -1, obj: root }];
+  const lines = text.split(/\r?\n/);
+
+  const process = (i: number): void => {
+    if (i >= lines.length) return;
+    const noComment = lines[i].replace(/(^|\s)#.*$/, '');
+    if (!noComment.trim()) return process(i + 1);
+    const indent = noComment.length - noComment.trimStart().length;
+    const line = noComment.trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].keyIndent) stack.pop();
+    const top = stack[stack.length - 1];
+
+    // A pending `parent:` whose first child this line is → become a map scope,
+    // then dispatch this same line into the new scope. A `- ` child instead
+    // turns the pending key into a LIST below — it must not materialize a map.
+    if (top.pending && !line.startsWith('- ') && indent > top.pending.indent && !Array.isArray(top.obj[top.pending.key])) {
+      const { key, indent: pIndent } = top.pending;
+      delete top.pending;
+      const created: Record<string, unknown> = {};
+      top.obj[key] = created;
+      stack.push({ keyIndent: pIndent, obj: created });
+      return process(i);
+    }
+
+    if (line.startsWith('- ')) {
+      if (top.pending) {
+        const existing = top.obj[top.pending.key];
+        const arr: unknown[] = Array.isArray(existing) ? existing : [];
+        arr.push(scalar(line.slice(2)));
+        top.obj[top.pending.key] = arr;
+      }
+      // stray items outside a pending key are ignored in this subset
+      return process(i + 1);
+    }
+
+    const colon = line.indexOf(':');
+    if (colon === -1) return process(i + 1); // not a mapping line in this subset
+    const key = line.slice(0, colon).trim();
+    const rest = line.slice(colon + 1).trim();
+    if (rest === '') {
+      top.pending = { key, indent };
+    } else {
+      top.obj[key] = scalar(rest);
+      delete top.pending;
+    }
+    process(i + 1);
+  };
+
+  process(0);
+  return root;
+}
+
+function scalar(v: string): unknown {
+  const t = v.trim().replace(/^["']|["']$/g, '');
+  if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+  if (t === 'true') return true;
+  if (t === 'false') return false;
+  return t;
+}
+
+export function loadPolicy(projectDir: string): MugiwaraPolicy | null {
+  for (const name of POLICY_FILES) {
+    const file = join(projectDir, name);
+    if (!existsSync(file)) continue;
+    return normalize(parsePolicyYaml(readFileSync(file, 'utf8')));
+  }
+  return null;
+}
+
+function normalize(raw: Record<string, unknown>): MugiwaraPolicy {
+  // A typo'd root key would otherwise silently disable the rule it carried.
+  for (const k of Object.keys(raw)) {
+    if (!KNOWN_ROOTS.includes(k)) throw new Error(`unknown policy key "${k}" (known: ${KNOWN_ROOTS.join(', ')})`);
+  }
+  const out: MugiwaraPolicy = {};
+  const lanes = raw.lanes as Record<string, unknown> | undefined;
+  if (lanes && Array.isArray(lanes.force_full)) out.lanes = { force_full: strings(lanes.force_full) };
+  const gates = raw.gates as Record<string, unknown> | undefined;
+  if (gates) {
+    out.gates = {};
+    const cov = gates.coverage as Record<string, unknown> | undefined;
+    if (cov) {
+      out.gates.coverage = {};
+      if (typeof cov.new === 'number') out.gates.coverage.new = cov.new;
+      if (typeof cov.modified === 'number') out.gates.coverage.modified = cov.modified;
+    }
+    if (Array.isArray(gates.require_human_approval))
+      out.gates.require_human_approval = strings(gates.require_human_approval);
+  }
+  const evidence = raw.evidence as Record<string, unknown> | undefined;
+  if (evidence && Array.isArray(evidence.required)) out.evidence = { required: strings(evidence.required) };
+  return out;
+}
+
+function strings(a: unknown[]): string[] {
+  return a.filter((x): x is string => typeof x === 'string' && x.length > 0);
+}
+
+/** Glob → RegExp: `**` crosses separators, `*` stays within one. */
+export function globToRegExp(glob: string): RegExp {
+  const esc = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  const src = esc.replace(/\*\*/g, '\u0000').replace(/\*/g, '[^/]*').replace(/\u0000/g, '.*');
+  return new RegExp(`^${src}$`);
+}
+
+/** Any changed path matching any policy glob? Returns the matching globs. */
+export function matchedGlobs(paths: string[], globs: string[]): string[] {
+  return globs.filter((g) => paths.some((p) => globToRegExp(g).test(p)));
+}
+
+/**
+ * Coverage thresholds: the max of the .mugiwara/config value (or its
+ * fallback) and any policy raise. Policy pushes up, never down.
+ */
+export function effectiveThreshold(configured: number, policyValue: number | undefined): number {
+  return Math.max(configured, policyValue ?? 0);
+}

package/src/provenance.ts

@@ -0,0 +1,116 @@
+// src/provenance.ts
+// Provenance ledger: line-of-sight from a commit to the
+// mission that produced it — which agent persona, which lane, verified by
+// what evidence. Distributed in two layers:
+//   1. a git note on refs/notes/mugiwara attached to the branch head
+//      (local precision archive; survives rebase via notes.rewriteRef)
+//   2. provenance.md in the mission dir, ready to paste as a PR comment
+//      (the layer every hosting UI can show)
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const NOTES_REF = 'refs/notes/mugiwara';
+
+/** Structural subset any mission state satisfies — keeps this import-free. */
+export type NoteSource = {
+  mission: string;
+  actor: string;
+  lane: string;
+  mode: string;
+  branch: string;
+  tasks_done: number;
+  tasks_total: number;
+  evidence: string[];
+  models?: string[];
+};
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+export function modelLabel(): string {
+  return process.env.MUGIWARA_MODEL?.trim()
+    || process.env.ANTHROPIC_MODEL?.trim()
+    || 'model-unrecorded (set MUGIWARA_MODEL to attribute)';
+}
+
+/** The provenance block — identical wording in the note and the md file. */
+export function buildNote(s: {
+  mission: string; actor: string; lane: string; mode: string; branch: string;
+  tasks_done: number; tasks_total: number; evidence: string[]; model?: string; models?: string[];
+}): string {
+  const gates = s.evidence.length ? s.evidence.join(' · ') : 'no evidence recorded';
+  // Per-stage attribution (A4): when flow history recorded models, render the
+  // unique set — a mid-mission switch must not collapse to the last env value.
+  // With nothing recorded, keep the env-fallback label wording.
+  const uniqModels = [...new Set((s.models ?? []).filter(Boolean))];
+  const modelPart = uniqModels.length ? `model(s): ${uniqModels.join(', ')}` : (s.model ?? modelLabel());
+  return [
+    `mission: ${s.mission}`,
+    `agent: ${s.actor || 'unknown'} · ${modelPart} · lane ${s.lane} · mode ${s.mode}`,
+    `tasks: ${s.tasks_done}/${s.tasks_total}`,
+    `gates/evidence: ${gates}`,
+    `branch: ${s.branch}`,
+    'human review: pending (PR review is the terminal gate)',
+  ].join('\n');
+}
+
+/** PR-paste-ready markdown wrapper around the same facts. */
+export function renderProvenanceMd(note: string, sha: string | null): string {
+  const lines = [
+    '# Provenance',
+    '',
+    '<!-- paste below into the PR description or a PR comment -->',
+    '',
+    '```',
+    note,
+    '```',
+    '',
+    sha ? `Commit: ${sha}` : 'Commit: not recorded (no git head resolved at closure)',
+    '',
+    'Query locally after pushing notes:',
+    '`git fetch origin refs/notes/mugiwara:refs/notes/mugiwara` then `mugiwara blame <path>`.',
+  ];
+  return lines.join('\n') + '\n';
+}
+
+export function attachGitNote(projectDir: string, branch: string, note: string): { sha: string } | null {
+  try {
+    let sha: string;
+    try {
+      sha = git(projectDir, ['rev-parse', '--verify', branch]);
+    } catch {
+      sha = git(projectDir, ['rev-parse', 'HEAD']);
+    }
+    git(projectDir, ['notes', '--ref=mugiwara', 'add', '-f', '-m', note, sha]);
+    return { sha };
+  } catch {
+    // not a repo, detached oddities, or notes disabled — degrade honestly
+    return null;
+  }
+}
+
+/** `mugiwara blame <path>` — last commit that touched the path + its note. */
+export function blamePath(projectDir: string, path: string): string {
+  let sha: string;
+  try {
+    sha = git(projectDir, ['log', '-1', '--format=%H', '--', path]);
+  } catch {
+    return `blame: not a git repository (${projectDir})`;
+  }
+  if (!sha) return `blame: no commit touches "${path}"`;
+  try {
+    const note = git(projectDir, ['notes', '--ref=mugiwara', 'show', sha]);
+    return `${path} @ ${sha.slice(0, 7)}\n${note}`;
+  } catch {
+    return `${path} @ ${sha.slice(0, 7)}\n(no mugiwara provenance note on this commit)`;
+  }
+}
+
+/** Closure hook: write provenance.md + attach the git note. */
+export function writeProvenance(projectDir: string, missionDir: string, state: NoteSource): void {
+  const note = buildNote(state);
+  const attached = attachGitNote(projectDir, state.branch, note);
+  writeFileSync(join(missionDir, 'provenance.md'), renderProvenanceMd(note, attached ? attached.sha : null));
+}