@ionivetech/mugiwara 0.4.0 → 0.5.1

package/scripts/retrieval-eval.ts

@@ -0,0 +1,261 @@
+#!/usr/bin/env bun
+// scripts/retrieval-eval.ts — offline retrieval ranking eval
+// Builds TF-IDF index over skill descriptions, scores prompts, reports rank-1 + top_k.
+// No model needed — pure string matching. Outputs JSON.
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFrontmatter } from '../src/frontmatter.ts';
+
+const root = join(import.meta.dirname, '..');
+const skillsDir = join(root, 'content', 'skills');
+const evalsDir = join(root, 'evals', 'cases');
+
+// --- TF-IDF ---
+type Index = { terms: Map<string, number>; docs: Map<string, Map<string, number>>; docCount: number };
+
+function tokenize(text: string): string[] {
+  return text.toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length > 1 && !['the', 'and', 'for', 'use', 'when', 'that', 'with', 'this', 'from', 'its', 'not', 'are', 'has'].includes(t));
+}
+
+function buildIndex(): Index {
+  const index: Index = { terms: new Map(), docs: new Map(), docCount: 0 };
+  const dirs = readdirSync(skillsDir).filter(d => statSync(join(skillsDir, d)).isDirectory());
+
+  for (const dir of dirs) {
+    const file = join(skillsDir, dir, 'SKILL.md');
+    if (!existsSync(file)) continue;
+
+    const { data } = parseFrontmatter(readFileSync(file, 'utf8'));
+    const desc = data.description ?? '';
+    const tokens = tokenize(desc);
+    const tf = new Map<string, number>();
+
+    for (const t of tokens) {
+      tf.set(t, (tf.get(t) || 0) + 1);
+      index.terms.set(t, (index.terms.get(t) || 0) + 1);
+    }
+
+    index.docs.set(dir, tf);
+    index.docCount++;
+  }
+
+  return index;
+}
+
+function tfidf(index: Index, doc: string, term: string): number {
+  const tf = index.docs.get(doc)?.get(term) || 0;
+  if (tf === 0) return 0;
+  const df = index.terms.get(term) || 1;
+  return tf * Math.log(index.docCount / df);
+}
+
+function score(index: Index, prompt: string): { skill: string; score: number }[] {
+  const promptTerms = tokenize(prompt);
+  const results: { skill: string; score: number }[] = [];
+
+  for (const [doc] of index.docs) {
+    let total = 0;
+    for (const t of promptTerms) {
+      total += tfidf(index, doc, t);
+    }
+    results.push({ skill: doc, score: total });
+  }
+
+  return results.sort((a, b) => b.score - a.score || a.skill.localeCompare(b.skill));
+}
+
+// --- case schema ---
+interface CaseFile {
+  name: string;
+  skill: string;
+  type?: string;
+  task: string;
+  rubric: string[];
+  expect_lane?: string;
+  trigger?: {
+    positive?: { prompt: string; top_k?: number }[];
+    negative?: { prompt: string }[];
+  };
+  behavioral?: { task: string; rubric: string[] }[];
+}
+
+interface Probe {
+  kind: 'positive' | 'negative';
+  skill: string;
+  prompt: string;
+  topK: number;
+}
+
+// --- build index ---
+const index = buildIndex();
+
+// --- load cases ---
+const skills = readdirSync(skillsDir).filter(d => statSync(join(skillsDir, d)).isDirectory());
+const files = readdirSync(evalsDir).filter(f => f.endsWith('.json'));
+const probes: Probe[] = [];
+const noSkillProbes: Probe[] = [];
+const covered = new Set<string>();
+
+for (const f of files) {
+  let c: CaseFile;
+  try {
+    c = JSON.parse(readFileSync(join(evalsDir, f), 'utf8'));
+  } catch (e) {
+    throw new Error(`eval case ${f} is not valid JSON: ${e}`);
+  }
+  if (!c.skill) throw new Error(`eval case ${f} has no "skill"`);
+  covered.add(c.skill);
+
+  const target = c.skill === '_no-skill' ? noSkillProbes : probes;
+  for (const p of c.trigger?.positive ?? [])
+    target.push({ kind: 'positive', skill: c.skill, prompt: p.prompt, topK: p.top_k ?? 3 });
+  for (const p of c.trigger?.negative ?? [])
+    target.push({ kind: 'negative', skill: c.skill, prompt: p.prompt, topK: 3 });
+}
+
+// --- coverage gate ---
+const missing = skills.filter(s => !covered.has(s));
+if (missing.length) {
+  console.error(`missing eval cases for ${missing.length} skills:`);
+  for (const s of missing) console.error(`  ${s}`);
+  process.exit(1);
+}
+
+// --- run probes ---
+let rank1 = 0, inTopK = 0, negPass = 0, noSkillPass = 0;
+const positives = probes.filter(p => p.kind === 'positive');
+const negatives = probes.filter(p => p.kind === 'negative');
+const nsPositives = noSkillProbes.filter(p => p.kind === 'positive');
+const nsNegatives = noSkillProbes.filter(p => p.kind === 'negative');
+const failures: string[] = [];
+const results: Record<string, { rank: number; score: number; top_k: number; passed: boolean }> = {};
+
+for (const p of positives) {
+  const ranked = score(index, p.prompt);
+  const rank = ranked.findIndex(r => r.skill === p.skill) + 1;
+  const key = `${p.skill}: ${p.prompt}`;
+  const entryScore = rank > 0 ? ranked[rank - 1].score : 0;
+  const topScore = ranked[0]?.score ?? 0;
+  const passed = entryScore > 0 && rank > 0 && rank <= p.topK;
+  results[key] = { rank, score: entryScore, top_k: p.topK, passed };
+  if (passed && rank === 1) rank1++;
+  if (passed) inTopK++;
+  else failures.push(`positive "${p.prompt}" → ${p.skill} ranked ${rank || 'unranked'} (want <=${p.topK}), got ${ranked[0]?.skill ?? 'none'}`);
+}
+
+for (const p of negatives) {
+  const ranked = score(index, p.prompt);
+  const top = ranked[0];
+  const pass = (top?.score ?? 0) === 0 || top?.skill !== p.skill;
+  const key = `!${p.skill}: ${p.prompt}`;
+  results[key] = { rank: 0, score: top?.score ?? 0, top_k: 3, passed: pass };
+  if (pass) negPass++;
+  else failures.push(`negative "${p.prompt}" wrongly ranked ${p.skill} first`);
+}
+
+for (const p of nsPositives) {
+  const ranked = score(index, p.prompt);
+  const top = ranked[0];
+  const pass = !top || top.score < 3.5;
+  const key = `_no-skill+: ${p.prompt}`;
+  results[key] = { rank: 0, score: top?.score ?? 0, top_k: 3, passed: pass };
+  if (pass) noSkillPass++;
+  else failures.push(`no-skill positive "${p.prompt}" → ${top.skill} score ${top.score.toFixed(2)} (want <3.5)`);
+}
+
+for (const p of nsNegatives) {
+  const ranked = score(index, p.prompt);
+  const top = ranked[0];
+  const pass = !!top && top.skill.startsWith('mugiwara-') && top.score >= 3.5;
+  const key = `_no-skill-: ${p.prompt}`;
+  results[key] = { rank: 0, score: top?.score ?? 0, top_k: 3, passed: pass };
+  if (pass) noSkillPass++;
+  else failures.push(`no-skill negative "${p.prompt}" → ${top?.skill ?? 'none'} score ${top?.score?.toFixed(2) ?? '0'} (want mugiwara skill >=3.5)`);
+}
+
+// --- compute rates ---
+const rank1Rate = positives.length ? (rank1 / positives.length) * 100 : 0;
+const topKRate  = positives.length ? (inTopK / positives.length) * 100 : 0;
+const negRate   = negatives.length ? (negPass / negatives.length) * 100 : 0;
+const nsTotal   = nsPositives.length + nsNegatives.length;
+const nsRate    = nsTotal ? (noSkillPass / nsTotal) * 100 : 100;
+
+const allPassed = Object.values(results).filter(r => r.passed).length;
+const allFailed = Object.values(results).filter(r => !r.passed).length;
+const totalProbes = Object.keys(results).length;
+
+// --- floor / ratchet ---
+const floorPath = join(root, 'evals', 'floor.json');
+const updateFloor = process.argv.includes('--update-floor');
+
+if (!existsSync(floorPath)) {
+  if (updateFloor) {
+    const initial = { rank1: Math.round(rank1Rate * 10) / 10, topk: Math.round(topKRate * 10) / 10, negatives: Math.round(negRate * 10) / 10, updated: new Date().toISOString().split('T')[0] };
+    writeJson(floorPath, initial);
+  }
+} else {
+  const floor = JSON.parse(readFileSync(floorPath, 'utf8'));
+  const TOL = 0.5;
+
+  if (updateFloor) {
+    floor.rank1 = Math.round(rank1Rate * 10) / 10;
+    floor.topk = Math.round(topKRate * 10) / 10;
+    floor.negatives = Math.round(negRate * 10) / 10;
+    floor.updated = new Date().toISOString().split('T')[0];
+    writeJson(floorPath, floor);
+  } else {
+    const regressions: string[] = [];
+    if (rank1Rate < floor.rank1 - TOL) regressions.push(`rank-1 ${rank1Rate.toFixed(1)}% < floor ${floor.rank1}%`);
+    if (topKRate < floor.topk - TOL) regressions.push(`top-k ${topKRate.toFixed(1)}% < floor ${floor.topk}%`);
+    if (negRate < floor.negatives - TOL) regressions.push(`negatives ${negRate.toFixed(1)}% < floor ${floor.negatives}%`);
+
+    console.log(`rank-1 ${rank1Rate.toFixed(1)}%  top-3 ${topKRate.toFixed(1)}%  negatives ${negRate.toFixed(1)}%  no-skill ${nsRate.toFixed(1)}%  (${positives.length}p / ${negatives.length}n / ${nsTotal}ns over ${skills.length} skills)`);
+    for (const f of failures) console.error(`  FAIL ${f}`);
+    if (regressions.length) {
+      regressions.forEach(r => console.error(`REGRESSION: ${r}`));
+      process.exit(1);
+    }
+  }
+}
+
+// --- report ---
+const ciArg = process.argv.indexOf('--json');
+if (ciArg !== -1) {
+  const report = {
+    index_size: index.docCount,
+    index_terms: index.terms.size,
+    probes: totalProbes,
+    positives: positives.length,
+    negatives: negatives.length,
+    no_skill: nsTotal,
+    rank1_count: rank1,
+    rank1_rate: `${rank1Rate.toFixed(1)}%`,
+    topk_count: inTopK,
+    topk_rate: `${topKRate.toFixed(1)}%`,
+    negative_pass: negPass,
+    negative_rate: `${negRate.toFixed(1)}%`,
+    no_skill_pass: noSkillPass,
+    no_skill_rate: `${nsRate.toFixed(1)}%`,
+    passed: allPassed,
+    failed: allFailed,
+    failures: failures.length > 0 ? failures : undefined,
+    results,
+  };
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  console.log(`\nRetrieval eval: ${allPassed}/${totalProbes} passed, rank-1 ${rank1Rate.toFixed(1)}%, top-3 ${topKRate.toFixed(1)}%, neg ${negRate.toFixed(1)}%, ns ${nsRate.toFixed(1)}%`);
+  if (failures.length > 0) {
+    console.error(`\n${failures.length} failures:`);
+    for (const f of failures) console.error(`  ${f}`);
+    process.exit(1);
+  }
+}
+
+function writeJson(path: string, obj: object) {
+  const { writeFileSync } = require('node:fs');
+  writeFileSync(path, JSON.stringify(obj, null, 2) + '\n');
+}

