@ionivetech/mugiwara 0.9.0 → 0.9.1

package/references/wave-banners.md

@@ -5,29 +5,28 @@ plugin and the opencode-target generator derive agent UI colors from the table
 below — change a color HERE, never in code. This file is machine-parsed:
 keep the table format exact (one row per agent, pipes, no extra columns).
 
-## Banner format (one form)
+## The banner
 
-Every flow stage opens with the banner line in the owning agent's color, and closes
-with a handoff line:
+Every flow stage opens with this line and closes with a handoff:
 
-```
-===== ⚔️ FLOW 3 — ZORO (EXECUTION) =====
-→ Flow 4 — Chopper (Checkpoint)
-```
+    ## ⚔️ Flow 3 — Zoro (Execution)
+    → Flow 4 — Chopper
 
-- Terminal: wrap the whole line in ANSI truecolor `\x1b[38;2;R;G;Bm` ... `\x1b[0m`.
-- Markdown UI: emit the plain equals line, no ANSI (UIs strip or garble escapes).
-- The crew emoji leads the line, before the `FLOW N` text.
-- RGB values come from the `hex` column below; R/G/B are the hex channels in
-  decimal (truecolor `38;2;R;G;B`). If the terminal lacks truecolor, use the
-  `ansi-256` index: `\x1b[38;5;Nm`.
-- Flow 9's handoff: `→ closure`.
-- The literal `FLOW N —` text must stay exact: the check-in protocol reads it.
-  Heal cycles are counted from the DECISION LOG's `## Flow 8` sections
-  (`mugiwara savepoint` greps `^## flow 8`), not from banners — a banner that
-  drops the literal does not reset the heal loop.
-- Never convey the flow stage by color alone — the crew name always accompanies
-  the color.
+Rules, all unconditional:
+
+- A markdown heading (`## `), the crew emoji, then `Flow N — Crew (Role)`.
+- **Never emit ANSI escapes.** The model cannot tell a terminal from a markdown
+  UI, so it must not try. Colour is applied by the harness plugin, which knows
+  the surface — see "Colour" below.
+- Keep `Flow N —` literal: the check-in protocol reads it.
+- Handoff is the LAST line of the stage's final response. Flow 9 closes with
+  `→ closure`.
+
+## Colour (harness, not model)
+
+The crew colour table below is consumed by the opencode plugin
+(`readBannerColors()`) and by any harness that can style output. The model never
+renders colour and never needs the hex values.
 
 ## Crew colors
 
@@ -53,12 +52,8 @@ their banners appear only when a wave or worker names them.
 
 ## Rules
 
-1. Banner before EVERY flow stage; handoff after it. Main thread emits `===== FLOW N — CREW =====` FIRST line and `→ Flow N+1 — Crew` LAST line even when subagent does work — covers Flow 0 Luffy, 1 Usopp, 2 Nami, 3 Zoro, 4 Chopper, 5 Sanji, 6 Franky, 7 Robin/Jinbe, 8 Brook, 9 Luffy. No flow stage starts without its banner (orchestration red flag).
-2. The color comes from this table only — never invent a hex mid-mission.
-3. One form everywhere: equals line `===== <emoji> FLOW N — <CREW> (ROLE) =====` — five `=` per side, the crew emoji from the table leading the line, ANSI-wrapped in terminals, plain in markdown-rendering UIs. When unsure, the plain form is safe everywhere.
-4. Only the crew table's colors and the two SGR forms above (truecolor,
-   256-index) may appear in a banner — never other escape families (OSC,
-   title, cursor, other SGR codes). The banner is a fixed template, not a
-   formatting playground.
+1. Banner before EVERY flow stage; handoff after it. Main thread emits `## <emoji> Flow N — Crew (Role)` FIRST line and `→ Flow N+1 — Crew` LAST line even when subagent does work — covers Flow 0 Luffy, 1 Usopp, 2 Nami, 3 Zoro, 4 Chopper, 5 Sanji, 6 Franky, 7 Robin/Jinbe, 8 Brook, 9 Luffy. No flow stage starts without its banner (orchestration red flag).
+2. The color comes from this table only — never invent a hex mid-mission. The model never emits color itself; the harness styles the heading.
+3. One form everywhere: heading `## <emoji> Flow N — Crew (Role)` — renders as a visual break in every markdown UI and stays readable as plain text in a terminal.
 5. Adding a crew member? Add the row here first; the plugin and target
    generator pick it up automatically.

