@ionivetech/mugiwara 0.3.0 → 0.5.0

package/docs/comparison.md

@@ -1,63 +1,58 @@
-# Comparison
-
-How mugiwara fits against the alternatives.
-
-## Mugiwara vs. plain skills (agent-skills / skills.sh)
-
-The [agent-skills](https://github.com/addyosmani/agent-skills) ecosystem ships
-standalone skills that an agent picks up on demand. Mugiwara ships the same
-portable `SKILL.md` format — and also ships:
-
-- **A named crew** — personas (Luffy, Nami, Zoro, …) on top of the skills, so
-  the pipeline has a defined owner per wave instead of "whichever skill fires."
-- **A pipeline, not a pile** — ordered waves (triage → plan → execute →
-  checkpoint → quality → gates → review → heal → closure) with gates between.
-- **Evidence discipline** — no wave passes on a claim; the owning role runs the
-  checks and shows output.
-- **A workspace contract** — `.mugiwara/` holds plan, results, ledger, and
-  logs, so a mission survives context loss.
-
-You can still install just the skills (`npx skills add ionivetech/mugiwara`).
-
-## 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 subagent
-  machinery does the work. Nothing to deploy, nothing to keep updated.
-- **Harness-native** — installs into Claude Code, opencode, Copilot, Gemini,
-  Codex, Cursor, and 70+ tools rather than forcing one runtime.
-- **Inline** — the pipeline runs in your main conversation (see
-  [execution-model.md](execution-model.md)); frameworks hide the work behind
-  their own execution graph.
-
-## Mugiwara vs. a single mega-prompt
-
-A mega-prompt gives you one big instruction. Mugiwara:
-
-- **Splits by specialization** — 25 focused skills + 15 personas instead of one
-  document that tries to be everything, so each phase has a tight contract.
-- **Is gated** — every wave has a verifiable gate and a recorded reason, so
-  drift is caught early.
-- **Heals** — a bounded 3-cycle heal loop reads the failure ledger and fixes
-  root causes, instead of re-running the same mega-prompt.
-
-## When NOT to use mugiwara
-
-- **One-line fixes** — Luffy routes trivia straight to execution; you don't
-  need the crew for a typo.
-- **You want a framework runtime** — if you need orchestration in code,
-  deployable graphs, or API-driven crews, a framework is the right tool.
-- **You want the crew to merge/deploy** — mugiwara deliberately stops at push +
-  PR. Human review is the terminal gate.
-
-## Summary
-
-| | Mugiwara | Plain skills | Framework crews | Mega-prompt |
-|---|----------|--------------|-----------------|-------------|
-| Runtime | none | none | yes | none |
-| Pipeline | ordered waves + gates | on-demand | graph | linear |
-| Visibility | inline in your chat | inline | behind the graph | inline |
-| Evidence gates | yes | no | configurable | no |
-| Self-healing | yes (3-cycle loop) | no | configurable | no |
-| Harnesses | 12+ | 70+ | one per framework | any |
+# Positioning
+
+What mugiwara is and when to use something else.
+
+## What mugiwara is
+
+**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.
+
+- **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.
+
+## What mugiwara refuses
+
+- **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.
+
+## When to use something else
+
+- **Deep autonomous marathon runs.** If you want an agent to disappear for
+  hours on subagent-driven builds with minimal visibility, superpowers'
+  `subagent-driven-development` is built for exactly that.
+- **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 (LangGraph, CrewAI).
+- **A single mega-prompt.** If you want one instruction with no ceremony,
+  mugiwara's pipeline is overkill for you.
+
+## Reproducible facts
+
+Generated from `content/` and `scripts/validate-content.ts`:
+
+| 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 |
+
+*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,15 @@ 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.
 
 Missing config on read = `guided`. Flip mid-mission with
 `mugiwara mode <guided|semi|auto>` — the change applies from the next wave,

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/developer-onboarding.md

@@ -18,35 +18,39 @@ bun install
 ```
 mugiwara/
 ├── content/            # single source of truth: skills/ + agents/ markdown
-├── agents/             # synced copy of content/agents (plugin copies at repo root)
-├── skills/             # synced copy of content/skills
+├── agents/             # symlink → content/agents (Claude Code plugin reads plugin root)
+├── skills/             # symlink → content/skills
 ├── src/                # CLI, installer, targets, frontmatter parser
 ├── scripts/            # validate-content, sync-version, run-evals, install scripts
 ├── test/               # vitest suite
 ├── .opencode/plugins/  # opencode plugin (registers crew at config load)
-├── .claude-plugin/     # Claude Code marketplace + sync.sh
+├── .claude-plugin/     # Claude Code marketplace + sync.sh (symlink guard)
 └── docs/               # these docs
 ```
 
 ## The source of truth
 
-`content/` is canonical. The repo-root `agents/` and `skills/` copies are
-generated for harnesses that read the repo directly:
+`content/` is the only physical source. The repo-root `agents/` and `skills/`
+are **symlinks** into it, so harnesses that read the plugin root (Claude Code
+marketplace) see the same files — there is no copy to drift. On a fresh clone
+where the symlinks are missing, recreate them:
 
 ```bash
 sh .claude-plugin/sync.sh
 ```
 
-Always edit `content/`, then sync. `bun run validate --check-sync` fails if the
-copies drift.
+Always edit `content/`. `bun run validate --check-sync` verifies the symlinks
+resolve to `content/` and never diverge.
 
 ## Validation
 
 ```bash
-bun run validate                # 32 skills + 15 agents: names, descriptions, line limits
-bun run validate --check-sync   # plugin copies match content/
+bun run validate                # 32 skills + 15 agents: names, descriptions, skip gates, line limits
+bun run validate --check-sync   # symlinks resolve to content/, never diverge
 bun run typecheck               # tsc --noEmit
-bun run test                    # vitest (43 tests)
+bun run test                    # vitest
+bun run evals                   # eval suite valid (structure + coverage gates)
+bun run evals --run             # optional: execute cases against a model CLI (MUGIWARA_EVAL_CMD)
 ```
 
 ## Editing a skill or agent
@@ -55,8 +59,7 @@ bun run test                    # vitest (43 tests)
 2. Respect the house style (see [skill-anatomy.md](skill-anatomy.md) and
    [agent-anatomy.md](agent-anatomy.md)): evidence over claims, exact commands,
    red flags, ≤120-line skill bodies.
-3. `sh .claude-plugin/sync.sh`
-4. `bun run validate && bun run typecheck && bun run test`
+3. `bun run validate && bun run typecheck && bun run test`
 
 ## Adding a new skill or agent
 
@@ -64,7 +67,8 @@ bun run test                    # vitest (43 tests)
 2. If it's an agent, list its held skills in frontmatter; give it a
    `description` ≥20 chars.
 3. If it's a skill, pick a folder name that matches `name`; description 20–500
-   chars; body ≤120 lines.
+   chars; body ≤120 lines; include a `## Skip when` block (1–4 bullets, numeric
+   thresholds) so the skill knows when it does not apply.
 4. Update the crew/technique tables in `README.md` and the docs (`agents.md`,
    `skills.md`).
 5. Sync + validate + test.

package/docs/enforcement.md

@@ -0,0 +1,35 @@
+# Enforcement
+
+A markdown harness cannot force a model to comply with prose — that is the
+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.

package/docs/getting-started.md

@@ -20,9 +20,19 @@ Pick your harness — every major one is supported. The two easiest:
 /plugin install mugiwara
 ```
 
-Everything else (Copilot, Gemini, Codex, Cursor, Windsurf, Cline, Kilo,
-Antigravity, pi) has a one-command install. See the [install guides](index.md#install-by-harness)
-or the CLI:
+| Harness | Install command |
+|---------|----------------|
+| Claude Code | `/plugin marketplace add ionivetech/mugiwara` then `/plugin install mugiwara` |
+| opencode | `{ "plugin": ["@ionivetech/mugiwara"] }` in `opencode.json` |
+| GitHub Copilot | `copilot plugin marketplace add ionivetech/mugiwara` then `copilot plugin install mugiwara` |
+| Gemini CLI | `gemini extensions install https://github.com/ionivetech/mugiwara` |
+| Codex | `codex plugin marketplace add ionivetech/mugiwara` then `codex plugin add mugiwara@mugiwara` |
+| Cursor | `/add-plugin mugiwara` |
+| Kimi Code | `/plugins install https://github.com/ionivetech/mugiwara` |
+| pi | `pi install git:github.com/ionivetech/mugiwara` |
+| Windsurf, Cline, Kilo, Antigravity | `npx @ionivetech/mugiwara@latest --project . --target <id> --yes` |
+
+Or the CLI for any target:
 
 ```bash
 npx @ionivetech/mugiwara@latest --project ./my-app --target all --yes
@@ -32,45 +42,76 @@ Requires **Node.js >= 20.11**. Bun is optional (build-from-source only).
 
 ## 2. Start a mission
 
-The workflow **auto-activates**: at session start the crew is announced, and
-when you give a non-trivial request the pipeline runs by itself — no need to
-call `/using-mugiwara`. It remains an optional explicit router if you want to
-hand-route a mission. Just ask, no agent names to remember:
+The workflow **auto-activates** at session start. The crew announces itself,
+then give any non-trivial request.
+
+### Small: lane 0–1
+
+```
+> fix the date formatting bug in src/utils/format.ts
+```
+
+Luffy routes it to **Lane 1** (Lean). Zoro reproduces and fixes, Sanji runs
+format + lint + tests. Two waves, visible as compact checkpoint reports. No
+nine-wave ceremony for a one-file bug.
+
+That's lane sizing: the process scales to the work. A typo (Lane 0) runs zero
+waves — the fix happens directly.
+
+### Medium: lane 2
+
+```
+> add a search bar to the products page
+```
+
+Touches frontend + API. Luffy routes to **Lane 2** (Standard). Nami plans 1
+wave with 3-5 tasks, Zoro executes test-first, Chopper audits every criterion,
+Sanji and Franky gate, Robin and Jinbe review.
+
+### Large: lane 3
 
 ```
-> add dark mode to the settings page
+> add role-based access control to the API
 ```
 
-`using-mugiwara` (the front door) routes your request, Luffy classifies it, and
-the wave pipeline runs. Because the crew runs **inline** in your main
-conversation, you watch every wave as it happens — as compact **checkpoint
-reports** (a wave banner, one report per crew member at each stage boundary,
-and a pause when something fails):
+Touches auth — Luffy routes to **Lane 3** (Full). All 9 waves run. Nami plans
+the migration, Zoro executes, Chopper audits, Sanji tests, Franky gates, Robin
+reviews the diff with a breaking-change map, Jinbe runs STRIDE + OWASP, Brook
+heals any failures (max 3 cycles), Luffy closes with a mission report + push +
+ready PR summary.
 
 ```
-  Wave 0  Luffy   triage → route: plan (requirements mostly clear)
-  Wave 2  Nami    plan   → .mugiwara/plans/2026-08-10-dark-mode.md (3 waves)
-  Wave 3  Zoro    execute→ 3 tasks, evidence shown per task
-  Wave 4  Chopper audit  → FAIL: toggle does not persist (ledger written)
-  Wave 8  Brook   heal   → fixed persistence + tests, looped back → PASS
-  Wave 9  Luffy   closure→ report appended to plan, intermediate files cleaned
+  Wave 0  Luffy   triage → route: full pipe (auth/ touched)
+  Wave 2  Nami    plan   → .mugiwara/plans/2026-08-10-rbac.md (2 waves, 5 tasks)
+  Wave 3  Zoro    execute→ 5 tasks, evidence per task
+  Wave 4  Chopper audit  → PASS: all criteria met, commit hygiene clean
+  Wave 5  Sanji   quality → PASS: lint 0, 312 tests green
+  Wave 6  Franky  gates  → PASS: new 94%, modified 87%, build green
+  Wave 7  Robin   review → 2 minor findings (batched)
+  Wave 7  Jinbe   security→ PASS: STRIDE clean, 0 high
+  Wave 9  Luffy   closure→ mission report + push + ready PR summary
 ```
 
-Prefer to drive the stages yourself? Every stage has a slash command that loads
-the skill, runs the crew role inline, and bridges state from `.mugiwara/`:
-`/mugiwara-plan`, `/mugiwara-execute`, `/mugiwara-review`, `/mugiwara-security`,
-`/mugiwara-heal`, `/mugiwara-ship`. You can jump into any stage.
+The crew runs **inline** in your main conversation — every wave reports as a
+compact checkpoint. Subagents only for parallel task batches.
+
+Prefer to drive stages yourself? Every stage has a slash command:
+`/mugiwara-plan`, `/mugiwara-execute`, `/mugiwara-review`,
+`/mugiwara-security`, `/mugiwara-heal`, `/mugiwara-ship`. Jump into any stage.
 
 ## 3. What you do during a mission
 
-Almost nothing, in the default mode:
+Almost nothing in `guided` mode:
 
 - Answer Nami's clarifying questions (one batched round before planning).
-- Give the plan an explicit GO when presented (or switch to `semi`/`auto`).
+- Give the plan an explicit GO when presented.
 - Review Brook's rollback note if a risky fix is proposed.
-- In every mode, open the PR at the end — the crew pushes the branch and hands
-  you the verdict file with a ready PR summary block. The crew never merges,
-  deploys, or creates a PR itself.
+- In every mode, **open the PR at the end** — the crew pushes the branch and
+  hands you a verdict file with a ready PR summary. The crew never creates a
+  PR, merges, or deploys.
+
+Switch to `semi` or `auto` if you want the crew to self-manage branch, commits,
+and ambiguities. See [modes](modes.md).
 
 ## 4. The `.mugiwara/` workspace
 
@@ -78,19 +119,40 @@ Every mission writes to `.mugiwara/` at the repo root:
 
 ```
 .mugiwara/
-├── config         # mode/branch/commit settings (gitignored)
-├── spec/          # brainstorm output
-├── plans/         # the clean execution plan (source of truth from Wave 2)
-├── results/       # audit, quality, gate, closure reports
-├── review/        # review + security findings
-├── issues/        # blocker ledger
-└── logs/          # decision + check-in log (deleted at cleanup)
+├── config          # mode, branch, commit, base, coverage thresholds
+├── state.json      # computed at every wave boundary by scripts/savepoint.sh
+├── spec/           # brainstorm output
+├── plans/          # clean execution plan (source of truth from Wave 2)
+├── results/        # audit, quality, gate, closure reports + evidence logs
+├── reports/        # human-readable mission reports
+├── review/         # review + security findings
+├── issues/         # blocker ledger
+├── refs/           # full skill/agent bodies for glob-loading harnesses
+└── logs/           # decision log + cross-mission lessons
 ```
 
-## 5. Next steps
+**Savepoint** runs at every wave boundary — `state.json` carries lane, wave,
+files, blockers, heal cycle, and token budget. Resume reads one file instead of
+six. See [audit-trail.md](audit-trail.md) for the full artifact map.
+
+## 5. Configuration
+
+`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global):
+
+| Key | Default | What it controls |
+|-----|---------|-----------------|
+| `mode` | guided | Autonomy: guided/semi/auto |
+| `branch` | `feature/{type}-{issue}-{slug}` | Branch naming pattern |
+| `commit` | conventional | Commit style: conventional/gitmoji/plain |
+| `base` | main | PR target branch |
+| `coverage_new` | 90 | Coverage % for new files |
+| `coverage_modified` | 80 | Coverage % for modified files |
+
+## 6. Next steps
 
