@kennethsolomon/shipkit 3.0.7 → 3.2.0

package/README.md

@@ -62,7 +62,7 @@ npm install -g @kennethsolomon/shipkit && shipkit
 
 ShipKit installs slash commands and skills into `~/.claude/`. Each command is a focused instruction set that Claude follows — no magic, just structured prompts that enforce quality gates.
 
-The workflow is linear: **Brainstorm → Plan → Branch → Test → Implement → Lint → Security → Review → Ship.**
+The workflow is linear: **Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → E2E Tests → Finish → Sync Features**
 
 Every gate must pass before the next step. If lint fails, fix it. If tests don't cover new code, write them. Security issues block the PR. This isn't optional — it's the whole point.
 
@@ -76,7 +76,7 @@ Every gate must pass before the next step. If lint fails, fix it. If tests don't
 
 ```
 Brainstorm → Plan → Branch → [Schema] → Write Tests → Implement → Commit
-  → Lint ✓ → Test ✓ → Security ✓ → Review ✓ → Update Task → Finish
+  → Lint ✓ → Test ✓ → Security ✓ → Review ✓ → E2E ✓ → Update Task → Finish → Sync Features
 ```
 
 | # | Command | Purpose |
@@ -84,26 +84,32 @@ Brainstorm → Plan → Branch → [Schema] → Write Tests → Implement → Co
 | 1 | read `tasks/todo.md` | Pick the next task |
 | 2 | read `tasks/lessons.md` | Review past corrections |
 | 3 | `/sk:brainstorm` | Clarify requirements — no code |
-| 4 | `/sk:frontend-design` | UI design spec *(skip if backend-only)*. Add `--pencil` to also generate a Pencil visual mockup |
-| 5 | `/sk:api-design` | API contracts *(skip if no new endpoints)* |
-| 6 | `/sk:accessibility` | WCAG 2.1 AA audit on design *(skip if no frontend)* |
-| 7 | `/sk:write-plan` | Write plan to `tasks/todo.md` |
-| 8 | `/sk:branch` | Create branch from current task |
-| 9 | `/sk:schema-migrate` | Schema change analysis *(skip if no DB changes)* |
-| 10 | `/sk:write-tests` | TDD red: write failing tests first |
-| 11 | `/sk:execute-plan` | TDD green: make tests pass |
-| 12 | `/sk:smart-commit` | Conventional commit |
-| 13 | **`/sk:lint`** | **GATE** — all linters must pass |
-| 14 | `/sk:smart-commit` | Auto-skip if already clean |
-| 15 | **`/sk:test`** | **GATE** — 100% coverage on new code |
-| 16 | `/sk:smart-commit` | Auto-skip if already clean |
-| 17 | **`/sk:security-check`** | **GATE** — 0 issues |
-| 18 | `/sk:smart-commit` | Auto-skip if already clean |
-| 19 | **`/sk:review`** | **GATE** — 0 issues including nitpicks |
-| 20 | `/sk:smart-commit` | Auto-skip if already clean |
-| 21 | `/sk:update-task` | Mark done, log completion |
-| 22 | `/sk:finish-feature` | Changelog + PR |
-| 23 | `/sk:release` | Version bump + tag *(optional)* |
+| 4 | `/sk:frontend-design` or `/sk:api-design` | Design spec *(skip if not needed)*. Frontend: add `--pencil` for Pencil visual mockup. API: REST/GraphQL contracts. |
+| 5 | `/sk:accessibility` | WCAG 2.1 AA audit on design *(skip if no frontend)* |
+| 6 | `/sk:write-plan` | Write plan to `tasks/todo.md` |
+| 7 | `/sk:branch` | Create branch from current task |
+| 8 | `/sk:schema-migrate` | Schema change analysis *(skip if no DB changes)* |
+| 9 | `/sk:write-tests` | TDD red: write failing tests first |
+| 10 | `/sk:execute-plan` | TDD green: make tests pass |
+| 11 | `/sk:smart-commit` | Conventional commit |
+| 12 | **`/sk:lint`** | **GATE** — Lint + Dep Audit — all linters must pass |
+| 13 | `/sk:smart-commit` | Auto-skip if already clean |
+| 14 | **`/sk:test`** | **GATE** — 100% coverage on new code |
+| 15 | `/sk:smart-commit` | Auto-skip if already clean |
+| 16 | **`/sk:security-check`** | **GATE** — 0 issues |
+| 17 | `/sk:smart-commit` | Auto-skip if already clean |
+| 18 | **`/sk:perf`** | **GATE** *(optional)* — critical/high findings = 0 |
+| 19 | `/sk:smart-commit` | Auto-skip if already clean |
+| 20 | **`/sk:review`** | **GATE** — Review + Simplify — 0 issues including nitpicks |
+| 21 | `/sk:smart-commit` | Auto-skip if already clean |
+| 22 | **`/sk:e2e`** | **GATE** — E2E Tests — all end-to-end tests must pass |
+| 23 | `/sk:smart-commit` | Auto-skip if already clean |
+| 24 | `/sk:update-task` | Mark done, log completion |
+| 25 | `/sk:finish-feature` | Changelog + PR |
+| 26 | `/sk:features` | Sync Features — update docs/features/ specs *(required)* |
+| 27 | `/sk:release` | Version bump + tag *(optional)* |
+
+> **Fix & Retest Protocol:** All code-producing gates (Lint, Test, Security, Performance, Review, E2E) apply the Fix & Retest Protocol: logic changes require updating unit tests before committing the fix. Fix immediately, then re-run — never ask the user to re-run.
 
 ### Bug Fix Flow
 
