gentle-pi 0.4.5 → 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

@@ -27,7 +27,7 @@ Keep synthesis short by default: decision, outcome, next action. Expand only whe
 
 ## Language Boundary
 
-User-facing conversation should stay in the user's language and follow the currently selected persona mode. In `gentleman` mode, Spanish uses natural Rioplatense voseo. In `neutral` mode, Spanish stays neutral/professional without regional expression.
+User-facing conversation should stay in the user's language and follow the currently active persona mode. The active mode is stated in the `Current persona mode:` line in the identity/harness section of this system prompt — always honor it for language style.
 
 Subagent-facing prompts should be written in English by default, even when the user speaks Spanish. Translate the user's request into concise English before delegation. This keeps token usage lower and gives built-in/project subagents a consistent operating language without changing the user-facing persona.
 
@@ -271,6 +271,15 @@ When Engram or another callable memory package is available, the parent owns mem
 - SDD artifact keys: in memory/hybrid mode, phase artifacts should use stable topic keys such as `sdd/<change>/proposal`, `sdd/<change>/spec`, `sdd/<change>/design`, `sdd/<change>/tasks`, `sdd/<change>/apply-progress`, and `sdd/<change>/verify-report`.
 - If memory tools are unavailable, do not pretend persistence exists; return artifacts inline and/or write OpenSpec files.
 
+Memory lifecycle rule (when Engram exposes lifecycle metadata/tooling):
+
+- At session start or before architecture-sensitive work, call `mem_review` with action `list` for the current project when the tool is available.
+- If `mem_review` is unavailable, do not fail the task. Continue with normal `mem_context`/`mem_search`, and still apply lifecycle metadata from any returned observations when present.
+- `active` memories may be used normally.
+- `needs_review` memories are stale context, not trusted facts.
+- When a retrieved memory is marked `needs_review`, surface that stale context to the user and verify it against current evidence before relying on it.
+- Do NOT call `mem_review` with action `mark_reviewed` automatically. Only call `mark_reviewed` after explicit user confirmation or through a dedicated memory maintenance command.
+
 ## Execution Mode
 
 Use the session's SDD preflight choice:
@@ -375,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");
@@ -149,6 +156,7 @@ const NEUTRAL_PERSONA_PROMPT = `Persona:
 - Be direct, technical, concise, warm, and professional.
 - Always respond in the same language the user writes in.
 - Do not use slang or regional expressions.
+- When the user writes Spanish, use neutral/professional Spanish. Do NOT use voseo (vos tenés, vos querés, hacé, andá, etc.) or any regional conjugations.
 - Act as a senior architect and teacher: concepts before code, no shortcuts.
 - Treat AI as a tool directed by the human; never present yourself as a default chatbot.
 - Push back when the user asks for code without enough context or understanding.
@@ -157,7 +165,14 @@ const NEUTRAL_PERSONA_PROMPT = `Persona:
 function buildGentlePrompt(persona: PersonaMode): string {
 	const personaPrompt =
 		persona === "neutral" ? NEUTRAL_PERSONA_PROMPT : GENTLEMAN_PERSONA_PROMPT;
+	const languageBoundary =
+		persona === "neutral"
+			? "Language: neutral/professional Spanish when the user writes Spanish. Do NOT use voseo or Rioplatense regional expressions."
+			: "Language: natural Rioplatense Spanish with voseo when the user writes Spanish.";
 	return `## el Gentleman Identity and Harness
+
+Current persona mode: ${persona}
+
 You are el Gentleman: a Pi-specific coding-agent harness for controlled development work.
 
 Identity contract:
@@ -169,6 +184,8 @@ Identity contract:
 
 ${personaPrompt}
 
+${languageBoundary}
+
 Harness principles:
 - el Gentleman is not prompt engineering. It is runtime discipline around powerful agents.
 - Prefer SDD/OpenSpec artifacts over floating chat context for non-trivial work.
@@ -182,11 +199,19 @@ Harness principles:
 ${getOrchestratorPrompt()}`;
 }
 
