@ionivetech/mugiwara 0.5.5 → 0.6.0

package/scripts/savepoint.sh

@@ -8,21 +8,30 @@ 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 flag must parse FIRST — it shifts positionals
 BRANCH_MODE=0
 if [ "${1:-}" = "--branch" ]; then
   BRANCH_MODE=1
-  MISSION="${2:-${STATE_MISSION:-}}"
+  shift
+  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}}"
+else
+  MISSION="${1:-${STATE_MISSION:-}}"
+  ACTOR="${2:-${STATE_ACTOR:-${GIT_AUTHOR_NAME:-${USER:-}}}}"
   BRANCH="${3:-$(git branch --show-current 2>/dev/null || echo 'unknown')}"
-  shift 2 2>/dev/null || true
+  WAVE="${4:-${STATE_WAVE:-1}}"
+  MODE="${5:-${STATE_MODE:-guided}}"
 fi
 
+# mission allowlist — MISSION feeds paths + sed + node argv; traversal or
+# sed metacharacters must not reach filesystem operations
+case "$MISSION" in
+  ""|*[!a-zA-Z0-9._-]*) die "invalid mission name \"$MISSION\" (allowlist: [a-zA-Z0-9._-])" ;;
+esac
+
 # per-branch state file when --branch used
 BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
 if [ "$BRANCH_MODE" -eq 1 ]; then
@@ -69,6 +78,19 @@ else
   LANE_REASON="$FILES_TOUCHED file(s) under 20 LOC"
 fi
 
+# path-weighted sizing (mirrors lane.sh): docs-only changes outside the product
+# surface never escalate to full from file count alone; sensitive-path
+# escalation above still wins.
+PRODUCT_PAT="^content/|^src/|^scripts/|^test/|^hooks/|^\.opencode/|^\.claude/|^evals/"
+if [ "$LANE" = "full" ] && [ -n "$CHANGED_FILES" ]; then
+  CODE_COUNT=$(echo "$CHANGED_FILES" | grep -E "$PRODUCT_PAT" 2>/dev/null | grep -c . || true)
+  if [ -z "$CODE_COUNT" ] || [ "$CODE_COUNT" -eq 0 ] 2>/dev/null; then
+    PREV="$LANE"
+    LANE="standard"
+    LANE_REASON="$FILES_TOUCHED files, docs-only — path-weighted down from $PREV"
+  fi
+fi
+
 # task counts from plan doc
 PLAN_FILE=$(ls "$MUGIWARA_DIR/plans/${MISSION}.md" 2>/dev/null || true)
 TASKS_DONE=0
@@ -85,22 +107,29 @@ if [ -n "$BLOCKERS_FILE" ] && [ -f "$BLOCKERS_FILE" ]; then
   BLOCKERS_OPEN=$(grep -c '|' "$BLOCKERS_FILE" 2>/dev/null || echo 0)
 fi
 
-# heal cycle
+# heal cycle — count WAVE-8 banner occurrences in the trace, not the word
+# "heal" anywhere (heal workers/healing text would inflate the counter and
+# cause a premature halt)
 HEAL_CYCLE=1
-TRACE_FILE=$(ls "$MUGIWARA_DIR/results/${MISSION}-trace.md" 2>/dev/null || true)
+TRACE_FILE=$(ls "$MUGIWARA_DIR/results/${MISSION}/"*trace*.md 2>/dev/null | head -1 || 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_COUNT=$(grep -ci '^.*Wave 8.*\|wave 8' "$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)
+# evidence paths — per-mission results folder (quoted printf, no sed — mission
+# name is allowlisted above, but avoid sed metacharacter semantics entirely)
+EVIDENCE=""
+for evf in "$MUGIWARA_DIR/results/${MISSION}/"*.md; do
+  [ -f "$evf" ] || continue
+  EVIDENCE="${EVIDENCE}${EVIDENCE:+,}.mugiwara/results/${MISSION}/$(basename "$evf")"
+done
 
-# skill version from package.json
+# skill version from package.json (argv-passing — never interpolate paths into node -e)
 SKILL_VERSION="1"
 if [ -f package.json ]; then
   PKG_JSON="$MUGIWARA_DIR/../package.json"
-  [ -f "$PKG_JSON" ] && SKILL_VERSION=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('$PKG_JSON','utf8')).version.split('.')[0])}catch(e){console.log('1')}" 2>/dev/null || echo "1")
+  [ -f "$PKG_JSON" ] && SKILL_VERSION=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')).version.split('.')[0])}catch(e){console.log('1')}" "$PKG_JSON" 2>/dev/null || echo "1")
 fi
 
 # tokens from env var (harness exports estimated tokens consumed)