@@ -118,8 +124,8 @@ Debug → Plan → Branch → Write Tests → Implement → Lint ✓ → Test
 | 3 | `/sk:branch` | Create branch |
 | 4 | `/sk:write-tests` | Reproduce the bug in a test |
 | 5 | `/sk:execute-plan` | Fix — make the test pass |
-| 6–9 | lint → test → security → review | Quality gates |
-| 10 | `/sk:finish-feature` | Changelog + PR |
+| 6–10 | `/sk:lint` → `/sk:test` → `/sk:security-check` → `/sk:review` → `/sk:e2e` | Quality gates |
+| 11 | `/sk:finish-feature` | Changelog + PR |
 
 ### Hotfix Flow
 
@@ -198,6 +204,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/sk:test` | Auto-detect and run all test suites, verify 100% coverage on new code |
 | `/sk:security-check` | OWASP security audit across changed code |
 | `/sk:perf` | Performance audit: bundle size, N+1 queries, Core Web Vitals |
+| `/sk:seo-audit` | SEO audit — dual-mode (source templates + dev server), ask-before-fix, checklist output to `tasks/seo-findings.md` |
 | `/sk:review` | Rigorous self-review across 7 dimensions |
 
 ### Shipping

package/commands/sk/security-check.md

@@ -108,7 +108,7 @@ Detect the project stack from `CLAUDE.md`, `package.json`, `composer.json`, `pyp
 
 ## Generate Report
 
-Write findings to `tasks/security-findings.md` using this format:
+Write findings to `tasks/security-findings.md` using this format. **Never overwrite** `tasks/security-findings.md` — append new audits with a date header. Old run checkboxes stay as-is (audit trail); only update findings from the current run.
 
 ```markdown
 # Security Audit — YYYY-MM-DD
@@ -119,42 +119,43 @@ Write findings to `tasks/security-findings.md` using this format:
 
 ## Critical (must fix before deploy)
 
-- **[FILE:LINE]** Description of vulnerability
+- [ ] **[FILE:LINE]** Description of vulnerability
   **Standard:** OWASP A03 — Injection (CWE-89)
   **Risk:** What could happen if exploited
   **Recommendation:** How to fix it
+- [x] **[FILE:LINE]** Description *(resolved)*
 
 ## High (fix before production)
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Standard:** ...
   **Risk:** ...
   **Recommendation:** ...
 
 ## Medium (should fix)
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Standard:** ...
   **Recommendation:** ...
 
 ## Low / Informational
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Recommendation:** ...
 
 ## Passed Checks
 
-- List of categories that passed with no findings
+- [Categories with no findings]
 
 ## Summary
 
-| Severity | Count |
-|----------|-------|
-| Critical | N |
-| High     | N |
-| Medium   | N |
-| Low      | N |
-| **Total** | **N** |
+| Severity | Open | Resolved this run |
+|----------|------|-------------------|
+| Critical | N    | N                 |
+| High     | N    | N                 |
+| Medium   | N    | N                 |
+| Low      | N    | N                 |
+| **Total** | **N** | **N**            |
 ```
 
 ## When Done
