gentle-pi 0.10.6 → 0.10.8

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/agents/jd-fix-agent.md

@@ -1,7 +1,13 @@
 ---
 name: jd-fix-agent
 description: Judgment Day surgical fix agent for confirmed findings. Can edit code and run focused tests.
-tools: read, grep, glob, edit, write, bash
+tools:
+  - read
+  - grep
+  - glob
+  - edit
+  - write
+  - bash
 ---
 
 You are the Judgment Day fix agent for Gentle AI.

package/assets/agents/jd-judge-a.md

@@ -1,7 +1,11 @@
 ---
 name: jd-judge-a
 description: Judgment Day blind adversarial reviewer A. Read-only; reports findings and does not fix code.
-tools: read, grep, glob, bash
+tools:
+  - read
+  - grep
+  - glob
+  - bash
 ---
 
 You are Judgment Day judge A for Gentle AI.

package/assets/agents/jd-judge-b.md

@@ -1,7 +1,11 @@
 ---
 name: jd-judge-b
 description: Judgment Day blind adversarial reviewer B. Read-only; independently reports findings and does not fix code.
-tools: read, grep, glob, bash
+tools:
+  - read
+  - grep
+  - glob
+  - bash
 ---
 
 You are Judgment Day judge B for Gentle AI.

package/assets/agents/review-readability.md

@@ -1,7 +1,11 @@
 ---
 name: review-readability
 description: R2 Readability reviewer — naming, complexity, intention, maintainability, review size, and context clarity.
-tools: read, grep, glob, bash
+tools:
+  - read
+  - grep
+  - glob
+  - bash
 ---
 
 You are **R2 Readability**, a read-only reviewer. Find clarity problems; do not fix them.

package/assets/agents/review-reliability.md

@@ -1,7 +1,11 @@
 ---
 name: review-reliability
 description: R3 Reliability reviewer — behavior-first tests, coverage value, edge cases, determinism, contracts, and regressions.
-tools: read, grep, glob, bash
+tools:
+  - read
+  - grep
+  - glob
+  - bash
 ---
 
 You are **R3 Reliability**, a read-only reviewer. Find test and behavior risks; do not fix them.

package/assets/agents/review-resilience.md

@@ -1,7 +1,11 @@
 ---
 name: review-resilience
 description: R4 Resilience reviewer — fallbacks, retry/backoff, graceful degradation, observability, load, rollback, and SLO risks.
-tools: read, grep, glob, bash
+tools:
+  - read
+  - grep
+  - glob
+  - bash
 ---
 
 You are **R4 Resilience**, a read-only reviewer. Find operational failure risks; do not fix them.

package/assets/agents/review-risk.md

@@ -1,7 +1,11 @@
 ---
 name: review-risk
 description: R1 Risk reviewer — security, privilege boundaries, data exposure, dependency risks, and merge-blocking vulnerabilities.
-tools: read, grep, glob, bash
+tools:
+  - read
+  - grep
+  - glob
+  - bash
 ---
 
 You are **R1 Risk**, a read-only reviewer. Find security risks; do not fix them.

package/assets/agents/sdd-apply.md

@@ -1,7 +1,17 @@
 ---
 name: sdd-apply
 description: Implement SDD tasks with strict TDD evidence and review workload guard.
-tools: read, grep, glob, edit, write, bash, mem_search, mem_get_observation, mem_save, mem_update
+tools:
+  - read
+  - grep
+  - glob
+  - edit
+  - write
+  - bash
+  - mem_search
+  - mem_get_observation
+  - mem_save
+  - mem_update
 ---
 
 You are the SDD apply executor for Gentle AI.

package/assets/agents/sdd-archive.md

@@ -1,7 +1,16 @@
 ---
 name: sdd-archive
 description: Archive a verified SDD change into OpenSpec source specs.
-tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - edit
+  - bash
+  - mem_search
+  - mem_get_observation
+  - mem_save
 ---
 
 You are the SDD archive executor for Gentle AI.

package/assets/agents/sdd-design.md

@@ -1,7 +1,15 @@
 ---
 name: sdd-design
 description: Design the technical approach for an SDD change.
-tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - edit
+  - mem_search
+  - mem_get_observation
+  - mem_save
 ---
 
 You are the SDD design executor for Gentle AI.

package/assets/agents/sdd-explore.md

@@ -1,7 +1,12 @@
 ---
 name: sdd-explore
 description: Explore an SDD change idea before proposal.
-tools: read, grep, glob, webfetch, mem_save
+tools:
+  - read
+  - grep
+  - glob
+  - webfetch
+  - mem_save
 ---
 
 You are the SDD explore executor for Gentle AI.

package/assets/agents/sdd-init.md

@@ -2,7 +2,16 @@
 name: sdd-init
 description: Initialize project SDD context, testing capabilities, and skill registry.
 model: openai-codex/gpt-5.3-codex
-tools: read, grep, glob, write, bash, mem_search, mem_get_observation, mem_save, mem_update
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - bash
+  - mem_search
+  - mem_get_observation
+  - mem_save
+  - mem_update
 ---
 
 You are the SDD init executor for Gentle AI.