@@ -126,41 +155,59 @@ 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
+# --- lane-rise compare (F9): read previous state, flag escalation ---
+LANE_PREV=""
+LANE_ROSE=false
+if [ -f "$STATE_FILE" ]; then
+  LANE_PREV=$(node -e "try{const s=require(process.argv[1]);process.stdout.write(s.lane||'')}catch(e){process.stdout.write('')}" "$STATE_FILE" 2>/dev/null || true)
+  if [ -n "$LANE_PREV" ] && [ "$LANE_PREV" != "$LANE" ]; then
+    # lane order: direct < lean < standard < full < spike (spike resizes, not a rise)
+    case "$LANE_PREV:$LANE" in
+      direct:lean|direct:standard|direct:full|lean:standard|lean:full|standard:full) LANE_ROSE=true ;;
+      *) LANE_ROSE=false ;;
+    esac
+  fi
+fi
 
+node -e "
+const data = {
+  mission: process.argv[1],
+  actor: process.argv[2],
+  branch: process.argv[3],
+  lane: process.argv[4],
+  lane_reason: process.argv[5],
+  lane_prev: process.argv[24] || null,
+  lane_rose: process.argv[25] === 'true',
+  wave: parseInt(process.argv[6], 10),
+  mode: process.argv[7],
+  base_sha: process.argv[8],
+  head_sha: process.argv[9],
+  files_touched: parseInt(process.argv[10], 10),
+  loc_delta: parseInt(process.argv[11], 10),
+  sensitive_paths: process.argv[12] ? process.argv[12].split(',').filter(Boolean) : [],
+  tasks: { done: parseInt(process.argv[13], 10), total: parseInt(process.argv[14], 10) },
+  blockers_open: parseInt(process.argv[15], 10),
+  heal_cycle: parseInt(process.argv[16], 10),
+  tokens_est: parseInt(process.argv[17], 10) || 0,
+  budget: parseInt(process.argv[18], 10) || 0,
+  budget_status: process.argv[19],
+  skill_version: process.argv[20],
+  evidence: process.argv[21] ? process.argv[21].split(',').filter(Boolean) : [],
+  updated_at: process.argv[22]
+};
+require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\n');
+" \
+  "$MISSION" "$ACTOR" "$BRANCH" "$LANE" "$LANE_REASON" \
+  "$WAVE" "$MODE" "$BASE_SHA" "$HEAD_SHA" "$FILES_TOUCHED" \
+  "$LOC_DELTA" "$SENSITIVE_PATHS" "$TASKS_DONE" "$TASKS_TOTAL" \
+  "$BLOCKERS_OPEN" "$HEAL_CYCLE" "$TOKENS_EST" "$BUDGET" \
+  "$STATUS" "$SKILL_VERSION" "$EVIDENCE" \
+  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  "$STATE_FILE" "$LANE_PREV" "$LANE_ROSE"
+
+if [ "$LANE_ROSE" = true ]; then
+  echo "⚠ LANE ROSE: $LANE_PREV → $LANE ($LANE_REASON) — escalate per check-in protocol"
+fi
 echo "✓ savepoint written: $STATE_FILE (lane=$LANE, wave=$WAVE, files=$FILES_TOUCHED)"

package/scripts/validate-content.ts

