@ionivetech/mugiwara 0.3.0 → 0.5.0

package/scripts/run-evals.ts

@@ -0,0 +1,113 @@
+#!/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 Case = {
+  name: string;
+  skill: string;
+  type?: 'positive' | 'negative' | 'adversarial' | 'lane';
+  task: string;
+  rubric: string[];
+  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 c: Case;
+    try { c = JSON.parse(readFileSync(join(casesDir, rel), 'utf8')); }
+    catch (e) { errors.push(`${rel}: invalid JSON (${(e as Error).message})`); continue; }
+    if (!c.name || !c.skill || !c.task || !Array.isArray(c.rubric) || !c.rubric.length)
+      errors.push(`${rel}: missing name/skill/task/nonempty rubric`);
+    else if (!existsSync(join(skillsDir, c.skill))) errors.push(`${rel}: unknown skill "${c.skill}"`);
+    if (c.type && !['positive', 'negative', 'adversarial', 'lane'].includes(c.type))
+      errors.push(`${rel}: bad type "${c.type}"`);
+    cases.push(c);
+  }
+  if (!cases.length) { errors.push('no cases in evals/cases/'); }
+
+  // coverage gates: the suite must exercise routing in all directions.
+  const types = new Set(cases.map(c => c.type).filter(Boolean));
+  if (cases.filter(c => c.type === 'positive').length < 2) errors.push('need ≥2 positive cases');
+  if (cases.filter(c => c.type === 'negative').length < 2) errors.push('need ≥2 negative cases');
+  if (cases.filter(c => c.type === 'adversarial').length < 2) errors.push('need ≥2 adversarial cases');
+  if (!types.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 matched = c.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: c.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 prompt = `Task: ${c.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: ${c.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,165 @@
+#!/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 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
+  LOC_DELTA=$(git diff --shortstat "$BASE_SHA"..HEAD 2>/dev/null | \
+    awk '{ins=0; del=0; for(i=1;i<=NF;i++){if($i=="insertion") ins=$(i-1); if($i=="deletion") del=$(i-1)} print ins-del}' || echo 0)
+fi
+[ -z "$LOC_DELTA" ] && LOC_DELTA=0
+[ "$LOC_DELTA" = "0" ] || LOC_DELTA=${LOC_DELTA//[^0-9-]/}
+
+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}`);
+}

