@ionivetech/mugiwara 0.6.5 → 0.6.6

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)`);
 }
 

package/src/continue.ts

@@ -0,0 +1,243 @@
+// src/continue.ts
+// Deterministic resume-point reader. Powers `mugiwara continue` and
+// `mugiwara status` — pure fs + JSON, zero model judgement. The prose skills
+// used to describe this scan so the host model would perform it; that cost a
+// full reasoning turn to answer "what is in flight?". This is the same answer
+// in one process spawn.
+//
+// Reads what scripts/savepoint.sh writes:
+//   .mugiwara/continue/<mission>/state.json    (solo)
+//   .mugiwara/continue/<mission>/<member>.json (team)
+//   .mugiwara/state/<mission>/...              (same shape, more fields)
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/** Mission/member allowlist — identical to savepoint.sh and mission.ts. */
+const SAFE = /^[A-Za-z0-9._-]+$/;
+const isSafeKey = (s: string): boolean => SAFE.test(s) && !/^\.+$/.test(s);
+
+export type ContinueEntry = {
+  mission: string;
+  member: string | null;
+  actor: string;
+  branch: string;
+  flow: number;
+  mode: string;
+  tasks_done: number;
+  tasks_total: number;
+  lane: string;
+  next_action: string;
+  next_session_prompt: string;
+  updated_at: string;
+};
+
+export type StateEntry = ContinueEntry & {
+  lane_reason: string;
+  lane_rose: boolean;
+  lane_prev: string;
+  lane_peak: string;
+  blockers_open: number;
+  heal_cycle: number;
+  heal_max_cycles: number;
+  heal_halt: boolean;
+  delegate_threshold: number;
+  delegate_due: boolean;
+  tokens_est: number;
+  budget: number;
+  budget_status: string;
+  files_touched: number;
+  evidence: string[];
+};
+
+const num = (v: unknown): number => {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+};
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+/**
+ * Resolve the git actor exactly as scripts/savepoint.sh does:
+ * STATE_ACTOR → GIT_AUTHOR_NAME → "name <email>" → USER. A byte difference
+ * here silently filters every mission out of the listing.
+ */
+export function gitActor(cwd: string): string {
+  const env = (process.env.STATE_ACTOR ?? '').trim();
+  if (env) return env;
+  const author = (process.env.GIT_AUTHOR_NAME ?? '').trim();
+  if (author) return author;
+  const git = (args: string[]): string => {
+    try {
+      return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {
+      return '';
+    }
+  };
+  const name = git(['config', 'user.name']);
+  const email = git(['config', 'user.email']);
+  if (name && email) return `${name} <${email}>`;
+  // USERNAME is the Windows spelling of USER; savepoint.sh resolves the same
+  // chain, and the two must stay byte-identical or the actor filter drops rows.
+  return name || process.env.USER || process.env.USERNAME || '';
+}
+
+/** Read every JSON under `.mugiwara/<root>/<mission>/*.json`. Corrupt files are skipped. */
+function scan<T>(projectDir: string, root: string, map: (raw: Record<string, unknown>, member: string | null) => T): T[] {
+  const base = join(projectDir, '.mugiwara', root);
+  if (!existsSync(base)) return [];
+  const out: T[] = [];
+  const missions = readdirSync(base, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isSafeKey(e.name))
+    .map((e) => e.name)
+    .sort();
+  for (const mission of missions) {
+    const dir = join(base, mission);
+    for (const f of readdirSync(dir).filter((n) => n.endsWith('.json')).sort()) {
+      // state.json is the solo (member-less) file; <member>.json is a team member
+      const stem = f.slice(0, -'.json'.length);
+      const member = stem === 'state' ? null : stem;
+      if (member !== null && !isSafeKey(member)) continue;
+      try {
+        const raw = JSON.parse(readFileSync(join(dir, f), 'utf8')) as Record<string, unknown>;
+        // trust the path over the file body: a mission field that disagrees
+        // with its own directory is a corrupt or hand-edited file
+        if (text(raw.mission) !== mission) continue;
+        out.push(map(raw, member));
+      } catch {
+        // corrupt savepoint — skip, never crash the listing
+      }
+    }
+  }
+  return out;
+}
+
+export function readContinue(projectDir: string): ContinueEntry[] {
+  return scan(projectDir, 'continue', (r, member) => ({
+    mission: text(r.mission),
+    member,
+    actor: text(r.actor),
+    branch: text(r.branch),
+    flow: num(r.flow ?? r.wave),
+    mode: text(r.mode) || 'guided',
+    tasks_done: num(r.tasks_done),
+    tasks_total: num(r.tasks_total),
+    lane: text(r.lane) || 'direct',
+    next_action: text(r.next_action),
+    next_session_prompt: text(r.next_session_prompt),
+    updated_at: text(r.updated_at),
+  }));
+}
+
+export function readState(projectDir: string): StateEntry[] {
+  return scan(projectDir, 'state', (r, member) => {
+    const tasks = (r.tasks ?? {}) as Record<string, unknown>;
+    return {
+      mission: text(r.mission),
+      member,
+      actor: text(r.actor),
+      branch: text(r.branch),
+      flow: num(r.flow ?? r.wave),
+      mode: text(r.mode) || 'guided',
+      tasks_done: num(tasks.done),
+      tasks_total: num(tasks.total),
+      lane: text(r.lane) || 'direct',
+      lane_reason: text(r.lane_reason),
+      lane_rose: r.lane_rose === true,
+      lane_prev: text(r.lane_prev),
+      lane_peak: text(r.lane_peak),
+      next_action: '',
+      next_session_prompt: '',
+      updated_at: text(r.updated_at),
+      blockers_open: num(r.blockers_open),
+      heal_cycle: num(r.heal_cycle),
+      heal_max_cycles: num(r.heal_max_cycles) || 3,
+      heal_halt: r.heal_halt === true,
+      delegate_threshold: num(r.delegate_threshold) || 60,
+      delegate_due: r.delegate_due === true,
+      tokens_est: num(r.tokens_est),
+      budget: num(r.budget),
+      budget_status: text(r.budget_status) || 'ok',
+      files_touched: num(r.files_touched),
+      evidence: Array.isArray(r.evidence) ? r.evidence.map(text).filter(Boolean) : [],
+    };
+  });
+}
+
+export type Resolution =
+  | { kind: 'none' }
+  | { kind: 'missions'; entries: ContinueEntry[] }
+  | { kind: 'members'; mission: string; entries: ContinueEntry[] }
+  | { kind: 'unknown-mission'; mission: string; known: string[] }
+  | { kind: 'unknown-member'; mission: string; member: string; known: string[] }
+  | { kind: 'resume'; entry: ContinueEntry };
+
+/**
+ * The three command forms, decided from disk alone:
+ *   (none)            → list every in-flight mission
+ *   <mission>         → solo resumes; team lists its members
+ *   <mission> <member>→ resume that member
+ *
+ * Solo-vs-team needs no plan-doc parse: savepoint writes `state.json` with a
+ * null member for solo and `<member>.json` per team member.
+ */
+export function resolveContinue(entries: ContinueEntry[], mission?: string, member?: string): Resolution {
+  if (!entries.length) return { kind: 'none' };
+
+  if (!mission) {
+    const missions = [...new Set(entries.map((e) => e.mission))];
+    if (missions.length === 1) return resolveContinue(entries, missions[0], member);
+    return { kind: 'missions', entries };
+  }
+
+  const inMission = entries.filter((e) => e.mission === mission);
+  if (!inMission.length) {
+    return { kind: 'unknown-mission', mission, known: [...new Set(entries.map((e) => e.mission))] };
+  }
+
+  if (member) {
+    const hit = inMission.find((e) => e.member === member);
+    if (!hit) {
+      return {
+        kind: 'unknown-member',
+        mission,
+        member,
+        known: inMission.map((e) => e.member ?? '(solo)'),
+      };
+    }
+    return { kind: 'resume', entry: hit };
+  }
+
+  const solo = inMission.find((e) => e.member === null);
+  // a solo file resumes directly; anything else needs the member picked, and
+  // is never guessed — resuming the wrong member's work is unrecoverable
+  if (solo && inMission.length === 1) return { kind: 'resume', entry: solo };
+  return { kind: 'members', mission, entries: inMission };
+}
+
+function pad(s: string, n: number): string {
+  return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+
+/** Fixed-width table — the whole point is that the host prints this verbatim. */
+export function formatTable(entries: ContinueEntry[]): string {
+  const rows = entries.map((e) => [
+    e.mission,
+    e.member ?? '—',
+    String(e.flow),
+    `${e.tasks_done}/${e.tasks_total}`,
+    e.lane,
+    e.mode,
+  ]);
+  const head = ['MISSION', 'MEMBER', 'FLOW', 'TASKS', 'LANE', 'MODE'];
+  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const line = (cells: string[]): string =>
+    '  ' + cells.map((c, i) => pad(c, widths[i])).join('  ').trimEnd();
+  return [line(head), ...rows.map(line)].join('\n');
+}
+
+/** The single resume line the mugiwara-resume skill contracts for. */
+export function formatResume(e: ContinueEntry): string {
+  const scope = e.member ? ` [${e.member}]` : '';
+  const next = e.next_session_prompt || '(no next_session_prompt recorded)';
+  return `Resumed: ${e.mission}${scope}, Flow ${e.flow}, ${e.tasks_done}/${e.tasks_total} tasks — next_action: ${e.next_action} — run: ${next}`;
+}

package/src/installer.ts

@@ -44,6 +44,15 @@ export interface Target {
   transformSkillFull?(data: FrontmatterData, body: string): TransformOut | null;
   transformAgentFull?(data: FrontmatterData, body: string): TransformOut | null;
   postInstall?(opts: { scope: Scope; projectDir: string; home: string; dryRun: boolean; files: string[] }): { written: string[]; notes: string[] };
+  /**
+   * Undo anything postInstall did to a file mugiwara does not own.
+   *
+   * Files listed in the manifest are deleted wholesale on uninstall, so a
+   * shared file we merely EDITED (settings.json) must never be reported as
+   * written — deleting it destroys the user's own configuration. Such files are
+   * un-merged here instead.
+   */
+  postUninstall?(opts: { scope: Scope; projectDir: string; home: string; dryRun: boolean }): { changed: string[]; notes: string[] };
 }
 
 export const CONTENT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'content');
