@ionivetech/mugiwara 0.7.0 → 0.8.0

package/scripts/benchmark-thresholds.json

@@ -0,0 +1,47 @@
+{
+  "workloads": [
+    {
+      "id": "lean-trivial",
+      "projected": 8000,
+      "overhead": 1000,
+      "context_max": 20000,
+      "evidence_min": 1,
+      "expected_surface": { "files": 2, "loc": 50 }
+    },
+    {
+      "id": "standard-feature",
+      "projected": 15000,
+      "overhead": 1500,
+      "context_max": 40000,
+      "evidence_min": 3,
+      "expected_surface": { "files": 8, "loc": 300 }
+    },
+    {
+      "id": "large-repo",
+      "projected": 22000,
+      "overhead": 2200,
+      "context_max": 80000,
+      "evidence_min": 5,
+      "expected_surface": { "files": 50, "loc": 2000 }
+    },
+    {
+      "id": "long-mission",
+      "projected": 23000,
+      "overhead": 2300,
+      "context_max": 90000,
+      "evidence_min": 5,
+      "expected_surface": { "files": 30, "loc": 1500 }
+    }
+  ],
+  "slop_floors": { "max_slop_events": 0 },
+  "regression": {
+    "allow_cost_down_only_when": ["correctness", "evidence", "security", "quality", "scope"]
+  },
+  "baselines": {
+    "correctness": 100,
+    "evidence": 5,
+    "security": 100,
+    "quality": 100,
+    "scope": 100
+  }
+}

package/scripts/check-doc-links.ts

@@ -16,8 +16,14 @@ function walk(d: string, out: string[] = []): string[] {
   return out;
 }
 const files: string[] = [];
-for (const r of ["docs", "examples"]) files.push(...walk(join(root, r)));
-for (const r of ["README.md", "ROADMAP.md"]) files.push(resolve(root, r));
+for (const r of ["docs", "examples"]) {
+  const p = join(root, r);
+  if (existsSync(p)) files.push(...walk(p));
+}
+for (const r of ["README.md", "ROADMAP.md"]) {
+  const p = resolve(root, r);
+  if (existsSync(p)) files.push(p);
+}
 
 let bad = 0;
 for (const f of files) {

package/scripts/gate-selftest.ts

@@ -578,6 +578,26 @@ console.log('\nT7 — evidence-thin gate');
   }
 }
 
