gentle-pi 0.5.0 → 0.6.0

package/assets/agents/review-readability.md

@@ -0,0 +1,24 @@
+---
+name: review-readability
+description: R2 Readability reviewer — naming, complexity, intention, maintainability, review size, and context clarity.
+tools: read, grep, glob, bash
+---
+
+You are **R2 Readability**, a read-only reviewer. Find clarity problems; do not fix them.
+
+Rule sources: ai-course-2 slides `05-code-smells.md`, `06-safe-refactoring.md`, `07-advanced-refactoring.md`, `08-tech-debt.md`, `22-docs-as-code.md`, `25-executive-summary.md`.
+
+## Review rules
+
+- Flag magic numbers that should be named constants or business-rule objects.
+- Flag long parameter lists that should be parameter objects.
+- Flag duplicated logic across components/hooks/modules.
+- Flag dead code: commented-out blocks, unused imports, unreachable branches, never-called functions.
+- Flag naming that hides intent or needs comment-heavy explanation.
+- Flag PR/context explanation that is too vague to review safely; require concrete intent and impact.
+- Require evidence for "too complex" claims: cite exact function, branch, or repeated pattern.
+- Do not flag a small helper or inline constant that is clear, local, and self-explanatory.
+
+## Output contract
+
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`

package/assets/agents/review-reliability.md

@@ -0,0 +1,25 @@
+---
+name: review-reliability
+description: R3 Reliability reviewer — behavior-first tests, coverage value, edge cases, determinism, contracts, and regressions.
+tools: read, grep, glob, bash
+---
+
+You are **R3 Reliability**, a read-only reviewer. Find test and behavior risks; do not fix them.
+
+Rule sources: ai-course-2 slides `01-testing-setup.md`, `02-tdd-implementation.md`, `03-integration-testing.md`, `04-e2e-testing.md`, `10-strategic-coverage.md`, `11-playwright-visibility.md`, `12-quality-gates-husky.md`, `23-apis-components.md`.
+
+## Review rules
+
+- Block behavior changes without tests that assert externally visible contract.
+- Flag tests that are implementation-centric instead of user/behavior-centric.
+- Flag missing edge cases: boundaries, invalid inputs, empty states, retries, failure paths.
+- Block when CI can pass with `test.only`; require `forbidOnly` or equivalent in CI configs.
+- Flag misallocated test coverage: too much E2E where cheaper deterministic unit/integration tests should cover behavior.
+- Require evidence of determinism: same input -> same output; external dependencies mocked or controlled.
+- Flag weak selectors in UI tests; prefer semantic/user-visible queries.
+- Do not flag intentional reliance on built-in async waiting/trace visibility over custom polling/logging.
+- Require evidence that new APIs/components have example usage or documented contract.
+
+## Output contract
+
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`

package/assets/agents/review-resilience.md

