supipowers 1.2.6 → 1.5.0

package/README.md

@@ -30,73 +30,104 @@ The installer detects your agent, registers the extension, and optionally sets u
 
 ### Requirements
 
-| Dependency | What it's for |
-| --- | --- |
-| [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) | The coding agent that supipowers extends |
-| [Bun](https://bun.sh) | Runtime — required for installation and the built-in SQLite FTS index |
-| [Git](https://git-scm.com) | Used by the installer and context-mode setup |
+| Dependency                                            | What it's for                                                         |
+| ----------------------------------------------------- | --------------------------------------------------------------------- |
+| [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) | The coding agent that supipowers extends                              |
+| [Bun](https://bun.sh)                                 | Runtime — required for installation and the built-in SQLite FTS index |
+| [Git](https://git-scm.com)                            | Used by the installer and context-mode setup                          |
 
 ### Optional dependencies
 
 The installer scans for these and offers to install any that are missing. Everything works without them, but each one unlocks additional capabilities.
 
-| Dependency | What it enables |
-| --- | --- |
-| [mcpc](https://github.com/apify/mcpc) | MCP server management via `/supi:mcp` |
-| [context-mode](https://github.com/ogrodev/context-mode) | Context window protection — large outputs are sandboxed automatically |
-| `typescript-language-server` | TypeScript/JS diagnostics and references in review gates |
-| `pyright` | Python type checking |
-| `rust-analyzer` | Rust language server |
-| `gopls` | Go language server |
-| `@playwright/cli` | Browser exploration and E2E test execution via `/supi:qa` |
+| Dependency                            | What it enables                                                       |
+| ------------------------------------- | --------------------------------------------------------------------- |
+| [mcpc](https://github.com/apify/mcpc) | MCP server management via `/supi:mcp`                                 |
+| supi-context-mode                     | Context window protection — large outputs are sandboxed automatically |
+| `typescript-language-server`          | TypeScript/JS diagnostics and references in review gates              |
+| `pyright`                             | Python type checking                                                  |
+| `rust-analyzer`                       | Rust language server                                                  |
+| `gopls`                               | Go language server                                                    |
+| `@playwright/cli`                     | Browser exploration and E2E test execution via `/supi:qa`             |
 
 > [!NOTE]
 > LSP servers are language-specific — install only the ones that match your project's stack.
+> supi-context-mode is heavily inspired at [context-mode](https://github.com/mksglu/context-mode)
 
 ## Commands
 
-| Command | What it does |
-| --- | --- |
-| `/supi` | Interactive menu with commands and project status |
-| `/supi:plan` | Collaborative planning with structured task breakdown |
-| `/supi:review` | Run quality gates at chosen depth |
-| `/supi:qa` | E2E testing pipeline with Playwright |
-| `/supi:fix-pr` | Assess and fix PR review comments |
-| `/supi:release` | Version bump, release notes, publish |
-| `/supi:commit` | AI-powered commit with conventional message generation |
-| `/supi:model` | Configure model assignments per action (plan, review, qa…) |
-| `/supi:context` | Show current context window usage and system prompt breakdown |
-| `/supi:mcp` | Manage MCP servers (connect, disconnect, migrate) |
-| `/supi:config` | Interactive settings TUI |
-| `/supi:status` | Check running sub-agents and progress |
-| `/supi:doctor` | Diagnose extension health and missing dependencies |
-| `/supi:update` | Update supipowers to the latest version |
-
-Commands like `/supi`, `/supi:config`, `/supi:commit`, and `/supi:status` are TUI-only — they open native dialogs without triggering the AI session.
+| Command                  | What it does                                                  |
+| ------------------------ | ------------------------------------------------------------- |
+| `/supi`                  | Interactive menu with commands and project status             |
+| `/supi:plan`             | Collaborative planning with structured task breakdown         |
+| `/supi:review`           | AI code review with validated findings docs and fix/document/discuss actions |
+| `/supi:checks`           | Run deterministic quality gates                               |
+| `/supi:qa`               | E2E testing pipeline with Playwright                          |
+| `/supi:fix-pr`           | Assess and fix PR review comments                             |
+| `/supi:release`          | Version bump, release notes, publish                          |
+| `/supi:commit`           | AI-powered commit with conventional message generation        |
+| `/supi:model`            | Configure model assignments per action (plan, review, qa…)    |
+| `/supi:context`          | Show current context window usage and system prompt breakdown |
+| `/supi:optimize-context` | Analyze loaded prompt/context usage and suggest reductions    |
+| `/supi:mcp`              | Manage MCP servers (connect, disconnect, migrate)             |
+| `/supi:config`           | Interactive settings TUI                                      |
+| `/supi:status`           | Check running sub-agents and progress                         |
+| `/supi:doctor`           | Diagnose extension health and missing dependencies            |
+| `/supi:generate`        | Documentation drift detection                                |
+| `/supi:update`           | Update supipowers to the latest version                       |
+| `/supi:agents`           | Manage review agents                                          |
+
+Most commands steer the AI session. These are TUI-only — they open native dialogs without triggering the AI: `/supi`, `/supi:config`, `/supi:status`, `/supi:review`, `/supi:update`, `/supi:doctor`, `/supi:mcp`, `/supi:model`, `/supi:context`, `/supi:optimize-context`, `/supi:commit`, `/supi:release`, `/supi:checks`, `/supi:agents`.
 
 ## How it works
 
 **Planning.** `/supi:plan` steers the AI through planning phases (scope → decompose → estimate → verify), saves the result to `.omp/supipowers/plans/`, and presents an approval UI. On approval, tasks execute in the same session.
 
-**Quality gates.** `/supi:review` runs composable checks selected by profile. LSP diagnostics surface real type errors. AI review catches logic issues. Test gates run your actual test suite. Each gate reports issues with severity levels.
+**Quality gates.** `/supi:checks` runs deterministic quality gates. Six gates are available: `lsp-diagnostics`, `lint`, `typecheck`, `format`, `test-suite`, and `build`. Each gate can be enabled independently via `/supi:config` or `.omp/supipowers/config.json`. Gates report issues with severity levels.
 
-**PR fixing.** `/supi:fix-pr` fetches PR review comments, critically assesses each one, checks for ripple effects, then fixes or rejects with evidence. Bot reviewers are auto-detected and filtered out.
-
-**Context protection.** When [context-mode](https://github.com/ogrodev/context-mode) is detected, supipowers injects routing hooks that protect the agent's context window. Large outputs, file reads, and HTTP calls are automatically routed through sandboxed execution so only summaries enter the conversation.
+**AI code review.** `/supi:review` runs a programmatic AI review pipeline with configurable depth (quick, deep, or multi-agent). It uses headless agent sessions with structured JSON validation, always validates findings before user action, writes the current validated findings to a session `findings.md` document, and then presents three next-step choices: `Fix now`, `Document only`, or `Discuss before fixing`.
 
-**Model assignment.** Each action (planning, review, QA) can be assigned a different model and thinking level. `/supi:model` opens a TUI picker backed by OMP's model registry.
+**PR fixing.** `/supi:fix-pr` fetches PR review comments, critically assesses each one, checks for ripple effects, then fixes or rejects with evidence. Bot reviewers are auto-detected and filtered out.
 
-## Quality profiles
+**Context protection.** When [context-mode](https://github.com/mksglu/context-mode) is detected, supipowers injects routing hooks that protect the agent's context window. Large outputs, file reads, and HTTP calls are automatically routed through sandboxed execution so only summaries enter the conversation.
 
-Three built-in profiles control how much `/supi:review` checks:
+**Model assignment.** Each action can be assigned a different model and thinking level. `/supi:model` opens a TUI picker backed by OMP's model registry.
 
-| Profile | LSP | AI Review | Code Quality | Tests | E2E |
-| --- | --- | --- | --- | --- | --- |
-| `quick` | ✓ | quick scan | — | — | — |
-| `thorough` _(default)_ | ✓ | deep | ✓ | — | — |
-| `full-regression` | ✓ | deep | ✓ | ✓ | ✓ |
+## Feature comparison with `obra/superpowers`
 
-Create custom profiles in `.omp/supipowers/profiles/`.
+> [!NOTE]
+> Based on the current `supipowers` repo and the documented features in [`obra/superpowers`](https://github.com/obra/superpowers). ✅ = part of the current documented product surface. ❌ = not part of the current documented product surface.
+
+| What is being compared                | supipowers | obra/superpowers |
+| ------------------------------------- | ---------- | ---------------- |
+| OMP-native slash commands             | ✅         | ❌               |
+| Automatic skill activation            | ❌         | ✅               |
+| Plan approval UI                      | ✅         | ❌               |
+| Parallel agent execution workflow     | ✅         | ✅               |
+| Code review workflow                  | ✅         | ✅               |
+| TDD / debugging / verification skills | ✅         | ✅               |
+| Browser QA / Playwright workflow      | ✅         | ❌               |
+| PR review comment fixing workflow     | ✅         | ❌               |
+| Release automation                    | ✅         | ❌               |
+| Commit workflow                       | ✅         | ❌               |
+| Context-window optimizations          | ✅         | ❌               |
+| MCP server management through mcpc    | ✅         | ❌               |
+| Git worktree workflow                 | ❌         | ✅               |
+
+## Quality gates
+
+`/supi:checks` runs deterministic quality gates. Each gate is independently configurable in `quality.gates` via `/supi:config` or the config JSON files:
+
+| Gate               | What it checks                  | Config type       |
+| ------------------ | ------------------------------- | ----------------- |
+| `lsp-diagnostics`  | Language server diagnostics     | enabled           |
+| `lint`             | Linter (e.g. `eslint`, `biome`) | enabled + command |
+| `typecheck`        | Type checker (e.g. `tsc`)       | enabled + command |
+| `format`           | Formatter check                 | enabled + command |
+| `test-suite`       | Test runner                     | enabled + command |
+| `build`            | Build verification              | enabled + command |
+
+Gates default to disabled. Enable them per-project in `.omp/supipowers/config.json` or globally in `~/.omp/supipowers/config.json`.
 
 ## Configuration
 
@@ -112,21 +143,50 @@ Configuration is a three-layer deep-merge (lowest to highest priority):
 2. `~/.omp/supipowers/config.json` — global overrides
 3. `.omp/supipowers/config.json` — per-project overrides
 
+
+## Release channels
+
+Three built-in channels are available: `github` (GitHub Release via `gh` CLI), `gitlab` (GitLab Release via `glab` CLI), and `gitea` (Gitea Release via `tea` CLI). Channels are selected per-project in `release.channels`.
+
+Custom channels can be defined in `release.customChannels`:
+
+```json
+{
+  "release": {
+    "customChannels": {
+      "my-channel": {
+        "label": "My Channel",
+        "publishCommand": "./scripts/publish.sh $tag",
+        "detectCommand": "which my-tool"
+      }
+    }
+  }
+}
+```
+
+| Field            | Required | Description                                                    |
+| ---------------- | -------- | -------------------------------------------------------------- |
+| `label`          | yes      | Display name shown in the release picker                       |
+| `publishCommand` | yes      | Shell command run to publish; `$tag`, `$version`, `$changelog` are passed as environment variables |
+| `detectCommand`  | no       | Shell command to detect availability; exit 0 = available. If omitted, the channel is assumed available |
+
 ## Skills
 
 Supipowers ships runtime-loaded prompt skills that are also available to the agent during regular sessions:
 
-| Skill | Used by |
-| --- | --- |
-| `planning` | `/supi:plan` |
-| `code-review` | `/supi:review` |
-| `qa-strategy` | `/supi:qa` |
-| `fix-pr` | `/supi:fix-pr` |
-| `debugging` | Agent sessions |
-| `tdd` | Agent sessions |
-| `verification` | Agent sessions |
-| `receiving-code-review` | Agent sessions |
-| `context-mode` | Context window guidance |
+| Skill                   | Used by                 |
+| ----------------------- | ----------------------- |
+| `planning`              | `/supi:plan`            |
+| `code-review`           | `/supi:review`          |
+| `qa-strategy`           | `/supi:qa`              |
+| `fix-pr`                | `/supi:fix-pr`          |
+| `debugging`             | Agent sessions          |
+| `tdd`                   | Agent sessions          |
+| `verification`          | Agent sessions          |
+| `receiving-code-review` | Agent sessions          |
+| `release`               | `/supi:release`         |
+| `context-mode`          | Context window guidance |
+| `creating-supi-agents`  | Agent creation guidance  |
 
 ## Development
 
@@ -138,3 +198,5 @@ bun run build        # emit to dist/
 ```
 
 Tests live in `tests/`, mirroring `src/` one-to-one. The test runner is Bun's built-in `bun:test`.
+
+Peer dependencies (`@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-ai`, `@oh-my-pi/pi-tui`, `@sinclair/typebox`) are provided by the OMP host; they are devDependencies only for type-checking during development.

package/bin/install.ts

@@ -315,139 +315,52 @@ function installToPlatform(platformDir: string, packageRoot: string): string {
 }
 
 /**
- * Install context-mode as a platform extension and register MCP server.
- *
- * Per upstream docs (Pi Coding Agent):
- *   1. git clone → ~/<platformDir>/extensions/context-mode
- *   2. npm install && npm run build
- *   3. Register MCP in ~/<platformDir>/settings/mcp.json
- *
- * Build requires Node.js 18+ (tsc, esbuild, node -e in build script).
- * Runtime uses bun to leverage bun:sqlite — context-mode auto-detects
- * Bun and skips better-sqlite3 entirely.
+ * Remove supi-context-mode / context-mode entries from the current agent/mcp.json
+ * and from the legacy settings/mcp.json location.
  */
-async function installContextMode(platformDir: string): Promise<void> {
-  const extDir = join(homedir(), platformDir, "extensions", "context-mode");
-  const startMjs = join(extDir, "start.mjs");
-
-  // Check if already installed and built
-  if (existsSync(startMjs)) {
-    // Already installed — just ensure MCP registration is up to date
-    registerContextModeMcp(platformDir, startMjs);
-    return;
-  }
-
-  const shouldInstall = await confirm({
-    message: `Install context-mode extension for context window protection? (${platformDir})`,
-  });
-  if (isCancel(shouldInstall) || !shouldInstall) {
-    note(
-      `Skipped. You can install later:\n` +
-        `  git clone https://github.com/mksglu/context-mode.git ~/${platformDir}/extensions/context-mode\n` +
-        `  cd ~/${platformDir}/extensions/context-mode && npm install && npm run build`,
-      `context-mode (${platformDir})`,
-    );
-    return;
-  }
-
-  // Check Node.js 18+ (required for build: tsc, esbuild, node -e in build script)
-  const nodeCheck = run("node", ["--version"]);
-  if (nodeCheck.error || nodeCheck.status !== 0) {
-    note(
-      "Node.js 18+ is required to build context-mode.\n" +
-        "Install from https://nodejs.org then re-run the installer.",
-      "context-mode requires Node.js",
-    );
-    return;
-  }
-  const nodeVersion = parseInt((nodeCheck.stdout ?? "").replace(/^v/, ""), 10);
-  if (nodeVersion < 18) {
-    note(
-      `Found Node.js v${nodeCheck.stdout?.trim()} but context-mode requires v18+.\n` +
-        "Update Node.js from https://nodejs.org then re-run the installer.",
-      "context-mode requires Node.js 18+",
-    );
-    return;
-  }
-
-  const s = spinner();
-  s.start(`Cloning context-mode to ~/${platformDir}/extensions/context-mode...`);
-
-  // Clone
-  const cloneResult = run("git", [
-    "clone",
-    "https://github.com/mksglu/context-mode.git",
-    extDir,
-  ]);
-  if (cloneResult.status !== 0) {
-    s.stop(`Failed to clone context-mode`);
-    note(
-      cloneResult.stderr?.trim() || "Unknown git clone error",
-      "context-mode install failed",
-    );
-    return;
-  }
-
-  // npm install (builds better-sqlite3 native bindings for Node.js fallback;
-  // at runtime under Bun, bun:sqlite is used instead via auto-detection)
-  s.message("Installing context-mode dependencies...");
-  const npmInstall = run("npm", ["install"], { cwd: extDir });
-  if (npmInstall.status !== 0) {
-    s.stop(`Failed to install context-mode dependencies`);
-    note(
-      npmInstall.stderr?.trim() || "Unknown npm install error",
-      "context-mode install failed",
-    );
-    return;
-  }
-
-  // npm run build (requires tsc + esbuild from devDeps, runs under Node.js)
-  s.message("Building context-mode...");
-  const npmBuild = run("npm", ["run", "build"], { cwd: extDir });
-  if (npmBuild.status !== 0) {
-    s.stop(`Failed to build context-mode`);
-    note(
-      npmBuild.stderr?.trim() || "Unknown build error",
-      "context-mode install failed",
-    );
-    return;
-  }
-
-  s.stop(`context-mode installed to ~/${platformDir}/extensions/context-mode`);
-
-  // Register MCP server
-  registerContextModeMcp(platformDir, startMjs);
-}
-
-/**
- * Register context-mode MCP entry in the platform's settings/mcp.json.
- *
- * Uses "bun" as the command so context-mode auto-detects Bun runtime
- * and uses bun:sqlite — no better-sqlite3 native bindings needed at runtime.
- */
-function registerContextModeMcp(platformDir: string, startMjs: string): void {
-  const mcpConfigPath = join(homedir(), platformDir, "settings", "mcp.json");
-  let mcpConfig: { mcpServers: Record<string, unknown> } = { mcpServers: {} };
-  if (existsSync(mcpConfigPath)) {
+function cleanupContextModeMcp(platformDir: string): void {
+  // Clean supi-context-mode from the current agent/mcp.json
+  const agentMcpPath = join(homedir(), platformDir, "agent", "mcp.json");
+  if (existsSync(agentMcpPath)) {
     try {
-      mcpConfig = JSON.parse(readFileSync(mcpConfigPath, "utf8"));
-      if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+      const agentConfig = JSON.parse(readFileSync(agentMcpPath, "utf8"));
+      let changed = false;
+      if (agentConfig.mcpServers?.["context-mode"]) {
+        delete agentConfig.mcpServers["context-mode"];
+        changed = true;
+      }
+      if (agentConfig.mcpServers?.["supi-context-mode"]) {
+        delete agentConfig.mcpServers["supi-context-mode"];
+        changed = true;
+      }
+      if (changed) {
+        writeFileSync(agentMcpPath, JSON.stringify(agentConfig, null, 2));
+      }
     } catch {
-      mcpConfig = { mcpServers: {} };
+      // Best effort — do not fail install on corrupt mcp.json
     }
   }
+}
 
-  mcpConfig.mcpServers["context-mode"] = {
-    command: "bun",
-    args: [startMjs],
-  };
+function cleanupLegacyMcp(platformDir: string): void {
+  const oldMcpPath = join(homedir(), platformDir, "settings", "mcp.json");
+  if (!existsSync(oldMcpPath)) return;
 
-  mkdirSync(dirname(mcpConfigPath), { recursive: true });
-  writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
-  note(
-    `Registered in ~/${platformDir}/settings/mcp.json`,
-    `context-mode (${platformDir})`,
-  );
+  try {
+    const config = JSON.parse(readFileSync(oldMcpPath, "utf8"));
+    delete config.mcpServers?.["context-mode"];
+    delete config.mcpServers?.["supi-context-mode"];
+
+    if (!config.mcpServers || Object.keys(config.mcpServers).length === 0) {
+      rmSync(oldMcpPath);
+    } else {
+      // Other servers exist — keep the file, just remove our entries
+      writeFileSync(oldMcpPath, JSON.stringify(config, null, 2));
+    }
+  } catch {
+    // Corrupted — remove it
+    try { rmSync(oldMcpPath); } catch { /* best effort */ }
+  }
 }
 
 // ── Main ─────────────────────────────────────────────────────
@@ -544,10 +457,17 @@ async function main(): Promise<void> {
   for (const target of targets) {
     installToPlatform(target.dir, packageRoot);
 
-    // ── Step 3b: Install context-mode extension + register MCP ──
-    await installContextMode(target.dir);
+    // ── Step 3b: Clean up legacy context-mode MCP registrations ──
+    cleanupContextModeMcp(target.dir);
+    cleanupLegacyMcp(target.dir);
   }
 
+  note(
+    "Context-mode tools are now built into supipowers (no external MCP server needed).\n" +
+    "You can manually remove any legacy installation at ~/<platformDir>/extensions/context-mode/",
+    "Context Mode",
+  );
+
   if (DEBUG) {
     note(`Debug log written to:\n${LOG_FILE}`, "Debug");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supipowers",
-  "version": "1.2.6",
+  "version": "1.5.0",
   "description": "Workflow extension for OMP coding agents.",
   "type": "module",
   "scripts": {
@@ -16,17 +16,24 @@
     "agent",
     "supipowers"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ogrodev/supipowers.git"
+  },
   "license": "MIT",
   "bin": {
     "supipowers": "bin/install.mjs"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "files": [
     "src",
     "skills",
     "bin/install.mjs",
     "bin/install.ts",
     "bin/local-install.sh",
-    "bin/ctx-mode-wrapper.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -39,7 +46,8 @@
     ]
   },
   "dependencies": {
-    "@clack/prompts": "^0.10.0"
+    "@clack/prompts": "^0.10.0",
+    "handlebars": "^4.7.8"
   },
   "peerDependencies": {
     "@oh-my-pi/pi-coding-agent": "*",

package/skills/code-review/SKILL.md

@@ -3,43 +3,140 @@ name: code-review
 description: Deep code review methodology for thorough quality assessment
 ---
 
-# Code Review Skill
-
-Systematic approach to reviewing code changes.
-
-## Review Checklist
-
-### Correctness
-- Does the code do what it claims?
-- Are edge cases handled?
-- Are error conditions handled?
-
-### Security
-- Input validation at system boundaries?
-- SQL injection, XSS, command injection risks?
-- Secrets in code or logs?
-- Authentication/authorization checks?
-
-### Performance
-- Unnecessary loops or allocations?
-- N+1 query patterns?
-- Missing indexes for frequent queries?
-- Large payloads or unbounded lists?
-
-### Maintainability
-- Clear naming (functions, variables, files)?
-- Single responsibility per unit?
-- Unnecessary abstractions or premature optimization?
-- Comments where logic isn't self-evident?
-
-### Testing
-- Tests cover the happy path?
-- Tests cover error/edge cases?
-- Tests are deterministic (no flaky tests)?
-- Test names describe the behavior?
-
-## Severity Levels
-
-- **error**: Must fix before merge. Bugs, security issues, data loss risks.
-- **warning**: Should fix. Code quality, maintainability, minor issues.
-- **info**: Nice to have. Style, naming suggestions, minor improvements.
+# Code Review
+
+Identify defects, security risks, and maintainability problems in code changes before they merge.
+
+## Quick Reference
+
+| Aspect | Detail |
+|---|---|
+| **Input** | PR diff, file contents, PR title/description |
+| **Output** | Structured findings (see Finding Format below) |
+| **Scope** | Changed lines + immediate context; follow references 1 level deep when a change touches a public API |
+| **Skip** | Formatting, import order, whitespace — defer to linters |
+| **Depth** | Read every changed line; skim unchanged context for broken assumptions |
+
+## Finding Format
+
+Each finding MUST follow this structure:
+
+```
+**[severity]** `file:line` — Description of the issue.
+Suggestion: concrete fix or direction.
+```
+
+**Severity levels:**
+
+| Level | Meaning | Gate |
+|---|---|---|
+| `error` | Bugs, security holes, data loss, crashes | MUST fix before merge |
+| `warning` | Wrong abstraction, missing validation, performance trap | SHOULD fix |
+| `info` | Naming, style, minor simplification | Nice to have |
+
+## Review Procedure
+
+Execute these phases in order. Each phase produces findings or nothing.
+
+### Phase 1 — Understand Intent
+Read the PR title, description, and linked issues. Determine what the change is supposed to do. If intent is unclear, report as `warning` before proceeding.
+
+### Phase 2 — Correctness
+For each changed function/block:
+- Trace inputs through the logic. Identify domain boundaries (null, empty, zero, negative, max-length).
+- For each boundary, verify the code handles or explicitly rejects it. Unhandled → `error`.
+- Check return values: can a caller confuse a failure return with a success? Silent failures → `error`.
+
+### Phase 3 — Security
+At every system boundary (user input, HTTP params, DB queries, shell commands, file paths):
+- Verify input is validated or sanitized before use. Missing → `error`.
+- Check for secrets in code, logs, or error messages. Present → `error`.
+- Verify auth checks exist for protected operations. Missing → `error`.
+
+### Phase 4 — Performance
+- Identify loops over collections: is work inside the loop that could be batched or hoisted? Report as `warning`.
+- Look for N+1 patterns: a query inside a loop that iterates query results. Report as `warning`.
+- Flag unbounded lists or payloads with no pagination/limit. Report as `warning`.
+
+### Phase 5 — Maintainability
+- Flag functions doing more than one job (needs "and" to describe) → `warning`.
+- Flag duplicated logic across the diff (same pattern 2+ times) → `info`.
+- Flag misleading names (function name promises X, body does Y) → `warning`.
+
+### Phase 6 — Tests
+- If the change adds behavior, verify a test covers the happy path. Missing → `warning`.
+- If the change fixes a bug, verify a regression test exists. Missing → `warning`.
+- Flag non-deterministic tests (time-dependent, random, order-dependent) → `warning`.
+
+## Examples
+
+### Bug: unhandled null at domain boundary
+
+```ts
+// PR diff
+function getUser(id: string) {
+  const row = db.query("SELECT * FROM users WHERE id = ?", [id]);
+  return { name: row.name, email: row.email };
+}
+```
+
+**Finding:**
+```
+**[error]** `src/users.ts:3` — `db.query` returns `null` when no row matches,
+but the next line unconditionally accesses `.name` on the result.
+Suggestion: Guard with `if (!row) return null` or throw a NotFoundError.
+```
+
+### Security: unsanitized input in shell command
+
+```python
+# PR diff
+def export_report(filename):
+    os.system(f"tar czf /tmp/{filename}.tar.gz /data/reports")
+```
+
+**Finding:**
+```
+**[error]** `reports/export.py:3` — `filename` is interpolated into a shell
+command without sanitization. An attacker passing `; rm -rf /` exploits this.
+Suggestion: Use `subprocess.run(["tar", "czf", ...])` with a list to avoid shell injection,
+and validate `filename` against an allowlist pattern.
+```
+
+### N+1 query in loop
+
+```ts
+// PR diff
+const orders = await db.orders.findMany({ where: { status: "open" } });
+for (const order of orders) {
+  const customer = await db.customers.findUnique({ where: { id: order.customerId } });
+  order.customerName = customer.name;
+}
+```
+
+**Finding:**
+```
+**[warning]** `src/orders.ts:2-5` — Each loop iteration issues a separate
+DB query for the customer. With N open orders this is N+1 queries.
+Suggestion: Use `include: { customer: true }` in the initial query, or
+batch-fetch customers with `findMany({ where: { id: { in: customerIds } } })`.
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---|---|
+| Report every finding with file, line, severity, and suggestion | Report vague findings without location or fix direction |
+| Prioritize errors first, then warnings, then info | Bury a critical bug under 10 style nits |
+| Read the full diff before writing findings | Review only the first file and stop |
+| Verify claims by reading the referenced code | Assume a pattern is wrong without checking the implementation |
+| Limit info-level findings to 5 max | Flood the review with cosmetic suggestions |
+
+## Final Checklist
+
+Before submitting your review, verify:
+- [ ] Every `error` finding includes a concrete reproduction scenario or input
+- [ ] Every finding has `file:line`, severity, description, and suggestion
+- [ ] Findings are grouped by severity (errors first)
+- [ ] No duplicate findings (same root cause reported once, not per-occurrence)
+- [ ] If zero findings: explicitly state "No issues found" — do not return empty output