@ionivetech/mugiwara 0.7.0 → 0.8.1

package/src/adaptive-budget.ts

@@ -0,0 +1,178 @@
+// src/adaptive-budget.ts
+// Phase 7 Adaptive Budget & Circuit Breaker — reservation, projection,
+// adaptive/expansion, progressive thresholds, circuit breaker, anomaly
+// (Native Cost Governor, plan §51 Phase 7, §24–§29).
+//
+// Boundary: pure verdict functions over explicit inputs (unit-testable), plus a
+// record helper that persists via the sanitized recordOptDecision (§41). No new
+// config keys; savepoint.sh/lane-base.sh untouched. The crew acts — this module
+// records.
+
+import { recordOptDecision } from './cost.ts';
+
+// ── Budget reservation (§25) ──
+
+export type BudgetReservation = { remaining: number; expected_max: number; available: number; reserved: number };
+
+export function reserveBudget(input: { remaining: number; expected_max: number }): BudgetReservation {
+  const reserved = input.expected_max;
+  const available = Math.max(0, input.remaining - reserved);
+  return { remaining: input.remaining, expected_max: input.expected_max, available, reserved };
+}
+
+// ── Budget projection (§26) ──
+
+export type BudgetProjection = {
+  current: number;
+  remaining_required: number;
+  expected_conditional: number;
+  possible_healing: number;
+  projected_min: number;
+  projected_max: number;
+};
+
+export function projectBudget(input: {
+  current: number;
+  remaining_required: number;
+  expected_conditional: number;
+  possible_healing: number;
+}): BudgetProjection {
+  const projected_min = input.current + input.remaining_required + input.expected_conditional;
+  const projected_max = projected_min + input.possible_healing;
+  return {
+    current: input.current,
+    remaining_required: input.remaining_required,
+    expected_conditional: input.expected_conditional,
+    possible_healing: input.possible_healing,
+    projected_min,
+    projected_max,
+  };
+}
+
+// ── Evidence-backed expansion (§27) ──
+
+export type ExpansionInput = {
+  reason: string;
+  has_evidence: boolean;
+  scope_expanded?: boolean;
+  security_path?: boolean;
+  test_surface_expanded?: boolean;
+  architecture_dependency?: boolean;
+  legitimate_healing?: boolean;
+};
+
+export type ExpansionVerdict = { allowed: boolean; reason: string };
+
+const VALID_REASONS = new Set([
+  'scope legitimately expanded',
+  'security-sensitive path',
+  'test surface larger',
+  'architecture dependency',
+  'legitimate healing',
+]);
+
+function isValidReason(reason: string): boolean {
+  return VALID_REASONS.has(reason);
+}
+
+function hasValidFlag(input: ExpansionInput): boolean {
+  return !!(
+    input.scope_expanded ||
+    input.security_path ||
+    input.test_surface_expanded ||
+    input.architecture_dependency ||
+    input.legitimate_healing
+  );
+}
+
+export function evaluateExpansion(input: ExpansionInput): ExpansionVerdict {
+  if (!input.has_evidence) {
+    return { allowed: false, reason: 'deny — no evidence' };
+  }
+  if (!input.reason || !isValidReason(input.reason)) {
+    return { allowed: false, reason: `deny — invalid reason: ${input.reason || '(empty)'}` };
+  }
+  if (!hasValidFlag(input)) {
+    return { allowed: false, reason: `deny — valid reason ${input.reason} but no matching flag set` };
+  }
+  return { allowed: true, reason: `allow — ${input.reason} with evidence` };
+}
+
+// ── Progressive thresholds (§28) ──
+
+export type AdaptiveStatus = 'ok' | 'optimize' | 'aggressive' | 'protect' | 'pause' | 'warning' | 'stop';
+
+export function checkProgressiveThreshold(input: { budget: number; used: number }): { status: AdaptiveStatus; pct: number } {
+  const pct = input.budget > 0 ? Math.round((input.used / input.budget) * 100) : 0;
+  let status: AdaptiveStatus = 'ok';
+  if (pct >= 300) status = 'stop';
+  else if (pct >= 150) status = 'warning';
+  else if (pct >= 100) status = 'pause';
+  else if (pct >= 90) status = 'protect';
+  else if (pct >= 75) status = 'aggressive';
+  else if (pct >= 60) status = 'optimize';
+  return { status, pct };
+}
+
+// ── Cost circuit breaker (§29) ──
+
+export type CircuitBreakerInput = {
+  expected: number;
+  actual: number;
+  progress_delta: number;
+  scope_expanded: boolean;
+  evidence_delta: number;
+};
+
+export type CircuitBreakerVerdict = { tripped: boolean; reason: string };
+
+export function checkCircuitBreaker(input: CircuitBreakerInput): CircuitBreakerVerdict {
+  // note: double-threshold (actual >= expected*2), tune if §29 needs finer signal
+  const doubled = input.expected * 2;
+  const noProgress = input.progress_delta === 0;
+  const noScopeOrEvidence = !input.scope_expanded && input.evidence_delta === 0;
+  const overDoubled = input.actual >= doubled;
+  if (overDoubled && noProgress && noScopeOrEvidence) {
+    return { tripped: true, reason: `breaker tripped — actual ${input.actual} ≥ 2× expected ${input.expected} with no progress/scope/evidence` };
+  }
+  if (!overDoubled) return { tripped: false, reason: `no breaker — actual ${input.actual} < 2× expected ${input.expected}` };
+  if (!noProgress) return { tripped: false, reason: 'no breaker — progress made' };
+  return { tripped: false, reason: 'no breaker — scope expanded or evidence gained' };
+}
+
+// ── Budget anomaly (§24, re-consumes slop 5k-zero-progress signal) ──
+
+export type BudgetAnomalyInput = {
+  progress_before: number;
+  progress_after: number;
+  tokens_before: number;
+  tokens_after: number;
+};
+
+export type BudgetAnomaly = { anomaly: boolean; reason: string };
+
+export function detectBudgetAnomaly(input: BudgetAnomalyInput): BudgetAnomaly {
+  const tokens_delta = input.tokens_after - input.tokens_before;
+  const progress_delta = input.progress_after - input.progress_before;
+  if (tokens_delta >= 5000 && progress_delta === 0) {
+    return { anomaly: true, reason: `anomaly — ${tokens_delta} tokens with no progress` };
+  }
+  if (tokens_delta < 5000 && progress_delta === 0) {
+    return { anomaly: false, reason: `no anomaly — ${tokens_delta} tokens below 5k floor` };
+  }
+  return { anomaly: false, reason: `no anomaly — progress ${progress_delta} over ${tokens_delta} tokens` };
+}
+
+// ── Decision trail (§41) ──
+
+export function recordBudgetDecision(
+  missionDir: string,
+  d: { decision: string; reason: string; evidence?: string },
+): void {
+  recordOptDecision(missionDir, {
+    actor: 'budget-governor',
+    decision: d.decision,
+    reason: d.reason,
+    evidence: d.evidence,
+  });
+}

