@ionivetech/mugiwara 0.6.2 → 0.6.4

package/scripts/savepoint.sh

@@ -1,12 +1,34 @@
 #!/usr/bin/env bash
-# scripts/savepoint.sh — write .mugiwara/state.json at every wave boundary.
-# Computed from git + file counts; zero model judgement.
+# scripts/savepoint.sh — write .mugiwara/state/<mission>/<member>.json at every
+# wave boundary. Computed from git + file counts; zero model judgement.
+# Identity is (mission, member), never branch. Solo = member empty → the file
+# is named state.json. Usage:
+#   savepoint.sh <mission> [member] [wave] [mode]
 set -u
 
 die() { echo "savepoint: $*" >&2; exit 1; }
 
 MUGIWARA_DIR="${MUGIWARA_DIR:-.mugiwara}"
 
+# shared path patterns — single source of truth (D3)
+# shellcheck source=scripts/lib/patterns.sh
+source "$(dirname "$0")/lib/patterns.sh"
+# shared lane budgets — single source of truth (D5), validated by lane-base.ts
+# shellcheck source=scripts/lib/lane-base.sh
+source "$(dirname "$0")/lib/lane-base.sh"
+
+# lane ordering: direct < lean < standard < full < spike (spike resizes, not a rise)
+lane_rank() {
+  case "$1" in
+    direct) echo 0 ;;
+    lean) echo 1 ;;
+    standard) echo 2 ;;
+    full) echo 3 ;;
+    spike) echo 4 ;;
+    *) echo 0 ;;
+  esac
+}
+
 # --- git identity for actor attribution ---
 # Resolve once from repo git config; used when no actor is passed explicitly.
 # GIT_AUTHOR_NAME is an env var usually unset — falling through to $USER
@@ -15,24 +37,18 @@ GIT_NAME="$(git config user.name 2>/dev/null || true)"
 GIT_EMAIL="$(git config user.email 2>/dev/null || true)"
 if [ -n "$GIT_NAME" ] && [ -n "$GIT_EMAIL" ]; then GIT_ID="$GIT_NAME <$GIT_EMAIL>"; else GIT_ID="$GIT_NAME"; fi
 
-# --- parse mission args ---
-# --branch flag must parse FIRST — it shifts positionals
-BRANCH_MODE=0
-if [ "${1:-}" = "--branch" ]; then
-  BRANCH_MODE=1
-  shift
-  MISSION="${1:-${STATE_MISSION:-}}"
-  ACTOR="${2:-${STATE_ACTOR:-${GIT_AUTHOR_NAME:-${GIT_ID:-${USER:-}}}}}"
-  BRANCH="${3:-$(git branch --show-current 2>/dev/null || echo 'unknown')}"
-  WAVE="${4:-${STATE_WAVE:-1}}"
-  MODE="${5:-${STATE_MODE:-guided}}"
-else
-  MISSION="${1:-${STATE_MISSION:-}}"
-  ACTOR="${2:-${STATE_ACTOR:-${GIT_AUTHOR_NAME:-${GIT_ID:-${USER:-}}}}}"
-  BRANCH="${3:-$(git branch --show-current 2>/dev/null || echo 'unknown')}"
-  WAVE="${4:-${STATE_WAVE:-1}}"
-  MODE="${5:-${STATE_MODE:-guided}}"
-fi
+# --- parse mission args: <mission> [member] [wave] [mode] ---
+MISSION="${1:-${STATE_MISSION:-}}"
+MEMBER="${2:-${STATE_MEMBER:-}}"
+WAVE="${3:-${STATE_WAVE:-1}}"
+MODE="${4:-${STATE_MODE:-guided}}"
+ACTOR="${STATE_ACTOR:-${GIT_AUTHOR_NAME:-${GIT_ID:-${USER:-}}}}"
+BRANCH="$(git branch --show-current 2>/dev/null || echo 'unknown')"
+
+# treat the legacy empty-actor placeholder '""' as "no member" (solo). The old
+# interface used '""' for the actor slot; the new (mission, member) interface
+# uses an empty arg. Accept both so callers need not know which one.
+if [ "$MEMBER" = '""' ]; then MEMBER=""; fi
 
 # mission allowlist — MISSION feeds paths + sed + node argv; traversal or
 # sed metacharacters must not reach filesystem operations
@@ -45,15 +61,32 @@ if [[ "$MISSION" =~ ^\.+$ ]]; then
   die "invalid mission name \"$MISSION\" (allowlist: [a-zA-Z0-9._-], not a dot-path)"
 fi
 
