@ionivetech/mugiwara 0.6.4 → 0.6.6

package/scripts/verify-install.ts

@@ -1,61 +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.
+// scripts/verify-install.ts — G1: prove the shipped prose does not lie.
+//
+// Three checks, all of which failed silently before:
+//   A. pointer resolution  — every `references/*.md` pointer resolves after install
+//   B. prose path validity — every `.mugiwara/…`, `scripts/…`, `docs/…` path a
+//      skill or agent NAMES either exists in the repo or matches a declared
+//      runtime shape. Four BLOCKER/MAJOR findings shared one root cause:
+//      nothing verified that a path named in prose actually exists.
+//   C. reference reachability — every reference file has an inbound pointer.
+//      Unreachable files still install into every project.
 
 import { existsSync, mkdtempSync, rmSync, readFileSync, readdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, basename, relative } from 'node:path';
 import { tmpdir } from 'node:os';
 import { installTo } from '../src/installer.ts';
-import { targets } from '../src/targets/index.ts';
+import { targets, TARGET_IDS } from '../src/targets/index.ts';
 
-const tierTargets = [
-  { id: 'claude', tier: 1 },
-  { id: 'codex', tier: 2 },
-  { id: 'kilo', tier: 3 },
-];
+const repoRoot = join(import.meta.dirname, '..');
+const fail: string[] = [];
+
+function findMd(root: string, out: string[] = []): string[] {
+  if (!existsSync(root)) return out;
+  for (const ent of readdirSync(root, { withFileTypes: true })) {
+    const p = join(root, ent.name);
+    if (ent.isDirectory()) findMd(p, out);
+    else if (ent.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
 
-let total = 0;
-let broken = 0;
+// ---------------------------------------------------------------------------
+// A. pointer resolution, across EVERY install target (was 3 of 9)
+// ---------------------------------------------------------------------------
+let pointers = 0;
+let brokenPointers = 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}-`));
+for (const id of TARGET_IDS) {
+  const target = targets[id];
+  const dir = mkdtempSync(join(tmpdir(), `mugi-verify-${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/'));
+    const skillFiles = findMd(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)];
+      // Targets emit skills either as `<skillsDir>/<name>/SKILL.md` (claude) or
+      // as a flat `<skillsDir>/<name>.instructions.md` (copilot). Both forms
+      // must yield the skill name, because non-native targets store references
+      // per-skill under `.mugiwara/refs/<name>/`.
+      const relSkill = relative(skillsDir, file);
+      const skillName = relSkill.includes('/') ? relSkill.split('/')[0] : basename(relSkill).split('.')[0];
 
-      for (const m of refs) {
-        total++;
+      for (const m of readFileSync(file, 'utf8').matchAll(/`([^`]*references\/[^`]+\.md)`/g)) {
+        pointers++;
         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`);
+        const candidates = [
+          join(dirname(file), pointer),
+          join(mugiwaraRefsDir, pointer.replace(/^(?:_shared\/)?references\//, '')),
+          ...(target.refsDir
+            ? [join(target.refsDir({ scope: 'project', projectDir: dir, home: '' }, skillName), basename(pointer))]
+            : []),
+        ];
+        if (!candidates.some((p) => existsSync(p))) {
+          brokenPointers++;
+          fail.push(`✗ [${id}] ${file.replace(dir + '/', '')}: \`${pointer}\` → not found`);
         }
       }
     }
@@ -64,9 +75,108 @@ for (const tt of tierTargets) {
   }
 }
 