+// Matches `git [global-flags] push` — tolerates flags like -C /repo or --work-tree=/tmp
+// between `git` and the subcommand. Short flags may be followed by a separate value token.
+const GIT_GLOBAL_FLAGS_SRC = String.raw`(?:\s+--?\S+(?:\s+[^-\s]\S*)?)* `;
+const GIT_PUSH_RE = new RegExp(String.raw`\bgit${GIT_GLOBAL_FLAGS_SRC}push\b`);
+
 const DENIED_BASH_PATTERNS: RegExp[] = [
-	/\brm\s+-rf\s+(?:\/|~|\$HOME|\.\.?)(?:\s|$)/,
+	// Block rm -rf targeting /, ~ or ~/subdir, $HOME or $HOME/subdir, .. or .
+	/\brm\s+-rf\s+(?:\/(?:\s|$)|~(?:\/|\s|$)|[$]HOME(?:\/|\s|$)|\.\.?(?:\s|$))/,
 	/\bgit\s+reset\s+--hard\b/,
 	/\bgit\s+clean\b(?=[^\n]*(?:-[^\n]*f|--force))(?=[^\n]*(?:-[^\n]*d|--directories))/,
-	/\bgit\s+push\b(?=[^\n]*\s--force(?:-with-lease)?\b)/,
+	// Force-push deny: tolerates git global flags (e.g. -C /repo) before the subcommand
+	new RegExp(String.raw`\bgit${GIT_GLOBAL_FLAGS_SRC}push\b(?=[^\n]*\s--force(?:-with-lease)?\b)`),
+	new RegExp(String.raw`\bgit${GIT_GLOBAL_FLAGS_SRC}push\b(?=[^\n]*\s-[^\s-]*f)`),
 	/\bchmod\s+-R\s+777\b/,
 	/\bchown\s+-R\b/,
 ];