-# per-branch state file when --branch used
-BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
-if [ "$BRANCH_MODE" -eq 1 ]; then
-  STATE_FILE="$MUGIWARA_DIR/state-${BRANCH_SLUG}.json"
+# member allowlist — MEMBER feeds a per-member file name; same rules as MISSION.
+case "$MEMBER" in
+  *[!a-zA-Z0-9._-]*) die "invalid member name \"$MEMBER\" (allowlist: [a-zA-Z0-9._-])" ;;
+esac
+if [[ "$MEMBER" =~ ^\.+$ ]]; then
+  die "invalid member name \"$MEMBER\" (allowlist: [a-zA-Z0-9._-], not a dot-path)"
+fi
+
+# BRANCH_SLUG sanitized to [A-Za-z0-9._-] — it feeds the continue branch field;
+# a newline/control char in BRANCH would corrupt the JSON (F5). Dropping illegal
+# chars is safe: slugs are keys, not content. Dot-only slugs emptied
+# (BSD/macOS-safe: no \+ BRE).
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-' | tr -cd 'A-Za-z0-9._-' | sed 's/^\.\{1,\}$//' )
+
+# state + continue live per (mission, member). Solo (member empty) → state.json.
+STATE_DIR="$MUGIWARA_DIR/state/$MISSION"
+CONTINUE_DIR="$MUGIWARA_DIR/continue/$MISSION"
+if [ -n "$MEMBER" ]; then
+  STATE_FILE="$STATE_DIR/$MEMBER.json"
+  CONTINUE_FILE="$CONTINUE_DIR/$MEMBER.json"
 else
-  STATE_FILE="$MUGIWARA_DIR/state.json"
+  STATE_FILE="$STATE_DIR/state.json"
+  CONTINUE_FILE="$CONTINUE_DIR/state.json"
 fi
 
-[ -z "$MISSION" ] && die "usage: savepoint.sh <mission> [actor] [branch] [wave] [mode]"
+[ -z "$MISSION" ] && die "usage: savepoint.sh <mission> [member] [wave] [mode]"
 [ -d .git ] || die "not a git repository"
 
 # --- computed fields ---
@@ -63,17 +96,23 @@ HEAD_SHA=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
 CHANGED_FILES=$(git diff --name-only "$BASE_SHA"..HEAD 2>/dev/null || git diff --name-only --cached 2>/dev/null || true)
 FILES_TOUCHED=$( [ -n "$CHANGED_FILES" ] && echo "$CHANGED_FILES" | wc -l | tr -d ' ' || echo 0 )
 
+LOC_INS=0
+LOC_DEL=0
 LOC_DELTA=0
+LOC_CHURN=0
 if [ "$BASE_SHA" != "unknown" ]; then
   STAT=$(git diff --shortstat "$BASE_SHA"..HEAD 2>/dev/null || echo "")
   INS=$(echo "$STAT" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo 0)
   DEL=$(echo "$STAT" | grep -oE '[0-9]+ deletion'  | grep -oE '[0-9]+' || echo 0)
-  LOC_DELTA=$(( ${INS:-0} - ${DEL:-0} ))
+  LOC_INS=$(( ${INS:-0} + 0 ))
+  LOC_DEL=$(( ${DEL:-0} + 0 ))
+  LOC_DELTA=$(( LOC_INS - LOC_DEL ))
+  # churn is insertion+deletion — refactors and deletions are work too (D4)
+  LOC_CHURN=$(( LOC_INS + LOC_DEL ))
 fi
 [ -z "$LOC_DELTA" ] && LOC_DELTA=0
 
-SENSITIVE_PATTERNS="auth/|payment/|billing/|crypto/|secrets/|\.env$|config/.*key|migration/|\.sql$|schema\.|\.prisma$|\.terraform|\.tf$"
-SENSITIVE_PATHS=$(echo "$CHANGED_FILES" | grep -E "$SENSITIVE_PATTERNS" 2>/dev/null | tr '\n' ',' | sed 's/,$//' || true)
+SENSITIVE_PATHS=$(echo "$CHANGED_FILES" | grep -E "$SENSITIVE_PATS" 2>/dev/null | tr '\n' ',' | sed 's/,$//' || true)
 
 LANE="direct"
 LANE_REASON=""
@@ -109,7 +148,6 @@ fi
 # path-weighted sizing (mirrors lane.sh): docs-only changes outside the product
 # surface never escalate to full from file count alone; sensitive-path
 # escalation above still wins.