+// --- Benchmark governor — tamper thresholds, prove harness goes red ---
+console.log('\nBenchmark governor — thresholds tamper');
+{
+  const threshFile = join(root, 'scripts', 'benchmark-thresholds.json');
+  if (!existsSync(threshFile)) {
+    console.log('  ⚠  benchmark-thresholds.json not found, skipping');
+  } else {
+    const original = readFileSync(threshFile, 'utf8');
+    try {
+      const data = JSON.parse(original);
+      data.workloads = data.workloads.map((w: Record<string, unknown>) => ({ ...w, projected: 0, overhead: 0 }));
+      writeFileSync(threshFile, JSON.stringify(data, null, 2));
+      assert('tampered thresholds → benchmark-governor fails', false, () => run('bench', 'bun scripts/benchmark-governor.ts'));
+    } finally {
+      writeFileSync(threshFile, original);
+      assert('restored → benchmark-governor passes', true, () => run('bench', 'bun scripts/benchmark-governor.ts'));
+    }
+  }
+}
+
 // --- DOCLINKS: a relative .md link that does not resolve must fail the gate ---
 console.log('\nDOCLINKS — doc link resolution');
 {

package/scripts/lib/lane-base.sh

@@ -7,10 +7,10 @@
 # LANE_BASE: token estimate for skills/agents loaded in this lane. Derived
 # from content word-sums × 1.35 (see scripts/lane-base.ts). spike is a
 # resize, not a rise — small base, tiny budget.
-LANE_BASE_lean=7000
-LANE_BASE_standard=13000
-LANE_BASE_full=23000
-LANE_BASE_spike=1000
+LANE_BASE_lean=8421
+LANE_BASE_standard=13325
+LANE_BASE_full=22016
+LANE_BASE_spike=5411
 
 # BUDGET: warn at 1.5×, stop at 3×.
 BUDGET_lean=12000

package/scripts/retrieval-eval.ts

@@ -93,14 +93,20 @@ interface Probe {
 // --- build index ---
 const index = buildIndex();
 
-// --- load cases ---
+// --- load cases (root + retrieval/ subdir for per-skill probes) ---
 const skills = readdirSync(skillsDir).filter(d => statSync(join(skillsDir, d)).isDirectory());
-const files = readdirSync(evalsDir).filter(f => f.endsWith('.json'));
+const rootCases = readdirSync(evalsDir).filter(f => f.endsWith('.json'));
+const retrievalDir = join(evalsDir, 'retrieval');
+const retrievalCases = existsSync(retrievalDir)
+  ? readdirSync(retrievalDir).filter(f => f.endsWith('.json')).map(f => join('retrieval', f))
+  : [];
+const files = [...rootCases, ...retrievalCases];
 const probes: Probe[] = [];
 const noSkillProbes: Probe[] = [];
 const covered = new Set<string>();
 
-for (const f of files) {
+for (const rel of files) {
+  const f = rel.includes('/') ? rel : rel;
   let c: CaseFile;
   try {
     c = JSON.parse(readFileSync(join(evalsDir, f), 'utf8'));

package/scripts/savepoint.sh

@@ -365,6 +365,22 @@ if [ "$HEAL_CYCLE" -ge "$HEAL_MAX_CYCLES" ] 2>/dev/null; then
   HEAL_HALT=true
 fi
 
+# depth flags — advisory → measured (roadmap v0.8 item 4). Read from config
+# like the other keys; computed into state.json so enforcement is a fact the
+# gates flow stage can read, not prose.
+DEPTH_REVIEW="full"; DEPTH_QUALITY="full"; DEPTH_VERIFY="off"
+if [ -f "$MUGIWARA_DIR/config" ]; then
+  _cfg_r=$(grep -E '^review_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$_cfg_r" ] && DEPTH_REVIEW="$_cfg_r"
+  _cfg_q=$(grep -E '^quality_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$_cfg_q" ] && DEPTH_QUALITY="$_cfg_q"
+  _cfg_v=$(grep -E '^verify_merged=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$_cfg_v" ] && DEPTH_VERIFY="$_cfg_v"
+fi
+case "$DEPTH_REVIEW" in full|standard|lean) ;; *) DEPTH_REVIEW="full" ;; esac
+case "$DEPTH_QUALITY" in full|standard|lean) ;; *) DEPTH_QUALITY="full" ;; esac
+case "$DEPTH_VERIFY" in on|off) ;; *) DEPTH_VERIFY="off" ;; esac
+
 # evidence paths — the mission's flow folder (quoted printf, no sed — mission
 # name is allowlisted above, but avoid sed metacharacter semantics entirely).
 # New missions use flows/; a legacy mission that already keeps waves/ stays on
@@ -498,6 +514,9 @@ const data = {
   heal_halt: process.argv[34] === 'true',
   delegate_threshold: parseInt(process.argv[35], 10) || 60,
   delegate_due: process.argv[36] === 'true',
+  review_depth: process.argv[38] || 'full',
+  quality_depth: process.argv[39] || 'full',
+  verify_merged: process.argv[40] || 'off',
   tokens_est: parseInt(process.argv[17], 10) || 0,
   tokens_source: process.argv[26] || 'computed',
   budget: parseInt(process.argv[18], 10) || 0,
@@ -517,7 +536,7 @@ require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\
   "$STATE_FILE" "$LANE_PREV" "$LANE_ROSE" "$TOKENS_SOURCE" "$LANE_PEAK" \
   "$LOC_INS" "$LOC_DEL" "$LOC_CHURN" "$MEMBER" "$VERBOSITY" \
   "$HEAL_MAX_CYCLES" "$HEAL_HALT" "$DELEGATE_THRESHOLD" "$DELEGATE_DUE" \
-  "$MODEL"
+  "$MODEL" "$DEPTH_REVIEW" "$DEPTH_QUALITY" "$DEPTH_VERIFY"
 
 if [ "$LANE_ROSE" = true ]; then
   echo "⚠ LANE ROSE: $LANE_PREV → $LANE ($LANE_REASON) — escalate per check-in protocol"

package/scripts/validate-content.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 // scripts/validate-content.ts
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { join, basename, dirname } from 'node:path';
 import { parseFrontmatter } from '../src/frontmatter.ts';
 
 const root = join(import.meta.dirname, '..', 'content');
@@ -28,6 +28,25 @@ function checkFile(file: string, wantName: string, kind: 'skill' | 'agent'): Rec
     if (bullets.length > 4) errors.push(`skill ${file}: "## Skip when" block exceeds 4 bullets`);
   }
   if (kind === 'skill' && !body.includes('## Red flags')) errors.push(`skill ${file}: missing required "## Red flags" block`);
+  if (kind === 'skill') {
+    // gate_artifact (roadmap item 2): a declared artifact must name a
+    // verifiable path (flows/ mission evidence, plan.md, or a references/
+    // file that must actually exist beside the skill).
+    const ga = (data as Record<string, unknown>).gate_artifact;
+    if (ga !== undefined) {
+      const v = String(ga).trim();
+      if (!v) errors.push(`skill ${file}: gate_artifact declared but empty`);
+      else if (!/(flows\/|plan\.md|references\/)/.test(v)) {
+        errors.push(`skill ${file}: gate_artifact "${v}" must name a flows/, plan.md, or references/ path`);
+      } else {
+        const refMatch = v.match(/(references\/[\w./-]+\.md)/);
+        if (refMatch) {
+          const refPath = join(dirname(file), refMatch[1]);
+          if (!existsSync(refPath)) errors.push(`skill ${file}: gate_artifact references "${refMatch[1]}" but file does not exist`);
+        }
+      }
+    }
+  }
   if (kind === 'skill') {
     const lines = body.split(/\r?\n/);
     const headingRe = /^## /;
@@ -357,7 +376,7 @@ if (integrityArg !== -1) {
     const constants = readFileSync(src, 'utf8');
     const docs = ['docs/concepts/cost.md', 'docs/concepts/lanes.md', 'README.md'];
     const expected: [string, string][] = [
-      ['lean', '7,000'], ['standard', '13,000'], ['full', '23,000'],
+      ['lean', '8,000'], ['standard', '13,000'], ['full', '22,000'],
       ['lean', '12,000'], ['standard', '25,000'], ['full', '50,000'],
     ];
     for (const doc of docs) {
@@ -393,7 +412,7 @@ if (integrityArg !== -1) {
         }
       }
     }
-  if (!constants.includes('LANE_BASE_lean=7000')) errors.push('doc-integrity: source lane-base.sh lean base drifted (expected 7000)');
+  if (!constants.includes('LANE_BASE_lean=8421')) errors.push('doc-integrity: source lane-base.sh lean base drifted (expected 8421)');
   if (!constants.includes('BUDGET_full=50000')) errors.push('doc-integrity: source lane-base.sh full budget drifted (expected 50000)');
 }
 }

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). */

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

