@ionivetech/mugiwara 0.8.2 → 0.9.1

package/scripts/savepoint.sh

@@ -63,9 +63,27 @@ if [ -n "$GIT_NAME" ] && [ -n "$GIT_EMAIL" ]; then GIT_ID="$GIT_NAME <$GIT_EMAIL
 
 # --- parse mission args: <mission> [member] [wave] [mode] ---
 MISSION="${1:-${STATE_MISSION:-}}"
+# member: positional > env > config team_member > empty (solo). Never derive
+# silently from git identity — solo vs team is a recorded Flow 0 decision, not
+# an inference. (W3)
 MEMBER="${2:-${STATE_MEMBER:-}}"
+if [ -z "$MEMBER" ] && [ -f "$MUGIWARA_DIR/config" ]; then
+  MEMBER=$(grep -E '^team_member=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
+fi
 WAVE="${3:-${STATE_WAVE:-1}}"
-MODE="${4:-${STATE_MODE:-guided}}"
+# mode: positional > env > project config > global config > guided. The hook
+# passes it positionally; direct script and CLI calls must fall back to config
+# or 11 of 12 harnesses record the wrong mode. (W1)
+MODE="${4:-${STATE_MODE:-}}"
+if [ -z "$MODE" ]; then
+  for _cfg in "$MUGIWARA_DIR/config" "$HOME/.mugiwara/config"; do
+    [ -f "$_cfg" ] || continue
+    _m=$(grep -E '^mode=' "$_cfg" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
+    [ -n "$_m" ] && { MODE="$_m"; break; }
+  done
+fi
+MODE="${MODE:-guided}"
+case "$MODE" in guided|semi|auto) ;; *) MODE="guided" ;; esac
 # Triage lane (M7): the lane Luffy assigned at Flow 0. Without it savepoint
 # recomputed the lane from file counts alone and silently discarded the
 # triage decision — a Lane 3 mission recorded itself as "direct". Explicit
@@ -91,7 +109,7 @@ esac
 # verbosity from config (project .mugiwara/config), default normal; env override
 VERBOSITY="${STATE_VERBOSITY:-normal}"
 if [ -f "$MUGIWARA_DIR/config" ]; then
