@ionivetech/mugiwara 0.6.5 → 0.7.0

package/src/rollback.ts

@@ -0,0 +1,95 @@
+// src/rollback.ts
+// Executable rollback map: recovery you can run, not prose.
+// Generated from git + state at closure; the human runs it, mugiwara never does.
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type RollbackInput = {
+  mission: string;
+  branch: string;
+  baseSha: string;
+};
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+/**
+ * Build the rollback script body. Pure given the inputs — the shas are read
+ * from the repo by the caller so this stays unit-testable without git.
+ */
+export function buildRollback(input: RollbackInput, commitsNewestFirst: string[], filesTouched: string[]): string {
+  const lines = [
+    '#!/usr/bin/env bash',
+    `# Rollback map for mission "${input.mission}" — generated at closure.`,
+    '# Human-executed. Review before running; mugiwara never runs this.',
+    `# Branch: ${input.branch}`,
+    `# Base:   ${input.baseSha}`,
+    '',
+    'set -euo pipefail',
+    '',
+  ];
+  if (!commitsNewestFirst.length && !filesTouched.length) {
+    lines.push('# No commits between base and HEAD on this branch — nothing to revert.', '');
+    return lines.join('\n');
+  }
+  if (!commitsNewestFirst.length) {
+    // Squash-merge workflows: the branch's changes reached the base ref as one
+    // squashed commit, so `rev-list base..branch` can come back empty while
+    // `git diff base branch` is not. "Nothing to revert" would be a lie — the
+    // changes are live. Emit loud, human-executable guidance and exit 1 so a
+    // careless run fails instead of silently doing nothing.
+    lines.push(
+      '# UNRESOLVED: squash-merged state detected.',
+      `# git rev-list ${input.baseSha}..${input.branch} is empty, but the diff`,
+      `# ${input.baseSha}..${input.branch} touches ${filesTouched.length} file(s):`,
+      '# the mission\'s changes were collapsed into commit(s) already on the base',
+      '# ref. No per-commit revert list can be derived automatically.',
+      '# Locate the squash commit, review it, then revert it:',
+      `#   git log --oneline ${input.baseSha}..HEAD --grep="${input.mission}"`,
+      '#   git revert <squash-commit>',
+      '# Files carrying the squashed changes (verify each after reverting):',
+      ...filesTouched.map((f) => `#   ${f}`),
+      '',
+      'echo "ROLLBACK INCOMPLETE: squash-merged state — locate and revert the squash commit manually" >&2',
+      'exit 1',
+      '',
+    );
+    return lines.join('\n');
+  }
+  lines.push(
+    '# Revert newest-first so earlier reverts never conflict with later ones.',
+    'git revert --no-edit \\',
+    commitsNewestFirst.map((c) => `  ${c}`).join(' \\\n'),
+    '',
+  );
+  if (filesTouched.length) {
+    lines.push(
+      '# Files this mission touched (verify the working tree is clean afterwards):',
+      ...filesTouched.map((f) => `#   ${f}`),
+      '',
+    );
+  }
+  return lines.join('\n');
+}
+
+/** Read the repo for everything the script needs, then write rollback.sh. */
+export function generateRollback(projectDir: string, missionDir: string, input: RollbackInput): { file: string; commits: number } | null {
+  try {
+    const range = `${input.baseSha}..${input.branch}`;
+    const revList = git(projectDir, ['rev-list', '--reverse', range]).split(/\r?\n/).filter(Boolean);
+    const commitsNewestFirst = [...revList].reverse();
+    const filesTouched = input.baseSha === 'unknown'
+      ? []
+      : git(projectDir, ['diff', '--name-only', input.baseSha, input.branch]).split(/\r?\n/).filter(Boolean);
+    const body = buildRollback(input, commitsNewestFirst, filesTouched);
+    const file = join(missionDir, 'rollback.sh');
+    writeFileSync(file, body, { mode: 0o755 });
+    return { file: 'rollback.sh', commits: commitsNewestFirst.length };
+  } catch {
+    // No git, unknown base, or an empty branch — a rollback map cannot be
+    // derived. Absent file beats a wrong one.
+    return null;
+  }
+}

package/src/routing.ts

