@ionivetech/mugiwara 0.5.5 → 0.6.1

package/scripts/release-notes.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
-// scripts/release-notes.ts — generates a human-readable release description
-// from git history between the previous tag and HEAD. Grouped by change type,
-// conventional-commit aware, no gh dependency.
+// scripts/release-notes.ts — generates a detailed GitHub Release description
+// from git history between the previous tag and HEAD. Pulls the full commit
+// message (subject + body), groups by conventional-commit type, flags breaking
+// changes, and lists the affected scopes. No gh dependency.
 //
-//   bun scripts/release-notes.ts            notes since the last tag → stdout
+//   bun scripts/release-notes.ts                 notes since the last tag → stdout
 //   bun scripts/release-notes.ts --since v0.3.0   notes from that tag → stdout
 import { execFileSync } from 'node:child_process';
 
@@ -22,15 +23,22 @@ if (!since) {
 }
 
 const range = since ? `${since}..HEAD` : '';
-const raw = execFileSync('git', ['log', '--pretty=%s', ...(range ? [range] : [])], { encoding: 'utf8' });
-const commits = raw.split(/\r?\n/).filter(Boolean);
+const raw = execFileSync('git', ['log', '--pretty=%H%n%s%n%n%b%n__END__', ...(range ? [range] : [])], { encoding: 'utf8' });
+const commits = raw
+  .split('__END__\n')
+  .map(c => c.trim())
+  .filter(Boolean)
+  .map(c => {
+    const [sha, subject, ...rest] = c.split('\n');
+    return { sha: sha.slice(0, 7), subject: subject ?? '', body: rest.join('\n').trim() };
+  });
 
 const groups: Record<string, { label: string; items: string[] }> = {
   feat: { label: 'New', items: [] },
   fix: { label: 'Fixed', items: [] },
-  docs: { label: 'Docs', items: [] },
   refactor: { label: 'Refactored', items: [] },
   perf: { label: 'Performance', items: [] },
+  docs: { label: 'Docs', items: [] },
   chore: { label: 'Housekeeping', items: [] },
   test: { label: 'Housekeeping', items: [] },
   ci: { label: 'Housekeeping', items: [] },
@@ -38,12 +46,33 @@ const groups: Record<string, { label: string; items: string[] }> = {
 
 const order = ['feat', 'fix', 'refactor', 'perf', 'docs', 'chore'];
 
-for (const c of commits) {
-  const m = /^(\w+)(?:\(.*\))?!?: (.*)/.exec(c);
+// strip signature trailers (Co-authored-by, Signed-off-by, review notes)
+const TRAILER = /^(Co-authored-by|Signed-off-by|Reviewed-by|Helped-by|Reported-by|Tested-by|Acked-by):/i;
+
+for (const commit of commits) {
+  const m = /^(\w+)(?:\((.*?)\))?!?: (.*)/.exec(commit.subject);
   const type = m ? m[1] : 'chore';
-  const text = m ? m[2] : c;
+  const scope = m?.[2] || '';
+  const text = m ? m[3] : commit.subject;
+  const breaking = Boolean(m?.[0]?.includes('!')) || /^BREAKING CHANGE:/m.test(commit.body);
+
+  const title = text.charAt(0).toUpperCase() + text.slice(1);
+  const scopeTag = scope ? ` \`${scope}\`` : '';
+  const breakingTag = breaking ? ' ⚠️ **BREAKING**' : '';
+
+  const bodyLines = commit.body
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(l => l && !TRAILER.test(l) && l !== '---')
+    // the release-version marker commit repeats the subject as body — drop it
+    .filter(l => l !== text);
+
+  let entry = `- ${title}${scopeTag}${breakingTag} \`${commit.sha}\``;
+  if (bodyLines.length) {
+    entry += '\n' + bodyLines.map(l => `  - ${l}`).join('\n');
+  }
   const g = groups[type] ?? groups.chore;
-  g.items.push(text.charAt(0).toUpperCase() + text.slice(1));
+  g.items.push(entry);
 }
 
 const lines: string[] = [];
@@ -52,11 +81,11 @@ for (const t of order) {
   if (!g.items.length) continue;
   lines.push(`## ${g.label}`);
   lines.push('');
-  for (const item of g.items) lines.push(`- ${item}`);
+  for (const item of g.items) lines.push(item);
   lines.push('');
 }
 
-const bumpIdx = commits.findIndex(c => /chore: release|chore: bump/.test(c));
+const bumpIdx = commits.findIndex(c => /chore: release|chore: bump/.test(c.subject));
 const body = commits.slice(0, bumpIdx === -1 ? commits.length : bumpIdx);
 const count = body.length || commits.length;
 

package/scripts/savepoint.sh

@@ -8,19 +8,33 @@ 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
+# dot-only names (".", "..", "...") pass the char allowlist but resolve upward
+# through join(...,"..") — reject them before any path is built from MISSION.
+if [[ "$MISSION" =~ ^\.+$ ]]; then
+  die "invalid mission name \"$MISSION\" (allowlist: [a-zA-Z0-9._-], not a dot-path)"
 fi
 
 # per-branch state file when --branch used
@@ -50,61 +64,119 @@ if [ "$BASE_SHA" != "unknown" ]; then
 fi
 [ -z "$LOC_DELTA" ] && LOC_DELTA=0
 
-SENSITIVE_PATTERNS="auth/|payment/|billing/|crypto/|secrets/|\.env|config/|migration/|\.sql$|schema\.|\.prisma$"
+SENSITIVE_PATTERNS="auth/|payment/|billing/|crypto/|secrets/|\.env$|config/.*key|migration/|\.sql$|schema\.|\.prisma$|\.terraform|\.tf$"
 SENSITIVE_PATHS=$(echo "$CHANGED_FILES" | grep -E "$SENSITIVE_PATTERNS" 2>/dev/null | tr '\n' ',' | sed 's/,$//' || true)
 
 LANE="direct"
 LANE_REASON=""
-if [ "$FILES_TOUCHED" -ge 9 ] 2>/dev/null || [ -n "$SENSITIVE_PATHS" ]; then
+# Sensitive-path escalation is unconditional — it wins over any count-based
+# lane AND over the docs-only downgrade below (bug C9).
+if [ -n "$SENSITIVE_PATHS" ]; then
+  LANE="full"
+  LANE_REASON="sensitive paths: $SENSITIVE_PATHS"
+elif [ "$FILES_TOUCHED" -ge 9 ] 2>/dev/null; then
   LANE="full"
-  LANE_REASON="$( [ -n "$SENSITIVE_PATHS" ] && echo "sensitive paths: $SENSITIVE_PATHS" || echo "$FILES_TOUCHED files")"
+  LANE_REASON="$FILES_TOUCHED files"
 elif [ "$FILES_TOUCHED" -ge 3 ] 2>/dev/null; then
   LANE="standard"
   LANE_REASON="$FILES_TOUCHED files"
 elif [ "$FILES_TOUCHED" -ge 2 ] 2>/dev/null; then
   LANE="lean"
   LANE_REASON="$FILES_TOUCHED files"
+elif [ "$FILES_TOUCHED" -eq 1 ] 2>/dev/null; then
+  # 1-file rule mirrors lane.sh: >=20 added LOC -> lean, else direct
+  ADDED=$(git diff --numstat "$BASE_SHA"..HEAD 2>/dev/null | awk '{s+=$1} END {print s+0}')
+  if [ "${ADDED:-0}" -ge 20 ] 2>/dev/null; then
+    LANE="lean"
+    LANE_REASON="1 file, $ADDED LOC"
+  else
+    LANE="direct"
+    LANE_REASON="1 file, <20 LOC"
+  fi
 else
   LANE="direct"
   LANE_REASON="$FILES_TOUCHED file(s) under 20 LOC"
 fi
 
-# task counts from plan doc
-PLAN_FILE=$(ls "$MUGIWARA_DIR/plans/${MISSION}.md" 2>/dev/null || true)
+# 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" ] && [ -z "$SENSITIVE_PATHS" ] && [ -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 is written date-prefixed (plans/YYYY-MM-DD-<mission>.md)
+# or bare (plans/<mission>.md); glob both, first match wins.
+PLAN_FILE=$(ls "$MUGIWARA_DIR"/plans/${MISSION}.md "$MUGIWARA_DIR"/plans/*-${MISSION}.md 2>/dev/null | head -1 || true)
 TASKS_DONE=0
 TASKS_TOTAL=0
 if [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
-  TASKS_TOTAL=$(grep -c '\[ \]' "$PLAN_FILE" 2>/dev/null || echo 0)
-  TASKS_DONE=$(grep -c '\[x\]' "$PLAN_FILE" 2>/dev/null || echo 0)
+  # total counts ALL task lines (checked + unchecked); done counts checked only.
+  # A fully-completed plan must read total=N done=N, never total=0 (the old
+  # unchecked-only grep degenerated a done plan to tasks.total=0).
+  TASKS_TOTAL=$(grep -cE '^\s*-\s*\[[ xX]\]' "$PLAN_FILE" 2>/dev/null || true)
+  TASKS_DONE=$(grep -c '\[x\]' "$PLAN_FILE" 2>/dev/null || true)
 fi
 
 # blocker count
 BLOCKERS_FILE=$(ls "$MUGIWARA_DIR/issues/${MISSION}-blockers.md" 2>/dev/null || true)
 BLOCKERS_OPEN=0
 if [ -n "$BLOCKERS_FILE" ] && [ -f "$BLOCKERS_FILE" ]; then
-  BLOCKERS_OPEN=$(grep -c '|' "$BLOCKERS_FILE" 2>/dev/null || echo 0)
+  # data rows start with a wave number; header "| wave |" and separator
+  # "|---|" are excluded by the ^\| ?[0-9]+ \| pattern
+  BLOCKERS_OPEN=$(grep -cE '^\| ?[0-9]+ ?\|' "$BLOCKERS_FILE" 2>/dev/null || true)
 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 || true)
   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)
-TOKENS_EST=${MUGIWARA_TOKENS:-0}
+# tokens proxy (F7): deterministic estimate when the harness does not report
+# real usage. Monotonic beats precise — LANE_BASE stands in for the skills
+# loaded this lane; loc_delta and written-artifact words scale with growth.
+# MUGIWARA_TOKENS overrides as the reported value.
+LANE_BASE=0
+case "$LANE" in
+  lean) LANE_BASE=1500 ;;
+  standard) LANE_BASE=4000 ;;
+  full) LANE_BASE=9000 ;;
+  spike) LANE_BASE=1000 ;;
+esac
+DOC_WORDS=$(cat "$MUGIWARA_DIR"/results/${MISSION}/*.md "$MUGIWARA_DIR"/plans/${MISSION}.md "$MUGIWARA_DIR"/plans/*-${MISSION}.md "$MUGIWARA_DIR"/spec/${MISSION}.md "$MUGIWARA_DIR"/spec/*-${MISSION}.md "$MUGIWARA_DIR"/logs/${MISSION}.md "$MUGIWARA_DIR"/logs/*-${MISSION}.md 2>/dev/null | wc -w | tr -d ' ')
+LOC_TOKENS=$(( LOC_DELTA > 0 ? LOC_DELTA * 12 : 0 ))
+TOKENS_SOURCE="computed"
+TOKENS_EST=$(( LANE_BASE + DOC_WORDS * 135 / 100 + LOC_TOKENS ))
+if [ -n "${MUGIWARA_TOKENS:-}" ]; then
+  TOKENS_EST="${MUGIWARA_TOKENS}"
+  TOKENS_SOURCE="reported"
+fi
 
 # budget per lane
 BUDGET=0
@@ -126,41 +198,60 @@ 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,
+  tokens_source: process.argv[26] || 'computed',
+  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" "$TOKENS_SOURCE"
+
+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,31 @@ 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' && !body.includes('## Red flags')) errors.push(`skill ${file}: missing required "## Red flags" block`);
+  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 +135,78 @@ 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`);
+}
+
+// --- write-boundary gate (W1): the hub skill must carry the refusal rule ---
+const hubFile = join(root, 'skills', 'mugiwara-orchestration', 'SKILL.md');
+if (existsSync(hubFile) && !readFileSync(hubFile, 'utf8').includes('## Write boundary')) {
+  errors.push('skill mugiwara-orchestration: missing "## Write boundary" section (non-executors refuse source writes)');
+}
+
+// --- agent-count gate (F14): user-facing/internal split derivable from content/agents/ ---
+const internalAgents = agentFiles.filter(f => {
+  const parsed = parseFrontmatter(readFileSync(join(agentDir, f), 'utf8'));
+  return parsed.data.internal === 'true';
+});
+const canonicalCount = `${agentFiles.length - internalAgents.length} agents (+${internalAgents.length} internal)`;
+for (const doc of ['README.md', 'docs/index.md', 'docs/concepts/agents.md']) {
+  const p = join(import.meta.dirname, '..', doc);
+  if (existsSync(p) && !readFileSync(p, 'utf8').includes(canonicalCount)) {
+    errors.push(`${doc}: missing canonical agent count "${canonicalCount}"`);
+  }
+}
+
+// --- 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/cli.ts

@@ -7,15 +7,15 @@ import { fileURLToPath } from 'node:url';
 import { parseArgs, type FlagValue, type Args } from './args.ts';
 import { createRl, choose, multiChoose, confirm } from './prompt.ts';
 import { targets, TARGET_IDS } from './targets/index.ts';
-import { installTo, removeInstalled, VERSION } from './installer.ts';
+import { installTo, removeInstalled, VERSION, ensureProjectGitignore } from './installer.ts';
 import { manifestPath, readManifest, writeManifest, type Scope } from './manifest.ts';
-import { resetMission } from './mission.ts';
+import { resetMission, archiveMission } from './mission.ts';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
 
 export async function run(argv: string[]): Promise<void> {
-  const { command, flags } = parseArgs(argv);
+  const { command, flags, _ } = parseArgs(argv);
   if (flag(flags.help) || command === 'help') return help();
   if (flag(flags.version)) { console.log(`mugiwara ${VERSION}`); return; }
   switch (command) {
@@ -24,6 +24,7 @@ export async function run(argv: string[]): Promise<void> {
     case 'uninstall': return uninstall(flags);
     case 'list': return list(flags);
     case 'reset': return resetCmd(flags);
+    case 'archive': return archive(flags, _);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
@@ -41,6 +42,17 @@ function resetCmd(flags: Args['flags']): void {
   if (result.kept.length) console.log(`kept: ${result.kept.join(', ')}`);
 }
 
+function archive(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const mission = positionals[1];
+  if (!mission) { console.error('usage: mugiwara archive <mission> [--project <dir>] [--dry-run]'); process.exit(1); }
+  const result = archiveMission(projectDir, mission, { dryRun: flag(flags.dryRun) });
+  if (result.report) console.log(`archive target: ${result.report}`);
+  if (result.removed.length) console.log(`${flag(flags.dryRun) ? 'would remove' : 'removed'}: ${result.removed.join(', ')}`);
+  if (result.kept.length) console.log(`kept: ${result.kept.join(', ')}`);
+  if (result.index) console.log(`index updated: ${result.index}`);
+}
+
 async function resolveOptions(flags: Args['flags']): Promise<{ scope: Scope; projectDir: string; targetIds: string[] }> {
   const interactive = !flag(flags.yes);
   if (interactive && !process.stdin.isTTY) {
@@ -95,6 +107,10 @@ async function install(flags: Args['flags']): Promise<void> {
     allFiles.push(...r.written);
     allNotes.push(...r.notes);
   }
+  if (scope === 'project') {
+    const gi = ensureProjectGitignore(projectDir, { dryRun: flag(flags.dryRun) });
+    allNotes.push(...gi.notes);
+  }
   if (flag(flags.dryRun)) { console.log('\nDry run — nothing written.'); return; }
   const file = manifestPath({ scope, projectDir, home });
   const prev = readManifest(file);
@@ -182,6 +198,7 @@ Usage:
   mugiwara list          show installations
   mugiwara list --check  health check: show installations + missing files
   mugiwara reset         wipe mission state (spec/plans/results/review/issues[/logs])
+  mugiwara archive <m>    fold a closed mission's evidence into its report, then remove loose files
   mugiwara --help        this help
   mugiwara --version     print version