-  CFG_VERBOSITY=$(grep -E '^verbosity=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  CFG_VERBOSITY=$(grep -E '^verbosity=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
   [ -n "$CFG_VERBOSITY" ] && VERBOSITY="$CFG_VERBOSITY"
 fi
 case "$VERBOSITY" in
@@ -102,7 +120,7 @@ esac
 # heal_max_cycles from config (project .mugiwara/config), default 3; env override
 HEAL_MAX_CYCLES="${STATE_HEAL_MAX_CYCLES:-3}"
 if [ -f "$MUGIWARA_DIR/config" ]; then
-  CFG_HEAL_MAX=$(grep -E '^heal_max_cycles=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  CFG_HEAL_MAX=$(grep -E '^heal_max_cycles=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
   [ -n "$CFG_HEAL_MAX" ] && HEAL_MAX_CYCLES="$CFG_HEAL_MAX"
 fi
 case "$HEAL_MAX_CYCLES" in
@@ -113,7 +131,7 @@ esac
 # delegate_threshold from config (project .mugiwara/config), default 60; env override
 DELEGATE_THRESHOLD="${STATE_DELEGATE_THRESHOLD:-60}"
 if [ -f "$MUGIWARA_DIR/config" ]; then
-  CFG_DELEGATE=$(grep -E '^delegate_threshold=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  CFG_DELEGATE=$(grep -E '^delegate_threshold=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
   [ -n "$CFG_DELEGATE" ] && DELEGATE_THRESHOLD="$CFG_DELEGATE"
 fi
 case "$DELEGATE_THRESHOLD" in
@@ -183,6 +201,17 @@ else
   CONTINUE_FILE="$MISSION_DIR/continue.json"
 fi
 
+# A mission is solo or team, never both. Two layouts side by side orphan one of
+# them: hidden from `status`, still read by the integrity gate. (W4)
+if [ -n "$MEMBER" ] && [ -f "$MISSION_DIR/state.json" ] && [ "${MUGIWARA_ALLOW_LAYOUT_SWITCH:-0}" != "1" ]; then
+  die "mission '$MISSION' is solo (state.json exists) — refusing to add member '$MEMBER'. Run: mugiwara migrate --to-team $MEMBER"
+fi
+if [ -z "$MEMBER" ] && ls "$MISSION_DIR"/*.json >/dev/null 2>&1; then
+  if ls "$MISSION_DIR"/*.json | grep -qv -e 'state.json' -e 'continue'; then
+    die "mission '$MISSION' is team — pass a member: savepoint.sh $MISSION <member> ..."
+  fi
+fi
+
 [ -z "$MISSION" ] && die "usage: savepoint.sh <mission> [member] [wave] [mode] [lane]"
 
 # --- computed fields ---
@@ -192,7 +221,7 @@ HEAD_SHA=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
 # lane_scope_glob (T5): monorepo scoping — count only files matching the glob
 LANE_SCOPE_GLOB=""
 if [ -f "$MUGIWARA_DIR/config" ]; then
-  _cfg_scope=$(grep -E '^lane_scope_glob=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"' | tr -d "'")
+  _cfg_scope=$(grep -E '^lane_scope_glob=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"' | tr -d "'")
   [ -n "$_cfg_scope" ] && LANE_SCOPE_GLOB="$_cfg_scope"
 fi
 # union of committed + staged + unstaged + untracked (F) — see patterns.sh
@@ -336,11 +365,19 @@ if [ -n "$LANE_PREV" ] && [ "$LANE_PREV" != "$LANE" ]; then
   esac
 fi
 
-# task counts from plan doc — bare name, one file per mission.
+# task counts — the execution mirror wins over the plan doc.
+# Zoro tracks one box per task in flows/todos.md as work lands, while plan.md
+# may carry no boxes at all (Steps: inline) or a different-granularity
+# acceptance list. Counting plan-only left finished missions reading 0/N.
+# Mirror wins when it has boxes; plan.md otherwise; sub-plan/ as before.
 PLAN_FILE="$MISSION_DIR/plan.md"
+TODOS_FILE="$MISSION_DIR/flows/todos.md"
 TASKS_DONE=0
 TASKS_TOTAL=0
-if [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
+if [ -f "$TODOS_FILE" ] && [ "$(count_boxes "$TODOS_FILE" '[ xX]')" -gt 0 ] 2>/dev/null; then
+  TASKS_TOTAL=$(count_boxes "$TODOS_FILE" '[ xX]')
+  TASKS_DONE=$(count_boxes "$TODOS_FILE" '[xX]')
+elif [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
   # 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).
@@ -395,6 +432,16 @@ if [ "$HEAL_CYCLE" -ge "$HEAL_MAX_CYCLES" ] 2>/dev/null; then
   HEAL_HALT=true
 fi
 
+# W10: register plan.md read so repeated_reads is not structurally zero (evidence.registerRead)
+if [ -f "$MISSION_DIR/plan.md" ] && [ ! -s "$MISSION_DIR/context-registry.jsonl" ]; then
+  mkdir -p "$MISSION_DIR"
+  _plan_fp=$(node -e "const crypto=require('crypto');const fs=require('fs');try{const d=fs.readFileSync(process.argv[1],'utf8');process.stdout.write(crypto.createHash('sha256').update(d).digest('hex'))}catch(e){process.stdout.write('')}" "$MISSION_DIR/plan.md" 2>/dev/null || true)
+  if [ -n "$_plan_fp" ]; then
+    _plan_chars=$(wc -c < "$MISSION_DIR/plan.md" 2>/dev/null | tr -d ' ' || echo 0)
+    printf '{"fingerprint":"%s","kind":"file","file":"plan.md","id":"E001","reads":1,"chars":%s,"ref":"E001 plan.md"}\n' "$_plan_fp" "$_plan_chars" >> "$MISSION_DIR/context-registry.jsonl" 2>/dev/null || true
+  fi
+fi
+
 # slop — context (repeated reads) per cost-governor §§21-24,31-32 — T5 wire all crews Luffy/Nami/Zoro/Brook
 REPEATED_READS=0
 REPEATED_THRESHOLD=3
@@ -410,15 +457,19 @@ fi
 # gates flow stage can read, not prose.
 DEPTH_REVIEW="full"; DEPTH_QUALITY="full"; DEPTH_VERIFY="off"
 if [ -f "$MUGIWARA_DIR/config" ]; then
-  _cfg_r=$(grep -E '^review_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  _cfg_r=$(grep -E '^review_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
   [ -n "$_cfg_r" ] && DEPTH_REVIEW="$_cfg_r"
-  _cfg_q=$(grep -E '^quality_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  _cfg_q=$(grep -E '^quality_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
   [ -n "$_cfg_q" ] && DEPTH_QUALITY="$_cfg_q"
-  _cfg_v=$(grep -E '^verify_merged=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  _cfg_v=$(grep -E '^verify_merged=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
   [ -n "$_cfg_v" ] && DEPTH_VERIFY="$_cfg_v"
 fi
-case "$DEPTH_REVIEW" in full|standard|lean) ;; *) DEPTH_REVIEW="full" ;; esac
-case "$DEPTH_QUALITY" in full|standard|lean) ;; *) DEPTH_QUALITY="full" ;; esac
+# `quick` is the documented third level; `lean` was an undocumented synonym.
+# Accept both, normalise to the documented name. (N3)
+[ "$DEPTH_REVIEW" = "lean" ] && DEPTH_REVIEW="quick"
+[ "$DEPTH_QUALITY" = "lean" ] && DEPTH_QUALITY="quick"
+case "$DEPTH_REVIEW" in full|standard|quick) ;; *) DEPTH_REVIEW="full" ;; esac
+case "$DEPTH_QUALITY" in full|standard|quick) ;; *) DEPTH_QUALITY="full" ;; esac
 case "$DEPTH_VERIFY" in on|off) ;; *) DEPTH_VERIFY="off" ;; esac
 
 # evidence paths — the mission's flow folder (quoted printf, no sed — mission
@@ -522,6 +573,75 @@ if [ "$BUDGET" -gt 0 ] 2>/dev/null; then
   fi
 fi
 
+# team_members for posture (W5) — config key team_members, default 1
+TEAM_MEMBERS=1
+if [ -f "$MUGIWARA_DIR/config" ]; then
+  _tm=$(grep -E '^team_members=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
+  [ -n "$_tm" ] && TEAM_MEMBERS="$_tm"
+fi
+case "$TEAM_MEMBERS" in ''|*[!0-9]*) TEAM_MEMBERS=1 ;; esac
+# plan metrics for posture decision (phase-isolated / parallel)
+PLAN_LINES=0
+PHASES=1
+INDEPENDENT_TASKS=0
+if [ -f "$MISSION_DIR/plan.md" ]; then
+  PLAN_LINES=$(wc -l < "$MISSION_DIR/plan.md" 2>/dev/null | tr -d ' ' || echo 0)
+  PH=$(grep -c "^## Wave" "$MISSION_DIR/plan.md" 2>/dev/null || true)
+  [ "$PH" -gt 0 ] 2>/dev/null && PHASES="$PH"
+  INDEPENDENT_TASKS=$(grep -c "\[PARALLEL\]" "$MISSION_DIR/plan.md" 2>/dev/null || true)
+fi
+# governor for posture
+GOVERNOR="normal"
+case "$STATUS" in
+  stop) GOVERNOR="stop" ;;
+  warn) GOVERNOR="avoid" ;;
+  *) GOVERNOR="normal" ;;
+esac
+CONTEXT_PRESSURE=false
+if [ "$BUDGET" -gt 0 ] 2>/dev/null && [ "$TOKENS_EST" -gt $(( BUDGET * 6 / 10 )) ] 2>/dev/null; then
+  CONTEXT_PRESSURE=true
+fi
+POSTURE="inline-sequential"
+POSTURE_REASON="no parallel/phase/team/relief trigger — default inline in plan order"
+POSTURE_PAUSE=false
+if [ "$GOVERNOR" = "stop" ]; then
+  POSTURE="inline-sequential"
+  POSTURE_REASON="governor stop — pause safely, keep inline; state + continue emitted"
+  POSTURE_PAUSE=true
+elif [ "$TEAM_MEMBERS" -gt 1 ] 2>/dev/null; then
+  POSTURE="team-scoped"
+  POSTURE_REASON="$TEAM_MEMBERS team members with non-overlapping scope"
+elif [ "$PHASES" -gt 3 ] 2>/dev/null || [ "$PLAN_LINES" -gt 1500 ] 2>/dev/null; then
+  POSTURE="phase-isolated"
+  POSTURE_REASON="large campaign — $PHASES phases / $PLAN_LINES lines"
+elif [ "$CONTEXT_PRESSURE" = true ]; then
+  POSTURE="context-relief"
+  POSTURE_REASON="context pressure with ordered dependent tasks — one worker at a time, order preserved"
+elif [ "$INDEPENDENT_TASKS" -ge 2 ] 2>/dev/null; then
+  POSTURE="parallel-workers"
+  POSTURE_REASON="$INDEPENDENT_TASKS independent tasks, no shared files/interfaces"
+fi
+# investigation config (W8) — three keys, defaults 2/5/2
+INV_MAX_PASSES=2
+INV_MAX_UNRELATED=5
+INV_REPEATED_THRESH=2
+if [ -f "$MUGIWARA_DIR/config" ]; then
+  _v=$(grep -E '^investigation_max_passes=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
+  [ -n "$_v" ] && INV_MAX_PASSES="$_v"
+  _v=$(grep -E '^investigation_max_unrelated_files=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
+  [ -n "$_v" ] && INV_MAX_UNRELATED="$_v"
+  _v=$(grep -E '^investigation_repeated_read_threshold=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | cut -d'#' -f1 | tr -d '[:space:]')
+  [ -n "$_v" ] && INV_REPEATED_THRESH="$_v"
+fi
+case "$INV_MAX_PASSES" in ''|*[!0-9]*) INV_MAX_PASSES=2 ;; esac
+case "$INV_MAX_UNRELATED" in ''|*[!0-9]*) INV_MAX_UNRELATED=5 ;; esac
+case "$INV_REPEATED_THRESH" in ''|*[!0-9]*) INV_REPEATED_THRESH=2 ;; esac
+# investigation_status: simple threshold check on repeated_reads (W8/W10)
+INVESTIGATION_STATUS="continue"
+if [ "$REPEATED_READS" -ge "$INV_REPEATED_THRESH" ] 2>/dev/null; then
+  INVESTIGATION_STATUS="stop"
+fi
+
 mkdir -p "$MISSION_DIR"
 
 node -e "
@@ -565,7 +685,12 @@ const data = {
   evidence: process.argv[21] ? process.argv[21].split(',').filter(Boolean) : [],
   updated_at: process.argv[22],
   schema_version: 2,
-  repeated_reads: parseInt(process.argv[41], 10) || 0
+  repeated_reads: parseInt(process.argv[41], 10) || 0,
+  team_members: parseInt(process.argv[42], 10) || 1,
+  posture: process.argv[43] || 'inline-sequential',
+  posture_reason: process.argv[44] || '',
+  posture_pause: process.argv[45] === 'true',
+  investigation_status: process.argv[46] || 'continue'
 };
 require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\n');
 " \
@@ -579,7 +704,7 @@ require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\
   "$LOC_INS" "$LOC_DEL" "$LOC_CHURN" "$MEMBER" "$VERBOSITY" \
   "$HEAL_MAX_CYCLES" "$HEAL_HALT" "$DELEGATE_THRESHOLD" "$DELEGATE_DUE" \
   "$MODEL" "$DEPTH_REVIEW" "$DEPTH_QUALITY" "$DEPTH_VERIFY" \
-  "$REPEATED_READS"
+  "$REPEATED_READS" "$TEAM_MEMBERS" "$POSTURE" "$POSTURE_REASON" "$POSTURE_PAUSE" "$INVESTIGATION_STATUS"
 
 if [ "$LANE_ROSE" = true ]; then
   echo "⚠ LANE ROSE: $LANE_PREV → $LANE ($LANE_REASON) — escalate per check-in protocol"

package/scripts/validate-content.ts

@@ -187,10 +187,18 @@ for (const doc of ['README.md', 'docs/index.md', 'docs/concepts/agents.md']) {
 // --- 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');
+  // Entry protocol: EVERY agent, Luffy included. Exempting him is what let a
+  // captain with no pre-flight checklist ship. (E2)
   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`);
+  // Return-to-Luffy: every agent EXCEPT Luffy — he cannot return to himself.
+  if (name !== 'luffy-orchestrator' && !text.includes('## Return to Luffy')) {
+    errors.push(`agent ${f}: missing "## Return to Luffy" hub rule`);
+  }
+  // Luffy carries the routing counterpart instead.
+  if (name === 'luffy-orchestrator' && !text.includes('Brainstorm is Usopp')) {
+    errors.push('agent luffy-orchestrator: missing the "never do another crew member\'s work" routing rule');
+  }
 }
 
 // --- hub-skill gate (F3): every agent lists mugiwara-orchestration (the hub rule's home) ---
@@ -414,7 +422,270 @@ if (integrityArg !== -1) {
     }
   if (!constants.includes('LANE_BASE_lean=8421')) errors.push('doc-integrity: source lane-base.sh lean base drifted (expected 8421)');
   if (!constants.includes('BUDGET_full=50000')) errors.push('doc-integrity: source lane-base.sh full budget drifted (expected 50000)');
+  // W12 stale path check: obsolete layout must not appear
+  const staleChecks: [string, string[]][] = [
+    ['state/<mission>', ['docs/concepts/comparison.md', 'docs/concepts/features.md', 'references/multi-actor.md', 'README.md']],
+    ['continue/<mission>', ['docs/concepts/comparison.md', 'docs/concepts/features.md', 'references/multi-actor.md', 'README.md']],
+    ['plans/<mission>', ['docs/concepts/comparison.md', 'docs/concepts/features.md', 'references/multi-actor.md', 'README.md']],
+    ['logs/lessons', ['docs/concepts/comparison.md', 'docs/concepts/features.md', 'references/multi-actor.md', 'README.md']],
+  ];
+  for (const [pat, docs] of staleChecks) {
+    for (const doc of docs) {
+      const p = join(import.meta.dirname, '..', doc);
+      if (existsSync(p) && readFileSync(p, 'utf8').includes(pat)) {
+        errors.push(`doc-integrity: ${doc} contains obsolete path "${pat}" — use missions/<mission>/ layout`);
+      }
+    }
+  }
+  // W17 metrics must come from .metrics/latest.json — check for hardcoded stale numbers not in metrics
+  const metricsPath2 = join(import.meta.dirname, '..', '.metrics/latest.json');
+  if (existsSync(metricsPath2)) {
+    const m2 = JSON.parse(readFileSync(metricsPath2, 'utf8'));
+    const readme2 = readFileSync(join(import.meta.dirname, '..', 'README.md'), 'utf8');
+    // ensure README rank-1 and pointers match metrics (also checked in --check-readme-metrics, but this is integrity)
+    const rankMatch2 = readme2.match(/Retrieval routing rank-1[^\n]*?(\d+\.\d+)%/);
+    if (rankMatch2 && parseFloat(rankMatch2[1]) !== Number(m2.retrieval_rank1)) {
+      errors.push(`doc-integrity: README rank-1 ${rankMatch2[1]}% != metrics ${m2.retrieval_rank1}%`);
+    }
+  }
+  // N4: a skill that instructs `mugiwara <cmd>` when the CLI has no such case is an
+  // instruction the agent cannot follow. This is how `initiative` shipped as a
+  // dangling reference. Cases are read from the CLI source, not hardcoded.
+  const cliSrc = readFileSync(join(import.meta.dirname, '..', 'src', 'cli.ts'), 'utf8');
+  // In-session phrases, not CLI verbs — see mugiwara-workflow.
+  const IN_SESSION = new Set(['mode', 'off']);
+  const referenced = new Set<string>();
+  const walkMarkdown = (dir: string): string[] =>
+    listFiles(dir).filter((f) => f.endsWith('.md')).map((f) => join(dir, f));
+  for (const dir of ['content', 'docs', 'references']) {
+    for (const file of walkMarkdown(join(import.meta.dirname, '..', dir))) {
+      const text = readFileSync(file, 'utf8');
+      for (const m of text.matchAll(/`mugiwara ([a-z-]+)/g)) referenced.add(m[1]);
+    }
+  }
+  // Also scan repo-root markdown (README, AGENTS) — same defect class.
+  for (const file of ['README.md', 'AGENTS.md']) {
+    const p = join(import.meta.dirname, '..', file);
+    if (!existsSync(p)) continue;
+    for (const m of readFileSync(p, 'utf8').matchAll(/`mugiwara ([a-z-]+)/g)) referenced.add(m[1]);
+  }
+  for (const cmd of referenced) {
+    if (IN_SESSION.has(cmd)) continue;
+    if (cmd.startsWith('--')) continue;
+    if (!cliSrc.includes(`case '${cmd}'`)) {
+      errors.push(`doc-integrity: docs instruct "mugiwara ${cmd}" but src/cli.ts has no case '${cmd}'`);
+    }
+  }
+  // N2 banner-format: no raw ANSI escapes in model-facing instructions. The
+  // colour table in wave-banners.md is data for the plugin, not an
+  // instruction — it holds hex, never escapes, so no exemption is needed.
+  // N8 in-session phrases must never read as slash commands.
+  const proseFiles: string[] = [];
+  for (const dir of ['content', 'docs', 'references']) {
+    proseFiles.push(...walkMarkdown(join(import.meta.dirname, '..', dir)));
+  }
+  for (const file of ['README.md', 'AGENTS.md']) {
+    const p = join(import.meta.dirname, '..', file);
+    if (existsSync(p)) proseFiles.push(p);
+  }
+  for (const file of proseFiles) {
+    const text = readFileSync(file, 'utf8');
+    if (/\\x1b\[|38;2;|38;5;/.test(text)) {
+      errors.push(`doc-integrity: ${file} instructs raw ANSI escapes the model cannot emit — banners are plain headings`);
+    }
+    // `/mugiwara continue` is a real CLI verb and out of scope — only the mode
+    // switch is an in-session phrase, so only its slash forms are flagged.
+    if (/`\/(mugiwara mode|mugiwara (guided|semi|auto))/.test(text)) {
+      errors.push(`doc-integrity: ${file} writes the in-session mode phrase as a slash command — say "mugiwara mode <level>" in session, no slash, no CLI flag`);
+    }
+  }
+  // N5: the flow-summary contract must exist — it is what keeps normal
+  // verbosity to one line per stage.
+  const orchSkill = readFileSync(join(import.meta.dirname, '..', 'content', 'skills', 'mugiwara-orchestration', 'SKILL.md'), 'utf8');
+  if (!orchSkill.includes('## Flow summary line')) {
+    errors.push('doc-integrity: mugiwara-orchestration SKILL.md lost its "## Flow summary line" contract');
+  }
+  // N9: the platform count must stay qualified — 9 installable + 3 marketplace.
+  const readme = readFileSync(join(import.meta.dirname, '..', 'README.md'), 'utf8');
+  if (readme.includes('12 platforms') && !readme.includes('via marketplace manifest')) {
+    errors.push('doc-integrity: README "12 platforms" is unqualified — split 9 via install + 3 via marketplace manifest');
+  }
+}
+}
+
+// --- config drift gate (W11): every key code reads must appear in DEFAULT_CONFIG and docs, and vice versa ---
+if (process.argv.includes('--check-config')) {
+  const cfgSrc = readFileSync(join(import.meta.dirname, '..', 'src/config.ts'), 'utf8');
+  const m = cfgSrc.match(/DEFAULT_CONFIG\s*=\s*\[([\s\S]*?)\]\.join/);
+  let defaultKeys: string[] = [];
+  if (m) {
+    const block = m[1];
+    for (const line of block.split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t) continue;
+      // extract string content between quotes
+      const q = t.match(/['"`]([^'"`]*?)['"`]/);
+      if (!q) continue;
+      let s = q[1].trim();
+      if (!s) continue;
+      if (s.startsWith('#')) s = s.slice(1).trim();
+      if (!s) continue;
+      const eq = s.indexOf('=');
+      if (eq === -1) continue;
+      const key = s.slice(0, eq).trim();
+      if (key) defaultKeys.push(key);
+    }
+  }
+  // docs keys from config.md table (only the ## Keys section, not template examples)
+  const docPath = join(import.meta.dirname, '..', 'docs/concepts/config.md');
+  let docKeys: string[] = [];
+  if (existsSync(docPath)) {
+    const docText = readFileSync(docPath, 'utf8');
+    const keysSectionMatch = docText.match(/## Keys([\s\S]*?)(?:\n## |\n#|$)/);
+    const keysSection = keysSectionMatch ? keysSectionMatch[1] : docText;
+    for (const line of keysSection.split(/\r?\n/)) {
+      const cm = line.match(/\|\s*`([^`]+)`\s*\|/);
+      if (cm) {
+        const k = cm[1].trim();
+        if (k && !docKeys.includes(k)) docKeys.push(k);
+      }
+    }
+  } else {
+    errors.push('config-drift: docs/concepts/config.md not found');
+  }
+  // code keys: scan src/*.ts, scripts/*.sh, hooks/*.ts for key patterns
+  const codeRoots = [
+    join(import.meta.dirname, '..', 'src'),
+    join(import.meta.dirname, '..', 'scripts'),
+    join(import.meta.dirname, '..', 'hooks'),
+  ];
+  const codeTextAll = codeRoots.map(r => {
+    if (!existsSync(r)) return '';
+    const files = readdirSync(r, { withFileTypes: true }).filter(e => e.isFile() && (e.name.endsWith('.ts') || e.name.endsWith('.sh'))).map(e => readFileSync(join(r, e.name), 'utf8')).join('\n');
+    // also need subdirectories
+    let sub = '';
+    try {
+      for (const e of readdirSync(r, { withFileTypes: true })) {
+        if (e.isDirectory()) {
+          const subdir = join(r, e.name);
+          for (const f of readdirSync(subdir, { withFileTypes: true }).filter(x => x.isFile() && (x.name.endsWith('.ts') || x.name.endsWith('.sh')))) {
+            sub += readFileSync(join(subdir, f.name), 'utf8') + '\n';
+          }
+        }
+      }
+    } catch {}
+    return files + sub;
+  }).join('\n');
+  // check each default key appears in code
+  for (const k of defaultKeys) {
+    if (!codeTextAll.includes(k)) {
+      errors.push(`config-drift: DEFAULT_CONFIG key "${k}" not found in code (src/*.ts, scripts/*.sh, hooks/*.ts)`);
+    }
+    if (!docKeys.includes(k)) {
+      errors.push(`config-drift: DEFAULT_CONFIG key "${k}" missing from docs/concepts/config.md`);
+    }
+  }
+  for (const k of docKeys) {
+    if (!defaultKeys.includes(k)) {
+      errors.push(`config-drift: docs/concepts/config.md key "${k}" not in DEFAULT_CONFIG`);
+    }
+    if (!codeTextAll.includes(k)) {
+      errors.push(`config-drift: docs key "${k}" not found in code`);
+    }
+  }
+  // N6: key parity is not value parity. A documented enum value the code rejects
+  // falls back silently — the user gets the default and no error. Compare both
+  // directions. (auto_commit is advisory-only by design — no code allowlist
+  // exists, so there is nothing to compare.)
+  const configMd = existsSync(docPath) ? readFileSync(docPath, 'utf8') : '';
+  const savepointSh = readFileSync(join(import.meta.dirname, '..', 'scripts', 'savepoint.sh'), 'utf8');
+  const parseDocumentedValues = (key: string): string[] => {
+    const m = configMd.match(new RegExp(`^\\|\\s*\`${key}\`\\s*\\|\\s*([^|]+)\\|`, 'm'));
+    if (!m) return [];
+    return m[1].split('/').map((v) => v.trim()).filter(Boolean);
+  };
+  const parseShellAllowlist = (varName: string): string[] => {
+    const m = savepointSh.match(new RegExp(`case "\\$${varName}" in\\s*([^)]+)\\)`));
+    if (!m) return [];
+    return m[1].split(/[|\s]+/).map((v) => v.trim()).filter(Boolean);
+  };
+  const parseTsUnion = (file: string, typeName: string, extra: string[] = [], exclude: RegExp | null = null): string[] => {
+    const p = join(import.meta.dirname, '..', file);
+    if (!existsSync(p)) return [];
+    const src = readFileSync(p, 'utf8');
+    const m = src.match(new RegExp(`type ${typeName} = ([^;]+);`));
+    if (!m) return [];
+    const vals = [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]);
+    return [...new Set([...vals, ...extra])].filter((v) => !(exclude && exclude.test(v)));
+  };
+  const ENUM_CHECKS: Array<{ key: string; accepted: string[] }> = [
+    { key: 'mode', accepted: parseShellAllowlist('MODE') },
+    { key: 'verbosity', accepted: parseShellAllowlist('VERBOSITY') },
+    { key: 'review_depth', accepted: parseShellAllowlist('DEPTH_REVIEW') },
+    { key: 'quality_depth', accepted: parseShellAllowlist('DEPTH_QUALITY') },
+    { key: 'verify_merged', accepted: parseShellAllowlist('DEPTH_VERIFY') },
+    // sign allowlist lives in TypeScript: read the exported union, not grep.
+    // 'minisign-fail' is internal (never a valid config value); 'auto' is an
+    // explicit resolveBackend case, so it counts as accepted.
+    { key: 'sign', accepted: parseTsUnion('src/sign.ts', 'BackendChoice', ['auto'], /-fail$/) },
+    { key: 'enforce', accepted: parseTsUnion('hooks/pipeline-guard.ts', 'Enforce') },
+  ];
+  for (const { key, accepted } of ENUM_CHECKS) {
+    const documented = parseDocumentedValues(key);
+    if (!documented.length || !accepted.length) continue;
+    const missing = documented.filter((v) => !accepted.includes(v));
+    const undocumented = accepted.filter((v) => !documented.includes(v));
+    if (missing.length) errors.push(`config ${key}: documented but rejected by code: ${missing.join(', ')}`);
+    if (undocumented.length) errors.push(`config ${key}: accepted by code but undocumented: ${undocumented.join(', ')}`);
+  }
+  if (!errors.some(e => e.startsWith('config-drift') || e.startsWith('config '))) {
+    console.log(`✓ config in sync: ${defaultKeys.length} keys (${defaultKeys.join(', ')})`);
+  }
 }
+
+// --- wiring gate (W7): every src module must be imported somewhere ---
+if (process.argv.includes('--check-wiring')) {
+  const srcDir = join(import.meta.dirname, '..', 'src');
+  const ENTRY = new Set(['cli.ts', 'index.ts', 'installer.ts']);
+  const srcFiles = readdirSync(srcDir).filter(n => n.endsWith('.ts'));
+  const searchDirs = [srcDir, join(import.meta.dirname, '..', 'hooks'), join(import.meta.dirname, '..', 'scripts')];
+  const allFiles: string[] = [];
+  for (const d of searchDirs) {
+    if (!existsSync(d)) continue;
+    const walk = (dir: string) => {
+      for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else if (e.isFile() && (e.name.endsWith('.ts') || e.name.endsWith('.js') || e.name.endsWith('.sh') || e.name.endsWith('.mjs'))) {
+          allFiles.push(full);
+        }
+      }
+    };
+    walk(d);
+  }
+  for (const f of srcFiles) {
+    if (ENTRY.has(f)) continue;
+    const stem = f.slice(0, -3);
+    let found = false;
+    for (const full of allFiles) {
+      if (full.endsWith(`/src/${f}`) || full === join(srcDir, f)) continue;
+      try {
+        const txt = readFileSync(full, 'utf8');
+        // hooks import shared code as '../src/<stem>' (bundled by build-hooks)
+        // — that is a first-class wire, not a dangling module.
+        if (txt.includes(`'./${stem}`) || txt.includes(`"./${stem}`) || txt.includes(`'./${stem}.ts'`) || txt.includes(`"./${stem}.ts"`) || txt.includes(`'../src/${stem}.ts'`) || txt.includes(`"../src/${stem}.ts"`)) {
+          found = true;
+          break;
+        }
+      } catch {}
+    }
+    if (!found) {
+      errors.push(`src/${f}: imported by nothing — wire it, or delete it with its tests and its features.md claim`);
+    }
+  }
+  if (!errors.some(e => e.includes('imported by nothing'))) {
+    console.log(`✓ wiring: all src modules imported`);
+  }
 }
 
 // --- README metrics gate (D3): README table must match .metrics/latest.json ---
@@ -477,6 +748,78 @@ if (process.argv.includes('--check-readme-metrics')) {
   }
 }
 
+// --- invariant-mechanism gate (E-gaps 5.2): every never/always/MUST has a mechanism ---
+// A rule with no machine behind it and no prose-only entry is a gap, not a
+// rule. Concepts live in docs/concepts/enforcement.md; each concept below
+// must have its anchor there, and every never/always/MUST line in content/
+// must match at least one concept. Adding a rule = table row + concept here
+// + mutation in gate-selftest.ts.
+if (process.argv.includes('--check-invariants')) {
+  const enfPath = join(import.meta.dirname, '..', 'docs', 'concepts', 'enforcement.md');
+  const enf = existsSync(enfPath) ? readFileSync(enfPath, 'utf8') : '';
+  if (!enf) errors.push('invariant gate: docs/concepts/enforcement.md is missing');
+  const CONCEPTS: Array<{ id: string; re: RegExp; anchor: string }> = [
+    { id: 'INV-triage', re: /triage|savepoint|flow 0/i, anchor: 'hooks/pipeline-guard.js' },
+    { id: 'INV-write-scope', re: /write-scope|delegat.*zoro|another crew member|crew member's (work|job)|dispatch another crew|one role at a time|embodies one|never.*mutat|mode: all|subagent|never forward|never dispatch|never.*route|never execute source/i, anchor: 'INV-write-scope' },
+    { id: 'INV-luffy-hub', re: /return to luffy|luffy routes?|routes? .*luffy|orchestrator|route reasons|check-in|decision log|next_action|flow stage|omitted|in-flight|exits 2/i, anchor: 'INV-hub' },
+    { id: 'INV-plan-nami', re: /only nami|nami's|without a GO|executor without/i, anchor: 'INV-plan-nami' },
+    { id: 'INV-banner', re: /banner/i, anchor: 'INV-banner' },
+    { id: 'INV-no-deploy', re: /deploys?|merging?|creates a PR|gh pr|push.*branch|terminal step|reaches a user|ship.*user/i, anchor: 'hooks/pretool-guard.js' },
+    { id: 'INV-heal-cap', re: /heal|4-phase|reproduce.*localize/i, anchor: 'INV-heal-cap' },
+    { id: 'INV-lane', re: /\blane\b|mission split|sub-mission|parallel.*safe|never.*parallel|\[PARALLEL\]|shortcut|full pipeline/i, anchor: 'INV-lane' },
+    { id: 'INV-evidence', re: /evidence|re-run|re run|claim|never validate|doubt|fresh (context|agent)|adversarial|no pass/i, anchor: 'INV-evidence' },
+    { id: 'INV-mode', re: /auto.?commit|auto mode|guided|semi|mode.*flip|steps cap|verbosity|auto never|never.*auto|never ask/i, anchor: 'INV-mode' },
+    { id: 'INV-quality', re: /weaken|threshold|coverage|lint|fake pass|silent.*pass|duplicat|complexity|dead code|strict|sonar|maintainability|assert green|failing suite|default-on|trigger|may raise|fixed numbers|invent tooling/i, anchor: 'INV-quality' },
+    { id: 'INV-tests', re: /\btdd\b|failing first|immutable|oracle|user.?test|flaky|intermittent|never.*test\b|gherkin|feature file|banned|translate-or-command|long unreachable|can never prove|never saw|small steps|never create inte|integration tests/i, anchor: 'INV-tests' },
+    { id: 'INV-resume', re: /restart|resume|continue\.json|continue from|never restarts?|never scan|state proves/i, anchor: 'INV-resume' },
+    { id: 'INV-english', re: /always english|one language only|conversational language/i, anchor: 'INV-english' },
+    { id: 'INV-plan-discipline', re: /zero-question|unverified path|\btbd\b|plan above or below|40-file|task index|stranger must|plan.*hole|regression|correctness.*break|never.*plan|never appended|2000\+ lines/i, anchor: 'INV-plan-discipline' },
+    { id: 'INV-security-contract', re: /secret|sanitiz|authz|\.safeParse|trust|inject|data, never|finding, not|dangerouslySetInnerHTML|owasp|stride|exploit|permission|pii|never trust|minor by default|severity|gets the matrix|expiry|revoke/i, anchor: 'INV-security-contract' },
+    { id: 'INV-git-hygiene', re: /commit|git add|revert|broken tree|staging|micro-commit|never.*tree|force-add|gitignore/i, anchor: 'INV-git-hygiene' },
+    { id: 'INV-conduct', re: /ego|yes-man|interrogat|trade-off|assume silently|batched question|sparring|recommendation|reconsider|pushes back|silently defer|verdict only/i, anchor: 'INV-conduct' },
+    { id: 'INV-mirror', re: /todo.*mirror|same response|transcript.*sufficient|task N\/M|echoing raw|compact.*table|report table|evidence link|never changes|always visible|audit surface|audit trail|never narrows|one-liner|mid-argument|overwrite|detailed summary|lags|never seeded|list never|must always see|never depends/i, anchor: 'INV-mirror' },
+    { id: 'INV-trust', re: /redefine.*rule|artifact trust|untrusted|HIGH trust|LOW-trust|instruction.*data|verbatim instructions|lesson/i, anchor: 'INV-trust' },
+    { id: 'INV-role', re: /never implements|never fixes|outside your role|luffy's, always|who never|never does what|11th member|finding yourself|coordinator|auditor/i, anchor: 'INV-role' },
+    { id: 'INV-role-conduct', re: /never refuse|never file|not verdicts|input, not|plain |generic assistant|embodies roles|fix the SKILL, never/i, anchor: 'INV-role-conduct' },
+    { id: 'INV-execution-misc', re: /inline.*main thread|worker|sequential|main thread IS the crew|frame persists|never drop the roles|inspection.*only|no network|no shell|read-only|pre-flow|never dispatch|wave|dispatch.*flow|never create config|never print|control-command|mid-task|posture/i, anchor: 'INV-execution-model' },
+    { id: 'INV-debug', re: /repro|root cause|symptom|minimal change|one theory|no debugging/i, anchor: 'INV-debug' },
+    { id: 'INV-a11y', re: /alt=|outline|aria|reduced-motion|contrast|gray-100|role\/label|focus|color-only/i, anchor: 'INV-a11y' },
+    { id: 'INV-code-facts', re: /operator|operand|almost always a bug|≠/i, anchor: 'INV-code-facts' },
+    { id: 'INV-contract', re: /contract|additive|versions|bump|deprecated/i, anchor: 'INV-contract' },
+    { id: 'INV-backend', re: /migration|ad-hoc|atomic|pagination|unbounded|N\+1|eager-load|invalidation|buffer whole|timeouts|cancellation|hang/i, anchor: 'INV-backend' },
+  ];
+  for (const c of CONCEPTS) {
+    if (enf && !enf.includes(c.anchor)) errors.push(`invariant gate: concept ${c.id} has no mechanism row in enforcement.md (anchor "${c.anchor}")`);
+  }
+  // The matrix documents the per-tier side of the hook concepts — a removed
+  // guard row must fail this gate, not slip through as prose.
+  for (const row of ['Irreversible-command guard', 'Turn-end enforcement']) {
+    const matrix = readFileSync(join(import.meta.dirname, '..', 'docs', 'reference', 'harness-matrix.md'), 'utf8');
+    if (!matrix.includes(row)) errors.push(`invariant gate: harness-matrix.md lost its "${row}" row`);
+  }
+  const lineRe = /\bnever\b|\balways\b|MUST/;
+  const scanRoots = [join(root, 'skills'), join(root, 'agents')];
+  const unreg: string[] = [];
+  const seen = new Set<string>();
+  const walkInv = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) { walkInv(full); continue; }
+      if (!e.name.endsWith('.md')) continue;
+      for (const line of readFileSync(full, 'utf8').split(/\r?\n/)) {
+        if (!lineRe.test(line)) continue;
+        const key = line.trim();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        if (!CONCEPTS.some((c) => c.re.test(line))) unreg.push(`${full.replace(root + '/', '')}: ${key.slice(0, 100)}`);
+      }
+    }
+  };
+  for (const d of scanRoots) walkInv(d);
+  for (const u of unreg) errors.push(`invariant without mechanism: ${u} — add a concept row in enforcement.md + a bucket above`);
+  if (!unreg.length && enf) console.log(`✓ invariants: every never/always/MUST maps to a mechanism row`);
+}
+
 // Conditional-assertion guard: an expect() reachable only inside a truthiness
 // check silently passes when the value is absent. This class produced 9 defects.
 // Allowed: checks keyed on a declared invariant (tier, fixture keys).