@bytesbrains/pi-review-gate 1.1.2

package/AGENTS.md

@@ -0,0 +1,80 @@
+# Review Gate — Agent Usage Guide
+
+> You are an AI agent. Use review-gate tools for all PR review and merge operations. Never call `git merge` directly.
+
+## Golden Rule
+
+> **⚠️ DO NOT call `git merge`, `gh pr merge`, or close PRs directly.**
+> Use `review_check()` → `review_approve()` and let CI handle the merge.
+> CI enforces all gates: required reviewers, breaking change detection, and conventional commit squash.
+
+## Workflow for Reviewing a PR
+
+```
+review_check(pr_number="51")        ← check merge readiness
+  │
+  ▼
+[CI green? Reviews in? No breaking changes? Not stale?]
+  │
+  ▼
+review_approve(pr_number="51",      ← submit your approval
+  comment="LGTM — all gates pass")
+  │
+  ▼
+[CI detects approval + gates pass → auto-merge]
+```
+
+## Workflow for Closing Stale PRs
+
+```
+review_status(pr_number="23")       ← check PR age
+  │
+  ▼
+review_close_stale(pr_number="23",  ← close with reason
+  reason="14+ days inactive")
+```
+
+## Requesting Reviews
+
+```
+review_request(pr_number="51",
+  reviewers="alice,bob")
+```
+
+## Understanding review_check Output
+
+```
+📋 PR #51 Merge Readiness
+   Title: feat(backup): add Firebase volume backup
+   State: open
+   CI Checks: ✅ all green
+   Reviews: 1 approved, 0 changes requested
+   Required reviewers: alice ✅
+   Breaking changes: ✅ none
+   Age: ✅ fresh (2 days)
+   Protected paths: ✅ none
+
+✅ PR is ready to merge! All gates passed.
+```
+
+## When Things Go Wrong
+
+| Problem | Solution |
+|---|---|
+| CI failed | Check CI logs, fix issues, push update |
+| Changes requested | Address reviewer feedback, push fixes, re-request review |
+| Breaking changes detected | Add BREAKING CHANGE to commit body, flag for human review |
+| Missing required reviewers | Use `review_request()` to assign path-required reviewers |
+| PR is stale | Either close with `review_close_stale()` or push an update to refresh |
+
+## Configuration Reference
+
+`.reviewrc.yml` controls review behavior:
+
+```yaml
+staleDays: 14                    # days before PR is considered stale
+minDiverseReviews: 1             # minimum different model families that must review
+requiredReviewers.agents/**: agent-owner   # path → reviewer mapping
+protectedPaths: .gitea/workflows/,agents/   # paths needing human review
+breakingChangePatterns: export interface,export type,BREAKING CHANGE:
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# Review Gate for Pi
+
+[![npm version](https://img.shields.io/npm/v/pi-review-gate)](https://www.npmjs.com/package/pi-review-gate)
+[![license](https://img.shields.io/npm/l/pi-review-gate)](./LICENSE)
+
+> CI-level merge guardian for AI agents — required reviewers, breaking change detection, stale PR cleanup, and review automation. **Agents don't `git merge` — CI merges only after all gates pass.**
+
+## Philosophy
+
+`pi-contrib-gate` handles the *contribution* side (branch → commit → PR).
+`pi-review-gate` handles the *review* side (check → approve → merge).
+
+Core enforcement runs in Gitea Actions — agents **cannot bypass** these gates.
+
+## Install
+
+```bash
+pi install npm:pi-review-gate
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `review_check(pr_number)` | Check PR merge readiness — CI, reviewers, breaking changes, staleness |
+| `review_approve(pr_number, comment)` | Submit an approval review |
+| `review_request(pr_number, reviewers)` | Request reviewers by username |
+| `review_status(pr_number)` | Show detailed review + CI status |
+| `review_close_stale(pr_number, reason)` | Close stale PR with comment |
+
+## Safety Intercepts
+
+The gate **passively monitors** all `bash` tool calls and:
+
+- ⛔ Blocks `git merge` — directs agents to use review tools instead
+- ⚠️ Warns on `gh pr close` or branch deletion
+
+## Review Gates (CI-enforced)
+
+These run in Gitea Actions — agents cannot skip them:
+
+| Gate | Config | Description |
+|---|---|---|
+| CI green | `quality.*` in .contribrc.yml | lint, test, build, doctor audit |
+| Required reviewers | `requiredReviewers.*` in .reviewrc.yml | Path-based required reviewer mapping |
+| Breaking change detection | `breakingChangePatterns` | API surface changes flagged for human review |
+| Stale PR closure | `staleDays` | Auto-close PRs inactive past threshold |
+| Protected paths | `protectedPaths` | Modifications to CI, agents, Docker → human review |
+| Model diversity | `minDiverseReviews` | Different model families must review (from #42) |
+
+## Configuration
+
+Create `.reviewrc.yml` in your project root:
+
+```yaml
+# Required reviewers by path pattern
+requiredReviewers.factory/**: factory-admin
+requiredReviewers.agents/**: agent-owner
+requiredReviewers..gitea/**: ci-admin
+
+# Stale PR threshold (days)
+staleDays: 14
+
+# Minimum distinct model families that must review (0 = disabled)
+minDiverseReviews: 1
+
+# Paths that always require human review
+protectedPaths: .gitea/workflows/,docker-compose.yml,Dockerfile,agents/,factory/package.json
+
+# Patterns that signal API-breaking changes
+breakingChangePatterns: export interface,export type,export function,export class,BREAKING CHANGE:
+```
+
+> Tip: Start with `staleDays: 14` and `minDiverseReviews: 0` during adoption, then tighten.
+
+## Workflow
+
+```
+contrib_submit() from pi-contrib-gate
+  │
+  ▼
+PR opened on Gitea
+  │
+  ▼
+CI runs (lint, test, build, doctor audit)
+  │
+  ▼
+review_check(pr_number)        ← agent checks readiness
+  │
+  ▼
+review_request(pr_number, ...)  ← request specific reviewers
+  │
+  ▼
+[reviewer approves]
+  │
+  ▼
+review_check(pr_number)        ← re-check: all green? required reviewers satisfied?
+  │
+  ▼
+CI auto-merges (squash)        ← only CI can merge
+  │
+  ▼
+PR closed, branch deleted
+```
+
+## Stale PR Cleanup
+
+PRs older than `staleDays` (default 14) are flagged. A CI scheduled job can auto-close them:
+
+```bash
+# Runs nightly in Gitea Actions
+review-gate-stale.sh --repo factory/wrok.in --days 14
+```
+
+## Breaking Change Detection
+
+Every CI run diffs against the base branch and scans for:
+- `export interface` / `export type` / `export function` / `export class` additions
+- `BREAKING CHANGE:` in commit messages
+
+If detected, CI adds a `⚠️ breaking-change` label and requires human review.
+
+## Integration with pi-contrib-gate
+
+The two gates work together:
+
+```
+pi-contrib-gate          pi-review-gate
+     │                        │
+     │  contrib_start_work    │
+     │  contrib_propose       │
+     │  contrib_submit  ────→ PR created
+     │                        │
+     │                        │  review_check
+     │                        │  review_request
+     │                        │  review_approve
+     │                        │  [CI enforcement]
+     │                        │  auto-merge (squash)
+```
+
+Install both for full agent governance:
+
+```bash
+pi install npm:pi-contrib-gate
+pi install npm:pi-review-gate
+```
+
+## License
+
+MIT © [nandal](https://github.com/nandal)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@bytesbrains/pi-review-gate",
+  "version": "1.1.2",
+  "description": "CI-level merge guardian for AI agents \u2014 required reviewers, breaking change detection, stale PR cleanup, and review automation.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "governance",
+    "ci",
+    "code-review",
+    "merge-gate",
+    "breaking-changes"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "review-gate"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/review-gate",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  }
+}

package/src/__tests__/review-gate.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import { loadConfig, DEFAULT_CONFIG } from "../config";
+import { detectBreakingChanges, isStale, matchRequiredReviewers } from "../validate";
+import { exec } from "../helpers";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ═══════════════════════════════════════
+// Config
+// ═══════════════════════════════════════
+describe("ReviewConfig", () => {
+  it("returns defaults when no config", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "review-test-"));
+    const config = loadConfig(tmp);
+    expect(config.staleDays).toBe(14);
+    expect(config.minDiverseReviews).toBe(1);
+    expect(config.protectedPaths.length).toBeGreaterThan(0);
+    expect(config.breakingChangePatterns.length).toBeGreaterThan(0);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses reviewrc.yml", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "review-test-"));
+    fs.writeFileSync(path.join(tmp, ".reviewrc.yml"), [
+      "staleDays: 7",
+      "minDiverseReviews: 2",
+      "protectedPaths: .gitea/,agents/",
+      'requiredReviewers.factory/**: factory-admin',
+      'requiredReviewers.agents/**: agent-owner,reviewer',
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.staleDays).toBe(7);
+    expect(config.minDiverseReviews).toBe(2);
+    expect(config.protectedPaths).toContain(".gitea/");
+    expect(config.protectedPaths).toContain("agents/");
+    expect(config.requiredReviewers["factory/**"]).toEqual(["factory-admin"]);
+    expect(config.requiredReviewers["agents/**"]).toEqual(["agent-owner", "reviewer"]);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Stale detection
+// ═══════════════════════════════════════
+describe("isStale", () => {
+  it("detects stale PR", () => {
+    const oldDate = new Date(Date.now() - 20 * 86400000).toISOString();
+    expect(isStale(oldDate, 14)).toBe(true);
+  });
+
+  it("detects fresh PR", () => {
+    const recentDate = new Date(Date.now() - 5 * 86400000).toISOString();
+    expect(isStale(recentDate, 14)).toBe(false);
+  });
+
+  it("exactly at boundary is fresh", () => {
+    const boundaryDate = new Date(Date.now() - 14 * 86400000 + 1000).toISOString();
+    expect(isStale(boundaryDate, 14)).toBe(false);
+  });
+});
+
+// ═══════════════════════════════════════
+// Required reviewers
+// ═══════════════════════════════════════
+describe("matchRequiredReviewers", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    requiredReviewers: {
+      "factory/": ["backend-dev"],
+      "agents/": ["agent-owner"],
+      ".gitea/": ["ci-admin"],
+      "Dockerfile": ["devops"],
+    },
+  };
+
+  it("matches by directory prefix", () => {
+    expect(matchRequiredReviewers(["factory/orchestrator.ts"], config)).toContain("backend-dev");
+  });
+
+  it("matches multiple patterns", () => {
+    const reviewers = matchRequiredReviewers(["factory/orchestrator.ts", "agents/developer.md"], config);
+    expect(reviewers).toContain("backend-dev");
+    expect(reviewers).toContain("agent-owner");
+  });
+
+  it("matches exact file", () => {
+    expect(matchRequiredReviewers(["Dockerfile"], config)).toContain("devops");
+  });
+
+  it("returns empty for unmatched paths", () => {
+    expect(matchRequiredReviewers(["README.md", "src/app.ts"], config)).toEqual([]);
+  });
+});
+
+// ═══════════════════════════════════════
+// Breaking change detection
+// ═══════════════════════════════════════
+describe("detectBreakingChanges", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    breakingChangePatterns: ["export interface", "export type", "BREAKING CHANGE:"],
+  };
+
+  it("returns no breaking changes for empty diff", () => {
+    // In a test env without a real diff, should return false
+    const result = detectBreakingChanges("HEAD", config, process.cwd());
+    expect(typeof result.hasBreaking).toBe("boolean");
+  });
+});
+
+// ═══════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════
+describe("exec helper", () => {
+  it("returns ok for valid command", () => {
+    const r = exec("echo test");
+    expect(r.ok).toBe(true);
+    expect(r.stdout).toBe("test");
+  });
+
+  it("returns not ok for invalid command", () => {
+    const r = exec("nonexistent-cmd-xyz 2>/dev/null");
+    expect(r.ok).toBe(false);
+  });
+});