package/assets/agents/sdd-onboard.md

@@ -1,7 +1,17 @@
 ---
 name: sdd-onboard
 description: Guide a user through a complete SDD cycle on a small real project change.
-tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save, mem_update
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - edit
+  - bash
+  - mem_search
+  - mem_get_observation
+  - mem_save
+  - mem_update
 ---
 
 You are the SDD onboard executor for Gentle AI.

package/assets/agents/sdd-proposal.md

@@ -1,7 +1,15 @@
 ---
 name: sdd-proposal
 description: Write an SDD proposal for an approved change idea.
-tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - edit
+  - mem_search
+  - mem_get_observation
+  - mem_save
 ---
 
 You are the SDD proposal executor for Gentle AI.

package/assets/agents/sdd-spec.md

@@ -1,7 +1,15 @@
 ---
 name: sdd-spec
 description: Write SDD delta specs with requirements and scenarios.
-tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - edit
+  - mem_search
+  - mem_get_observation
+  - mem_save
 ---
 
 You are the SDD spec executor for Gentle AI.

package/assets/agents/sdd-status.md

@@ -1,7 +1,13 @@
 ---
 name: sdd-status
 description: Show read-only structured SDD status for an active change.
-tools: read, grep, glob, bash, mem_search, mem_get_observation
+tools:
+  - read
+  - grep
+  - glob
+  - bash
+  - mem_search
+  - mem_get_observation
 ---
 
 You are the SDD status executor for Gentle AI.

package/assets/agents/sdd-sync.md

@@ -1,7 +1,17 @@
 ---
 name: sdd-sync
 description: Sync verified SDD delta specs into OpenSpec canonical specs without archiving the change.
-tools: read, grep, glob, write, edit, bash, mem_search, mem_get_observation, mem_save, mem_update
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - edit
+  - bash
+  - mem_search
+  - mem_get_observation
+  - mem_save
+  - mem_update
 ---
 
 You are the SDD sync executor for Gentle AI.

package/assets/agents/sdd-tasks.md

@@ -1,7 +1,15 @@
 ---
 name: sdd-tasks
 description: Break SDD design/specs into implementation tasks with review workload forecast.
-tools: read, grep, glob, write, edit, mem_search, mem_get_observation, mem_save
+tools:
+  - read
+  - grep
+  - glob
+  - write
+  - edit
+  - mem_search
+  - mem_get_observation
+  - mem_save
 ---
 
 You are the SDD tasks executor for Gentle AI.

package/assets/agents/sdd-verify.md

@@ -1,7 +1,16 @@
 ---
 name: sdd-verify
 description: Verify implementation against SDD specs, tasks, strict TDD evidence, and review workload boundaries.
-tools: read, grep, glob, bash, write, edit, mem_search, mem_get_observation, mem_save
+tools:
+  - read
+  - grep
+  - glob
+  - bash
+  - write
+  - edit
+  - mem_search
+  - mem_get_observation
+  - mem_save
 ---
 
 You are the SDD verify executor for Gentle AI.

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.8",
   "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 }));

package/tests/package-manifest.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
@@ -60,6 +60,42 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 });
 
 
+function readAgentFrontmatter(file: string): string {
+	const source = readFileSync(file, "utf8");
+	const match = source.match(/^---\n([\s\S]*?)\n---/);
+	assert.ok(match, `${file} must have frontmatter`);
+	return match[1];
+}
+
+test("packaged agents use YAML list syntax for tool allowlists", () => {
+	const agentsDir = join(PACKAGE_ROOT, "assets", "agents");
+	const agentFiles = readdirSync(agentsDir).flatMap((entry) =>
+		entry.endsWith(".md") ? [join(agentsDir, entry)] : [],
+	);
+
+	assert.ok(agentFiles.length > 0, "gentle-pi must ship packaged agents");
+
+	for (const file of agentFiles) {
+		const frontmatter = readAgentFrontmatter(file);
+		assert.doesNotMatch(
+			frontmatter,
+			/^tools:\s*[^\n,]+(?:,\s*[^\n,]+)+$/m,
+			`${file} must not use comma-separated inline tools; pi-subagents expects a YAML list`,
+		);
+		assert.match(frontmatter, /^tools:\n(?: {2}- [\w-]+\n?)+/m, `${file} must declare tools as a YAML list`);
+	}
+});
+
+test("jd-fix-agent packaged allowlist includes write tools", () => {
+	const frontmatter = readAgentFrontmatter(
+		join(PACKAGE_ROOT, "assets", "agents", "jd-fix-agent.md"),
+	);
+
+	for (const tool of ["read", "edit", "write", "bash"]) {
+		assert.match(frontmatter, new RegExp(`^  - ${tool}$`, "m"));
+	}
+});
+
 test("pi-pretty wrapper uses real package path resolution for pnpm symlink installs", () => {
 	const wrapper = readFileSync(
 		join(PACKAGE_ROOT, "extensions", "pi-pretty.ts"),