@phuc1403/musketeer 0.8.0 → 0.9.0

package/template/.claude/skills/code-review/SKILL.md

@@ -1,54 +1,201 @@
----
-name: code-review
-description: "Review code quality with adversarial rigor. Supports input modes: pending changes, PR number, commit hash, codebase scan. Always-on red-team analysis finds security holes, false assumptions, and failure modes."
-argument-hint: "[#PR | COMMIT | --pending | codebase [parallel]]"
-metadata:
-  author: claudekit
-  version: "3.0.0"
----
-
-# Code Review
-
-Adversarial, evidence-based code review. Two stages: **Quality** then **Adversarial** (red-team). Be honest, brutal, concise. **YAGNI / KISS / DRY.** Verify before claiming; evidence before assertions.
-
-## 1. Resolve the input
-
-Parse arguments, first match wins, then get the diff:
-
-| Argument | Mode | Diff command |
-|----------|------|--------------|
-| `#123` / PR URL | PR | `gh pr diff <n>` (+ `gh pr view <n> --json title,body,baseRefName` for intent) |
-| `[0-9a-f]{7,40}` | Commit | `git show <sha>` |
-| `--pending` | Pending | `git diff HEAD` (staged + unstaged) — ask user for intent |
-| *(none, changes in context)* | Default | recent changes already in context |
-| `codebase` / `codebase parallel` | Codebase | full-codebase scan (see below) |
-| *(none, no context)* | Prompt | `AskUserQuestion`: pending / PR / commit / codebase |
-
-Errors: PR not found → "PR #N not found"; bad SHA → "commit not found — is it pushed?"; empty `git diff HEAD` → "no pending changes". Ambiguous PR-vs-commit → prefer PR, note the assumption.
-
-Always review **added/modified lines** (`+` in diff). Pre-existing code is out of scope unless the change makes it newly broken.
-
-## 2. Stage 1 — Quality review
-
-If the work implemented a plan/spec, first confirm compliance: list each requirement, mark PASS / MISSING / EXTRA. Missing requirements fail the review before quality matters — well-written code that doesn't match the spec is still wrong.
-
-Then review the diff for: correctness, standards, edge cases (null/empty/boundary/error paths), performance, and reuse/simplification. Dispatch a `code-reviewer` subagent for non-trivial diffs; review inline for small ones. Each finding: `file:line`, problem, fix.
-
-**Checklists (optional, for pre-landing / security audits):** detect project type — `package.json` with react/vue/next/etc → load `references/checklists/web-app.md`; `src/routes|api|controllers` → `references/checklists/api.md`; always load `references/checklists/base.md`. Run critical categories first (blocking), informational second. Honor the suppressions list at the bottom of `base.md`.
-
-## 3. Stage 2 — Adversarial review (always-on)
-
-**Skip only when ALL true:** ≤2 files changed, ≤30 lines, no security-sensitive files (auth/crypto/input-parsing/SQL/env), no new dependencies. When skipped, note `Adversarial: skipped (below threshold)`.
-
-**Never skip** when auth/middleware/security/crypto, a lockfile, env vars, DB schema, or an API route changed.
-
-Run the red-team pass per **`references/adversarial-review.md`** — spawn an adversarial `code-reviewer` whose only job is to break the code (security holes, false assumptions, failure modes, races, data corruption, supply chain, observability gaps). Then adjudicate each finding **Accept / Reject / Defer** with a reason — no silent dismissals; benefit of the doubt goes to the adversary. Critical accepted findings block merge. On re-review, pass only the fix diff.
-
-## Codebase modes
-
-- **`codebase`** — explore relevant files, dispatch parallel `code-reviewer` subagents by area, then run the always-on adversarial pass over the full scope. Report combined findings.
-- **`codebase parallel`** — first enumerate edge cases exhaustively (null, boundary, error, race, validation, security, leaks, untested paths), group into ≤6 categories, dispatch one `code-reviewer` per category to **verify** them, aggregate handled/unhandled, then run the adversarial pass.
-
-## Bottom line
-
-Resolve what you're reviewing → quality pass → adversarial pass (scope-gated) → adjudicate → fix Critical, then claim only with verification evidence.
+---
+name: code-review
+description: "Review code quality with evidence-based rigor. Supports input modes: pending changes, PR number, commit hash, and codebase scan. Focuses on bugs, regressions, maintainability, reliability, and verification gaps."
+user-invocable: true
+when_to_use: "Invoke to review diffs, PRs, commits, or full codebases."
+category: utilities
+keywords: [review, quality, verification, reliability]
+argument-hint: "[#PR | COMMIT | --pending | codebase [parallel]]"
+metadata:
+  author: claudekit
+  version: "4.0.0"
+---
+
+# Code Review
+
+Production-readiness code review with technical rigor, evidence-based claims, and verification over performative responses. Reviews focus on production risks, regression paths, and whether the implementation matches the requested change.
+
+## Input Modes
+
+Auto-detect from arguments. If ambiguous or no arguments, prompt via `AskUserQuestion`.
+
+| Input | Mode | What Gets Reviewed |
+|-------|------|--------------------|
+| `#123` or PR URL | **PR** | Full PR diff fetched via `gh pr diff` |
+| `abc1234` (7+ hex chars) | **Commit** | Single commit diff via `git show` |
+| `--pending` | **Pending** | Staged + unstaged changes via `git diff` |
+| *(no args, recent changes)* | **Default** | Recent changes in context |
+| `codebase` | **Codebase** | Full codebase scan |
+| `codebase parallel` | **Codebase+** | Parallel multi-reviewer audit |
+
+**Resolution details:** `references/input-mode-resolution.md`
+
+### No Arguments
+
+If invoked WITHOUT arguments and no recent changes in context, use `AskUserQuestion` with header "Review Target", question "What would you like to review?":
+
+| Option | Description |
+|--------|-------------|
+| Pending changes | Review staged/unstaged git diff |
+| Enter PR number | Fetch and review a specific PR |
+| Enter commit hash | Review a specific commit |
+| Full codebase scan | Deep codebase analysis |
+| Parallel codebase audit | Multi-reviewer codebase scan |
+
+## Core Principle
+
+**YAGNI**, **KISS**, **DRY** always. Technical correctness over social comfort.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+Default assumption: reviewed code may be AI-assisted. Do not trust polished shape, confident comments, or happy-path tests. Verify behavior, project-rule compliance, and scope discipline from evidence.
+
+No rubber-stamp reviews. The reviewer is not trying to please the author or preserve momentum; the reviewer enforces the rulebook and blocks defects, regressions, hidden scope drift, and AI-slop patterns.
+
+Verify before implementing. Ask before assuming. Evidence before claims.
+
+## Practices
+
+| Practice | When | Reference |
+|----------|------|-----------|
+| **Spec compliance** | After implementing from plan/spec, BEFORE quality review | `references/spec-compliance-review.md` |
+| Receiving feedback | Unclear feedback, external reviewers, needs prioritization | `references/code-review-reception.md` |
+| Requesting review | After tasks, before merge, stuck on problem | `references/requesting-code-review.md` |
+| Verification gates | Before any completion claim, commit, PR | `references/verification-before-completion.md` |
+| Edge case scouting | After implementation, before review | `references/edge-case-scouting.md` |
+| **Checklist review** | Pre-landing, pre-merge, security audit | `references/checklist-workflow.md` |
+| **Task-managed reviews** | Multi-file features (3+ files), parallel reviewers, fix cycles | `references/task-management-reviews.md` |
+
+## Quick Decision Tree
+
+```
+SITUATION?
+│
+├─ Input mode? → Resolve diff (references/input-mode-resolution.md)
+│   ├─ #PR / URL → fetch PR diff
+│   ├─ commit hash → git show
+│   ├─ --pending → git diff (staged + unstaged)
+│   ├─ codebase → full scan (references/codebase-scan-workflow.md)
+│   ├─ codebase parallel → parallel audit (references/parallel-review-workflow.md)
+│   └─ default → recent changes in context
+│
+├─ Received feedback → STOP if unclear, verify if external, implement if human partner
+├─ Completed work from plan/spec:
+│   ├─ Stage 1: Spec compliance review (references/spec-compliance-review.md)
+│   │   └─ PASS? → Stage 2 │ FAIL? → Fix → Re-review Stage 1
+│   ├─ Stage 2: Code quality review (code-reviewer subagent)
+│   │   └─ Scout edge cases → Review standards, performance
+│   └─ Verification gate → Run required tests/builds before claims
+├─ Completed work (no plan) → Scout → Code quality → Verification
+├─ Pre-landing / ship → Load checklists → Two-pass review → Verification
+├─ Multi-file feature (3+ files) → Create review pipeline tasks (scout→review→fix→verify)
+└─ About to claim status → RUN verification command FIRST
+```
+
+### Review Protocol
+
+**Stage 1 — Spec Compliance** (load `references/spec-compliance-review.md`)
+- Does code match what was requested?
+- Any missing requirements? Any unjustified extras?
+- MUST pass before Stage 2
+
+**Stage 2 — Code Quality** (code-reviewer subagent)
+- Only runs AFTER spec compliance passes
+- Standards, security, performance, edge cases
+
+**Final Verification**
+- Runs AFTER Stage 2 passes
+- Re-run the relevant tests, build, lint, or manual reproduction
+- Verify accepted findings are fixed and no new regression is introduced
+- Critical findings block merge until fixed and re-verified
+
+## Receiving Feedback
+
+**Pattern:** READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
+No performative agreement. Verify before implementing. Push back if wrong.
+
+**Full protocol:** `references/code-review-reception.md`
+
+## Requesting Review
+
+**When:** After each task, major features, before merge
+
+**Process:**
+1. **Scout edge cases first** (see below)
+2. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
+3. Dispatch code-reviewer subagent with: WHAT, PLAN, BASE_SHA, HEAD_SHA, DESCRIPTION
+4. Fix Critical immediately, Important before proceeding
+
+**Full protocol:** `references/requesting-code-review.md`
+
+## Edge Case Scouting
+
+**When:** After implementation, before requesting code-reviewer
+
+**Process:**
+1. Dispatch an `Explore` subagent with an edge-case-focused prompt
+2. It analyzes: affected files, data flows, error paths, boundary conditions
+3. Review the returned findings for potential issues
+4. Address critical gaps before code review
+
+**Full protocol:** `references/edge-case-scouting.md`
+
+## Task-Managed Review Pipeline
+
+**When:** Multi-file features (3+ changed files), parallel code-reviewer scopes, review cycles with Critical fix iterations.
+
+**Fallback:** Task tools (`TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList`) are CLI-only — unavailable in VSCode extension. If they error, use `TodoWrite` for tracking and run pipeline sequentially. Review quality is identical.
+
+**Pipeline:** scout → review → fix → verify (each a Task with dependency chain)
+
+```
+TaskCreate: "Scout edge cases"         → pending
+TaskCreate: "Review implementation"    → pending, blockedBy: [scout]
+TaskCreate: "Fix critical issues"      → pending, blockedBy: [review]
+TaskCreate: "Verify fixes pass"        → pending, blockedBy: [fix]
+```
+
+**Parallel reviews:** Spawn scoped code-reviewer subagents for independent file groups (e.g., backend + frontend). Fix task blocks on all reviewers completing.
+
+**Re-review cycles:** If fixes introduce new issues, create cycle-2 review task. Limit 3 cycles, escalate to user after.
+
+**Full protocol:** `references/task-management-reviews.md`
+
+## Verification Gates
+
+**Iron Law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+**Gate:** IDENTIFY command → RUN full → READ output → VERIFY confirms → THEN claim
+
+**Requirements:**
+- Tests pass: Output shows 0 failures
+- Build succeeds: Exit 0
+- Bug fixed: Original symptom passes
+- Requirements met: Checklist verified
+
+**Red Flags:** "should"/"probably"/"seems to", satisfaction before verification, trusting agent reports
+
+**Full protocol:** `references/verification-before-completion.md`
+
+## Integration with Workflows
+
+- **Subagent-Driven:** Scout → Review → Verify before next task
+- **Pull Requests:** Scout → Code quality → Verify → Merge
+- **Task Pipeline:** Create review tasks with dependencies → auto-unblock through chain
+- **PR Review:** `/code-review #123` → fetch diff → full review pipeline on PR changes
+- **Commit Review:** `/code-review abc1234` → review specific commit with full pipeline
+
+## Codebase Analysis Subcommands
+
+| Subcommand | Reference | Purpose |
+|------------|-----------|---------|
+| `/code-review codebase` | `references/codebase-scan-workflow.md` | Scan & analyze the codebase |
+| `/code-review codebase parallel` | `references/parallel-review-workflow.md` | Ultrathink edge cases, then parallel verify |
+
+## Bottom Line
+
+1. Resolve input mode first — know WHAT you're reviewing
+2. Technical rigor over social performance
+3. Scout edge cases before review
+4. Evidence before claims
+
+Verify. Scout. Question. Then implement. Evidence. Then claim.

