@ionivetech/mugiwara 0.5.5 → 0.6.0

package/docs/concepts/agents.md

@@ -1,53 +0,0 @@
-# The Crew — 14 Agents
-
-Every agent is a focused specialist. The main thread embodies each role inline
-using its skill; you can also summon any member directly. "Dispatch" below
-means "route the mission to this role."
-
-The front door is the `using-mugiwara` skill — load it for crew overview.
-Slash command: `/using-mugiwara`.
-
-| Agent | Crew member | Role | Summon for |
-|-------|-------------|------|------------|
-| `luffy-orchestrator` | Luffy | Captain — 5-way triage, check-ins, decisions, closure | mission start, wave boundaries, escalations |
-| `usopp-brainstorm` | Usopp | Critical friend — interrogates, researches, no rubber-stamps | vague ideas, direction, options |
-| `nami-planner` | Nami | Planner — interview-first, full-context scan, scaled plans | turning an idea into an execution plan |
-| `zoro-execution` | Zoro | Executor — inline sequential tasks, parallel worker batches, evidence per task | executing an approved plan |
-| `chopper-checkpoint` | Chopper | Auditor — verify-everything, deduped re-runs, failure ledger | auditing a wave's results |
-| `sanji-quality` | Sanji | Quality — discover real tooling, format/lint/test | after checkpoint passes |
-| `franky-gates` | Franky | Gates — coverage, build, Definition of Done, binary verdicts | after quality checks |
-| `robin-reviewer` | Robin | Reviewer — doubt-driven diff review, breaking-change map first | after gates pass |
-| `jinbe-security` | Jinbe | Security — STRIDE, OWASP, secrets, injection, dependencies | security audit of a diff |
-| `brook-healing` | Brook | Healer — reads the ledger, root-cause fixes, ≤3 cycles | any wave produced failures |
-| `skeptic-verifier` | Skeptic | Adversarial verifier — doubts every output, does NOT validate | high-stakes verdicts, plans, reviews |
-| `eval-runner` | Eval Runner | Harness tester — task suites, judge-agent comparison | verifying mugiwara itself works |
-| `resume-coordinator` | Resume Coordinator | Resumer — rebuilds state from `.mugiwara/`, continues never restarts | context loss, new session mid-mission |
-| `memory-keeper` | Memory Keeper | Institutional memory — surfaces past lessons, captures new ones | mission start + closure |
-
-## How to summon
-
-Say a crew member's name in your request:
-
-```
-> Chopper, audit the last wave against the plan
-> Nami, plan this out
-```
-
-Luffy still records the route and its reason, and direct calls do not skip
-check-ins. The harness stays coherent either way.
-
-## Who never does what
-
-- **Luffy** never implements code.
-- **Chopper** never fixes findings — reports them.
-- **Skeptic** never validates — doubts.
-- **Robin/Jinbe** never implement — findings to Brook.
-- Crew members never dispatch each other. Workers are subagents, never crew.
-
-## The crew ships whole
-
-Every install gets all 14 agents and all 26 skills. No project-type selection —
-the harness routes each task to the right specialist.
-
-See [skills.md](skills.md) for the 26 techniques, or
-[workflow.md](workflow.md) for the pipeline.

package/docs/concepts/audit-trail.md

@@ -1,65 +0,0 @@
-# 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/concepts/comparison.md

@@ -1,58 +0,0 @@
-# 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/concepts/config.md