package/scripts/validate-content.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env bun
+// scripts/validate-content.ts
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { parseFrontmatter } from '../src/frontmatter.ts';
+
+const root = join(import.meta.dirname, '..', 'content');
+const errors: string[] = [];
+
+function checkFile(file: string, wantName: string, kind: 'skill' | 'agent'): Record<string, string> | null {
+  let parsed;
+  try { parsed = parseFrontmatter(readFileSync(file, 'utf8')); }
+  catch (e) { errors.push(`${kind} ${file}: ${(e as Error).message}`); return null; }
+  const { data, body } = parsed;
+  if (data.name !== wantName) errors.push(`${kind} ${file}: name "${data.name}" != "${wantName}"`);
+  const d = data.description ?? '';
+  if (kind === 'skill' && (d.length < 20 || d.length > 500)) errors.push(`skill ${file}: description must be 20-500 chars (got ${d.length})`);
+  if (kind === 'agent' && d.length < 20) errors.push(`agent ${file}: description too short`);
+  if (kind === 'skill' && body.replace(/\r?\n$/, '').split(/\r?\n/).length > 120) errors.push(`skill ${file}: body exceeds 120 lines`);
+  if (kind === 'skill' && !body.includes('## Skip when')) errors.push(`skill ${file}: missing required "## Skip when" block (≤4 lines, numeric threshold)`);
+  if (kind === 'skill' && body.includes('## Skip when')) {
+    const lines = body.split(/\r?\n/);
+    const idx = lines.findIndex(l => l.startsWith('## Skip when'));
+    const gateLines = lines.slice(idx + 1).findIndex(l => l.startsWith('## '));
+    const end = gateLines === -1 ? lines.length : idx + 1 + gateLines;
+    const bullets = lines.slice(idx + 1, end).filter(l => l.trim().startsWith('-'));
+    if (bullets.length === 0) errors.push(`skill ${file}: "## Skip when" needs ≥1 bullet`);
+    if (bullets.length > 4) errors.push(`skill ${file}: "## Skip when" block exceeds 4 bullets`);
+  }
+  return data;
+}
+
+function listFiles(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(...listFiles(p, join(prefix, ent.name)));
+    else out.push(join(prefix, ent.name));
+  }
+  return out;
+}
+
+const syncArg = process.argv.indexOf('--check-sync');
+if (syncArg !== -1) {
+  const pairs = [['content/skills', 'skills'], ['content/agents', 'agents']] as const;
+  const diffs: string[] = [];
+  for (const [from, to] of pairs) {
+    const fromRoot = join(import.meta.dirname, '..', from);
+    const toRoot = join(import.meta.dirname, '..', to);
+    const fromFiles = listFiles(fromRoot).sort();
+    const toFiles = listFiles(toRoot).sort();
+    for (const rel of fromFiles) {
+      const f = join(fromRoot, rel), t = join(toRoot, rel);
+      if (!existsSync(t)) diffs.push(`missing copy: ${to}/${rel} (run .claude-plugin/sync.sh)`);
+      else if (readFileSync(f, 'utf8') !== readFileSync(t, 'utf8')) diffs.push(`out of sync: ${to}/${rel}`);
+    }
+    for (const rel of toFiles) {
+      if (!fromFiles.includes(rel)) diffs.push(`stale copy: ${to}/${rel} (not in content/, run .claude-plugin/sync.sh)`);
+    }
+  }
+  if (diffs.length) { console.error(diffs.map(d => `✗ ${d}`).join('\n')); process.exit(1); }
+  console.log('✓ plugin copies in sync with content/');
+  process.exit(0);
+}
+
+const skillDirs = existsSync(join(root, 'skills'))
+  ? readdirSync(join(root, 'skills')).filter(d => statSync(join(root, 'skills', d)).isDirectory())
+  : [];
+const names = new Map<string, string>();
+const usedSkills = new Set<string>();
+
+const checkArg = process.argv.indexOf('--check');
+if (checkArg !== -1) {
+  const file = process.argv[checkArg + 1];
+  const isSkill = file.includes('skills');
+  const want = isSkill ? basename(join(file, '..')) : basename(file).replace(/\.md$/, '');
+  checkFile(file, want, isSkill ? 'skill' : 'agent');
+  if (errors.length) { console.error(errors.map(e => `✗ ${e}`).join('\n')); process.exit(1); }
+  console.log(`✓ ${file}`);
+  process.exit(0);
+}
+
+for (const dir of skillDirs) {
+  const file = join(root, 'skills', dir, 'SKILL.md');
+  if (!existsSync(file)) { errors.push(`skill ${dir}: missing SKILL.md`); continue; }
+  const data = checkFile(file, dir, 'skill');
+  if (data) {
+    if (names.has(data.name)) errors.push(`duplicate name: ${data.name}`);
+    names.set(data.name, file);
+  }
+}
+
+const agentDir = join(root, 'agents');
+const agentFiles = existsSync(agentDir) ? readdirSync(agentDir).filter(f => f.endsWith('.md')) : [];
+for (const f of agentFiles) {
+  const data = checkFile(join(agentDir, f), f.replace(/\.md$/, ''), 'agent');
+  if (!data) continue;
+  if (names.has(data.name)) errors.push(`duplicate name: ${data.name}`);
+  names.set(data.name, f);
+  const skills = (data.skills ?? '').split(',').map(s => s.trim()).filter(Boolean);
+  if (skills.length === 0) errors.push(`agent ${f}: skills field missing/empty`);
+  for (const s of skills) {
+    usedSkills.add(s);
+    if (!skillDirs.includes(s)) errors.push(`agent ${f}: unknown skill "${s}"`);
+  }
+}
+
+for (const dir of skillDirs) {
+  if (dir !== 'mugiwara-workflow' && !usedSkills.has(dir)) errors.push(`skill ${dir}: not referenced by any agent`);
+}
+
+// --- manifest-sync check: .claude-plugin/plugin.json must set-equal content/ ---
+const manifestArg = process.argv.indexOf('--check-manifest');
+if (manifestArg !== -1) {
+  const manifests = ['.claude-plugin/plugin.json'];
+  let manifestErrors = 0;
+
+  for (const mp of manifests) {
+    const mpath = join(import.meta.dirname, '..', mp);
+    if (!existsSync(mpath)) { errors.push(`manifest ${mp}: file not found`); continue; }
+    let mdata;
+    try { mdata = JSON.parse(readFileSync(mpath, 'utf8')); }
+    catch (e) { errors.push(`manifest ${mp}: invalid JSON`); continue; }
+
+    const mSkills = mdata?.metadata?.skills;
+    const mAgents = mdata?.metadata?.agents;
+    if (!Array.isArray(mSkills)) { errors.push(`manifest ${mp}: missing metadata.skills array`); }
+    if (!Array.isArray(mAgents)) { errors.push(`manifest ${mp}: missing metadata.agents array`); }
+    if (!mSkills || !mAgents) continue;
+
+    const mSkillSet = new Set(mSkills);
+    const mAgentSet = new Set(mAgents);
+
+    // every skill in content/ must be in manifest
+    for (const dir of skillDirs) {
+      if (!mSkillSet.has(dir)) {
+        errors.push(`manifest ${mp}: missing skill "${dir}"`);
+        manifestErrors++;
+      }
+    }
+    // no stale entries in manifest
+    for (const s of mSkills) {
+      if (!skillDirs.includes(s)) {
+        errors.push(`manifest ${mp}: stale skill "${s}" (not in content/skills/)`);
+        manifestErrors++;
+      }
+    }
+    // every agent in content/ must be in manifest
+    for (const f of agentFiles) {
+      const name = f.replace(/\.md$/, '');
+      if (!mAgentSet.has(name)) {
+        errors.push(`manifest ${mp}: missing agent "${name}"`);
+        manifestErrors++;
+      }
+    }
+    for (const a of mAgents) {
+      if (!agentFiles.includes(`${a}.md`)) {
+        errors.push(`manifest ${mp}: stale agent "${a}" (not in content/agents/)`);
+        manifestErrors++;
+      }
+    }
+  }
+
+  if (manifestErrors === 0) console.log('✓ manifest in sync with content/');
+}
+
+// --- index budget gate ---
+const INDEX_BUDGET = 5500; // chars, all skill + agent descriptions combined
+let totalDescChars = 0;
+for (const dir of skillDirs) {
+  const file = join(root, 'skills', dir, 'SKILL.md');
+  if (!existsSync(file)) continue;
+  const parsed = parseFrontmatter(readFileSync(file, 'utf8'));
+  totalDescChars += (parsed.data.description ?? '').length;
+}
+for (const f of agentFiles) {
+  const parsed = parseFrontmatter(readFileSync(join(agentDir, f), 'utf8'));
+  totalDescChars += (parsed.data.description ?? '').length;
+}
+if (totalDescChars > INDEX_BUDGET) {
+  errors.push(`index budget exceeded: ${totalDescChars}/${INDEX_BUDGET} chars (skill + agent descriptions)`);
+} else {
+  console.log(`✓ index budget: ${totalDescChars}/${INDEX_BUDGET} chars`);
+}
+
+// --- docs-drift check: docs/skills.md and docs/agents.md must reference all content/ entries ---
+const docsArg = process.argv.indexOf('--check-docs');
+if (docsArg !== -1) {
+  const docsDir = join(import.meta.dirname, '..', 'docs');
+  const skillsDoc = join(docsDir, 'skills.md');
+  const agentsDoc = join(docsDir, 'agents.md');
+  let docErrors = 0;
+
+  if (existsSync(skillsDoc)) {
+    const content = readFileSync(skillsDoc, 'utf8');
+    for (const dir of skillDirs) {
+      if (!content.includes(dir)) {
+        errors.push(`docs/skills.md: missing skill "${dir}"`);
+        docErrors++;
+      }
+    }
+  } else {
+    errors.push('docs/skills.md: file not found');
+    docErrors++;
+  }
+
+  if (existsSync(agentsDoc)) {
+    const content = readFileSync(agentsDoc, 'utf8');
+    for (const f of agentFiles) {
+      const name = f.replace(/\.md$/, '');
+      if (!content.includes(name)) {
+        errors.push(`docs/agents.md: missing agent "${name}"`);
+        docErrors++;
+      }
+    }
+  } else {
+    errors.push('docs/agents.md: file not found');
+    docErrors++;
+  }
+
+  if (docErrors === 0) console.log('✓ docs in sync with content/');
+}
+
+if (errors.length) { console.error(errors.map(e => `✗ ${e}`).join('\n')); process.exit(1); }
+console.log(`✓ content valid: ${skillDirs.length} skills, ${agentFiles.length} agents`);