@@ -14,7 +14,12 @@ import { resetMission, archiveMission } from './mission.ts';
 import { runScript, RUNNABLE } from './run.ts';
 import { readContinue, readState, resolveContinue, formatTable, formatResume, gitActor } 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';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
@@ -23,6 +28,23 @@ 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; }
+  // `continue` and `status` are read-only position commands: dispatch before
+  // config bootstrap so a fresh project never gets a .mugiwara/config created
+  // and no setup chatter is printed before missions/members are listed.
+  if (command === 'continue' || command === 'status') {
+    return command === 'continue' ? continueCmd(flags, _) : statusCmd(flags);
+  }
+  // A command on a fresh project must be immediately usable — bootstrap the
+  // default .mugiwara/config when it is missing (not only at install time).
+  // Skipped for install/update --dry-run: a dry run must not mutate the
+  // project (the installer writes the config itself on a real install).
+  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)`);
+    }
+  }
   switch (command) {
     case 'install': return install(flags);
     case 'update': return install({ ...flags, force: true });
@@ -33,6 +55,7 @@ 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, _);
@@ -350,6 +373,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 +508,27 @@ function handoffCmd(flags: Args['flags'], positionals: string[]): void {
   console.log(`\nwritten: ${out}`);
 }
 
-/** `mugiwara sign <mission>` / `--verify` — optional minisign attestation. */
+/** `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,11 +553,15 @@ 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 run <script> [args...]
                          run a bundled harness script here (${RUNNABLE.join(', ')})
   mugiwara savepoint <mission> [member] [flow] [mode]