@ionivetech/mugiwara 0.9.0 → 0.9.1

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) ---
@@ -440,20 +448,68 @@ if (integrityArg !== -1) {
       errors.push(`doc-integrity: README rank-1 ${rankMatch2[1]}% != metrics ${m2.retrieval_rank1}%`);
     }
   }
-  // stale CLI commands: any `mugiwara <word>` where word is not a valid CLI case, appearing as code, is stale
-  const validCmds = new Set(['install','update','uninstall','list','reset','archive','clean','continue','status','cost','run','savepoint','blame','handoff','sign','migrate','lesson','help','version','mode','off']);
-  const docsToScan = ['docs/concepts/workflow.md','docs/concepts/config.md','README.md','references/multi-actor.md'];
-  for (const doc of docsToScan) {
-    const p = join(import.meta.dirname, '..', doc);
+  // 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;
-    const txt = readFileSync(p, 'utf8');
-    for (const m of txt.matchAll(/`mugiwara ([a-z-]+)/g)) {
-      const cmd = m[1];
-      if (!validCmds.has(cmd) && cmd !== '--help' && cmd !== '--version') {
-        errors.push(`doc-integrity: ${doc} contains stale command "mugiwara ${cmd}" not in src/cli.ts`);
-      }
+    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');
+  }
 }
 }
 
@@ -537,7 +593,52 @@ if (process.argv.includes('--check-config')) {
       errors.push(`config-drift: docs key "${k}" not found in code`);
     }
   }
-  if (!errors.some(e => e.startsWith('config-drift'))) {
+  // 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(', ')})`);
   }
 }