package/src/args.ts

@@ -9,7 +9,8 @@ export type Args = {
 const VALUE_FLAGS: Record<string, string> = { '--project': 'project', '--target': 'target' };
 const BOOL_FLAGS: Record<string, string> = {
   '--global': 'global', '--yes': 'yes', '-y': 'yes', '--force': 'force',
-  '--dry-run': 'dryRun', '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
+  '--dry-run': 'dryRun', '--keep-logs': 'keepLogs',
+  '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
 };
 
 export function parseArgs(argv: string[]): Args {

package/src/cli.ts

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 // src/cli.ts
-import { existsSync, readFileSync, readdirSync, realpathSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parseArgs, type FlagValue, type Args } from './args.ts';
 import { createRl, choose, multiChoose, confirm } from './prompt.ts';
 import { targets, TARGET_IDS } from './targets/index.ts';
-import { installTo, removeInstalled, VERSION, CONTENT_DIR } from './installer.ts';
+import { installTo, removeInstalled, VERSION } from './installer.ts';
 import { manifestPath, readManifest, writeManifest, type Scope } from './manifest.ts';
-import { parseFrontmatter } from './frontmatter.ts';
+import { resetMission } from './mission.ts';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
@@ -23,11 +23,24 @@ export async function run(argv: string[]): Promise<void> {
     case 'update': return install({ ...flags, force: true });
     case 'uninstall': return uninstall(flags);
     case 'list': return list(flags);
-    case 'skills': return skills();
+    case 'reset': return resetCmd(flags);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
 
+function resetCmd(flags: Args['flags']): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const force = flag(flags.force);
+  const result = resetMission(projectDir, flag(flags.keepLogs), force);
+  if (result.blocked) {
+    console.error(`✗ ${result.blocked}`);
+    process.exit(1);
+  }
+  if (result.removed.length) console.log(`removed: ${result.removed.join(', ')}`);
+  else console.log('nothing to remove.');
+  if (result.kept.length) console.log(`kept: ${result.kept.join(', ')}`);
+}
+
 async function resolveOptions(flags: Args['flags']): Promise<{ scope: Scope; projectDir: string; targetIds: string[] }> {
   const interactive = !flag(flags.yes);
   const rl = interactive ? createRl() : null;
@@ -126,19 +139,6 @@ function list(flags: Args['flags']): void {
   if (!found) console.log('No mugiwara installation found.');
 }
 
-function skills(): void {
-  const dir = join(CONTENT_DIR, 'skills');
-  const names = readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name).sort();
-  const rows = names.map(name => {
-    const { data } = parseFrontmatter(readFileSync(join(dir, name, 'SKILL.md'), 'utf8'));
-    return [name, data.description ?? ''] as const;
-  });
-  const w = Math.max(...rows.map(r => r[0].length)) + 2;
-  console.log(`mugiwara ${VERSION} — ${rows.length} skills (agentskills.io format):\n`);
-  for (const [name, description] of rows) console.log(`  ${name.padEnd(w)}${description}`);
-  console.log(`\nInstall skills into any agent via skills.sh:\n  npx skills add ionivetech/mugiwara`);
-}
-
 function help(): void {
   console.log(`mugiwara ${VERSION} — the Straw Hat crew for AI agents
 
@@ -147,7 +147,7 @@ Usage:
   mugiwara update        replace existing files (backs up differences first)
   mugiwara uninstall     remove installed files via manifest
   mugiwara list          show installations
-  mugiwara skills        list installable skills (agentskills.io)
+  mugiwara reset         wipe mission state (spec/plans/results/review/issues[/logs])
   mugiwara --help        this help
   mugiwara --version     print version
 
@@ -157,7 +157,8 @@ Flags:
   --target <ids|all>     comma-separated: ${TARGET_IDS.join(', ')}
   --yes, -y              non-interactive (needs --global/--project, --target)
   --force                overwrite differing files (with backup)
-  --dry-run              print actions without writing`);
+  --dry-run              print actions without writing
+  --keep-logs            with reset: keep .mugiwara/logs (lessons ledger survives)`);
 }
 
 let entry = process.argv[1] !== undefined ? resolve(process.argv[1]) : undefined;