@ionivetech/mugiwara 0.6.6 → 0.7.0

package/scripts/savepoint.sh

@@ -1,15 +1,27 @@
 #!/usr/bin/env bash
-# scripts/savepoint.sh — write .mugiwara/state/<mission>/<member>.json at every
-# wave boundary. Computed from git + file counts; zero model judgement.
+# scripts/savepoint.sh — write .mugiwara/missions/<mission>/<member>.json at every
+# flow-stage 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] [lane]
+#   savepoint.sh <mission> [member] [flow] [mode] [lane]
 set -u
 
 die() { echo "savepoint: $*" >&2; exit 1; }
 
 MUGIWARA_DIR="${MUGIWARA_DIR:-.mugiwara}"
 
+# optional provider-reported tokens file (T4): --tokens-file <path> JSON {input_tokens, output_tokens}
+TOKENS_FILE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tokens-file) TOKENS_FILE="${2:-}"; [ -n "$TOKENS_FILE" ] || die "--tokens-file requires a path"; shift 2 ;;
+    --tokens-file=*) TOKENS_FILE="${1#*=}"; shift ;;
+    --) shift; break ;;
+    -*) die "unknown flag \"$1\"" ;;
+    *) break ;;
+  esac
+done
+
 # shared path patterns — single source of truth (D3)
 # shellcheck source=scripts/lib/patterns.sh
 source "$(dirname "$0")/lib/patterns.sh"
@@ -99,6 +111,12 @@ esac
 [ "$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')"
+# Per-stage model attribution (A4): record which model produced THIS stage.
+# MUGIWARA_MODEL wins over ANTHROPIC_MODEL; 'unknown' beats a lie. Closure
+# renders the unique set across stage files so mid-mission switches stay
+# visible in provenance instead of every line attributing to the last value.
+MODEL="${MUGIWARA_MODEL:-${ANTHROPIC_MODEL:-}}"
+[ -n "$MODEL" ] || MODEL="unknown"
 
 # treat the legacy empty-actor placeholder '""' as "no member" (solo). The old
 # interface used '""' for the actor slot; the new (mission, member) interface
@@ -123,6 +141,12 @@ esac
 if [[ "$MEMBER" =~ ^\.+$ ]]; then
   die "invalid member name \"$MEMBER\" (allowlist: [a-zA-Z0-9._-], not a dot-path)"
 fi
+# reserved stems — <member>.json and continue-<member>.json share the mission
+# dir with state.json / continue.json; member "state" or "continue" would
+# overwrite the solo files (state pointer or resume pointer).
+case "$MEMBER" in
+  state|continue) die "reserved member name \"$MEMBER\" (state, continue)" ;;
+esac
 
 # 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
@@ -130,15 +154,16 @@ fi
 # (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"
+# state + continue live in the mission dir. Solo (member empty) → state.json
+# + continue.json; team writes <member>.json + continue-<member>.json so
+# parallel members never clobber each other.
+MISSION_DIR="$MUGIWARA_DIR/missions/$MISSION"
 if [ -n "$MEMBER" ]; then
-  STATE_FILE="$STATE_DIR/$MEMBER.json"
-  CONTINUE_FILE="$CONTINUE_DIR/$MEMBER.json"
+  STATE_FILE="$MISSION_DIR/$MEMBER.json"
+  CONTINUE_FILE="$MISSION_DIR/continue-$MEMBER.json"
 else
-  STATE_FILE="$STATE_DIR/state.json"
-  CONTINUE_FILE="$CONTINUE_DIR/state.json"
+  STATE_FILE="$MISSION_DIR/state.json"
+  CONTINUE_FILE="$MISSION_DIR/continue.json"
 fi
 
 [ -z "$MISSION" ] && die "usage: savepoint.sh <mission> [member] [wave] [mode] [lane]"
@@ -148,21 +173,46 @@ fi
 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")
 