package/src/args.ts

@@ -6,11 +6,12 @@ export type Args = {
   flags: Record<string, FlagValue>;
 };
 
-const VALUE_FLAGS: Record<string, string> = { '--project': 'project', '--target': 'target', '--before': 'before' };
+const VALUE_FLAGS: Record<string, string> = { '--project': 'project', '--target': 'target', '--before': 'before', '--backend': 'backend', '--mission': 'mission' };
 const BOOL_FLAGS: Record<string, string> = {
   '--global': 'global', '--yes': 'yes', '-y': 'yes', '--force': 'force',
   '--dry-run': 'dryRun', '--keep-logs': 'keepLogs', '--check': 'check', '--all': 'all', '--verify': 'verify',
-  '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
+  '--gen-key': 'genKey', '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
+  '--json': 'json', '--ledger': 'ledger',
 };
 
 export function parseArgs(argv: string[]): Args {

package/src/budget.ts

@@ -8,25 +8,16 @@
 // Token telemetry stays honest elsewhere: the estimator remains the default;
 // `tokens_source: reported` activates only where the harness exposes real
 // usage (see docs/concepts/cost.md). This module does not estimate tokens.
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { readConfig } from './config.ts';
 
 export function readBudgetConfig(projectDir: string): number {
-  for (const base of [projectDir, homedir()]) {
-    const file = join(base, '.mugiwara', 'config');
-    if (!existsSync(file)) continue;
-    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
-      const t = line.trim();
-      if (!t || t.startsWith('#')) continue;
-      const eq = t.indexOf('=');
-      if (eq === -1) continue;
-      if (t.slice(0, eq).trim() !== 'context_budget_chars') continue;
-      const n = Number(t.slice(eq + 1).trim());
-      return Number.isFinite(n) && n > 0 ? n : 0;
-    }
-  }
-  return 0; // unset — measurement still recorded, never enforced
+  const cfg = readConfig(projectDir);
+  const raw = cfg.context_budget_chars;
+  if (raw === undefined || raw === '') return 0;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 0;
 }
 
 /** Sum of bytes across the trail: top-level *.md + flows/* (legacy waves/* counts too). */
