gentle-pi 0.10.6 → 0.10.7

package/README.md

@@ -125,17 +125,29 @@ The goal is not ceremony. The goal is to avoid accidental chaos. Once a task sto
 | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
 | Reading 4+ files to understand a flow                                                                                       | Launch `scout`, `context-builder`, or the closest read-only mapping subagent. |
 | Touching 2+ non-trivial code files                                                                                          | Delegate one writer; do not continue inline unless delegation is unavailable. |
-| Commit, push, or PR after code changes                                                                                      | Run a fresh-context `reviewer` unless the diff is trivial docs/text.          |
-| Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue                                                  | Stop and run a fresh audit reviewer before continuing.                        |
+| Commit, push, or PR after code changes                                                                                      | Select a fresh-context review lens unless the diff is trivial docs/text.      |
+| Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue                                                  | Stop and run a fresh audit through the relevant review lens before continuing. |
 | Long monolithic session with accumulating complexity, roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits | Pause and delegate the remaining work, or stop and explain the exact blocker. |
 
 The intended balanced loop for a bounded bugfix is:
 
 ```text
-parent git/status + clarify → scout when context-heavy → one worker writes → fresh reviewer audits → parent validates and reports
+parent git/status + clarify → scout when context-heavy → one worker writes → selected review lens audits → parent validates and reports
 ```
 
-Fresh reviewers are intentionally not token-saving devices; they buy independent judgment. `scout`/`context-builder` save parent context by compressing broad exploration. `worker` preserves a single writer thread.
+Fresh review lenses are intentionally not token-saving devices; they buy independent judgment. `scout`/`context-builder` save parent context by compressing broad exploration. `worker` preserves a single writer thread.
+
+`reviewer` is not an installed subagent name. It is a routing intent. Select the concrete lens by risk profile:
+
+| Context | Review lens |
+| --- | --- |
+| Clear naming, structure, maintainability, small refactors | `review-readability` |
+| Behavior, state, tests, determinism, regressions | `review-reliability` |
+| Shell/process integration, partial failures, recovery, degraded dependencies | `review-resilience` |
+| Security, permissions, data exposure/loss, architecture, dependencies | `review-risk` |
+| Large PR, hot path, or >400 changed lines | Full 4R: `review-risk`, `review-resilience`, `review-readability`, `review-reliability` |
+
+If multiple rows match, run the narrow set that covers the risk. For example, shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.
 
 ## SDD/OpenSpec flow
 

package/assets/orchestrator.md

@@ -88,7 +88,7 @@ If `subagent_*` tools are unavailable, fall back to Pi's native `Agent` tool or
 
 ### Pi Subagent Model Routing
 
-For generic Pi subagents (`delegate`, `worker`, `scout`, `reviewer`, `context-builder`, `oracle`, `planner`, `researcher`, or other non-SDD agents), do not pass the `model` parameter by default. Let `pi-subagents` resolve model and thinking from `.pi/settings.json`, `.pi/subagents.json`, global subagent config, and runtime defaults.
+For generic Pi subagents (`delegate`, `worker`, `scout`, review lens agents, `context-builder`, `oracle`, `planner`, `researcher`, or other non-SDD agents), do not pass the `model` parameter by default. Let `pi-subagents` resolve model and thinking from `.pi/settings.json`, `.pi/subagents.json`, global subagent config, and runtime defaults.
 
 SDD model assignment tables apply only to SDD/Judgment-Day phase agents. They must not be used for generic Pi delegation.
 
@@ -97,7 +97,7 @@ Only pass `model` for generic subagents when the user explicitly requests a mode
 Default balanced pattern for bounded implementation:
 
 ```text
-parent clarifies and checks git → scout/context-builder when context-heavy → one worker writes → fresh reviewer audits diff → parent validates and reports
+parent clarifies and checks git → scout/context-builder when context-heavy → one worker writes → selected review lens audits diff → parent validates and reports
 ```
 
 Do not make every task SDD. Do make non-trivial tasks multi-agent at the narrowest useful point.
@@ -139,10 +139,10 @@ These are parent-orchestrator stop rules. Once any trigger fires, the parent MUS
 
 1. **4-file rule**: if understanding requires reading 4+ files, launch `scout`, `context-builder`, or the closest read-only mapping subagent with fresh context and a narrow mapping task. State the fallback agent/runtime if the preferred one is unavailable.
 2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer; inline writing is allowed only for trivial/mechanical edits or when the parent explicitly records why no delegation runtime is available. A fresh review still follows delegated implementation.