+# lane_scope_glob (T5): monorepo scoping — count only files matching the glob
+LANE_SCOPE_GLOB=""
+if [ -f "$MUGIWARA_DIR/config" ]; then
+  _cfg_scope=$(grep -E '^lane_scope_glob=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | tr -d '"' | tr -d "'")
+  [ -n "$_cfg_scope" ] && LANE_SCOPE_GLOB="$_cfg_scope"
+fi
 # 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 )
-
-read -r LOC_INS LOC_DEL <<EOF
+# sensitive-path escalation always uses unfiltered set (safety never shrinks, T5)
+SENSITIVE_PATHS=$(echo "$CHANGED_FILES" | grep -E "$SENSITIVE_PATS" 2>/dev/null | tr '\n' ',' | sed 's/,$//' || true)
+# scoped counting (T5)
+SCOPED_FILES="$CHANGED_FILES"
+if [ -n "$LANE_SCOPE_GLOB" ] && [ -n "$CHANGED_FILES" ]; then
+  shopt -s extglob globstar 2>/dev/null || true
+  SCOPED_FILES=""
+  while IFS= read -r _sf; do
+    [ -z "$_sf" ] && continue
+    # shellcheck disable=SC2053
+    if [[ "$_sf" == $LANE_SCOPE_GLOB ]]; then
+      SCOPED_FILES="${SCOPED_FILES}${SCOPED_FILES:+
+}$_sf"
+    fi
+  done <<< "$CHANGED_FILES"
+fi
+FILES_TOUCHED=$( [ -n "$SCOPED_FILES" ] && echo "$SCOPED_FILES" | wc -l | tr -d ' ' || echo 0 )
+if [ -n "$LANE_SCOPE_GLOB" ]; then
+  read -r LOC_INS LOC_DEL <<EOF
+$( { echo "$SCOPED_FILES" | while IFS= read -r _lf; do [ -n "$_lf" ] && git diff --numstat "$BASE_SHA"..HEAD -- "$_lf" 2>/dev/null; git diff --numstat HEAD -- "$_lf" 2>/dev/null; done; echo "$SCOPED_FILES" | while IFS= read -r _uf; do [ -z "$_uf" ] && continue; if git ls-files --others --exclude-standard -- "$_uf" 2>/dev/null | grep -qx "$_uf"; then printf '%s\t0\t%s\n' "$(wc -l < "$_uf" 2>/dev/null | tr -d ' ' || echo 0)" "$_uf"; fi; done; } | awk '{ if ($1 ~ /^[0-9]+$/) i+=$1; if ($2 ~ /^[0-9]+$/) d+=$2 } END { print (i+0)" "(d+0) }')
+EOF
+else
+  read -r LOC_INS LOC_DEL <<EOF
 $(changed_loc "$BASE_SHA")
 EOF
+fi
 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)
-
 LANE="direct"
 LANE_REASON=""
 # Sensitive-path escalation is unconditional — it wins over any count-based
@@ -196,9 +246,10 @@ 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.
-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)
+# escalation above still wins. With lane_scope_glob the check applies to the
+# scoped set — but sensitive wins unfiltered above, so safety never shrinks.
+if [ "$LANE" = "full" ] && [ -z "$SENSITIVE_PATHS" ] && [ -n "$SCOPED_FILES" ]; then
+  CODE_COUNT=$(echo "$SCOPED_FILES" | grep -E "$PRODUCT_PAT" 2>/dev/null | grep -c . || true)
   if [ -z "$CODE_COUNT" ] || [ "$CODE_COUNT" -eq 0 ] 2>/dev/null; then
     PREV="$LANE"
     LANE="standard"
@@ -206,6 +257,20 @@ if [ "$LANE" = "full" ] && [ -z "$SENSITIVE_PATHS" ] && [ -n "$CHANGED_FILES" ];
   fi
 fi
 
+# policy as code: mugiwara.policy.yml lanes.force_full raises the
+# lane to full — upward only. Optional: no file or no bun = no-op.
+if command -v bun >/dev/null 2>&1 && { [ -f mugiwara.policy.yml ] || [ -f mugiwara.policy.yaml ]; }; then
+  POLICY_HITS=$(printf '%s\n' "$CHANGED_FILES" | bun "$(dirname "$0")/policy-force.ts")
+  RC=$?
+  if [ "$RC" -ne 0 ]; then
+    die "mugiwara.policy.yml is invalid — fix or remove it (fail-closed)"
+  fi
+  if [ -n "$POLICY_HITS" ]; then
+    LANE="full"
+    LANE_REASON="policy force_full ($POLICY_HITS)"
+  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
@@ -255,9 +320,8 @@ if [ -n "$LANE_PREV" ] && [ "$LANE_PREV" != "$LANE" ]; then
   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)