-PRODUCT_PAT="^content/|^src/|^scripts/|^test/|^hooks/|^\.opencode/|^\.claude/|^evals/"
 if [ "$LANE" = "full" ] && [ -z "$SENSITIVE_PATHS" ] && [ -n "$CHANGED_FILES" ]; then
   CODE_COUNT=$(echo "$CHANGED_FILES" | grep -E "$PRODUCT_PAT" 2>/dev/null | grep -c . || true)
   if [ -z "$CODE_COUNT" ] || [ "$CODE_COUNT" -eq 0 ] 2>/dev/null; then
@@ -119,6 +157,42 @@ if [ "$LANE" = "full" ] && [ -z "$SENSITIVE_PATHS" ] && [ -n "$CHANGED_FILES" ];
   fi
 fi
 
+# --- lane-rise compare (F9) + monotonic clamp (D2): read previous state ---
+# Clamp runs here — before LANE_BASE/BUDGET — so tokens and budget follow the
+# held lane, never the raw shrunken one.
+LANE_PREV=""
+LANE_PEAK=""
+LANE_ROSE=false
+PREV_MISSION=""
+if [ -f "$STATE_FILE" ]; then
+  PREV_JSON=$(node -e "try{const fs=require('fs');const s=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(JSON.stringify({mission:s.mission||'',lane:s.lane||'',peak:s.lane_peak||''}))}catch(e){process.stdout.write('{}')}" "$STATE_FILE" 2>/dev/null || true)
+  PREV_MISSION=$(echo "$PREV_JSON" | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{process.stdout.write(JSON.parse(d).mission||'')}catch(e){process.stdout.write('')}})" 2>/dev/null || true)
+  LANE_PREV=$(echo "$PREV_JSON" | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{process.stdout.write(JSON.parse(d).lane||'')}catch(e){process.stdout.write('')}})" 2>/dev/null || true)
+  LANE_PEAK=$(echo "$PREV_JSON" | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{process.stdout.write(JSON.parse(d).peak||'')}catch(e){process.stdout.write('')}})" 2>/dev/null || true)
+fi
+# fresh mission resets the clamp: a different mission in state.json is a new
+# run, not a lane drop — no carry-over of peak or prev (case 10).
+if [ -n "$PREV_MISSION" ] && [ "$PREV_MISSION" != "$MISSION" ]; then
+  LANE_PREV=""
+  LANE_PEAK=""
+fi
+# monotonic clamp: never drop below the previous peak; spike is a resize, not a rise.
+if [ -n "$LANE_PEAK" ] && [ "$LANE_PEAK" != "spike" ] && [ "$(lane_rank "$LANE")" -lt "$(lane_rank "$LANE_PEAK")" ]; then
+  LANE="$LANE_PEAK"
+  LANE_REASON="$LANE_REASON (held at peak $LANE — clamp D2)"
+fi
+if [ -z "$LANE_PEAK" ] || [ "$LANE_PEAK" = "spike" ]; then
+  LANE_PEAK="$LANE"
+elif [ "$(lane_rank "$LANE")" -gt "$(lane_rank "$LANE_PEAK")" ]; then
+  LANE_PEAK="$LANE"
+fi
+if [ -n "$LANE_PREV" ] && [ "$LANE_PREV" != "$LANE" ]; then
+  case "$LANE_PREV:$LANE" in
+    direct:lean|direct:standard|direct:full|lean:standard|lean:full|standard:full) LANE_ROSE=true ;;
+    *) LANE_ROSE=false ;;
+  esac
+fi
+
 # task counts from plan doc — plan is written date-prefixed (plans/YYYY-MM-DD-<mission>.md)
 # or bare (plans/<mission>.md); glob both, first match wins.
 PLAN_FILE=$(ls "$MUGIWARA_DIR"/plans/${MISSION}.md "$MUGIWARA_DIR"/plans/*-${MISSION}.md 2>/dev/null | head -1 || true)
@@ -168,17 +242,18 @@ fi
 
 # tokens proxy (F7): deterministic estimate when the harness does not report
 # real usage. Monotonic beats precise — LANE_BASE stands in for the skills
-# loaded this lane; loc_delta and written-artifact words scale with growth.
+# loaded this lane (measured from content, validated by scripts/lane-base.ts);
+# loc_churn and written-artifact words scale with growth.
 # MUGIWARA_TOKENS overrides as the reported value.
 LANE_BASE=0
 case "$LANE" in
-  lean) LANE_BASE=1500 ;;
-  standard) LANE_BASE=4000 ;;
-  full) LANE_BASE=9000 ;;
-  spike) LANE_BASE=1000 ;;
+  lean) LANE_BASE=$LANE_BASE_lean ;;
+  standard) LANE_BASE=$LANE_BASE_standard ;;
+  full) LANE_BASE=$LANE_BASE_full ;;
+  spike) LANE_BASE=$LANE_BASE_spike ;;
 esac
 DOC_WORDS=$(cat "$MUGIWARA_DIR"/results/${MISSION}/*.md "$MUGIWARA_DIR"/plans/${MISSION}.md "$MUGIWARA_DIR"/plans/*-${MISSION}.md "$MUGIWARA_DIR"/spec/${MISSION}.md "$MUGIWARA_DIR"/spec/*-${MISSION}.md "$MUGIWARA_DIR"/logs/${MISSION}.md "$MUGIWARA_DIR"/logs/*-${MISSION}.md 2>/dev/null | wc -w | tr -d ' ')
-LOC_TOKENS=$(( LOC_DELTA > 0 ? LOC_DELTA * 12 : 0 ))
+LOC_TOKENS=$(( LOC_CHURN * 12 ))
 TOKENS_SOURCE="computed"
 TOKENS_EST=$(( LANE_BASE + DOC_WORDS * 135 / 100 + LOC_TOKENS ))
 if [ -n "${MUGIWARA_TOKENS:-}" ]; then
@@ -189,10 +264,10 @@ fi
 # budget per lane
 BUDGET=0
 case "$LANE" in
-  lean) BUDGET=4000 ;;
-  standard) BUDGET=10000 ;;
-  full) BUDGET=20000 ;;
-  spike) BUDGET=3000 ;;
+  lean) BUDGET=$BUDGET_lean ;;
+  standard) BUDGET=$BUDGET_standard ;;
+  full) BUDGET=$BUDGET_full ;;
+  spike) BUDGET=$BUDGET_spike ;;
   *) BUDGET=0 ;;
 esac
 
@@ -206,30 +281,18 @@ elif [ "$BUDGET" -gt 0 ] && [ "$TOKENS_EST" -ge "$WARN_AT" ] 2>/dev/null; then
   STATUS="warn"
 fi
 
-mkdir -p "$MUGIWARA_DIR"
-
-# --- lane-rise compare (F9): read previous state, flag escalation ---
-LANE_PREV=""
-LANE_ROSE=false
-if [ -f "$STATE_FILE" ]; then
-  LANE_PREV=$(node -e "try{const s=require(process.argv[1]);process.stdout.write(s.lane||'')}catch(e){process.stdout.write('')}" "$STATE_FILE" 2>/dev/null || true)
-  if [ -n "$LANE_PREV" ] && [ "$LANE_PREV" != "$LANE" ]; then
-    # lane order: direct < lean < standard < full < spike (spike resizes, not a rise)
-    case "$LANE_PREV:$LANE" in
-      direct:lean|direct:standard|direct:full|lean:standard|lean:full|standard:full) LANE_ROSE=true ;;
-      *) LANE_ROSE=false ;;
-    esac
-  fi
-fi
+mkdir -p "$MUGIWARA_DIR/state/$MISSION" "$MUGIWARA_DIR/continue/$MISSION"
 
 node -e "
 const data = {
   mission: process.argv[1],
+  member: process.argv[31] || null,
   actor: process.argv[2],
   branch: process.argv[3],
   lane: process.argv[4],
   lane_reason: process.argv[5],
   lane_prev: process.argv[24] || null,
+  lane_peak: process.argv[27] || null,
   lane_rose: process.argv[25] === 'true',
   wave: parseInt(process.argv[6], 10),
   mode: process.argv[7],
@@ -237,6 +300,9 @@ const data = {
   head_sha: process.argv[9],
   files_touched: parseInt(process.argv[10], 10),
   loc_delta: parseInt(process.argv[11], 10),
+  loc_ins: parseInt(process.argv[28], 10) || 0,
+  loc_del: parseInt(process.argv[29], 10) || 0,
+  loc_churn: parseInt(process.argv[30], 10) || 0,
   sensitive_paths: process.argv[12] ? process.argv[12].split(',').filter(Boolean) : [],
   tasks: { done: parseInt(process.argv[13], 10), total: parseInt(process.argv[14], 10) },
   blockers_open: parseInt(process.argv[15], 10),
@@ -257,9 +323,57 @@ require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\
   "$BLOCKERS_OPEN" "$HEAL_CYCLE" "$TOKENS_EST" "$BUDGET" \
   "$STATUS" "$SKILL_VERSION" "$EVIDENCE" \
   "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-  "$STATE_FILE" "$LANE_PREV" "$LANE_ROSE" "$TOKENS_SOURCE"
+  "$STATE_FILE" "$LANE_PREV" "$LANE_ROSE" "$TOKENS_SOURCE" "$LANE_PEAK" \
+  "$LOC_INS" "$LOC_DEL" "$LOC_CHURN" "$MEMBER"
 
 if [ "$LANE_ROSE" = true ]; then
   echo "⚠ LANE ROSE: $LANE_PREV → $LANE ($LANE_REASON) — escalate per check-in protocol"
 fi
+
+# --- continue/<mission>/<member>.json (D10): machine-written resume point ---
+# Written alongside state.json so an interrupted session (step-limit truncation,
+# crash, new session) can resume without human recall. Same trust as state.json:
+# computed fields, never model judgement. The resume skill treats it as data to
+# verify against the plan/todos, never verbatim instructions.
+# Scoped by (mission, member) like state.json — solo writes state.json, team
+# writes <member>.json, so parallel members never clobber each other. The
+# crew-written next_session_prompt line is preserved across savepoints.
+if [ -n "$MISSION" ]; then
+  NEXT_SESSION_PROMPT=""
+  if [ -f "$CONTINUE_FILE" ]; then
+    NEXT_SESSION_PROMPT=$(node -e "try{const s=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));process.stdout.write(s.next_session_prompt||'')}catch(e){process.stdout.write('')}" "$CONTINUE_FILE" 2>/dev/null || true)
+  fi
+  # N2: every field echoed into continue is validated first. MISSION + MEMBER
+  # are allowlisted upstream; WAVE numeric, MODE enum, BRANCH slug-sanitized.
+  CONT_WAVE=$(echo "$WAVE" | tr -cd '0-9')
+  case "$MODE" in
+    guided|semi|auto) CONT_MODE="$MODE" ;;
+    *) CONT_MODE="guided" ;;
+  esac
+  CONT_BRANCH="${BRANCH_SLUG:-unknown}"
+  node -e "
+  const fs = require('fs');
+  const data = {
+    mission: process.argv[1],
+    member: process.argv[2] || null,
+    actor: process.argv[13] || '',
+    branch: process.argv[3],
+    wave: parseInt(process.argv[4], 10) || 0,
+    mode: process.argv[5],
+    tasks_done: parseInt(process.argv[6], 10) || 0,
+    tasks_total: parseInt(process.argv[7], 10) || 0,
+    lane: process.argv[8],
+    lane_prev: process.argv[9] || null,
+    updated_at: process.argv[10],
+    next_action: 'verify this wave against the plan, then continue per plan (next wave or closure)'
+  };
+  try { data.next_session_prompt = JSON.parse(fs.readFileSync(process.argv[12],'utf8')).next_session_prompt || ''; } catch (e) { data.next_session_prompt = ''; }
+  fs.writeFileSync(process.argv[11], JSON.stringify(data, null, 2) + '\n');
+  " \
+    "$MISSION" "$MEMBER" "$CONT_BRANCH" "$CONT_WAVE" "$CONT_MODE" \
+    "$TASKS_DONE" "$TASKS_TOTAL" "$LANE" "$LANE_PREV" \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$CONTINUE_FILE" "$CONTINUE_FILE" "$ACTOR"
+fi
+
 echo "✓ savepoint written: $STATE_FILE (lane=$LANE, wave=$WAVE, files=$FILES_TOUCHED)"

package/scripts/setup-fixtures.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+// scripts/setup-fixtures.ts — materialize test/fixtures/*.json into real git
+// repos in a temp dir. Each fixture = a JSON manifest with base/branch file
+// trees. The script writes the base tree on the trunk branch, creates the
+// feature branch, applies the branch tree, and commits. Used by tests to get
+// a deterministic repo per scenario. Never touches the main repo's .git.
+//
+// Usage:
+//   bun scripts/setup-fixtures.ts <fixture> <targetDir>
+//   bun scripts/setup-fixtures.ts --list
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const fixturesDir = join(import.meta.dirname, '..', 'test', 'fixtures');
+
+function fixtureNames(): string[] {
+  return readdirSync(fixturesDir).filter(f => f.endsWith('.json')).map(f => f.replace(/\.json$/, ''));
+}
+
+if (process.argv[2] === '--list') {
+  console.log(fixtureNames().join('\n'));
+  process.exit(0);
+}
+
+const name = process.argv[2];
+const target = process.argv[3];
+if (!name || !target) {
+  console.error('usage: bun scripts/setup-fixtures.ts <fixture> <targetDir>');
+  process.exit(1);
+}
+
+type Fixture = {
+  name: string;
+  baseBranch: string;
+  base: Record<string, string>;
+  branch: Record<string, string>;
+  binary?: string[];
+  gitInit?: boolean;
+  note?: string;
+};
+
+const file = join(fixturesDir, name + '.json');
+if (!existsSync(file)) {
+  console.error(`fixture not found: ${name} (have: ${fixtureNames().join(', ')})`);
+  process.exit(1);
+}
+const fx = JSON.parse(readFileSync(file, 'utf8')) as Fixture;
+
+// target must be a fresh empty dir
+if (existsSync(target)) rmSync(target, { recursive: true, force: true });
+mkdirSync(target, { recursive: true });
+
+if (fx.gitInit === false) {
+  // no-git fixture: just an empty dir with one file, no .git ever created
+  mkdirSync(join(target, 'src'), { recursive: true });
+  writeFileSync(join(target, 'src', 'main.ts'), 'export const main = () => 1;\n');
+  console.log(`fixture ${name}: materialized (no .git)`);
+  process.exit(0);
+}
+
+const writeTree = (tree: Record<string, string>) => {
+  for (const [path, content] of Object.entries(tree)) {
+    const full = join(target, path);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+};
+
+// names feed unquoted git branch args — validate before interpolation (F3).
+// Fixture files are repo-owned, but `name` is a CLI arg and `trunk` comes from
+// fixture JSON; both must be safe git ref names.
+const SAFE_REF = /^[A-Za-z0-9._/-]+$/;
+if (!SAFE_REF.test(name) || !SAFE_REF.test(fx.baseBranch || '')) {
+  console.error(`fixture ${name}: unsafe branch name rejected`);
+  process.exit(1);
+}
+
+execSync('git init -q', { cwd: target });
+execSync('git config user.email test@test.com && git config user.name Test', { cwd: target });
+
+const trunk = fx.baseBranch || 'main';
+// branch named after trunk if trunk isn't main (so savepoint base-resolve paths differ)
+execSync(`git checkout -q -b ${trunk}`, { cwd: target });
+
+// base commit on trunk
+writeTree(fx.base);
+for (const rel of fx.binary ?? []) {
+  if (fx.base[rel]) writeFileSync(join(target, rel), fx.base[rel]);
+}
+execSync('git add -A && git commit -q -m base', { cwd: target });
+
+// feature branch applies the branch tree (files removed from base not in
+// branch get deleted; contents updated; new files added)
+execSync(`git checkout -q -b feat-${fx.name}`, { cwd: target });
+for (const rel of Object.keys(fx.base)) {
+  if (!(rel in fx.branch)) {
+    execSync(`git rm -q --ignore-unmatch "${rel}"`, { cwd: target });
+  }
+}
+writeTree(fx.branch);
+for (const rel of fx.binary ?? []) {
+  if (fx.branch[rel]) writeFileSync(join(target, rel), fx.branch[rel]);
+}
+execSync('git add -A && git commit -q -m wip', { cwd: target });
+
+console.log(`fixture ${name}: materialized at ${target} (trunk=${trunk}, branch=feat-${fx.name})`);

package/scripts/validate-content.ts

@@ -319,5 +319,66 @@ const agentsDoc = join(docsDir, 'concepts', 'agents.md');
   if (docErrors === 0) console.log('✓ docs in sync with content/');
 }
 
+// --- doc-integrity check: documented thresholds must match source constants ---
+// Docs are claims; a claim that drifts from the source is a lie. LANE_BASE +
+// BUDGET live in scripts/lib/lane-base.sh (validated by lane-base.ts); the
+// cost docs must cite the same numbers. Evidence logs carry an exit code /
+// verdict claim — a test must back it (lane-integrity cases 22-24).
+const integrityArg = process.argv.indexOf('--check-doc-integrity');
+if (integrityArg !== -1) {
+  const src = join(import.meta.dirname, '..', 'scripts', 'lib', 'lane-base.sh');
+  if (!existsSync(src)) {
+    errors.push('doc-integrity: scripts/lib/lane-base.sh not found — cannot verify thresholds');
+  } else {
+    const constants = readFileSync(src, 'utf8');
+    const docs = ['docs/concepts/cost.md', 'docs/concepts/lanes.md', 'README.md'];
+    const expected: [string, string][] = [
+      ['lean', '7,000'], ['standard', '13,000'], ['full', '23,000'],
+      ['lean', '12,000'], ['standard', '25,000'], ['full', '50,000'],
+    ];
+    for (const doc of docs) {
+      const p = join(import.meta.dirname, '..', doc);
+      if (!existsSync(p)) { errors.push(`doc-integrity: ${doc} not found`); continue; }
+      const text = readFileSync(p, 'utf8');
+      for (const [lane, num] of expected) {
+        // each doc must cite the budget/LANE_BASE number for that lane; accept
+        // both the comma form (7,000) and the k-shorthand (7k / ~7k)
+        const compact = num.replace(',', '').replace(/0+$/, '');
+        const kForm = /^(\d+)000$/.exec(num);
+        const variants = [num, compact, ...(kForm ? [`${kForm[1]}k`, `~${kForm[1]}k`] : [])];
+        if (!variants.some(v => text.includes(v))) {
+          errors.push(`doc-integrity: ${doc} missing ${lane} threshold ${num} (source: ${src})`);
+        }
+      }
+      // warn/stop are 1.5x / 3x of BUDGET (code: WARN_AT=BUDGET*3/2,
+      // STOP_AT=BUDGET*3) — presence is not enough, the arithmetic must be
+      // right. A doc claiming 1.5x/3x of LANE_BASE is the exact lie this gate
+      // exists to catch. Checked on the authoritative cost doc only.
+      if (doc === 'docs/concepts/cost.md') {
+        const budgets: [string, number][] = [['lean', 12000], ['standard', 25000], ['full', 50000]];
+        for (const [lane, budget] of budgets) {
+          const warn = budget * 3 / 2;
+          const stop = budget * 3;
+          const warnForms = [`${warn}`, `${Math.round(warn / 1000)}k`, `${warn.toLocaleString()}`, `${warn / 1000}k`];
+          const stopForms = [`${stop}`, `${stop / 1000}k`, `${stop.toLocaleString()}`];
+          const hasWarn = warnForms.some(f => text.includes(f));
+          const hasStop = stopForms.some(f => text.includes(f));
+          if (!hasWarn || !hasStop) {
+            errors.push(`doc-integrity: ${doc} ${lane} warn/stop must be 1.5x/3x of budget ${budget} (warn ${warn}, stop ${stop})`);
+          }
+        }
+      }
+    }
+    if (!constants.includes('LANE_BASE_lean=7000')) errors.push('doc-integrity: source lane-base.sh lean base drifted (expected 7000)');
+    if (!constants.includes('BUDGET_full=50000')) errors.push('doc-integrity: source lane-base.sh full budget drifted (expected 50000)');
+  }
+  // evidence exit-code claim must be test-backed
+  const evTest = join(import.meta.dirname, '..', 'test', 'lane-integrity.test.ts');
+  const testText = existsSync(evTest) ? readFileSync(evTest, 'utf8') : '';
+  if (!testText.includes('# Exit:') || !testText.includes('# Verdict:')) {
+    errors.push('doc-integrity: audit-trail claims evidence logs carry exit code + verdict, but no test asserts them');
+  }
+}
+
 if (errors.length) { console.error(errors.map(e => `✗ ${e}`).join('\n')); process.exit(1); }
 console.log(`✓ content valid: ${skillDirs.length} skills, ${agentFiles.length} agents`);

package/src/cli.ts

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { parseArgs, type FlagValue, type Args } from './args.ts';
 import { createRl, choose, multiChoose, confirm } from './prompt.ts';
 import { targets, TARGET_IDS } from './targets/index.ts';
-import { installTo, removeInstalled, VERSION, ensureProjectGitignore } from './installer.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';
 
@@ -151,6 +151,10 @@ async function uninstall(flags: Args['flags']): Promise<void> {
   }
   const removed = removeInstalled(manifest, { dryRun: flag(flags.dryRun) });
   if (!flag(flags.dryRun)) {
+    if (scope === 'project') {
+      const gi = removeProjectGitignore(projectDir);
+      for (const n of gi.notes) console.log(`   note: ${n}`);
+    }
     rmSync(file);
     const mugiDir = join(scope === 'global' ? home : projectDir, '.mugiwara');
     if (existsSync(mugiDir) && readdirSync(mugiDir).length === 0) {

package/src/installer.ts

@@ -182,28 +182,90 @@ function assertNotSymlink(file: string): void {
   }
 }
 
+const GITIGNORE_BLOCK_START = '# >>> mugiwara >>>';
+const GITIGNORE_BLOCK_END = '# <<< mugiwara <<<';
+// legacy marker from v0.6.2 — block was undelimited, single '# mugiwara'
+// header. Kept for detection so an old install is not double-appended.
 const GITIGNORE_MARKER = '# mugiwara';
-const GITIGNORE_BLOCK = `# mugiwara — audit trail is the product: commit reports/, results/, logs/, spec/, plans/.
+const GITIGNORE_BLOCK = `# >>> mugiwara >>> — audit trail is the product: commit reports/, results/, logs/, spec/, plans/.
 # Ignore session state and regenerated files.
-.mugiwara/state.json
-.mugiwara/state-*.json
+.mugiwara/state/
+.mugiwara/continue/
 .mugiwara/config
-.mugiwara/continue.md
 .mugiwara/refs/
+# <<< mugiwara <<<
 `;
 
 export function ensureProjectGitignore(projectDir: string, opts: { dryRun?: boolean } = {}): { appended: boolean; notes: string[] } {
   const { dryRun = false } = opts;
   const path = join(projectDir, '.gitignore');
   assertNotSymlink(path);
-  if (existsSync(path) && readFileSync(path, 'utf8').includes(GITIGNORE_MARKER)) {
-    return { appended: false, notes: [] };
+  let existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (existing) {
+    // Delimited block present with the current entries → nothing to do.
+    if (existing.includes(GITIGNORE_BLOCK_START) && existing.includes('.mugiwara/state/')) {
+      return { appended: false, notes: [] };
+    }
+    // Legacy (v0.6.2) or outdated delimited block → upgrade in place:
+    // strip the old mugiwara entries (both forms), then append the new block.
+    // Without this, upgraded projects keep committing per-wave state/continue
+    // JSON to git — session state must stay ignored (Robin MAJOR, Jinbe Low).
+    const hadOld = existing.includes(GITIGNORE_MARKER) || existing.includes(GITIGNORE_BLOCK_START);
+    if (hadOld) {
+      const clean = removeProjectGitignore(projectDir, { dryRun });
+      existing = clean.removed ? (existsSync(path) ? readFileSync(path, 'utf8') : '') : existing;
+    }
   }
-  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
   const separator = existing.length && !existing.endsWith('\n') ? '\n' : '';
   if (!dryRun) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, existing + separator + GITIGNORE_BLOCK);
   }
-  return { appended: true, notes: [`.gitignore ${dryRun ? 'would append' : 'appended'} mugiwara audit-trail block`] };
+  return { appended: true, notes: [`.gitignore ${dryRun ? 'would upgrade+append' : 'upgraded'} mugiwara audit-trail block`] };
+}
+
+// remove the delimited mugiwara block, preserving user lines. Handles both
+// the current delimited block and the legacy undelimited block (v0.6.2).
+export function removeProjectGitignore(projectDir: string, { dryRun = false }: { dryRun?: boolean } = {}): { removed: boolean; notes: string[] } {
+  const path = join(projectDir, '.gitignore');
+  assertNotSymlink(path);
+  if (!existsSync(path)) return { removed: false, notes: [] };
+  const current = readFileSync(path, 'utf8');
+
+  const delimited = current.includes(GITIGNORE_BLOCK_START);
+  let cleaned: string;
+  if (delimited) {
+    // strip everything between (and including) the delimiters. Both
+    // delimiters must be present — a missing END (hand-edit) with end=-1
+    // would slice() from char 18 and truncate the user's file.
+    const start = current.indexOf(GITIGNORE_BLOCK_START);
+    const end = current.indexOf(GITIGNORE_BLOCK_END);
+    if (end < start) return { removed: false, notes: ['delimiter mismatch — .gitignore left untouched'] };
+    cleaned = current.slice(0, start) + current.slice(end + GITIGNORE_BLOCK_END.length);
+  } else if (current.includes(GITIGNORE_MARKER)) {
+    // legacy (v0.6.2): strip the exact undelimited block — the header, the
+    // explanatory comment, and the five known lines. Prefix-matching would
+    // delete user-owned lines that merely start with a mugiwara path.
+    const LEGACY_LINES = new Set([
+      '.mugiwara/state.json',
+      '.mugiwara/state-*.json',
+      '.mugiwara/config',
+      '.mugiwara/continue.md',
+      '.mugiwara/refs/',
+    ]);
+    const lines = current.split('\n').filter(l => {
+      const t = l.trim();
+      if (t.startsWith(GITIGNORE_MARKER)) return false; // header + comment
+      return !LEGACY_LINES.has(t);
+    });
+    cleaned = lines.join('\n');
+  } else {
+    return { removed: false, notes: [] };
+  }
+
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n+$/, '\n');
+  if (cleaned.trim() === '') cleaned = '';
+  if (cleaned === current) return { removed: false, notes: [] };
+  if (!dryRun) writeFileSync(path, cleaned);
+  return { removed: true, notes: [`.gitignore ${dryRun ? 'would strip' : 'stripped'} mugiwara block`] };
 }