package/scripts/run-evals.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env bun
+// scripts/run-evals.ts — the mugiwara eval harness.
+// Two modes:
+//   bun scripts/run-evals.ts            validate the suite (structure + coverage). CI-safe, no model.
+//   bun scripts/run-evals.ts --run [cmd]  execute each case against a model CLI and score the rubric.
+//
+// --run uses the command to invoke a model that prints only its answer to the
+// task; the harness scores the answer against the rubric with a heuristic
+// keyword match, then reports pass/fail per case and a rank-1 style score.
+// The command defaults to "claude -p" — override with MUGIWARA_EVAL_CMD.
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = join(import.meta.dirname, '..');
+const casesDir = join(root, 'evals', 'cases');
+const skillsDir = join(root, 'content', 'skills');
+const errors: string[] = [];
+
+type BehavioralTest = {
+  task: string;
+  rubric: string[];
+};
+
+type Case = {
+  name: string;
+  skill: string;
+  type?: 'positive' | 'negative' | 'adversarial' | 'lane';
+  behavioral?: BehavioralTest[];
+  expect_lane?: string;
+};
+
+function listCases(dir: string, prefix = ''): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, ent.name);
+    if (ent.isDirectory()) out.push(...listCases(p, join(prefix, ent.name)));
+    else if (ent.name.endsWith('.json')) out.push(join(prefix, ent.name));
+  }
+  return out;
+}
+
+function validateSuite(): Case[] {
+  const cases: Case[] = [];
+  const files = listCases(casesDir).sort();
+  for (const rel of files) {
+    let raw: any;
+    try { raw = JSON.parse(readFileSync(join(casesDir, rel), 'utf8')); }
+    catch (e) { errors.push(`${rel}: invalid JSON (${(e as Error).message})`); continue; }
+    if (!raw.name || !raw.skill) { errors.push(`${rel}: missing name/skill`); continue; }
+
+    // skip files with no behavioral section (e.g. _no-skill.json)
+    if (!raw.behavioral || !Array.isArray(raw.behavioral) || raw.behavioral.length === 0) continue;
+    if (raw.skill === '_no-skill') continue;
+
+    // infer type from filename if not declared
+    const type = raw.type ?? (
+      rel.includes('positive') ? 'positive' :
+      rel.includes('negative') ? 'negative' :
+      rel.includes('adversarial') ? 'adversarial' :
+      rel.includes('lane') ? 'lane' :
+      undefined
+    );
+
+    // validate skill exists
+    if (!existsSync(join(skillsDir, raw.skill)))
+      errors.push(`${rel}: unknown skill "${raw.skill}"`);
+
+    if (type && !['positive', 'negative', 'adversarial', 'lane'].includes(type))
+      errors.push(`${rel}: bad type "${type}"`);
+
+    // register one case per behavioral test
+    for (const b of raw.behavioral) {
+      if (!b.task || !Array.isArray(b.rubric) || !b.rubric.length) {
+        errors.push(`${rel}: behavioral entry missing task/nonempty rubric`);
+        continue;
+      }
+      cases.push({
+        name: raw.name,
+        skill: raw.skill,
+        type,
+        behavioral: [b],
+        expect_lane: raw.expect_lane,
+      });
+    }
+  }
+
+  if (!cases.length) { errors.push('no behavioral cases in evals/cases/'); }
+
+  // coverage gates: the suite must exercise routing in all directions.
+  const explicitTypes = cases.filter(c => c.type);
+  const allTypes = new Set(explicitTypes.map(c => c.type).filter(Boolean));
+  if (explicitTypes.filter(c => c.type === 'adversarial').length < 2) errors.push('need >=2 adversarial cases');
+  if (!allTypes.has('lane')) errors.push('need >=1 lane case');
+  return cases;
+}
+
+function scoreRubric(answer: string, c: Case): { pass: number; total: number; matched: string[] } {
+  const a = answer.toLowerCase();
+  const rubric = c.behavioral?.[0]?.rubric ?? [];
+  const matched = rubric.filter(r => {
+    const terms = r.toLowerCase().split(/[^a-z0-9]+/).filter(w => w.length > 3 && !['does', 'not', 'with', 'into', 'from'].includes(w));
+    return terms.some(t => a.includes(t));
+  });
+  return { pass: matched.length, total: rubric.length, matched };
+}
+
+async function runCases(env: { execFileSync: typeof import('node:child_process').execFileSync; bin: string; pre: string[] }): Promise<void> {
+  const cases = validateSuite();
+  if (errors.length) { console.error(errors.map(e => `✗ ${e}`).join('\n')); process.exit(1); }
+  const { execFileSync, bin, pre } = env;
+  let total = 0, passed = 0;
+  for (const c of cases) {
+    const task = c.behavioral?.[0]?.task ?? '';
+    const prompt = `Task: ${task}\n\nWhich mugiwara skill should run and why? Be concrete.`;
+    let raw = '';
+    try {
+      raw = execFileSync(bin, [...pre, prompt], { encoding: 'utf8', timeout: 60000, maxBuffer: 10 * 1024 * 1024 });
+    } catch (e: any) {
+      raw = e.stdout?.toString?.() ?? String(e.message);
+    }
+    const { pass, total: t, matched } = scoreRubric(raw, c);
+    total += t;
+    passed += pass;
+    const pct = Math.round((pass / t) * 100);
+    console.log(`${pct >= 70 ? '✓' : '✗'} ${c.name} — ${pass}/${t} rubric (${pct}%)`);
+    if (pass < t) {
+      console.log(`    task: ${task}`);
+      console.log(`    matched: ${matched.length ? matched.join('; ') : 'none'}`);
+    }
+  }
+  const overall = Math.round((passed / total) * 100);
+  console.log(`\nOVERALL ${passed}/${total} (${overall}%)`);
+  if (overall < 70) process.exitCode = 1;
+}
+
+const runArg = process.argv.indexOf('--run');
+if (runArg !== -1) {
+  const { execFileSync } = require('node:child_process');
+  const cmd = process.env.MUGIWARA_EVAL_CMD ?? 'claude -p';
+  const [bin, ...pre] = cmd.split(' ');
+  runCases({ execFileSync, bin, pre });
+  process.exit(0);
+}
+
+const cases = validateSuite();
+if (errors.length) { console.error(errors.map(e => `✗ ${e}`).join('\n')); process.exit(1); }
+console.log(`✓ eval suite OK: ${cases.length} cases (${cases.filter(c => c.type === 'positive').length} positive, ${cases.filter(c => c.type === 'negative').length} negative, ${cases.filter(c => c.type === 'adversarial').length} adversarial, ${cases.filter(c => c.type === 'lane').length} lane)`);
+for (const c of cases) console.log(`  ${c.name} [${c.type ?? 'default'}]`);