@@ -162,15 +163,29 @@ Write findings to `tasks/security-findings.md` using this format:
 Tell the user:
 
 > "Security audit complete. Findings saved to `tasks/security-findings.md`.
-> - **Critical:** N | **High:** N | **Medium:** N | **Low:** N
+> - **Critical:** N open (N resolved) | **High:** N open (N resolved) | **Medium:** N open | **Low:** N open
 >
 > Review the findings, then run `/sk:finish-feature` when ready to finalize."
 
 If there are Critical or High findings:
-> "There are critical/high findings that should be addressed before merging. Fix them, then re-run `/sk:security-check` to verify."
+> "There are critical/high findings that MUST be fixed before merging. These are HARD GATE items — `- [ ]` findings block all forward progress. Fix them, then re-run `/sk:security-check` to verify."
 
 **Do not auto-fix.** The user decides what to address.
 
+### Fix & Retest Protocol
+
+When applying a fix, classify it before committing:
+
+**a. Config/hardening change** (adding security header, fixing CORS config, adding rate limit, sanitizing output without changing logic) → commit and re-run `/sk:security-check`. No test update needed.
+
+**b. Logic change** (new input validation branch, modified query parameterization, changed auth check, refactored data handling) → trigger protocol:
+1. Update or add failing unit tests for the new secure behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:security-check` from scratch
+
+**Why:** Security fixes often change logic (e.g., adding parameterized queries, sanitizing inputs). Tests must cover the new secure behavior, not just the old vulnerable path.
+
 ---
 
 ## Model Routing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennethsolomon/shipkit",
-  "version": "3.0.7",
+  "version": "3.2.0",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/sk:accessibility/SKILL.md

@@ -89,20 +89,25 @@ Write findings to `tasks/accessibility-findings.md`:
 
 ## Failures (must fix)
 
-- **[Component/File:Line]** Description
+- [ ] **[Component/File:Line]** Description
+  **Criterion:** WCAG X.X.X — [Name]
+  **Impact:** [Who is affected and how]
+  **Recommendation:** [How to fix]
+
+- [x] **[Component/File:Line]** Description *(resolved)*
   **Criterion:** WCAG X.X.X — [Name]
   **Impact:** [Who is affected and how]
   **Recommendation:** [How to fix]
 
 ## Warnings (should fix)
 
-- **[Component/File:Line]** Description
+- [ ] **[Component/File:Line]** Description
   **Criterion:** WCAG X.X.X — [Name]
   **Recommendation:** [How to fix]
 
 ## Manual Checks Required
 
-- [Things that require human/screen reader testing]
+- [ ] [Things that require human/screen reader testing]
 
 ## Passed Checks
 
@@ -110,11 +115,11 @@ Write findings to `tasks/accessibility-findings.md`:
 
 ## Summary
 
-| Level    | Count |
-|----------|-------|
-| Failures | N     |
-| Warnings | N     |
-| Manual   | N     |
+| Level    | Open | Resolved this run |
+|----------|------|-------------------|
+| Failures | N    | N                 |
+| Warnings | N    | N                 |
+| Manual   | N    | N                 |
 ```
 
 **Never overwrite** `tasks/accessibility-findings.md` — append new audits with a date header.