-3. **PR rule**: before commit/push/PR for code changes, run a fresh-context reviewer unless the diff is trivial docs/text-only.
-4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit reviewer before continuing.
+3. **PR rule**: before commit/push/PR for code changes, select a fresh-context review lens unless the diff is trivial docs/text-only.
+4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit through the relevant review lens before continuing.
 5. **Long-session rule**: if accumulating work is no longer clearly local — roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation — pause and delegate the remaining work instead of silently continuing monolithically.
-6. **Fresh review rule**: use fresh-context reviewer/audit subagents for adversarial review of diffs, conflicts, PR readiness, and incidents. Use continuity-oriented workers only for implementation work that needs inherited state.
+6. **Fresh review rule**: use fresh-context review lens subagents for adversarial review of diffs, conflicts, PR readiness, and incidents. Use continuity-oriented workers only for implementation work that needs inherited state.
 
 ### Cost and Context Balance
 
@@ -150,7 +150,7 @@ Prefer delegation when fresh context improves correctness more than token saving
 
 - Use `scout`/`context-builder` to compress broad repo exploration into a short handoff instead of loading many files into the parent.
 - Use a single `worker` for one writer thread; do not run parallel writers unless isolated worktrees are explicitly approved.
-- Use fresh `reviewer` agents after implementation, conflict resolution, or incidents because their value is independence from the parent's assumptions.
+- Use fresh concrete review lens agents after implementation, conflict resolution, or incidents because their value is independence from the parent's assumptions. Do not call a generic `reviewer` subagent; choose from `review-risk`, `review-reliability`, `review-resilience`, `review-readability`, or the full 4R set.
 - Use `outputMode: "file-only"` for large child reports and summarize only decisions, blockers, and paths in the parent thread.
 - Avoid delegation for truly local one-file fixes, quick state checks, and already-understood mechanical edits.
 
@@ -159,21 +159,35 @@ Prefer delegation when fresh context improves correctness more than token saving
 Bugfix with unfamiliar flow:
 
 ```text
-parent git/status + clarify → scout fresh maps flow/files → parent decides → worker fork implements + tests → reviewer fresh audits diff → parent validates
+parent git/status + clarify → scout fresh maps flow/files → parent decides → worker fork implements + tests → selected review lens audits diff → parent validates
 ```
 
 Conflict or dependency-marker cleanup:
 
 ```text
-parent reproduces/checks conflict → parent or worker resolves → reviewer fresh checks markers, package/lock consistency, and repo cleanliness → parent reports/pushes
+parent reproduces/checks conflict → parent or worker resolves → selected review lens checks markers, package/lock consistency, and repo cleanliness → parent reports/pushes
 ```
 
 After tooling/worktree incident:
 
 ```text
-stop writes → parent captures git status → reviewer fresh audits affected repos/worktrees with no edits → parent applies only confirmed recovery steps
+stop writes → parent captures git status → selected review lens audits affected repos/worktrees with no edits → parent applies only confirmed recovery steps
 ```
 
+### Review Lens Selection
+
+`reviewer` is an intent, not an installed subagent name. The parent must select concrete review agents by risk profile:
+
+| Context | Review lens |
+| --- | --- |
+| Clear naming, structure, maintainability, small refactors | `review-readability` |
+| Behavior, state, tests, determinism, regressions | `review-reliability` |
+| Shell/process integration, partial failures, recovery, degraded dependencies | `review-resilience` |
+| Security, permissions, data exposure/loss, architecture, dependencies | `review-risk` |
+| Large PR, hot path, or >400 changed lines | Full 4R: `review-risk`, `review-resilience`, `review-readability`, `review-reliability` |
+
+If multiple rows match, run the narrow set that covers the risk. Example: shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.
+
 ## SDD Workflow
 
 SDD phases:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.10.6",
+  "version": "0.10.7",
   "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/skills/gentle-ai/SKILL.md

@@ -18,7 +18,7 @@ When asked who or what you are, answer as el Gentleman: a Pi-specific coding-age
 - If tests exist, follow strict TDD: RED, GREEN, TRIANGULATE, REFACTOR, and record evidence.
 - Keep one parent session responsible for orchestration; child subagents should receive concrete phase work and must not spawn more subagents.
 - Parent-only delegation triggers apply after complexity appears: 4+ files for understanding, 2+ non-trivial files to write, commit/PR after code changes, tooling/worktree incidents, or long sessions with accumulating complexity.
-- As parent, prefer `scout`/`context-builder` for context-heavy exploration, one forked `worker` for implementation, and fresh-context `reviewer` agents for adversarial review before PRs and after incidents.
+- As parent, prefer `scout`/`context-builder` for context-heavy exploration, one forked `worker` for implementation, and fresh-context review lenses for adversarial review before PRs and after incidents. Do not call a generic `reviewer` subagent; select the concrete lens: `review-risk`, `review-reliability`, `review-resilience`, `review-readability`, or the full 4R set.
 - Keep writes single-threaded unless the user explicitly approves isolated parallel worktrees.
 - Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
 - Never claim persistent memory is available because of el Gentleman itself; memory is provided by separate packages/tools when active.