-- Learn the [execution model](execution-model.md) — why everything is visible.
-- Set your [mode](modes.md) — `guided` asks at every gate, `semi`/`auto`
-  self-answer.
-- Read the [config reference](config.md) — branch/commit/PR writing standards.
-- Meet the [crew](agents.md).
+- Meet the [crew](agents.md) — 15 agents with permission boundaries.
+- Browse the [skills](skills.md) — 26 skills with the 3-layer disclosure model.
+- Understand the [lanes](lanes.md) — how work is sized before it runs.
+- Set your [mode](modes.md) — guided/semi/auto.
+- Read the [audit trail](audit-trail.md) — every artifact and how to review it.
+- See the [compliance matrix](compliance-matrix.md) — rule compliance per model.

package/docs/harness-matrix.md

@@ -0,0 +1,41 @@
+# Harness Matrix
+
+What actually differs per harness tier. Every skill and agent file ships to every harness, but behavior differs in three tiers.
+
+| Tier | Harnesses | Skills | Agents | `references/` | Scope |
+|------|-----------|--------|--------|:---:|-------|
+| **1** | Claude Code, opencode | Native, auto-trigger per skill | Real, dispatchable | Yes | global + project |
+| **2** | Gemini, Codex, Copilot | Full body in rules dir + bootstrap pointer | Markdown only | Yes | project only |
+| **3** | Windsurf, Cline, Kilo, Antigravity | Stub; body in `.mugiwara/refs/` | Stub | Yes | project only |
+
+## Behavioral differences
+
+### Tier 1 — Full
+
+- Skills auto-trigger when `description` frontmatter matches the task.
+- Agents are dispatchable subagents with isolation.
+- Progressive disclosure works: description → body → `references/`.
+- Global scope supported — install once, use in every project.
+
+### Tier 2 — Skills only
+
+- Agent files are markdown — the main thread embodies the persona, no subagent dispatch.
+- Skills load as rules files; the model chooses which to read per task.
+- **Project scope only** — `generic.ts` throws on global scope.
+- `references/` files are copied to `.mugiwara/refs/` and reachable.
+
+### Tier 3 — Stubs
+
+- Rule directories get **stub files** — the frontmatter and a pointer to `.mugiwara/refs/`.
+- Full body is loaded only when the agent opens the reference file.
+- Saves ~40k tokens of glob-load. Trade: the model must decide to open the ref.
+- **Project scope only.**
+- `references/` files are copied to `.mugiwara/refs/` — depth is available, just not auto-loaded.
+- Wave-boundary state flush: savepoint writes `state.json` so the model has computed state to resume from.
+
+## What's the same everywhere
+
+- All 32 (→ 26) skill directories ship to every harness.
+- All 15 agent markdown files ship to every harness.
+- `references/` files are always copied.
+- The workflow, lane sizing, and evidence discipline are identical — the difference is in how the model loads them.

