@ionivetech/mugiwara 0.2.0 → 0.3.0

package/content/skills/mugiwara-git-worktrees/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: mugiwara-git-worktrees
+description: Use when running parallel branch work, keeping the main workspace clean, or reviewing a branch without switching. Isolated worktrees via git worktree add, branch hygiene, and safe cleanup.
+---
+
+# Git Worktrees — Isolated Parallel Branches
+
+Worktrees give each branch its own checkout, so parallel missions, reviews, and experiments never fight over one working tree. Companion to mugiwara-git, not a replacement for commit discipline.
+
+## When to use
+
+- Parallel independent tasks on separate branches that must progress without blocking each other.
+- Keeping the main workspace clean: main checkout stays untouched while risky work lives in a worktree.
+- Reviewing or verifying a branch without switching: open it in a worktree, inspect, discard.
+- Any task so risky you want it physically separate from the current tree.
+
+Prefer a worktree over `git stash` juggling — each branch gets a real checkout, not a rescue from the reflog.
+
+## Process
+
+1. Create the worktree bound to a new branch:
+   `git worktree add -b <branch> <path>` (e.g. `git worktree add -b feature/ABC-123-dark-mode ../dark-mode`).
+2. Work entirely inside `<path>`: edit, commit, push there. Treat it as the only home of that branch.
+3. Do not touch that branch from the main checkout, and vice versa. Two tasks never share one worktree.
+4. Verify the work before it leaves the worktree: run the branch's checks and tests inside `<path>`.
+5. Merge or rebase back into the main branch from the main checkout; push when done.
+6. Clean up once the branch is merged or abandoned:
+   - `git worktree remove <path>` (add `--force` only if it has uncommitted changes you accept losing).
+   - `git worktree prune` to drop stale bookkeeping for worktrees removed outside git's book.
+7. Check nothing is left behind: `git worktree list` should show only your active checkouts.
+
+## Cleanup safety
+
+- Remove only worktrees you created. Host-owned worktrees — ones the repo or another agent set up — are not yours to delete; leave them.
+- Never remove a worktree that still has unmerged commits unless you have deliberately abandoned that branch.
+- Remove the worktree, not the branch directory with `rm -rf`; bypassing git leaves stale metadata that `prune` then has to guess about.
+- A worktree without a branch (`--detach`) is throwaway: verify, then remove with no branch to worry about.
+
+## Rationalizations
+
+| Rationalization | Why it fails |
+| --- | --- |
+| "I'll just switch branches, it's faster." | Uncommitted changes block checkout; one mistake mixes work from two tasks. |
+| "I can work on both branches in one checkout." | Stash conflicts and forgotten checkouts lose or misattribute work. |
+| "Removing a worktree is the same as deleting a folder." | `rm -rf` leaves git's worktree bookkeeping stale; `git worktree remove` stays consistent. |
+| "Their worktree looks abandoned, I'll clean it up." | Host-owned state. If it looks dead, report it, never remove it. |
+
+## Red flags
+
+- A worktree path inside the repo's own directory tree — nested worktrees are confusing and error-prone.
+- Deleting or force-removing a worktree whose branch has unpushed commits.
+- The same branch checked out in two worktrees, or two tasks sharing one worktree.
+- Touching or re-checking-out a host-owned worktree.
+
+All mean: stop, verify branch state, and clean up only what belongs to your task.
+
+## Verification
+
+1. `git worktree list` shows exactly the checkouts you expect — yours, none stale.
+2. After cleanup, the worktree path is gone and `git worktree prune` reports nothing to prune.
+3. The main checkout shows no leftover files, locks, or artifacts from the removed worktree.
+4. The removed branch's commits are either merged into main or deliberately abandoned — never stranded.

package/content/skills/mugiwara-healing/SKILL.md

@@ -50,6 +50,18 @@ Before fixing a bug: write the failing test that reproduces it, watch it fail, t
 4. After healing: update the ledger — mark each healed row with evidence; keep unfixed rows for escalation.
 5. Cycle counter: after this wave the flow returns to Wave 4 (Chopper) for re-audit. Same failure surviving 3 heal cycles → stop, escalate with full history.
 
+## Worker subagents
+
+Brook runs inline; the only dispatches are disposable WORKER subagents for genuinely parallel work. Three named workers:
+
+- **reviewer-worker** — adversarial diff review of Brook's fixes from a fresh context (per `mugiwara-review`).
+- **security-worker** — security pass over the fixes (per `mugiwara-security`).
+- **re-run-check worker** — independently re-runs the failed checks and returns raw evidence (command output, exit codes), so the re-verify is not Brook re-confirming its own fix.
+
+Flow: Brook aggregates worker findings → applies minimal root-cause fixes (triage matrix + Rules above) → dispatches a re-run-check worker to re-verify.
+
+Workers are NOT crew members — disposable subagents, one narrow job, results return as a report. The crew itself always runs inline in the main thread, never Task-dispatched.
+
 ## Output
 
 Fixed list (finding → commit → evidence), escalated list (finding → plan → owner), updated ledger → back to Wave 4 (Chopper).

package/content/skills/mugiwara-mode/SKILL.md