package/skills/sk:e2e/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: sk:e2e
+description: "Run E2E behavioral verification using agent-browser as the final quality gate before finalize. Tests the complete, reviewed, secure implementation from a user's perspective."
+---
+
+# /sk:e2e
+
+E2E behavioral verification — the final quality gate before `/sk:finish-feature`. Runs after Review to verify the complete, reviewed, secure implementation works end-to-end from a user's perspective.
+
+**Hard gate:** all scenarios must pass. Zero failures allowed.
+
+## Allowed Tools
+
+Bash, Read, Glob, Grep
+
+## Steps
+
+### 1. Read Context
+
+Read these files to understand what to test:
+- `tasks/todo.md` — planned features and acceptance criteria
+- `tasks/findings.md` — design decisions and expected behaviors
+- `tasks/progress.md` — implementation notes
+
+### 2. Check agent-browser is Available
+
+```bash
+agent-browser --version
+```
+
+If not found, instruct the user:
+```
+agent-browser is required. Install it:
+  npm install -g agent-browser
+  agent-browser install   # downloads Chrome (~100MB)
+Then re-run /sk:e2e.
+```
+Stop if not available.
+
+### 3. Detect Local Server
+
+Determine what URL to test against:
+- Check for a dev server command in `package.json` scripts (`dev`, `start`)
+- Check for `artisan serve` in Laravel projects (`php artisan serve`)
+- Check for `vite` or `next dev`
+- If a server is already running (check common ports: 3000, 5173, 8000, 8080), use it
+- If no server is running, start one in the background and note the URL
+
+### 4. Locate E2E Test Files
+
+Find E2E test scenarios written during the Write Tests step:
+```bash
+find . -name "*.e2e.*" -o -name "*.spec.*" | grep -v node_modules
+ls tests/e2e/ 2>/dev/null
+```
+
+If no E2E test files exist, derive scenarios from `tasks/todo.md` acceptance criteria and `tasks/findings.md`.
+
+### 5. Run E2E Scenarios
+
+For each scenario, use agent-browser following this core pattern:
+
+```bash
+# Navigate to the page
+agent-browser open <url>
+
+# Get interactive elements (token-efficient ref-based snapshot)
+agent-browser snapshot -i
+
+# Interact using @refs (never CSS selectors)
+agent-browser click @e1
+agent-browser fill @e2 "input value"
+agent-browser press Enter
+
+# Use semantic locators when @refs aren't stable
+agent-browser find role button
+agent-browser find text "Expected Text"
+agent-browser find label "Email"
+
+# Assert expected state
+agent-browser snapshot   # check content
+agent-browser find text "Success Message"
+```
+
+**Ref-based interaction is required.** Never use CSS selectors (`#id`, `.class`) — use semantic locators (`find role`, `find text`, `find label`, `find placeholder`) for stability.
+
+For each scenario, record:
+- Scenario name
+- Steps executed
+- Result: PASS or FAIL
+- On FAIL: what was expected vs. what was found (include snapshot excerpt)
+
+### 6. Report Results
+
+```
+E2E Results:
+  PASS  [scenario name]
+  PASS  [scenario name]
+  FAIL  [scenario name] — expected "X" but found "Y"
+
+Total: X passed, Y failed
+```
+
+If all pass → proceed to Fix & Retest Protocol section (no action needed).
+If any fail → apply Fix & Retest Protocol.
+
+## Fix & Retest Protocol
+
+When this gate requires a fix, classify it before committing:
+
+**a. Style/config/wording change** (CSS tweak, copy change, selector fix) → commit and re-run `/sk:e2e` (no unit test update needed)
+
+**b. Logic change** (new branch, modified condition, new data path, query change, new function, API change) → trigger protocol:
+1. Update or add failing unit tests for the new behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:e2e` from scratch
+
+**Exception:** Formatter auto-fixes are never logic changes — bypass protocol automatically.
+
+**This gate cannot be skipped.** All scenarios must pass before proceeding to `/sk:update-task`.
+
+## Next Steps
+
+If all scenarios pass:
+> "E2E gate clean. Run `/sk:update-task` to mark the task done."
+
+If failures remain after fixes:
+> "Re-running /sk:e2e — [N] scenarios still failing."
+
+---
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:e2e"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |
+
+> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:lint/SKILL.md

@@ -66,15 +66,38 @@ Agent 2: "Run vendor/bin/rector --dry-run. Report all suggested changes with fil
 Agent 3: "Run npx eslint . Report all errors with file:line."
 ```
 
