@ionivetech/mugiwara 0.5.5 → 0.6.1

package/src/installer.ts

@@ -1,5 +1,5 @@
 // src/installer.ts
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync, rmSync, lstatSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +11,7 @@ export type ContentItem = {
   data: FrontmatterData;
   body: string;
   refs: { relPath: string; text: string }[];
+  internal?: boolean;
 };
 
 export type InstallOptions = {
@@ -35,6 +36,7 @@ export interface Target {
   label: string;
   native: boolean;
   tier?: 1 | 2 | 3;
+  refPointerPrefix?: string;
   paths(opts: { scope: Scope; projectDir: string; home: string }): { skillsDir: string; agentsDir: string };
   transformSkill(data: FrontmatterData, body: string): TransformOut;
   transformAgent(data: FrontmatterData, body: string): TransformOut;
@@ -48,7 +50,7 @@ export const CONTENT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '
 const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')) as { version: string };
 export const VERSION = pkg.version;
 
-export function collectContent(): { skills: ContentItem[]; agents: ContentItem[] } {
+export function collectContent(): { skills: ContentItem[]; agents: ContentItem[]; sharedRefs: { relPath: string; text: string }[] } {
   const skillNames = readdirSync(join(CONTENT_DIR, 'skills'), { withFileTypes: true })
     .filter(e => e.isDirectory()).map(e => e.name);
   const skills = skillNames.map(name => {
@@ -59,9 +61,17 @@ export function collectContent(): { skills: ContentItem[]; agents: ContentItem[]
     .filter(f => f.endsWith('.md'))
     .map(f => {
       const { data, body } = parseFrontmatter(readFileSync(join(CONTENT_DIR, 'agents', f), 'utf8'));
-      return { name: f.replace(/\.md$/, ''), data, body, refs: [] as { relPath: string; text: string }[] };
+      return { name: f.replace(/\.md$/, ''), data, body, refs: [] as { relPath: string; text: string }[], internal: data.internal === 'true' };
     });
-  return { skills, agents };
+  const sharedRefsDir = join(dirname(CONTENT_DIR), 'references');
+  const sharedRefs: { relPath: string; text: string }[] = [];
+  if (existsSync(sharedRefsDir)) {
+    for (const f of readdirSync(sharedRefsDir)) {
+      if (!f.endsWith('.md')) continue;
+      sharedRefs.push({ relPath: f, text: readFileSync(join(sharedRefsDir, f), 'utf8') });
+    }
+  }
+  return { skills, agents, sharedRefs };
 }
 
 function collectRefs(skillDir: string): { relPath: string; text: string }[] {
@@ -74,7 +84,7 @@ function collectRefs(skillDir: string): { relPath: string; text: string }[] {
 export function installTo(target: Target, opts: InstallOptions): InstallResult {
   const { scope, projectDir, dryRun = false, force = false } = opts;
   const home = opts.home ?? homedir();
-  const { skills, agents } = collectContent();
+  const { skills, agents, sharedRefs } = collectContent();
   const dirs = target.paths({ scope, projectDir, home });
   const backupRoot = join(scope === 'global' ? home : projectDir, '.mugiwara');
   const result: InstallResult = { written: [], skipped: [], backedUp: [], notes: [] };
@@ -100,10 +110,22 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
 
   for (const s of skills) {
     const out = target.transformSkill(s.data, s.body);
-    if (out) writeOne(join(dirs.skillsDir, out.relPath), out.text);
+    if (out) {
+      let text = out.text;
+      if (target.refPointerPrefix !== undefined && target.refPointerPrefix !== '') {
+        text = text.replace(/`_shared\/references\//g, '`' + target.refPointerPrefix + '_shared/references/');
+      }
+      writeOne(join(dirs.skillsDir, out.relPath), text);
+    }
     if (target.transformSkillFull) {
       const full = target.transformSkillFull(s.data, s.body);
-      if (full && target.refsDir) writeOne(join(target.refsDir({ scope, projectDir, home }, s.name), full.relPath), full.text);
+      if (full && target.refsDir) {
+        let text = full.text;
+        if (target.refPointerPrefix !== undefined && target.refPointerPrefix !== '') {
+          text = text.replace(/`_shared\/references\//g, '`' + target.refPointerPrefix + '_shared/references/');
+        }
+        writeOne(join(target.refsDir({ scope, projectDir, home }, s.name), full.relPath), text);
+      }
     }
     if (s.refs.length && target.refsDir) {
       const refsRoot = target.refsDir({ scope, projectDir, home }, s.name);
@@ -111,7 +133,7 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
     }
   }
   for (const a of agents) {
-    const out = target.transformAgent(a.data, a.body);
+    const out = target.transformAgent({ ...a.data, ...(a.internal ? { 'internal-agent': 'true' } : {}) }, a.body);
     if (out) writeOne(join(dirs.agentsDir, out.relPath), out.text);
     if (target.transformAgentFull) {
       const full = target.transformAgentFull(a.data, a.body);
@@ -119,6 +141,11 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
     }
   }
 
+  if (sharedRefs.length) {
+    const sharedRoot = join(dirs.skillsDir, '_shared', 'references');
+    for (const r of sharedRefs) writeOne(join(sharedRoot, r.relPath), r.text);
+  }
+
   if (target.postInstall) {
     const post = target.postInstall({ scope, projectDir, home, dryRun, files: result.written });
     result.written.push(...post.written);
@@ -144,3 +171,39 @@ export function removeInstalled(manifest: { files: string[] }, { dryRun = false
   }
   return removed;
 }
+
+function assertNotSymlink(file: string): void {
+  if (!existsSync(file)) return;
+  try {
+    if (lstatSync(file).isSymbolicLink()) throw new Error(`refusing to follow symlink: ${file}`);
+  } catch (e) {
+    if ((e as { code?: string }).code === 'ENOENT') return;
+    throw e;
+  }
+}
+
+const GITIGNORE_MARKER = '# mugiwara';
+const GITIGNORE_BLOCK = `# mugiwara — audit trail is the product: commit reports/, results/, logs/, spec/, plans/.
+# Ignore session state and regenerated files.
+.mugiwara/state.json
+.mugiwara/state-*.json
+.mugiwara/config
+.mugiwara/continue.md
+.mugiwara/refs/
+`;
+
+export function ensureProjectGitignore(projectDir: string, opts: { dryRun?: boolean } = {}): { appended: boolean; notes: string[] } {
+  const { dryRun = false } = opts;
+  const path = join(projectDir, '.gitignore');
+  assertNotSymlink(path);
+  if (existsSync(path) && readFileSync(path, 'utf8').includes(GITIGNORE_MARKER)) {
+    return { appended: false, notes: [] };
+  }
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const separator = existing.length && !existing.endsWith('\n') ? '\n' : '';
+  if (!dryRun) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, existing + separator + GITIGNORE_BLOCK);
+  }
+  return { appended: true, notes: [`.gitignore ${dryRun ? 'would append' : 'appended'} mugiwara audit-trail block`] };
+}

package/src/mission.ts

@@ -1,6 +1,6 @@
 // src/mission.ts
 // Mission-state helpers for the mugiwara CLI (installer + reset only).
-import { existsSync, rmSync, readFileSync } from 'node:fs';
+import { existsSync, rmSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 function activeActor(projectDir: string): string | null {
@@ -30,10 +30,12 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
     const p = join(root, dir);
     if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(dir); }
   }
-  // mission state files
-  for (const f of ['state.json']) {
-    const p = join(root, f);
-    if (existsSync(p)) { rmSync(p); removed.push(f); }
+  // mission state files — state.json + branch-specific state-*.json
+  for (const f of readdirSync(root)) {
+    if (/^state(-.+)?\.json$/.test(f)) {
+      const p = join(root, f);
+      if (existsSync(p)) { rmSync(p); removed.push(f); }
+    }
   }
   if (!keepLogs) {
     const p = join(root, 'logs');
@@ -46,3 +48,113 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
   }
   return { removed, kept };
 }
+
+export function archiveMission(projectDir: string, mission: string, opts: { dryRun?: boolean } = {}): { report: string | null; removed: string[]; kept: string[]; index?: string } {
+  const { dryRun = false } = opts;
+  const root = join(projectDir, '.mugiwara');
+  // mission allowlist — same as savepoint.sh / mission-report.sh. Dot-only
+  // names (".", "..") would resolve upward through join(...,"..") and let
+  // rmSync reach state.json/config outside the mission dir.
+  if (!mission || /[^a-zA-Z0-9._-]/.test(mission) || /^\.+$/.test(mission)) throw new Error(`invalid mission name "${mission}" (allowlist: [a-zA-Z0-9._-], not a dot-path)`);
+  const removed: string[] = [];
+  const kept: string[] = [];
+
+  // A file belongs to this mission when stripping the optional YYYY-MM-DD-
+  // prefix leaves `<mission>.md` or `<mission>-<suffix>.md`. Covers both the
+  // bare names and the date-prefixed names the prose writes (audit-trail.md).
+  const belongs = (f: string): boolean => {
+    const base = f.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+    return base === `${mission}.md` || base.startsWith(`${mission}-`);
+  };
+
+  // locate the report (the archive target that must survive). Reports are
+  // date-prefixed (`reports/YYYY-MM-DD-<mission>.md`); compare the stripped
+  // mission name so `bar-foo.md` is not mistaken for mission `foo`.
+  let report: string | null = null;
+  const reportsDir = join(root, 'reports');
+  if (existsSync(reportsDir)) {
+    const f = readdirSync(reportsDir).find(n => {
+      const m = n.match(/^(\d{4}-\d{2}-\d{2})-(.+)\.md$/);
+      return !!m && m[2] === mission;
+    });
+    if (f) report = join('reports', f);
+  }
+
+  // remove per-mission wave intermediates from results/<mission>/, EXCEPT
+  // 06-closure.md and 07-pr-verdict.md (PR material + closure stay)
+  const resultsDir = join(root, 'results', mission);
+  if (existsSync(resultsDir)) {
+    for (const f of readdirSync(resultsDir)) {
+      if (f === '06-closure.md' || f === '07-pr-verdict.md') { kept.push(join('results', mission, f)); continue; }
+      const p = join(resultsDir, f);
+      if (!dryRun) rmSync(p, { recursive: true, force: true });
+      removed.push(join('results', mission, f));
+    }
+  }
+
+  // spec, review, issues, per-mission decision log — bare + date-prefixed
+  const specDir = join(root, 'spec');
+  if (existsSync(specDir)) {
+    for (const f of readdirSync(specDir)) {
+      if (!belongs(f)) continue;
+      const p = join(specDir, f);
+      if (!dryRun) rmSync(p);
+      removed.push(join('spec', f));
+    }
+  }
+
+  for (const dir of ['review', 'issues']) {
+    const d = join(root, dir);
+    if (!existsSync(d)) continue;
+    for (const f of readdirSync(d)) {
+      if (!belongs(f)) continue;
+      const p = join(d, f);
+      if (!dryRun) rmSync(p, { force: true });
+      removed.push(join(dir, f));
+    }
+  }
+
+  const logsDir = join(root, 'logs');
+  if (existsSync(logsDir)) {
+    for (const f of readdirSync(logsDir)) {
+      if (!belongs(f)) continue;
+      const p = join(logsDir, f);
+      if (!dryRun) rmSync(p);
+      removed.push(join('logs', f));
+    }
+  }
+
+  // continue.md is a session handoff — only remove it if it belongs to THIS
+  // mission (its content references the mission name); otherwise leave it.
+  const cont = join(root, 'continue.md');
+  if (existsSync(cont)) {
+    try {
+      if (readFileSync(cont, 'utf8').includes(mission)) {
+        if (!dryRun) rmSync(cont);
+        removed.push('continue.md');
+      }
+    } catch { /* unreadable — leave it */ }
+  }
+
+  // kept: report + the audit-trail survivors
+  if (report) kept.push(report);
+  for (const k of ['plans', 'config', 'state.json', join('logs', 'lessons.md')]) {
+    if (existsSync(join(root, k))) kept.push(k);
+  }
+
+  // summary index: append one line per archived mission (retention aid),
+  // idempotently — never duplicate a line for an already-indexed mission.
+  let index: string | undefined;
+  const indexFile = join(root, 'reports', 'index.md');
+  const line = `- ${mission} — ${new Date().toISOString().slice(0, 10)}${report ? ` → ${report}` : ''}\n`;
+  if (!dryRun) {
+    mkdirSync(join(root, 'reports'), { recursive: true });
+    const existing = existsSync(indexFile) ? readFileSync(indexFile, 'utf8') : '';
+    if (!existing.split(/\r?\n/).some(l => l.startsWith(`- ${mission} —`))) {
+      const header = existing ? '' : '# Mission index\n\n';
+      appendFileSync(indexFile, header + line);
+    }
+    index = join('reports', 'index.md');
+  }
+  return { report, removed, kept, index };
+}

package/src/targets/claude.ts

@@ -1,17 +1,27 @@
 // src/targets/claude.ts
-import { existsSync, readFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, copyFileSync, chmodSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stringifyFrontmatter, type FrontmatterData } from '../frontmatter.ts';
 import type { Target } from '../installer.ts';
 
 const here = dirname(fileURLToPath(import.meta.url));
-const HOOK_SRC = join(here, '..', '..', 'hooks', 'session-start.ts');
+const HOOKS_SRC = join(here, '..', '..', 'hooks');
+const COMMANDS_SRC = join(here, '..', '..', '.claude', 'commands');
+
+// Claude Code has no path-scoped permission. write-scope maps to a partial
+// `tools:` list: artifacts agents lose Edit (cannot modify existing source)
+// but keep Write (must create .mugiwara/**); source agents get the default set.
+function toolsFromScope(scope?: string): string | undefined {
+  if (scope === 'artifacts') return 'Read, Grep, Glob, Write, Bash, WebFetch, WebSearch';
+  return undefined;
+}
 
 export const target: Target = {
   id: 'claude',
   label: 'Claude Code',
   native: true,
+  refPointerPrefix: '../',
   paths({ scope, projectDir, home }) {
     const root = scope === 'global' ? join(home, '.claude') : join(projectDir, '.claude');
     return { skillsDir: join(root, 'skills'), agentsDir: join(root, 'agents') };
@@ -25,6 +35,10 @@ export const target: Target = {
   transformAgent(data: FrontmatterData, body: string) {
     const fm: FrontmatterData = { name: data.name, description: data.description };
     if (data.tools) fm.tools = data.tools;
+    else {
+      const generated = toolsFromScope(data['write-scope']);
+      if (generated) fm.tools = generated;
+    }
     return { relPath: `${data.name}.md`, text: stringifyFrontmatter(fm, body) };
   },
   refsDir({ scope, projectDir, home }, skillName: string) {
@@ -32,15 +46,37 @@ export const target: Target = {
     return join(root, 'skills', skillName, 'references');
   },
   postInstall({ scope, projectDir, home, dryRun }) {
-    // Wire the SessionStart hook (inline doctrine) into the installed .claude dir.
+    // Wire hook scripts (SessionStart + UserPromptSubmit) into the installed .claude dir.
     const root = scope === 'global' ? join(home, '.claude') : join(projectDir, '.claude');
-    const hookFile = join(root, 'hooks', 'session-start.ts');
+    const written: string[] = [];
+    const notes: string[] = [];
     if (dryRun) return { written: [], notes: [] };
-    if (existsSync(HOOK_SRC) && !existsSync(hookFile)) {
-      mkdirSync(dirname(hookFile), { recursive: true });
-      copyFileSync(HOOK_SRC, hookFile);
-      return { written: [hookFile], notes: [] };
+    if (existsSync(HOOKS_SRC)) {
+      for (const f of readdirSync(HOOKS_SRC)) {
+        if (!f.endsWith('.ts')) continue;
+        const dst = join(root, 'hooks', f);
+        if (!existsSync(dst)) {
+          mkdirSync(dirname(dst), { recursive: true });
+          copyFileSync(join(HOOKS_SRC, f), dst);
+          // /bin/sh executes hooks via shebang — a non-executable copy is a
+          // "Permission denied" at first user prompt. chmod every hook file.
+          chmodSync(dst, 0o755);
+          written.push(dst);
+        }
+      }
+    }
+    // Port the /mugiwara commands into the installed .claude dir.
+    if (existsSync(COMMANDS_SRC)) {
+      const dstDir = join(root, 'commands');
+      mkdirSync(dstDir, { recursive: true });
+      for (const f of readdirSync(COMMANDS_SRC)) {
+        if (!f.endsWith('.md')) continue;
+        const src = join(COMMANDS_SRC, f);
+        const dst = join(dstDir, f);
+        if (!existsSync(dst)) { copyFileSync(src, dst); written.push(dst); }
+        else notes.push(`existing command kept: ${dst}`);
+      }
     }
-    return { written: [], notes: [] };
+    return { written, notes };
   },
 };

package/src/targets/generic.ts

@@ -44,7 +44,7 @@ export function makeGeneric(opts: {
       if (stubOnly) {
         return {
           relPath: `agent-${data.name}.md`,
-          text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills: ${data.skills ?? ''}. Read \`.mugiwara/refs/${data.name}.md\` when embodying this role.`,
+          text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills: ${data.skills ?? ''}. Read \`.mugiwara/refs/${data.name}.md\` when embodying this role.\n\nOnly zoro-execution and brook-healing may modify source code.\nReturn your output to luffy-orchestrator; do not choose the next step.`,
         };
       }
       return { relPath: `agent-${data.name}.md`, text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills used: ${data.skills ?? ''}\n\n${body}` };

package/src/targets/opencode.ts

@@ -20,26 +20,45 @@ const CREW: Record<string, CrewConfig> = {
   'usopp-brainstorm': { color: '#f59e0b', temperature: 0.6, steps: 15 },
   'nami-planner': { color: '#f97316', temperature: 0.2, steps: 15 },
   'zoro-execution': { color: '#22c55e', temperature: 0.1, steps: 30 },
-  'chopper-checkpoint': { color: '#3b82f6', temperature: 0.1, permission: { edit: 'deny' }, steps: 15 },
-  'sanji-quality': { color: '#a855f7', temperature: 0.1, permission: { edit: 'deny' }, steps: 10 },
-  'franky-gates': { color: '#06b6d4', temperature: 0.1, permission: { edit: 'deny' }, steps: 10 },
-  'robin-reviewer': { color: '#8b5cf6', temperature: 0.2, permission: { edit: 'deny' }, steps: 15 },
-  'jinbe-security': { color: '#6366f1', temperature: 0.2, permission: { edit: 'deny' }, steps: 15 },
+  'chopper-checkpoint': { color: '#3b82f6', temperature: 0.1, steps: 15 },
+  'sanji-quality': { color: '#a855f7', temperature: 0.1, steps: 10 },
+  'franky-gates': { color: '#06b6d4', temperature: 0.1, steps: 10 },
+  'robin-reviewer': { color: '#8b5cf6', temperature: 0.2, steps: 15 },
+  'jinbe-security': { color: '#6366f1', temperature: 0.2, steps: 15 },
   'brook-healing': { color: '#ec4899', temperature: 0.1, steps: 20 },
-  'skeptic-verifier': { color: '#64748b', temperature: 0.1, permission: { edit: 'deny' }, steps: 12 },
+  'skeptic-verifier': { color: '#64748b', temperature: 0.1, steps: 12 },
   'eval-runner': { color: '#14b8a6', temperature: 0.2, steps: 15 },
   'resume-coordinator': { color: '#d97706', temperature: 0.2, steps: 10 },
   'memory-keeper': { color: '#d946ef', temperature: 0.2, steps: 8 },
 };
 
-function agentFrontmatter(name: string, description: string) {
+// write-scope is the single source of truth (content/agents/*.md frontmatter).
+// The path boundary (artifacts vs source) IS expressible in opencode:
+// permission.edit accepts glob/pattern -> action, last match wins. Artifacts
+// agents get deny-all-edit except .mugiwara/**; source agents (zoro, brook)
+// get full edit allow. Derived at install time from the frontmatter field.
+function permissionFromScope(scope: string | undefined): Record<string, string | Record<string, string>> | undefined {
+  if (scope === 'source') return { edit: 'allow' };
+  if (scope === 'artifacts') return { edit: { '*': 'deny', '.mugiwara/**': 'allow' } };
+  return undefined;
+}
+
+function agentFrontmatter(name: string, description: string, writeScope?: string) {
   const crew = CREW[name];
   const lines = [`description: ${description}`, `mode: all`];
   if (crew) {
     lines.push(`color: '${crew.color}'`, `temperature: ${crew.temperature}`, `steps: ${crew.steps}`);
-    if (crew.permission) {
+    const perm = permissionFromScope(writeScope);
+    if (perm) {
       lines.push('permission:');
-      for (const [k, v] of Object.entries(crew.permission)) lines.push(`  ${k}: ${v}`);
+      for (const [k, v] of Object.entries(perm)) {
+        if (typeof v === 'string') {
+          lines.push(`  ${k}: ${v}`);
+        } else {
+          lines.push(`  ${k}:`);
+          for (const [pk, pv] of Object.entries(v)) lines.push(`    "${pk}": ${pv}`);
+        }
+      }
     }
   }
   return lines.join('\n');
@@ -49,6 +68,7 @@ export const target: Target = {
   id: 'opencode',
   label: 'opencode',
   native: true,
+  refPointerPrefix: '../',
   paths({ scope, projectDir, home }) {
     const root = scope === 'global' ? join(home, '.config', 'opencode') : join(projectDir, '.opencode');
     return { skillsDir: join(root, 'skills'), agentsDir: join(root, 'agents') };
@@ -60,7 +80,8 @@ export const target: Target = {
     };
   },
   transformAgent(data: FrontmatterData, body: string) {
-    const fm = agentFrontmatter(data.name, data.description);
+    const desc = data['internal-agent'] === 'true' ? `[INTERNAL] ${data.description}` : data.description;
+    const fm = agentFrontmatter(data.name, desc, data['write-scope']);
     return { relPath: `${data.name}.md`, text: `---\n${fm}\n---\n${body}` };
   },
   refsDir({ scope, projectDir, home }, skillName: string) {

package/docs/concepts/agents.md

@@ -1,53 +0,0 @@
-# The Crew — 14 Agents
-
-Every agent is a focused specialist. The main thread embodies each role inline
-using its skill; you can also summon any member directly. "Dispatch" below
-means "route the mission to this role."
-
-The front door is the `using-mugiwara` skill — load it for crew overview.
-Slash command: `/using-mugiwara`.
-
-| Agent | Crew member | Role | Summon for |
-|-------|-------------|------|------------|
-| `luffy-orchestrator` | Luffy | Captain — 5-way triage, check-ins, decisions, closure | mission start, wave boundaries, escalations |
-| `usopp-brainstorm` | Usopp | Critical friend — interrogates, researches, no rubber-stamps | vague ideas, direction, options |
-| `nami-planner` | Nami | Planner — interview-first, full-context scan, scaled plans | turning an idea into an execution plan |
-| `zoro-execution` | Zoro | Executor — inline sequential tasks, parallel worker batches, evidence per task | executing an approved plan |
-| `chopper-checkpoint` | Chopper | Auditor — verify-everything, deduped re-runs, failure ledger | auditing a wave's results |
-| `sanji-quality` | Sanji | Quality — discover real tooling, format/lint/test | after checkpoint passes |
-| `franky-gates` | Franky | Gates — coverage, build, Definition of Done, binary verdicts | after quality checks |
-| `robin-reviewer` | Robin | Reviewer — doubt-driven diff review, breaking-change map first | after gates pass |
-| `jinbe-security` | Jinbe | Security — STRIDE, OWASP, secrets, injection, dependencies | security audit of a diff |
-| `brook-healing` | Brook | Healer — reads the ledger, root-cause fixes, ≤3 cycles | any wave produced failures |
-| `skeptic-verifier` | Skeptic | Adversarial verifier — doubts every output, does NOT validate | high-stakes verdicts, plans, reviews |
-| `eval-runner` | Eval Runner | Harness tester — task suites, judge-agent comparison | verifying mugiwara itself works |
-| `resume-coordinator` | Resume Coordinator | Resumer — rebuilds state from `.mugiwara/`, continues never restarts | context loss, new session mid-mission |
-| `memory-keeper` | Memory Keeper | Institutional memory — surfaces past lessons, captures new ones | mission start + closure |
-
-## How to summon
-
-Say a crew member's name in your request:
-
-```
-> Chopper, audit the last wave against the plan
-> Nami, plan this out
-```
-
-Luffy still records the route and its reason, and direct calls do not skip
-check-ins. The harness stays coherent either way.
-
-## Who never does what
-
-- **Luffy** never implements code.
-- **Chopper** never fixes findings — reports them.
-- **Skeptic** never validates — doubts.
-- **Robin/Jinbe** never implement — findings to Brook.
-- Crew members never dispatch each other. Workers are subagents, never crew.
-
-## The crew ships whole
-
-Every install gets all 14 agents and all 26 skills. No project-type selection —
-the harness routes each task to the right specialist.
-
-See [skills.md](skills.md) for the 26 techniques, or
-[workflow.md](workflow.md) for the pipeline.

package/docs/concepts/audit-trail.md

@@ -1,65 +0,0 @@
-# Audit Trail
-
-Every artifact the Mugiwara crew produces — what writes it, when, and how to
-read it as a reviewer.
-
-## The artifacts
-
-| Artifact | Path | Written by | When | For |
-|----------|------|-----------|------|-----|
-| **Plan doc** | `.mugiwara/plans/YYYY-MM-DD-<mission>.md` | Nami (planning) | Wave 2 | Zero-context executor — waves, tasks, criteria, risk |
-| **Spec** | `.mugiwara/spec/YYYY-MM-DD-<mission>.md` | Usopp (brainstorm) / Luffy (spec bridge) | Wave 0–1 | Bridge from idea to plan — goal, acceptance, constraints |
-| **State** | `.mugiwara/state.json` | `scripts/savepoint.sh` | Every wave boundary | Computed mission state: lane, wave, files, blockers, token budget, evidence paths |
-| **Decision log** | `.mugiwara/logs/YYYY-MM-DD-<mission>.md` | Luffy (orchestrator) | Every wave | Route reason, check-in verdicts, mode flips, decisions |
-| **Blocker ledger** | `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` | Any agent | On blocker hit | Row per blocker: wave, task, symptom, attempted, help-needed |
-| **Todo list** | `.mugiwara/results/<mission>-todos.md` | Zoro (execution) | Wave 3 | Checkbox per task, checked with evidence pointer |
-| **Audit report** | `.mugiwara/results/YYYY-MM-DD-<mission>-audit.md` | Chopper (checkpoint) | Wave 4 | Per-task evidence, commit hygiene, parallel-conflict, honest classification |
-| **Quality report** | `.mugiwara/results/YYYY-MM-DD-<mission>-quality.md` | Sanji (quality) | Wave 5 | Formatter/linter/unit/user-test results |
-| **Gate verdict** | `.mugiwara/results/YYYY-MM-DD-<mission>-gates.md` | Franky (gates) | Wave 6 | Coverage thresholds from config, build exit, DoD verdict |
-| **Review findings** | `.mugiwara/review/YYYY-MM-DD-<mission>-review.md` | Robin (review) | Wave 7 | Severity-tagged: path:line → problem → fix |
-| **Security report** | `.mugiwara/review/YYYY-MM-DD-<mission>-security.md` | Jinbe (security) | Wave 7 | STRIDE, OWASP mapping, checklist, CVSS severity |
-| **Heal report** | `.mugiwara/results/YYYY-MM-DD-<mission>-heal.md` | Brook (healing) | Wave 8 | Fixed list, escalated list, updated ledger |
-| **Closure report** | `.mugiwara/results/YYYY-MM-DD-<mission>-closure.md` | Luffy (orchestrator) | Wave 9 | Mission summary, per-wave outcomes, deferred items, lessons |
-| **Mission report** | `.mugiwara/reports/YYYY-MM-DD-<mission>.md` | `scripts/mission-report.sh` | Wave 9 | Human-readable summary: what changed, gates, state, token cost |
-| **PR verdict** | `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md` | Luffy (orchestrator) | Wave 9 | Ready PR summary block for the user to open the PR |
-| **Trace** | `.mugiwara/results/<mission>-trace.md` | Resume coordinator | Every dispatch | Dispatch → outcome — drives resume (legacy; state.json preferred) |
-| **Lessons ledger** | `.mugiwara/logs/lessons.md` | Memory Keeper | Cross-mission | One row per real lesson, append-only, all actors share |
-| **Evidence logs** | `.mugiwara/results/<label>-<hash>.log` | `scripts/evidence.sh` | On demand | Command stdout/stderr capture with timestamp and exit code |
-
-## How to read as a reviewer
-
-1. **Start with the mission report** (`reports/`) — one file, what changed, gates, token cost.
-2. **Check the gate verdict** (`results/<mission>-gates.md`) — coverage from config, build, DoD. Any FAIL needs explanation.
-3. **Spot-check the audit report** (`results/<mission>-audit.md`) — did Chopper re-run checks or accept claims? Every criterion gets a command run + evidence row.
-4. **Review findings count** (`review/`) — how many blocker/major/minor? Were they healed? Check the heal report for closure.
-5. **State.json** for raw numbers — lane, wave, files, blockers open, heal cycle, token budget status (ok/warn/stop).
-
-## What stays after cleanup
-
-After Wave 9 closure (run via `mugiwara-ship` cleanup procedure):
-
-**Kept** (audit trail + PR material):
-- `config` — runtime config
-- `plans/<mission>.md` — clean plan doc
-- `results/<mission>-closure.md` — closure report
-- `results/<mission>-pr-verdict.md` — PR material
-- `reports/<mission>.md` — mission report
-- `state.json` — final mission state (unless another actor's mission is active)
-- `logs/lessons.md` — cross-mission lessons
-- `backup/`, `manifest.json` — harness config
-
-**Deleted** (consumed/superseded):
-- `spec/<mission>.md` — consumed by planning
-- `results/<mission>-todos.md` — consumed
-- `results/<mission>-audit.md` — superseded by closure
-- `results/<mission>-quality.md` — consumed
-- `results/<mission>-gates.md` — consumed
-- `results/<mission>-heal.md` — consumed
-- `results/<mission>-trace.md` — consumed (state.json is canonical)
-- `review/<mission>-review.md` — consumed
-- `review/<mission>-security.md` — consumed
-- `issues/<mission>-blockers.md` — consumed
-- `logs/<mission>.md` — decision log, per-mission
-
-Cleanup lists candidates first (dry-run), then deletes. A mission is only
-closed after cleanup runs.

package/docs/concepts/comparison.md

@@ -1,58 +0,0 @@
-# Positioning
-
-What mugiwara is and when to use something else.
-
-## What mugiwara is
-
-**Mugiwara is the governance layer for AI-assisted engineering work.** Every
-change carries a human-reviewable trail — which wave, what evidence, approved
-by whom — and the cost of the process scales to the size of the work.
-
-- **Lane sizing** — process scales from zero waves (typo) to nine (auth
-  migration), computed from the diff by `scripts/lane.sh`, not guessed.
-- **Evidence trail** — every wave boundary writes computed state to
-  `state.json`. No wave passes on a spoken claim. `scripts/evidence.sh` wraps
-  check commands and captures output.
-- **Resume from disk** — lose context mid-mission and the crew rebuilds from
-  `.mugiwara/` instead of restarting.
-- **15 named agents** in a 9-wave gated pipeline — each wave has a defined
-  owner, handoff, and verification gate.
-- **26 skills** with skip gates on all of them, progressive disclosure into
-  `references/`, and deterministic tooling for lane, evidence, and state.
-
-## What mugiwara refuses
-
-- **A runtime or daemon.** Orchestration stays in the harness. Pure markdown.
-- **Auto-merge or auto-deploy.** Human review at the PR is the terminal gate.
-- **Unattended marathon mode.** Mugiwara runs inline by default — you watch
-  every wave. Subagents only for parallel work.
-- **Skill-count growth.** 26 is the ceiling; a new skill replaces an old one.
-- **Head-to-head feature scorecards.** The compliance matrix replaces them.
-
-## When to use something else
-
-- **Deep autonomous marathon runs.** If you want an agent to disappear for
-  hours on subagent-driven builds with minimal visibility, superpowers'
-  `subagent-driven-development` is built for exactly that.
-- **Reference-encyclopedia depth.** agent-skills carries richer per-skill
-  engineering references (Hyrum's Law, test pyramid, Chesterton's Fence).
-- **A runtime service.** If you need API-driven, deployable agent crews, use a
-  framework (LangGraph, CrewAI).
-- **A single mega-prompt.** If you want one instruction with no ceremony,
-  mugiwara's pipeline is overkill for you.
-
-## Reproducible facts
-
-Generated from `content/` and `scripts/validate-content.ts`:
-
-| Metric | Value |
-|--------|:-----:|
-| Skills | 26 |
-| Agents | 15 |
-| Index (all descriptions) | ~10k chars (~2.5k tokens) |
-| Avg skill size | ~1.2k tokens |
-| Skills with skip gate | 26/26 |
-| References/ files | growing |
-| Evals | 11 cases |
-
-*Figures from Aug 2026. Recalculate with `bun scripts/validate-content.ts --check-manifest`.*