@tianhai/pi-workflow-kit 0.15.0 → 0.17.1

package/docs/plans/completed/2026-05-25-pr5-improvements-implementation.md

@@ -0,0 +1,273 @@
+# Implementation Plan: PR #5 Improvements
+
+Fixes CI failures, tightens consistency across the workflow chain, and improves the design-review integration so every skill speaks with one voice.
+
+---
+
+## Task 1: Fix biome lint and format errors in workflow-guard
+
+<!-- tdd: modifying-tested-code -->
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: The biome linter runs on `extensions/workflow-guard.ts` and `tests/workflow-guard.test.ts`
+  - When: `npx biome check` is executed
+  - Then: Zero errors and zero warnings are emitted
+- **Edge Case (no functional regression)**:
+  - Given: The existing test suite for workflow-guard
+  - When: `npx vitest run` is executed
+  - Then: All 27 existing tests still pass
+
+Files:
+- `extensions/workflow-guard.ts`
+- `tests/workflow-guard.test.ts`
+
+Steps:
+1. Fix `extensions/workflow-guard.ts` line 163 — replace string concatenation with template literal:
+   ```ts
+   // Before:
+   return !absolute.startsWith(plansDir + "/");
+   // After:
+   return !absolute.startsWith(`${plansDir}/`);
+   ```
+2. Fix `tests/workflow-guard.test.ts` line 1 — remove unused `beforeEach` import:
+   ```ts
+   // Before:
+   import { describe, it, expect, beforeEach } from "vitest";
+   // After:
+   import { describe, it, expect } from "vitest";
+   ```
+3. Fix `tests/workflow-guard.test.ts` line 19 — remove unused `getCurrentPhase` import:
+   ```ts
+   // Before:
+   import { getCurrentPhase, isSafeCommand, shouldBlockFilePath } from "../extensions/workflow-guard";
+   // After:
+   import { isSafeCommand, shouldBlockFilePath } from "../extensions/workflow-guard";
+   ```
+4. Run `npx biome check extensions/ tests/` — confirm zero errors.
+5. Run `npx vitest run` — confirm all tests pass.
+
+---
+
+## Task 2: Fix CHANGELOG `[Unreleased]` link
+
+<!-- tdd: trivial -->
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: The CHANGELOG.md file with version link references
+  - When: A reader clicks the `[Unreleased]` link
+  - Then: It shows changes between v0.16.0 and HEAD (not v0.14.0)
+
+Files:
+- `CHANGELOG.md`
+
+Steps:
+1. Update the `[Unreleased]` link at the bottom of CHANGELOG.md:
+   ```markdown
+   // Before:
+   [Unreleased]: https://github.com/yinloo-ola/pi-workflow-kit/compare/v0.14.0...HEAD
+   // After:
+   [Unreleased]: https://github.com/yinloo-ola/pi-workflow-kit/compare/v0.16.0...HEAD
+   ```
+
+---
+
+## Task 3: Align skill descriptions — trim design-review, match tone
+
+<!-- tdd: trivial -->
+
+All six skills should follow the same description pattern: a one-sentence summary of what the skill does, followed by trigger guidance. The `design-review` description currently front-loads usage instructions that belong in the skill body.
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: The `description` frontmatter of `skills/design-review/SKILL.md`
+  - When: Compared to the other five skill descriptions
+  - Then: It follows the same pattern — concise purpose first, trigger guidance second
+- **Edge Case (no information loss)**:
+  - Given: The trimmed description
+  - When: An agent reads it for skill matching
+  - Then: It still contains enough signal to trigger correctly (keywords: audit, design, production risks, security, scalability)
+
+Files:
+- `skills/design-review/SKILL.md`
+
+Steps:
+1. Replace the description in `skills/design-review/SKILL.md` frontmatter:
+   ```yaml
+   // Before:
+   description: "Audit a design doc for production risks — security, scalability, fault tolerance, and operational hazards. Run after brainstorming, before writing-plans. Use when the brainstorm flags a non-trivial design, or when you want to stress-test a design for production readiness."
+   // After:
+   description: "Audit a design doc for production risks — security, scalability, fault tolerance, and operational hazards. Use after brainstorming for non-trivial designs, or when you want to stress-test a design for production readiness."
+   ```
+   This trims the redundant "Run after brainstorming, before writing-plans" (the workflow order is documented in README) while keeping the trigger guidance.
+
+---
+
+## Task 4: Remove redundant user confirmation for trivial design-review
+
+<!-- tdd: modifying-tested-code -->
+
+The brainstorming skill already asked the user to classify trivial vs non-trivial. When the design doc says "Simple change — no design review needed", the user already made that decision. Asking again in design-review step 2 adds friction without value.
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path (trivial skip)**:
+  - Given: A design doc with "Simple change — no design review needed"
+  - When: `/skill:design-review` is run
+  - Then: The agent automatically appends the "Skipped — trivial change" section and moves on, without asking the user to confirm
+- **Edge Case (non-trivial proceeds normally)**:
+  - Given: A design doc without the trivial marker
+  - When: `/skill:design-review` is run
+  - Then: The full audit proceeds as before (no behavior change)
+
+Files:
+- `skills/design-review/SKILL.md`
+
+Steps:
+1. In step 2 ("Check triviality"), replace the interactive confirmation with an automatic skip:
+   ```markdown
+   // Before:
+   2. **Check triviality** — if the design doc notes "Simple change — no design review needed", confirm with the user: "This looks like a trivial change. Skip the full audit?" If yes, append a brief section:
+
+   // After:
+   2. **Check triviality** — if the design doc notes "Simple change — no design review needed", append a brief section:
+   ```
+2. Remove the "If yes," conditional — the append and stop is now unconditional for trivial docs.
+3. Verify the file reads cleanly — the flow is now: find doc → check trivial → (if trivial: append + stop, else: continue to step 3).
+
+---
+
+## Task 5: Evaluate design for review need regardless of design doc presence
+
+<!-- tdd: trivial -->
+
+The brainstorming skill flags "database changes, external services, auth, concurrency, large data flows" for design-review. The writing-plans safety net checks for a slightly different list and only when a design doc exists. When writing-plans is used standalone (no design doc), the safety net never fires — so a non-trivial standalone design skips design-review entirely.
+
+The fix: always evaluate whether the design involves high-risk patterns, regardless of source. A design doc with no `## Architectural Review` section and a standalone user description both deserve the same scrutiny.
+
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path (design doc, no review section)**:
+  - Given: A design doc exists without an `## Architectural Review` section, and the design involves database schema changes
+  - When: Writing-plans step 1 runs
+  - Then: The agent prompts the user to run `/skill:design-review` or type 'proceed'
+- **Happy Path (standalone, non-trivial)**:
+  - Given: No design doc exists, and the user describes a feature involving authentication and external API integrations
+  - When: Writing-plans gathers context
+  - Then: The agent prompts: "This design involves [auth, external APIs] but hasn't been reviewed for production risks. Run `/skill:design-review` first, or type 'proceed' to skip."
+- **Edge Case (design doc already reviewed)**:
+  - Given: A design doc with an `## Architectural Review` section
+  - When: Writing-plans step 1 runs
+  - Then: No prompt — the review already happened
+- **Edge Case (trivial)**:
+  - Given: A trivial design (config rename, simple field addition) with or without a design doc
+  - When: Writing-plans evaluates the design
+  - Then: No prompt — no trigger categories matched
+
+Files:
+- `skills/brainstorming/SKILL.md`
+- `skills/writing-plans/SKILL.md`
+
+Steps:
+1. Update `skills/brainstorming/SKILL.md` step 4 to match writing-plans' more specific list:
+   ```markdown
+   // Before:
+   For non-trivial designs, note any areas that may need production-risk review (database changes, external services, auth, concurrency, large data flows). You don't need to audit them here — just flag them for the design-review stage.
+
+   // After:
+   For non-trivial designs, note any areas that may need production-risk review (database schema changes, authentication or authorization, external API integrations, concurrency or batch processing, file uploads or large data flows, Redis/caching/message queues). You don't need to audit them here — just flag them for the design-review stage.
+   ```
+2. Update `skills/writing-plans/SKILL.md` step 1 — consolidate the safety net into one check that applies regardless of whether a design doc exists. Replace the current conditional with:
+   ```markdown
+   // Before (current text — only checks design docs):
+   Then check whether the design doc has an `## Architectural Review` section. If it doesn't, and the design involves any of the following, prompt the user...
+
+   // After (unified check):
+   Then evaluate whether the design — whether from the design doc or from the user's description and codebase exploration — involves any of the following:
+
+   - Database schema changes or migrations
+   - Authentication or authorization logic
+   - External API or service integrations
+   - Concurrency or batch processing
+   - File uploads or large data flows
+   - Redis, caching, or message queues
+
+   If any apply AND the design doc does not already have an `## Architectural Review` section, prompt the user: "This design involves [list what you found] but hasn't been reviewed for production risks. Run `/skill:design-review` first, or type 'proceed' to skip."
+
+   If the design doc explicitly notes "Simple change — no design review needed", skip this check.
+   ```
+3. Verify the safety net fires for both design-doc and standalone paths, and skips when the review already exists.
+
+---
+
+## Task 6: Generalize `NODE_ENV` reference in executing-tasks
+
+<!-- tdd: trivial -->
+
+The QA Test frame references `NODE_ENV` which is Node.js-specific. Since the workflow kit is used across languages (the examples reference SQL, Go, etc.), this should be generalized.
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: The QA Test frame in `skills/executing-tasks/SKILL.md`
+  - When: A developer working in Python or Go reads it
+  - Then: The guidance makes sense without Node.js context
+- **Edge Case (Node.js users still understand)**:
+  - Given: A Node.js developer reading the same text
+  - When: They see the generalized phrasing
+  - Then: They understand it means `NODE_ENV=test` or equivalent
+
+Files:
+- `skills/executing-tasks/SKILL.md`
+
+Steps:
+1. In the QA Test frame, replace the `NODE_ENV` reference:
+   ```markdown
+   // Before:
+   External dependencies must be mocked or stubbed. `NODE_ENV` must be `test` (or equivalent).
+
+   // After:
+   External dependencies must be mocked or stubbed. Ensure the test environment is isolated (e.g., `NODE_ENV=test`, `GO_ENV=test`, or equivalent for your stack).
+   ```
+
+---
+
+## Task 7: Deduplicate test coverage requirement in writing-plans task format
+
+<!-- tdd: trivial -->
+
+The "Each task must include" section has two overlapping bullets about test coverage:
+1. The new Acceptance Criteria block (Happy Path + Edge Cases)
+2. The old "Each task's tests should cover the happy path and at least one edge case" bullet
+
+The Acceptance Criteria block supersedes the old bullet. Keeping both is redundant and confusing.
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: The task format section in `skills/writing-plans/SKILL.md`
+  - When: Reading the "Each task must include" bullets
+  - Then: Test coverage is specified exactly once (in the Acceptance Criteria block), not duplicated
+
+Files:
+- `skills/writing-plans/SKILL.md`
+
+Steps:
+1. Remove the redundant bullet from "Each task must include":
+   ```markdown
+   // Remove this line (now covered by Acceptance Criteria):
+   - Each task's tests should cover the happy path and at least one edge case or error path, with concrete assertions
+   ```
+2. Verify the Acceptance Criteria bullet already covers this requirement with its "Happy Path" and "Edge Cases & Error Paths" sub-bullets.
+
+---
+
+## Task 8: Run tests and verify CI passes
+
+<!-- tdd: trivial -->
+
+Files:
+- None (verification only)
+
+Steps:
+1. Run `npx biome check extensions/ tests/` — confirm zero errors.
+2. Run `npx vitest run` — confirm all existing tests pass.
+3. Verify the CHANGELOG link renders correctly.

package/docs/plans/completed/2026-05-25-pr5-improvements-progress.md

@@ -0,0 +1,17 @@
+# Progress: PR #5 Improvements
+
+Plan: docs/plans/2026-05-25-pr5-improvements-implementation.md
+Branch: design-review-split
+Started: 2026-05-25T12:00:00Z
+Last updated: 2026-05-25T12:26:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Fix biome lint and format errors in workflow-guard | 6f2eb8c |
+| 2 | ✅ done | Fix CHANGELOG `[Unreleased]` link | 4866c25 |
+| 3 | ✅ done | Align skill descriptions — trim design-review, match tone | 541ea9b |
+| 4 | ✅ done | Remove redundant user confirmation for trivial design-review | 953b6d6 |
+| 5 | ✅ done | Evaluate design for review need regardless of design doc presence | 20ea47e |
+| 6 | ✅ done | Generalize `NODE_ENV` reference in executing-tasks | b117a44 |
+| 7 | ✅ done | Deduplicate test coverage requirement in writing-plans task format | 3a34266 |
+| 8 | ✅ done | Run tests and verify CI passes | — |

package/docs/plans/completed/2026-06-03-add-verify-skill-design.md

@@ -0,0 +1,51 @@
+# Add Verify Skill — Design Doc
+
+## Context
+
+Based on [Chris LeMa's "The Last Prompt"](https://chrislema.com/the-last-prompt-you-need-when-building-software-with-ai), we need a post-implementation code verification phase in pi-workflow-kit. The existing `design-review` skill validates architecture *intentions* at the design-doc level, but there's no review of the *actual implemented code*. This is where the most dangerous bugs hide: signature mismatches between layers, dead code, duplicated logic, and security holes that pass tests but break in production.
+
+## Decision
+
+### Add a `verify` skill (new)
+
+A single skill triggered by `/skill:verify` that runs three sequential expert review passes over implemented code:
+
+1. **Security** 🔴 — adversarial review as if a junior wrote it and the best security expert is auditing
+2. **Optimization** 🟡 — dead code, duplication, over/under-engineering, performance
+3. **Traceability** 🔵 — end-to-end call chain verification across every layer boundary
+
+Output: structured markdown report at `docs/plans/*-verification-report.md` with findings and actionable task list.
+
+### Keep `design-review` unchanged
+
+`design-review` stays between brainstorm and plan — it validates architecture before task breakdown. Moving it would lose the cheap "catch it before you build it" value.
+
+### Update README
+
+Add `verify` to the workflow diagram, skill table, and quick start. The pipeline becomes:
+
+```
+brainstorm → design-review → plan → execute → verify → finalize
+```
+
+## Workflow Integration
+
+```
+brainstorm → design-review (optional) → plan → execute → verify → finalize
+                                                 ↑         ↑
+                                           existing         new
+```
+
+- `verify` runs after `executing-tasks` and before `finalizing`
+- It's optional — trivial changes can skip it
+- The report's remediation task list feeds directly into a follow-up `/skill:writing-plans` if fixes are needed
+- Read-only: can write to `docs/plans/` only, cannot modify source code
+
+## Files to Change
+
+1. **`skills/verify/SKILL.md`** — new skill (full content in `docs/plans/2026-06-03-verify-skill-design.md`)
+2. **`README.md`** — update workflow diagram, skill table, quick start, and project structure
+
+## Production Risks
+
+Simple change — no design review needed. We're adding a new SKILL.md and updating documentation. No code execution, no external integrations, no security surface.

package/docs/plans/completed/2026-06-03-add-verify-skill-implementation.md

@@ -0,0 +1,111 @@
+# Implementation Plan: Add Verify Skill
+
+Design: `docs/plans/2026-06-03-add-verify-skill-design.md`
+
+## Overview
+
+Add a `verify` skill to pi-workflow-kit — a post-implementation code verification phase that runs three expert review passes (security, optimization, traceability) over implemented code. Also update the README to reflect the expanded workflow pipeline.
+
+Full SKILL.md content is in `docs/plans/2026-06-03-verify-skill-design.md` (lines 7-176, inside the code fence).
+
+## Task 1: Create the verify skill
+
+<!-- tdd: trivial -->
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: No `skills/verify/` directory exists
+  - When: `skills/verify/SKILL.md` is created
+  - Then: The file contains valid YAML frontmatter with `name: verify` and a description mentioning security, optimization, and traceability. The file body contains all three review pass sections, the report format template, and the principles section.
+- **Edge Case (skill already exists)**:
+  - Given: `skills/verify/SKILL.md` already exists
+  - When: Task runs
+  - Then: The existing file is overwritten with the new content
+
+Files:
+- `skills/verify/SKILL.md`
+
+Steps:
+1. Create the directory `skills/verify/`
+2. Create `skills/verify/SKILL.md` with the full content from the design draft. The content is the markdown inside the code fence in `docs/plans/2026-06-03-verify-skill-design.md` (lines 8-176). Copy it exactly — it includes:
+   - YAML frontmatter with name and description
+   - # Verify heading and intro paragraph
+   - ## Process section (5 steps)
+   - ## Pass 1 — Security Review 🔴 (framing, what to look for, severity table)
+   - ## Pass 2 — Optimization Review 🟡 (framing, what to look for, priority table)
+   - ## Pass 3 — Traceability Review 🔵 (framing, what to look for 4 sub-items, severity table)
+   - ## Report Format section (full template with summary table, findings sections, remediation task list)
+   - ## Principles section (5 bullets)
+
+## Task 2: Update README with verify skill
+
+<!-- tdd: trivial -->
+
+Acceptance Criteria (QA Engineer Hat):
+- **Happy Path**:
+  - Given: README.md has the current workflow (brainstorm → design-review → plan → execute → finalize)
+  - When: README is updated
+  - Then: All five sections are updated — tagline, workflow diagram, skill table, phase control, quick start, and project structure — to include `verify` between execute and finalize.
+- **Edge Case (verify already in README)**:
+  - Given: README already contains verify references
+  - When: Task runs
+  - Then: No duplicate entries are introduced
+
+Files:
+- `README.md`
+
+Steps:
+
+1. Update the tagline (line 3) — change `brainstorm→plan→execute→finalize` to `brainstorm→plan→execute→verify→finalize`:
+   ```
+   > Stop AI agents from rushing to code. Enforce a structured brainstorm→plan→execute→verify→finalize workflow with TDD discipline.
+   ```
+
+2. Update the "🧠 6 Workflow Skills" heading (line 36) to "🧠 7 Workflow Skills"
+
+3. Update the workflow diagram (lines 40-44) to:
+   ```
+   brainstorm → design-review → plan → execute → verify → finalize
+                                            ↕
+                                         diagnose (anytime)
+   ```
+
+4. Add verify to the skill table (after the Execute row, before Finalize):
+   ```
+   | **Verify** | `/skill:verify` | Three expert review passes (security, optimization, traceability) on implemented code |
+   ```
+
+5. Update the phase control section (lines 61-67) to add verify:
+   ```
+   /skill:brainstorming   →  discuss and design
+   /skill:design-review   →  audit for production risks (non-trivial designs)
+   /skill:writing-plans   →  break into tasks
+   /skill:executing-tasks →  implement with TDD
+   /skill:verify          →  review code for security, optimization, and traceability issues
+   /skill:finalizing      →  ship it
+   ```
+
+6. Update the quick start section (lines 110-135) to add verify between executing-tasks and finalizing:
+   ```
+   > /skill:executing-tasks
+
+   # (agent implements with TDD, cognitive persona shifts, all tools unlocked)
+   > /skill:verify
+
+   # (agent runs security, optimization, and traceability reviews on implemented code)
+   > /skill:finalizing
+
+   # (agent archives docs, curates lessons, creates PR)
+   ```
+
+7. Update the project structure (lines 146-161) to add verify:
+   ```
+   ├── skills/
+   │   ├── brainstorming/SKILL.md
+   │   ├── design-review/SKILL.md
+   │   ├── writing-plans/SKILL.md
+   │   ├── executing-tasks/SKILL.md
+   │   ├── verify/SKILL.md
+   │   ├── finalizing/SKILL.md
+   │   └── diagnose/SKILL.md
+   ```

package/docs/plans/completed/2026-06-03-add-verify-skill-progress.md

@@ -0,0 +1,11 @@
+# Progress: Add Verify Skill
+
+Plan: docs/plans/2026-06-03-add-verify-skill-implementation.md
+Branch: add-verify-skill
+Started: 2026-06-03T13:00:00Z
+Last updated: 2026-06-03T13:00:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Create the verify skill | c48d47a |
+| 2 | ✅ done | Update README with verify skill | ea37ea8 |

package/docs/plans/completed/2026-06-03-verify-skill-design.md

@@ -0,0 +1,176 @@
+# Verify Skill — Draft SKILL.md
+
+> **Target path:** `skills/verify/SKILL.md` (to be created during executing-tasks)
+
+---
+
+```markdown
+---
+name: verify
+description: "Post-implementation code verification with three expert review passes — security, optimization, and traceability. Use after executing-tasks and before finalizing to catch issues that pass tests but break in production. Runs the 'last prompt' pattern: adversarial security review, dead code and duplication audit, and end-to-end contract verification across every layer. Use this skill whenever the user says 'verify', 'review the code', 'check for issues', 'security review', 'the last prompt', 'audit', or when code has been implemented and needs a quality gate before shipping."
+---
+
+# Verify
+
+Three expert review passes over the implemented codebase. Read-only — you **may** write the verification report to `docs/plans/`, but you **may not** modify source code.
+
+The core insight: code that passes tests is not code that's ready. Working code can have security holes, dead branches, duplicated logic, and broken contracts between layers — especially when AI generates across many files without maintaining a single mental model of the whole system. This skill catches what tests miss.
+
+## Process
+
+1. **Check what's been done** — run `git log --oneline` and `git diff --stat` to understand the scope of recent changes. If nothing has been implemented, say "No code changes found. Run `/skill:executing-tasks` first." and stop.
+
+2. **Identify the project's layers** — before reviewing, map the codebase's architecture. Look for layer boundaries: UI/handlers/routes → services/business logic → repositories/data access → database/models. Note the patterns: does the project use controllers, handlers, or routes? Services or use cases? Repositories or DAOs? This map drives the traceability pass.
+
+3. **Run three expert review passes** — each pass adopts a distinct adversarial framing. Do them sequentially. For each pass, read the relevant code deeply — don't skim. Then write findings.
+
+4. **Compile the report** — write all findings to `docs/plans/*-verification-report.md`. Present the report to the user and wait for feedback.
+
+5. **Offer to create a remediation plan** — after the report, ask: "Want me to create a fix plan from these findings? Run `/skill:writing-plans` to turn the task list into executable tasks."
+
+## Pass 1 — Security Review 🔴
+
+**Framing:** A junior developer wrote this code. Now the best security expert on the team is reviewing it — adversarial, suspicious of everything. Trust nothing.
+
+**What to look for:**
+
+- **Input validation** — every external input (HTTP params, form data, headers, query strings, environment variables) must be validated and sanitized. Unvalidated input is a critical finding.
+- **Authentication & authorization** — every endpoint that handles user data must have auth checks. Are there endpoints that skip auth? Can one user access another user's data by changing an ID?
+- **Injection** — SQL queries built by string concatenation, unsanitized shell commands, template injection, XSS in HTML output. Any raw variable interpolated into a query or command is critical.
+- **Secrets** — API keys, passwords, tokens hardcoded in source files. Check environment variable loading — are defaults set to empty or to actual secrets?
+- **Data exposure** — are sensitive fields (passwords, tokens, PII) logged, returned in API responses, or stored unencrypted?
+- **Dependency risks** — known-vulnerable packages (if `package.json`/`go.mod`/`requirements.txt` is present).
+
+**Severity classification:**
+
+| Severity | Definition |
+|----------|-----------|
+| Critical | Exploitable right now — auth bypass, injection, data leak |
+| High | Likely exploitable — missing validation on sensitive endpoint, weak auth |
+| Medium | Harder to exploit but real risk — verbose error messages leaking internals, missing rate limits |
+| Low | Best practice violations — missing CSP headers, no HSTS, long session timeouts |
+
+## Pass 2 — Optimization Review 🟡
+
+**Framing:** A code quality expert looking for waste — things that make the codebase harder to maintain, slower to run, or more confusing than necessary.
+
+**What to look for:**
+
+- **Dead code** — functions, methods, types, or exports that are never called anywhere in the codebase. Search for definitions and verify they have callers.
+- **Duplication** — the same logic implemented in slightly different ways across multiple files. AI-generated code is especially prone to this — if context was lost between sessions, the AI solved the same sub-problem differently in two places. Flag each pair with file paths and line numbers.
+- **Over-engineering** — abstractions, interfaces, or layers that add complexity without earning their keep (only one implementation, no real variation across the seam).
+- **Under-engineering** — god functions, 200-line blocks, deeply nested conditionals that should be extracted.
+- **Performance concerns** — N+1 queries, unbounded loops, unnecessary copies of large data structures, missing pagination on list endpoints.
+
+**Priority classification:**
+
+| Priority | Definition |
+|----------|-----------|
+| P0 | Dead code in a critical path or duplicated logic that will diverge |
+| P1 | Significant duplication or over-engineering that increases maintenance cost |
+| P2 | Minor cleanups — long functions, missing pagination, style inconsistencies |
+
+## Pass 3 — Traceability Review 🔵
+
+**Framing:** An integration expert tracing every user-facing action end-to-end — from UI to database and back. The AI generates code file-by-file, and the seams between files are where bugs hide.
+
+**What to look for:**
+
+1. **Map every entry point** — list all handlers, routes, controllers, or event listeners that receive external input.
+2. **Trace each call chain** — for each entry point, follow the call: handler → service → repository → database. At each boundary, verify:
+   - **Function name** — does the caller use the exact function name the callee exposes?
+   - **Argument names** — does the caller pass `userId` when the function expects `user_id`? Does `id` mean the same thing in both layers?
+   - **Argument types** — is a string passed where an integer is expected? Is an object shape different from what the next layer destructures?
+   - **Return shape** — does the caller expect fields that the callee actually returns? Are response DTOs consistent across layers?
+3. **Check error propagation** — when a database query returns no results, does the service layer handle it? Does the handler return 404 or 500? Do errors propagate cleanly or get swallowed silently?
+4. **Verify the round-trip** — if the UI calls `getUser(id)` and displays `user.name`, trace that `name` actually exists in the DB schema, gets selected by the query, mapped by the repository, passed through the service, included in the response, and rendered by the UI.
+
+**This is the pass that catches the most bugs.** AI-generated code will often have a frontend calling `getUserProfile(userId)` and a backend exposing `get_user_profile(user_id)` — both work in isolation, neither works together.
+
+**Severity classification:**
+
+| Severity | Definition |
+|----------|-----------|
+| Critical | Call chain is completely broken — function doesn't exist or signature is fundamentally wrong |
+| High | Signature mismatch — wrong arg names, wrong types, missing required fields |
+| Medium | Silent error handling — errors swallowed without logging or user feedback |
+| Low | Inconsistent naming conventions that could confuse future developers |
+
+## Report Format
+
+Write findings to `docs/plans/*-verification-report.md` using this structure:
+
+    # Verification Report: <feature/topic>
+
+    **Date:** <ISO date>
+    **Scope:** <summary of what was reviewed>
+    **Reviewer:** AI verify skill (security + optimization + traceability)
+
+    ## Summary
+
+    | Pass | Critical | High | Medium | Low |
+    |------|----------|------|--------|-----|
+    | Security | X | X | X | X |
+    | Optimization | — | X | X | X |
+    | Traceability | X | X | X | X |
+    | **Total** | **X** | **X** | **X** | **X** |
+
+    ## 🔴 Security Findings
+
+    ### [S-001] Critical — <short title>
+
+    **Location:** `path/to/file.ts:line`
+
+    **Issue:** <what's wrong and why it matters>
+
+    **Fix:** <concrete remediation step>
+
+    ### [S-002] High — <short title>
+    ...
+
+    ## 🟡 Optimization Findings
+
+    ### [O-001] P0 — <short title>
+
+    **Location:** `path/to/file.ts:line` and `path/to/other.ts:line`
+
+    **Issue:** <what's wrong>
+
+    **Fix:** <concrete remediation step>
+
+    ### [O-002] P1 — <short title>
+    ...
+
+    ## 🔵 Traceability Findings
+
+    ### [T-001] Critical — <short title>
+
+    **Entry point:** `path/to/handler.ts:line`
+    **Call chain:** handler → service → repository → DB
+    **Broken at:** <which boundary>
+    **Issue:** <what's wrong — e.g., handler passes `userId` but service expects `user_id`>
+
+    **Fix:** <concrete remediation step>
+
+    ### [T-002] High — <short title>
+    ...
+
+    ## Remediation Task List
+
+    Convert findings into actionable tasks:
+
+    | ID | Priority | Finding | Estimated Effort |
+    |----|----------|---------|-----------------|
+    | S-001 | Critical | <one-liner> | <small/medium/large> |
+    | T-001 | Critical | <one-liner> | <small/medium/large> |
+    | O-001 | P0 | <one-liner> | <small/medium/large> |
+    | ...
+
+## Principles
+
+- **Be specific** — every finding must include a file path and line reference. "There might be security issues" is useless.
+- **Be adversarial** — actively look for problems. If you don't find any, say so — but don't phone it in.
+- **Be proportional** — a small config change doesn't need the same depth as a new API endpoint. Adjust your review depth to the scope of changes.
+- **Don't fix anything** — this is read-only. Find and report. The user decides what to fix and when.
+- **Focus on seams** — the traceability pass is where the most value lives. Code within a single file is usually coherent; the bugs hide between files.
+```