-### 5. Fix and Re-run
+### 5. Run Dependency Audit
 
-If any analyzer reports errors:
+Run dependency vulnerability checks for detected stacks:
+
+| Stack | Command | Block on |
+|-------|---------|----------|
+| PHP (composer.json) | `composer audit` | any severity with fix available (`composer audit` has no severity filter) |
+| Node (package.json) | `npm audit --audit-level=high` | high or critical |
+| Node (yarn.lock) | `yarn audit --level high` | high or critical |
+| Node (pnpm-lock.yaml) | `pnpm audit --audit-level high` | high or critical |
+| Python (pyproject.toml / requirements.txt) | `pip-audit` | high or critical |
+
+For each detected package manager, run the audit command and capture output.
+
+**Block (fail this gate):**
+- PHP: any vulnerability that has a fix available (`composer audit` exits non-zero for all severities — no filtering option exists)
+- Node/Python: critical or high severity vulnerabilities that have a fix available
+
+**Warn (pass with note):** medium/low severity for Node/Python, or any severity with no available fix — note in report but do not block.
+
+Skip stacks not present in the project.
+
+### 6. Fix and Re-run
+
+If any analyzer reports errors or the dep audit blocks:
 1. Fix all reported issues
 2. Re-run formatters (fixes may need formatting)
 3. Re-launch all analyzers in parallel
-4. Loop until every tool exits clean
+4. Re-run dep audit if any dependency was fixed
+5. Loop until every tool exits clean
 
-### 6. Report Results
+### 7. Report Results
 
 Print one line per tool:
 
@@ -90,12 +113,34 @@ ESLint:        X errors fixed / clean
 ruff check:    X issues fixed / clean
 golangci-lint: X issues fixed / clean
 cargo clippy:  X warnings fixed / clean
+composer audit: clean / X vulns blocked
+npm audit:     clean / X vulns blocked
 ```
 
 Only include lines for detected tools. All must show "clean" before this skill passes.
 
 ---
 
+## Fix & Retest Protocol
+
+When this gate requires a fix, classify it before committing:
+
+**a. Formatter auto-fix** (Pint, Prettier, gofmt, cargo fmt changed whitespace/style) → commit and re-run `/sk:lint`. Never a logic change — bypass protocol.
+
+**b. Analyzer fix** (PHPStan type error, Rector suggestion, ESLint error, ruff violation) → classify each fix:
+  - Type annotation, import order, unused var, style rule → **style fix** → commit and re-run
+  - New guard clause, changed condition, extracted function, modified data flow → **logic change** → trigger protocol:
+    1. Update or add failing unit tests for the new behavior
+    2. Re-run `/sk:test` — must pass at 100% coverage
+    3. Commit (tests + fix together in one commit)
+    4. Re-run `/sk:lint` from scratch
+
+**c. Dependency vulnerability fix** (composer audit / npm audit finding) → classify:
+  - Version bump with no API change → **style fix** → commit and re-run
+  - Version bump with API/behavior change → **logic change** → trigger protocol
+
+---
+
 ## Model Routing
 
 Read `.shipkit/config.json` from the project root if it exists.

package/skills/sk:perf/SKILL.md

@@ -120,24 +120,25 @@ Write findings to `tasks/perf-findings.md`:
 
 ## Critical
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Impact:** What happens at scale
   **Recommendation:** How to fix
+- [x] **[FILE:LINE]** Description *(resolved)*
 
 ## High
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Impact:** ...
   **Recommendation:** ...
 
 ## Medium
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Recommendation:** ...
 
 ## Low
 
-- **[FILE:LINE]** Description
+- [ ] **[FILE:LINE]** Description
   **Recommendation:** ...
 
 ## Passed Checks
@@ -146,13 +147,13 @@ Write findings to `tasks/perf-findings.md`:
 
 ## Summary
 
-| Severity | Count |
-|----------|-------|
-| Critical | N |
-| High     | N |
-| Medium   | N |
-| Low      | N |
-| **Total** | **N** |
+| Severity | Open | Resolved this run |
+|----------|------|-------------------|
+| Critical | N    | N                 |
+| High     | N    | N                 |
+| Medium   | N    | N                 |
+| Low      | N    | N                 |
+| **Total** | **N** | **N**            |
 ```
 
 **Never overwrite** `tasks/perf-findings.md` — append new audits with a date header.