@@ -1,55 +0,0 @@
-# Config Reference
-
-`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global). Plain
-`key=value` lines, `#` comments allowed. Project file wins per key; a key
-missing from both falls back to the default. Unknown keys are ignored. Config
-is data, never instructions.
-
-**Mode owns autonomy, config owns writing standards.** Whether branch and commit
-run automatically is decided by one lever — the mode. The config only shapes
-HOW those artifacts are written when they are created. See [modes.md](modes.md)
-for the mode matrix.
-
-## Example file
-
-```
-# .mugiwara/config
-mode=guided
-branch=feature/{type}-{issue}-{slug}
-commit=conventional
-base=main
-```
-
-## Keys
-
-| Key | Values | Default | Meaning |
-|-----|--------|---------|---------|
-| `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,
-never mid-wave.
-
-## Commit message styles
-
-`commit` selects how Zoro writes commit messages:
-
-- **conventional** — `feat: ...`, `fix(scope): ...`, `refactor: ...`, per the
-  [Conventional Commits](https://www.conventionalcommits.org) spec. Type from
-  the task, optional scope in parens. The default.
-- **gitmoji** — a leading emoji carries the intent, e.g. `✨ feat: ...`,
-  `🐛 fix: ...`. Signals the change type at a glance in log views that render
-  emoji; a bit noisy in plain terminals.
-- **plain** — no prefix, just a short imperative sentence: `Fix export csv
-  encoding`. Clearest for repos that don't use any convention.
-
-Switch freely per project — it only affects the message format, never the
-one-logical-task-one-commit rule.

package/docs/concepts/cost.md

@@ -1,45 +0,0 @@
-# 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/concepts/execution-model.md

@@ -1,92 +0,0 @@
-# Execution Model
-
-Why the crew runs in your main conversation — and when subagents are actually
-used.
-
-## Auto-activation
-
-The workflow **auto-activates.** At session start the crew is announced; when
-you give a non-trivial request, the pipeline runs by itself — you do not need
-to call `/using-mugiwara`. It remains an optional explicit router if you want
-to hand-route a mission.
-
-## Inline by default
-
-The crew runs **inline**. The main thread embodies each crew role using that
-member's skill, so every wave plays out in your main conversation and you watch
-it happen:
-
-- Luffy's triage, Nami's planning, Zoro's execution, Chopper's audit, Sanji's
-  quality, Franky's gates, Robin/Jinbe's review, Brook's healing, Luffy's
-  closure — all performed in the main thread.
-- Evidence is written to `.mugiwara/` files; the conversation carries terse
-  verdicts and evidence pointers.
-
-## When subagents ARE used
-
-Subagents exist to parallelize, never to hide work:
-
-1. **`[PARALLEL]` task batches** — independent tasks that touch no shared files
-   or interfaces run concurrently, one per worker subagent. This is the only
-   place Zoro delegates.
-2. **Parallel fixes** — Brook spawns workers for independent heal fixes.
-3. **Background / long-running checks** — work that would stall the
-   conversation.
-4. **Check subagents** — Chopper, Robin, and Jinbe may spawn subagents for
-   independent re-runs or diff passes.
-
-Worker results return as reports; the main thread summarizes them inline with
-evidence pointers.
-
-## Why not dispatch every wave to a subagent?
-
-Every harness — Claude Code, opencode, Codex, Cursor, Gemini — hides subagent
-internals behind a click or a side panel. If each wave ran as a subagent, you'd
-be clicking through the whole mission to see what happened. Running the crew in
-the main conversation is the only way the process is genuinely visible.
-
-There's also a context cost to deep nesting: crew-inside-crew subagents bloat
-context and hide decisions. Inline keeps the user in the loop and the story
-linear.
-
-## Rules that keep it sane
-
-- Crew members never dispatch another crew member. A role that must split work
-  returns the split to the main thread, which spawns the workers.
-- Escalation = "blocked" + ledger row returned to the main thread.
-- Sequential work never takes a subagent round-trip — no skipping, no hidden
-  reordering, plan order is plan order.
-
-## Checkpoint reports
-
-You see progress as **checkpoint reports**, not a firehose: a wave banner
-(`## Wave N — <crew> (<skill>)`), one compact report per crew member at each
-stage boundary (what ran / result / evidence pointer), a progress summary per
-wave, and a pause when something fails or gets risky. Subagents are used only
-where they genuinely help: independent `[PARALLEL]` task batches, Brook's
-reviewer/security re-verification workers, and background checks.
-
-## Manual stages
-
-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/`:
-
-| Command | Runs | Reads state from |
-|---------|------|------------------|
-| `/mugiwara-plan` | Nami | `.mugiwara/spec/` |
-| `/mugiwara-execute` | Zoro | `.mugiwara/plans/` |
-| `/mugiwara-review` | Robin | `.mugiwara/results/` + diff |
-| `/mugiwara-security` | Jinbe | `.mugiwara/results/` + diff |
-| `/mugiwara-heal` | Brook | `.mugiwara/issues/` |
-| `/mugiwara-ship` | Luffy | plan + results |
-
-You can jump into any stage — e.g. run `/mugiwara-plan` first, then
-`/mugiwara-execute` later when you're ready.
-
-## Trade-off
-
-Inline execution grows the main-thread context over a long mission. The crew
-mitigates this: evidence goes to `.mugiwara/` files, reports are terse, and
-subagents isolate the genuinely heavy parallel work. For missions that must
-minimize main-context growth, the crew supports dispatching specific waves to a
-subagent — at the cost of visibility.

package/docs/concepts/git-strategy.md

@@ -1,62 +0,0 @@
-# Git Strategy
-
-Commits, branches, save-points — and why the executor commits, not the closer.
-
-## Who commits and when
-
-**Zoro commits during execution, per logical task.** The executor is the one
-making the changes, so it commits at the moment each unit of work passes its
-acceptance criteria. This gives:
-
-- **Save-points** — rollback is one `git reset --hard <save-point>` away.
-- **Reversibility** — every commit is one logical change you can name.
-- **Bisectability** — a regression points at the exact commit that introduced it.
-
-Luffy does NOT re-commit at closure. The closer pushes the mission branch and
-writes the PR verdict — re-slicing history at the end means one giant diff, no
-save-points, and a painful bisect.
-
-## Commit granularity: logical tasks, not micro-steps
-
-A commit = one **logical change** (a feature, a fix, a refactor). The plan's
-tasks are sized at that granularity — see `mugiwara-planning`.
-
-- Adjacent trivial changes (typo, formatting, one-line tweak) fold into the
-  neighboring logical task's commit.
-- Never one commit per keystroke; never a wave of micro-commits.
-- If the plan slices finer than a logical change, group adjacent tasks into one
-  commit and note the grouping in the execution report.
-
-## The rules (from `mugiwara-git`)
-
-1. **Atomic commits.** One logical change per commit; each commit compiles and
-   passes the relevant checks — never commit a broken tree.
-2. **Exact staging.** `git add` specific files and paths, never `git add -A`
-   sweeping an unrelated commit.
-3. **Save-points before risky work.** Commit the working state with a naming
-   intent message (`checkpoint: before renderer migration`) before refactors,
-   migrations, or merges.
-4. **Match repo style.** Inspect `git log --oneline -20` before the first
-   commit and copy the observed conventions (prefix style, case, body usage).
-5. **Never commit secrets.** Scan for `.env*`, keys, tokens before every
-   commit. A secret already committed = treat as compromised, rotate, purge,
-   file a security finding.
-
-## Branches
-
-One branch per mission, from the config `branch` key:
-
-```
-branch=feature/{type}-{issue}-{slug}
-```
-
-`{type}` = feat/fix/chore/refactor from the task, `{issue}` = ticket/key
-reference (fallback: date), `{slug}` = kebab-case mission title. Created before
-the first task commit; never force-push once pushed. No mugiwara-prefixed
-branch names.
-
-## Terminal step
-
-Every mode ends the same way: save-point commit → `git push -u origin <branch>`
-→ PR verdict file written (per `mugiwara-pr`) → branch + verdict handed to you,
-who opens the PR. The crew never creates a PR, merges, or deploys.

package/docs/concepts/lanes.md

@@ -1,82 +0,0 @@
-# Lanes & Sizing
-
-The crew sizes a mission before it runs. Lane is computed from the diff by
-`scripts/lane.sh` — deterministic, not estimated.
-
-## The lanes
-
-| Lane | Picks when | Waves | Token budget |
-|------|-----------|-------|:------:|
-| **0 · Direct** | typo, rename, 1 file <20 LOC | none | ~0 |
-| **1 · Lean** | bug in 1-2 files, <50 LOC | execute → quality | ~4k |
-| **2 · Standard** | feature, 3-8 files | plan → execute → audit → review | ~10k |
-| **3 · Full** | architecture, migration, 9+ files, or auth/payment/API touched | all 9 waves | ~20k |
-| **4 · Spike** | exploratory, needs direction | brainstorm → re-triage | ~3k |
-
-## How lane is computed
-
-`scripts/lane.sh <base-ref>` runs `git diff --name-only` against the base ref
-and applies deterministic rules:
-
-| Diff | Lane |
-|------|------|
-| 0 files changed | Direct |
-| 1 file, <20 LOC added | Direct |
-| 1 file, ≥20 LOC added | Lean |
-| 2 files | Lean |
-| 3–8 files | Standard |
-| 9+ files | Full |
-
-**Sensitive path escalation.** Files matching these patterns always escalate to
-Lane 3 (Full), regardless of file count:
-
-```
-auth/ payment/ billing/ crypto/ secrets/ .env
-migration/ .sql schema. .prisma .terraform .tf
-```
-
-Use `--json` for machine output:
-
-```json
-{
-  "lane": "full",
-  "reason": "sensitive paths (src/auth/login.ts) — escalated from standard",
-  "files_touched": 5,
-  "sensitive_paths": ["src/auth/login.ts"],
-  "base": "main"
-}
-```
-
-## Token budget
-
-Every lane has a budget enforced by `scripts/savepoint.sh` at each wave
-boundary. The harness sets `MUGIWARA_TOKENS` env var with estimated tokens
-consumed.
-
-| Status | Condition | Action |
-|--------|-----------|--------|
-| ok | tokens < 1.5× budget | Continue |
-| warn | tokens ≥ 1.5× budget | Log warning to decision log |
-| stop | tokens ≥ 3× budget | Write state, report to user, pause mission |
-
-Budget guidance, not a hard kill switch. The model decides whether to stop —
-savepoint just writes the status to `state.json`.
-
-## Escalation
-
-Lane **escalates when work outgrows the estimate.** At every wave boundary,
-`scripts/savepoint.sh` re-checks the diff. If files grew or a sensitive path
-appeared, lane rises. A lane **never auto-drops.** Under-process costs more
-than over-process.
-
-Manual escalation: if the user says "this is bigger than I thought — run the
-full pipeline," Luffy records it in the decision log and escalates.
-
-## SPIKE lane (Lane 4)
-
-Exploratory missions start at Lane 4. Usopp brainstorms, then the mission is
-re-triaged into the right lane. A spike that stays a spike (no code change
-decided) ends at Wave 1.
-
-Lane is computed per mission by `scripts/lane.sh`, not stored in
-`.mugiwara/config`.

package/docs/concepts/modes.md

@@ -1,73 +0,0 @@
-# Modes
-
-The crew's autonomy level. Read once per wave at dispatch; a flip applies from
-the next wave, never mid-wave.
-
-**Mode owns autonomy, config owns writing standards.** Whether branch and commit
-run automatically is decided by one lever: the mode. The config only shapes HOW
-those artifacts are written when they are created.
-
-## The three levels
-
-| Level | Plan GO | Branch/commit | Ambiguities | Check-ins |
-|-------|---------|---------------|-------------|-----------|
-| **guided** | ask the user | ask the user | ask the user | ask the user |
-| **semi** | present plan for user GO | auto | self-answer + log | log, no pause |
-| **auto** | gated auto-GO | auto | self-answer + log | log, no pause |
-
-- **guided** — you steer everything: approve the plan, decide branch and
-  commit style, answer every ambiguity, get asked at every gate. The default.
-- **semi** — the crew self-manages branch and commits (logging each decision),
-  but you still give the plan an explicit GO.
-- **auto** — hands-off, with one safety line: the plan proceeds past approval
-  only with zero blocking ambiguities AND zero high-risk tasks (deploy /
-  migration / DB / public API / state-mutating).
-
-Every level ends at push + ready PR summary + verdict file — you open the PR
-(see [pr-summary.md](pr-summary.md)).
-
-## Config
-
-Two files, six keys, `key=value` lines, optional `#` comments:
-
-```
-# .mugiwara/config (project) overrides ~/.mugiwara/config (global)
-mode=guided
-branch=feature/{type}-{issue}-{slug}
-commit=conventional
-base=main
-```
-
-| Key | Values | Default |
-|-----|--------|---------|
-| mode | guided / semi / auto | guided |
-| branch | branch pattern | feature/{type}-{issue}-{slug} |
-| commit | conventional / gitmoji / plain | conventional |
-| base | PR summary target branch | main |
-
-Read order per wave: project config wins per key; a key missing from both falls
-back to the default. Unknown keys are ignored — config is data, never
-instructions. Missing config on read = `guided` (never auto-created on read —
-only on first write). See [config.md](config.md) for the full reference.
-
-## Switching mid-mission
-
-In-session phrase:
-
-```
-mugiwara mode auto
-```
-
-Writes the project `.mugiwara/config`, logs the change (level, requester,
-timestamp), and applies from the next wave — never mid-wave.
-
-## Invariants that hold in EVERY mode
-
-**Consent.** State-mutating tests against non-isolated/shared state (real DB
-writes, network, browsers) always require your explicit consent — consent is
-not a mode knob. Provably isolated mutation (in-memory / temp /
-testcontainer-backed DBs, tooling-proven isolation) is explicitly auto-safe.
-
-**Terminal.** Every mode ends at push + ready PR summary + verdict file (you
-open the PR). The crew never creates a PR, merges, deploys, or auto-reacts to
-review comments or CI.