@@ -0,0 +1,24 @@
+---
+name: review-resilience
+description: R4 Resilience reviewer — fallbacks, retry/backoff, graceful degradation, observability, load, rollback, and SLO risks.
+tools: read, grep, glob, bash
+---
+
+You are **R4 Resilience**, a read-only reviewer. Find operational failure risks; do not fix them.
+
+Rule sources: ai-course-2 slides `09-essential-metrics.md`, `13-observability-strategy.md`, `14-sentry-implementation.md`, `15-sentry-errors.md`, `16-sentry-performance.md`, `17-sentry-alertas.md`, `29-performance-percibida.md`.
+
+## Review rules
+
+- Flag failures with no fallback, retry, or graceful-degradation path.
+- Block when production error-rate or build/test thresholds are ignored. Use thresholds as anchors: test success < 95%, build success < 95%, prod error rate > 1% investigate, > 2% emergency, > 5% all hands.
+- Flag releases that can regress without alerting/observability hooks.
+- Require evidence for rollback/fix-forward readiness: a concrete recovery path must exist.
+- Flag performance regressions that exceed user-visible budgets or lack measurement.
+- Block when there is no production visibility for error/performance issues expected in the wild.
+- Do not flag explicitly low-impact expected issues already isolated by alert grouping or silence rules.
+- Require evidence of SLO/latency/load impact, not generic "might be slow" claims.
+
+## Output contract
+
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`

package/assets/agents/review-risk.md

@@ -0,0 +1,24 @@
+---
+name: review-risk
+description: R1 Risk reviewer — security, privilege boundaries, data exposure, dependency risks, and merge-blocking vulnerabilities.
+tools: read, grep, glob, bash
+---
+
+You are **R1 Risk**, a read-only reviewer. Find security risks; do not fix them.
+
+Rule sources: ai-course-2 slides `18-env-secrets.md`, `19-web-security.md`, `20-auth-tokens.md`, `21-owasp-top10.md`.
+
+## Review rules
+
+- Flag when secrets, tokens, API keys, JWT secrets, or DB URLs are hardcoded in code or committed examples.
+- Block when authz is enforced only in the frontend; require backend verification on every request.
+- Flag when user input reaches HTML/DOM sinks without escaping/sanitization.
+- Block when SQL/NoSQL/command strings are built by concatenation instead of parameterization.
+- Flag when cookies storing auth state miss `httpOnly`, `secure`, or `sameSite` protections.
+- Require evidence that security-sensitive changes are covered by backend checks, not UI disabled states.
+- Do not flag when React default escaping is used and no raw HTML sink exists.
+- Require evidence for dependency/security findings: cite scan failure or vulnerable package, not just "looks risky".
+
+## Output contract
+
+Report findings only. Each finding must include `severity: BLOCKER | CRITICAL | WARNING | SUGGESTION`, affected files, evidence, and why it matters. If clean, say exactly: `No findings.`

package/assets/chains/4r-review.chain.md

@@ -0,0 +1,39 @@
+---
+name: 4r-review
+description: Pre-PR 4R review fan-out — runs all four review lenses (risk, readability, reliability, resilience) in sequence and writes individual reports.
+---
+
+## review-risk
+
+output: review-risk-report.md
+outputMode: file-only
+progress: true
+
+Run R1 Risk review on the current diff. Report security, privilege boundary, data exposure, dependency, and merge-blocking vulnerability findings. If clean, say exactly: `No findings.`
+
+## review-readability
+
+reads: review-risk-report.md
+output: review-readability-report.md
+outputMode: file-only
+progress: true
+
+Run R2 Readability review on the current diff. Report naming, complexity, intention, maintainability, review size, and context clarity findings. If clean, say exactly: `No findings.`
+
+## review-reliability
+
+reads: review-risk-report.md+review-readability-report.md
+output: review-reliability-report.md
+outputMode: file-only
+progress: true
+
+Run R3 Reliability review on the current diff. Report behavior-first test coverage, edge case, determinism, contract, and regression findings. If clean, say exactly: `No findings.`
+
+## review-resilience
+
+reads: review-risk-report.md+review-readability-report.md+review-reliability-report.md
+output: review-resilience-report.md
+outputMode: file-only
+progress: true
+
+Run R4 Resilience review on the current diff. Report fallback, retry/backoff, graceful degradation, observability, load, rollback, and SLO risk findings. If clean, say exactly: `No findings.`

package/assets/orchestrator.md

@@ -384,3 +384,19 @@ Automatic mode does not override reviewer burnout protection.
 - Ask before destructive git operations, publishing, or irreversible file changes.
 - Keep writes single-threaded unless isolated worktrees are explicitly approved.
 - Preserve human control: user decisions beat agent momentum.
+
+## 4R Review Triggers
+
+The extension (`extensions/gentle-ai.ts`) gates `bash` tool calls that look like git/gh workflow events. Gate semantics:
+
+- **pre-commit** (`git commit`): advisory only. The extension notifies the user to consider running `review-readability` but does NOT block. No orchestrator action needed.
+- **pre-push** (`git push`): advisory only. Same as pre-commit — notify, do not block.
+- **pre-pr** (`gh pr create`): **strong gate**. The extension blocks when any of these hold:
+  - Changed paths match hot globs: `**/auth/**`, `**/update/**`, `**/security/**`, `**/payments/**`
+  - Diff exceeds 400 changed lines (added + deleted)
+  - When blocked, the reason names all four agents to run first.
+- **post-sdd-phase** (design, apply): **strong gate** for `judgment-day`. Handled separately by SDD phase orchestration, not this diff-based hook.
+
+When the extension blocks a `gh pr create` command, the orchestrator must launch the `4r-review` chain (or run the four agents individually) and wait for their reports before the user retries the PR command.
+
+Prohibition: do NOT configure the full 4R fan-out on `pre-commit` or `pre-push` with `always: true`. Everyday events must use a single advisory lens to keep development-loop cost low (spec G token-budget rule). The `validateTriggerRuleSet` function in `lib/review-triggers.ts` enforces this at config load time.

package/extensions/gentle-ai.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import {
 	existsSync,
 	mkdirSync,
@@ -38,6 +39,12 @@ import {
 	sddStatusSeverity,
 	type SddPhase,
 } from "../lib/sdd-status.ts";
+import {
+	evaluateEvent,
+	matchPathGlobs,
+	type ChangedDiff,
+	type TriggerEvent,
+} from "../lib/review-triggers.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
@@ -1760,6 +1767,139 @@ async function handlePersonaCommand(ctx: ExtensionContext): Promise<void> {
 	);
 }
 
+// ---------------------------------------------------------------------------
+// Review gate helpers — pure, exported via __testing for unit tests
+// ---------------------------------------------------------------------------
+
+/**
+ * Classifies a bash command string as a TriggerEvent for the review gate,
+ * or returns null if the command is not a recognized git/gh workflow trigger.
+ *
+ * Regexes are tolerant of flags between tokens.
+ */
+export function classifyReviewEvent(command: string): TriggerEvent | null {
+	const trimmed = command.trim();
+	// gh pr create → pre-pr (check before generic push to avoid overlap)
+	if (/^gh\s+pr\s+create\b/.test(trimmed)) return "pre-pr";
+	// git commit → pre-commit
+	if (/^git(?:\s+(?:-C\s+\S+|--work-tree=\S+|--git-dir=\S+))?\s+commit\b/.test(trimmed))
+		return "pre-commit";
+	// git push → pre-push
+	if (/^git(?:\s+(?:-C\s+\S+|--work-tree=\S+|--git-dir=\S+))?\s+push\b/.test(trimmed))
+		return "pre-push";
+	return null;
+}
+
+/**
+ * Parses the output of `git diff --numstat` into a ChangedDiff.
+ * Binary files show `-  -  path`; their contribution to changedLines is 0.
+ */
+export function parseNumstat(output: string): ChangedDiff {
+	const changedPaths: string[] = [];
+	let changedLines = 0;
+	for (const line of output.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		// Format: "<added>\t<deleted>\t<path>"
+		const parts = trimmed.split("\t");
+		if (parts.length < 3) continue;
+		const added = parts[0];
+		const deleted = parts[1];
+		const filePath = parts.slice(2).join("\t");
+		if (!filePath) continue;
+		changedPaths.push(filePath);
+		// Binary rows have "-" in both columns; treat as 0.
+		const addedNum = added === "-" ? 0 : parseInt(added, 10);
+		const deletedNum = deleted === "-" ? 0 : parseInt(deleted, 10);
+		if (!isNaN(addedNum)) changedLines += addedNum;
+		if (!isNaN(deletedNum)) changedLines += deletedNum;
+	}
+	return { changedPaths, changedLines };
+}
+
+/**
+ * Computes a ChangedDiff for the given event by running git numstat.
+ * Returns null on any error (fail open — never break the user's git command).
+ */
+function computeDiffForEvent(event: TriggerEvent, cwd: string): ChangedDiff | null {
+	const gitOpts = {
+		cwd,
+		encoding: "utf8" as const,
+		stdio: ["pipe", "pipe", "pipe"] as const,
+		// Bound synchronous git calls so a slow/large repo cannot freeze the extension process.
+		// The existing outer try/catch returns null (fail-open) when this throws.
+		timeout: 2000,
+	};
+	try {
+		let raw: string;
+		if (event === "pre-commit") {
+			raw = execFileSync("git", ["diff", "--cached", "--numstat"], gitOpts);
+		} else {
+			// pre-push or pre-pr: diff vs merge-base
+			let base = "";
+			for (const ref of ["origin/HEAD", "origin/main", "main"]) {
+				try {
+					base = execFileSync("git", ["merge-base", "HEAD", ref], gitOpts).trim();
+					if (base) break;
+				} catch {
+					// try next ref
+				}
+			}
+			if (!base) {
+				// Final fallback: cached diff
+				try {
+					raw = execFileSync("git", ["diff", "--cached", "--numstat"], gitOpts);
+					return parseNumstat(raw);
+				} catch {
+					return null;
+				}
+			}
+			raw = execFileSync("git", ["diff", "--numstat", `${base}...HEAD`], gitOpts);
+		}
+		return parseNumstat(raw);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Runs the review gate for a bash command, composing with the existing
+ * confirmCommand flow. Returns a block result for strong mode, notifies for
+ * advisory mode, or returns undefined to fall through.
+ */
+async function applyReviewGate(
+	command: string,
+	ctx: ExtensionContext,
+): Promise<ToolCallEventResult | undefined> {
+	const event = classifyReviewEvent(command);
+	if (!event) return undefined;
+
+	const diff = computeDiffForEvent(event, ctx.cwd);
+	if (!diff) return undefined;
+
+	const result = evaluateEvent(event, diff);
+	if (!result) return undefined;
+
+	if (result.mode === "advisory") {
+		if (ctx.hasUI) {
+			const commitOrPush = event === "pre-push" ? "this push" : "this commit";
+			ctx.ui.notify(
+				`Review suggestion: consider running agent "${result.run.join(", ")}" before ${commitOrPush}. ${result.reason}`,
+				"info",
+			);
+		}
+		return undefined;
+	}
+
+	// strong mode — block
+	return {
+		block: true,
+		reason:
+			`Gentle AI 4R review gate: run ${result.run.join(", ")} before this command. ` +
+			result.reason,
+	};
+}
+
 /** @internal */
 export const __testing = {
 	listAgentsFromDir,
@@ -1767,6 +1907,8 @@ export const __testing = {
 	classifyGuardedCommand,
 	loadRuntimeGuardrailsConfig,
 	buildGentlePrompt,
+	classifyReviewEvent,
+	parseNumstat,
 };
 
 export default function gentleAi(pi: ExtensionAPI): void {
@@ -1850,6 +1992,8 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		if (event.toolName !== "bash") return undefined;
 		if (!isRecord(event.input) || typeof event.input.command !== "string")
 			return undefined;
+		const reviewGateResult = await applyReviewGate(event.input.command, ctx);
+		if (reviewGateResult) return reviewGateResult;
 		return confirmCommand(event.input.command, ctx);
 	});
 

package/lib/review-triggers.ts

@@ -0,0 +1,414 @@
+/**
+ * review-triggers.ts
+ *
+ * Pure trigger logic for the 4R review gate system. No I/O, fully unit-testable.
+ * Ported 1:1 from gentle-ai/internal/catalog/triggers.go and
+ * gentle-ai/internal/model/trigger.go.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type TriggerEvent =
+	| "pre-commit"
+	| "pre-push"
+	| "pre-pr"
+	| "post-sdd-phase"
+	| "on-ci"
+	| "on-schedule";
+
+export type TriggerMode = "advisory" | "strong";
+
+export interface TriggerWhen {
+	always?: boolean;
+	pathGlobs?: string[];
+	minDiffLines?: number;
+	phases?: string[];
+	combine?: "" | "or" | "and";
+}
+
+export interface TriggerBinding {
+	on: TriggerEvent;
+	when: TriggerWhen;
+	run: string[];
+	mode: TriggerMode;
+	reason: string;
+}
+
+export interface TriggerRuleSet {
+	bindings: TriggerBinding[];
+}
+
+export interface ChangedDiff {
+	changedPaths: string[];
+	changedLines: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum number of changed lines in a diff that triggers the full 4R review
+ * fan-out on pre-pr events. Mirrors defaultLargeChangedLineThreshold in triggers.go.
+ */
+export const LARGE_CHANGED_LINE_THRESHOLD = 400;
+
+/**
+ * Closed set of recognized agent identifiers.
+ * Mirrors knownAgentList in triggers.go.
+ */
+export const KNOWN_AGENTS: readonly string[] = [
+	// 4R review lenses
+	"review-risk",
+	"review-readability",
+	"review-reliability",
+	"review-resilience",
+	// Adversarial verification
+	"judgment-day",
+	// SDD phase identifiers
+	"sdd-explore",
+	"sdd-propose",
+	"sdd-spec",
+	"sdd-design",
+	"sdd-tasks",
+	"sdd-apply",
+	"sdd-verify",
+	"sdd-archive",
+];
+
+// ---------------------------------------------------------------------------
+// Supported events (mirrors defaultRuleSet.Events in triggers.go)
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_EVENTS: ReadonlySet<TriggerEvent> = new Set([
+	"pre-commit",
+	"pre-push",
+	"pre-pr",
+	"post-sdd-phase",
+	"on-ci",
+	"on-schedule",
+]);
+
+// ---------------------------------------------------------------------------
+// Valid SDD phase identifiers for the When.phases field.
+// Mirrors validSDDPhases in ValidateTriggerRuleSet.
+// ---------------------------------------------------------------------------
+
+const VALID_SDD_PHASES: ReadonlySet<string> = new Set([
+	"sdd-explore",
+	"sdd-propose",
+	"sdd-spec",
+	"sdd-design",
+	"sdd-tasks",
+	"sdd-apply",
+	"sdd-verify",
+	"sdd-archive",
+	// Short names used in post-sdd-phase conditions.
+	"explore",
+	"propose",
+	"spec",
+	"design",
+	"tasks",
+	"apply",
+	"verify",
+	"archive",
+]);
+
+// ---------------------------------------------------------------------------
+// DEFAULT_RULE_SET
+// Ported 1:1 from triggers.go defaultRuleSet.Bindings
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_RULE_SET: TriggerRuleSet = {
+	bindings: [
+		{
+			on: "pre-commit",
+			when: { always: true },
+			run: ["review-readability"],
+			mode: "advisory",
+			reason:
+				"everyday event → ONE cheap advisory lens (~1x); full 4R fan-out reserved for pre-pr",
+		},
+		{
+			on: "pre-push",
+			when: { always: true },
+			run: ["review-readability"],
+			mode: "advisory",
+			reason:
+				"everyday event → ONE cheap advisory lens (~1x); 4R fan-out reserved for pre-pr on hot paths / large diffs",
+		},
+		{
+			on: "pre-pr",
+			when: {
+				pathGlobs: ["**/auth/**", "**/update/**", "**/security/**", "**/payments/**"],
+				minDiffLines: LARGE_CHANGED_LINE_THRESHOLD,
+				combine: "or",
+			},
+			run: ["review-risk", "review-resilience", "review-readability", "review-reliability"],
+			mode: "strong",
+			reason:
+				"full 4R fan-out (~4x) only on hot paths (auth/update/security/payments) or diffs exceeding 400 changed lines",
+		},
+		{
+			on: "post-sdd-phase",
+			when: { phases: ["design", "apply"] },
+			run: ["judgment-day"],
+			mode: "strong",
+			reason:
+				"adversarial verification (~4 + 3*findings cost) only at high-stakes SDD phases (design and apply)",
+		},
+	],
+};
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Reports whether run contains all four 4R review agents.
+ * Mirrors has4RFanOut in triggers.go.
+ */
+function has4RFanOut(run: readonly string[]): boolean {
+	const found = new Set(run);
+	return (
+		found.has("review-risk") &&
+		found.has("review-readability") &&
+		found.has("review-reliability") &&
+		found.has("review-resilience")
+	);
+}
+
+/**
+ * Validates each binding in set against the closed vocabularies.
+ * Throws a descriptive Error on the first violation.
+ * Mirrors ValidateTriggerRuleSet in triggers.go.
+ */
+export function validateTriggerRuleSet(set: TriggerRuleSet): void {
+	const knownAgentsSet = new Set(KNOWN_AGENTS);
+	const validCombine: ReadonlySet<string> = new Set(["", "or", "and"]);
+
+	for (let i = 0; i < set.bindings.length; i++) {
+		const b = set.bindings[i];
+
+		// Validate On.
+		if (!SUPPORTED_EVENTS.has(b.on)) {
+			throw new Error(`binding[${i}]: unknown event "${b.on}"`);
+		}
+
+		// Validate Run.
+		if (!b.run || b.run.length === 0) {
+			throw new Error(`binding[${i}]: Run must not be empty`);
+		}
+		for (const agent of b.run) {
+			if (!knownAgentsSet.has(agent)) {
+				throw new Error(`binding[${i}]: unknown run agent "${agent}"`);
+			}
+		}
+
+		// Validate Mode.
+		if (b.mode !== "advisory" && b.mode !== "strong") {
+			throw new Error(`binding[${i}]: unknown mode "${b.mode}"`);
+		}
+
+		// Validate When vocabulary.
+		const w = b.when;
+
+		// MinDiffLines when non-zero must be positive (> 0). Zero is unset/unused; negative rejected.
+		// Check this BEFORE the "at least one condition" check so negative values get the right error.
+		if (w.minDiffLines !== undefined && w.minDiffLines < 0) {
+			throw new Error(`binding[${i}]: When.MinDiffLines must be a positive integer (> 0)`);
+		}
+
+		// PathGlobs non-nil but empty is invalid.
+		if (w.pathGlobs !== undefined && w.pathGlobs.length === 0) {
+			throw new Error(`binding[${i}]: When.pathGlobs must not be an empty slice`);
+		}
+
+		// Must have at least one condition set.
+		const hasCondition =
+			w.always === true ||
+			(w.pathGlobs !== undefined && w.pathGlobs.length > 0) ||
+			(w.minDiffLines !== undefined && w.minDiffLines > 0) ||
+			(w.phases !== undefined && w.phases.length > 0);
+		if (!hasCondition) {
+			throw new Error(
+				`binding[${i}]: When must have at least one condition (always, pathGlobs, minDiffLines, or phases)`,
+			);
+		}
+
+		// Combine must be a recognized value.
+		const combineVal: string = w.combine ?? "";
+		if (!validCombine.has(combineVal)) {
+			throw new Error(
+				`binding[${i}]: When.combine "${combineVal}" is not in {"" "or" "and"}`,
+			);
+		}
+
+		// Phases must be recognized SDD phase identifiers.
+		if (w.phases) {
+			for (const p of w.phases) {
+				if (!VALID_SDD_PHASES.has(p)) {
+					throw new Error(
+						`binding[${i}]: When.phases entry "${p}" is not a recognized SDD phase identifier`,
+					);
+				}
+			}
+		}
+
+		// Phases is only valid for post-sdd-phase event.
+		if (w.phases && w.phases.length > 0 && b.on !== "post-sdd-phase") {
+			throw new Error(
+				`binding[${i}]: When.phases may only be used with the post-sdd-phase event (got "${b.on}")`,
+			);
+		}
+
+		// Spec G prohibition: full 4R fan-out on everyday event with always=true is PROHIBITED.
+		if ((b.on === "pre-commit" || b.on === "pre-push") && w.always === true) {
+			if (has4RFanOut(b.run)) {
+				throw new Error(
+					`binding[${i}]: full 4R fan-out (review-risk, review-readability, review-reliability, review-resilience) ` +
+						`on "${b.on}" with when.always=true is prohibited — everyday events must use a single advisory lens, ` +
+						`not the full 4R fan-out (spec G token-budget rule)`,
+				);
+			}
+		}
+	}
+}
+
+// Validate DEFAULT_RULE_SET at module load — proves it's always valid.
+validateTriggerRuleSet(DEFAULT_RULE_SET);
+
+// ---------------------------------------------------------------------------
+// matchPathGlobs
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts a glob pattern (using ** and *) to a RegExp.
+ * Supports the doublestar/segment forms used by the trigger rule set.
+ *
+ * Key behavior: a leading doublestar-slash means "zero or more leading path
+ * segments", so a pattern like auth-glob matches both "src/auth/login.ts"
+ * AND "auth/login.ts" (zero leading segments). A doublestar in a non-leading
+ * position expands to ".*". A single star expands to "[^/]*" (no separator
+ * crossing). All other regex metacharacters are escaped.
+ */
+function globToRegExp(glob: string): RegExp {
+	// Step 1: escape all regex metacharacters except * (which we handle below).
+	const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+
+	// Step 2: tokenize every ** before touching single *.
+	const tokenized = escaped.replace(/\*\*/g, "__DS__");
+
+	// Step 3: replace single * with [^/]* (no path-separator crossing).
+	const withSingleStar = tokenized.replace(/\*/g, "[^/]*");
+
+	// Step 4: convert a leading __DS__/ to "zero or more leading path segments",
+	// so that a glob like the auth hot-path pattern matches both
+	// "src/auth/login.ts" (leading segments) AND "auth/login.ts" (zero leading).
+	const withLeading = withSingleStar.replace(/^__DS__\//, "(?:.*/)?");
+
+	// Step 5: restore remaining __DS__ tokens as .* (match any chars including /).
+	const withDoubleStar = withLeading.replace(/__DS__/g, ".*");
+
+	return new RegExp(`^${withDoubleStar}$`);
+}
+
+/**
+ * Returns true if any path in `paths` matches any glob in `globs`.
+ * Supports the `**` wildcard matching any path segment.
+ */
+export function matchPathGlobs(paths: readonly string[], globs: readonly string[]): boolean {
+	if (paths.length === 0 || globs.length === 0) return false;
+	const regexps = globs.map(globToRegExp);
+	return paths.some((p) => regexps.some((re) => re.test(p)));
+}
+
+// ---------------------------------------------------------------------------
+// evaluateEvent
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluates a trigger event against the DEFAULT_RULE_SET and the provided diff.
+ *
+ * Returns `{ run, mode, reason }` for the first binding that fires, or `null`
+ * if no binding fires.
+ *
+ * Note: `post-sdd-phase` bindings use `phases` for firing, not diff conditions.
+ * Passing a `post-sdd-phase` event here will always return null because the
+ * phase parameter is not available in this diff-based entry point. Use
+ * `evaluatePostSddPhaseEvent` for phase-driven triggering.
+ */
+export function evaluateEvent(
+	event: TriggerEvent,
+	diff: ChangedDiff,
+): { run: string[]; mode: TriggerMode; reason: string } | null {
+	for (const binding of DEFAULT_RULE_SET.bindings) {
+		if (binding.on !== event) continue;
+
+		const w = binding.when;
+
+		// always → unconditional match
+		if (w.always === true) {
+			return { run: binding.run, mode: binding.mode, reason: binding.reason };
+		}
+
+		// post-sdd-phase uses phases, not diff conditions — skip here
+		if (event === "post-sdd-phase") {
+			continue;
+		}
+
+		// Evaluate path and line conditions using combine mode
+		const combine = w.combine ?? "or";
+		const pathMatches =
+			w.pathGlobs && w.pathGlobs.length > 0
+				? matchPathGlobs(diff.changedPaths, w.pathGlobs)
+				: false;
+		const lineMatches =
+			w.minDiffLines !== undefined && w.minDiffLines > 0
+				? diff.changedLines >= w.minDiffLines
+				: false;
+
+		const hasPathCondition = w.pathGlobs !== undefined && w.pathGlobs.length > 0;
+		const hasLineCondition = w.minDiffLines !== undefined && w.minDiffLines > 0;
+
+		let fires = false;
+		if (combine === "and") {
+			// Both conditions must hold (only when both are specified)
+			if (hasPathCondition && hasLineCondition) {
+				fires = pathMatches && lineMatches;
+			} else if (hasPathCondition) {
+				fires = pathMatches;
+			} else if (hasLineCondition) {
+				fires = lineMatches;
+			}
+		} else {
+			// "or" or "" — any condition firing is enough
+			fires = pathMatches || lineMatches;
+		}
+
+		if (fires) {
+			return { run: binding.run, mode: binding.mode, reason: binding.reason };
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Evaluates a post-sdd-phase trigger for a specific SDD phase name.
+ * Returns `{ run, mode, reason }` if a binding matches, or `null`.
+ */
+export function evaluatePostSddPhaseEvent(
+	phase: string,
+): { run: string[]; mode: TriggerMode; reason: string } | null {
+	for (const binding of DEFAULT_RULE_SET.bindings) {
+		if (binding.on !== "post-sdd-phase") continue;
+		const w = binding.when;
+		if (w.phases && w.phases.includes(phase)) {
+			return { run: binding.run, mode: binding.mode, reason: binding.reason };
+		}
+	}
+	return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/tests/review-gate.test.ts

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+
+const { classifyReviewEvent, parseNumstat } = __testing;
+
+// ---------------------------------------------------------------------------
+// classifyReviewEvent — command → TriggerEvent classification
+// ---------------------------------------------------------------------------
+
+test("classifyReviewEvent: git commit → pre-commit", () => {
+	assert.equal(classifyReviewEvent("git commit -m 'fix: stuff'"), "pre-commit");
+});
+
+test("classifyReviewEvent: git commit --amend → pre-commit", () => {
+	assert.equal(classifyReviewEvent("git commit --amend --no-edit"), "pre-commit");
+});
+
+test("classifyReviewEvent: git push → pre-push", () => {
+	assert.equal(classifyReviewEvent("git push origin main"), "pre-push");
+});
+
+test("classifyReviewEvent: git push with flags → pre-push", () => {
+	assert.equal(classifyReviewEvent("git push -u origin feat/my-feature"), "pre-push");
+});
+
+test("classifyReviewEvent: gh pr create → pre-pr", () => {
+	assert.equal(classifyReviewEvent("gh pr create --title 'My PR' --body 'desc'"), "pre-pr");
+});
+
+test("classifyReviewEvent: gh pr create with flags → pre-pr", () => {
+	assert.equal(classifyReviewEvent("gh pr create --draft"), "pre-pr");
+});
+
+test("classifyReviewEvent: unrelated command → null", () => {
+	assert.equal(classifyReviewEvent("npm install"), null);
+});
+
+test("classifyReviewEvent: echo hello → null", () => {
+	assert.equal(classifyReviewEvent("echo hello"), null);
+});
+
+test("classifyReviewEvent: git status → null", () => {
+	assert.equal(classifyReviewEvent("git status"), null);
+});
+
+test("classifyReviewEvent: git log → null", () => {
+	assert.equal(classifyReviewEvent("git log --oneline -5"), null);
+});
+
+// ---------------------------------------------------------------------------
+// parseNumstat — parses git diff --numstat output
+// ---------------------------------------------------------------------------
+
+test("parseNumstat: empty string → zero lines, no paths", () => {
+	const result = parseNumstat("");
+	assert.equal(result.changedLines, 0);
+	assert.deepEqual(result.changedPaths, []);
+});
+
+test("parseNumstat: single line normal file", () => {
+	const result = parseNumstat("5\t3\tsrc/foo.ts\n");
+	assert.equal(result.changedLines, 8);
+	assert.deepEqual(result.changedPaths, ["src/foo.ts"]);
+});
+
+test("parseNumstat: multiple lines", () => {
+	const result = parseNumstat("10\t2\tsrc/a.ts\n3\t1\tsrc/b.ts\n");
+	assert.equal(result.changedLines, 16);
+	assert.deepEqual(result.changedPaths, ["src/a.ts", "src/b.ts"]);
+});
+
+test("parseNumstat: binary row (- -) counts as 0 changed lines", () => {
+	const result = parseNumstat("-\t-\tassets/image.png\n");
+	assert.equal(result.changedLines, 0);
+	assert.deepEqual(result.changedPaths, ["assets/image.png"]);
+});
+
+test("parseNumstat: mixed normal and binary rows", () => {
+	const result = parseNumstat("5\t2\tsrc/main.ts\n-\t-\tassets/logo.png\n1\t0\tsrc/util.ts\n");
+	assert.equal(result.changedLines, 8);
+	assert.deepEqual(result.changedPaths, ["src/main.ts", "assets/logo.png", "src/util.ts"]);
+});
+
+test("parseNumstat: whitespace-only input → zero", () => {
+	const result = parseNumstat("   \n   \n");
+	assert.equal(result.changedLines, 0);
+	assert.deepEqual(result.changedPaths, []);
+});
+
+// ---------------------------------------------------------------------------
+// FIX 3: parseNumstat distinguishes empty-but-valid from git error (null)
+// ---------------------------------------------------------------------------
+
+test("parseNumstat: empty numstat output returns zero diff object, not null", () => {
+	// Empty staging area / no changes: git succeeds but prints nothing.
+	// Must return a valid ChangedDiff so advisory bindings still fire, not null.
+	const result = parseNumstat("");
+	assert.ok(result !== null, "parseNumstat should return a ChangedDiff object, not null");
+	assert.equal(result.changedLines, 0);
+	assert.deepEqual(result.changedPaths, []);
+});

package/tests/review-triggers.test.ts

@@ -0,0 +1,382 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	DEFAULT_RULE_SET,
+	KNOWN_AGENTS,
+	LARGE_CHANGED_LINE_THRESHOLD,
+	evaluateEvent,
+	matchPathGlobs,
+	validateTriggerRuleSet,
+	type ChangedDiff,
+	type TriggerBinding,
+	type TriggerRuleSet,
+} from "../lib/review-triggers.ts";
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — accepts DEFAULT_RULE_SET
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: DEFAULT_RULE_SET is valid", () => {
+	assert.doesNotThrow(() => validateTriggerRuleSet(DEFAULT_RULE_SET));
+});
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — rejects negative minDiffLines
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: rejects negative minDiffLines", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-pr",
+				when: { minDiffLines: -1 },
+				run: ["review-risk"],
+				mode: "strong",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /MinDiffLines/);
+});
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — rejects 4R fan-out on pre-commit/pre-push with always
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: rejects 4R fan-out on pre-commit with always:true", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-commit",
+				when: { always: true },
+				run: [
+					"review-risk",
+					"review-readability",
+					"review-reliability",
+					"review-resilience",
+				],
+				mode: "strong",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /4R fan-out|spec G/i);
+});
+
+test("validateTriggerRuleSet: rejects 4R fan-out on pre-push with always:true", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-push",
+				when: { always: true },
+				run: [
+					"review-risk",
+					"review-readability",
+					"review-reliability",
+					"review-resilience",
+				],
+				mode: "strong",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /4R fan-out|spec G/i);
+});
+
+test("validateTriggerRuleSet: allows 4R fan-out on pre-pr (not everyday event)", () => {
+	const ok: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-pr",
+				when: { minDiffLines: 400, combine: "or" },
+				run: [
+					"review-risk",
+					"review-readability",
+					"review-reliability",
+					"review-resilience",
+				],
+				mode: "strong",
+				reason: "test",
+			},
+		],
+	};
+	assert.doesNotThrow(() => validateTriggerRuleSet(ok));
+});
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — rejects unknown agent
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: rejects unknown agent in run", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-commit",
+				when: { always: true },
+				run: ["not-a-real-agent"],
+				mode: "advisory",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /unknown.*agent|agent.*unknown/i);
+});
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — rejects empty run
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: rejects empty run array", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-commit",
+				when: { always: true },
+				run: [],
+				mode: "advisory",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /run.*empty|empty.*run/i);
+});
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — rejects phases on non-post-sdd-phase event
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: rejects phases field on pre-commit event", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-commit",
+				when: { phases: ["design"] },
+				run: ["judgment-day"],
+				mode: "strong",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /phases.*post-sdd-phase|post-sdd-phase.*phases/i);
+});
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — rejects empty-slice When
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: rejects When with no conditions set", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-commit",
+				when: {},
+				run: ["review-readability"],
+				mode: "advisory",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /at least one condition/i);
+});
+
+// ---------------------------------------------------------------------------
+// validateTriggerRuleSet — rejects invalid combine value
+// ---------------------------------------------------------------------------
+
+test("validateTriggerRuleSet: rejects invalid combine value", () => {
+	const bad: TriggerRuleSet = {
+		bindings: [
+			{
+				on: "pre-pr",
+				when: { pathGlobs: ["**/auth/**"], combine: "xor" as "" },
+				run: ["review-risk"],
+				mode: "strong",
+				reason: "test",
+			},
+		],
+	};
+	assert.throws(() => validateTriggerRuleSet(bad), /combine/i);
+});
+
+// ---------------------------------------------------------------------------
+// KNOWN_AGENTS — closed set coverage
+// ---------------------------------------------------------------------------
+
+test("KNOWN_AGENTS contains all 4R agents and SDD phases", () => {
+	const required = [
+		"review-risk",
+		"review-readability",
+		"review-reliability",
+		"review-resilience",
+		"judgment-day",
+		"sdd-explore",
+		"sdd-propose",
+		"sdd-spec",
+		"sdd-design",
+		"sdd-tasks",
+		"sdd-apply",
+		"sdd-verify",
+		"sdd-archive",
+	];
+	for (const agent of required) {
+		assert.ok(KNOWN_AGENTS.includes(agent), `Expected KNOWN_AGENTS to include "${agent}"`);
+	}
+});
+
+// ---------------------------------------------------------------------------
+// LARGE_CHANGED_LINE_THRESHOLD
+// ---------------------------------------------------------------------------
+
+test("LARGE_CHANGED_LINE_THRESHOLD is 400", () => {
+	assert.equal(LARGE_CHANGED_LINE_THRESHOLD, 400);
+});
+
+// ---------------------------------------------------------------------------
+// matchPathGlobs — positive cases
+// ---------------------------------------------------------------------------
+
+test("matchPathGlobs: src/auth/login.ts matches **/auth/**", () => {
+	assert.ok(matchPathGlobs(["src/auth/login.ts"], ["**/auth/**"]));
+});
+
+test("matchPathGlobs: src/security/handler.ts matches **/security/**", () => {
+	assert.ok(matchPathGlobs(["src/security/handler.ts"], ["**/security/**"]));
+});
+
+test("matchPathGlobs: src/payments/gateway.ts matches **/payments/**", () => {
+	assert.ok(matchPathGlobs(["src/payments/gateway.ts"], ["**/payments/**"]));
+});
+
+test("matchPathGlobs: src/update/updater.ts matches **/update/**", () => {
+	assert.ok(matchPathGlobs(["src/update/updater.ts"], ["**/update/**"]));
+});
+
+test("matchPathGlobs: deep path matches **/auth/**", () => {
+	assert.ok(matchPathGlobs(["a/b/c/auth/deep/file.ts"], ["**/auth/**"]));
+});
+
+test("matchPathGlobs: mixed paths — only one matches — returns true", () => {
+	assert.ok(matchPathGlobs(["src/utils/helper.ts", "src/auth/middleware.ts"], ["**/auth/**"]));
+});
+
+// ---------------------------------------------------------------------------
+// matchPathGlobs — negative cases
+// ---------------------------------------------------------------------------
+
+test("matchPathGlobs: src/utils/helper.ts does NOT match **/auth/**", () => {
+	assert.equal(matchPathGlobs(["src/utils/helper.ts"], ["**/auth/**"]), false);
+});
+
+test("matchPathGlobs: empty paths returns false", () => {
+	assert.equal(matchPathGlobs([], ["**/auth/**"]), false);
+});
+
+test("matchPathGlobs: path without auth segment does not match auth glob", () => {
+	assert.equal(matchPathGlobs(["src/authutils/helper.ts"], ["**/auth/**"]), false);
+});
+
+// ---------------------------------------------------------------------------
+// matchPathGlobs — root-level directory matching (FIX 1: leading **/ zero segments)
+// ---------------------------------------------------------------------------
+
+test("matchPathGlobs: auth/login.ts (root-level) matches **/auth/**", () => {
+	assert.ok(matchPathGlobs(["auth/login.ts"], ["**/auth/**"]));
+});
+
+test("matchPathGlobs: payments/stripe.ts (root-level) matches **/payments/**", () => {
+	assert.ok(matchPathGlobs(["payments/stripe.ts"], ["**/payments/**"]));
+});
+
+test("matchPathGlobs: security/config.ts (root-level) matches **/security/**", () => {
+	assert.ok(matchPathGlobs(["security/config.ts"], ["**/security/**"]));
+});
+
+test("matchPathGlobs: authutils/helper.ts (root-level) does NOT match **/auth/** (segment boundary required)", () => {
+	assert.equal(matchPathGlobs(["authutils/helper.ts"], ["**/auth/**"]), false);
+});
+
+// ---------------------------------------------------------------------------
+// evaluateEvent — pre-commit: always fires advisory readability
+// ---------------------------------------------------------------------------
+
+test("evaluateEvent: pre-commit always fires advisory review-readability", () => {
+	const diff: ChangedDiff = { changedPaths: [], changedLines: 0 };
+	const result = evaluateEvent("pre-commit", diff);
+	assert.ok(result !== null, "Expected a result for pre-commit");
+	assert.equal(result!.mode, "advisory");
+	assert.ok(result!.run.includes("review-readability"));
+});
+
+test("evaluateEvent: pre-push always fires advisory review-readability", () => {
+	const diff: ChangedDiff = { changedPaths: [], changedLines: 0 };
+	const result = evaluateEvent("pre-push", diff);
+	assert.ok(result !== null, "Expected a result for pre-push");
+	assert.equal(result!.mode, "advisory");
+	assert.ok(result!.run.includes("review-readability"));
+});
+
+// ---------------------------------------------------------------------------
+// evaluateEvent — pre-pr: fires strong 4R when path matches hot globs
+// ---------------------------------------------------------------------------
+
+test("evaluateEvent: pre-pr fires strong 4R when auth path matches", () => {
+	const diff: ChangedDiff = {
+		changedPaths: ["src/auth/middleware.ts"],
+		changedLines: 10,
+	};
+	const result = evaluateEvent("pre-pr", diff);
+	assert.ok(result !== null, "Expected a result for pre-pr on auth path");
+	assert.equal(result!.mode, "strong");
+	assert.ok(result!.run.includes("review-risk"));
+	assert.ok(result!.run.includes("review-readability"));
+	assert.ok(result!.run.includes("review-reliability"));
+	assert.ok(result!.run.includes("review-resilience"));
+});
+
+// ---------------------------------------------------------------------------
+// evaluateEvent — pre-pr: fires strong 4R when changedLines >= 400
+// ---------------------------------------------------------------------------
+
+test("evaluateEvent: pre-pr fires strong 4R when changedLines >= 400", () => {
+	const diff: ChangedDiff = {
+		changedPaths: ["src/utils/helper.ts"],
+		changedLines: 400,
+	};
+	const result = evaluateEvent("pre-pr", diff);
+	assert.ok(result !== null, "Expected a result for pre-pr on large diff");
+	assert.equal(result!.mode, "strong");
+});
+
+test("evaluateEvent: pre-pr threshold boundary — 400 fires", () => {
+	const diff: ChangedDiff = { changedPaths: [], changedLines: 400 };
+	const result = evaluateEvent("pre-pr", diff);
+	assert.ok(result !== null, "Expected a result at boundary 400");
+});
+
+test("evaluateEvent: pre-pr threshold boundary — 399 does NOT fire", () => {
+	const diff: ChangedDiff = { changedPaths: [], changedLines: 399 };
+	const result = evaluateEvent("pre-pr", diff);
+	assert.equal(result, null, "Expected null at 399 with no hot paths");
+});
+
+// ---------------------------------------------------------------------------
+// evaluateEvent — pre-pr: does NOT fire when neither condition holds
+// ---------------------------------------------------------------------------
+
+test("evaluateEvent: pre-pr does NOT fire with 0 lines and no hot paths", () => {
+	const diff: ChangedDiff = {
+		changedPaths: ["src/utils/helper.ts"],
+		changedLines: 0,
+	};
+	const result = evaluateEvent("pre-pr", diff);
+	assert.equal(result, null);
+});
+
+test("evaluateEvent: pre-pr does NOT fire with 50 lines and no hot paths", () => {
+	const diff: ChangedDiff = {
+		changedPaths: ["src/components/Button.tsx"],
+		changedLines: 50,
+	};
+	const result = evaluateEvent("pre-pr", diff);
+	assert.equal(result, null);
+});