@@ -194,11 +219,189 @@ const DENIED_BASH_PATTERNS: RegExp[] = [
 const CONFIRM_BASH_PATTERNS: RegExp[] = [
 	/\bgit\s+push\b/,
 	/\bgit\s+rebase\b/,
-	/\bgit\s+branch\s+-D\b/,
+	/\bgit\s+branch\s+(?:-[a-zA-Z]*D[a-zA-Z]*|-[a-zA-Z]*d[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*d[a-zA-Z]*|--delete\b[^\n]*--force\b|--force\b[^\n]*--delete\b)/,
 	/\bnpm\s+publish\b/,
 	/\bpi\s+remove\b/,
 ];
 
+// ---------------------------------------------------------------------------
+// Autonomous guard — runtime guardrails config
+// ---------------------------------------------------------------------------
+
+const GUARD_ACTION = {
+	ALLOW: "allow",
+	CONFIRM: "confirm",
+	BLOCK: "block",
+} as const;
+
+type GuardAction = (typeof GUARD_ACTION)[keyof typeof GUARD_ACTION];
+type GuardClassification = GuardAction | "not-guarded";
+
+const GUARDED_COMMAND_KEY = {
+	GIT_PUSH: "gitPush",
+	GIT_REBASE: "gitRebase",
+	GIT_BRANCH_DELETE_FORCE: "gitBranchDeleteForce",
+	NPM_PUBLISH: "npmPublish",
+	PI_REMOVE: "piRemove",
+} as const;
+
+type GuardedCommandKey = (typeof GUARDED_COMMAND_KEY)[keyof typeof GUARDED_COMMAND_KEY];
+
+type GuardedCommandsConfig = Partial<Record<GuardedCommandKey, GuardAction>>;
+
+interface RuntimeGuardrailsConfig {
+	autonomousMode: boolean;
+	guardedCommands: GuardedCommandsConfig;
+}
+
+interface LoadGuardrailsOptions {
+	/** Override the config home directory (used in tests to avoid touching ~/.pi). */
+	gentlePiConfigHome?: string;
+}
+
+const GUARDED_KEY_PATTERNS: Record<GuardedCommandKey, RegExp> = {
+	gitPush: GIT_PUSH_RE,
+	gitRebase: /\bgit\s+rebase\b/,
+	gitBranchDeleteForce: /\bgit\s+branch\s+(?:-[a-zA-Z]*D[a-zA-Z]*|-[a-zA-Z]*d[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*d[a-zA-Z]*|--delete\b[^\n]*--force\b|--force\b[^\n]*--delete\b)/,
+	npmPublish: /\bnpm\s+publish\b/,
+	piRemove: /\bpi\s+remove\b/,
+};
+
+const AUTONOMOUS_DEFAULT_ACTIONS: Record<GuardedCommandKey, GuardAction> = {
+	gitPush: "allow",
+	gitRebase: "confirm",
+	gitBranchDeleteForce: "confirm",
+	npmPublish: "block",
+	piRemove: "confirm",
+};
+
+const SAFE_GUARDRAILS_CONFIG: RuntimeGuardrailsConfig = {
+	autonomousMode: false,
+	guardedCommands: {},
+};
+
+/**
+ * Classify a shell command under the runtime guard policy.
+ *
+ * Ordering (non-negotiable):
+ *   1. Hard-deny patterns → "block" (always, cannot be overridden by config)
+ *   2. If autonomousMode is false → mirror the legacy CONFIRM_BASH_PATTERNS result
+ *   3. If autonomousMode is true → use configured GuardAction for the matched key
+ *      (applying AUTONOMOUS_DEFAULT_ACTIONS for any key not set in guardedCommands)
+ *   4. No match → "not-guarded"
+ */
+function classifyGuardedCommand(
+	command: string,
+	config: RuntimeGuardrailsConfig,
+): GuardClassification {
+	// Step 1: hard-deny always wins, regardless of any config
+	for (const pattern of DENIED_BASH_PATTERNS) {
+		if (pattern.test(command)) return "block";
+	}
+
+	// Step 2 & 3: find which guarded key (if any) this command matches
+	for (const [key, pattern] of Object.entries(GUARDED_KEY_PATTERNS) as [GuardedCommandKey, RegExp][]) {
+		if (!pattern.test(command)) continue;
+
+		// Matched a guarded key
+		if (!config.autonomousMode) {
+			// Legacy behavior: any match → confirm
+			return "confirm";
+		}
+
+		// Autonomous mode: use configured action, fall back to sensible defaults
+		const configuredAction = config.guardedCommands[key];
+		return configuredAction ?? AUTONOMOUS_DEFAULT_ACTIONS[key];
+	}
+
+	return "not-guarded";
+}
+
+function parseGuardrailsConfigFile(
+	raw: string,
+): RuntimeGuardrailsConfig | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (!isRecord(parsed)) return undefined;
+
+	const autonomousMode = parsed.autonomousMode === true;
+
+	const rawCommands = isRecord(parsed.guardedCommands) ? parsed.guardedCommands : {};
+	const guardedCommands: GuardedCommandsConfig = {};
+	const validActions = new Set<string>(["allow", "confirm", "block"]);
+	for (const [key, value] of Object.entries(rawCommands)) {
+		if (
+			typeof value === "string" &&
+			validActions.has(value) &&
+			Object.values(GUARDED_COMMAND_KEY).includes(key as GuardedCommandKey)
+		) {
+			guardedCommands[key as GuardedCommandKey] = value as GuardAction;
+		}
+	}
+
+	return { autonomousMode, guardedCommands };
+}
+
+/**
+ * Load the runtime guardrails config.
+ *
+ * Resolution order (project overrides global):
+ *   1. Check GENTLE_PI_AUTONOMOUS_MODE env var — if "1", forces autonomousMode=true
+ *      and uses default guarded command actions.
+ *   2. Read global config from ${gentlePiConfigHome}/runtime-guardrails.json
+ *   3. Read project config from ${cwd}/.pi/gentle-ai/runtime-guardrails.json
+ *      (project values are merged on top of global)
+ *   4. Any parse/read error anywhere → fail safe (return SAFE_GUARDRAILS_CONFIG)
+ */
+function loadRuntimeGuardrailsConfig(
+	cwd: string,
+	options: LoadGuardrailsOptions = {},
+): RuntimeGuardrailsConfig {
+	try {
+		// Env var override: forces autonomous mode with default actions
+		if (process.env.GENTLE_PI_AUTONOMOUS_MODE === "1") {
+			return { autonomousMode: true, guardedCommands: {} };
+		}
+
+		const configHome = options.gentlePiConfigHome ?? gentleAiConfigHome();
+		const globalConfigPath = join(configHome, "runtime-guardrails.json");
+		const projectConfigPath = join(cwd, ".pi", "gentle-ai", "runtime-guardrails.json");
+
+		let merged: RuntimeGuardrailsConfig = { autonomousMode: false, guardedCommands: {} };
+
+		if (existsSync(globalConfigPath)) {
+			const globalParsed = parseGuardrailsConfigFile(
+				readFileSync(globalConfigPath, "utf8"),
+			);
+			if (!globalParsed) return SAFE_GUARDRAILS_CONFIG;
+			merged = globalParsed;
+		}
+
+		if (existsSync(projectConfigPath)) {
+			const projectParsed = parseGuardrailsConfigFile(
+				readFileSync(projectConfigPath, "utf8"),
+			);
+			if (!projectParsed) return SAFE_GUARDRAILS_CONFIG;
+			// Project values fully override global values
+			merged = {
+				autonomousMode: projectParsed.autonomousMode,
+				guardedCommands: {
+					...merged.guardedCommands,
+					...projectParsed.guardedCommands,
+				},
+			};
+		}
+
+		return merged;
+	} catch {
+		return SAFE_GUARDRAILS_CONFIG;
+	}
+}
+
 const PATH_GUARDED_TOOL_NAMES = new Set(["read", "write", "edit"]);
 const PATH_INPUT_KEYS = new Set([
 	"path",
@@ -329,25 +532,6 @@ function sddPhaseFromAgentStartEvent(event: unknown): SddPhase | undefined {
 	return undefined;
 }
 
-function evaluateDeniedCommand(
-	command: string,
-): ToolCallEventResult | undefined {
-	for (const pattern of DENIED_BASH_PATTERNS) {
-		if (pattern.test(command)) {
-			return {
-				block: true,
-				reason:
-					"Gentle AI safety policy blocked a destructive shell command. Ask the user for an explicit safer plan.",
-			};
-		}
-	}
-	return undefined;
-}
-
-function commandRequiresConfirmation(command: string): boolean {
-	return CONFIRM_BASH_PATTERNS.some((pattern) => pattern.test(command));
-}
-
 function normalizePolicyPath(value: string): string {
 	return value.trim().replace(/^~(?=\/|$)/, homedir()).replace(/\\/g, "/").toLowerCase();
 }
@@ -408,9 +592,23 @@ async function confirmCommand(
 	command: string,
 	ctx: ExtensionContext,
 ): Promise<ToolCallEventResult | undefined> {
-	const denied = evaluateDeniedCommand(command);
-	if (denied) return denied;
-	if (!commandRequiresConfirmation(command)) return undefined;
+	const guardrailsConfig = loadRuntimeGuardrailsConfig(ctx.cwd);
+	const classification = classifyGuardedCommand(command, guardrailsConfig);
+
+	if (classification === "block") {
+		return {
+			block: true,
+			reason:
+				"Gentle AI safety policy blocked a destructive shell command. Ask the user for an explicit safer plan.",
+		};
+	}
+
+	if (classification === "not-guarded") return undefined;
+
+	// classification is "allow" or "confirm" from this point on
+	if (classification === "allow") return undefined;
+
+	// classification === "confirm"
 	if (!ctx.hasUI) {
 		return {
 			block: true,
@@ -1569,10 +1767,148 @@ 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,
 	listAgentsFromDirAsync,
+	classifyGuardedCommand,
+	loadRuntimeGuardrailsConfig,
+	buildGentlePrompt,
+	classifyReviewEvent,
+	parseNumstat,
 };
 
 export default function gentleAi(pi: ExtensionAPI): void {
@@ -1656,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);
 	});