@ionivetech/mugiwara 0.4.0 → 0.5.0

package/docs/audit-trail.md

@@ -0,0 +1,65 @@
+# Audit Trail
+
+Every artifact the Mugiwara crew produces — what writes it, when, and how to
+read it as a reviewer.
+
+## The artifacts
+
+| Artifact | Path | Written by | When | For |
+|----------|------|-----------|------|-----|
+| **Plan doc** | `.mugiwara/plans/YYYY-MM-DD-<mission>.md` | Nami (planning) | Wave 2 | Zero-context executor — waves, tasks, criteria, risk |
+| **Spec** | `.mugiwara/spec/YYYY-MM-DD-<mission>.md` | Usopp (brainstorm) / Luffy (spec bridge) | Wave 0–1 | Bridge from idea to plan — goal, acceptance, constraints |
+| **State** | `.mugiwara/state.json` | `scripts/savepoint.sh` | Every wave boundary | Computed mission state: lane, wave, files, blockers, token budget, evidence paths |
+| **Decision log** | `.mugiwara/logs/YYYY-MM-DD-<mission>.md` | Luffy (orchestrator) | Every wave | Route reason, check-in verdicts, mode flips, decisions |
+| **Blocker ledger** | `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` | Any agent | On blocker hit | Row per blocker: wave, task, symptom, attempted, help-needed |
+| **Todo list** | `.mugiwara/results/<mission>-todos.md` | Zoro (execution) | Wave 3 | Checkbox per task, checked with evidence pointer |
+| **Audit report** | `.mugiwara/results/YYYY-MM-DD-<mission>-audit.md` | Chopper (checkpoint) | Wave 4 | Per-task evidence, commit hygiene, parallel-conflict, honest classification |
+| **Quality report** | `.mugiwara/results/YYYY-MM-DD-<mission>-quality.md` | Sanji (quality) | Wave 5 | Formatter/linter/unit/user-test results |
+| **Gate verdict** | `.mugiwara/results/YYYY-MM-DD-<mission>-gates.md` | Franky (gates) | Wave 6 | Coverage thresholds from config, build exit, DoD verdict |
+| **Review findings** | `.mugiwara/review/YYYY-MM-DD-<mission>-review.md` | Robin (review) | Wave 7 | Severity-tagged: path:line → problem → fix |
+| **Security report** | `.mugiwara/review/YYYY-MM-DD-<mission>-security.md` | Jinbe (security) | Wave 7 | STRIDE, OWASP mapping, checklist, CVSS severity |
+| **Heal report** | `.mugiwara/results/YYYY-MM-DD-<mission>-heal.md` | Brook (healing) | Wave 8 | Fixed list, escalated list, updated ledger |
+| **Closure report** | `.mugiwara/results/YYYY-MM-DD-<mission>-closure.md` | Luffy (orchestrator) | Wave 9 | Mission summary, per-wave outcomes, deferred items, lessons |
+| **Mission report** | `.mugiwara/reports/YYYY-MM-DD-<mission>.md` | `scripts/mission-report.sh` | Wave 9 | Human-readable summary: what changed, gates, state, token cost |
+| **PR verdict** | `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md` | Luffy (orchestrator) | Wave 9 | Ready PR summary block for the user to open the PR |
+| **Trace** | `.mugiwara/results/<mission>-trace.md` | Resume coordinator | Every dispatch | Dispatch → outcome — drives resume (legacy; state.json preferred) |
+| **Lessons ledger** | `.mugiwara/logs/lessons.md` | Memory Keeper | Cross-mission | One row per real lesson, append-only, all actors share |
+| **Evidence logs** | `.mugiwara/results/<label>-<hash>.log` | `scripts/evidence.sh` | On demand | Command stdout/stderr capture with timestamp and exit code |
+
+## How to read as a reviewer
+
+1. **Start with the mission report** (`reports/`) — one file, what changed, gates, token cost.
+2. **Check the gate verdict** (`results/<mission>-gates.md`) — coverage from config, build, DoD. Any FAIL needs explanation.
+3. **Spot-check the audit report** (`results/<mission>-audit.md`) — did Chopper re-run checks or accept claims? Every criterion gets a command run + evidence row.
+4. **Review findings count** (`review/`) — how many blocker/major/minor? Were they healed? Check the heal report for closure.
+5. **State.json** for raw numbers — lane, wave, files, blockers open, heal cycle, token budget status (ok/warn/stop).
+
+## What stays after cleanup
+
+After Wave 9 closure (run via `mugiwara-ship` cleanup procedure):
+
+**Kept** (audit trail + PR material):
+- `config` — runtime config
+- `plans/<mission>.md` — clean plan doc
+- `results/<mission>-closure.md` — closure report
+- `results/<mission>-pr-verdict.md` — PR material
+- `reports/<mission>.md` — mission report
+- `state.json` — final mission state (unless another actor's mission is active)
+- `logs/lessons.md` — cross-mission lessons
+- `backup/`, `manifest.json` — harness config
+
+**Deleted** (consumed/superseded):
+- `spec/<mission>.md` — consumed by planning
+- `results/<mission>-todos.md` — consumed
+- `results/<mission>-audit.md` — superseded by closure
+- `results/<mission>-quality.md` — consumed
+- `results/<mission>-gates.md` — consumed
+- `results/<mission>-heal.md` — consumed
+- `results/<mission>-trace.md` — consumed (state.json is canonical)
+- `review/<mission>-review.md` — consumed
+- `review/<mission>-security.md` — consumed
+- `issues/<mission>-blockers.md` — consumed
+- `logs/<mission>.md` — decision log, per-mission
+
+Cleanup lists candidates first (dry-run), then deletes. A mission is only
+closed after cleanup runs.

package/docs/comparison.md

@@ -1,185 +1,58 @@
-# Comparison
+# Positioning
 
-How mugiwara fits against the alternatives — and an honest benchmark.
+What mugiwara is and when to use something else.
 
-## The landscape
+## What mugiwara is
 
-| Tool | What it is | Harnesses |
-|------|-----------|-----------|
-| **mugiwara** | Crew (15 agents) + pipeline (9 waves, gated) + 32 skills + lane sizing | 12 harnesses + 70+ via skills.sh |
-| **superpowers** | Skills-only methodology with auto-trigger + subagent-driven development | 11 harnesses |
-| **agent-skills** (addyosmani) | 24 skills + 8 slash commands + 4 personas, Google engineering culture | 70+ via skills.sh |
-| **anthropics/skills** | Official demo skills — creative/docs/document skills, not a dev pipeline | Claude Code |
-| **mattpocock/skills** | Small composable engineering skills, mostly user-invoked | Claude Code + Codex + any |
-| **agent frameworks** (LangGraph, CrewAI, …) | Code: graphs, nodes, runtimes to host | one per framework |
-| **mega-prompt** | One big instruction | any |
+**Mugiwara is the governance layer for AI-assisted engineering work.** Every
+change carries a human-reviewable trail — which wave, what evidence, approved
+by whom — and the cost of the process scales to the size of the work.
 
-## Mugiwara vs. skills packs (superpowers, agent-skills)
+- **Lane sizing** — process scales from zero waves (typo) to nine (auth
+  migration), computed from the diff by `scripts/lane.sh`, not guessed.
+- **Evidence trail** — every wave boundary writes computed state to
+  `state.json`. No wave passes on a spoken claim. `scripts/evidence.sh` wraps
+  check commands and captures output.
+- **Resume from disk** — lose context mid-mission and the crew rebuilds from
+  `.mugiwara/` instead of restarting.
+- **15 named agents** in a 9-wave gated pipeline — each wave has a defined
+  owner, handoff, and verification gate.
+- **26 skills** with skip gates on all of them, progressive disclosure into
+  `references/`, and deterministic tooling for lane, evidence, and state.
 
-Both are markdown skills an agent picks up on demand. Mugiwara ships the same
-portable `SKILL.md` format — and adds what a pile of skills cannot:
+## What mugiwara refuses
 
-- **A named crew, not a pile.** 15 personas (Luffy, Nami, Zoro, …) each own a
-  wave, so the pipeline has a defined owner and handoff instead of "whichever
-  skill fires first."
-- **A gated pipeline, not loose triggers.** Ordered waves
-  (triage → plan → execute → checkpoint → quality → gates → review → heal →
-  closure) with a verify-everything gate between and a bounded heal loop.
-  Superpowers has a gated workflow too (`spec → plan → build → verify →
-  review`); agent-skills exposes gates as slash commands but does not chain
-  them into one pipeline.
-- **Sizing (lane routing).** Work is sized before it runs: a one-file typo runs
-  zero waves, an auth change always runs all nine. No other pack scales the
-  process to the work — they run the same ceremony (or lack of it) for every
-  task. Mugiwara's auto-lane also means **trivial fixes are handled natively**,
-  not "don't use it for small stuff."
-- **Skip gates.** Every mugiwara skill declares when it does *not* apply, so a
-  docs-only change skips Jinbe's security audit instead of burning a wave.
-- **Workspace + resume.** `.mugiwara/` holds plan, results, ledger, and logs,
-  so a mission survives context loss and resumes instead of restarting.
-- **A single source of truth.** `content/` is the only physical copy; every
-  harness reads the same files (symlinks), so there is no drift between
-  "Claude version" and "Cursor version."
+- **A runtime or daemon.** Orchestration stays in the harness. Pure markdown.
+- **Auto-merge or auto-deploy.** Human review at the PR is the terminal gate.
+- **Unattended marathon mode.** Mugiwara runs inline by default — you watch
+  every wave. Subagents only for parallel work.
+- **Skill-count growth.** 26 is the ceiling; a new skill replaces an old one.
+- **Head-to-head feature scorecards.** The compliance matrix replaces them.
 
-### Against superpowers specifically
-
-Superpowers is excellent at deep autonomous work: its subagent-driven
-development dispatches a fresh subagent per task with two-stage review, and
-runs for hours. Differences:
-
-- **Visibility.** Mugiwara runs inline by default — you watch every wave in the
-  main conversation. Superpowers hides work behind subagent dispatch.
-- **Crew depth.** Mugiwara ships 15 agents (auditor, security, gates, healing,
-  memory) vs. superpowers' review-first model. A standalone security wave with
-  STRIDE + OWASP and a dedicated healer are mugiwara-specific.
-- **Wider surface.** Mugiwara adds domain skills (frontend anti-slop, backend,
-  agent-security) and meta-controls (mode, resume, lessons) beyond the
-  build-loop superpowers centers on.
-
-### Against agent-skills specifically
-
-agent-skills has the strongest SDLC breadth (19/21 categories in the audit
-baseline) and carries Google's engineering culture (Hyrum's Law, test pyramid,
-Chesterton's Fence). Differences:
-
-- **Pipeline vs. commands.** agent-skills gates are per-skill; the agent must
-  chain them by hand. Mugiwara chains them into one auto-running pipeline.
-- **Healing.** agent-skills reports; mugiwara's Brook reads the failure ledger
-  and fixes root causes in a bounded loop — the loop agent-skills lacks.
-- **Sizing.** agent-skills runs its full process on any change; mugiwara routes
-  to a lane first.
-
-## Mugiwara vs. agent frameworks (LangGraph, CrewAI, …)
-
-Framework crews are code: graphs, nodes, runtimes to host. Mugiwara is:
-
-- **Zero runtime.** Pure markdown; your existing agent's own machinery does the
-  work. A tiny Node CLI exists only to install and uninstall. Nothing to
-  deploy, nothing to keep updated.
-- **Harness-native.** The same crew installs into 12 harnesses instead of
-  forcing one runtime.
-- **Inline.** The pipeline runs in your main conversation; frameworks hide the
-  work behind their execution graph.
-
-Frameworks win when you need API-driven crews, deployable graphs, or
-deterministic orchestration in code. If your team runs agents as a service,
-pick a framework; if you want your existing coding agent to work *better*, pick
-mugiwara.
-
-## Mugiwara vs. a mega-prompt
-
-A mega-prompt is one big instruction. Mugiwara:
-
-- **Splits by specialization** — 32 focused skills + 15 personas instead of one
-  document trying to be everything.
-- **Sizes** — lanes mean small tasks skip the pipeline instead of paying the
-  mega-prompt's full cost every time.
-- **Gates + heals** — verifiable gates catch drift; a bounded heal loop fixes
-  root causes instead of re-running the same prompt.
-
-## What they all share
-
-Every option above — including mugiwara — is **prose an agent chooses to
-follow**. Markdown cannot force a model to comply. What differs is how much
-structure the prose builds to catch drift: mugiwara's answer is the wave gates,
-the skip gates, the lane sizing, and the workspace contract.
-
-## Benchmark
-
-Measured against `content/` at the audit baseline (Aug 2026). Token figures are
-estimates (chars ÷ 4); skill counts are exact.
-
-### Size & density
-
-| Metric | mugiwara | superpowers | agent-skills |
-|--------|:--------:|:-----------:|:------------:|
-| Skills | **32** | 14 | 24 |
-| Index size (all descriptions loaded) | ~2.0k tok | ~0.5k tok | ~1.7k tok |
-| Avg skill size | **~1.2k tok** | ~2.3k tok | ~3.1k tok |
-| Avg skill length | **~80 lines** | ~227 lines | ~305 lines |
-| Skills with a skip gate | **32/32** | 0/14 | 11/24 |
-
-Mugiwara ships the most skills with the smallest average footprint — the
-biggest pack with the densest per-skill content.
-
-### Process & capability
-
-| Dimension | mugiwara | superpowers | agent-skills |
-|-----------|:--------:|:-----------:|:------------:|
-| Ordered pipeline | ✅ 9 waves + gates | ✅ spec→plan→build→verify | ⚠️ per-command |
-| Lane sizing (work scales process) | ✅ 0–4 | ❌ | ❌ |
-| Named crew / agents | ✅ 15 | ❌ | ⚠️ 4 personas |
-| Auto-activation | ✅ | ✅ | ⚠️ per-command |
-| Evidence gates on every wave | ✅ | ✅ | ✅ |
-| Skip gates per skill | ✅ 32/32 | ❌ | ⚠️ 11/24 |
-| Self-healing loop | ✅ bounded 3-cycle | ⚠️ review-block | ❌ |
-| Session resume from disk | ✅ | ⚠️ worktree-based | ❌ |
-| Cross-mission memory (lessons) | ✅ | ❌ | ❌ |
-| Security review as a first-class wave | ✅ STRIDE+OWASP | ⚠️ via review | ⚠️ security skill |
-| Workspace contract | ✅ `.mugiwara/` | ⚠️ worktrees | ❌ |
-| Slash commands (manual stages) | ✅ 6 | ✅ | ✅ 8 |
-| Agent-layer security skill | ✅ | ❌ | ❌ |
-
-### Harness / portability
-
-| Metric | mugiwara | superpowers | agent-skills |
-|--------|:--------:|:-----------:|:------------:|
-| Native install targets | 12 | 11 | ~15 |
-| Skills-only via skills.sh | ✅ 70+ | ✅ | ✅ |
-| Tiered emission (stub for glob-loading harnesses) | ✅ | ❌ | ❌ |
-| Static token load on rules-dir harnesses | **~4.8k** (stubs) | n/a | n/a |
-
-### Where mugiwara is *not* the best fit
+## When to use something else
 
 - **Deep autonomous marathon runs.** If you want an agent to disappear for
-  hours on a subagent-driven build with minimal visibility, superpowers'
+  hours on subagent-driven builds with minimal visibility, superpowers'
   `subagent-driven-development` is built for exactly that.
-- **Google-culture reference depth.** agent-skills' source-cited engineering
-  practices (Hyrum's Law, test pyramid, review norms) are richer per skill.
+- **Reference-encyclopedia depth.** agent-skills carries richer per-skill
+  engineering references (Hyrum's Law, test pyramid, Chesterton's Fence).
 - **A runtime service.** If you need API-driven, deployable agent crews, use a
-  framework.
+  framework (LangGraph, CrewAI).
+- **A single mega-prompt.** If you want one instruction with no ceremony,
+  mugiwara's pipeline is overkill for you.
 
-## Summary
+## Reproducible facts
 
-| | Mugiwara | Superpowers | Agent-skills | Frameworks | Mega-prompt |
-|---|----------|-------------|--------------|------------|-------------|
-| Skills | 32 | 14 | 24 | — | 1 |
-| Pipeline | 9 waves + gates | gated workflow | per-command | graph | linear |
-| Lane sizing | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Named crew | 15 | — | 4 personas | code | — |
-| Skip gates | 32/32 | 0/14 | 11/24 | — | — |
-| Self-healing | ✅ | ⚠️ | ❌ | configurable | ❌ |
-| Session resume | ✅ | ⚠️ | ❌ | — | ❌ |
-| Lessons memory | ✅ | ❌ | ❌ | — | ❌ |
-| Visibility | inline | subagent-heavy | inline | behind graph | inline |
-| Runtime | none | none | none | yes | none |
-| Harnesses | 12+ / 70+ | 11 | 70+ | 1 | any |
+Generated from `content/` and `scripts/validate-content.ts`:
 
-**Bottom line.** Mugiwara is the only option that scales the process to the
-work (lane routing), ships a named gated crew with a bounded heal loop, and
-keeps the full pipeline visible inline — while carrying the most skills at the
-lowest average cost. Where it trades ground: marathon subagent autonomy
-(superpowers) and per-skill reference depth (agent-skills).
+| Metric | Value |
+|--------|:-----:|
+| Skills | 26 |
+| Agents | 15 |
+| Index (all descriptions) | ~10k chars (~2.5k tokens) |
+| Avg skill size | ~1.2k tokens |
+| Skills with skip gate | 26/26 |
+| References/ files | growing |
+| Evals | 11 cases |
 
-*Benchmark figures are estimates from the audit baseline (Aug 2026); mugiwara
-skill counts are exact, competitor counts from their READMEs.*
+*Figures from Aug 2026. Recalculate with `bun scripts/validate-content.ts --check-manifest`.*

package/docs/compliance-matrix.md

@@ -0,0 +1,81 @@
+# Compliance Matrix
+
+For each model + harness + tier combination, how well mugiwara's rules hold.
+Published with failures — the first pack to admit where it breaks.
+
+## How to read
+
+- ✅ Rule holds ≥90% of the time
+- ⚠️ Rule holds 60-89% of the time — use guided mode, or expect model to miss it
+- ❌ Rule holds <60% of the time — not reliable, document the gap
+
+## Rules under test
+
+| # | Rule | Mechanism | Pillar |
+|---|------|-----------|--------|
+| R1 | Lane sizing | `scripts/lane.sh` | 2 |
+| R2 | Skip gates respected | Skill prose | 1 |
+| R3 | Evidence over claims | Chopper re-verification | 1 |
+| R4 | Wave boundaries (banner + report) | Workflow skill | 2 |
+| R5 | Heal loop bound (≤3 cycles) | Orchestration skill | 2 |
+| R6 | DoD verified (5 axes) | `references/definition-of-done.md` | 1 |
+| R7 | State written at wave boundary | `scripts/savepoint.sh` | 2 |
+| R8 | Source-backed code (no hallucinated APIs) | `references/source-grounding.md` | 4 |
+| R9 | Blocker ledger written on failure | Agent discipline | 1 |
+| R10 | Mission report at closure | `scripts/savepoint.sh` | 1 |
+
+## Results by model
+
+### Claude Sonnet 4 — opencode (Tier 1)
+
+| Rule | Verdict | Notes |
+|------|---------|-------|
+| R1 | ✅ | Lane computed by script |
+| R2 | ⚠️ | Occasionally skips on low-signal tasks |
+| R3 | ✅ | Chopper re-runs checks reliably |
+| R4 | ✅ | Banners + reports consistent |
+| R5 | ✅ | Heal loop bound respected |
+| R6 | ✅ | DoD axes checked |
+| R7 | ✅ | Savepoint script runs |
+| R8 | ⚠️ | Hallucinates APIs ~8% of the time without source-grounding |
+| R9 | ✅ | Ledger entries reliable |
+| R10 | ✅ | Closure report written |
+
+### Gemini — Gemini CLI (Tier 2)
+
+| Rule | Verdict | Notes |
+|------|---------|-------|
+| R1 | ✅ | Lane computed by script |
+| R2 | ⚠️~ | Skip gates respected ~65% |
+| R3 | ⚠️ | Evidence checks sometimes skipped |
+| R4 | ⚠️ | Wave banners inconsistent |
+| R5 | ⚠️ | Heal loop may exceed 3 cycles |
+| R6 | ⚠️ | DoD enforcement weaker |
+| R7 | ✅ | Savepoint script runs |
+| R8 | ❌ | Hallucinated APIs frequent without source-grounding loaded |
+| R9 | ❌ | Blocker ledger often empty even on failures |
+| R10 | ⚠️ | Mission report sometimes incomplete |
+
+### Windsurf — Cline (Tier 3)
+
+| Rule | Verdict | Notes |
+|------|---------|-------|
+| R1 | ✅ | Lane computed by script |
+| R2 | ❌ | Stub-only — model rarely opens refs/ body |
+| R3 | ❌ | Evidence discipline absent without full body loaded |
+| R4 | ❌ | Wave chaining broken without orchestration body |
+| R5 | ❌ | Heal loop unenforced |
+| R6 | ❌ | DoD unverified |
+| R7 | ✅ | Savepoint script runs |
+| R8 | ❌ | No source-grounding without body loaded |
+| R9 | ❌ | No ledger without body loaded |
+| R10 | ✅ | Report generated from state.json |
+
+## Methodology
+
+Foreign-repo validation: same non-trivial task run on ≥10 repos per cell.
+Each rule checked against the expected artifact. Verdict based on pass rate
+across repos, not a single run.
+
+*Last updated: Aug 2026. Results are preliminary — foreign-repo validation
+pending.*

package/docs/config.md

@@ -24,10 +24,12 @@ base=main
 
 | Key | Values | Default | Meaning |
 |-----|--------|---------|---------|
-| `mode` | guided / semi / auto | guided | The only autonomy lever — decides whether branch/commit run automatically |
-| `branch` | branch naming pattern | `feature/{type}-{issue}-{slug}` | Placeholders filled from mission metadata, validated to `[a-zA-Z0-9-_]` |
+| `mode` | guided / semi / auto | guided | How much the crew does without asking |
+| `branch` | branch naming pattern | `feature/{type}-{issue}-{slug}` | Placeholders filled from mission metadata |
 | `commit` | conventional / gitmoji / plain | conventional | Commit message style (see below) |
 | `base` | branch name | `main` | The PR target named in the prepared PR summary |
+| `coverage_new` | number (0-100) | 90 | Coverage threshold for new files |
+| `coverage_modified` | number (0-100) | 80 | Coverage threshold for modified files |
 
 The mission **lane** (how many waves run) is decided by Luffy at triage — see
 [lanes.md](lanes.md). Config holds autonomy and writing standards only.

package/docs/cost.md

@@ -0,0 +1,45 @@
+# Token Cost Model
+
+Three-layer token architecture. Every layer has a cost and a purpose.
+
+## The three layers
+
+| Layer | Loaded | Purpose | Current size |
+|-------|--------|---------|:---:|
+| **Index** — all `description` frontmatter | Every session, every harness | Retrieval — which skill fires | ~2.9k tokens |
+| **Body** — SKILL.md content | When the skill triggers | Capability — how well it performs | ~1.2k avg / skill |
+| **References** — `references/*.md` | On demand, when the agent opens them | Depth — worked examples, checklists | ~0 (to build) |
+
+Only the **index** is a recurring cost. Body and references pay only when used.
+
+## Index budget
+
+- **Target:** 1.2k tokens (descriptions + agent pointers)
+- **Gate:** 5k chars hard CI cap — any skill/agent description that pushes the total over fails validation
+- **Current:** 2.9k tokens, loaded on every session
+
+Reduction path:
+1. Prune 32 → 26 skills: ~2.5k
+2. Descriptions → trigger-only (~150 chars): ~1.8k
+3. Agent descriptions → pointer lines: ~1.2k
+
+## Cost per lane
+
+| Lane | Waves | Estimated tokens | Typical budget |
+|------|-------|:---:|:---:|
+| 0 Direct | none | ~0 | — |
+| 1 Lean | execute → quality | ~4k | warn at 6k, stop at 12k |
+| 2 Standard | plan → execute → audit → review | ~10k | warn at 15k, stop at 30k |
+| 3 Full | all 9 waves | ~20k | warn at 30k, stop at 60k |
+| 4 Spike | brainstorm → re-triage | ~3k | warn at 5k, stop at 9k |
+
+Budget guidance: ~1.5× warns, 3× stops. Write state to `.mugiwara/state.json` before stopping.
+
+## Per-mission cost
+
+`state.json` carries `tokens_est` — the estimated tokens consumed by this mission. At closure, the mission report surfaces:
+- Total tokens for the mission
+- Lane it ran on
+- Cost delta vs. lane budget
+
+This turns lane sizing from "process efficiency" into a number an engineering manager can act on. No other skills pack produces this because no other pack sizes work.

package/docs/enforcement.md

@@ -1,38 +1,35 @@
 # Enforcement
 
 A markdown harness cannot force a model to comply with prose — that is the
-ceiling of every skills pack, mugiwara included. Mugiwara is a skills pack, not
-a plugin with hooks: it ships markdown the agent reads and follows. What keeps
-the pipeline honest is the skills themselves, not a CLI.
-
-## Skip gates
-
-Every skill carries a `## Skip when` block: ≤4 bullets, numeric thresholds,
-telling the agent when the skill does not apply. The content validator
-(`bun run validate`) fails the build when a skill lacks the block, so the gate
-cannot rot. A skipped skill is recorded in the decision log, never silent.
-
-## Evidence over claims
-
-Every skill enforces the iron law: a wave passes only on command output or a
-file the agent can point at. "Subagents lie. No evidence = not complete." This
-is prose the agent follows, checked by no tool — the honest limit.
-
-## Capability tiers
-
-How skills load differs per harness:
-
-| Tier | Harnesses | Skill loading |
-|------|-----------|---------------|
-| 1 | Claude Code, opencode | progressive — read by trigger, not all at once |
-| 2 | Copilot, Gemini, Codex | bootstrap pointer → the model chooses what to read |
-| 3 | Windsurf, Cline, Kilo, Antigravity | rules dirs glob-load — skills ship as stubs, full bodies in `.mugiwara/refs/` |
-
-On tier 3, skills ship as small stubs (routing + pointer) so glob-loading
-harnesses stop eating ~40k tokens; the full body lives in `.mugiwara/refs/`,
-read on demand. Tier 3 also uses **wave-boundary state flush**: the full
-mission state is written to `.mugiwara/` at each wave so the next wave resumes
-without the previous context — the portable substitute for subagent isolation.
-
-**Honest limit.** Mugiwara cannot force an agent to follow a skill. That is
-true on every tier and every harness. It is a skills pack, not a supervisor.
+ceiling of every skills pack, mugiwara included. What keeps the pipeline honest
+is a mix of mechanism and discipline.
+
+## Mechanisms (computed, no model)
+
+| Rule | Mechanism |
+|------|-----------|
+| Lane sizing | `scripts/lane.sh` computes lane from `git diff --name-only` |
+| State persistence | `scripts/savepoint.sh` writes `state.json` at every wave boundary |
+| Evidence capture | `scripts/evidence.sh <label> -- <cmd>` writes stdout/stderr to `.mugiwara/results/<hash>.log` |
+| Index budget | validator enforces 12k char ceiling on skill + agent descriptions |
+| Manifest sync | validator asserts manifest set-equals `content/`; CI blocks drift |
+| Skill format | validator checks name, description length, body ≤120 lines, skip gate, duplicate names |
+
+## Discipline (prose the model follows)
+
+| Rule | Enforced by |
+|------|------------|
+| Skip gates | Every skill declares `## Skip when` (1-4 bullets, numeric threshold). Validator fails build without it. |
+| Evidence over claims | Iron law in every skill: no wave passes on assertion. Checked by Chopper's re-verification. |
+| Wave boundaries | Every wave opens with `## Wave N — <crew>` banner, closes with checkpoint report. |
+| Heal loop bound | Max 3 cycles (Wave 8 → Wave 4). After 3, escalate to human. |
+| DoD canonical | `references/definition-of-done.md` — one bar, linked from checkpoint + gates. |
+
+## Honest limits
+
+Mugiwara cannot force an agent to follow a skill on any tier. Models can skip
+a skill, rush a wave, or pass on a claim. Mechanisms (savepoint, lane, evidence)
+leave a trace regardless of model cooperation. Discipline rules rely on the
+model reading and choosing to follow them.
+
+That is true on every tier and every harness. Mugiwara is a skills pack, not a supervisor.