@@ -570,7 +671,9 @@ if (process.argv.includes('--check-wiring')) {
       if (full.endsWith(`/src/${f}`) || full === join(srcDir, f)) continue;
       try {
         const txt = readFileSync(full, 'utf8');
-        if (txt.includes(`'./${stem}`) || txt.includes(`"./${stem}`) || txt.includes(`'./${stem}.ts'`) || txt.includes(`"./${stem}.ts"`)) {
+        // 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;
         }
@@ -645,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).

package/scripts/write-metrics.ts

@@ -3,7 +3,7 @@
 // Deterministic, no network. Runs retrieval-eval --json and verify-install --json.
 
 import { execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 const root = join(import.meta.dirname, '..');
@@ -71,3 +71,27 @@ const outPath = join(outDir, 'latest.json');
 writeFileSync(outPath, JSON.stringify(metrics, null, 2) + '\n');
 console.log(`✓ wrote ${outPath}`);
 console.log(JSON.stringify(metrics, null, 2));
+
+// Sync the README metrics table in the same run, so neither AI nor human
+// opens a PR with stale numbers (the classic first-push CI red). The
+// --check-readme-metrics gate stays as the backstop: if these patterns stop
+// matching, it fails loudly instead of silently drifting.
+{
+  const readmePath = join(root, 'README.md');
+  const before = readFileSync(readmePath, 'utf8');
+  let after = before;
+  after = after.replace(
+    /\*\*[\d.]+%\*\*, \d+ probes/,
+    `**${rank1Str}**, ${probes} probes`,
+  );
+  after = after.replace(
+    /\*\*\d+\/\d+\*\*(, \d+ targets)/,
+    `**${pointersTotal}/${pointersTotal}**$1`,
+  );
+  if (after !== before) {
+    writeFileSync(readmePath, after);
+    console.log('✓ README metrics table synced');
+  } else {
+    console.log('✓ README metrics table already current');
+  }
+}

package/src/cli.ts

@@ -19,6 +19,7 @@ import { ensureConfig } from './config.ts';
 import { costEnvelope } from './cost.ts';
 import { computeLiveSlop } from './slop.ts';
 import { loadRegistry } from './evidence.ts';
+import { runInitiative } from './initiative.ts';
 import { buildCostLedger, toCostJSON } from './reporting.ts';
 import { enforceHarnessPolicy } from './policy.ts';
 
@@ -82,6 +83,7 @@ export async function run(argv: string[]): Promise<void> {
     case 'sign': return signCmd(flags, _);
     case 'migrate': return migrateCmd(flags, _);
     case 'lesson': return lessonCmd(flags, _);
+    case 'initiative': return initiativeCmd(flags, _);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
@@ -197,7 +199,13 @@ async function resolveOptions(flags: Args['flags']): Promise<{ scope: Scope; pro
         targetIds = idx.includes(0) ? [...TARGET_IDS] : idx.map(i => TARGET_IDS[i - 1]);
       }
     }
+    const MARKETPLACE = new Set(['cursor', 'kimi', 'pi']);
     for (const id of targetIds) {
+      if (MARKETPLACE.has(id)) {
+        console.error(`mugiwara: ${id} installs through its marketplace manifest, not --target.`);
+        console.error('  See docs/reference/harness-matrix.md — marketplace row.');
+        process.exit(1);
+      }
       if (!targets[id]) throw new Error(`Unknown target: ${id} (valid: ${TARGET_IDS.join(', ')}, all)`);
     }
 
@@ -604,6 +612,13 @@ function lessonCmd(flags: Args['flags'], positionals: string[]): void {
   console.log(`lesson appended: ${line}`);
 }
 
+/** `mugiwara initiative <status|conflict-check> <plan>` — sub-mission checks. */
+function initiativeCmd(_flags: Args['flags'], positionals: string[]): void {
+  const r = runInitiative(positionals[1], positionals[2]);
+  process.stdout.write(r.output);
+  if (r.code !== 0) process.exit(r.code);
+}
+
 export function migrateCmd(flags: Args['flags'], positionals: string[] = []): void {
   const projectDir = resolveProjectDir(str(flags.project));
   const dryRun = flag(flags.dryRun);

package/src/config.ts

@@ -23,7 +23,7 @@ export const DEFAULT_CONFIG = [
   '# -- Git --------------------------------------------------',
   'branch=feature/{type}-{issue}-{slug}',
   'commit=conventional',
-  'auto_commit=on               # on | off — off hands you an uncommitted tree in guided/semi',
+  'auto_commit=off              # on | off — off hands you an uncommitted tree in guided/semi',
   '',
   '# -- Gates ------------------------------------------------',
   'coverage_new=85',

package/src/guards.ts

@@ -0,0 +1,40 @@
+// src/guards.ts — shared irreversible-command predicates (E4, E5).
+//
+// Single source of truth for the FORBIDDEN table. hooks/pretool-guard.ts
+// imports it (bundled into the .js by build-hooks). The opencode plugin
+// (.opencode/plugins/mugiwara.mjs) embeds a copy of the table delimited by
+// the same GUARDS-TABLE markers — test/plugin.test.ts asserts the two blocks
+// are byte-identical, so a drift fails CI instead of silently forking
+// enforcement across harnesses.
+
+export const FORBIDDEN: Array<[RegExp, string]> = [
+// GUARDS-TABLE-START
+  [/\bgh\s+pr\s+(create|merge|ready)\b/, 'opening or merging a PR'],
+  [/\bgh\s+release\s+create\b/, 'creating a release'],
+  [/\bgit\s+merge\b/, 'merging a branch'],
+  [/\bgit\s+push\b[^|;&]*\b(main|master|production|release)\b/, 'pushing to a protected branch'],
+  [/\bgit\s+push\b[^|;&]*--force/, 'force-pushing'],
+  [/\bnpm\s+publish\b|\byarn\s+publish\b|\bpnpm\s+publish\b/, 'publishing a package'],
+  [/\bkubectl\s+(apply|delete|rollout)\b/, 'changing a cluster'],
+  [/\bterraform\s+(apply|destroy)\b/, 'changing infrastructure'],
+  [/\bdocker\s+push\b/, 'pushing an image'],
+  [/\baws\s+\w+\s+(create|delete|update|put)\b/, 'changing cloud resources'],
+// GUARDS-TABLE-END
+];
+
+/** The refused action for a shell command, or null when it may run. */
+export function checkCommand(command: string): string | null {
+  for (const [re, action] of FORBIDDEN) {
+    if (re.test(command)) return action;
+  }
+  return null;
+}
+
+/** Deny message: names the action, the human terminal step, the escape hatch. */
+export function refusalMessage(action: string): string {
+  return (
+    `Mugiwara: refusing to ${action}. The crew never creates a PR, merges, or ` +
+    `deploys — the human does, from the branch and the verdict the crew hands over. ` +
+    `Run it yourself, or set enforce=off in .mugiwara/config.`
+  );
+}

package/src/initiative.ts

@@ -0,0 +1,174 @@
+// src/initiative.ts — sub-mission dashboard + conflict detection (N1).
+//
+// Flow 2 produces a `## Sub-missions` table on team missions; nothing checked
+// it after the original command was deleted. `status` renders the dashboard,
+// `conflict-check` exits 1 when one file is touched by two sub-missions.
+import { existsSync, readFileSync } from 'node:fs';
+
+export interface SubMission {
+  id: string;
+  name: string;
+  assignee: string;
+  branch: string;
+  status: string;
+  dependsOn: string;
+  touchedFiles: string[];
+}
+
+/** Canonical header — printed as the hint when a table fails to parse. */
+export const SUB_MISSIONS_HEADER =
+  '| ID | Name | Assignee | Branch | Status | Depends On | Touched Files |';
+
+/** Split a Touched Files cell on commas AND whitespace; no trailing commas survive. */
+export function splitTouchedFiles(cell: string): string[] {
+  return cell
+    .split(/[,\s]+/)
+    .map((s) => s.trim().replace(/,+$/, ''))
+    .filter(Boolean);
+}
+
+export interface ParseResult {
+  /** True when a `## Sub-missions` section exists (any case). */
+  hasSection: boolean;
+  rows: SubMission[];
+}
+
+function splitRow(line: string): string[] {
+  let t = line.trim();
+  if (t.startsWith('|')) t = t.slice(1);
+  if (t.endsWith('|')) t = t.slice(0, -1);
+  return t.split('|').map((c) => c.trim());
+}
+
+/**
+ * Parse the `## Sub-missions` table. Header match is case-insensitive
+ * (`| id | name |` and `| ID | Name |` both work). Returns zero rows — not an
+ * error here — when the section exists but no data rows parse; the caller
+ * decides what that means (conflict-check treats it as a defect, never as a
+ * solo mission).
+ */
+export function parseSubMissions(planText: string): ParseResult {
+  const lines = planText.split('\n');
+  const sectionIdx = lines.findIndex((l) => /^##\s+sub-missions\s*$/i.test(l.trim()));
+  if (sectionIdx < 0) return { hasSection: false, rows: [] };
+  const endIdx = lines.findIndex((l, i) => i > sectionIdx && /^##\s+\S/.test(l.trim()));
+  const body = lines.slice(sectionIdx + 1, endIdx < 0 ? undefined : endIdx);
+
+  const isTableLine = (l: string): boolean => /^\s*\|.*\|\s*$/.test(l);
+  const isSeparator = (l: string): boolean => /^\s*\|?[\s:|-]+\|?[\s:|.-]*$/.test(l) && /-/.test(l);
+  const table = body.filter((l) => isTableLine(l));
+  if (!table.length) return { hasSection: true, rows: [] };
+  const header = splitRow(table[0]).map((c) => c.toLowerCase());
+  // Case-insensitive header match: must at least identify id + name columns.
+  const idIdx = header.findIndex((c) => c === 'id');
+  const nameIdx = header.findIndex((c) => c === 'name');
+  if (idIdx < 0 || nameIdx < 0) return { hasSection: true, rows: [] };
+  const col = (name: string, fallback: number): number => {
+    const i = header.findIndex((c) => c === name);
+    return i < 0 ? fallback : i;
+  };
+  const touchedIdx = header.findIndex((c) => /touch/.test(c));
+  const dataStart = table.length > 1 && isSeparator(table[1]) ? 2 : 1;
+  const rows: SubMission[] = [];
+  for (const line of table.slice(dataStart)) {
+    if (isSeparator(line)) continue;
+    const cells = splitRow(line);
+    const id = cells[idIdx] ?? '';
+    if (!id) continue;
+    rows.push({
+      id,
+      name: cells[nameIdx] ?? '',
+      assignee: cells[col('assignee', 2)] ?? '',
+      branch: cells[col('branch', 3)] ?? '',
+      status: cells[col('status', 4)] ?? '',
+      dependsOn: cells[col('depends on', 5)] ?? '',
+      touchedFiles: touchedIdx < 0 ? [] : splitTouchedFiles(cells[touchedIdx] ?? ''),
+    });
+  }
+  return { hasSection: true, rows };
+}
+
+const DONE = /(\[x\]|done|complete|merged|closed)/i;
+
+/** Rows whose Depends On names an unfinished sub-mission. */
+export function blockedRows(rows: SubMission[]): Array<{ id: string; blockedBy: string }> {
+  const statusOf = new Map(rows.map((r) => [r.id.toLowerCase(), r.status]));
+  const out: Array<{ id: string; blockedBy: string }> = [];
+  for (const r of rows) {
+    const dep = r.dependsOn.trim();
+    if (!dep || dep === '-') continue;
+    for (const part of dep.split(/[,\s]+/).filter(Boolean)) {
+      const st = statusOf.get(part.toLowerCase());
+      if (st !== undefined && !DONE.test(st)) {
+        out.push({ id: r.id, blockedBy: part });
+        break;
+      }
+      if (st === undefined && !DONE.test(dep)) {
+        out.push({ id: r.id, blockedBy: part });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+export interface Conflict {
+  file: string;
+  ids: string[];
+}
+
+/** Files touched by more than one sub-mission. */
+export function findConflicts(rows: SubMission[]): Conflict[] {
+  const owners = new Map<string, string[]>();
+  for (const r of rows) {
+    for (const f of r.touchedFiles) {
+      const list = owners.get(f) ?? [];
+      if (!list.includes(r.id)) list.push(r.id);
+      owners.set(f, list);
+    }
+  }
+  return [...owners.entries()]
+    .filter(([, ids]) => ids.length > 1)
+    .map(([file, ids]) => ({ file, ids }));
+}
+
+export interface InitiativeResult {
+  code: number;
+  output: string;
+}
+
+export function runInitiative(sub: string | undefined, planPath: string | undefined): InitiativeResult {
+  if (!sub || (sub !== 'status' && sub !== 'conflict-check')) {
+    return { code: 1, output: 'usage: mugiwara initiative <status|conflict-check> <plan>\n' };
+  }
+  if (!planPath) {
+    return { code: 1, output: `usage: mugiwara initiative ${sub} <plan>\n` };
+  }
+  if (!existsSync(planPath)) {
+    return { code: 1, output: `mugiwara: plan not found: ${planPath}\n` };
+  }
+  const { hasSection, rows } = parseSubMissions(readFileSync(planPath, 'utf8'));
+  if (!hasSection) {
+    return { code: 0, output: 'solo mission (no ## Sub-missions section)\n' };
+  }
+  if (!rows.length) {
+    return {
+      code: 1,
+      output: `mugiwara: ## Sub-missions section present but no rows parsed — expected header:\n${SUB_MISSIONS_HEADER}\n`,
+    };
+  }
+  if (sub === 'status') {
+    const blocked = new Map(blockedRows(rows).map((b) => [b.id, b.blockedBy]));
+    const lines = ['id | name | assignee | branch | status | blocked-by'];
+    for (const r of rows) {
+      lines.push(
+        `${r.id} | ${r.name} | ${r.assignee} | ${r.branch} | ${r.status} | ${blocked.get(r.id) ?? '-'}`,
+      );
+    }
+    return { code: 0, output: lines.join('\n') + '\n' };
+  }
+  const conflicts = findConflicts(rows);
+  if (!conflicts.length) return { code: 0, output: 'no conflicts: no file is touched by two sub-missions\n' };
+  const lines = conflicts.map((c) => `conflict: ${c.file} touched by ${c.ids.join(', ')}`);
+  return { code: 1, output: lines.join('\n') + '\n' };
+}

package/src/targets/claude.ts

@@ -62,6 +62,7 @@ function wireSettings(root: string, hooksDir: string): { written: string[]; note
   const events: Record<string, { file: string; timeout: number; matcher?: string }> = {
     SessionStart: { file: 'session-start.js', timeout: 10 },
     UserPromptSubmit: { file: 'mugiwara-mode-tracker.js', timeout: 5 },
+    PreToolUse: { file: 'pretool-guard.js', timeout: 10, matcher: 'Bash' },
     Stop: { file: 'auto-savepoint.js', timeout: 20 },
     SubagentStop: { file: 'pipeline-guard.js', timeout: 15 },
     // matcher scopes the marker to crew invocations — without it the hook would