@ionivetech/mugiwara 0.3.0 → 0.5.0

package/content/skills/mugiwara-planning/references/plan-template.md

@@ -0,0 +1,46 @@
+# Plan Template
+
+Scaled plan skeleton. Nami picks Quick/Standard/Full based on mission size.
+
+## Quick (1 task, ≤2 files)
+
+```markdown
+# <mission> — <goal>
+
+## Key decisions
+<why this approach>
+
+## Waves
+
+| Wave | Focus | Tasks | Gate |
+|------|-------|-------|------|
+| 3 | <what> | T1 | <command-verifiable exit check> |
+
+## Task index
+
+| # | Task | Files | Size | Depends-on | Acceptance |
+|---|------|-------|------|------------|------------|
+| T1 | <title> | <paths> | S | — | <one-line check> |
+
+## Detail: T1 — <title>
+- Files: <exact paths>
+- Steps: [ ] <test → impl → verify>
+- Acceptance: <command>
+- Risk: none
+```
+
+## Standard (1 wave, 2-8 tasks)
+
+Add: Architecture overview, Context scan, Implementation graph, Acceptance per task.
+
+## Full (multi-wave, parallel, risk)
+
+Add all of Standard + Key decisions, Project structure, Risk & rollback, Definition of Done.
+
+## Anti-patterns to avoid
+
+- "TBD" or "add appropriate error handling" in a step.
+- No file paths, or Acceptance like "works correctly" (uncheckable).
+- `[PARALLEL]` without file- AND interface-disjoint proof.
+- High-risk task with no rollback plan.
+- Vague plan expecting the executor to figure it out.

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

@@ -1,10 +1,15 @@
 ---
 name: mugiwara-pr
-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.
+description: Use at closure to push branch + prepare PR material — plain git push, verdict file with ready PR summary. Never creates PR, merges, or deploys.
 ---
 
 # PR Handoff (CI/CD Loop)
 
+## Skip when
+
+- Not at closure: PR material is terminal-step-only, never per-wave.
+- User handles the PR themselves and declined the verdict file.
+
 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

package/content/skills/{mugiwara-test-driven-development → mugiwara-proof-order}/SKILL.md

@@ -1,10 +1,15 @@
 ---
-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.
+name: mugiwara-proof-order
+description: Use when writing code — RED-GREEN-REFACTOR. Proof value from WHEN the test runs, not that it exists. One test = one behavior.
 ---
 
 # Test-Driven Development
 
+## Skip when
+
+- No production code written: docs, config, or pure dependency bump.
+- Refactor already fully covered by existing passing tests (record the reason).
+
 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

package/content/skills/mugiwara-proof-order/references/proof-order-examples.md

@@ -0,0 +1,62 @@
+# Proof Order Examples
+
+The test's proof value comes from WHEN it runs, not that it exists.
+
+## Why order matters
+
+```
+❌ Write implementation → Write test → Test passes immediately
+   The test never demonstrated it could catch the bug.
+   You cannot prove the test is testing the right thing.
+
+✅ Write test (red) → Watch it fail → Write implementation → Test passes (green)
+   The red phase proves the test catches the absence of the feature.
+   The green phase proves the feature satisfies the test.
+```
+
+## Example: password validation
+
+```ts
+// RED — test first, watch it fail
+describe('validatePassword', () => {
+  it('rejects passwords shorter than 8 characters', () => {
+    expect(validatePassword('short')).toBe(false);
+  });
+});
+
+// FAIL: validatePassword is not defined
+
+// GREEN — minimal impl
+function validatePassword(pw: string): boolean {
+  return pw.length >= 8;
+}
+
+// REFACTOR — while green
+function validatePassword(pw: string): boolean {
+  if (pw.length < 8) return false;
+  if (!/[A-Z]/.test(pw)) return false;
+  if (!/[0-9]/.test(pw)) return false;
+  return true;
+}
+```
+
+## Anti-pattern: test after implementation
+
+```ts
+// Code already written, then test added later:
+function formatCurrency(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
+// Test passes immediately — proves nothing:
+it('formats currency', () => {
+  expect(formatCurrency(10)).toBe('$10.00'); // green on first run
+});
+```
+
+The fix: comment out the implementation, watch the test fail, then uncomment.
+If the test still passes with implementation removed, the test is wrong.
+
+## Rule
+
+A test that passes on first run has proven nothing. Discard the implementation and redo test-first, or comment it out and prove the test actually fails before restoring.

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