@@ -171,6 +172,27 @@ If there are no critical or high findings:
 
 ---
 
+## Fix & Retest Protocol
+
+When applying a performance fix, classify it before committing:
+
+**a. Config/infrastructure change** (adding cache headers, enabling compression, changing CDN config, adjusting connection pool size) → commit and re-run `/sk:perf`. No test update needed.
+
+**b. Logic change** (fixing N+1 query by changing data-fetching logic, refactoring algorithm, modifying data structure, changing pagination logic) → trigger protocol:
+1. Update or add failing unit tests for the new optimized behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:perf` to verify the fix resolved the finding
+
+**Common logic-change performance fixes:**
+- N+1 fix: changes how related data is fetched → update tests that assert on query count or data shape
+- Algorithm change: O(n²) → O(n log n) → update tests that assert on output correctness
+- Pagination: adding LIMIT/offset → update tests that assert on result set size
+
+**Why:** Performance fixes often change how data is fetched or processed. Tests must verify the optimized path produces correct results.
+
+---
+
 ## Model Routing
 
 Read `.shipkit/config.json` from the project root if it exists.

package/skills/sk:review/SKILL.md

@@ -15,14 +15,31 @@ This is a **report-only** step. If Critical or Warning issues are found, the use
 
 ## Allowed Tools
 
-Bash, Read, Glob, Grep
+Bash, Read, Glob, Grep, Skill
 
-**Intentionally NO Write or Edit** — this skill is report-only. If issues are found, the user decides what to fix.
+**Step 0 only:** the `simplify` skill is invoked via the Skill tool, which carries its own Write/Edit permissions. All other steps are read-only — no direct Write or Edit calls. If issues are found in the main review, the user decides what to fix.
 
 ## Steps
 
 You MUST complete these steps in order:
 
+### 0. Run Simplify First
+
+Before reviewing, invoke the built-in `simplify` skill on the changed files to catch reuse, quality, and efficiency issues automatically:
+
+> "Review the changed files on this branch for reuse, quality, and efficiency. Fix any issues found."
+
+Use `git diff main..HEAD --name-only` to identify the changed files, then run simplify on them.
+
+If simplify makes any changes:
+1. Verify the changes are correct
+2. Commit them with `/sk:smart-commit` before continuing the review
+3. Note in the review report: "Simplify pre-pass: X files updated"
+
+If simplify makes no changes, proceed directly to step 1.
+
+**Note:** Simplify runs automatically as part of `/sk:review` — users do not need to run it separately.
+
 ### 1. Read Project Context
 
 ```
@@ -327,6 +344,20 @@ If the user wants to fix nitpicks, loop back to `/sk:debug` + `/sk:smart-commit`
 If the review is **completely clean**:
 > "Review complete — no issues found. Run `/sk:finish-feature` to finalize the branch and create a PR."
 
+### Fix & Retest Protocol
+
+When applying a fix from this review, classify it before committing:
+
+**a. Style/naming/comment change** (rename variable, add doc comment, reorder imports, extract constant) → commit and re-run `/sk:review`. No test update needed.
+
+**b. Logic change** (fix incorrect condition, add missing null check, change data flow, refactor algorithm, fix async bug) → trigger protocol:
+1. Update or add failing unit tests for the corrected behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:review` from scratch
+
+**Why:** Review catches logic bugs. Fixing a logic bug without updating tests leaves the test suite asserting on the old (wrong) behavior.
+
 ---
 
 ## Model Routing