package/template/.claude/skills/code-review/references/checklist-workflow.md

@@ -0,0 +1,96 @@
+# Checklist-Based Review Workflow
+
+How to apply structured review checklists during code review.
+
+## When to Use
+
+- Pre-landing review before merge
+- Explicit request for checklist review
+- Security audit before release
+- Code-reviewer agent when reviewing significant changes (10+ files or security-sensitive)
+
+## Workflow
+
+### 1. Auto-Detect Project Type
+
+```bash
+# Check for web app frameworks
+if grep -qE '"(react|vue|svelte|next|nuxt|angular)"' package.json 2>/dev/null; then
+  echo "web-app"
+# Check for API patterns
+elif ls src/routes/ src/api/ src/controllers/ app/controllers/ 2>/dev/null | head -1; then
+  echo "api"
+else
+  echo "base-only"
+fi
+```
+
+### 2. Load Checklists
+
+Always load: `checklists/base.md`
+
+Overlay based on detection:
+- `web-app` → also load `checklists/web-app.md`
+- `api` → also load `checklists/api.md`
+- Both detected → load both overlays
+
+### 3. Get the Diff
+
+```bash
+git fetch origin main --quiet
+git diff origin/main
+```
+
+**CRITICAL:** Read the FULL diff before flagging anything. Checklist suppressions require full context.
+
+### 4. Two-Pass Review
+
+**Pass 1 (CRITICAL) — Run first:**
+- Scan diff against ALL critical categories (base + overlays)
+- Each finding must include: `[file:line]`, problem, fix
+- These block `/ship` pipeline
+
+**Pass 2 (INFORMATIONAL) — Run second:**
+- Scan diff against ALL informational categories (base + overlays)
+- Same format: `[file:line]`, problem, fix
+- Included in PR body but don't block
+
+### 5. Check Suppressions
+
+Before reporting any finding, verify it's NOT in the suppressions list (bottom of `base.md`).
+
+Key suppressions:
+- Already addressed in the diff
+- Readability-aiding redundancy
+- Style/formatting issues
+- "Consider using X" when Y works fine
+
+### 6. Output
+
+```
+Pre-Landing Review: N issues (X critical, Y informational)
+
+**CRITICAL** (blocking):
+- [src/auth/login.ts:42] User input is interpolated directly into a query
+  Fix: Use the project's parameterized query helper before passing user input
+
+**Issues** (non-blocking):
+- [src/api/users.ts:88] Magic number 30 for pagination limit
+  Fix: Extract to constant `DEFAULT_PAGE_SIZE = 30`
+```
+
+### 7. Critical Issue Resolution
+
+For each critical issue, use `AskUserQuestion`:
+- Problem with `file:line`
+- Recommended fix
+- Options:
+  - A) Fix now (recommended)
+  - B) Acknowledge and proceed
+  - C) False positive — skip
+
+If user chose A (fix): apply fixes, commit, then re-run tests before continuing.
+
+## Integration with /code-review
+
+When invoked as part of standard code review, the checklist augments (not replaces) the existing scout → review → fix → verify pipeline. Checklist findings are merged with code-reviewer's own findings.