package/scripts/build-hooks.ts

@@ -12,7 +12,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
-export const HOOK_ENTRIES = ['session-start', 'mugiwara-mode-tracker', 'auto-savepoint', 'engagement-marker', 'pipeline-guard'];
+export const HOOK_ENTRIES = ['session-start', 'mugiwara-mode-tracker', 'auto-savepoint', 'engagement-marker', 'pipeline-guard', 'pretool-guard'];
 
 // --check verifies the committed .js files are present and current, without
 // rewriting them. hooks.json points at the .js builds, so a missing or stale

package/scripts/gate-selftest.ts

@@ -968,5 +968,347 @@ console.log('\nW12 — doc integrity stale path');
   }
 }
 
+// --- E1: delete ## Before you start from luffy-orchestrator.md → validate-content fails ---
+console.log('\nE1 — luffy entry protocol');
+{
+  const lf = join(root, 'content', 'agents', 'luffy-orchestrator.md');
+  const original = readFileSync(lf, 'utf8');
+  try {
+    const broken = original.replace('## Before you start', '## Before you begin');
+    if (broken === original) {
+      console.error('✗ E1: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(lf, broken);
+      assert('luffy section renamed → validate-content fails', false, () => run('E1', 'bun scripts/validate-content.ts'));
+    }
+  } finally {
+    writeFileSync(lf, original);
+    assert('restored → content passes', true, () => run('E1-restore', 'bun scripts/validate-content.ts'));
+  }
+}
+
+// --- E2: restore the luffy exemption → the gate goes blind, selftest catches it ---
+console.log('\nE2 — luffy exemption');
+{
+  const vf = join(root, 'scripts', 'validate-content.ts');
+  const lf = join(root, 'content', 'agents', 'luffy-orchestrator.md');
+  const vOrig = readFileSync(vf, 'utf8');
+  const lOrig = readFileSync(lf, 'utf8');
+  try {
+    const vBroken = vOrig.replace(
+      "  const name = f.replace(/\\.md$/, '');\n  const text = readFileSync(join(agentDir, f), 'utf8');",
+      "  const name = f.replace(/\\.md$/, '');\n  if (name === 'luffy-orchestrator') continue;\n  const text = readFileSync(join(agentDir, f), 'utf8');",
+    );
+    const lBroken = lOrig.replace('## Before you start', '## Before you begin');
+    if (vBroken === vOrig || lBroken === lOrig) {
+      console.error('✗ E2: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(vf, vBroken);
+      writeFileSync(lf, lBroken);
+      // Blindness proof: with the exemption back, a captain with no checklist
+      // passes the gate. Demonstrating that blindness IS the passing test —
+      // it proves the gate can go blind, which is what this mutation guards.
+      if (run('E2', 'bun scripts/validate-content.ts')) {
+        passed++;
+        console.log('  ✓ E2: exemption blinds the gate — regression caught');
+      } else {
+        console.error('✗ E2: gate still red — exemption no longer blinds');
+        failed++;
+      }
+    }
+  } finally {
+    writeFileSync(vf, vOrig);
+    writeFileSync(lf, lOrig);
+    assert('restored → content passes', true, () => run('E2-restore', 'bun scripts/validate-content.ts'));
+  }
+}
+
+// --- E3: restore the source-only predicate → artifact case fails ---
+console.log('\nE3 — source-only predicate');
+{
+  const gf = join(root, 'hooks', 'pipeline-guard.ts');
+  const original = readFileSync(gf, 'utf8');
+  try {
+    const broken = original.replace('if (!sourceChangedNow && !artifactWorkNow()) return;', 'if (!sourceChangedNow) return;');
+    if (broken === original) {
+      console.error('✗ E3: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(gf, broken);
+      execSync('bun scripts/build-hooks.ts', { cwd: root, stdio: 'pipe', timeout: 120000 });
+      assert('source-only predicate → artifact case fails', false, () => run('E3', 'bunx vitest run test/hooks.test.ts -t "artifacts written"'));
+    }
+  } finally {
+    writeFileSync(gf, original);
+    execSync('bun scripts/build-hooks.ts', { cwd: root, stdio: 'pipe', timeout: 120000 });
+    assert('restored → artifact case passes', true, () => run('E3-restore', 'bunx vitest run test/hooks.test.ts -t "artifacts written"'));
+  }
+}
+
+// --- E4: remove gh pr create from the FORBIDDEN table → deny case fails ---
+console.log('\nE4 — forbidden table');
+{
+  const gf = join(root, 'src', 'guards.ts');
+  const original = readFileSync(gf, 'utf8');
+  try {
+    const broken = original.replace("  [/\\bgh\\s+pr\\s+(create|merge|ready)\\b/, 'opening or merging a PR'],\n", '');
+    if (broken === original) {
+      console.error('✗ E4: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(gf, broken);
+      execSync('bun scripts/build-hooks.ts', { cwd: root, stdio: 'pipe', timeout: 120000 });
+      assert('missing pr-create row → deny case fails', false, () => run('E4', 'bunx vitest run test/hooks.test.ts -t "gh pr create"'));
+    }
+  } finally {
+    writeFileSync(gf, original);
+    execSync('bun scripts/build-hooks.ts', { cwd: root, stdio: 'pipe', timeout: 120000 });
+    assert('restored → deny case passes', true, () => run('E4-restore', 'bunx vitest run test/hooks.test.ts -t "gh pr create"'));
+  }
+}
+
+// --- E5-overcorrection: block every git push → feature-push case fails ---
+console.log('\nE5 — over-broad push matcher');
+{
+  const gf = join(root, 'src', 'guards.ts');
+  const original = readFileSync(gf, 'utf8');
+  try {
+    const broken = original.replace(
+      "  [/\\bgit\\s+push\\b[^|;&]*\\b(main|master|production|release)\\b/, 'pushing to a protected branch'],",
+      "  [/\\bgit\\s+push\\b[^|;&]*\\b(main|master|production|release)\\b/, 'pushing to a protected branch'],\n  [/\\bgit\\s+push\\b/, 'pushing anything'],",
+    );
+    if (broken === original) {
+      console.error('✗ E5: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(gf, broken);
+      execSync('bun scripts/build-hooks.ts', { cwd: root, stdio: 'pipe', timeout: 120000 });
+      assert('push-all matcher → feature-push case fails', false, () => run('E5', 'bunx vitest run test/hooks.test.ts -t "feature-branch push"'));
+    }
+  } finally {
+    writeFileSync(gf, original);
+    execSync('bun scripts/build-hooks.ts', { cwd: root, stdio: 'pipe', timeout: 120000 });
+    assert('restored → feature-push passes', true, () => run('E5-restore', 'bunx vitest run test/hooks.test.ts -t "feature-branch push"'));
+  }
+}
+
+// --- E6: remove the harness-matrix guard row → --check-invariants fails ---
+console.log('\nE6 — matrix guard row');
+{
+  const mf = join(root, 'docs', 'reference', 'harness-matrix.md');
+  const original = readFileSync(mf, 'utf8');
+  try {
+    const broken = original.replace(/Irreversible-command guard/g, 'Irreversible-command sentry');
+    if (broken === original) {
+      console.error('✗ E6: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(mf, broken);
+      assert('guard row renamed → --check-invariants fails', false, () => run('E6', 'bun scripts/validate-content.ts --check-invariants'));
+    }
+  } finally {
+    writeFileSync(mf, original);
+    assert('restored → invariants pass', true, () => run('E6-restore', 'bun scripts/validate-content.ts --check-invariants'));
+  }
+}
+
+// --- E7: point the mirror at a missing file → mirror test fails ---
+console.log('\nE7 — todos mirror');
+{
+  const sf = join(root, 'scripts', 'savepoint.sh');
+  const original = readFileSync(sf, 'utf8');
+  try {
+    const broken = original.replace('TODOS_FILE="$MISSION_DIR/flows/todos.md"', 'TODOS_FILE="$MISSION_DIR/flows/nope.md"');
+    if (broken === original) {
+      console.error('✗ E7: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(sf, broken);
+      assert('missing mirror → mirror test fails', false, () => run('E7', 'bunx vitest run test/savepoint.test.ts -t "todos mirror"'));
+    }
+  } finally {
+    writeFileSync(sf, original);
+    assert('restored → mirror test passes', true, () => run('E7-restore', 'bunx vitest run test/savepoint.test.ts -t "todos mirror"'));
+  }
+}
+
+// --- N1 mutation: remove `case 'initiative'` → --check-doc-integrity red ---
+console.log('\nN1 — initiative case mutation');
+{
+  const f = join(root, 'src', 'cli.ts');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = original.replace("    case 'initiative': return initiativeCmd(flags, _);\n", '');
+    if (broken === original) {
+      console.error('✗ N1: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(f, broken);
+      assert('missing initiative case → doc-integrity fails', false, () => run('N1', 'bun scripts/validate-content.ts --check-doc-integrity'));
+    }
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → doc-integrity passes', true, () => run('N1-restore', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  }
+}
+
+// --- N2 mutation: ANSI escape back into wave-banners.md → banner-format red ---
+console.log('\nN2 — banner-format mutation');
+{
+  const f = join(root, 'references', 'wave-banners.md');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = `${original}\nTerminal: wrap in ANSI \`\\x1b[38;2;R;G;Bm\` ... \`\\x1b[0m\`.\n`;
+    writeFileSync(f, broken);
+    assert('ANSI escape in prose → doc-integrity fails', false, () => run('N2', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → doc-integrity passes', true, () => run('N2-restore', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  }
+}
+
+// --- N3 mutation: depth allowlist back to lean → --check-config red ---
+console.log('\nN3 — depth allowlist mutation');
+{
+  const f = join(root, 'scripts', 'savepoint.sh');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = original.split('in full|standard|quick').join('in full|standard|lean');
+    if (broken === original) {
+      console.error('✗ N3: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(f, broken);
+      assert('lean-only allowlist → check-config fails', false, () => run('N3', 'bun scripts/validate-content.ts --check-config'));
+    }
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → check-config passes', true, () => run('N3-restore', 'bun scripts/validate-content.ts --check-config'));
+  }
+}
+
+// --- N4 mutation: documented enum value the code rejects → --check-config red ---
+console.log('\nN4 — documented-enum mutation');
+{
+  const f = join(root, 'docs', 'concepts', 'config.md');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = original.replace('`review_depth` | full / standard / quick |', '`review_depth` | full / standard / turbo |');
+    if (broken === original) {
+      console.error('✗ N4: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(f, broken);
+      assert('turbo documented → check-config fails', false, () => run('N4', 'bun scripts/validate-content.ts --check-config'));
+    }
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → check-config passes', true, () => run('N4-restore', 'bun scripts/validate-content.ts --check-config'));
+  }
+}
+
+// --- N5 mutation: flow-summary contract removed → content validation red ---
+console.log('\nN5 — flow-summary mutation');
+{
+  const f = join(root, 'content', 'skills', 'mugiwara-orchestration', 'SKILL.md');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = original.replace('## Flow summary line\n', '');
+    if (broken === original) {
+      console.error('✗ N5: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(f, broken);
+      assert('summary contract removed → validation fails', false, () => run('N5', 'bun scripts/validate-content.ts --check-doc-integrity'));
+    }
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → validation passes', true, () => run('N5-restore', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  }
+}
+
+// --- N6 mutation: banner recording removed from marker → hooks banner test red ---
+console.log('\nN6 — banner-recording mutation');
+{
+  const f = join(root, 'hooks', 'engagement-marker.ts');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = original
+      .replace("        if (sameSession && typeof prev.last_banner_flow === 'number') bannerFlow = prev.last_banner_flow;\n", '')
+      .replace("        if (sameSession && typeof prev.last_banner_flow_at === 'string') bannerFlowAt = prev.last_banner_flow_at;\n", '');
+    if (broken === original) {
+      console.error('✗ N6: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(f, broken);
+      run('N6-build', 'bun run build-hooks');
+      assert('recording removed → banner test fails', false, () => run('N6', 'bun test test/hooks.test.ts -t banner'));
+    }
+  } finally {
+    writeFileSync(f, original);
+    run('N6-rebuild', 'bun run build-hooks');
+    assert('restored → banner test passes', true, () => run('N6-restore', 'bun test test/hooks.test.ts -t banner'));
+  }
+}
+
+// --- N7 mutation: `mugiwara lessons import` with no CLI case → doc-integrity red ---
+console.log('\nN7 — lessons-import mutation');
+{
+  const f = join(root, 'docs', 'adoption.md');
+  const original = readFileSync(f, 'utf8');
+  try {
+    writeFileSync(f, `${original}\nImport with \`mugiwara lessons import <file>\`.\n`);
+    assert('dangling lessons verb → doc-integrity fails', false, () => run('N7', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → doc-integrity passes', true, () => run('N7-restore', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  }
+}
+
+// --- N8 mutation: `/mugiwara mode` slash form → in-session phrase check red ---
+console.log('\nN8 — slash-mode mutation');
+{
+  const f = join(root, 'content', 'skills', 'mugiwara-workflow', 'SKILL.md');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = original.replace('Say `mugiwara mode <guided|semi|auto>` in session', '`/mugiwara mode <guided|semi|auto>` applies');
+    if (broken === original) {
+      console.error('✗ N8: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(f, broken);
+      assert('slash mode phrase → doc-integrity fails', false, () => run('N8', 'bun scripts/validate-content.ts --check-doc-integrity'));
+    }
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → doc-integrity passes', true, () => run('N8-restore', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  }
+}
+
+// --- N9 mutation: unqualified "12 platforms" → README platform-count check red ---
+console.log('\nN9 — platform-count mutation');
+{
+  const f = join(root, 'README.md');
+  const original = readFileSync(f, 'utf8');
+  try {
+    const broken = original.replace(
+      '9 via install (Claude, opencode, Copilot, Gemini, Codex, Windsurf, Cline, Kilo, Antigravity) + 3 via marketplace manifest (Cursor, Kimi, Pi)',
+      'Claude, opencode, Copilot, Gemini, Codex, Cursor, Kimi, Pi, and 5 more',
+    );
+    if (broken === original) {
+      console.error('✗ N9: mutation target not found');
+      failed++;
+    } else {
+      writeFileSync(f, broken);
+      assert('unqualified count → doc-integrity fails', false, () => run('N9', 'bun scripts/validate-content.ts --check-doc-integrity'));
+    }
+  } finally {
+    writeFileSync(f, original);
+    assert('restored → doc-integrity passes', true, () => run('N9-restore', 'bun scripts/validate-content.ts --check-doc-integrity'));
+  }
+}
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed > 0 ? 1 : 0);

package/scripts/savepoint.sh

@@ -365,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).
@@ -456,8 +464,12 @@ if [ -f "$MUGIWARA_DIR/config" ]; then
   _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