@@ -27,6 +27,30 @@ function checkFile(file: string, wantName: string, kind: 'skill' | 'agent'): Rec
     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`);
   }
+  if (kind === 'skill') {
+    const lines = body.split(/\r?\n/);
+    const headingRe = /^## /;
+    const sections: { heading: string; start: number; end: number }[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (headingRe.test(lines[i])) sections.push({ heading: lines[i].replace(/^## /, ''), start: i, end: 0 });
+    }
+    for (let si = 0; si < sections.length; si++) {
+      sections[si].end = si + 1 < sections.length ? sections[si + 1].start : lines.length;
+      // count non-empty, non-table, non-code-fence content lines
+      let inFence = false;
+      let contentLines = 0;
+      for (let li = sections[si].start; li < sections[si].end; li++) {
+        const l = lines[li].trim();
+        if (!l) continue;
+        if (l.startsWith('```')) { inFence = !inFence; continue; }
+        if (inFence) continue;
+        if (l.startsWith('|') || l.startsWith('- |')) continue;
+        contentLines++;
+      }
+      if (contentLines >= 20) errors.push(`skill ${file}: section "${sections[si].heading}" is ${contentLines} content lines (≥20) — move to references/`);
+      else if (contentLines >= 15) console.warn(`⚠  skill ${file}: section "${sections[si].heading}" is ${contentLines} content lines (≥15, consider moving to references/)`);
+    }
+  }
   return data;
 }
 
@@ -110,6 +134,59 @@ for (const dir of skillDirs) {
   if (dir !== 'mugiwara-workflow' && !usedSkills.has(dir)) errors.push(`skill ${dir}: not referenced by any agent`);
 }
 