@@ -1,10 +1,15 @@
 ---
 name: mugiwara-quality
-description: Use after checkpoint passes to run code quality checks - formatter, linter, unit tests, and with recorded user consent integration tests. Detects the project's real tooling first, never weakens configs to pass.
+description: Use after checkpoint passes — formatter, linter, unit tests. Discovers project tooling, never weakens configs. User tests under consent matrix.
 ---
 
 # Quality (Sanji)
 
+## Skip when
+
+- No code changed: docs-only or config-only diff with no lint/test surface.
+- Repo has no detectable tooling (no test/lint/format commands) — record the skip.
+
 Cook the checks properly; never cut corners to make them pass.
 
 ## Discover the stack first
@@ -36,9 +41,9 @@ 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.
+When triggered, consent by mode (per mode config 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`)
+## Mode + consent (per mode config)
 
 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.
 

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

@@ -1,51 +1,67 @@
 ---
 name: mugiwara-resume
-description: Use when a mission is interrupted, context is lost or compacted, or a new session starts mid-mission - rebuild the full picture from .mugiwara/ state and continue from the exact point, never restart.
+description: Use when mission interrupted, context lost, or new session mid-mission — rebuild from .mugiwara/state.json, continue never restart.
 ---
 
 # Session Resume (Never Start Over)
 
-The host AI can lose context — compaction, a new session, a crash. Disk state under `.mugiwara/` is the single source of truth. Rebuild the picture from disk, continue from the exact point, never restart.
+## Skip when
 
-## The state contract
+- Fresh mission: no `.mugiwara/` state exists to rebuild from.
+- No interruption, compaction, or new-session-mid-mission happened.
 
-What survives on disk and drives resume:
+The host AI can lose context — compaction, new session, crash. Disk state is truth. Rebuild from one file, continue from exact point, never restart.
 
-| File | Holds |
-|------|-------|
-| `.mugiwara/plans/YYYY-MM-DD-<mission>.md` | waves, tasks, acceptance criteria (clean plan) |
-| `.mugiwara/results/<mission>-todos.md` | checkbox per task, checked = done with evidence |
-| `.mugiwara/results/<mission>-trace.md` | every dispatch, outcome |
-| `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` | blocker rows with owners / heal state |
-| `.mugiwara/logs/YYYY-MM-DD-<mission>.md` | Luffy's decision + check-in log |
-| `.mugiwara/config` | current mode (project); `~/.mugiwara/config` = global default; per-mission override rows live in the decision log |
+## State contract
 
-## Resume protocol
+Resume reads one file: `.mugiwara/state.json`. All position data is computed at every wave boundary by `scripts/savepoint.sh`.
+
+```json
+{
+  "mission": "2026-08-11-invitation-accepted",
+  "actor": "farid",
+  "branch": "feature/feat-MKR-412",
+  "lane": "full",
+  "lane_reason": "auth/ path touched",
+  "wave": 5,
+  "mode": "guided",
+  "base_sha": "a3f1c2e",
+  "files_touched": 11,
+  "loc_delta": 340,
+  "sensitive_paths": ["src/auth/invitation.ts"],
+  "tasks": { "done": 7, "total": 12 },
+  "blockers_open": 1,
+  "heal_cycle": 1,
+  "tokens_est": 14200,
+  "budget": 20000,
+  "evidence": [".mugiwara/results/wave4-audit.md"],
+  "updated_at": "2026-08-11T12:40:00Z"
+}
+```
 
-Read in this order, then act:
+## Resume protocol
 
-1. Plan doc → current wave, remaining tasks.
-2. Todos → done/undone (unchecked box = not done, regardless of memory).
-3. Trace → last completed step, last outcome.
-4. Blocker ledger → open rows (they have owners / are mid-heal).
-5. Config → the mode. Read `.mugiwara/config` (project) then `~/.mugiwara/config` (global) before re-deriving position; missing = `guided`. If a per-mission override row exists in the decision log (`.mugiwara/logs/YYYY-MM-DD-<mission>.md`), that level wins over the config file for this mission.
-6. Re-derive position: wave N, tasks remaining, open blockers, heal counter, and the resumed mode.
-7. State it in one line: "Resumed: Wave 5, tasks 5.3-5.7 pending, 1 blocker (env), heal counter 1, mode semi." Then CONTINUE — do not re-verify completed waves unless the trace shows a failure.
+1. Read `.mugiwara/state.json`. If absent, this is a fresh mission — no resume needed.
+2. Derive position from fields: wave N, tasks done/total, blockers open, heal cycle, mode.
+3. If `state.json` is stale or corrupted, fall back to legacy files: plan doc → todos → trace → blocker ledger → config. Then write a fresh `state.json`.
+4. State it: "Resumed: Wave 5, 7/12 tasks, 1 blocker, heal cycle 1, mode guided."
+5. Continue — do not re-verify completed waves.
 
 ## Rules
 
 1. Never trust memory over disk — disk is truth.
-2. Never re-run completed work — the trace proves it.
+2. Never re-run completed work — state.json proves it.
 3. Never skip the resume read — guessing position = drift.
-4. If disk state is missing/contradictory → escalate to Luffy to reconcile, do not invent state.
+4. If state.json is absent and no legacy files exist → fresh mission, escalate to Luffy.
 
-## Writing discipline
+## Rationalizations
 
-Update todos/trace AFTER every task, not at the end. Resume quality is proportional to log freshness. A stale log makes the next resume guess.
+- "I remember where we were" → memory lies after compaction; disk is truth.
+- "Re-running is safer" → wastes the mission; trust state.json.
+- "I'll update state later" → savepoint.sh runs at every wave boundary; state is always current.
 
-## Rationalizations + red flags
+## Red flags
 
-- "I remember where we were" → memory lies after compaction; disk is truth.
-- "Re-running is safer" → wastes the mission; trust the trace.
-- "I'll update todos later" → later never comes; resume breaks.
-- Red flags: reading any file out of order, re-doing a wave the trace shows complete, skipping the blocker ledger, inventing state instead of escalating, a resume position stated without citing the files.
+- Resume position stated without citing state.json or legacy files.
+- Re-doing a wave state.json shows complete.
+- Inventing state instead of escalating when files are missing.

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

@@ -1,10 +1,15 @@
 ---
 name: mugiwara-review
-description: Use after quality gates pass to review the diff adversarially - doubt-driven review, breaking-change damage map via repo-wide caller mapping first, five-axis review with regression emphasis, sonar smells, severity criteria, dispute hierarchy, docs gaps. Findings to .mugiwara/review/. Max 3 cycles then escalate.
+description: Use after gates pass to review the diff — breaking-change map via caller mapping, five-axis review, severity-tagged findings. Max 3 cycles.
 ---
 
 # Review (Robin)
 
+## Skip when
+
+- Zero diff to review: docs-only change or lane 0 one-line fix.
+- User explicitly deferred review and recorded the decision.
+
 Review like the diff will be maintained by someone else at 3am — and like the implementer is wrong until proven otherwise.
 
 ## Breaking-change analysis (do this FIRST) — build the damage map

package/content/skills/mugiwara-review/references/five-axis-worksheet.md

@@ -0,0 +1,36 @@
+# Five-Axis Review Worksheet
+
+One verdict + evidence per axis. No axis passes on assertion.
+
+## Axes
+
+| Axis | Question | Evidence required |
+|------|----------|-------------------|
+| Correctness | Does the change break anything that currently works? | Re-run caller tests, verify edge cases |
+| Readability | Can a new team member understand the diff in 5 minutes? | Naming convention check, function length, comment quality |
+| Architecture | Does the change fit the existing system structure? | No parallel patterns, no new abstraction without need |
+| Security | Any security regression or new attack surface? | STRIDE on changed surface, checklist pass |
+| Performance | Any N+1, O(n²), or unbounded resource use introduced? | Profiler output or manual analysis of hot path |
+
+## Example
+
+```
+Axis: Correctness
+Verdict: PASS
+Evidence: npm test -- --shard=1/2 passes (312 tests), caller grep confirms all
+          imports of renamed function updated
+```
+
+```
+Axis: Security
+Verdict: FAIL
+Evidence: New endpoint POST /api/export has no authz middleware. Missing rate
+          limit on file generation (DoS risk).
+```
+
+## Rules
+
+- One verdict per axis. "Partial pass" = FAIL.
+- Evidence is command output or file path, never a paraphrase.
+- FAIL on any axis → overall review FAIL → Brook (Wave 8).
+- PASS on all 5 → forward to closure.

package/content/skills/mugiwara-review/references/severity-rubric.md

@@ -0,0 +1,20 @@
+# Severity Rubric
+
+For review findings. Every finding gets a severity backed by criteria.
+
+| Severity | Definition | Examples | Action |
+|----------|-----------|----------|--------|
+| **blocker** | public-break with no migration path, wrong behavior shipped, security hole | renamed public API with callers unfixed, authz bypass, data loss | Fix before merge |
+| **major** | internal-break with callers unfixed, missed contract, behavior change outside declared scope | changed function signature, missing error handling, N+1 in hot path | Fix this mission |
+| **minor** | polish, style drift, batched items | inconsistent naming, missing test for edge case, duplicated 3-line helper | May batch with Brook |
+
+## CVSS-style for security
+
+| Severity | Exploitability × Impact |
+|----------|------------------------|
+| Critical | Reachable + tooling exists + pre-auth → data loss/auth bypass/RCE |
+| High | Reachable + limited tooling → PII leak, privilege escalation |
+| Medium | Requires auth/conditions → partial exposure |
+| Low | Defense-in-depth gaps, no known exploit path |
+
+Security findings are never "minor by default." Every finding gets the matrix.

package/content/skills/{mugiwara-systematic-debugging → mugiwara-root-cause}/SKILL.md

@@ -1,16 +1,23 @@
 ---
-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.
+name: mugiwara-root-cause
+description: Use for debugging bugs, crashes, regressions — 4-phase: reproduce, localize, reduce, fix+guard. Stop-the-line on failures.
 ---
 
 # Systematic Debugging
 
+## Skip when
+
+- Cause already known and reproduced, fix obvious, failure not intermittent.
+- One-line revert or rollback resolves it with no investigation needed.
+
 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.
 
+Framework code from docs, not memory: `references/source-grounding.md`.
+
 ## Process
 
 ### Phase 1 — Reproduce

package/content/skills/mugiwara-root-cause/references/four-phase-worked.md

@@ -0,0 +1,71 @@
+# Four-Phase Debugging — Worked Example
+
+A real bug traced end to end through reproduce → localize → reduce → fix + guard.
+
+## The bug report
+
+```
+Title: Users see "null" instead of display name on profile page
+Severity: medium
+Reported: Aug 2026
+```
+
+## Phase 1 — Reproduce
+
+```bash
+# Create user with no displayName
+$ curl -X POST /api/users -d '{"email":"test@ex.com"}'
+{"id": "u_42", "email": "test@ex.com"}
+
+# Fetch profile
+$ curl /api/users/u_42
+{"id": "u_42", "displayName": "null", "email": "test@ex.com"}
+```
+
+Expected: `displayName` should be `null` (JSON null) or omitted, not string `"null"`.
+
+## Phase 2 — Localize
+
+```bash
+$ git grep -n 'displayName' src/
+src/models/user.ts:12:  displayName?: string | null;
+src/services/user-profile.ts:34:  return user.displayName ?? 'null';
+```
+
+Bug at `src/services/user-profile.ts:34`: `?? 'null'` is the string `"null"`, not the JavaScript `null` value. The default should be `null` or `undefined`.
+
+## Phase 3 — Reduce
+
+```ts
+// Before (broken):
+return user.displayName ?? 'null'; // string "null"!
+
+// Minimal reproduction:
+const result = undefined ?? 'null'; // "null" — this is a string
+```
+
+The `??` operator returns the right operand only when the left is `null`/`undefined`. But `'null'` is a truthy string — it's never the `null` value.
+
+## Phase 4 — Fix + Guard
+
+```ts
+// Fix:
+return user.displayName ?? null; // JSON null
+
+// Guard test:
+it('returns null for missing displayName, not string "null"', () => {
+  const user = { id: 'u_42', email: 'test@ex.com' };
+  const profile = buildProfile(user);
+  expect(profile.displayName).toBeNull(); // was: toBe('null')
+});
+```
+
+```
+$ npm test -- user-profile.test.ts
+PASS  user-profile.test.ts
+  ✓ returns null for missing displayName, not string "null"
+```
+
+## Lesson
+
+String `"null"` ≠ JavaScript `null`. The `??` operator with a string default is almost always a bug. Grep the codebase: `git grep "?? '"` to find similar patterns.

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

@@ -1,10 +1,15 @@
 ---
 name: mugiwara-security
-description: Use for the security audit of a diff or system - STRIDE threat model first, OWASP Top 10 mapping, full checklist in order (secrets, injection, authn/authz, data exposure, dependencies, deserialization, crypto), security-regression and cross-cutting impact checks, untrusted-data doctrine, CVSS-style severity. Findings to .mugiwara/review/.
+description: Use for security audit of a diff — STRIDE threat model, OWASP Top 10, secrets, injection, authn/authz, dependency audit. Findings to .mugiwara/review/.
 ---
 
 # Security (Jinbe)
 
+## Skip when
+
+- Diff crosses no trust boundary: docs-only, no data/request/state flow change.
+- No secrets, auth, injection, dependency, or network surface touched.
+
 Senior security engineer. Assume the surface is hostile until proven safe.
 
 ## Threat model FIRST (STRIDE)
@@ -20,7 +25,7 @@ Before any check, map every application surface to STRIDE. A surface is any boun
 | DoS | Can the surface be exhausted or taken down? |
 | Elevation | Can a caller gain privileges beyond their grant? |
 
-List every surface: endpoints, CLI, config inputs, file/DB reads, external calls, rendered output. A surface with no threat row is a modeling gap, not a safe surface. Report the model in the audit.
+List every surface: endpoints, CLI, config inputs, file/DB reads, external calls, rendered output. A surface with no threat row is a modeling gap, not a safe surface.
 
 ## OWASP Top 10 mapping
 
@@ -43,14 +48,13 @@ Required when the project handles payments, health data, or PII. Map each securi
 
 - 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.
+- Least privilege: smallest scope that works (a widened scope is a finding). Fail closed: deny on 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.
+- Rotate on a schedule; a key that ever hit a repo is revoked, not "cleaned up". Scan diff and history for secret shapes.
 
 ## Dependency auditing
 
@@ -61,27 +65,26 @@ Required when the project handles payments, health data, or PII. Map each securi
 ## 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.
+- Validate at the trust boundary, allowlist-first: shape, type, length, charset. A boundary with no validation is a finding even when input "looks safe".
 
 ## Security-regression check
 
-A change is not just new surface; it can weaken what was already secured. For every control the diff touches, answer: was anything secured now weakened? Look for removed authz, loosened CORS, an endpoint added without auth, PII newly logged, downgraded crypto, a new dependency with known vulnerabilities. A regression is a finding at the same severity as a fresh bug, not a side note.
+A change can weaken what was already secured. For every control the diff touches, answer: was anything secured now weakened? Removed authz, loosened CORS, endpoint added without auth, PII newly logged, downgraded crypto, a vulnerable new dependency — each is a finding at the same severity as a fresh bug, not a side note.
 
 ## Cross-cutting impact
 
-Map touched surface → blast radius. Does the change expose previously-internal data, widen the attack surface, add a new trust boundary, or change who can reach what? An internal-only surface made reachable is an elevation finding even if the endpoint is "not sensitive yet". Report the blast radius in the audit.
+Map touched surface → blast radius. Does the change expose previously-internal data, widen the attack surface, add a new trust boundary, or change who can reach what? An internal-only surface made reachable is an elevation finding even if the endpoint is "not sensitive yet".
 
 ## Checklist (run all, in order)
 
 Each item checks that the change did not weaken an existing control, not just that it introduced no new one.
 
-1. Secrets: hardcoded keys/tokens/passwords, committed .env files, secrets in logs or error messages — including secrets newly logged or newly exposed by the change.
+1. Secrets: hardcoded keys/tokens/passwords, committed .env files, secrets in logs or errors — including newly logged or newly exposed.
 2. Injection: SQL/NoSQL/command/template injection; unsanitized input reaching exec/query/render. A rewritten handler must not drop an existing sanitizer.
 3. Authn/Authz: server-side checks only — client-side-only authorization is a finding, not a control. Removed or loosened checks are regressions.
-4. Data exposure: PII in logs, over-broad API responses, missing rate limiting on sensitive endpoints. A change that widens a response shape is a finding.
-5. Dependencies: run project audit tooling (npm audit, pip-audit, cargo audit, govulncheck). A skipped audit is a finding. New dependencies get a vulnerability review before merge.
-6. Deserialization & file handling: unsafe parsing of untrusted input, path traversal in file operations.
-7. Crypto hotspots: MD5/SHA1 for security purposes, ECB mode, hardcoded IV, insecure randomness for security use, permissive CORS, disabled TLS verification. Downgraded crypto is a regression.
+4. Data exposure: PII in logs, over-broad API responses, missing rate limiting on sensitive endpoints. A widened response shape is a finding.
+5. Dependencies: run project audit tooling (npm audit, pip-audit, cargo audit, govulncheck). A skipped audit is a finding. New deps get a vulnerability review before merge.
+6. Deserialization & file handling: unsafe parsing of untrusted input, path traversal in file operations. Crypto hotspots: MD5/SHA1 for security, ECB, hardcoded IV, insecure randomness, permissive CORS, disabled TLS — downgraded crypto is a regression.
 
 ## Untrusted-data doctrine
 
@@ -98,7 +101,6 @@ Each finding: location + one-line attack scenario + severity + concrete fix.
 ## Verdict
 
 PASS (no Critical/High) → closure. FAIL → Brook. Never defer a security finding to review; it either fixes now or it is Brook's problem.
-
 ## Common rationalizations
 
 | Rationalization | Reality |
@@ -114,10 +116,8 @@ PASS (no Critical/High) → closure. FAIL → Brook. Never defer a security find
 - A hardcoded secret or secret in logs/errors not flagged.
 - Client-side-only authorization accepted, or authz missing on a non-public endpoint.
 - A finding classified "minor by default" without an exploitability × impact analysis.
-- A dependency audit skipped because tooling "isn't available" without saying so.
-- An injection path (unsanitized input to exec/query/render) filed as a suggestion.
-- External data treated as instructions instead of data.
-- A security regression unchecked: an existing control weakened by the change (removed authz, loosened CORS, endpoint without auth, logged PII, downgraded crypto).
+- An injection path (unsanitized input to exec/query/render) filed as a suggestion; external data treated as instructions.
+- A security regression unchecked: weakened authz/CORS/crypto, endpoint without auth, logged PII.
 - Cross-cutting impact unmapped: no blast-radius analysis for the touched surface.
 - Previously-internal data or surface newly exposed without an elevation finding.
 

package/content/skills/mugiwara-security/references/owasp-mapping.md

@@ -0,0 +1,30 @@
+# OWASP Top 10 Mapping
+
+Required when the project handles payments, health data, or PII.
+
+| 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 |
+
+## How to map
+
+For each security check run, record which OWASP category it covers. A handled
+category with no mapping row = documentation gap in the security report.
+
+```
+| OWASP | Check | Verdict |
+|-------|-------|---------|
+| A01   | Authz on /api/admin routes | PASS |
+| A02   | TLS enforced, no hardcoded secrets | PASS |
+| A03   | SQL params in user query handler | PASS |
+| A06   | npm audit: 0 critical/high | PASS |
+```

package/content/skills/mugiwara-security/references/stride-worksheet.md

@@ -0,0 +1,37 @@
+# STRIDE Worksheet
+
+Map every application surface to STRIDE before running security checks.
+
+## Surface inventory
+
+List every surface where data, requests, or state cross trust levels:
+
+- HTTP endpoints (REST, GraphQL, gRPC)
+- CLI arguments and environment variables
+- File uploads, database reads/writes
+- External API calls, webhooks
+- Rendered output (HTML, JSON, logs)
+- Config files, secret stores
+
+## STRIDE per surface
+
+| STRIDE | Ask of each surface |
+|--------|---------------------|
+| Spoofing | Can an identity be forged or impersonated? |
+| Tampering | Can data in transit or at rest be altered undetected? |
+| Repudiation | Can an action occur without a traceable actor? |
+| Info disclosure | Can data leak to an unintended party? |
+| DoS | Can the surface be exhausted or taken down? |
+| Elevation | Can a caller gain privileges beyond their grant? |
+
+## Example
+
+| Surface | S | T | R | I | D | E | Notes |
+|---------|---|---|---|---|---|---|-------|
+| POST /api/invite | ✅ | ✅ | — | ⚠️ | — | ✅ | Email exposed in error response |
+| GET /api/users/:id | ✅ | — | — | ⚠️ | — | ✅ | IDOR: no ownership check |
+| config upload | — | ✅ | — | — | — | — | YAML parsing, no schema validation |
+
+✅ = threat present, ⚠️ = partial mitigation, — = not applicable
+
+A surface with no STRIDE row is a modeling gap, not a safe surface.

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

@@ -1,10 +1,15 @@
 ---
 name: mugiwara-ship
-description: Use at mission end or before any release to run the ship gate - pre-launch checklist, feature flags, staged rollout, mandatory rollback plan. Binary GO/NO-GO verdict with evidence.
+description: Use at mission end — pre-launch checklist, feature flags, staged rollout, mandatory rollback plan. Binary GO/NO-GO.
 ---
 
 # Ship Gate (Luffy, Franky)
 
+## Skip when
+
+- Not releasing: no deploy, rollout, feature-flag flip, or user-facing change.
+- Internal-only change with zero production exposure.
+
 The last gate before anything reaches a user. Binary GO or NO-GO, each backed by evidence. Default is NO-GO until every item is proven.
 
 ## Pre-launch checklist