@ionivetech/mugiwara 0.6.5 → 0.6.6

package/scripts/savepoint.sh

@@ -3,7 +3,7 @@
 # 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]
+#   savepoint.sh <mission> [member] [wave] [mode] [lane]
 set -u
 
 die() { echo "savepoint: $*" >&2; exit 1; }
@@ -42,6 +42,28 @@ MISSION="${1:-${STATE_MISSION:-}}"
 MEMBER="${2:-${STATE_MEMBER:-}}"
 WAVE="${3:-${STATE_WAVE:-1}}"
 MODE="${4:-${STATE_MODE:-guided}}"
+# Triage lane (M7): the lane Luffy assigned at Flow 0. Without it savepoint
+# recomputed the lane from file counts alone and silently discarded the
+# triage decision — a Lane 3 mission recorded itself as "direct". Explicit
+# lane acts as a FLOOR: the computed lane may still raise it, never lower it.
+LANE_EXPLICIT="${5:-${STATE_LANE:-}}"
+case "$LANE_EXPLICIT" in
+  ""|direct|lean|standard|full|spike) ;;
+  *) die "invalid lane \"$LANE_EXPLICIT\" (one of: direct lean standard full spike)" ;;
+esac
+# Wave may be fractional in the docs (4.5 = the checkpoint between waves).
+# parseInt("4.5")=4 while tr -cd '0-9' gives "45", so state and continue
+# disagreed on the same mission. Normalize once, here, for both writers.
+# Keep only digits and the decimal point, then take the integer part. Garbage
+# input still sanitizes to 0 (the N2 contract the continue writer already had);
+# a fractional wave now truncates identically in BOTH writers instead of
+# splitting into 4 (parseInt) and 45 (digit-strip).
+WAVE_INT=$(printf '%s' "$WAVE" | tr -cd '0-9.')
+WAVE_INT=${WAVE_INT%%.*}
+case "$WAVE_INT" in
+  ''|*[!0-9]*) WAVE_INT=0 ;;
+esac
+
 # verbosity from config (project .mugiwara/config), default normal; env override
 VERBOSITY="${STATE_VERBOSITY:-normal}"
 if [ -f "$MUGIWARA_DIR/config" ]; then
@@ -52,7 +74,30 @@ case "$VERBOSITY" in
   normal|full) ;;
   *) VERBOSITY="normal" ;;
 esac
-ACTOR="${STATE_ACTOR:-${GIT_AUTHOR_NAME:-${GIT_ID:-${USER:-}}}}"
+
+# heal_max_cycles from config (project .mugiwara/config), default 3; env override
+HEAL_MAX_CYCLES="${STATE_HEAL_MAX_CYCLES:-3}"
+if [ -f "$MUGIWARA_DIR/config" ]; then
+  CFG_HEAL_MAX=$(grep -E '^heal_max_cycles=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$CFG_HEAL_MAX" ] && HEAL_MAX_CYCLES="$CFG_HEAL_MAX"
+fi
+case "$HEAL_MAX_CYCLES" in
+  ''|*[!0-9]*) HEAL_MAX_CYCLES=3 ;;
+esac
+[ "$HEAL_MAX_CYCLES" -lt 1 ] 2>/dev/null && HEAL_MAX_CYCLES=3
+
+# delegate_threshold from config (project .mugiwara/config), default 60; env override
+DELEGATE_THRESHOLD="${STATE_DELEGATE_THRESHOLD:-60}"
+if [ -f "$MUGIWARA_DIR/config" ]; then
+  CFG_DELEGATE=$(grep -E '^delegate_threshold=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$CFG_DELEGATE" ] && DELEGATE_THRESHOLD="$CFG_DELEGATE"
+fi
+case "$DELEGATE_THRESHOLD" in
+  ''|*[!0-9]*) DELEGATE_THRESHOLD=60 ;;
+esac
+[ "$DELEGATE_THRESHOLD" -lt 1 ] 2>/dev/null && DELEGATE_THRESHOLD=1
+[ "$DELEGATE_THRESHOLD" -gt 100 ] 2>/dev/null && DELEGATE_THRESHOLD=100
+ACTOR="${STATE_ACTOR:-${GIT_AUTHOR_NAME:-${GIT_ID:-${USER:-${USERNAME:-}}}}}"
 BRANCH="$(git branch --show-current 2>/dev/null || echo 'unknown')"
 
 # treat the legacy empty-actor placeholder '""' as "no member" (solo). The old