package/template/.claude/skills/code-review/references/checklists/api.md

@@ -1,52 +1,52 @@
-# API Review Checklist (Overlay)
-
-Additive to `base.md`. Apply when project exposes REST/GraphQL/gRPC APIs.
-
-## Detection
-
-Apply this overlay when any of these are true:
-- Project has route definitions (Express, FastAPI, NestJS, Django, Rails, Go chi/gin)
-- OpenAPI/Swagger spec file exists
-- `src/routes/`, `src/api/`, `src/controllers/` directories
-- GraphQL schema files in the diff
-
----
-
-## Pass 1 — CRITICAL (additions to base)
-
-### Auth & Rate Limiting
-- Public endpoints missing rate limiting (login, registration, password reset)
-- API keys or tokens exposed in URL query parameters (use headers)
-- Missing auth middleware on new routes
-- Batch/bulk endpoints without per-item authorization checks
-
-### Input Validation
-- Request body accepted without schema validation (missing Zod, Joi, Pydantic, etc.)
-- Mass assignment: entire request body spread into database model
-- File upload without size/type restrictions
-- Array inputs without length limits (DoS via large payloads)
-
-### Data Exposure
-- Sensitive fields in API responses (password hashes, internal IDs, tokens)
-- Stack traces or internal error details in production error responses
-- Verbose error messages that leak schema/implementation details
-
----
-
-## Pass 2 — INFORMATIONAL (additions to base)
-
-### API Design
-- List endpoints without pagination (LIMIT/OFFSET or cursor-based)
-- Missing consistent error response format across endpoints
-- Inconsistent naming conventions (camelCase vs snake_case in same API)
-- Missing request/response content-type headers
-
-### Observability
-- New endpoints without logging/metrics
-- Error paths that swallow exceptions silently
-- Missing correlation/request IDs for tracing
-
-### Versioning & Compatibility
-- Breaking changes to existing response shapes without version bump
-- Removed fields without deprecation notice
-- Changed field types (string → number) in existing responses
+# API Review Checklist (Overlay)
+
+Additive to `base.md`. Apply when project exposes REST/GraphQL/gRPC APIs.
+
+## Detection
+
+Apply this overlay when any of these are true:
+- Project has route definitions (Express, FastAPI, NestJS, Django, Rails, Go chi/gin)
+- OpenAPI/Swagger spec file exists
+- `src/routes/`, `src/api/`, `src/controllers/` directories
+- GraphQL schema files in the diff
+
+---
+
+## Pass 1 — CRITICAL (additions to base)
+
+### Auth & Rate Limiting
+- Public endpoints missing rate limiting (login, registration, password reset)
+- API keys or tokens exposed in URL query parameters (use headers)
+- Missing auth middleware on new routes
+- Batch/bulk endpoints without per-item authorization checks
+
+### Input Validation
+- Request body accepted without schema validation (missing Zod, Joi, Pydantic, etc.)
+- Mass assignment: entire request body spread into database model
+- File upload without size/type restrictions
+- Array inputs without length limits (resource exhaustion via oversized requests)
+
+### Data Exposure
+- Sensitive fields in API responses (password hashes, internal IDs, tokens)
+- Stack traces or internal error details in production error responses
+- Verbose error messages that leak schema/implementation details
+
+---
+
+## Pass 2 — INFORMATIONAL (additions to base)
+
+### API Design
+- List endpoints without pagination (LIMIT/OFFSET or cursor-based)
+- Missing consistent error response format across endpoints
+- Inconsistent naming conventions (camelCase vs snake_case in same API)
+- Missing request/response content-type headers
+
+### Observability
+- New endpoints without logging/metrics
+- Error paths that swallow exceptions silently
+- Missing correlation/request IDs for tracing
+
+### Versioning & Compatibility
+- Breaking changes to existing response shapes without version bump
+- Removed fields without deprecation notice
+- Changed field types (string → number) in existing responses