package/scripts/savepoint.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# scripts/savepoint.sh — write .mugiwara/state.json at every wave boundary.
+# Computed from git + file counts; zero model judgement.
+set -u
+
+die() { echo "savepoint: $*" >&2; exit 1; }
+
+MUGIWARA_DIR="${MUGIWARA_DIR:-.mugiwara}"
+
+# --- parse mission args ---
+MISSION="${1:-${STATE_MISSION:-}}"
+ACTOR="${2:-${STATE_ACTOR:-${GIT_AUTHOR_NAME:-${USER:-}}}}"
+BRANCH="${3:-$(git branch --show-current 2>/dev/null || echo 'unknown')}"
+WAVE="${4:-${STATE_WAVE:-1}}"
+MODE="${5:-${STATE_MODE:-guided}}"
+
+# --branch flag for per-branch state
+BRANCH_MODE=0
+if [ "${1:-}" = "--branch" ]; then
+  BRANCH_MODE=1
+  MISSION="${2:-${STATE_MISSION:-}}"
+  BRANCH="${3:-$(git branch --show-current 2>/dev/null || echo 'unknown')}"
+  shift 2 2>/dev/null || true
+fi
+
+# per-branch state file when --branch used
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+if [ "$BRANCH_MODE" -eq 1 ]; then
+  STATE_FILE="$MUGIWARA_DIR/state-${BRANCH_SLUG}.json"
+else
+  STATE_FILE="$MUGIWARA_DIR/state.json"
+fi
+
+[ -z "$MISSION" ] && die "usage: savepoint.sh <mission> [actor] [branch] [wave] [mode]"
+[ -d .git ] || die "not a git repository"
+
+# --- computed fields ---
+BASE_SHA=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null || git merge-base HEAD "$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')" 2>/dev/null || git rev-parse HEAD~1 2>/dev/null || echo "unknown")
+HEAD_SHA=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+
+CHANGED_FILES=$(git diff --name-only "$BASE_SHA"..HEAD 2>/dev/null || git diff --name-only --cached 2>/dev/null || true)
+FILES_TOUCHED=$( [ -n "$CHANGED_FILES" ] && echo "$CHANGED_FILES" | wc -l | tr -d ' ' || echo 0 )
+
+LOC_DELTA=0
+if [ "$BASE_SHA" != "unknown" ]; then
+  STAT=$(git diff --shortstat "$BASE_SHA"..HEAD 2>/dev/null || echo "")
+  INS=$(echo "$STAT" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo 0)
+  DEL=$(echo "$STAT" | grep -oE '[0-9]+ deletion'  | grep -oE '[0-9]+' || echo 0)
+  LOC_DELTA=$(( ${INS:-0} - ${DEL:-0} ))
+fi
+[ -z "$LOC_DELTA" ] && LOC_DELTA=0
+
+SENSITIVE_PATTERNS="auth/|payment/|billing/|crypto/|secrets/|\.env|config/|migration/|\.sql$|schema\.|\.prisma$"
+SENSITIVE_PATHS=$(echo "$CHANGED_FILES" | grep -E "$SENSITIVE_PATTERNS" 2>/dev/null | tr '\n' ',' | sed 's/,$//' || true)
+
+LANE="direct"
+LANE_REASON=""
+if [ "$FILES_TOUCHED" -ge 9 ] 2>/dev/null || [ -n "$SENSITIVE_PATHS" ]; then
+  LANE="full"
+  LANE_REASON="$( [ -n "$SENSITIVE_PATHS" ] && echo "sensitive paths: $SENSITIVE_PATHS" || echo "$FILES_TOUCHED files")"
+elif [ "$FILES_TOUCHED" -ge 3 ] 2>/dev/null; then
+  LANE="standard"
+  LANE_REASON="$FILES_TOUCHED files"
+elif [ "$FILES_TOUCHED" -ge 2 ] 2>/dev/null; then
+  LANE="lean"
+  LANE_REASON="$FILES_TOUCHED files"
+else
+  LANE="direct"
+  LANE_REASON="$FILES_TOUCHED file(s) under 20 LOC"
+fi
+
+# task counts from plan doc
+PLAN_FILE=$(ls "$MUGIWARA_DIR/plans/${MISSION}.md" 2>/dev/null || true)
+TASKS_DONE=0
+TASKS_TOTAL=0
+if [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
+  TASKS_TOTAL=$(grep -c '\[ \]' "$PLAN_FILE" 2>/dev/null || echo 0)
+  TASKS_DONE=$(grep -c '\[x\]' "$PLAN_FILE" 2>/dev/null || echo 0)
+fi
+
+# blocker count
+BLOCKERS_FILE=$(ls "$MUGIWARA_DIR/issues/${MISSION}-blockers.md" 2>/dev/null || true)
+BLOCKERS_OPEN=0
+if [ -n "$BLOCKERS_FILE" ] && [ -f "$BLOCKERS_FILE" ]; then
+  BLOCKERS_OPEN=$(grep -c '|' "$BLOCKERS_FILE" 2>/dev/null || echo 0)
+fi
+
+# heal cycle
+HEAL_CYCLE=1
+TRACE_FILE=$(ls "$MUGIWARA_DIR/results/${MISSION}-trace.md" 2>/dev/null || true)
+if [ -n "$TRACE_FILE" ] && [ -f "$TRACE_FILE" ]; then
+  HEAL_COUNT=$(grep -ci 'Wave 8\|wave 8\|heal' "$TRACE_FILE" 2>/dev/null || echo 0)
+  HEAL_CYCLE=$((HEAL_COUNT + 1))
+fi
+
+# evidence paths
+EVIDENCE=$(ls "$MUGIWARA_DIR/results/" 2>/dev/null | grep "$MISSION" | sed 's|^|.mugiwara/results/|' | tr '\n' ',' | sed 's/,$//' || true)
+
+# skill version from package.json
+SKILL_VERSION="1"
+if [ -f package.json ]; then
+  PKG_JSON="$MUGIWARA_DIR/../package.json"
+  [ -f "$PKG_JSON" ] && SKILL_VERSION=$(python3 -c "import json; v=json.load(open('$PKG_JSON')).get('version','1'); print(v.split('.')[0])" 2>/dev/null || echo "1")
+fi
+
+# tokens from env var (harness exports estimated tokens consumed)
+TOKENS_EST=${MUGIWARA_TOKENS:-0}
+
+# budget per lane
+BUDGET=0
+case "$LANE" in
+  lean) BUDGET=4000 ;;
+  standard) BUDGET=10000 ;;
+  full) BUDGET=20000 ;;
+  spike) BUDGET=3000 ;;
+  *) BUDGET=0 ;;
+esac
+
+# token budget gate
+WARN_AT=$(( BUDGET * 3 / 2 ))
+STOP_AT=$(( BUDGET * 3 ))
+STATUS="ok"
+if [ "$BUDGET" -gt 0 ] && [ "$TOKENS_EST" -ge "$STOP_AT" ] 2>/dev/null; then
+  STATUS="stop"
+elif [ "$BUDGET" -gt 0 ] && [ "$TOKENS_EST" -ge "$WARN_AT" ] 2>/dev/null; then
+  STATUS="warn"
+fi
+
+SENSITIVE_ARR=""
+if [ -n "$SENSITIVE_PATHS" ]; then
+  SENSITIVE_ARR=$(echo "$SENSITIVE_PATHS" | tr ',' '\n' | sed 's/^/"/;s/$/"/' | tr '\n' ',' | sed 's/,$//')
+fi
+EVIDENCE_ARR=""
+if [ -n "$EVIDENCE" ]; then
+  EVIDENCE_ARR=$(echo "$EVIDENCE" | tr ',' '\n' | sed 's/^/"/;s/$/"/' | tr '\n' ',' | sed 's/,$//')
+fi
+
+mkdir -p "$MUGIWARA_DIR"
+
+cat > "$STATE_FILE" <<JSON
+{
+  "mission": "$MISSION",
+  "actor": "$ACTOR",
+  "branch": "$BRANCH",
+  "lane": "$LANE",
+  "lane_reason": "$LANE_REASON",
+  "wave": $WAVE,
+  "mode": "$MODE",
+  "base_sha": "$BASE_SHA",
+  "head_sha": "$HEAD_SHA",
+  "files_touched": $FILES_TOUCHED,
+  "loc_delta": $LOC_DELTA,
+  "sensitive_paths": [${SENSITIVE_ARR}],
+  "tasks": { "done": $TASKS_DONE, "total": $TASKS_TOTAL },
+  "blockers_open": $BLOCKERS_OPEN,
+  "heal_cycle": $HEAL_CYCLE,
+  "tokens_est": $TOKENS_EST,
+  "budget": $BUDGET,
+  "budget_status": "$STATUS",
+  "skill_version": "$SKILL_VERSION",
+  "evidence": [${EVIDENCE_ARR}],
+  "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+JSON
+
+echo "✓ savepoint written: $STATE_FILE (lane=$LANE, wave=$WAVE, files=$FILES_TOUCHED)"

package/scripts/sync-version.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+// scripts/sync-version.ts — syncs package.json version into the plugin manifests
+// so Claude/Copilot plugin version always matches the published npm version.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = join(import.meta.dirname, '..');
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const v = pkg.version;
+
+const targets = [
+  join(root, '.claude-plugin', 'plugin.json'),
+  join(root, 'plugin.json'),
+  join(root, '.claude-plugin', 'marketplace.json'),
+  join(root, 'gemini-extension.json'),
+  join(root, '.codex-plugin', 'plugin.json'),
+  join(root, '.cursor-plugin', 'plugin.json'),
+  join(root, '.kimi-plugin', 'plugin.json'),
+];
+
+for (const file of targets) {
+  const doc = JSON.parse(readFileSync(file, 'utf8'));
+  if (doc.version !== undefined) doc.version = v;
+  if (doc.metadata?.version !== undefined) doc.metadata.version = v;
+  if (Array.isArray(doc.plugins)) {
+    for (const p of doc.plugins) if (p.version !== undefined) p.version = v;
+  }
+  writeFileSync(file, JSON.stringify(doc, null, 2) + '\n');
+  console.log(`synced ${file} → ${v}`);
+}