+// --- write-scope gate (F2): every agent declares a scope; only executors may write source ---
+const SOURCE_SCOPED = new Set(['zoro-execution', 'brook-healing']);
+for (const f of agentFiles) {
+  const name = f.replace(/\.md$/, '');
+  const parsed = parseFrontmatter(readFileSync(join(agentDir, f), 'utf8'));
+  const scope = parsed.data['write-scope'];
+  if (!scope) { errors.push(`agent ${f}: missing write-scope (artifacts | source)`); continue; }
+  if (scope !== 'artifacts' && scope !== 'source') errors.push(`agent ${f}: write-scope must be artifacts | source (got "${scope}")`);
+  if (scope === 'source' && !SOURCE_SCOPED.has(name)) errors.push(`agent ${f}: only zoro-execution and brook-healing may declare write-scope: source`);
+}
+
+// --- hub-rule gate (F3): every non-Luffy agent carries both hub sections ---
+for (const f of agentFiles) {
+  const name = f.replace(/\.md$/, '');
+  if (name === 'luffy-orchestrator') continue;
+  const text = readFileSync(join(agentDir, f), 'utf8');
+  if (!text.includes('## Before you start')) errors.push(`agent ${f}: missing "## Before you start" entry protocol`);
+  if (!text.includes('## Return to Luffy')) errors.push(`agent ${f}: missing "## Return to Luffy" hub rule`);
+}
+
+// --- hub-skill gate (F3): every agent lists mugiwara-orchestration (the hub rule's home) ---
+for (const f of agentFiles) {
+  const parsed = parseFrontmatter(readFileSync(join(agentDir, f), 'utf8'));
+  const skills = (parsed.data.skills ?? '').split(',').map(s => s.trim());
+  if (!skills.includes('mugiwara-orchestration')) errors.push(`agent ${f}: missing mugiwara-orchestration in skills (hub rule lives there)`);
+}
+
+// --- handoff-target gate (F4): a body naming another crew member as a handoff
+// target without Luffy in the same line fails CI ---
+const HANDOFF_CREW = ['usopp', 'nami', 'zoro', 'chopper', 'sanji', 'franky', 'robin', 'jinbe', 'brook', 'skeptic', 'memory-keeper', 'resume-coordinator', 'eval-runner'];
+// Verb class covers direct handoff language plus synonyms (route/send/pass/
+// escalate/delegate/transfer) so the F4 gate does not leak through paraphrase.
+const handoffRe = new RegExp(`\\b(hand to|hand off to|dispatch|route to|send to|pass to|escalate to|delegate to|transfer to)\\s+(?:a\\s+|another\\s+|the\\s+)?(?:crew members?|${HANDOFF_CREW.join('|')})`, 'i');
+// Negation must DIRECTLY precede the handoff verb, not sit anywhere in the
+// line ("do not hand off" later in the same line is a different clause).
+const NEGATION_VERB = /\b(never|not|no|don't|do not)\s+(hand|dispatch|route|send|pass|escalate|delegate|transfer)\b/i;
+for (const f of [...agentFiles, ...skillDirs.map(d => join(root, 'skills', d, 'SKILL.md'))]) {
+  if (!existsSync(f)) continue;
+  const text = readFileSync(f, 'utf8');
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = handoffRe.exec(line);
+    if (!m) continue;
+    // clause boundary: only the clause containing the handoff verb counts
+    const clauseStart = line.lastIndexOf('.', m.index) + 1;
+    const clause = line.slice(clauseStart, m.index + m[0].length);
+    if (NEGATION_VERB.test(clause)) continue;      // "never dispatch X" — constraint
+    if (/\bLuffy\b|to Luffy\b/.test(line)) continue; // hub named in same line ("main thread" is NOT the hub — Luffy is)
+    errors.push(`handoff leak ${f.replace(root + '/', '')}:${i + 1}: "${line.trim()}" — handoff target must be Luffy or name Luffy in the same line`);
+  }
+}
+
 // --- manifest-sync check: .claude-plugin/plugin.json must set-equal content/ ---
 const manifestArg = process.argv.indexOf('--check-manifest');
 if (manifestArg !== -1) {

package/scripts/verify-install.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+// scripts/verify-install.ts — G1: verify all references/*.md pointers resolve after install.
+// Installs to temp dir for one target per tier, then checks every pointer.
+
+import { existsSync, mkdtempSync, rmSync, readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { installTo } from '../src/installer.ts';
+import { targets } from '../src/targets/index.ts';
+
+const tierTargets = [
+  { id: 'claude', tier: 1 },
+  { id: 'codex', tier: 2 },
+  { id: 'kilo', tier: 3 },
+];
+
+let total = 0;
+let broken = 0;
+
+for (const tt of tierTargets) {
+  const target = targets[tt.id];
+  if (!target) { console.log(`⚠  target ${tt.id} not found, skipping`); continue; }
+  const dir = mkdtempSync(join(tmpdir(), `mugi-verify-${tt.id}-`));
+  try {
+    installTo(target, { scope: 'project', projectDir: dir, dryRun: false, force: true });
+
+    const skillsDir = target.paths({ scope: 'project', projectDir: dir, home: '' }).skillsDir;
+    const mugiwaraRefsDir = join(dir, '.mugiwara', 'refs');
+
+    function findSkillFiles(root: string): string[] {
+      const out: string[] = [];
+      if (!existsSync(root)) return out;
+      for (const ent of readdirSync(root, { withFileTypes: true })) {
+        const p = join(root, ent.name);
+        if (ent.isDirectory()) out.push(...findSkillFiles(p));
+        else if (ent.name.endsWith('.md')) out.push(p);
+      }
+      return out;
+    }
+
+    const skillFiles = findSkillFiles(skillsDir)
+      .filter(f => !f.replace(skillsDir, '').includes('/references/'));
+
+    for (const file of skillFiles) {
+      const body = readFileSync(file, 'utf8');
+      const refs = [...body.matchAll(/`([^`]*references\/[^`]+\.md)`/g)];
+
+      for (const m of refs) {
+        total++;
+        const pointer = m[1];
+        const localResolve = join(dirname(file), pointer);
+        const mugiwaraResolve = join(mugiwaraRefsDir, pointer.replace(/^(?:_shared\/)?references\//, ''));
+        const resolved = [localResolve, mugiwaraResolve].find(p => existsSync(p));
+
+        if (!resolved) {
+          broken++;
+          const relFile = file.replace(dir + '/', '');
+          console.log(`✗ ${relFile}: \`${pointer}\` → not found`);
+        }
+      }
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (broken > 0) {
+  console.log(`\n✗ ${broken}/${total} pointers cannot resolve after install`);
+  process.exit(1);
+}
+
+console.log(`✓ ${total} pointers checked across ${tierTargets.length} targets — all resolve`);

package/src/installer.ts

@@ -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);

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 } 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');

package/src/targets/claude.ts

@@ -1,5 +1,5 @@
 // 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';
@@ -7,11 +7,13 @@ import type { Target } from '../installer.ts';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const HOOK_SRC = join(here, '..', '..', 'hooks', 'session-start.ts');
+const COMMANDS_SRC = join(here, '..', '..', '.claude', 'commands');
 
 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') };
@@ -35,12 +37,27 @@ export const target: Target = {
     // Wire the SessionStart hook (inline doctrine) 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: [] };
+      chmodSync(hookFile, 0o755);
+      written.push(hookFile);
     }
-    return { written: [], notes: [] };
+    // 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 };
   },
 };

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) {