@@ -15,17 +15,18 @@ The crew's autonomy level. Read once per wave at dispatch; a flip takes effect f
 | semi | present plan for user GO | auto | self-answer + log | log, no pause |
 | auto | gated auto-GO | auto | self-answer + log | log, no pause |
 
-Consent is an invariant in ALL levels — see below. Every level ends at push + ready PR + verdict; the crew never merges or deploys.
+Consent is an invariant in ALL levels — see below. Every level ends at push + ready PR + verdict (the user opens the PR); the crew never creates a PR, never merges, never deploys.
 
 ## Config
 
-Two files, three keys, `key=value` lines, optional `#` comments:
+Two files, four 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 (no mugiwara branding) |
@@ -33,6 +34,14 @@ commit=conventional
 | mode | guided / semi / auto | guided |
 | branch | branch pattern | feature/{type}-{issue}-{slug} |
 | commit | conventional / gitmoji / plain | conventional |
+| base | PR summary target branch | main |
+
+**Mode owns autonomy; config owns writing standards.** The mode key alone
+decides whether branch/commit run automatically. The remaining keys shape HOW
+artifacts are written — the `branch` naming pattern, the `commit` message
+style, and `base` (the PR target named in the prepared PR summary per
+`mugiwara-pr`). There is no autonomy key in config; a mode flip is the only
+lever that changes behavior.
 
 The `branch` value is a naming pattern, never executed: its placeholders (`{type}`/`{issue}`/`{slug}`) are filled from mission metadata and validated against a safe charset (alphanumerics, `-`, `_`) before any git command.
 
@@ -52,7 +61,7 @@ The plan proceeds past approval in `auto` ONLY with zero blocking ambiguities AN
 
 ## Terminal invariant
 
-Every mode ends at: push the mission branch (per the `branch` key) → write the PR verdict file per `mugiwara-pr` → hand the branch + verdict to the user, who opens the PR. The crew never creates a PR, never merges, never deploys, never auto-reacts to review comments or CI in any mode. PR review is the terminal gate.
+Every mode ends at: push the mission branch (per the `branch` key) → write the PR verdict file per `mugiwara-pr` (includes a ready PR summary; target per `base`) → hand the branch + verdict to the user, who opens the PR. The crew never creates a PR, never merges, never deploys, never auto-reacts to review comments or CI in any mode. PR review is the terminal gate.
 
 ## Rules
 
@@ -60,4 +69,4 @@ Every mode ends at: push the mission branch (per the `branch` key) → write the
 2. Missing config on read = guided; the file is created only on a write.
 3. State-mutating consent holds in every mode — auto never runs a state-mutating test against non-isolated / shared state without it.
 4. Auto plan-GO is gated, never assumed.
-5. The terminal is push + ready PR + verdict in every mode.
+5. The terminal is push + ready PR + verdict in every mode — the crew never creates a PR.

package/content/skills/mugiwara-orchestration/SKILL.md

@@ -48,6 +48,10 @@ By mode (per `mugiwara-mode`): `guided` checks in with the user as today; `semi`
 
 On drift: stop, diagnose with Chopper's ledger, decide continue / retry / escalate to human.
 
+## Wave transitions (visibility)
+
+Every wave opens with a visible main-thread banner `## Wave N — <crew> (<skill>)` and closes with the handoff line `→ Wave N+1 — <crew>` (Wave 9: `→ closure`). No wave starts without its banner. A wave intentionally omitted is never silent — record wave, owner, and reason in the decision log before moving on. The user must always see which crew runs now and who takes over next.
+
 ## Work splitting
 
 When a wave has many independent tasks, instruct Zoro to parallelize — one task per WORKER subagent — and may split the mission into parallel tracks. Only `[PARALLEL]` sets are dispatched; sequential work stays inline. Never run more parallelism than the plan proves safe (check the dependency graph, no shared files). A `[PARALLEL]` task set with a hidden dependency edge is a red flag.
@@ -64,7 +68,21 @@ Recognize the in-session phrase `mugiwara mode <guided|semi|auto>`: write the pr
 
 Gate — every task's acceptance criteria verified, every gate passed, findings resolved or explicitly deferred with an owner, blocker ledger reviewed, unused intermediate markdown files deleted. Write the closure report to `.mugiwara/results/YYYY-MM-DD-<mission>-closure.md`: mission summary, per-wave outcomes, deferred items, lessons learned. The plan doc stays untouched.
 