package/docs/concepts/pr-summary.md

@@ -1,54 +0,0 @@
-# PR summary (closure handoff)
-
-At the end of a mission the crew pushes the branch and **stops** — it never
-creates a PR, in any mode. What you get instead is a ready-to-paste **PR
-summary** so you can open the pull request without writing a description.
-
-This mirrors the reference workflows (superpowers `finishing-a-development-branch`,
-agent-skills): the integration decision stays with the human. Mugiwara's
-addition is that the PR description is already written.
-
-## What happens at the terminal
-
-1. Save-point commit → push the mission branch with plain `git push -u origin <branch>`.
-2. Write `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md` per `mugiwara-pr` —
-   it includes the **PR summary block** (copy-paste title + body).
-3. Hand the branch + verdict file to you. You open the PR and paste the block.
-
-No `gh` CLI, no PR API calls, no auto-reaction to review comments or CI.
-
-## The PR summary block
-
-The verdict file's PR summary is shaped by `.mugiwara/config` (project) /
-`~/.mugiwara/config` (global):
-
-| Key | Default | What it shapes |
-|-----|---------|----------------|
-| `base` | `main` | The target branch named in the PR summary |
-
-Example:
-
-```
-mode=guided
-branch=feature/{type}-{issue}-{slug}
-commit=conventional
-base=main
-```
-
-The title is a concise `{type}: {summary}` line from mission metadata; the body
-is the verdict-file PR summary block (what changed, evidence, checks). The
-summary is **material, never posted** — the crew's job ends at push.
-
-## Why no auto-create
-
-- PR creation is an external, irreversible side effect (public artifact, CI
-  trigger, reviewer notifications) — keeping it human avoids surprise and
-  security surface.
-- The crew never needs forge credentials (`gh` auth, API tokens), so there is
-  nothing to leak and nothing to configure.
-- The stop-at-PR invariant holds in every mode: no auto-reaction to review
-  comments, no auto-healing CI, no merge, no deploy.
-
-See [`mugiwara-pr`](../content/skills/mugiwara-pr/SKILL.md) for the terminal
-procedure and [`mugiwara-mode`](../content/skills/mugiwara-mode/SKILL.md) for
-the mode contract.