@@ -54,3 +45,14 @@ export function formatFootprint(chars: number, budget: number): string {
     ? `${base} — OVER budget ${budget}`
     : `${base} (budget ${budget})`;
 }
+
+// ── Auto-compress threshold (T4) — 80% of budget ───────────────────────────
+export const COMPRESS_THRESHOLD_PCT = 0.8;
+
+export function shouldCompress(budget: number, chars: number): boolean {
+  return budget > 0 && chars > Math.floor(budget * COMPRESS_THRESHOLD_PCT);
+}
+
+export function compressThreshold(budget: number): number {
+  return Math.floor(budget * COMPRESS_THRESHOLD_PCT);
+}

package/src/check-artifacts.ts

@@ -0,0 +1,45 @@
+// src/check-artifacts.ts
+// Mission artifact gate (roadmap v0.8 item 4): every Lane 2+ mission must
+// carry its evidence trail — plan.md (the contract) and flows/* execution
+// evidence — or the archive refuses to fold, same as the secret gate.
+// Lane 0/1 missions are audit-lite: no plan/flows required.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface ArtifactCheck {
+  ok: boolean;
+  missing: string[];
+  lane: string | null;
+}
+
+const LANE_MIN = new Set(['standard', 'full', 'spike']);
+
+/** Lane 2+ (standard/full/spike) missions require the evidence trail. */
+export function checkMissionArtifacts(missionDir: string): ArtifactCheck {
+  const statePath = join(missionDir, 'state.json');
+  if (!existsSync(statePath)) {
+    // archived mission (report.md survives, state folded away) — nothing to check
+    return { ok: true, missing: [], lane: null };
+  }
+  let lane = 'unknown';
+  try {
+    const s = JSON.parse(readFileSyncSafe(statePath)) as Record<string, unknown>;
+    if (typeof s.lane === 'string') lane = s.lane;
+  } catch { /* unreadable state → treat as unknown lane */ }
+
+  if (!LANE_MIN.has(lane)) {
+    return { ok: true, missing: [], lane }; // audit-lite lanes pass without trail
+  }
+
+  const missing: string[] = [];
+  if (!existsSync(join(missionDir, 'plan.md'))) missing.push('plan.md');
+  const flowsDir = join(missionDir, 'flows');
+  const hasFlows = existsSync(flowsDir) && readdirSync(flowsDir).length > 0;
+  if (!hasFlows) missing.push('flows/ (no execution evidence)');
+
+  return { ok: missing.length === 0, missing, lane };
+}
+
+function readFileSyncSafe(p: string): string {
+  try { return readFileSync(p, 'utf8'); } catch { return ''; }
+}

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // src/cli.ts
-import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -12,9 +12,15 @@ import { installTo, removeInstalled, VERSION, ensureProjectGitignore, removeProj
 import { manifestPath, readManifest, writeManifest, type Scope } from './manifest.ts';
 import { resetMission, archiveMission } from './mission.ts';
 import { runScript, RUNNABLE } from './run.ts';
-import { readContinue, readState, resolveContinue, formatTable, formatResume, gitActor } from './continue.ts';
+import { readContinue, readState, resolveContinue, formatTable, formatResume, gitActor, hasLegacyLayout, CURRENT_SCHEMA_VERSION } from './continue.ts';
 import { blamePath } from './provenance.ts';
-import { signReport, verifyReport } from './sign.ts';
+import { signReport, verifyReport, ensurePureKey, hasMinisign } from './sign.ts';
+import { ensureConfig } from './config.ts';
+import { costEnvelope } from './cost.ts';
+import { computeLiveSlop } from './slop.ts';
+import { loadRegistry } from './evidence.ts';
+import { buildCostLedger, toCostJSON } from './reporting.ts';
+import { enforceHarnessPolicy } from './policy.ts';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
@@ -23,6 +29,30 @@ export async function run(argv: string[]): Promise<void> {
   const { command, flags, _ } = parseArgs(argv);
   if (flag(flags.help) || command === 'help') return help();
   if (flag(flags.version)) { console.log(`mugiwara ${VERSION}`); return; }
+  // harness.require_enforcement — enterprise gate: refuse rules-based harnesses
+  // (only opencode is runtime-enforced). Covers run/savepoint/archive/status
+  // + other workflow commands; install/update/uninstall/list are setup and bypass.
+  {
+    const bypass = new Set(['install', 'update', 'uninstall', 'list']);
+    if (!bypass.has(command)) {
+      const projectDirForHarness = resolve(str(flags.project) ?? process.cwd());
+      enforceHarnessPolicy(projectDirForHarness);
+    }
+  }
+  // Bootstrap default .mugiwara/config on any command when missing — including
+  // `continue`/`status` — so tier-3 agents that only mkdir .mugiwara still get
+  // a config. Also covered by readConfig() auto-create for non-CLI entry.
+  // Skipped for install/update --dry-run: a dry run must not mutate the project.
+  const isDryRunInstall = (command === 'install' || command === 'update') && flag(flags.dryRun);
+  if (!isDryRunInstall) {
+    const projectDir = resolve(str(flags.project) ?? process.cwd());
+    if (ensureConfig(projectDir)) {
+      console.log(`default .mugiwara/config written at ${join(projectDir, '.mugiwara', 'config')} (edit it to customise)`);
+    }
+  }
+  if (command === 'continue' || command === 'status') {
+    return command === 'continue' ? continueCmd(flags, _) : statusCmd(flags);
+  }
   switch (command) {
     case 'install': return install(flags);
     case 'update': return install({ ...flags, force: true });
@@ -33,11 +63,13 @@ export async function run(argv: string[]): Promise<void> {
     case 'clean': return cleanCmd(flags);
     case 'continue': return continueCmd(flags, _);
     case 'status': return statusCmd(flags);
+    case 'cost': return costCmd(flags, _);
     case 'run': return runCmd(flags, _);
     case 'savepoint': return runCmd(flags, ['run', 'savepoint.sh', ..._.slice(1)]);
     case 'blame': return blameCmd(flags, _);
     case 'handoff': return handoffCmd(flags, _);
     case 'sign': return signCmd(flags, _);
+    case 'migrate': return migrateCmd(flags);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
@@ -259,9 +291,27 @@ async function uninstall(flags: Args['flags']): Promise<void> {
   console.log(`OK removed ${removed.length} files`);
 }
 
+function legacyWarning(projectDir: string): void {
+  if (hasLegacyLayout(projectDir)) {
+    console.error('⚠ legacy layout detected (v0.6 .mugiwara/state/ — run `mugiwara migrate` to move to missions/)');
+  }
+}
+
+function schemaWarnings(projectDir: string): void {
+  const states = readState(projectDir);
+  for (const s of states) {
+    const v = s.schema_version;
+    if (v !== CURRENT_SCHEMA_VERSION) {
+      const wrote = v === null || v === undefined || v === '' ? 'unknown' : String(v);
+      console.error(`⚠ state written by v${wrote} (mission ${s.mission}${s.member ? `/${s.member}` : ''}) — current expects v${CURRENT_SCHEMA_VERSION} — run \`mugiwara migrate\``);
+    }
+  }
+}
+
 function list(flags: Args['flags']): void {
   const home = homedir();
   const projectDir = resolve(str(flags.project) ?? process.cwd());
+  legacyWarning(projectDir);
   let found = false;
   for (const [label, file] of [
     ['project', manifestPath({ scope: 'project', projectDir, home })],
@@ -293,6 +343,8 @@ function list(flags: Args['flags']): void {
  */
 function continueCmd(flags: Args['flags'], positionals: string[]): void {
   const projectDir = resolve(str(flags.project) ?? process.cwd());
+  legacyWarning(projectDir);
+  schemaWarnings(projectDir);
   const [mission, member] = positionals.slice(1);
   let entries = readContinue(projectDir);
 
@@ -335,6 +387,8 @@ function continueCmd(flags: Args['flags'], positionals: string[]): void {
 /** `mugiwara status` — one screen of computed mission state, no model needed. */
 function statusCmd(flags: Args['flags']): void {
   const projectDir = resolve(str(flags.project) ?? process.cwd());
+  legacyWarning(projectDir);
+  schemaWarnings(projectDir);
   const states = readState(projectDir);
   if (!states.length) { console.log('No mission state on disk.'); return; }
   const actor = flag(flags.all) ? null : gitActor(projectDir);
@@ -350,6 +404,61 @@ function statusCmd(flags: Args['flags']): void {
   }
 }
 
+/** `mugiwara cost [--mission <id>] [--json] [--ledger]` — show cost ledger, avoided work, efficiency, trail. */
+function costCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const mission = str(flags.mission) ?? positionals[1] ?? (() => {
+    const states = readState(projectDir);
+    if (states.length === 1) return states[0].mission;
+    if (states.length > 1) {
+      console.error('multiple missions in flight — specify --mission <id>');
+      process.exit(1);
+    }
+    return null;
+  })();
+  if (!mission) {
+    console.error('usage: mugiwara cost [--mission <id>] [--json] [--ledger] [--project <dir>]');
+    process.exit(1);
+  }
+  const missionDir = join(projectDir, '.mugiwara', 'missions', mission);
+  if (!existsSync(missionDir)) {
+    console.error(`No cost ledger found for mission "${mission}"`);
+    process.exit(1);
+  }
+  const states = readState(projectDir).filter((s) => s.mission === mission);
+  const envelope = states.length
+    ? costEnvelope({ lane: (states[0] as unknown as { lane?: string }).lane, budget: (states[0] as unknown as { budget?: number }).budget, tokens_est: (states[0] as unknown as { tokens_est?: number }).tokens_est })
+    : costEnvelope({ lane: 'full', tokens_est: 0 });
+  // live slop (§3.3): run existing detectors over state already available
+  // (heal cycle, context registry repeated reads) so slop_interventions is real.
+  const state0 = states[0] as unknown as { heal_cycle?: number };
+  let repeatedReads = 0;
+  try {
+    const reg = loadRegistry(missionDir);
+    repeatedReads = reg.reduce((s, e) => s + Math.max(e.reads - 1, 0), 0);
+  } catch {
+    repeatedReads = 0;
+  }
+  const liveSlop = computeLiveSlop({ heal_cycle: state0?.heal_cycle ?? 0, repeated_reads: repeatedReads });
+  const ledger = buildCostLedger({ missionDir, envelope, slopSummary: { interventions: liveSlop.interventions } });
+  if (flag(flags.json)) {
+    console.log(toCostJSON(ledger));
+    return;
+  }
+  console.log(`Cost envelope: ${ledger.envelope.status} ${ledger.envelope.pct}% (${ledger.envelope.used}/${ledger.envelope.planned})`);
+  console.log(`Avoided: ${ledger.avoided.stages_avoided} stages, ${ledger.avoided.contexts_avoided} contexts, ~${ledger.avoided.tokens_avoided_est} tokens`);
+  console.log(`Efficiency: reuse ${ledger.efficiency.reuse_rate}, dup ${ledger.efficiency.duplicate_avoidance_chars} chars, budget ${ledger.efficiency.budget_efficiency_pct}%`);
+  if (ledger.avoided.slop_interventions > 0) {
+    const roles = Object.entries(liveSlop.perRole).map(([r, n]) => `${r}:${n}`).join(', ');
+    console.log(`Slop: ${ledger.avoided.slop_interventions} intervention(s) — ${roles}`);
+  }
+  console.log(`Trail: ${ledger.trail.length} decisions`);
+  if (flag(flags.ledger) && ledger.trail.length) {
+    for (const t of ledger.trail.slice(0, 20)) console.log(`- ${t.ts} — ${t.actor}: ${t.decision} — reason: ${t.reason}${t.evidence ? ` — evidence: ${t.evidence}` : ''}`);
+    if (ledger.trail.length > 20) console.log(`… ${ledger.trail.length - 20} more`);
+  }
+}
+
 /** `mugiwara run <script.sh> [args]` — run a bundled harness script here. */
 function runCmd(flags: Args['flags'], positionals: string[]): void {
   const projectDir = resolve(str(flags.project) ?? process.cwd());
@@ -430,11 +539,109 @@ function handoffCmd(flags: Args['flags'], positionals: string[]): void {
   console.log(`\nwritten: ${out}`);
 }
 
-/** `mugiwara sign <mission>` / `--verify` — optional minisign attestation. */
+export function migrateCmd(flags: Args['flags']): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const dryRun = flag(flags.dryRun);
+  const legacyState = join(projectDir, '.mugiwara', 'state');
+  const legacyContinue = join(projectDir, '.mugiwara', 'continue');
+  const missionsRoot = join(projectDir, '.mugiwara', 'missions');
+  const moves: Array<{ src: string; dest: string }> = [];
+
+  const collect = (srcRoot: string, isContinue: boolean) => {
+    if (!existsSync(srcRoot)) return;
+    const walk = (dir: string) => {
+      for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else if (e.isFile() && e.name.endsWith('.json')) {
+          const rel = full.slice(srcRoot.length + 1);
+          let destRel: string;
+          if (isContinue) {
+            const parts = rel.split('/');
+            const file = parts.pop()!;
+            const mission = parts.join('/');
+            const stem = file.slice(0, -'.json'.length);
+            let destFile: string;
+            if (stem === 'state') destFile = 'continue.json';
+            else destFile = `continue-${stem}.json`;
+            destRel = mission ? join(mission, destFile) : destFile;
+          } else {
+            destRel = rel;
+          }
+          moves.push({ src: full, dest: join(missionsRoot, destRel) });
+        }
+      }
+    };
+    walk(srcRoot);
+  };
+  collect(legacyState, false);
+  collect(legacyContinue, true);
+
+  // legacy flat: .mugiwara/state.json style? treat any top-level .mugiwara/state*.json as not legacy missions but still warn
+  // Already covered by state/ dir; nothing more to collect.
+
+  if (!moves.length) {
+    if (!existsSync(legacyState) && !existsSync(legacyContinue)) {
+      console.log('no legacy layout found (.mugiwara/state/ does not exist)');
+    } else {
+      console.log('no legacy state files to migrate');
+    }
+    return;
+  }
+
+  for (const m of moves) {
+    console.log(`${dryRun ? 'would migrate' : 'migrated'} ${m.src} → ${m.dest}`);
+    if (!dryRun) {
+      mkdirSync(dirname(m.dest), { recursive: true });
+      try {
+        const raw = JSON.parse(readFileSync(m.src, 'utf8')) as Record<string, unknown>;
+        raw.schema_version = CURRENT_SCHEMA_VERSION;
+        writeFileSync(m.dest, JSON.stringify(raw, null, 2) + '\n');
+        rmSync(m.src, { force: true });
+      } catch {
+        try { renameSync(m.src, m.dest); } catch { /* ignore */ }
+      }
+    }
+  }
+  if (!dryRun) {
+    const prune = (root: string) => {
+      if (!existsSync(root)) return;
+      const walkPrune = (dir: string) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+          if (e.isDirectory()) walkPrune(join(dir, e.name));
+        }
+        try { if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+      };
+      walkPrune(root);
+      try { if (existsSync(root) && readdirSync(root).length === 0) rmSync(root, { recursive: true, force: true }); } catch { /* ignore */ }
+    };
+    prune(legacyState);
+    prune(legacyContinue);
+  }
+  console.log(`${dryRun ? 'would migrate' : 'migrated'} ${moves.length} file(s)${dryRun ? ' (dry run)' : ''}`);
+}
+
+/** `mugiwara sign <mission>` / `--verify` / `--gen-key` — optional attestation. */
 function signCmd(flags: Args['flags'], _: string[]): void {
   const projectDir = resolve(str(flags.project) ?? process.cwd());
+  if (flag(flags.genKey)) {
+    const backend = str(flags.backend) ?? 'auto';
+    const home = homedir();
+    if (backend === 'minisign') {
+      if (!hasMinisign()) { console.error('✗ minisign not installed — cannot generate keys with this backend'); process.exit(1); }
+      try {
+        execFileSync('minisign', ['-G'], { stdio: 'inherit' });
+        console.log('✓ minisign key pair generated in ~/.mugiwara/');
+        return;
+      } catch { console.error('✗ key generation failed'); process.exit(1); }
+    }
+    // pure (default)
+    const dir = ensurePureKey(home);
+    console.log(`✓ pure ed25519 key pair ready: ${join(dir, 'mugiwara.key')} / ${join(dir, 'mugiwara.pub')}`);
+    return;
+  }
   const mission = _[1];
-  if (!mission) { console.error('usage: mugiwara sign <mission> [--verify] [--project <dir>]'); process.exit(1); }
+  if (!mission) { console.error('usage: mugiwara sign <mission> [--verify] [--gen-key [--backend pure|minisign]] [--project <dir>]'); process.exit(1); }
   const missionDir = join(projectDir, '.mugiwara', 'missions', mission);
   if (!existsSync(missionDir)) { console.error(`no mission dir: ${missionDir}`); process.exit(1); }
   const r = flag(flags.verify) ? verifyReport(projectDir, missionDir) : signReport(projectDir, missionDir);
@@ -459,15 +666,21 @@ Usage:
   mugiwara continue <m> [member]
                          print the exact resume point for that mission/member
   mugiwara status        computed mission state: wave, tasks, lane, blockers, budget
+  mugiwara cost [--mission <id>] [--json] [--ledger]
+                         show cost ledger, avoided work, efficiency, trail (human + JSON)
   mugiwara blame <path>  provenance note on the last commit touching <path>
                          (fetch notes first: git fetch origin 'refs/notes/mugiwara:refs/notes/mugiwara')
   mugiwara handoff <m>   write .mugiwara/missions/<m>/handoff.md — a report the next
                          engineer can act on (computed state + staleness check)
-  mugiwara sign <m>      optional attestation: minisign-sign report.md (--verify to check)
+  mugiwara sign <m>      attestation: sign report.md (auto/minisign/pure/off; --verify to check)
+  mugiwara sign --gen-key [--backend pure|minisign]
+                         create signing keys (pure ed25519 default)
+  mugiwara migrate [--dry-run] [--project <dir>]
+                          move legacy .mugiwara/state/ layout to .mugiwara/missions/
   mugiwara run <script> [args...]
-                         run a bundled harness script here (${RUNNABLE.join(', ')})
+                          run a bundled harness script here (${RUNNABLE.join(', ')})
   mugiwara savepoint <mission> [member] [flow] [mode]
-                         shorthand for: mugiwara run savepoint.sh ...
+                          shorthand for: mugiwara run savepoint.sh ...
   mugiwara --help        this help
   mugiwara --version     print version