-Terminal step (every mode): save-point commit → push the mission branch (per the config `branch` key, default `feature/{type}-{issue}-{slug}`) with plain `git push -u origin <branch>` → write `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md` per the `mugiwara-pr` format (includes a copy-paste PR description block) → hand the branch + verdict file to the user, who opens the PR. The crew never creates a PR, never merges, never deploys. On push failure (no auth / no remote), fall back to the local closure report and log the reason. Never auto-react to review comments or CI in any mode.
+### Detailed closure summary (mandatory, inline)
+
+Present a detailed summary to the user — never a one-liner:
+
+- Mission summary — goal, mode, waves, task count.
+- Per-wave outcome table — wave, tasks, status, evidence pointer.
+- Gate verdicts — quality, gates (coverage/build/DoD), review + security findings with dispositions, e2e (run / skipped + why).
+- Tests — unit/integration results; ATDD oracle verdict when user tests were declared.
+- Risks / rollback — remaining risk and the rollback path (revert commit / feature flag).
+- Deferred items + owner.
+- Next steps — PR material pointer, anything the user must do.
+
+### Terminal step (every mode, per `mugiwara-mode`)
+
+Save-point commit → push the mission branch (per the config `branch` key, default `feature/{type}-{issue}-{slug}`) with plain `git push -u origin <branch>` → write `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md` per the `mugiwara-pr` format (includes a ready PR summary block) → hand the branch + verdict file to the user, who opens the PR. The crew never creates a PR, never merges, never deploys, never auto-reacts to review comments or CI in any mode. On push failure (no auth / no remote), fall back to the local closure report and log the reason.
 
 Lessons: at Wave 0 triage read `.mugiwara/logs/lessons.md` and surface relevant rows to the owning agent. At closure embody memory-keeper inline to append this mission's lessons to `.mugiwara/logs/lessons.md` — one row per real lesson, append-only, never overwrite.
 

package/content/skills/mugiwara-planning/SKILL.md

@@ -15,8 +15,6 @@ Classify the mission by size first — after Luffy's route — then write the pl
 | **Standard** | 1 wave, 2-8 tasks, light dependency | Goals, Architecture overview, Context scan, Implementation graph, Wave table, Detail task, Anti-pattern, Acceptance |
 | **Full** | multi-wave, parallel, risk involved | All of Standard + Flow detail, Key decisions, Project structure, Risk & rollback, Definition of Done |
 
-Pick the smallest level that fits. Oversized plan wastes effort; undersized plan hides risk.
-
 ## Interview-first
 
 Batch ALL blocking ambiguities into ONE question round before writing. If a major decision appears mid-plan, stop and ask then — never assume silently. Unanswered question goes back to Luffy, never forward to Zoro.
@@ -59,34 +57,34 @@ Before the detail blocks, add two markdown tables so Zoro can read the shape at
 |---|------|-------|------|------------|------------|
 | T1 | <title> | <paths> | S | — | <one-line check> |
 
-`[PARALLEL]`/`[SEQUENTIAL, depends-on]` markers stay in the wave header AND in the task detail blocks; the index table mirrors the same dependency edges.
-
 ## Unified task template
 
 ```
-**Task N: <title>** `[PARALLEL]` | `[SEQUENTIAL, depends-on: Task M]`
+**Task N: <title>** `[PARALLEL]` | `[SEQUENTIAL, depends-on: Task M (file: <path>)]`
 - Files: create/modify <exact paths>
-- Interfaces: consumes → produces
+- Interfaces: consumes <file> from Task M → produces <file> for Task N
 - Size: XS | S | M | L | XL  (XL = 8+ files → split)
+- Break: none | <split condition when this task may exceed 8 files or diverge>
 - Steps: [ ] <TDD: failing test → run → implement → run → commit>
 - Acceptance: <command-verifiable>
 - Risk: none | <rollback plan>
 ```
 
-Every task uses this template at every level — zero-question standard: exact file paths (never "the component"), exact TDD commands, and an acceptance criterion that is a literal command or file check ("works correctly" is banned). A task touching deploy, data migration, secrets, or public API carries a `Risk` line; high-risk tasks get a rollback plan before execution. XL (8+ files) splits into smaller tasks first.
-
 **Task size = commit granularity.** Zoro commits per LOGICAL task, not per micro-step. Size tasks as meaningful units of work (a feature, a fix, a refactor), not keystrokes — a "fix typo" or "rename variable" task should be folded into its neighboring logical task, never standalone. If the plan is full of XS tasks, merge them up before writing: a plan sliced into a dozen one-line commits is a plan that will litter the history. Few, well-sized tasks → few, meaningful commits.
 
 ## Waves
 
-Group tasks into waves; each wave ends in a verified, reviewable state. Build the dependency graph from each task's Interfaces: X consumes what Y produces → X depends on Y.
+Group tasks into waves; each wave ends in a verified, reviewable state.
 
-- `[PARALLEL]` ONLY when tasks share no file AND no interface dependency.
-- State the proof in the wave header: disjoint files + no common consumed/produced interface.
-- Otherwise `[SEQUENTIAL, depends-on: Task M]`. Never mark parallel on assumption.
+- `[PARALLEL]` ONLY when tasks share no file AND no interface dependency; state the proof (disjoint files + no shared interface) in the wave header.
+- Otherwise `[SEQUENTIAL, depends-on: Task M (file: <path>)].` Never mark parallel on assumption.
 
 Per-wave gate: acceptance checks run, evidence captured; a wave starts only when its dependencies are proven done.
 
+## Implementation graph
+
+Every edge names its file: `consumes <file> from Task M → produces <file> for Task N`; flag cross-file risk edges (two tasks reading the same file — never parallel). Tasks carrying `Break:` split mid-execution when files exceed 8 or concerns diverge — re-index the tail.
+
 ## Acceptance vs Definition of Done
 
 - **Acceptance** = "did we build the right thing?" — per task, command-verifiable.