@@ -0,0 +1,69 @@
+// src/routing.ts
+// Review routing: tell the reviewer where to look. A ranked
+// reading order computed from what the mission touched — not a flat diff.
+// Heuristic and labeled as such: the ranking decides reading ORDER, never
+// whether a line is correct.
+
+export type RankedFile = { path: string; score: number; reasons: string[] };
+
+const DOC_PAT = /\.(md|txt|rst)$|^docs\/|^(CHANGELOG|LICENSE|README)/;
+const TEST_PAT = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|__tests__|specs?)\//;
+
+export type RoutingSource = { evidence: string[]; sensitive_paths?: string[] };
+
+/**
+ * Score one path. Sensitive paths dominate; production code next; tests and
+ * docs sink. Files the evidence trail never mentions get a bump — absence of
+ * evidence is exactly where review attention pays.
+ */
+export function scorePath(path: string, sensitivePaths: string[], evidenceJoined: string): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  let score = 0;
+  const sensitiveHit = sensitivePaths.some((s) => s && (path === s || path.startsWith(s.replace(/\/?$/, '/')) || new RegExp(s.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*')).test(path)));
+  if (sensitiveHit) {
+    score += 100;
+    reasons.push('sensitive path');
+  }
+  if (!DOC_PAT.test(path) && !TEST_PAT.test(path)) {
+    score += 50;
+    reasons.push('production code');
+  } else if (TEST_PAT.test(path)) {
+    score += 10;
+    reasons.push('test scaffolding — skim unless behavior changed');
+  } else {
+    score += 5;
+    reasons.push('docs/config');
+  }
+  if (!evidenceJoined.includes(path)) {
+    score += 20;
+    reasons.push('not covered by recorded evidence');
+  }
+  return { score, reasons };
+}
+
+export function rankFiles(paths: string[], state: RoutingSource): RankedFile[] {
+  const sensitive = state.sensitive_paths ?? [];
+  const ev = state.evidence.join(' ');
+  return paths
+    .map((path) => {
+      const { score, reasons } = scorePath(path, sensitive, ev);
+      return { path, score, reasons };
+    })
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+}
+
+export function renderRouting(ranked: RankedFile[], mission: string): string {
+  if (!ranked.length) return '';
+  const lines = [
+    '',
+    '## Review routing',
+    '',
+    `Ranked reading order for \`${mission}\` (heuristic ordering — it decides where to look first, never correctness):`,
+    '',
+  ];
+  ranked.forEach((r, i) => {
+    lines.push(`${i + 1}. \`${r.path}\` — ${r.reasons.join('; ')}`);
+  });
+  lines.push('');
+  return lines.join('\n');
+}

package/src/run.ts

@@ -0,0 +1,82 @@
+// src/run.ts
+// `mugiwara run <script> [args...]` — runs a bundled harness script against the
+// current project.
+//
+// Why this exists: the skills tell the crew to run `scripts/savepoint.sh`, but
+// the installer only ever copied `content/` and `references/` into a project.
+// That path resolved against the project's cwd, where the file does not exist,
+// so every savepoint / lane call silently did
+// nothing. Resolving from the package root fixes it for every install target at
+// once.
+import { existsSync, readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// src/ during dev, dist/ once bundled — scripts/ sits beside both
+export const SCRIPTS_DIR = join(here, '..', 'scripts');
+
+/** Scripts a project is meant to call. Anything else stays internal tooling. */
+export const RUNNABLE = ['savepoint.sh', 'lane.sh'] as const;
+
+/**
+ * Locate a POSIX shell. Windows has none natively, but Git for Windows ships
+ * one and mugiwara is git-backed anyway — savepoint reads git to compute state,
+ * so a git-less machine cannot run a mission regardless.
+ */
+export function findBash(): string | null {
+  const explicit = process.env.MUGIWARA_BASH?.trim();
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const candidates =
+    process.platform === 'win32'
+      ? [
+          'C:\\Program Files\\Git\\bin\\bash.exe',
+          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+          join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Git', 'bin', 'bash.exe'),
+        ]
+      : // /bin/bash is not universal on Linux — Alpine and other busybox-based
+        // images ship /bin/sh only. Probing beats assuming: an assumed path
+        // spawns ENOENT, which surfaces as a stack trace instead of the
+        // actionable "no bash found" message below.
+        ['/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash', '/opt/homebrew/bin/bash'];
+  for (const p of candidates) {
+    if (p && existsSync(p)) return p;
+  }
+  // last resort: whatever is on PATH (Git Bash, WSL, MSYS, a nonstandard prefix)
+  const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['bash'], {
+    encoding: 'utf8',
+  });
+  const first = probe.stdout?.split(/\r?\n/).find((l) => l.trim());
+  return first?.trim() || null;
+}
+
+/** Platform-correct remedy for a missing bash — "install Git for Windows" is wrong advice on Linux. */
+export function noBashMessage(): string {
+  const remedy =
+    process.platform === 'win32'
+      ? 'Install Git for Windows (which ships bash)'
+      : 'Install bash with your package manager (e.g. `apk add bash`, `apt install bash`)';
+  return `no bash found. ${remedy}, or set MUGIWARA_BASH to a bash executable.`;
+}
+
+export function runScript(name: string, args: string[], projectDir: string): number {
+  // no path separators: `run` takes a script name, never an arbitrary path
+  if (!/^[a-z0-9-]+\.sh$/.test(name)) {
+    throw new Error(`invalid script name "${name}" (expected one of: ${RUNNABLE.join(', ')})`);
+  }
+  const script = join(SCRIPTS_DIR, name);
+  if (!existsSync(script)) {
+    const have = existsSync(SCRIPTS_DIR) ? readdirSync(SCRIPTS_DIR).filter((f) => f.endsWith('.sh')) : [];
+    throw new Error(`script not found: ${name}${have.length ? ` (available: ${have.join(', ')})` : ''}`);
+  }
+  const bash = findBash();
+  if (!bash) throw new Error(noBashMessage());
+  const r = spawnSync(bash, [script, ...args], {
+    cwd: resolve(projectDir),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (r.error) throw r.error;
+  return r.status ?? 1;
+}

package/src/sign.ts

@@ -0,0 +1,61 @@
+// src/sign.ts
+// Signed attestation: evidence that cannot be fabricated
+// after the fact — optional, user-keyed, never a hard dependency.
+//
+// Uses minisign when it is installed and the user supplies keys. No minisign,
+// no keys → today's behavior, stated plainly in the output. Detached
+// signature lives beside the report (`report.md.minisig`).
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function signArgs(reportPath: string, secretKey: string): string[] {
+  return ['-Sm', reportPath, '-s', secretKey];
+}
+
+export function verifyArgs(reportPath: string, pubKey: string | null): string[] {
+  return pubKey ? ['-Vm', reportPath, '-p', pubKey] : ['-Vm', reportPath];
+}
+
+export function hasMinisign(): boolean {
+  try {
+    execFileSync('minisign', ['-v'], { stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultKey(flag: 'secret' | 'public'): string {
+  return join(homedir(), '.mugiwara', flag === 'secret' ? 'minisign.key' : 'minisign.pub');
+}
+
+export function signReport(projectDir: string, missionDir: string): { ok: boolean; message: string } {
+  const report = join(missionDir, 'report.md');
+  if (!existsSync(report)) return { ok: false, message: 'no report.md to sign — archive first' };
+  if (!hasMinisign()) {
+    return { ok: false, message: 'minisign not installed — signing skipped (install minisign to enable attestation)' };
+  }
+  const secretKey = process.env.MUGIWARA_SIGN_KEY?.trim() || defaultKey('secret');
+  try {
+    execFileSync('minisign', signArgs(report, secretKey), { cwd: projectDir, stdio: 'pipe', input: process.env.MUGIWARA_SIGN_PASSWORD ?? '' });
+    return { ok: true, message: `signed ${report}.minisig (key: ${secretKey})` };
+  } catch (e) {
+    return { ok: false, message: `signing failed: ${(e as Error).message}` };
+  }
+}
+
+export function verifyReport(projectDir: string, missionDir: string): { ok: boolean; message: string } {
+  const report = join(missionDir, 'report.md');
+  const sig = `${report}.minisig`;
+  if (!existsSync(sig)) return { ok: false, message: 'not signed (no .minisig beside report.md)' };
+  if (!hasMinisign()) return { ok: false, message: 'minisign not installed — cannot verify' };
+  const pubKey = existsSync(defaultKey('public')) ? defaultKey('public') : null;
+  try {
+    execFileSync('minisign', verifyArgs(report, pubKey), { cwd: projectDir, stdio: 'pipe' });
+    return { ok: true, message: 'signature verifies against report.md' };
+  } catch {
+    return { ok: false, message: 'SIGNATURE INVALID — report.md changed after signing' };
+  }
+}

package/src/targets/claude.ts

@@ -1,5 +1,5 @@
 // src/targets/claude.ts
-import { existsSync, readFileSync, mkdirSync, copyFileSync, chmodSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, 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';
@@ -19,6 +19,128 @@ function toolsFromScope(scope?: string): string | undefined {
   return undefined;
 }
 
+/**
+ * Register the copied hooks in settings.json.
+ *
+ * Copying hook files into .claude/hooks/ is not enough — Claude Code only runs
+ * a hook that settings.json names. Without this the CLI install left three
+ * dead files on disk while the plugin install (which reads hooks/hooks.json
+ * itself) worked, so the two install paths silently disagreed.
+ *
+ * Idempotent: an entry whose command already points at our hook is left alone,
+ * and unrelated user hooks are never touched.
+ */
+const SCRIPTS_SRC = join(here, '..', '..', 'scripts');
+
+/** Copy the harness shell scripts (and their shared lib) next to the hooks. */
+function copyScripts(dstDir: string): string[] {
+  if (!existsSync(SCRIPTS_SRC)) return [];
+  const written: string[] = [];
+  const copyDir = (src: string, dst: string): void => {
+    if (!existsSync(src)) return;
+    for (const f of readdirSync(src)) {
+      // install.sh is the npx bootstrap, not a harness script — never shipped
+      // into a project.
+      if (!f.endsWith('.sh') || f === 'install.sh') continue;
+      const to = join(dst, f);
+      mkdirSync(dst, { recursive: true });
+      copyFileSync(join(src, f), to);
+      chmodSync(to, 0o755);
+      written.push(to);
+    }
+  };
+  copyDir(SCRIPTS_SRC, dstDir);
+  copyDir(join(SCRIPTS_SRC, 'lib'), join(dstDir, 'lib'));
+  return written;
+}
+
+type HookEntry = { type: string; command: string; timeout?: number };
+type HookGroup = { matcher?: string; hooks: HookEntry[] };
+
+function wireSettings(root: string, hooksDir: string): { written: string[]; notes: string[] } {
+  const file = join(root, 'settings.json');
+  const events: Record<string, { file: string; timeout: number; matcher?: string }> = {
+    SessionStart: { file: 'session-start.js', timeout: 10 },
+    UserPromptSubmit: { file: 'mugiwara-mode-tracker.js', timeout: 5 },
+    Stop: { file: 'auto-savepoint.js', timeout: 20 },
+    SubagentStop: { file: 'pipeline-guard.js', timeout: 15 },
+    // matcher scopes the marker to crew invocations — without it the hook would
+    // fire on every tool call in the session for no benefit
+    PostToolUse: { file: 'engagement-marker.js', timeout: 5, matcher: 'Task|Skill' },
+  };
+
+  let settings: Record<string, unknown> = {};
+  if (existsSync(file)) {
+    try {
+      settings = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>;
+    } catch {
+      // a hand-broken settings.json is the user's to fix — never overwrite it
+      return { written: [], notes: [`${file} is not valid JSON — add the mugiwara hooks manually`] };
+    }
+  }
+  const hooks = (settings.hooks ?? {}) as Record<string, HookGroup[]>;
+  let changed = false;
+  for (const [event, spec] of Object.entries(events)) {
+    const command = join(hooksDir, spec.file);
+    if (!existsSync(command)) continue;
+    const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const already = groups.some((g) => g.hooks?.some((h) => h.command?.includes(spec.file)));
+    if (already) continue;
+    const group: HookGroup = { hooks: [{ type: 'command', command: JSON.stringify(command), timeout: spec.timeout }] };
+    if (spec.matcher) group.matcher = spec.matcher;
+    groups.push(group);
+    hooks[event] = groups;
+    changed = true;
+  }
+  if (!changed) return { written: [], notes: [] };
+  settings.hooks = hooks;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  // NOT reported as `written`: the manifest is an uninstall delete-list, and
+  // settings.json belongs to the user — we only merged into it. It is un-merged
+  // by unwireSettings instead.
+  return { written: [], notes: [`hooks registered in ${file}`] };
+}
+
+/**
+ * Remove only the hook entries mugiwara added, leaving every other setting and
+ * any user-authored hook untouched. Identified by their command pointing into
+ * our hooks dir.
+ */
+function unwireSettings(root: string): { changed: string[]; notes: string[] } {
+  const file = join(root, 'settings.json');
+  if (!existsSync(file)) return { changed: [], notes: [] };
+  let settings: Record<string, unknown>;
+  try {
+    settings = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return { changed: [], notes: [`${file} is not valid JSON — left untouched`] };
+  }
+  const hooks = settings.hooks as Record<string, HookGroup[]> | undefined;
+  if (!hooks) return { changed: [], notes: [] };
+
+  const ours = new Set(['session-start.js', 'mugiwara-mode-tracker.js', 'auto-savepoint.js', 'pipeline-guard.js', 'engagement-marker.js']);
+  const isOurs = (h: HookEntry): boolean =>
+    [...ours].some((f) => h.command?.includes(join('hooks', f)) || h.command?.includes(`hooks/${f}`));
+
+  let changed = false;
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = groups
+      .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isOurs(h)) }))
+      .filter((g) => g.hooks.length > 0);
+    if (kept.length !== groups.length || kept.some((g, i) => g.hooks.length !== groups[i]?.hooks?.length)) {
+      changed = true;
+    }
+    if (kept.length) hooks[event] = kept;
+    else { delete hooks[event]; changed = true; }
+  }
+  if (!changed) return { changed: [], notes: [] };
+  if (!Object.keys(hooks).length) delete settings.hooks;
+  // an emptied settings.json still belongs to the user — rewrite, never remove
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { changed: [file], notes: [] };
+}
+
 export const target: Target = {
   id: 'claude',
   label: 'Claude Code',
@@ -55,7 +177,9 @@ export const target: Target = {
     if (dryRun) return { written: [], notes: [] };
     if (existsSync(HOOKS_SRC)) {
       for (const f of readdirSync(HOOKS_SRC)) {
-        if (!f.endsWith('.ts')) continue;
+        // .js is what settings.json runs (node-only, no bun needed); .ts ships
+        // beside it as the readable source. hooks.json is for plugin installs.
+        if (!/\.(ts|js|json)$/.test(f)) continue;
         const dst = join(root, 'hooks', f);
         if (!existsSync(dst)) {
           mkdirSync(dirname(dst), { recursive: true });
@@ -66,6 +190,15 @@ export const target: Target = {
           written.push(dst);
         }
       }
+      // The Stop hook shells out to savepoint.sh, resolved beside its own
+      // directory. A plugin install already has <plugin>/scripts/; a CLI
+      // install needs the shell scripts copied next to the hooks or the hook
+      // finds nothing and mission state stays empty — the exact bug this
+      // whole path exists to fix.
+      written.push(...copyScripts(join(root, 'scripts')));
+      const wired = wireSettings(root, join(root, 'hooks'));
+      written.push(...wired.written);
+      notes.push(...wired.notes);
     }
     // Port the /mugiwara commands into the installed .claude dir.
     if (existsSync(COMMANDS_SRC)) {
@@ -81,4 +214,9 @@ export const target: Target = {
     }
     return { written, notes };
   },
+  postUninstall({ scope, projectDir, home, dryRun }) {
+    if (dryRun) return { changed: [], notes: [] };
+    const root = scope === 'global' ? join(home, '.claude') : join(projectDir, '.claude');
+    return unwireSettings(root);
+  },
 };

package/src/targets/copilot.ts

@@ -12,10 +12,29 @@ export const target: Target = {
     const root = scope === 'global' ? join(home, '.copilot') : join(projectDir, '.github');
     return { skillsDir: join(root, 'instructions'), agentsDir: join(root, 'agents') };
   },
+  // Copilot injects EVERY matching instruction file into EVERY request — so
+  // the full corpus (26 files, ~27k tokens) was per-request cost, not
+  // per-session. Ship a routing stub here and park the full body in the
+  // per-skill refs dir, which the agent reads on demand. applyTo stays '**/*'
+  // so the routing line is always present; it is a few lines, not a skill.
   transformSkill(data: FrontmatterData, body: string) {
+    void body;
     return {
       relPath: `${data.name}.instructions.md`,
-      text: stringifyFrontmatter({ description: data.description, applyTo: '**/*' }, body),
+      text: stringifyFrontmatter(
+        { description: data.description, applyTo: '**/*' },
+        `# ${data.name}
+
+> ${data.description}
+
+Full skill: read \`.mugiwara/refs/${data.name}/${data.name}.md\` when the crew invokes this role.`,
+      ),
+    };
+  },
+  transformSkillFull(data: FrontmatterData, body: string) {
+    return {
+      relPath: `${data.name}.md`,
+      text: stringifyFrontmatter({ description: data.description }, body),
     };
   },
   transformAgent(data: FrontmatterData, body: string) {

package/src/targets/generic.ts

@@ -31,7 +31,7 @@ export function makeGeneric(opts: {
         // tokens at session start. The agent reads the full file on demand.
         return {
           relPath: `${data.name}.md`,
-          text: `# ${data.name}\n\n> ${data.description}\n\n## Skip when\n\nFull skill: \`${data.name}\` — read \`.mugiwara/refs/${data.name}.md\` when the crew invokes this role.`,
+          text: `# ${data.name}\n\n> ${data.description}\n\n## Skip when\n\nFull skill: \`${data.name}\` — read \`.mugiwara/refs/${data.name}/${data.name}.md\` when the crew invokes this role.`,
         };
       }
       return { relPath: `${data.name}.md`, text: `# ${data.name}\n\n> ${data.description}\n\n${body}` };
@@ -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.\n\nOnly zoro-execution and brook-healing may modify source code.\nReturn your output to luffy-orchestrator; do not choose the next step.`,
+          text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills: ${data.skills ?? ''}. Read \`.mugiwara/refs/${data.name}/${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}` };
@@ -53,10 +53,15 @@ export function makeGeneric(opts: {
       if (!stubOnly) return null;
       return { relPath: `${data.name}.md`, text: `# Agent: ${data.name}\n\n> ${data.description}\n\nSkills used: ${data.skills ?? ''}\n\n${body}` };
     },
-    refsDir({ projectDir }: { scope: Scope; projectDir: string; home: string }) {
+    refsDir({ projectDir }: { scope: Scope; projectDir: string; home: string }, skillName: string) {
       // Keep reference detail outside the rules dir so the harness never
       // glob-loads it; the skill names the path and the agent reads on demand.
-      return join(projectDir, '.mugiwara', 'refs');
+      // Per-skill subdir is load-bearing, not tidiness: a flat refs dir let
+      // same-named references collide (agent-security/checklist.md vs
+      // frontend/checklist.md, contract-first/process.md vs
+      // root-cause/process.md) and first-writer-wins silently served the
+      // wrong document to the skill that asked for it.
+      return join(projectDir, '.mugiwara', 'refs', skillName);
     },
     postInstall({ projectDir, dryRun }) {
       if (!bootstrapFile) return { written: [], notes: [] };

package/src/targets/opencode.ts

@@ -33,7 +33,6 @@ const CREW: Record<string, CrewConfig> = {
   '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 },
-  'onboarding-guide': { color: '#0ea5e9', temperature: 0.3, steps: 15 },
 };
 
 // Crew colors from the wave-banners table (single source of truth). Returns

package/.opencode/commands/mugiwara-execute.md

@@ -1,13 +0,0 @@
----
-description: Execute an approved mugiwara plan as Zoro (execution stage)
----
-Execute the approved plan as Zoro, inline in the main conversation:
-
-1. **Entry protocol first** — read the mission state (`.mugiwara/state/<mission>/[member].json`). No active mission → run Wave 0 triage before anything else. Foreign mission → stop, report owner. Base drift → stop, ask. Non-git → degrade to standard, say so once.
-2. Load the skill: `mugiwara-execution`.
-3. Read the existing plan from `.mugiwara/plans/` — that file is the bridge, never re-plan.
-4. Open a todo list, run tasks sequentially inline; dispatch [PARALLEL] batches to worker subagents only.
-5. Commit per logical task and verify every acceptance criterion with evidence in `.mugiwara/results/`.
-6. **Return the result to Luffy — do not choose the next wave.**
-
-See skills/mugiwara-execution for the wave-structured protocol.

package/.opencode/commands/mugiwara-heal.md

@@ -1,13 +0,0 @@
----
-description: Heal earlier-wave failures as Brook (healing stage, after review/security findings)
----
-Heal failures as Brook, inline in the main conversation:
-
-1. **Entry protocol first** — read the mission state (`.mugiwara/state/<mission>/[member].json`). No active mission → run Wave 0 triage before anything else. Foreign mission → stop, report owner. Base drift → stop, ask. Non-git → degrade to standard, say so once. Read `heal_cycle` — at 3, STOP and escalate to the user.
-2. Load the skill: `mugiwara-healing`.
-3. Read the `.mugiwara/issues` ledger first — stop-the-line triage per failure, never fix blind.
-4. Prove-it before fixing: reproduce or verify the failure from `.mugiwara/results/` evidence.
-5. Apply minimal root-cause fixes, update the ledger with evidence.
-6. **Return the result to Luffy — do not choose the next wave.**
-
-See skills/mugiwara-healing for the triage protocol.

package/.opencode/commands/mugiwara-onboard.md

@@ -1,15 +0,0 @@
----
-description: Run the Mugiwara onboarding wizard — conversation via the onboarding-guide agent, or the terminal wizard (bun scripts/onboard.ts) for CLI users.
----
-Mugiwara onboard: $ARGUMENTS
-
-Run the onboarding wizard. Two paths:
-
-1. Conversation (default): the onboarding-guide agent runs the 9-question
-   wizard through the host's native question tool (choices + free type),
-   then writes .mugiwara/config. No network.
-2. Terminal (CLI users / non-interactive hosts):
-   `bun scripts/onboard.ts`
-
-The wizard never writes .mugiwara/onboard.json. All 15 crew agents are always
-active — no agent-selection step.

package/.opencode/commands/mugiwara-plan.md

@@ -1,17 +0,0 @@
----
-description: Plan a mugiwara mission as Nami (planning stage)
----
-Plan the mission as Nami, inline in the main conversation:
-
-1. **Entry protocol first** — read the mission state (`.mugiwara/state/<mission>/[member].json`). No active mission → run Wave 0 triage before anything else. Foreign mission → stop, report owner. Base drift → stop, ask. Non-git → degrade to standard, say so once.
-2. Load the skill: `mugiwara-planning`.
-3. Classify mission size, interview first, scan full context, write the scaled Quick/Standard/Full plan.
-4. Embody the Nami crew role inline — never Task-dispatch.
-5. Persist the plan to `.mugiwara/plans/`; later stages read it from there as the bridge.
-6. **Return the plan to Luffy — do not choose the next wave.**
-
-Spec input: read `.mugiwara/spec/YYYY-MM-DD-<mission>.md`. If it is empty or
-missing, write the spec bridge from the user's request first (goal, acceptance
-criteria, constraints) before planning — never plan from an empty spec.
-
-See skills/mugiwara-planning for the full template and wave structure.

package/.opencode/commands/mugiwara-ship.md

@@ -1,13 +0,0 @@
----
-description: Close the mission as Luffy (closure + ship stage, at mission end)
----
-Close the mission as Luffy, inline in the main conversation:
-
-1. **Entry protocol first** — read the mission state (`.mugiwara/state/<mission>/[member].json`). No active mission → run Wave 0 triage before anything else. Foreign mission → stop, report owner. Base drift → stop, ask. Non-git → degrade to standard, say so once.
-2. Load the skills: `mugiwara-orchestration` + `mugiwara-ship`.
-3. Run the ship gate: pre-launch checklist, feature flags, staged rollout, mandatory rollback plan — binary GO/NO-GO with evidence.
-4. Bridge on `.mugiwara/plans/` (promise) vs `.mugiwara/results/` (evidence) for the Definition-of-Done verdict.
-5. Close the mission: lessons ledger update, then the terminal step — save-point commit, push the branch, write the PR verdict, hand to the user.
-6. **The crew never creates a PR, never merges, never deploys — hand the branch + verdict to the user.**
-
-See skills/mugiwara-ship for the gate and skills/mugiwara-orchestration for closure.

package/.opencode/commands/using-mugiwara.md

@@ -1,20 +0,0 @@
----
-description: Mugiwara crew reference — how it works, crew overview, pipeline summary. Documentation only.
----
-Mugiwara Reference: $ARGUMENTS
-
-`mugiwara-orchestration` auto-loads as gatekeeper for every task — no need to call this command.
-
-## How it works
-
-- 11 agents: Luffy (triage), Usopp (brainstorm), Nami (plan), Zoro (execute), Chopper (audit), Sanji (quality), Franky (gates), Robin (review), Jinbe (security), Brook (heal), Resume (+3 internal: Skeptic, Eval Runner, Memory)
-- 26 skills — one per crew role + domain skills (frontend, backend, git, security)
-- 9-wave pipeline runs inline in the main conversation
-- Evidence over claims at every wave
-- Autonomy modes: guided, semi, auto
-
-## When to use this command
-
-Use `/using-mugiwara` when you want the crew overview or pipeline summary. For task routing and classification, `mugiwara-orchestration` auto-loads as gatekeeper — you do not need to call this first.
-
-See skills/mugiwara-workflow for the full pipeline.