-if (broken > 0) {
-  console.log(`\n✗ ${broken}/${total} pointers cannot resolve after install`);
-  process.exit(1);
+// ---------------------------------------------------------------------------
+// B. prose path validity
+// ---------------------------------------------------------------------------
+// `.mugiwara/**` paths are written at RUNTIME — they never exist in a clone
+// (`.mugiwara/` is gitignored), so existence proves nothing. What can be
+// verified is the SHAPE: prose must name the same filename template the
+// scripts actually write. This is the check that would have caught
+// savepoint.sh globbing `issues/<mission>-blockers.md` while 15 prose sites
+// mandated the dated `issues/YYYY-MM-DD-<mission>-blockers.md`.
+const RUNTIME_SHAPES: RegExp[] = [
+  /^\.mugiwara\/?(\*\*)?$/,                                       // bare mention of the dir
+  /^~?\/?\.mugiwara\/config$/,                                    // project + global config
+  /^\.mugiwara\/(state|continue)\/<mission>\/(\[member\]|state|<member>)\.json$/,
+  /^\.mugiwara\/issues\/(YYYY-MM-DD-<mission>-blockers\.md)?$/,
+  /^\.mugiwara\/logs\/(YYYY-MM-DD-<mission>\.md|lessons\.md)?$/,
+  /^\.mugiwara\/(plans|spec|reports)\/(YYYY-MM-DD-<mission>\.md)?$/,
+  /^\.mugiwara\/review\/(YYYY-MM-DD-<mission>-(review|security|verifier)\.md)?$/,
+  /^\.mugiwara\/results\/<mission>\/([0-9]{2}-[a-z-]+|eval|resume|todos)\.md$/,
+  /^\.mugiwara\/results\/?$/,
+];
+
+// Shape violations that exist today and are NOT fixed in this mission because
+// another worker holds `content/**` prose this wave. Ratchet: a NEW violation
+// fails the gate; these two are reported, then must be deleted from this list.
+// Prose paths whose SHAPE is known-wrong but not yet fixed. Reported every run
+// so they cannot rot quietly; emptied as each is repaired. Keep this empty —
+// an entry here is a defect with a due date, never a permanent exemption.
+const KNOWN_SHAPE_DRIFT = new Map<string, string>([]);
+
+/** `[label](path)`, `bun scripts/x.ts --flag`, trailing punctuation → the bare path. */
+function normalizePath(raw: string): string {
+  let s = raw.trim();
+  const link = s.match(/^\[[^\]]*\]\(([^)]+)\)$/);
+  if (link) s = link[1];
+  s = s.replace(/^(?:bun|bash|sh|npx|node)\s+/, '');
+  s = s.split(/\s/)[0];
+  return s.replace(/[.,;:]$/, '');
+}
+
+const PROSE_PATH = /`([^`\n]*?(?:\.mugiwara\/|scripts\/|docs\/)[^`\n]*?)`/g;
+const proseFiles = [...findMd(join(repoRoot, 'content')), ...findMd(join(repoRoot, 'references'))];
+
+let prosePaths = 0;
+const drift: string[] = [];
+for (const file of proseFiles) {
+  const rel = relative(repoRoot, file);
+  readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+    for (const m of line.matchAll(PROSE_PATH)) {
+      const p = normalizePath(m[1]);
+      if (!p.includes('/')) continue;
+      prosePaths++;
+      const at = `${rel}:${i + 1}`;
+
+      if (/(^|\/)\.mugiwara\//.test(p) || p === '.mugiwara/' || p === '.mugiwara/**') {
+        if (RUNTIME_SHAPES.some((re) => re.test(p))) continue;
+        if (KNOWN_SHAPE_DRIFT.has(p)) { drift.push(`  ${at}: \`${p}\` — ${KNOWN_SHAPE_DRIFT.get(p)}`); continue; }
+        fail.push(`✗ ${at}: \`${p}\` → not a declared runtime path shape`);
+        continue;
+      }
+      // scripts/ and docs/ are SHIPPED files — they must exist in the repo
+      if (!existsSync(join(repoRoot, p))) fail.push(`✗ ${at}: \`${p}\` → file does not exist`);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// C. reference reachability (file → pointer, the inverse of check A)
+// ---------------------------------------------------------------------------
+// Hard zero. The 18 orphans this ratchet was holding were all substantive —
+// worksheets, rubrics and worked examples their own skill visibly needed — so
+// every one was wired to its parent section rather than deleted. With the
+// backlog at zero the ratchet becomes what it should always have been: a new
+// reference file must be pointed at by the prose that needs it, or it is not
+// a reference, it is dead weight shipped to every project.
+const ORPHAN_BASELINE = 0;
+
+const corpus = proseFiles.map((f) => ({ file: f, body: readFileSync(f, 'utf8') }));
+const refFiles = proseFiles.filter((f) => f.includes('/references/') || relative(repoRoot, f).startsWith('references/'));
+const orphans: string[] = [];
+for (const rf of refFiles) {
+  const needle = `references/${basename(rf)}`;
+  const reachable = corpus.some((c) => c.file !== rf && c.body.includes(needle));
+  if (!reachable) orphans.push(relative(repoRoot, rf));
+}
+if (orphans.length > ORPHAN_BASELINE) {
+  fail.push(
+    `✗ ${orphans.length} unreachable reference files (baseline ${ORPHAN_BASELINE}) — a new orphan was added:\n` +
+      orphans.map((o) => `    ${o}`).join('\n'),
+  );
 }
 
-console.log(`✓ ${total} pointers checked across ${tierTargets.length} targets — all resolve`);
+// ---------------------------------------------------------------------------
+console.log(`  ${pointers} pointers checked across ${TARGET_IDS.length} targets`);
+console.log(`  ${prosePaths} prose paths checked in ${proseFiles.length} files`);
+console.log(`  ${orphans.length}/${refFiles.length} reference files unreachable (baseline ${ORPHAN_BASELINE})`);
+if (orphans.length) orphans.forEach((o) => console.log(`    orphan: ${o}`));
+if (drift.length) { console.log('  known prose-path drift (owned elsewhere, must be fixed):'); drift.forEach((d) => console.log(d)); }
+
+if (fail.length) {
+  console.log('');
+  fail.forEach((f) => console.log(f));
+  console.log(`\n✗ verify-install: ${fail.length} problem(s) (${brokenPointers} broken pointers)`);
+  process.exit(1);
+}
+console.log('✓ verify-install: pointers resolve, prose paths valid, no new orphans');

package/src/args.ts

@@ -9,7 +9,7 @@ export type Args = {
 const VALUE_FLAGS: Record<string, string> = { '--project': 'project', '--target': 'target' };
 const BOOL_FLAGS: Record<string, string> = {
   '--global': 'global', '--yes': 'yes', '-y': 'yes', '--force': 'force',
-  '--dry-run': 'dryRun', '--keep-logs': 'keepLogs', '--check': 'check',
+  '--dry-run': 'dryRun', '--keep-logs': 'keepLogs', '--check': 'check', '--all': 'all',
   '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
 };
 

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // src/cli.ts
 import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,6 +11,9 @@ import { targets, TARGET_IDS } from './targets/index.ts';
 import { installTo, removeInstalled, VERSION, ensureProjectGitignore, removeProjectGitignore } from './installer.ts';
 import { manifestPath, readManifest, writeManifest, type Scope } from './manifest.ts';
 import { resetMission, archiveMission } from './mission.ts';
+import { runOnboard } from './onboard.ts';
+import { runScript, RUNNABLE } from './run.ts';
+import { readContinue, readState, resolveContinue, formatTable, formatResume, gitActor } from './continue.ts';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
@@ -25,6 +29,13 @@ export async function run(argv: string[]): Promise<void> {
     case 'list': return list(flags);
     case 'reset': return resetCmd(flags);
     case 'archive': return archive(flags, _);
+    case 'onboard': return onboardCmd(flags);
+    case 'continue': return continueCmd(flags, _);
+    case 'status': return statusCmd(flags);
+    case 'run': return runCmd(flags, _);
+    case 'savepoint': return runCmd(flags, ['run', 'savepoint.sh', ..._.slice(1)]);
+    case 'initiative': return initiativeCmd(flags, _);
+    case 'start': return startCmd(flags, _);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
@@ -53,6 +64,12 @@ function archive(flags: Args['flags'], positionals: string[]): void {
   if (result.index) console.log(`index updated: ${result.index}`);
 }
 
+async function onboardCmd(flags: Args['flags']): Promise<void> {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  if (!existsSync(projectDir)) throw new Error(`Project dir not found: ${projectDir}`);
+  await runOnboard(projectDir);
+}
+
 async function resolveOptions(flags: Args['flags']): Promise<{ scope: Scope; projectDir: string; targetIds: string[] }> {
   const interactive = !flag(flags.yes);
   if (interactive && !process.stdin.isTTY) {
@@ -123,6 +140,22 @@ async function install(flags: Args['flags']): Promise<void> {
   });
   console.log(`\nOK mugiwara ${VERSION} installed (manifest: ${file})`);
   if (allNotes.length) console.log(`${allNotes.length} note(s) above may need attention.`);
+  // TASK 8: name exactly one next step, and state the active mode + enforce
+  // value since both change behaviour.
+  if (scope === 'project') {
+    const cfg = join(projectDir, '.mugiwara', 'config');
+    let mode = 'guided', enforce = 'block';
+    if (existsSync(cfg)) {
+      for (const line of readFileSync(cfg, 'utf8').split(/\r?\n/)) {
+        const [k, v] = line.split('=').map((s) => s.trim());
+        if (k === 'mode') mode = v;
+        if (k === 'enforce') enforce = v;
+      }
+    }
+    console.log(`\nNext: run \`mugiwara onboard\` to customise (mode=${mode}, enforce=${enforce} now).`);
+  } else {
+    console.log('\nNext: run `mugiwara onboard` in a project to write its .mugiwara/config.');
+  }
 }
 
 async function uninstall(flags: Args['flags']): Promise<void> {
@@ -150,6 +183,16 @@ async function uninstall(flags: Args['flags']): Promise<void> {
     if (!ok) { console.log('Aborted.'); return; }
   }
   const removed = removeInstalled(manifest, { dryRun: flag(flags.dryRun) });
+  // Un-merge anything we injected into files the user owns. These are
+  // deliberately absent from the manifest — deleting them would destroy the
+  // user's own configuration alongside ours.
+  for (const id of manifest.targets) {
+    const t = targets[id];
+    if (!t?.postUninstall) continue;
+    const post = t.postUninstall({ scope, projectDir, home, dryRun: flag(flags.dryRun) });
+    for (const f of post.changed) console.log(`   unwired mugiwara hooks from ${f}`);
+    for (const n of post.notes) console.log(`   note: ${n}`);
+  }
   if (!flag(flags.dryRun)) {
     if (scope === 'project') {
       const gi = removeProjectGitignore(projectDir);
@@ -192,6 +235,166 @@ function list(flags: Args['flags']): void {
   if (!found) console.log('No mugiwara installation found.');
 }
 
+/**
+ * `mugiwara continue [mission] [member]` — the deterministic half of resume.
+ *
+ * Selecting which mission/member to resume is a directory scan, not a judgement
+ * call, so it runs here instead of costing the host model a reasoning turn.
+ * Only the last step (verifying next_action against the plan) needs a model,
+ * and that happens after this prints.
+ *
+ * Exit codes: 0 = a single resume point was printed; 2 = ambiguous or absent,
+ * the caller must stop and let the user pick.
+ */
+function continueCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const [mission, member] = positionals.slice(1);
+  let entries = readContinue(projectDir);
+
+  // default to this actor's work; --all crosses actors on a shared checkout
+  if (!flag(flags.all)) {
+    const actor = gitActor(projectDir);
+    const mine = entries.filter((e) => e.actor === actor);
+    // an actor-less savepoint (older file, or git identity unset) is still the
+    // only thing on disk — showing nothing would look like "no missions"
+    if (mine.length) entries = mine;
+  }
+
+  const r = resolveContinue(entries, mission, member);
+  if (r.kind === 'resume') { console.log(formatResume(r.entry)); return; }
+
+  if (r.kind === 'none') {
+    console.log('No mission in flight. Start one with Flow 0 triage (mugiwara-orchestration).');
+  } else if (r.kind === 'missions') {
+    console.log(`${new Set(r.entries.map((e) => e.mission)).size} missions in flight:\n`);
+    console.log(formatTable(r.entries));
+    console.log('\nPick one: mugiwara continue <mission> [member]');
+  } else if (r.kind === 'members') {
+    console.log(`Mission "${r.mission}" has ${r.entries.length} members in flight:\n`);
+    console.log(formatTable(r.entries));
+    console.log(`\nPick one: mugiwara continue ${r.mission} <member>`);
+  } else if (r.kind === 'unknown-mission') {
+    console.error(`No in-flight mission "${r.mission}". Known: ${r.known.join(', ') || '(none)'}`);
+  } else {
+    console.error(`Mission "${r.mission}" has no member "${r.member}". Known: ${r.known.join(', ')}`);
+  }
+  process.exit(2);
+}
+
+/** `mugiwara status` — one screen of computed mission state, no model needed. */
+function statusCmd(flags: Args['flags']): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const states = readState(projectDir);
+  if (!states.length) { console.log('No mission state on disk.'); return; }
+  const actor = flag(flags.all) ? null : gitActor(projectDir);
+  const rows = actor ? (states.filter((s) => s.actor === actor).length ? states.filter((s) => s.actor === actor) : states) : states;
+  for (const s of rows) {
+    const scope = s.member ? ` [${s.member}]` : '';
+    console.log(`${s.mission}${scope}`);
+    console.log(`  flow ${s.flow} · ${s.tasks_done}/${s.tasks_total} tasks · lane ${s.lane}${s.lane_rose ? ' ⬆ ROSE' : ''}${s.lane_reason ? ` (${s.lane_reason})` : ''} · mode ${s.mode}`);
+    console.log(`  blockers ${s.blockers_open} · heal cycle ${s.heal_cycle}/${s.heal_max_cycles}${s.heal_halt ? ' — HALT' : ''} · files touched ${s.files_touched}`);
+    if (s.budget) console.log(`  tokens ${s.tokens_est}/${s.budget} (${s.budget_status})${s.delegate_due ? ' · delegate due' : ''}`);
+    console.log(`  branch ${s.branch} · updated ${s.updated_at}`);
+    if (s.evidence.length) console.log(`  evidence: ${s.evidence.join(', ')}`);
+  }
+}
+
+/** `mugiwara run <script.sh> [args]` — run a bundled harness script here. */
+function runCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const name = positionals[1];
+  if (!name) {
+    console.error(`usage: mugiwara run <script> [args...]\n  scripts: ${RUNNABLE.join(', ')}`);
+    process.exit(1);
+  }
+  const code = runScript(name, positionals.slice(2), projectDir);
+  if (code !== 0) process.exit(code);
+}
+
+/** `mugiwara initiative <status|conflict-check|set-status> <plan> [args]` — team sub-mission coordination. */
+function initiativeCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const sub = positionals[1];
+  if (!sub) {
+    console.error('usage: mugiwara initiative <status|conflict-check|set-status> <plan-file> [--id <id> --status <s>]');
+    process.exit(1);
+  }
+  const script = join(import.meta.dirname, '..', 'scripts', 'initiative.ts');
+  // initiative.ts is TypeScript — spawn `bun` (which strips types), not node,
+  // which only strips types on >=22.18. engines floor is >=20.11.
+  const bun = process.platform === 'win32' ? 'bun.exe' : 'bun';
+  const r = spawnSync(bun, [script, ...positionals.slice(1)], {
+    cwd: projectDir,
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (r.error) throw r.error;
+  if (r.status) process.exit(r.status);
+}
+
+/** `mugiwara start <mission> [member]` — begin a mission from its plan. */
+function startCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const mission = positionals[1];
+  if (!mission) {
+    console.error('usage: mugiwara start <mission> [member]');
+    process.exit(1);
+  }
+  // find the plan doc: plans/<mission>.md or plans/YYYY-MM-DD-<mission>.md
+  const plansDir = join(projectDir, '.mugiwara', 'plans');
+  let planFile = '';
+  if (existsSync(plansDir)) {
+    const bare = join(plansDir, `${mission}.md`);
+    if (existsSync(bare)) planFile = bare;
+    else {
+      const dated = readdirSync(plansDir).filter((f) => f.endsWith(`-${mission}.md`)).sort().pop();
+      if (dated) planFile = join(plansDir, dated);
+    }
+  }
+  if (!planFile) {
+    console.error(`mugiwara start: no plan found for "${mission}" in ${plansDir}`);
+    process.exit(1);
+  }
+  const plan = readFileSync(planFile, 'utf8');
+
+  // team plan = has a ## Sub-missions table; solo = none.
+  const subMatch = plan.match(/##\s*Sub-missions/i);
+  let member = positionals[2] ?? '';
+  if (subMatch && !member) {
+    // team: find the row whose Assignee matches this git actor
+    const actor = gitActor(projectDir);
+    const name = actor.split('<')[0].trim();
+    const rowRe = /^\|\s*([\w.-]+)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|/gm;
+    let m: RegExpExecArray | null;
+    let found = '';
+    while ((m = rowRe.exec(plan))) {
+      const assignee = m[3].trim();
+      if (assignee === name || assignee === actor) { found = m[1].trim(); break; }
+    }
+    if (!found) {
+      console.error(`mugiwara start: no sub-mission assigned to "${name}" in ${planFile}. Pass a member explicitly: mugiwara start ${mission} <member>`);
+      process.exit(1);
+    }
+    member = found;
+  }
+
+  // write the savepoint: mission [member] flow=0 mode=auto lane=full (start)
+  const code = runScript('savepoint.sh', [mission, member, '0', 'auto', 'full'], projectDir);
+  if (code !== 0) process.exit(code);
+
+  // team plan: mark the sub-mission in-progress in the plan (source of truth)
+  if (subMatch && member) {
+    const init = join(import.meta.dirname, '..', 'scripts', 'initiative.ts');
+    const bun = process.platform === 'win32' ? 'bun.exe' : 'bun';
+    const r = spawnSync(bun, [init, 'set-status', planFile, '--id', member, '--status', 'in-progress'], {
+      cwd: projectDir, stdio: 'inherit', env: process.env,
+    });
+    if (r.status) process.exit(r.status);
+  }
+
+  console.log(`mugiwara start: ${mission}${member ? ` [${member}]` : ''} begun at Flow 0. Resume anytime with: mugiwara continue ${mission}${member ? ` ${member}` : ''}`);
+}
+
 function help(): void {
   console.log(`mugiwara ${VERSION} — the Straw Hat crew for AI agents
 
@@ -203,6 +406,19 @@ Usage:
   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 onboard       run the zero-LLM onboarding wizard (writes .mugiwara/config)
+  mugiwara continue      list in-flight missions (exit 2 = pick one, nothing resumed)
+  mugiwara continue <m> [member]
+                         print the exact resume point for that mission/member
+  mugiwara status        computed mission state: wave, tasks, lane, blockers, budget
+  mugiwara run <script> [args...]
+                         run a bundled harness script here (${RUNNABLE.join(', ')})
+  mugiwara savepoint <mission> [member] [wave] [mode]
+                         shorthand for: mugiwara run savepoint.sh ...
+  mugiwara initiative <status|conflict-check|set-status> <plan> [args]
+                         team sub-mission coordination (status / conflict-check / set-status)
+  mugiwara start <mission> [member]
+                         begin a mission from its plan (solo, or team sub-mission by git actor)
   mugiwara --help        this help
   mugiwara --version     print version
 
@@ -214,6 +430,7 @@ Flags:
   --force                overwrite differing files (with backup)
   --dry-run              print actions without writing
   --check                with list: report missing files (health check)
+  --all                  with continue/status: every actor, not just yours
   --keep-logs            with reset: keep .mugiwara/logs (lessons ledger survives)`);
 }