@@ -98,7 +96,7 @@ Per-wave gate: acceptance checks run, evidence captured; a wave starts only when
 - No Files paths, or an Acceptance like "works correctly" (uncheckable).
 - Assumed tooling not confirmed in the context scan, or silent reordering/dropping tasks.
 - `[PARALLEL]` without file- AND interface-disjoint proof.
-- Missing dependency edges between tasks touching each other's outputs.
+- Missing file-level dependency edges (no `(file: path)`), or a task with no Break point spanning 8+ files.
 - Gold-plating (speculative features) or a high-risk task with no rollback plan.
 
 Any anti-pattern fails the quality bar — fix the plan before handoff. Never ship a plan with a known hole. "Vague plan, the executor will figure it out" → wave stalls or ships wrong; "skip the context scan" → fiction; "trust me, they're parallel" → race; "rollback is someone else's problem" → data loss.
@@ -110,9 +108,9 @@ Any anti-pattern fails the quality bar — fix the plan before handoff. Never sh
 ## Key decisions       (why this way)
 ## Architecture overview
 ## Project structure
-## Implementation graph  (consumes → produces)
 ## Waves               (table: wave | focus | tasks | gate; parallel proof in header)
-## Task index          (table: # | task | files | size | depends-on | acceptance)
+## Implementation graph  (consumes <file> from Task M → produces <file> for Task N; cross-file risk edges)
+## Task index          (table: # | task | files | size | depends-on <file> | acceptance)
 ## Detail tasks        (unified template, one block per task)
 ## Risk & rollback
 ```

package/content/skills/mugiwara-pr/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: mugiwara-pr
-description: Use at closure to push the mission branch and prepare the PR material - one provider-agnostic verdict file the user pastes into the PR, one local check-run summary. Plain git push, no gh CLI, no auto-reaction to review comments or CI in any mode.
+description: Use at closure to push the mission branch and prepare the PR material - one provider-agnostic verdict file with a ready-to-paste PR summary block. Plain git push, no gh CLI, no PR creation, no auto-reaction to review comments or CI in any mode.
 ---
 
 # PR Handoff (CI/CD Loop)
 
-Mugiwara's evidence lands where the team reviews. At terminal, push the mission branch with plain `git`, write one structured verdict file the user pastes into the PR, and stop. No `gh` CLI, no PR API calls, no posting. Never per-wave.
+Mugiwara's evidence lands where the team reviews. At terminal, push the mission branch with plain `git` and write one structured verdict file. No PR is created by the crew — the user opens the PR and pastes the ready PR summary. Never per-wave.
 
 ## Verdict file
 
@@ -17,7 +17,18 @@ Write `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md`:
 - User-test verdict — when user tests were declared, the ATDD oracle result (per `mugiwara-testcases`), from real runs, never asserted.
 - Closure-report link — `.mugiwara/results/YYYY-MM-DD-<mission>-closure.md`.
 - Final verdict line — PASS / FAIL with the single blocking reason, if any.
-- Optional PR description block — copy-paste title + body ready for the user's PR.
+- **PR summary block** — copy-paste title + body ready for the user's PR.
+
+## PR summary
+
+Prepare the PR description so the user can paste and submit without writing it:
+
+- Title — a concise `{type}: {summary}` line from mission metadata.
+- Body — the verdict-file PR summary block (what changed, evidence, checks).
+- Target — the `base` config (default `main`) is named in the summary.
+- Validate every interpolated value against the safe charset and quote it.
+
+The summary is material, never posted — the crew stops at push.
 
 ## Handoff rule
 
@@ -26,12 +37,12 @@ Push the branch + write the verdict file at terminal, after every wave passes (n
 ## Push adapter (plain git, no gh)
 
 - Push: `git push -u origin <branch>` (branch per the `branch` config key, default `feature/{type}-{issue}-{slug}`).
-- No PR is created by the crew — the user opens the PR and pastes the verdict block.
+- No PR is created by the crew in any mode — the user opens the PR and pastes the PR summary block.
 - Interpolated identifiers (branch, owner/repo) are harness- or repo-derived, never read from untrusted content. Derive owner/repo from `git remote get-url origin`. Quote every interpolated value in the shell command and validate it against a safe charset (alphanumerics, `-`, `_`, `/`) before use.
 
 ## Stop-at-PR invariant
 
-The crew NEVER auto-reacts to review comments or auto-heals CI failures in any mode. That is a future, explicitly-opted feature.
+The crew NEVER creates a PR, auto-reacts to review comments, or auto-heals CI failures in any mode. PR creation and review are the user's — the crew's job ends at push + a ready PR summary. Reacting is a future, explicitly-opted feature.
 
 ## Credentials
 
@@ -46,6 +57,6 @@ Before finalizing the verdict file, scan it for secret patterns (`.env`-style li
 1. Write the verdict file before pushing; hand off last, once.
 2. Push branch + verdict file at terminal; never per-wave.
 3. Verdicts come from captured evidence (command output), never asserted.
-4. No auto-reaction to review comments or CI in any mode.
+4. No PR is created, no auto-reaction to review comments or CI in any mode.
 5. Auth missing → local closure fallback + logged reason.
 6. Scan the verdict file for secrets before handoff; on a match, redact and log.

package/content/skills/mugiwara-quality/SKILL.md

@@ -18,6 +18,7 @@ Never assume `npm test`. Detect the project's real commands from package.json sc
 3. Unit tests — full suite, capture output.
 4. User-declared test suites (per `mugiwara-testcases`) — run under the consent matrix below.
 5. Integration tests — never created by us; when user tests are declared and state-mutating, see the consent matrix.
+6. Optional e2e gate — only when BOTH repo e2e setup AND changed-file e2e patterns hold, consent by mode, see below.
 
 ## User suites (per `mugiwara-testcases`)
 
@@ -29,6 +30,14 @@ Run the declared user test files under the consent matrix:
 
 The user-AC verdict feeds the gates wave — it must come from these runs actually executing, never asserted.
 
+## Optional e2e gate
+
+Optional, never default-on. Trigger ONLY when BOTH hold:
+- Repo has e2e setup — any of `playwright.config.*`, `cypress.config.*`, `e2e/` dir, `test:e2e` npm script.
+- Changed/staged files match e2e patterns — `e2e/**`, `*.e2e.*`, `specs/**`.
+
+When triggered, consent by mode (per `mugiwara-mode` invariant): `guided`/`semi` ask first — run now / skip / run manually later; `auto` runs only provably-isolated e2e (in-memory / local / tooling-proven isolation). Otherwise skip-and-log: record the skip reason (no setup, no matching files, no consent) in the report. The e2e gate never blocks silently and never blocks a pass — a skip is logged, not a failure.
+
 ## Mode + consent (per `mugiwara-mode`)
 
 Consent is an invariant, not a mode knob. State-mutating tests against NON-isolated / shared state (real DB writes, network, browsers) ALWAYS require explicit user consent in ALL modes. Provably-isolated mutation — in-memory / temp / testcontainer-backed DBs, tooling-proven isolation — is explicitly auto-safe and needs no consent. `auto` runs only provably-isolated tests automatically (unit-level, or tooling-proven isolation such as in-memory / local DB). `guided`/`semi`: integration tests keep the existing ask-first rule — run automatically now / skip / run manually later. Record every consent answer in the report.
@@ -54,3 +63,4 @@ Per check: command run, exit status, key output excerpt, pass/fail → to `.mugi
 | "Integration tests, skip them, too slow." | Skipping is policy, not laziness: we never create integration tests, and undeclared suites don't run. Declared user suites run under the consent matrix. |
 | "No tooling found, wave done." | No tooling means say so and propose the minimal setup, never a silent skip. |
 | "Formatter and linter are the same." | They are separate checks; run both. |
+| "E2E setup exists, so the gate runs." | No — trigger needs BOTH setup AND changed-file e2e patterns, plus consent by mode. Otherwise skip-and-log, never run unasked. |

package/content/skills/mugiwara-security/SKILL.md

@@ -24,7 +24,44 @@ List every surface: endpoints, CLI, config inputs, file/DB reads, external calls
 
 ## OWASP Top 10 mapping
 
-Required when the project handles payments, health data, or PII. Map each security check to its OWASP Top 10 category (e.g. injection → A03, authn/authz → A01/A07, data exposure → A02/A05, deps → A06). No mapping row for a handled category = a documentation gap.
+Required when the project handles payments, health data, or PII. Map each security check to its OWASP category; a handled category with no mapping row = documentation gap.
+
+| Code | Category | Review area |
+|------|----------|-------------|
+| A01 | Broken access control | authz gaps, IDOR, missing server-side checks |
+| A02 | Cryptographic failures | PII in transit/at rest, weak crypto, exposed secrets |
+| A03 | Injection | SQL/NoSQL/OS/template injection, unsanitized input to exec/render |
+| A04 | Insecure design | missing threat model, trust-boundary failures |
+| A05 | Misconfiguration | default creds, verbose errors, permissive headers, debug on |
+| A06 | Vulnerable components | dependency audit, known-vuln check, outdated libs |
+| A07 | Authn failures | broken sessions, brute-forceable login, credential reuse |
+| A08 | Integrity | insecure deserialization, supply-chain tamper |
+| A09 | Logging/monitoring | PII in logs, missing audit trail, silent failures |
+| A10 | SSRF | server-side requests to attacker-controlled targets, URL validation |
+
+## Authn/Authz patterns
+
+- Authn ≠ authz: identity is not permission. Verify both, server-side only; client-side-only checks are findings, not controls.
+- Sessions/tokens: validate server-side, enforce expiry and revocation, rotate on privilege change, never in URL or logs.
+- Least privilege: smallest scope that works; a widened scope is a finding.
+- Fail closed: deny on any absent/ambiguous permission. Fail-open authz is Critical.
+
+## Secrets management
+
+- Never in code: no hardcoded keys/tokens/passwords, no committed .env, no secrets in logs or dumps.
+- Source from env or a vault (AWS Secrets Manager, Vault, etc.); inject at runtime, never inline.
+- Rotate on a schedule; a key that ever hit a repo is revoked, not "cleaned up". Scan diff and history for secret shapes — a pushed secret is exposed regardless of later removal.
+
+## Dependency auditing
+
+- Lockfiles are the truth: audit the lock, not the manifest; commit lockfiles.
+- Run the project's own audit tooling (npm audit, pip-audit, cargo audit, govulncheck, osv-scanner). A skipped audit is a finding.
+- Fail on CVEs reachable from the diff; a new dependency gets a vuln + maintenance review before merge. Pin versions, verify provenance, inspect postinstall scripts.
+
+## Boundary system
+
+- Every external interface is hostile: HTTP bodies/headers, query strings, uploads, CLI args, config, env, upstream responses, rendered HTML.
+- Validate at the trust boundary, allowlist-first: shape, type, length, charset. A boundary with no validation is a finding even when input "looks safe"; a value is never trusted past its origin.
 
 ## Security-regression check
 

package/content/skills/mugiwara-ship/SKILL.md

@@ -43,9 +43,32 @@ Run every item and record evidence; a checkbox ticked without output is a failed
 3. A critical finding at any stage → NO-GO. Non-critical findings → list them, decide ship-with-tracking or fix-first, and record which.
 4. Write the verdict and evidence to `.mugiwara/results/`.
 
+## Cleanup (after the terminal step)
+
+Once the branch is pushed and the PR material is written, clean `.mugiwara/` of
+consumed intermediates. Never touch anything outside `.mugiwara/`.
+
+**KEEP** (they are the audit trail and PR material):
+
+- `config`
+- `plans/YYYY-MM-DD-<mission>.md` — the clean plan doc
+- `results/YYYY-MM-DD-<mission>-closure.md` — closure report
+- `results/YYYY-MM-DD-<mission>-pr-verdict.md` — PR material
+- `logs/lessons.md` and any cross-mission state (`backup/`, `manifest.json`)
+
+**DELETE** (consumed or superseded):
+
+- `spec/YYYY-MM-DD-<mission>.md` — consumed by planning
+- `results/` wave reports — todos, audits, quality/gate/healing reports
+- `review/` and `issues/` per-mission findings
+- `logs/YYYY-MM-DD-<mission>.md` and mode-flip logs
+
+Procedure: list the candidates first (dry-run), delete them, then report what
+was removed and what stays. A mission is only closed after cleanup runs.
+
 ## Iron Law
 
-NO-GO UNTIL PROVEN. Missing evidence is a NO-GO. A release that cannot be rolled back is a NO-GO.
+NO-GO UNTIL PROVEN. Missing evidence is a NO-GO. A release that cannot be rolled back is a NO-GO. A mission that ships without cleanup leaves a rotting `.mugiwara/`.
 
 ## Red flags
 

package/content/skills/mugiwara-systematic-debugging/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: mugiwara-systematic-debugging
+description: Use when any agent or worker hits a failure and must debug it - a bug, a test that fails for an unknown reason, a crash, a wrong result, or an unexplained regression. A standalone 4-phase discipline - reproduce, localize, reduce, fix + guard. Stop-the-line on failures, prove-it before fixing, rollback prep before a risky fix.
+---
+
+# Systematic Debugging
+
+A failure is a stopping event, not a speed bump. Do not guess, do not patch. Walk the four phases in order; each gates the next.
+
+## When to use
+
+Any bug, unexplained failure, crash, or regression in code, tests, or config. When the cause is unknown, the fix is not obvious, or the failure is intermittent. Standalone discipline — use it before any fix ships, and escalate when a phase cannot complete.
+
+## Process
+
+### Phase 1 — Reproduce
+
+1. See it fail for the intended reason. Run the failing case as-is, capture the exact error, exit code, and input.
+2. No repro = no debugging. If it will not reproduce, record the conditions, mark `unreproducible`, and move on — never fix a ghost.
+3. Prove the failure is current: re-run on clean state, not a warm cache or half-applied change.
+4. Stop-the-line: a red test or crash halts new work until it is green or escalated.
+
+### Phase 2 — Localize
+
+1. Bisect to the minimal surface. Narrow by time (`git bisect`), by layer (config/test/code/env), or by input (binary search over the failing data).
+2. Read the full error before touching anything — line, file, and surrounding code.
+3. Grep every caller of the suspect function. A symptom on one path may be a shared root.
+4. Ask what changed recently: diff, new deps, config drift.
+5. Name the layer and the likely function; say it out loud. If you cannot state a hypothesis, keep bisecting.
+
+### Phase 3 — Reduce
+
+1. Strip to the failing core. Delete branches, comments, unrelated code until the smallest case that still fails remains.
+2. Preserve the repro, do not preserve the noise. If the reduced case passes, you over-deleted or misdiagnosed — restore and re-cut.
+3. A reduced case makes the root cause visible and doubles as the seed for the regression test.
+
+### Phase 4 — Fix + guard
+
+1. Prove-it before fixing: write the failing test that reproduces the failure, watch it fail (red), then fix until green. Red → code → green, in that order.
+2. Fix at the root cause, not the symptom. One minimal change where all callers route through; never a patch on the one caller that surfaced.
+3. Risky fix → rollback prep first: snapshot the state, note the revert point, and record how to undo before you change anything.
+4. Guard: add or extend the regression test that fails without the fix. A fix with no guard is unproven.
+5. Re-run the failed check end-to-end and capture the output as evidence.
+
+Escalate with full repro when a phase cannot complete — guesswork is not an outcome.
+
+## Rationalizations
+
+| Rationalization | Reality |
+|-----------------|---------|
+| "It works sometimes, must be flaky" | Intermittent failures have a root cause; reproduce harder, never shrug |
+| "I know the fix, let's skip the test" | No red test = no proof. Write it first |
+| "This one path is enough" | Other callers share the same root; patch the shared function |
+| "A quick patch now, cleanup later" | Pile-on fixes bury the root cause |
+| "The failure is environmental" | Prove it with a repro or mark `unreproducible` — do not assume |
+| "Too risky, let's just roll back everything" | Rollback prep, not blanket revert — know the exact revert point |
+
+## Red flags
+
+- Fixing without a repro.
+- Skipping the failing test and fixing straight into code.
+- Patching the symptom path while siblings stay broken.
+- The reduced case passing — over-deletion or a wrong diagnosis.
+- A "flaky" label with no evidence.
+- Multiple stacked fixes on one failure.
+- A risky fix applied with no rollback prep.
+
+All mean: the failure is not understood. Stop, walk the phases, or escalate with the repro.
+
+## Verification
+
+- Repro recorded: command, input, expected vs actual.
+- Localization stated as a named layer + function.
+- Reduction produces a minimal failing case.
+- Fix is one root-cause change, guard test written, red confirmed before green.
+- Failed check re-run and captured.
+- Rollback point noted for any risky fix.

package/content/skills/mugiwara-test-driven-development/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: mugiwara-test-driven-development
+description: Use when writing code during execution - RED-GREEN-REFACTOR discipline, proof-of-when over proof-of-exists, test pyramid shape, one test = one behavior, assert real behavior over mocks, refactor while green. Referenced by zoro-execution; complements mugiwara-testcases (user AC intake) - this is the executor's TDD contract.
+---
+
+# Test-Driven Development
+
+A test proves nothing by existing. It proves nothing by passing. Its entire value lives in WHEN it runs and HOW it fails. TDD is the discipline that makes that proof real.
+
+## When to use
+
+Every task that writes production code — feature, bug fix, refactor, new function. The moment code leaves your keyboard, its test must already have failed first.
+
+## Process
+
+RED:
+
+1. Write exactly one failing test for the next behavior. Name it plainly: `shouldRejectOrderWhenStockIsZero`, not `test2`.
+2. Run it. WATCH it fail — for the intended reason (feature missing), not a typo, not a wrong assertion, not a broken harness.
+3. A test that fails for the wrong reason proves nothing. If it red-screens on an import error, the proof is that you can't import, not that the feature is missing. Fix the harness, re-watch it fail correctly.
+4. If the test passes on first run, it tests something that already exists. You wrote it after the code, or you tested the wrong thing. Stop, revert, redo.
+
+GREEN:
+
+5. Write the minimal implementation that makes the test pass. No extras, no "while I'm here", no unrequested polish.
+6. Run again — green. Watch it go green; do not assume.
+7. If you caught yourself writing implementation before its test, discard it and redo it test-first. "It's basically right" is not salvageable.
+
+REFACTOR:
+
+8. Now, and only now, improve structure. The test stays green the whole time — it is your safety net.
+9. Each refactor step: change, run, green. Small steps, never a long unreachable stretch.
+
+Green is a floor, not a finish. A green pass on a messy implementation is not done; it is the starting line for refactor. Never silence a failing test by deleting it or weakening its assertion — that converts the proof into a lie.
+
+## Test pyramid
+
+- ~80% unit tests — one behavior, in-memory, milliseconds, run constantly.
+- ~15% integration tests — real boundaries (DB, filesystem, service) in isolated harnesses.
+- ~5% end-to-end — the whole stack, sparse and precious.
+
+Build bottom-up: the pyramid's point is that the slow, fragile, expensive layers carry as little as possible. If you write a test and it lands high in the pyramid, ask if a unit test can carry the same proof first. Flat is a defect: all-unit is fine, all-E2E is a treadmill, all-mocks is a hallucination.
+
+## One test, one behavior
+
+- Each test asserts one behavior and one reason for it. Split a two-assertion test that fails for two possible reasons — a failure should point at exactly one broken decision.
+- Assert on real behavior: actual return values, real state, real side effects — not on that a mock was called.
+- Mocks are for the edges — faking the slow or nondeterministic neighbor (clock, network, random). A mock that asserts internal call order instead of observable outcome is asserting the implementation, and locks your code into its own structure.
+
+## Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll write the test after, then run it" | That run can only pass — it can never prove it catches the bug. You bought confidence, not proof. |
+| "The test passed first try, that's fine" | It tested code that already existed. The RED step is the whole point; skipping it skips the proof. |
+| "I'm sure this is broken, I'll just fix it" | No failing test first means no regression net, and you'll never know if you fixed the symptom or the cause. |
+| "The failing test was a typo, let's just move on" | A red for the wrong reason is not red at all. Fix the harness, re-watch it fail for the intended reason. |
+| "Mock it, faster than a real boundary" | A mock asserting your own call order verifies your imagination, not the software. |
+| "Just weaken this assertion to pass CI" | You converted the proof into a lie and shipped it. Never. |
+| "It's only one function, test is overkill" | The one function you skip is the one that breaks the deploy. |
+
+## Red flags
+
+- A test that passes without having failed first.
+- A red that is a typo, import error, or wrong assertion — you never saw the intended failure.
+- Implementation present before its test, "reused as reference".
+- One test with a pile of unrelated assertions.
+- Mocks verifying internal call sequences instead of outcomes.
+- A failing test deleted or weakened to go green.
+- A refactor run that never re-runs the suite, or a suite that fails and is refactored anyway.
+- An 80/15/5 pyramid that is actually 5/15/80.
+
+All mean: stop, go back to the last green, redo the step honestly.
+
+## Verification
+
+The evidence of a TDD task is the sequence, not the endpoint:
+
+- the red run output (captured), showing the intended failure reason,
+- the green run output (captured), after the minimal implementation,
+- the refactor pass output, still green,
+- the test file committed alongside the code it proves, never orphaned.
+
+A report that shows only the final green run is an incomplete report. The checkpoint audits the sequence.

package/content/skills/mugiwara-workflow/SKILL.md

@@ -11,6 +11,12 @@ The Straw Hat harness: Wave 0 triage + Waves 1-9, with an optional adversarial p
 
 **Inline by default.** The main/primary agent runs the pipeline and plays each crew role itself using that member's skill. Every wave's work is performed in the main conversation so the user sees the process live — no hidden subagent jumps, no click-to-expand. The crew members are personas + skills the main thread embodies, not mandatory dispatch targets.
 
+**Visible wave transitions.** Every wave opens with a main-thread banner `## Wave N — <crew> (<skill>)` and closes with the handoff line `→ Wave N+1 — <crew>` (Wave 9: `→ closure`). No wave starts without its banner; the conversation names who runs now and who takes over next so the user always sees the chain live.
+
+**Auto-activation.** Any non-trivial request fires the harness without the user asking. Check first, before exploring or answering: if the request could benefit from the crew, start Wave 0 triage. The user does not need to invoke `using-mugiwara` explicitly — the workflow starts itself.
+
+**Checkpoint-report presentation.** The banner marks a stage boundary; no wave passes silently. At each boundary the owning crew reports inline — one compact per-crew report: what ran, the result, the evidence pointer. No narration of every tool call. Each wave closes with a short progress summary (done / in-flight / blocked + next handoff). On failure or risk, PAUSE: report the problem and get a continue / retry / escalate decision before proceeding.
+
 1. For each wave, the main thread loads the owning crew member's skill (e.g. `mugiwara-checkpoint` for Wave 4) and performs that role inline: triage, planning, execution, audit, quality, gates, review, closure — all in the main thread.
 2. Dispatch a subagent ONLY when the work is genuinely parallel or background: an independent `[PARALLEL]` task batch (Zoro's WORKER subagents, Wave 3), parallel fixes (Brook, Wave 8), or a long-running check that would stall the conversation. Subagent results return to the main thread as a report; the main thread summarizes the outcome inline with evidence pointers.
 3. Crew members NEVER dispatch another crew member. A crew role that must split work returns the split plan to the main thread, which spawns the workers.
@@ -77,12 +83,12 @@ Never silently work around a blocker. Brook reads this ledger at Wave 8 to decid
 
 ## Cleanup
 
-At closure (Wave 9), delete unused intermediate markdown files in `.mugiwara/` — superseded results, review, issues reports, and the per-mission decision log in `logs/`. Keep the plan doc and the closure report.
+At closure (Wave 9), after the terminal step, run the cleanup procedure in `mugiwara-ship`: delete consumed intermediates — superseded results, review, issues reports, the per-mission decision log in `logs/`, and the consumed spec. Keep the plan doc, the closure report, the PR verdict, `config`, and cross-mission state (`logs/lessons.md`, `backup/`, `manifest.json`). List candidates before deleting.
 
 ## Rules
 
 1. Evidence over claims: no wave passes on assertion. The owning agent runs the checks and shows output.
-2. No wave skipped without the reason recorded in the decision log (`.mugiwara/logs/`).
+2. No wave skipped without the reason recorded in the decision log (`.mugiwara/logs/`) — name the wave, owner, and reason at the moment of omission.
 3. Heal loop is bounded: Wave 8 → Wave 4, max 3 cycles. After that, escalate to the human with full history.
 4. Any agent may consult Luffy mid-flight (embody `luffy-orchestrator` inline) for decisions and escalations.
 5. Wave 7 runs Robin and Jinbe review passes in parallel — both are inline passes over the same diff, or parallel review subagents for large diffs.