+# task counts from plan doc — bare name, one file per mission.
+PLAN_FILE="$MISSION_DIR/plan.md"
 TASKS_DONE=0
 TASKS_TOTAL=0
 if [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
@@ -269,11 +333,7 @@ if [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
 fi
 
 # blocker count
-# 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_FILE="$MISSION_DIR/blockers.md"
 BLOCKERS_OPEN=0
 if [ -n "$BLOCKERS_FILE" ] && [ -f "$BLOCKERS_FILE" ]; then
   # data rows start with a wave number; header "| wave |" and separator
@@ -281,27 +341,18 @@ if [ -n "$BLOCKERS_FILE" ] && [ -f "$BLOCKERS_FILE" ]; then
   BLOCKERS_OPEN=$(grep -cE '^\| ?[0-9]+ ?\|' "$BLOCKERS_FILE" 2>/dev/null || true)
 fi
 
-# 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 — count Flow-8 (healing) section headings in the DECISION LOG
+# (missions/<mission>/decisions.md), 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.
 HEAL_CYCLE=1
 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
+LOG_FILE="$MISSION_DIR/decisions.md"
+if [ -f "$LOG_FILE" ]; then
+  HEAL_COUNT=$(grep -ciE '^## flow 8([^0-9a-z]|$)' "$LOG_FILE" 2>/dev/null || true)
+fi
 if [ "$HEAL_COUNT" -gt 0 ]; then
   HEAL_CYCLE=$((HEAL_COUNT + 1))
 fi
@@ -314,12 +365,18 @@ 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 paths — the mission's flow folder (quoted printf, no sed — mission
+# name is allowlisted above, but avoid sed metacharacter semantics entirely).
+# New missions use flows/; a legacy mission that already keeps waves/ stays on
+# waves/ so an in-flight trail never splits across two directories.
+FLOWDIR="flows"
+if [ -d "$MISSION_DIR/waves" ] && [ ! -d "$MISSION_DIR/flows" ]; then
+  FLOWDIR="waves"
+fi
 EVIDENCE=""
-for evf in "$MUGIWARA_DIR/results/${MISSION}/"*.md; do
+for evf in "$MISSION_DIR/$FLOWDIR/"*.md; do
   [ -f "$evf" ] || continue
-  EVIDENCE="${EVIDENCE}${EVIDENCE:+,}.mugiwara/results/${MISSION}/$(basename "$evf")"
+  EVIDENCE="${EVIDENCE}${EVIDENCE:+,}.mugiwara/missions/${MISSION}/${FLOWDIR}/$(basename "$evf")"
 done
 
 # skill version — MUGIWARA's own package.json, resolved from the script
@@ -340,7 +397,21 @@ fi
 # real usage. Monotonic beats precise — LANE_BASE stands in for the skills
 # loaded this lane (measured from content, validated by scripts/lane-base.ts);
 # loc_churn and written-artifact words scale with growth.
+# auto-detect harness for token reporting (Tier-1: Claude Code / opencode)
+# If --tokens-file not given, try env/file fallbacks so estimator is last resort.
+if [ -z "$TOKENS_FILE" ]; then
+  for _cand in "${MUGIWARA_TOKENS_FILE:-}" "${CLAUDE_TOKENS_FILE:-}" "${OPENCODE_TOKENS_FILE:-}" "/tmp/mugiwara-tokens.json" "$HOME/.cache/mugiwara/tokens.json" ".mugiwara/tokens.json"; do
+    [ -n "$_cand" ] && [ -f "$_cand" ] && TOKENS_FILE="$_cand" && break
+  done
+fi
+# detect harness (for logging / future tier checks)
+HARNESS="unknown"
+if [ -n "${CLAUDECODE:-}" ] || [ -n "${CLAUDE_CODE_ENTRYPOINT:-}" ] || echo "${ANTHROPIC_MODEL:-}" | grep -qi claude 2>/dev/null; then HARNESS="claude";
+elif [ -n "${OPENCODE:-}" ] || [ -f ".opencode/config.json" ] || [ -n "${OPENCODE_TOKENS_FILE:-}" ]; then HARNESS="opencode";
+elif [ -n "${CURSOR:-}" ] || [ -n "${VSCODE_GIT_ASKPASS_NODE:-}" ]; then HARNESS="cursor/vscode"; fi
+
 # MUGIWARA_TOKENS overrides as the reported value.
+# --tokens-file (T4) is the first-class provider-reported path: JSON {input_tokens, output_tokens}
 LANE_BASE=0
 case "$LANE" in
   lean) LANE_BASE=$LANE_BASE_lean ;;
@@ -348,14 +419,19 @@ case "$LANE" in
   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 ' ')