@@ -151,6 +160,36 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
     result.written.push(...post.written);
     result.notes.push(...post.notes);
   }
+
+  // TASK 8: a fresh install must be immediately usable — write a default
+  // .mugiwara/config (the same defaults `mugiwara onboard` would write) so no
+  // key silently falls back. Only for project scope; global installs don't own
+  // a project config. Never overwrite an existing config.
+  if (scope === 'project') {
+    const configPath = join(projectDir, '.mugiwara', 'config');
+    // lstat, not existsSync: a pre-created symlinked config must not be
+    // followed and overwritten (TOCTOU / symlink defense-in-depth).
+    let configExists = false;
+    try { configExists = lstatSync(configPath).isFile() || lstatSync(configPath).isSymbolicLink(); } catch { configExists = false; }
+    if (!configExists) {
+      const body = [
+        'mode=guided',
+        'branch=feature/{type}-{issue}-{slug}',
+        'commit=conventional',
+        'auto_commit=on',
+        'coverage_new=90',
+        'coverage_modified=80',
+        'review_depth=full',
+        'quality_depth=full',
+        'delegate_threshold=60',
+        'heal_max_cycles=3',
+        'verbosity=normal',
+      ].join('\n') + '\n';
+      if (!dryRun) { mkdirSync(dirname(configPath), { recursive: true }); writeFileSync(configPath, body); }
+      result.written.push(configPath);
+      result.notes.push(`default config written: ${configPath} (run \`mugiwara onboard\` to customise)`);
+    }
+  }
   return result;
 }