package/docs/index.md

@@ -1,11 +1,14 @@
 # Mugiwara Docs
 
 The Straw Hat crew of AI agents and skills. These docs cover what the crew is,
-how to adopt it, and how each harness installs it. The crew is pure markdown —
-no runtime, no daemons, nothing to host. It ships **15 agents** and **32
-skills**, and the workflow **auto-activates** at session start — a non-trivial
-request runs the pipeline by itself, with `/using-mugiwara` as an optional
-explicit router.
+how to adopt it, and how each harness installs it. The crew is markdown plus a
+small Node CLI (`mugiwara`) — no daemons, nothing to host. It ships **15
+agents** and **32 skills**, and the workflow **auto-activates** at session
+start — a non-trivial request runs the pipeline by itself, with
+`/using-mugiwara` as an optional explicit router. Work is **sized to a lane**
+before it runs: small fixes skip the pipeline, sensitive changes run the full
+nine waves, and every wave passes only on **evidence**, never on a spoken
+claim.
 
 ## Start here
 
@@ -20,6 +23,8 @@ explicit router.
 | [The techniques](skills.md) | All 32 skills and what each enforces |
 | [The wave pipeline](workflow.md) | How a mission flows Wave 0 → Wave 9 |
 | [Execution model](execution-model.md) | Inline-by-default: why the crew runs in your main conversation |
+| [Lanes & sizing](lanes.md) | How Luffy sizes work at triage: Lane 0–4, escalation, budget |
+| [Enforcement](enforcement.md) | Skip gates, evidence over claims, and capability tiers |
 | [Git discipline](git-strategy.md) | Commits, branches, save-points — and why the executor commits |
 
 ## Install by harness
@@ -41,6 +46,7 @@ explicit router.
 |-----|----------------|
 | [Skill anatomy](skill-anatomy.md) | How a mugiwara skill file is structured |
 | [Agent anatomy](agent-anatomy.md) | How a mugiwara agent file is structured |
+| [Troubleshooting](troubleshooting.md) | Common problems and how to fix them |
 | [Developer onboarding](developer-onboarding.md) | Repo layout, validation, tests, contributing |
 
 ## Resources