@@ -96,31 +141,25 @@ else
   CONTINUE_FILE="$CONTINUE_DIR/state.json"
 fi
 
-[ -z "$MISSION" ] && die "usage: savepoint.sh <mission> [member] [wave] [mode]"
+[ -z "$MISSION" ] && die "usage: savepoint.sh <mission> [member] [wave] [mode] [lane]"
 [ -d .git ] || die "not a git repository"
 
 # --- computed fields ---
 BASE_SHA=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null || git merge-base HEAD "$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')" 2>/dev/null || git rev-parse HEAD~1 2>/dev/null || echo "unknown")
 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)
+# union of committed + staged + unstaged + untracked (F) — see patterns.sh
+CHANGED_FILES=$(changed_files "$BASE_SHA")
 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_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
+read -r LOC_INS LOC_DEL <<EOF
+$(changed_loc "$BASE_SHA")
+EOF
+LOC_INS=$(( ${LOC_INS:-0} + 0 ))
+LOC_DEL=$(( ${LOC_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 ))
 
 SENSITIVE_PATHS=$(echo "$CHANGED_FILES" | grep -E "$SENSITIVE_PATS" 2>/dev/null | tr '\n' ',' | sed 's/,$//' || true)
 
@@ -142,7 +181,7 @@ elif [ "$FILES_TOUCHED" -ge 2 ] 2>/dev/null; then
   LANE_REASON="$FILES_TOUCHED files"
 elif [ "$FILES_TOUCHED" -eq 1 ] 2>/dev/null; then
   # 1-file rule mirrors lane.sh: >=20 added LOC -> lean, else direct
-  ADDED=$(git diff --numstat "$BASE_SHA"..HEAD 2>/dev/null | awk '{s+=$1} END {print s+0}')
+  ADDED="$LOC_INS"
   if [ "${ADDED:-0}" -ge 20 ] 2>/dev/null; then
     LANE="lean"
     LANE_REASON="1 file, $ADDED LOC"
@@ -167,6 +206,19 @@ if [ "$LANE" = "full" ] && [ -z "$SENSITIVE_PATHS" ] && [ -n "$CHANGED_FILES" ];
   fi
 fi
 
+# explicit triage lane (M7) applied as a floor — the computed lane above may
+# raise it, never lower it. Sensitive-path escalation still wins
+# unconditionally: spike is a resize, not a rise, so it never displaces the
+# full lane a sensitive path forced.
+if [ -n "$LANE_EXPLICIT" ]; then
+  if [ "$LANE_EXPLICIT" = "spike" ] && [ -n "$SENSITIVE_PATHS" ]; then
+    LANE_REASON="$LANE_REASON (explicit spike ignored — sensitive paths)"
+  elif [ "$(lane_rank "$LANE_EXPLICIT")" -gt "$(lane_rank "$LANE")" ]; then
+    LANE_REASON="triage lane $LANE_EXPLICIT (floor; computed $LANE — $LANE_REASON)"
+    LANE="$LANE_EXPLICIT"
+  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.
@@ -217,7 +269,11 @@ if [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
 fi
 
 # blocker count
-BLOCKERS_FILE=$(ls "$MUGIWARA_DIR/issues/${MISSION}-blockers.md" 2>/dev/null || true)
+# The crew writes the DATED name (`YYYY-MM-DD-<mission>-blockers.md`) — that is
+# what 15 prose sites mandate and what lands on disk. Matching only the bare
+# name made blockers_open structurally 0 forever, and that zero feeds the DoD
+# ship-readiness axis. Accept both; newest wins.
+BLOCKERS_FILE=$(ls -t "$MUGIWARA_DIR/issues/${MISSION}-blockers.md" "$MUGIWARA_DIR"/????-??-??-"${MISSION}"-blockers.md "$MUGIWARA_DIR/issues"/????-??-??-"${MISSION}"-blockers.md 2>/dev/null | head -1 || true)
 BLOCKERS_OPEN=0
 if [ -n "$BLOCKERS_FILE" ] && [ -f "$BLOCKERS_FILE" ]; then
   # data rows start with a wave number; header "| wave |" and separator
@@ -225,16 +281,39 @@ if [ -n "$BLOCKERS_FILE" ] && [ -f "$BLOCKERS_FILE" ]; then
   BLOCKERS_OPEN=$(grep -cE '^\| ?[0-9]+ ?\|' "$BLOCKERS_FILE" 2>/dev/null || true)
 fi
 
-# heal cycle — count WAVE-8 banner occurrences in the trace, not the word
-# "heal" anywhere (heal workers/healing text would inflate the counter and
-# cause a premature halt)
+# heal cycle — count Flow-8 (healing) section headings in the DECISION LOG,
+# which every mission writes (luffy-orchestrator rule 10). Not the word "heal"
+# anywhere (heal workers/healing text would inflate the counter and cause a
+# premature halt). Each heal cycle is logged as a "## Flow 8 — healing" section;
+# the [^0-9a-z] guard keeps adjacent "## Flow 8b"-style sections from counting.
+# Aggregate across ALL dated logs (a multi-day mission spans several files) —
+# reading only the newest would undercount earlier days' heal cycles.
 HEAL_CYCLE=1
-TRACE_FILE=$(ls "$MUGIWARA_DIR/results/${MISSION}/"*trace*.md 2>/dev/null | head -1 || true)
-if [ -n "$TRACE_FILE" ] && [ -f "$TRACE_FILE" ]; then
-  HEAL_COUNT=$(grep -ci '^.*Wave 8.*\|wave 8' "$TRACE_FILE" 2>/dev/null || true)
+HEAL_COUNT=0
+# Cap the date prefix to today: a future-dated log (9999-…) must not inflate
+# the heal counter and trigger a premature halt.
+TODAY=$(date +%Y-%m-%d)
+for LOG_FILE in "$MUGIWARA_DIR"/????-??-??-"${MISSION}".md "$MUGIWARA_DIR/logs"/????-??-??-"${MISSION}".md; do
+  [ -f "$LOG_FILE" ] || continue
+  LOG_DATE=$(basename "$LOG_FILE" | cut -c1-10)
+  case "$LOG_DATE" in
+    ''|*[!0-9-]*) continue ;;
+  esac
+  if [ "$LOG_DATE" \> "$TODAY" ]; then continue; fi
+  HEAL_COUNT=$((HEAL_COUNT + $(grep -ciE '^## flow 8([^0-9a-z]|$)' "$LOG_FILE" 2>/dev/null || true)))
+done
+if [ "$HEAL_COUNT" -gt 0 ]; then
   HEAL_CYCLE=$((HEAL_COUNT + 1))
 fi
 
+# heal halt — computed from the heal counter and the config cap (task 4f wires
+# heal_max_cycles into the counter's home). heal_cycle starts at 1, so
+# heal_cycle >= heal_max_cycles means the cap is reached: escalate, never re-run.
+HEAL_HALT=false
+if [ "$HEAL_CYCLE" -ge "$HEAL_MAX_CYCLES" ] 2>/dev/null; then
+  HEAL_HALT=true
+fi
+
 # evidence paths — per-mission results folder (quoted printf, no sed — mission
 # name is allowlisted above, but avoid sed metacharacter semantics entirely)
 EVIDENCE=""
@@ -243,12 +322,19 @@ for evf in "$MUGIWARA_DIR/results/${MISSION}/"*.md; do
   EVIDENCE="${EVIDENCE}${EVIDENCE:+,}.mugiwara/results/${MISSION}/$(basename "$evf")"
 done
 
-# skill version from package.json (argv-passing — never interpolate paths into node -e)
-SKILL_VERSION="1"
-if [ -f package.json ]; then
-  PKG_JSON="$MUGIWARA_DIR/../package.json"
-  [ -f "$PKG_JSON" ] && SKILL_VERSION=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')).version.split('.')[0])}catch(e){console.log('1')}" "$PKG_JSON" 2>/dev/null || echo "1")
+# skill version — MUGIWARA's own package.json, resolved from the script
+# location (B3). The old "$MUGIWARA_DIR/../package.json" was the USER's
+# project manifest: the version-mismatch resume prompt fired when a user
+# shipped their own v2.0.0 and stayed silent across every real mugiwara
+# release. Never fall back to the user's file — "unknown" is the honest
+# answer. Full version, not the major: mugiwara's breaking changes land in
+# 0.x minors, which a major-only string can never see.
+SKILL_VERSION="unknown"
+PKG_JSON="$(dirname "$0")/../package.json"
+if [ -f "$PKG_JSON" ]; then
+  SKILL_VERSION=$(node -e "try{const v=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')).version;console.log(v||'unknown')}catch(e){console.log('unknown')}" "$PKG_JSON" 2>/dev/null || echo "unknown")
 fi
+[ -z "$SKILL_VERSION" ] && SKILL_VERSION="unknown"
 
 # tokens proxy (F7): deterministic estimate when the harness does not report
 # real usage. Monotonic beats precise — LANE_BASE stands in for the skills
@@ -291,6 +377,19 @@ elif [ "$BUDGET" -gt 0 ] && [ "$TOKENS_EST" -ge "$WARN_AT" ] 2>/dev/null; then
   STATUS="warn"
 fi
 
+# delegate due — the execution skill's context-pressure trigger (task 4f wires
+# delegate_threshold into a computed flag). tokens_est >= threshold% of budget
+# → remaining sequential tasks dispatch to workers. Threshold stays relative:
+# a bigger budget raises the bar, it does not remove it. Budget 0 (unknown
+# lane) → never due.
+DELEGATE_DUE=false
+if [ "$BUDGET" -gt 0 ] 2>/dev/null; then
+  DELEGATE_AT=$(( BUDGET * DELEGATE_THRESHOLD / 100 ))
+  if [ "$TOKENS_EST" -ge "$DELEGATE_AT" ] 2>/dev/null; then
+    DELEGATE_DUE=true
+  fi
+fi
+
 mkdir -p "$MUGIWARA_DIR/state/$MISSION" "$MUGIWARA_DIR/continue/$MISSION"
 
 node -e "
@@ -304,7 +403,7 @@ const data = {
   lane_prev: process.argv[24] || null,
   lane_peak: process.argv[27] || null,
   lane_rose: process.argv[25] === 'true',
-  wave: parseInt(process.argv[6], 10),
+  flow: parseInt(process.argv[6], 10),
   mode: process.argv[7],
   verbosity: process.argv[32] || 'normal',
   base_sha: process.argv[8],
@@ -318,6 +417,10 @@ const data = {
   tasks: { done: parseInt(process.argv[13], 10), total: parseInt(process.argv[14], 10) },
   blockers_open: parseInt(process.argv[15], 10),
   heal_cycle: parseInt(process.argv[16], 10),
+  heal_max_cycles: parseInt(process.argv[33], 10) || 3,
+  heal_halt: process.argv[34] === 'true',
+  delegate_threshold: parseInt(process.argv[35], 10) || 60,
+  delegate_due: process.argv[36] === 'true',
   tokens_est: parseInt(process.argv[17], 10) || 0,
   tokens_source: process.argv[26] || 'computed',
   budget: parseInt(process.argv[18], 10) || 0,
@@ -329,13 +432,14 @@ const data = {
 require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\n');
 " \
   "$MISSION" "$ACTOR" "$BRANCH" "$LANE" "$LANE_REASON" \
-  "$WAVE" "$MODE" "$BASE_SHA" "$HEAD_SHA" "$FILES_TOUCHED" \
+  "$WAVE_INT" "$MODE" "$BASE_SHA" "$HEAD_SHA" "$FILES_TOUCHED" \
   "$LOC_DELTA" "$SENSITIVE_PATHS" "$TASKS_DONE" "$TASKS_TOTAL" \
   "$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" "$LANE_PEAK" \
-  "$LOC_INS" "$LOC_DEL" "$LOC_CHURN" "$MEMBER" "$VERBOSITY"
+  "$LOC_INS" "$LOC_DEL" "$LOC_CHURN" "$MEMBER" "$VERBOSITY" \
+  "$HEAL_MAX_CYCLES" "$HEAL_HALT" "$DELEGATE_THRESHOLD" "$DELEGATE_DUE"
 
 if [ "$LANE_ROSE" = true ]; then
   echo "⚠ LANE ROSE: $LANE_PREV → $LANE ($LANE_REASON) — escalate per check-in protocol"
@@ -356,7 +460,7 @@ if [ -n "$MISSION" ]; then
   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')
+  CONT_WAVE="$WAVE_INT"
   case "$MODE" in
     guided|semi|auto) CONT_MODE="$MODE" ;;
     *) CONT_MODE="guided" ;;
@@ -369,7 +473,7 @@ if [ -n "$MISSION" ]; then
     member: process.argv[2] || null,
     actor: process.argv[13] || '',
     branch: process.argv[3],
-    wave: parseInt(process.argv[4], 10) || 0,
+    flow: 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,

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',
 };