@@ -44,15 +44,29 @@ clarify → explore → proposal → spec → design → tasks → apply → ver
 For bounded implementation with subagents:
 
 ```text
-clarify → scout/context-builder when context-heavy → one worker → fresh reviewers → worker fixes → verify
+clarify → scout/context-builder when context-heavy → one worker → selected review lens(es) → worker fixes → verify
 ```
 
 Hard delegation triggers:
 
 - **4-file rule**: reading 4+ files to understand means delegate exploration.
 - **Multi-file write rule**: touching 2+ non-trivial files means use one worker or at least fresh review before completion.
-- **PR rule**: before commit/push/PR for code changes, run fresh review unless the diff is trivial docs/text.
-- **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, run fresh audit.
+- **PR rule**: before commit/push/PR for code changes, select a fresh review lens unless the diff is trivial docs/text.
+- **Incident rule**: after wrong cwd, accidental worktree/repo mutation, merge recovery, confusing test command, or environment workaround, run a fresh audit through the relevant review lens.
 - **Long-session rule**: after roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits with no delegation and accumulating complexity, pause and choose a subagent or justify not doing so.
 
+## Review Lens Selection
+
+Never request a subagent named `reviewer`; it is an intent, not an installed agent. Select concrete review agents by risk profile:
+
+| Context | Review lens |
+| --- | --- |
+| Clear naming, structure, maintainability, small refactors | `review-readability` |
+| Behavior, state, tests, determinism, regressions | `review-reliability` |
+| Shell/process integration, partial failures, recovery, degraded dependencies | `review-resilience` |
+| Security, permissions, data exposure/loss, architecture, dependencies | `review-risk` |
+| Large PR, hot path, or >400 changed lines | Full 4R: `review-risk`, `review-resilience`, `review-readability`, `review-reliability` |
+
+If multiple rows match, run the narrow set that covers the risk. Example: shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.
+
 The package ensures SDD agents and chains are available as global Pi runtime assets. Project-local SDD files are overrides/debug copies only. Use `/gentle-ai:install-sdd --force` only for recovery or intentional global refresh.

package/tests/gentle-ai.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
@@ -16,7 +16,7 @@ test("agent discovery skips skills directories", async (t) => {
 	const root = mkdtempSync(join(tmpdir(), "gentle-pi-agents-"));
 	t.after(() => rmSync(root, { recursive: true, force: true }));
 	const dotAgents = join(root, ".agents");
-	writeMarkdown(join(dotAgents, "reviewer.md"), "name: reviewer\n");
+	writeMarkdown(join(dotAgents, "review-risk.md"), "name: review-risk\n");
 	writeMarkdown(join(dotAgents, "team", "worker.md"), "name: worker\n");
 	writeMarkdown(join(dotAgents, "skills", "ai-sdk", "SKILL.md"), "name: ai-sdk\n");
 	writeMarkdown(
@@ -29,14 +29,40 @@ test("agent discovery skips skills directories", async (t) => {
 
 	assert.deepEqual(
 		syncAgents.map((agent) => agent.name),
-		["reviewer", "worker"],
+		["review-risk", "worker"],
 	);
 	assert.deepEqual(
 		asyncAgents.map((agent) => agent.name),
-		["reviewer", "worker"],
+		["review-risk", "worker"],
 	);
 });
 
+test("runtime guidance routes review intent to concrete lenses", () => {
+	const guidedFiles = [
+		"README.md",
+		"assets/orchestrator.md",
+		"skills/gentle-ai/SKILL.md",
+	];
+	const forbiddenGenericRoutes = [
+		/fresh-context `reviewer`/,
+		/fresh reviewer audits/,
+		/reviewer fresh audits/,
+		/run a fresh-context `reviewer`/,
+	];
+
+	for (const file of guidedFiles) {
+		const content = readFileSync(file, "utf8");
+		assert.match(content, /Review Lens Selection|review lens/);
+		assert.match(content, /review-risk/);
+		assert.match(content, /review-reliability/);
+		assert.match(content, /review-resilience/);
+		assert.match(content, /review-readability/);
+		for (const forbidden of forbiddenGenericRoutes) {
+			assert.doesNotMatch(content, forbidden, `${file} must not route to generic reviewer`);
+		}
+	}
+});
+
 test("agent model discovery prioritizes SDD and Judgment Day agents", (t) => {
 	const root = mkdtempSync(join(tmpdir(), "gentle-pi-model-agents-"));
 	t.after(() => rmSync(root, { recursive: true, force: true }));