package/src/config.ts

@@ -0,0 +1,50 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface ReviewConfig {
+  minDiverseReviews: number;
+  requiredReviewers: Record<string, string[]>;
+  staleDays: number;
+  protectedPaths: string[];
+  breakingChangePatterns: string[];
+}
+
+export const DEFAULT_CONFIG: ReviewConfig = {
+  minDiverseReviews: 1,
+  requiredReviewers: {},
+  staleDays: 14,
+  protectedPaths: [".gitea/workflows/", "docker-compose.yml", "Dockerfile", ".env.example", "agents/", "factory/package.json"],
+  breakingChangePatterns: ["export interface", "export type", "export function", "export class", "BREAKING CHANGE:"],
+};
+
+export function loadConfig(cwd: string): ReviewConfig {
+  const configPath = path.join(cwd, ".reviewrc.yml");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, unknown> = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^\s*([\w][\w.*\/-]+):\s*(.+)$/);
+      if (m) {
+        let val = m[2].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
+        result[m[1]] = val;
+      }
+    }
+    const reviewers: Record<string, string[]> = {};
+    for (const [key, val] of Object.entries(result)) {
+      if (key.startsWith("requiredReviewers.")) {
+        reviewers[key.replace("requiredReviewers.", "")] = (val as string).split(",").map(s => s.trim()).filter(Boolean);
+      }
+    }
+    return {
+      minDiverseReviews: parseInt(result["minDiverseReviews"] as string) || DEFAULT_CONFIG.minDiverseReviews,
+      requiredReviewers: reviewers,
+      staleDays: parseInt(result["staleDays"] as string) || DEFAULT_CONFIG.staleDays,
+      protectedPaths: (result["protectedPaths"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.protectedPaths,
+      breakingChangePatterns: (result["breakingChangePatterns"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.breakingChangePatterns,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,46 @@
+import * as cp from "node:child_process";
+
+export function exec(cmd: string, cwd?: string): { ok: boolean; stdout: string; stderr: string } {
+  try {
+    const r = cp.execSync(cmd, { cwd, encoding: "utf-8", timeout: 30000 });
+    return { ok: true, stdout: r.trim(), stderr: "" };
+  } catch (e: any) {
+    return { ok: false, stdout: e.stdout?.trim() || "", stderr: e.stderr?.trim() || e.message };
+  }
+}
+
+export function currentBranch(cwd: string): string {
+  return exec("git branch --show-current", cwd).stdout;
+}
+
+export function resolveGitea(cwd: string): { repo: string; token: string } {
+  const remote = exec("git remote get-url gitea 2>/dev/null || git remote get-url origin", cwd);
+  const url = remote.stdout || "";
+  const match = url.match(/[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  const repo = match ? `${match[1]}/${match[2]}` : "factory/wrok.in";
+  const credMatch = url.match(/:\/\/([^:]+):([^@]+)@/);
+  const token = credMatch ? credMatch[2] : "";
+  return { repo, token };
+}
+
+export async function giteaApi(path: string, method: string, body: Record<string, unknown> | null, opts: { repo: string; token?: string }, _cwd: string): Promise<{ ok: boolean; data: unknown; error?: string }> {
+  const base = `http://127.0.0.1:3001/api/v1/repos/${opts.repo}`;
+  const url = `${base}${path}`;
+  const headers: Record<string, string> = { "Content-Type": "application/json", "Accept": "application/json" };
+  if (opts.token) headers["Authorization"] = `token ${opts.token}`;
+
+  try {
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok) return { ok: false, data: null, error: text || `HTTP ${res.status}` };
+    try { return { ok: true, data: JSON.parse(text) }; } catch { return { ok: true, data: text }; }
+  } catch (e: any) {
+    return { ok: false, data: null, error: e.message || "Network error" };
+  }
+}
+
+export interface CommitEntry { hash: string; type: string; scope: string; subject: string; body: string; }

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * pi-review-gate — CI-Level Merge Guardian
+ *
+ * Tools: review_check, review_approve, review_request, review_status, review_close_stale
+ * Config: .reviewrc.yml
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { interceptToolCall } from "./intercepts";
+import { checkTool } from "./tools/check";
+import { approveTool, requestTool, statusTool, closeStaleTool } from "./tools/review";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("tool_call", interceptToolCall);
+  pi.registerTool(checkTool);
+  pi.registerTool(approveTool);
+  pi.registerTool(requestTool);
+  pi.registerTool(statusTool);
+  pi.registerTool(closeStaleTool);
+}

package/src/intercepts.ts

@@ -0,0 +1,14 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export async function interceptToolCall(event: any, ctx: ExtensionContext) {
+  if (event.toolName !== "bash" || typeof event.input.command !== "string") return;
+  const cmd = event.input.command;
+
+  if (/\bgit\s+merge\b/.test(cmd)) {
+    const ok = await ctx.ui.confirm("Manual merge blocked", `Direct git merge bypasses review gates.\n\nCommand: ${cmd}\n\nUse review tools instead.\n\nAllow anyway?`);
+    if (!ok) return { block: true, reason: "Use review tools. CI performs the merge after all gates pass." };
+  }
+  if (/\bgh\s+pr\s+close\b/.test(cmd) || /\bgit\s+push\b.*--delete/.test(cmd)) {
+    ctx.ui.notify("Consider using review_close_stale() for PR lifecycle management.", "warning");
+  }
+}

package/src/tools/check.ts

@@ -0,0 +1,81 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { exec, currentBranch, resolveGitea, giteaApi } from "../helpers";
+import { detectBreakingChanges, isStale, matchRequiredReviewers } from "../validate";
+
+export const checkTool = {
+  name: "review_check" as const,
+  label: "Check PR Merge Readiness",
+  description: "Check if a PR meets all merge requirements: CI green, reviewers, no breaking changes, not stale.",
+  parameters: Type.Object({
+    pr_number: Type.Optional(Type.String({})),
+    base: Type.Optional(Type.String({})),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const opts = resolveGitea(ctx.cwd);
+    const base = params.base || "dev";
+    let prNumber = params.pr_number;
+    let pr: Record<string, unknown> | null = null;
+
+    if (prNumber) {
+      const r = await giteaApi(`/pulls/${prNumber}`, "GET", null, opts, ctx.cwd);
+      if (r.ok) pr = r.data as Record<string, unknown>;
+    } else {
+      const branch = currentBranch(ctx.cwd);
+      const r = await giteaApi(`/pulls?state=open&head=${branch}`, "GET", null, opts, ctx.cwd);
+      if (r.ok && Array.isArray(r.data) && r.data.length > 0) {
+        pr = r.data[0] as Record<string, unknown>;
+        prNumber = String(pr.number);
+      }
+    }
+    if (!pr) return { content: [{ type: "text", text: "No open PR found." }], isError: true, details: {} };
+
+    const lines: string[] = [];
+    const issues: string[] = [];
+    let ready = true;
+
+    lines.push(`📋 PR #${prNumber} Merge Readiness`);
+    lines.push(`   Title: ${pr.title || "?"}`);
+    lines.push(`   State: ${pr.state}`);
+
+    const reviewsR = await giteaApi(`/pulls/${prNumber}/reviews`, "GET", null, opts, ctx.cwd);
+    const reviews = Array.isArray(reviewsR.data) ? reviewsR.data : [];
+    const changeRequests = reviews.filter((r: any) => r.state === "REQUEST_CHANGES");
+    if (changeRequests.length > 0) { issues.push(`❌ ${changeRequests.length} reviewer(s) requested changes`); ready = false; }
+    lines.push(`   Reviews: ${reviews.filter((r: any) => r.state === "APPROVED").length} approved, ${changeRequests.length} changes requested`);
+
+    const diff = exec(`git diff ${base}...HEAD --name-only 2>/dev/null`, ctx.cwd);
+    const changedFiles = diff.ok ? diff.stdout.split("\n").filter(Boolean) : [];
+    const required = matchRequiredReviewers(changedFiles, config);
+    if (required.length > 0) {
+      const reviewerLogins = new Set(reviews.map((r: any) => r.user?.login));
+      const missing = required.filter(r => !reviewerLogins.has(r));
+      if (missing.length > 0) issues.push(`⚠️ Missing required reviewers: ${missing.join(", ")}`);
+      lines.push(`   Required reviewers: ${required.join(", ")}`);
+    }
+
+    const breaking = detectBreakingChanges(base, config, ctx.cwd);
+    if (breaking.hasBreaking) { issues.push("⚠️ Potential breaking changes detected"); for (const c of breaking.changes) issues.push(`   - ${c}`); }
+    lines.push(`   Breaking changes: ${breaking.hasBreaking ? "⚠️ detected" : "✅ none"}`);
+
+    if (pr.created_at) {
+      const stale = isStale(pr.created_at as string, config.staleDays);
+      if (stale) issues.push(`⚠️ PR is ${config.staleDays}+ days old`);
+      lines.push(`   Age: ${stale ? "⚠️ stale" : "✅ fresh"}`);
+    }
+
+    const hasProtected = changedFiles.some(f => config.protectedPaths.some(p => f.startsWith(p)));
+    if (hasProtected) issues.push("🔒 Protected paths modified — human review required");
+    lines.push(`   Protected paths: ${hasProtected ? "🔒 yes" : "✅ none"}`);
+
+    const hasBlockers = issues.some(i => i.startsWith("❌") || i.startsWith("🔒"));
+    if (issues.length > 0) { lines.push(""); for (const i of issues) lines.push(`   ${i}`); }
+    if (hasBlockers) lines.push("", "❌ PR is NOT ready.");
+    else if (issues.length === 0) lines.push("", "✅ PR is ready to merge!");
+    else lines.push("", "⚠️ PR has warnings but can be merged.");
+
+    return { content: [{ type: "text", text: lines.join("\n") }], details: { prNumber, ready: !hasBlockers } };
+  },
+};

package/src/tools/review.ts

@@ -0,0 +1,101 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { currentBranch, resolveGitea, giteaApi } from "../helpers";
+
+export const approveTool = {
+  name: "review_approve" as const,
+  label: "Approve PR",
+  description: "Submit an approval review on a pull request.",
+  parameters: Type.Object({
+    pr_number: Type.Optional(Type.String({})),
+    comment: Type.Optional(Type.String({})),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    let prNumber = params.pr_number;
+    if (!prNumber) {
+      const branch = currentBranch(ctx.cwd);
+      const r = await giteaApi(`/pulls?state=open&head=${branch}`, "GET", null, opts, ctx.cwd);
+      if (r.ok && Array.isArray(r.data) && r.data.length > 0) prNumber = String((r.data[0] as any).number);
+    }
+    if (!prNumber) return { content: [{ type: "text", text: "No open PR found." }], isError: true, details: {} };
+    const body: Record<string, unknown> = { event: "APPROVE" };
+    if (params.comment) body.body = params.comment;
+    const r = await giteaApi(`/pulls/${prNumber}/reviews`, "POST", body, opts, ctx.cwd);
+    if (!r.ok) return { content: [{ type: "text", text: `Approval failed: ${r.error}` }], isError: true, details: {} };
+    return { content: [{ type: "text", text: `✅ PR #${prNumber} approved. CI will auto-merge once all checks pass.` }], details: { prNumber } };
+  },
+};
+
+export const requestTool = {
+  name: "review_request" as const,
+  label: "Request Reviewers",
+  description: "Request specific reviewers on a pull request.",
+  parameters: Type.Object({
+    pr_number: Type.Optional(Type.String({})),
+    reviewers: Type.String({}),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    let prNumber = params.pr_number;
+    if (!prNumber) {
+      const branch = currentBranch(ctx.cwd);
+      const r = await giteaApi(`/pulls?state=open&head=${branch}`, "GET", null, opts, ctx.cwd);
+      if (r.ok && Array.isArray(r.data) && r.data.length > 0) prNumber = String((r.data[0] as any).number);
+    }
+    if (!prNumber) return { content: [{ type: "text", text: "No open PR found." }], isError: true, details: {} };
+    const reviewerList = params.reviewers.split(",").map((s: string) => s.trim()).filter(Boolean);
+    if (reviewerList.length === 0) return { content: [{ type: "text", text: "No valid reviewers." }], isError: true, details: {} };
+    const r = await giteaApi(`/pulls/${prNumber}/requested_reviewers`, "POST", { reviewers: reviewerList }, opts, ctx.cwd);
+    if (!r.ok) return { content: [{ type: "text", text: `Failed: ${r.error}` }], isError: true, details: {} };
+    return { content: [{ type: "text", text: `✅ Reviewers requested on PR #${prNumber}: ${reviewerList.join(", ")}` }], details: { prNumber } };
+  },
+};
+
+export const statusTool = {
+  name: "review_status" as const,
+  label: "Review Status",
+  description: "Show detailed review and CI status for a PR.",
+  parameters: Type.Object({ pr_number: Type.Optional(Type.String({})) }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    let prNumber = params.pr_number;
+    if (!prNumber) {
+      const branch = currentBranch(ctx.cwd);
+      const r = await giteaApi(`/pulls?state=open&head=${branch}`, "GET", null, opts, ctx.cwd);
+      if (r.ok && Array.isArray(r.data) && r.data.length > 0) prNumber = String((r.data[0] as any).number);
+    }
+    if (!prNumber) return { content: [{ type: "text", text: "No open PR found." }], isError: true, details: {} };
+    const prR = await giteaApi(`/pulls/${prNumber}`, "GET", null, opts, ctx.cwd);
+    if (!prR.ok) return { content: [{ type: "text", text: `PR #${prNumber} not found.` }], isError: true, details: {} };
+    const pr = prR.data as Record<string, unknown>;
+    const reviewsR = await giteaApi(`/pulls/${prNumber}/reviews`, "GET", null, opts, ctx.cwd);
+    const reviews = Array.isArray(reviewsR.data) ? reviewsR.data : [];
+    const lines = [`📋 PR #${prNumber} — ${pr.title}`, `   State: ${pr.state}  |  Draft: ${pr.draft ? "yes" : "no"}`, `   Author: ${(pr.user as any)?.login}`, `   Branch: ${(pr as any).head?.label || "?"} → ${(pr as any).base?.label || "?"}`, `   URL: ${pr.html_url}`, "", `👥 Reviews (${reviews.length}):`];
+    for (const r of reviews as any[]) {
+      const icon = r.state === "APPROVED" ? "✅" : r.state === "REQUEST_CHANGES" ? "❌" : "💬";
+      lines.push(`   ${icon} ${r.user?.login} — ${r.state}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }], details: { prNumber } };
+  },
+};
+
+export const closeStaleTool = {
+  name: "review_close_stale" as const,
+  label: "Close Stale PR",
+  description: "Close a stale pull request with a comment.",
+  parameters: Type.Object({
+    pr_number: Type.String({}),
+    reason: Type.Optional(Type.String({})),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    const reason = params.reason || "stale";
+    const prR = await giteaApi(`/pulls/${params.pr_number}`, "GET", null, opts, ctx.cwd);
+    if (!prR.ok) return { content: [{ type: "text", text: `PR #${params.pr_number} not found.` }], isError: true, details: {} };
+    await giteaApi(`/issues/${params.pr_number}/comments`, "POST", { body: `🔒 Auto-closed: ${reason}.` }, opts, ctx.cwd);
+    const r = await giteaApi(`/pulls/${params.pr_number}`, "PATCH", { state: "closed" }, opts, ctx.cwd);
+    if (!r.ok) return { content: [{ type: "text", text: `Failed: ${r.error}` }], isError: true, details: {} };
+    return { content: [{ type: "text", text: `🔒 PR #${params.pr_number} closed.` }], details: { prNumber: params.pr_number } };
+  },
+};

package/src/validate.ts

@@ -0,0 +1,37 @@
+import type { ReviewConfig } from "./config";
+import { exec } from "./helpers";
+
+export function detectBreakingChanges(baseBranch: string, config: ReviewConfig, cwd: string): { hasBreaking: boolean; changes: string[] } {
+  const changes: string[] = [];
+  const diff = exec(`git diff ${baseBranch}...HEAD --diff-filter=M -- "*.ts" "*.tsx" 2>/dev/null`, cwd);
+  if (!diff.ok || !diff.stdout) return { hasBreaking: false, changes: [] };
+  for (const pattern of config.breakingChangePatterns) {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const matches = diff.stdout.split("\n").filter(l => l.startsWith("+") && new RegExp(escaped).test(l));
+    if (matches.length > 0) changes.push(`Pattern "${pattern}" matched in ${matches.length} added line(s)`);
+  }
+  const log = exec(`git log ${baseBranch}..HEAD --oneline`, cwd);
+  if (log.ok && log.stdout.includes("BREAKING CHANGE")) changes.push("Commit message includes BREAKING CHANGE marker");
+  return { hasBreaking: changes.length > 0, changes };
+}
+
+export function isStale(prCreatedAt: string, staleDays: number): boolean {
+  return (Date.now() - new Date(prCreatedAt).getTime()) / 86400000 > staleDays;
+}
+
+export function matchRequiredReviewers(changedFiles: string[], config: ReviewConfig): string[] {
+  const matched = new Set<string>();
+  for (const [pattern, reviewers] of Object.entries(config.requiredReviewers)) {
+    if (changedFiles.some(f => pattern.endsWith("*") ? f.startsWith(pattern.slice(0, -1)) : pattern.endsWith("/") ? f.startsWith(pattern) : f === pattern)) {
+      for (const r of reviewers) matched.add(r);
+    }
+  }
+  return [...matched];
+}
+
+export function parseDependencies(body: string, pattern: string): string[] {
+  const deps = new Set<string>();
+  let m; const re = new RegExp(pattern, "gi");
+  while ((m = re.exec(body)) !== null) deps.add(m[1]);
+  return [...deps];
+}