+DOC_WORDS=$(cat "$MISSION_DIR"/"$FLOWDIR"/*.md "$MISSION_DIR"/plan.md "$MISSION_DIR"/spec.md "$MISSION_DIR"/decisions.md 2>/dev/null | wc -w | tr -d ' ')
 LOC_TOKENS=$(( LOC_CHURN * 12 ))
-TOKENS_SOURCE="computed"
+TOKENS_SOURCE="estimator"
 TOKENS_EST=$(( LANE_BASE + DOC_WORDS * 135 / 100 + LOC_TOKENS ))
 if [ -n "${MUGIWARA_TOKENS:-}" ]; then
   TOKENS_EST="${MUGIWARA_TOKENS}"
   TOKENS_SOURCE="reported"
 fi
+if [ -n "$TOKENS_FILE" ]; then
+  [ -f "$TOKENS_FILE" ] || die "tokens file not found: $TOKENS_FILE"
+  TOKENS_EST=$(node -e "try{const j=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));const i=Number(j.input_tokens)||0;const o=Number(j.output_tokens)||0;console.log(i+o)}catch(e){console.log(0)}" "$TOKENS_FILE" 2>/dev/null || echo 0)
+  TOKENS_SOURCE="reported"
+fi
 
 # budget per lane
 BUDGET=0
@@ -390,7 +466,7 @@ if [ "$BUDGET" -gt 0 ] 2>/dev/null; then
   fi
 fi
 
-mkdir -p "$MUGIWARA_DIR/state/$MISSION" "$MUGIWARA_DIR/continue/$MISSION"
+mkdir -p "$MISSION_DIR"
 
 node -e "
 const data = {
@@ -406,6 +482,7 @@ const data = {
   flow: parseInt(process.argv[6], 10),
   mode: process.argv[7],
   verbosity: process.argv[32] || 'normal',
+  model: process.argv[37] || 'unknown',
   base_sha: process.argv[8],
   head_sha: process.argv[9],
   files_touched: parseInt(process.argv[10], 10),
@@ -439,20 +516,21 @@ require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\
   "$(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" \
-  "$HEAL_MAX_CYCLES" "$HEAL_HALT" "$DELEGATE_THRESHOLD" "$DELEGATE_DUE"
+  "$HEAL_MAX_CYCLES" "$HEAL_HALT" "$DELEGATE_THRESHOLD" "$DELEGATE_DUE" \
+  "$MODEL"
 
 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 ---
+# --- continue.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.
+# Scoped by (mission, member) like state.json — solo writes continue.json, team
+# writes continue-<member>.json. The crew-written next_session_prompt line is
+# preserved across savepoints.
 if [ -n "$MISSION" ]; then
   NEXT_SESSION_PROMPT=""
   if [ -f "$CONTINUE_FILE" ]; then
@@ -491,4 +569,4 @@ if [ -n "$MISSION" ]; then
     "$CONTINUE_FILE" "$CONTINUE_FILE" "$ACTOR"
 fi
 
-echo "✓ savepoint written: $STATE_FILE (lane=$LANE, wave=$WAVE, files=$FILES_TOUCHED)"
+echo "✓ savepoint written: $STATE_FILE (lane=$LANE, flow=$WAVE, files=$FILES_TOUCHED)"

package/scripts/validate-content.ts

@@ -286,6 +286,25 @@ if (totalDescChars > INDEX_BUDGET) {
   console.log(`✓ index budget: ${totalDescChars}/${INDEX_BUDGET} chars`);
 }
 
+// The measured index size is published in docs/concepts/cost.md. A measured
+// number in prose that drifted from reality is a defect (it survived one
+// release: cost.md claimed 5,437 chars after the prune measured 4,688).
+// Gate the doc against the measurement so the class stays closed.
+const costDoc = join(root, '..', 'docs', 'concepts', 'cost.md');
+if (existsSync(costDoc)) {
+  const m = readFileSync(costDoc, 'utf8').match(/\*\*Current:\*\* (\d[\d,]*) chars/);
+  if (!m) {
+    errors.push('docs/concepts/cost.md: missing "**Current:** <n> chars" line for the measured index size');
+  } else {
+    const stated = parseInt(m[1].replace(/,/g, ''), 10);
+    if (stated !== totalDescChars) {
+      errors.push(`docs/concepts/cost.md states ${stated} index chars but content measures ${totalDescChars} — update the doc`);
+    } else {
+      console.log(`✓ cost.md index chars match measurement (${stated})`);
+    }
+  }
+}
+
 // --- docs-drift check: docs/skills.md and docs/agents.md must reference all content/ entries ---
 const docsArg = process.argv.indexOf('--check-docs');
 if (docsArg !== -1) {
@@ -374,15 +393,9 @@ if (integrityArg !== -1) {
         }
       }
     }
-    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 (!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)');
+}
 }
 
 // Conditional-assertion guard: an expect() reachable only inside a truthiness

package/scripts/verify-install.ts

@@ -87,13 +87,15 @@ for (const id of TARGET_IDS) {
 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\/?$/,
+  /^\.mugiwara\/lessons\.md$/,
+  /^\.mugiwara\/index\.md$/,
+  /^\.mugiwara\/missions\/(<mission>|[a-z0-9._-]+)\/(plan|spec|decisions|blockers|review|security|report)\.md$/,
+  /^\.mugiwara\/missions\/(<mission>|[a-z0-9._-]+)\/flows\/([0-9]{2}-[a-z-]+|eval|resume|todos)\.md$/,
+  /^\.mugiwara\/missions\/<mission>\/flows\/?$/,
+  /^\.mugiwara\/missions\/(<mission>|[a-z0-9._-]+)\/waves\/([0-9]{2}-[a-z-]+|eval|resume|todos)\.md$/, // legacy layout, still read
+  /^\.mugiwara\/missions\/<mission>\/waves\/?$/, // legacy layout, still read
+  /^\.mugiwara\/missions\/<mission>\/(state\.json|<member>\.json)$/,
+  /^\.mugiwara\/missions\/<mission>\/(continue\.json|continue-<member>\.json)$/,
 ];
 
 // Shape violations that exist today and are NOT fixed in this mission because

package/src/args.ts

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

package/src/budget.ts

@@ -0,0 +1,56 @@
+// src/budget.ts
+// Context budget as a gate: a mission's trail is itself
+// context the next reader must load. At archive time, measure the total
+// footprint of the artifacts that survive and compare against the configured
+// ceiling — a bloated trail is caught like a failed test, with a visible
+// number in the report.
+//
+// Token telemetry stays honest elsewhere: the estimator remains the default;
+// `tokens_source: reported` activates only where the harness exposes real
+// usage (see docs/concepts/cost.md). This module does not estimate tokens.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function readBudgetConfig(projectDir: string): number {
+  for (const base of [projectDir, homedir()]) {
+    const file = join(base, '.mugiwara', 'config');
+    if (!existsSync(file)) continue;
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t || t.startsWith('#')) continue;
+      const eq = t.indexOf('=');
+      if (eq === -1) continue;
+      if (t.slice(0, eq).trim() !== 'context_budget_chars') continue;
+      const n = Number(t.slice(eq + 1).trim());
+      return Number.isFinite(n) && n > 0 ? n : 0;
+    }
+  }
+  return 0; // unset — measurement still recorded, never enforced
+}
+
+/** Sum of bytes across the trail: top-level *.md + flows/* (legacy waves/* counts too). */
+export function measureContextChars(missionDir: string): number {
+  let total = 0;
+  const add = (p: string): void => {
+    try { total += statSync(p).size; } catch { /* vanished mid-measure */ }
+  };
+  for (const f of readdirSync(missionDir)) {
+    if (/\.md$/.test(f)) add(join(missionDir, f));
+  }
+  for (const sub of ['flows', 'waves']) {
+    const dir = join(missionDir, sub);
+    if (existsSync(dir)) {
+      for (const f of readdirSync(dir)) add(join(dir, f));
+    }
+  }
+  return total;
+}
+
+export function formatFootprint(chars: number, budget: number): string {
+  const base = `Context footprint: ${chars} chars`;
+  if (!budget) return `${base} (no budget configured)`;
+  return chars > budget
+    ? `${base} — OVER budget ${budget}`
+    : `${base} (budget ${budget})`;
+}