package/template/.claude/skills/code-review/references/checklists/base.md

@@ -1,100 +1,100 @@
-# Base Review Checklist
-
-Universal checklist for all project types. Two-pass model: critical (blocking) + informational (non-blocking).
-
-## Instructions
-
-Review `git diff origin/main` for the issues below. Be specific — cite `file:line` and suggest fixes. Skip anything that's fine. Only flag real problems.
-
-**Output format:**
-
-```
-Pre-Landing Review: N issues (X critical, Y informational)
-
-**CRITICAL** (blocking):
-- [file:line] Problem description
-  Fix: suggested fix
-
-**Issues** (non-blocking):
-- [file:line] Problem description
-  Fix: suggested fix
-```
-
-If no issues: `Pre-Landing Review: No issues found.`
-
-Be terse. One line problem, one line fix. No preamble.
-
----
-
-## Pass 1 — CRITICAL (blocking)
-
-### Injection & Data Safety
-- String interpolation in SQL/database queries (even with type casting — use parameterized queries)
-- Unsanitized user input written to database or rendered in HTML
-- Raw HTML output from user-controlled data (`innerHTML`, `dangerouslySetInnerHTML`, `html_safe`, `raw()`, `| safe`)
-- Command injection via string concatenation in shell commands (use argument arrays)
-- Path traversal via user input in file operations
-
-### Race Conditions & Concurrency
-- Read-check-write without atomic operations (check-then-set should be atomic WHERE + UPDATE)
-- Find-or-create without unique database constraint (concurrent calls create duplicates)
-- Status transitions without atomic WHERE old_status + UPDATE new_status
-- Shared mutable state accessed without synchronization
-
-### Security Boundaries
-- Missing authentication checks on new endpoints/routes
-- Privilege escalation paths (user can access/modify another user's data — IDOR)
-- Secrets in logs, error responses, or client-side code
-- LLM/AI output written to database or used in queries without validation
-- JWT/token comparison using `==` instead of constant-time comparison
-
-### Auth & Access Control
-- New API endpoints without auth middleware
-- Missing authorization check (authenticated but not authorized)
-- Admin-only operations accessible to regular users
-- Session fixation or token reuse vulnerabilities
-
----
-
-## Pass 2 — INFORMATIONAL (non-blocking)
-
-### Conditional Side Effects
-- Code branches on condition but forgets side effect on one branch (e.g., sets status but not associated data)
-- Log messages claiming action happened but action was conditionally skipped
-
-### Magic Numbers & String Coupling
-- Bare numeric literals used in multiple files — should be named constants
-- Error message strings used as query filters elsewhere (grep for the string)
-
-### Dead Code & Consistency
-- Variables assigned but never read
-- Stale comments describing old behavior after code changed
-- Import/require statements for unused modules
-
-### Test Gaps
-- Missing negative-path tests (error cases, validation failures)
-- Assertions on type/status but not side effects (e.g., checks status but not that email was sent)
-- Missing integration tests for security enforcement (auth, rate limiting, access control)
-
-### Type Coercion at Boundaries
-- Values crossing language/system boundaries where type could change (string vs number)
-- Hash/digest inputs that don't normalize types before serialization
-
-### Performance
-- O(n*m) lookups in views/templates (array search inside loops — use hash/map lookup)
-- Missing pagination on list endpoints returning unbounded results
-- N+1 queries: loading associations inside loops without eager loading
-- Unbounded queries without LIMIT
-
----
-
-## Suppressions — DO NOT flag these
-
-- Redundancy that aids readability (e.g., `present?` redundant with length check)
-- "Add comment explaining why this threshold was chosen" — thresholds change, comments rot
-- "This assertion could be tighter" when assertion already covers the behavior
-- Consistency-only changes (wrapping a value to match how another constant is guarded)
-- Harmless no-ops (e.g., `.filter()` on array that never contains the filtered value)
-- ANYTHING already addressed in the diff being reviewed — read the FULL diff before commenting
-- Style/formatting issues (use a linter for that)
-- "Consider using X instead of Y" when Y works fine
+# Base Review Checklist
+
+Universal checklist for all project types. Two-pass model: critical (blocking) + informational (non-blocking).
+
+## Instructions
+
+Review `git diff origin/main` for the issues below. Be specific — cite `file:line` and suggest fixes. Skip anything that's fine. Only flag real problems.
+
+**Output format:**
+
+```
+Pre-Landing Review: N issues (X critical, Y informational)
+
+**CRITICAL** (blocking):
+- [file:line] Problem description
+  Fix: suggested fix
+
+**Issues** (non-blocking):
+- [file:line] Problem description
+  Fix: suggested fix
+```
+
+If no issues: `Pre-Landing Review: No issues found.`
+
+Be terse. One line problem, one line fix. No preamble.
+
+---
+
+## Pass 1 — CRITICAL (blocking)
+
+### Injection & Data Safety
+- String interpolation in SQL/database queries (even with type casting — use parameterized queries)
+- Unsanitized user input written to database or rendered in HTML
+- Raw HTML output from user-controlled data (`innerHTML`, `dangerouslySetInnerHTML`, `html_safe`, `raw()`, `| safe`)
+- Command injection via string concatenation in shell commands (use argument arrays)
+- Path traversal via user input in file operations
+
+### Race Conditions & Concurrency
+- Read-check-write without atomic operations (check-then-set should be atomic WHERE + UPDATE)
+- Find-or-create without unique database constraint (concurrent calls create duplicates)
+- Status transitions without atomic WHERE old_status + UPDATE new_status
+- Shared mutable state accessed without synchronization
+
+### Security Boundaries
+- Missing authentication checks on new endpoints/routes
+- Privilege escalation paths (user can access/modify another user's data — IDOR)
+- Secrets in logs, error responses, or client-side code
+- LLM/AI output written to database or used in queries without validation
+- JWT/token comparison using `==` instead of constant-time comparison
+
+### Auth & Access Control
+- New API endpoints without auth middleware
+- Missing authorization check (authenticated but not authorized)
+- Admin-only operations accessible to regular users
+- Session fixation or token reuse defects
+
+---
+
+## Pass 2 — INFORMATIONAL (non-blocking)
+
+### Conditional Side Effects
+- Code branches on condition but forgets side effect on one branch (e.g., sets status but not associated data)
+- Log messages claiming action happened but action was conditionally skipped
+
+### Magic Numbers & String Coupling
+- Bare numeric literals used in multiple files — should be named constants
+- Error message strings used as query filters elsewhere (grep for the string)
+
+### Dead Code & Consistency
+- Variables assigned but never read
+- Stale comments describing old behavior after code changed
+- Import/require statements for unused modules
+
+### Test Gaps
+- Missing negative-path tests (error cases, validation failures)
+- Assertions on type/status but not side effects (e.g., checks status but not that email was sent)
+- Missing integration tests for security enforcement (auth, rate limiting, access control)
+
+### Type Coercion at Boundaries
+- Values crossing language/system boundaries where type could change (string vs number)
+- Hash/digest inputs that don't normalize types before serialization
+
+### Performance
+- O(n*m) lookups in views/templates (array search inside loops — use hash/map lookup)
+- Missing pagination on list endpoints returning unbounded results
+- N+1 queries: loading associations inside loops without eager loading
+- Unbounded queries without LIMIT
+
+---
+
+## Suppressions — DO NOT flag these
+
+- Redundancy that aids readability (e.g., `present?` redundant with length check)
+- "Add comment explaining why this threshold was chosen" — thresholds change, comments rot
+- "This assertion could be tighter" when assertion already covers the behavior
+- Consistency-only changes (wrapping a value to match how another constant is guarded)
+- Harmless no-ops (e.g., `.filter()` on array that never contains the filtered value)
+- ANYTHING already addressed in the diff being reviewed — read the FULL diff before commenting
+- Style/formatting issues (use a linter for that)
+- "Consider using X instead of Y" when Y works fine