@selesai/code 0.5.29 → 0.6.1

package/dist/extensions/pi-subagents/test/unit/tool-description.test.ts

@@ -9,8 +9,10 @@ import {
 	buildSubagentToolDescription,
 	COMPACT_SUBAGENT_TOOL_DESCRIPTION,
 	FULL_SUBAGENT_TOOL_DESCRIPTION,
+	SUBAGENT_PARENT_ROUTING_GUIDANCE,
 	SUBAGENT_SAFETY_GUIDANCE,
 } from "../../src/extension/tool-description.ts";
+import { BUILTIN_AGENT_NAMES } from "../../src/agents/agents.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../../src/runs/shared/pi-args.ts";
 
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -31,9 +33,12 @@ describe("registered subagent tool description", () => {
 	it("keeps full mode safe and free of hardcoded builtin agent names", () => {
 		const description = buildSubagentToolDescription();
 
-		for (const builtinName of ["scout", "worker", "planner"]) {
+		for (const builtinName of BUILTIN_AGENT_NAMES) {
 			assert.doesNotMatch(description, new RegExp(`\\b${builtinName}\\b`));
 		}
+		for (const legacyName of ["scout", "worker", "planner"]) {
+			assert.doesNotMatch(description, new RegExp(`\\b${legacyName}\\b`));
+		}
 		assert.match(description, /^To delegate work, call with \{ agent, task \}, \{ tasks \}, or \{ chain \}; omit action\./i);
 		assert.match(description, /Use action only for management\/control actions listed below/i);
 		assert.match(description, /use \{ action: "list" \} to inspect configured agents\/chains/i);
@@ -50,6 +55,11 @@ describe("registered subagent tool description", () => {
 		assert.doesNotMatch(description, /only for foreground runs/i);
 		assert.doesNotMatch(description, /omit for async\/background runs/i);
 		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
+		assert.match(description, /PARENT-ONLY SUBAGENT ROUTING/);
+		assert.match(description, /call \{ action: "list" \} and select only an executable entry using its current role, context, and tool metadata/i);
+		assert.match(description, /Keep tiny targeted reads and simple answers local/i);
+		assert.match(description, /broad local investigation, external research, and mutation\/implementation work/i);
+		assert.match(description, /parent remains the decision-maker and normally the sole writer/i);
 		assert.match(description, /Do not sleep or poll status just to wait/i);
 		assert.match(description, /use subagent_wait/i);
 		assert.match(description, /interactive session.*normally return control/i);
@@ -62,6 +72,10 @@ describe("registered subagent tool description", () => {
 		assert.match(description, /action: "steer"/);
 		assert.match(description, /schedule-list/);
 		assert.match(description, /action: "eject"/);
+		assert.match(description, /action: "eject", agent: "agent-name"/);
+		assert.match(description, /action: "disable", agent: "agent-name"/);
+		assert.match(description, /action: "enable", agent: "agent-name"/);
+		assert.match(description, /action: "reset", agent: "agent-name"/);
 		assert.match(description, /action: "disable"/);
 		assert.match(description, /action: "grant-spawn-budget"/);
 		assert.match(description, /root interactive parent/i);
@@ -97,6 +111,14 @@ describe("registered subagent tool description", () => {
 		assert.match(description, /PARALLEL/);
 		assert.match(description, /CHAIN/);
 		assert.match(description, /action without execution fields/i);
+		assert.match(description, /Parent-only routing/);
+		assert.match(description, /select only an executable entry using its current role, context, and tool metadata/i);
+		assert.match(description, /Keep tiny targeted reads and simple answers local/i);
+		assert.match(description, /broad local investigation, external research, and mutation\/implementation work/i);
+		assert.match(description, /parent remains the decision-maker and normally the sole writer/i);
+		for (const builtinName of BUILTIN_AGENT_NAMES) {
+			assert.doesNotMatch(description, new RegExp(`\\b${builtinName}\\b`));
+		}
 		assert.match(description, /subagent_wait/i);
 		assert.match(description, /interactive session.*normally return control/i);
 		assert.match(description, /Non-interactive runs.*auto-drain current-session work at agent_end/i);
@@ -127,6 +149,15 @@ describe("registered subagent tool description", () => {
 		assert.match(description, /count:/);
 	});
 
+	it("documents task-aware list advice as explicit-only in both modes", () => {
+		for (const description of [FULL_SUBAGENT_TOOL_DESCRIPTION, COMPACT_SUBAGENT_TOOL_DESCRIPTION]) {
+			assert.match(description, /\{ action: "list", task: "\.\.\." \}/);
+			assert.match(description, /advisory/i);
+			assert.match(description, /never launches/i);
+			assert.match(description, /explicitly call subagent|execute the recommended agent explicitly/i);
+		}
+	});
+
 	it("renders a custom project description with placeholders and mandatory safety guidance", () => {
 		const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-project-"));
 		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-agent-"));
@@ -148,6 +179,8 @@ describe("registered subagent tool description", () => {
 		assert.match(description, new RegExp(escapeRegex(agentDir)));
 		assert.match(description, new RegExp(escapeRegex(projectConfigDir)));
 		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
+		assert.match(description, /PARENT-ONLY SUBAGENT ROUTING/);
+		assert.match(description, /select only an executable entry using its current role, context, and tool metadata/i);
 		assert.equal(warnings.length, 0);
 	});
 
@@ -213,7 +246,7 @@ describe("registered subagent tool description", () => {
 		assert.ok(warnings.some((message) => message.includes("Ignoring invalid toolDescriptionMode")));
 	});
 
-	function readRegisteredDescription(agentDir: string): string {
+	function readRegisteredTool(agentDir: string): { description: string; promptGuidelines?: string[] } {
 		const script = String.raw`
 			import registerSubagentExtension from "./src/extension/index.ts";
 			const events = { on() { return () => {}; }, emit() {} };
@@ -234,7 +267,10 @@ describe("registered subagent tool description", () => {
 			});
 			registerSubagentExtension(fakePi);
 			if (!registeredTool) throw new Error("tool not registered");
-			process.stdout.write(JSON.stringify(registeredTool.description));
+			process.stdout.write(JSON.stringify({
+				description: registeredTool.description,
+				promptGuidelines: registeredTool.promptGuidelines ?? null,
+			}));
 		`;
 		const output = execFileSync(
 			process.execPath,
@@ -248,7 +284,7 @@ describe("registered subagent tool description", () => {
 			],
 			{ cwd: projectRoot, env: parentToolEnv(agentDir), encoding: "utf-8" },
 		);
-		return JSON.parse(output) as string;
+		return JSON.parse(output) as { description: string; promptGuidelines?: string[] };
 	}
 
 	function writeExtensionConfig(agentDir: string, config: Record<string, unknown>): void {
@@ -259,25 +295,40 @@ describe("registered subagent tool description", () => {
 
 	it("registers full, compact, custom, and fallback descriptions from extension config", () => {
 		const defaultAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-default-"));
-		assert.equal(readRegisteredDescription(defaultAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(defaultAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const compactAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-compact-"));
 		writeExtensionConfig(compactAgentDir, { toolDescriptionMode: "compact" });
-		assert.equal(readRegisteredDescription(compactAgentDir), COMPACT_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(compactAgentDir).description, COMPACT_SUBAGENT_TOOL_DESCRIPTION);
 
 		const customAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-custom-"));
 		writeExtensionConfig(customAgentDir, { toolDescriptionMode: "custom" });
 		fs.writeFileSync(path.join(customAgentDir, "subagent-tool-description.md"), "Registered custom description.", "utf-8");
-		const customDescription = readRegisteredDescription(customAgentDir);
+		const customDescription = readRegisteredTool(customAgentDir).description;
 		assert.match(customDescription, /Registered custom description/);
 		assert.match(customDescription, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
 
 		const missingCustomAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-missing-"));
 		writeExtensionConfig(missingCustomAgentDir, { toolDescriptionMode: "custom" });
-		assert.equal(readRegisteredDescription(missingCustomAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(missingCustomAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const invalidAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-invalid-"));
 		writeExtensionConfig(invalidAgentDir, { toolDescriptionMode: "tiny" });
-		assert.equal(readRegisteredDescription(invalidAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredTool(invalidAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
+	});
+
+	it("registers parent-only routing guidance as promptGuidelines on the parent tool", () => {
+		const defaultAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-guidelines-"));
+		const registered = readRegisteredTool(defaultAgentDir);
+
+		assert.ok(Array.isArray(registered.promptGuidelines), "parent subagent tool must expose promptGuidelines");
+		assert.equal(registered.promptGuidelines!.length, 1);
+		assert.equal(registered.promptGuidelines![0], SUBAGENT_PARENT_ROUTING_GUIDANCE);
+		assert.doesNotMatch(SUBAGENT_PARENT_ROUTING_GUIDANCE, new RegExp(BUILTIN_AGENT_NAMES.join("|")));
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /\{ action: "list" \}/);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /executable entry/i);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /tiny targeted reads and simple answers local/i);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /broad local investigation, external research, and mutation\/implementation work/i);
+		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /decision-maker and normally the sole writer/i);
 	});
 });

package/dist/skills/ponytail/SKILL.md

@@ -111,8 +111,6 @@ test, YAGNI applies to tests too.
 
 ## Boundaries
 
-Ponytail governs what you build, not how you talk (pair with Caveman for
-terse prose). "stop ponytail" / "normal mode": revert. Level persists until
-changed or session end.
+Ponytail governs what you build, not how you talk. "stop ponytail" / "normal mode": revert. Level persists until changed or session end.
 
 The shortest path to done is the right path.

package/docs/plans/subagent-delegation/phase-0-correctness.md

@@ -0,0 +1,265 @@
+# Phase 0 Plan — Correctness Cleanup Before Delegation Changes
+
+## Objective
+
+Correct stale bundled-agent documentation and impossible builtin-agent contracts without changing intended delegation policy. Keep current runtime defaults authoritative: only `architect` and `recapper` fork by default; the other four builtins are fresh-context.
+
+## Non-goals
+
+- Do not redesign delegation behavior, context policy, model routing, or orchestration.
+- Do not grant `commentator` write tools.
+- Do not make `researcher` portable by adding new extension/package dependencies.
+- Do not alter user settings, user-home skills, `.selesai/`, `.pi-subagents/`, or unrelated dirty changes.
+- Do not run `npm run build`: it cleans `dist/` and can destroy unrelated dirty generated artifacts.
+
+## Review findings
+
+- **High — stale/mangled role docs:** `src/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md:14,176-192,269` and `README.md:105-116,407` duplicate roles, omit `recapper`, and contain a false self-alias.
+- **High — context contradiction:** `constraints-and-recipes.md:8-9,106,141` and `execution-controls.md:363,369-376` claim `builder`/`commentator` fork by default; their frontmatter declares `fresh`.
+- **High — stale discovery paths:** `execution-controls.md:9-22` and additional README discovery/settings text describe `.pi`, although runtime discovers `.selesai` and legacy `.agents`.
+- **Medium — impossible/unsafe role contracts:** `agents/architect.md:38` tells a child without `question` or `subagent` access to use them; `agents/builder.md:7,21` requires bridge-only `contact_supervisor`; `agents/researcher.md:4` misclassifies MCP tools as builtin tools.
+- **Medium — output/tool-description drift:** role tables say read-only agents write output files and that `commentator` can receive edit/write tools from an explicit fix pass. Neither is true.
+
+## Discovery and baseline preservation
+
+1. From repository root, run:
+   ```bash
+   git status --short
+   git diff --check
+   git diff -- src/extensions/pi-subagents dist/extensions/pi-subagents
+   ```
+2. Record every pre-existing dirty path and hunk. Treat them as owned by another change.
+3. Before touching an affected `dist/extensions/pi-subagents/**` file, inspect its existing diff. If it is already dirty, manually merge only the Phase 0 documentation/agent hunk; never reset, checkout, clean, or overwrite unrelated content.
+4. Confirm these runtime facts before editing:
+   - `src/extensions/pi-subagents/src/agents/agents.ts`: `BUILTIN_AGENT_NAMES` is exactly `architect`, `builder`, `commentator`, `explorer`, `recapper`, `researcher`; discovery uses `.selesai/agents` plus legacy `.agents`.
+   - `src/extensions/pi-subagents/agents/*.md`: only `architect` and `recapper` have `defaultContext: fork`.
+   - `src/extensions/pi-subagents/src/intercom/intercom-bridge.ts:applyIntercomBridgeToAgent`: bridge tools are appended only when the bridge is active.
+   - `src/extensions/pi-subagents/src/runs/shared/pi-args.ts:resolvePiLaunchToolPlan` and `tool-availability.ts`: `tools` is a strict allowlist and `mcp:` values become direct MCP selections.
+
+## Files and ownership
+
+### Source files to modify
+
+| File | Ownership / required change |
+|---|---|
+| `src/extensions/pi-subagents/agents/architect.md` | Builtin planner’s executable prompt; remove unavailable-tool instructions. |
+| `src/extensions/pi-subagents/agents/builder.md` | Builtin writer’s declared tool contract and escalation instruction. |
+| `src/extensions/pi-subagents/agents/researcher.md` | Builtin researcher’s MCP-tool declaration. |
+| `src/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md` | Canonical parent-skill role routing/table guidance. |
+| `src/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md` | Canonical default-context/workflow guidance. |
+| `src/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md` | Canonical discovery, context, and commentator-workflow guidance. |
+| `src/extensions/pi-subagents/README.md` | Public package documentation for builtin roles, paths, and defaults. |
+| `src/extensions/pi-subagents/test/unit/agent-frontmatter.test.ts` | Existing runtime-discovery test seam for builtin frontmatter. |
+| `src/extensions/pi-subagents/test/unit/builtin-agent-documentation.test.ts` (new) | Narrow regression test for six unique builtin roles in both public role tables. |
+
+### Generated package mirrors to synchronize
+
+Mirror only corresponding changed source assets into:
+
+- `dist/extensions/pi-subagents/agents/architect.md`
+- `dist/extensions/pi-subagents/agents/builder.md`
+- `dist/extensions/pi-subagents/agents/researcher.md`
+- `dist/extensions/pi-subagents/README.md`
+- `dist/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md`
+- `dist/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md`
+- `dist/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md`
+
+Do **not** modify runtime TypeScript, user settings, skill installations, or unrelated `dist` output.
+
+## Ordered implementation tasks
+
+### 1. Correct impossible builtin-agent instructions
+
+1. In `agents/architect.md`, replace the sentence that says the architect should use an explorer agent and a “questions tool.”
+   - New instruction: inspect the repository directly with its available read/search tools.
+   - For unresolved user-owned decisions, require the architect to list them explicitly in the returned plan rather than trying to ask questions or launch a child.
+   - Do not add `question`, `interview`, `subagent`, or `contact_supervisor` to architect’s allowlist.
+
+2. In `agents/builder.md`:
+   - Remove `contact_supervisor` from the static `tools:` frontmatter list.
+   - Replace the unconditional instruction to call it with a conditional rule:
+     - when injected bridge instructions make `contact_supervisor` available, use it for unapproved decisions and wait;
+     - otherwise stop, do not guess, and report the exact blocking decision.
+   - Keep all existing core writer tools and the single-writer role unchanged.
+
+3. In `agents/researcher.md`, prefix `grep_app_search` and `grep_app_fetch` with `mcp:` in `tools:`.
+   - Preserve `read` and `web_explore`.
+   - Do not add `extensions` or `subagentOnlyExtensions`; that would introduce a separate dependency/policy decision.
+
+### 2. Repair role, output, capability, and specialty documentation
+
+1. In `prompting-and-roles.md`:
+   - Change “use `explorer` or `explorer`” to one `explorer`.
+   - Replace the malformed Builtin Agents table with exactly one row for each canonical builtin:
+     `architect`, `builder`, `commentator`, `explorer`, `recapper`, `researcher`.
+   - Describe outputs as final responses/artifacts only when caller-configured output persistence is used; never claim read-only agents write project files such as `context.md`, `plan.md`, or `research.md`.
+   - Describe `commentator` as review-only and `builder` as the writer. Remove the claim that a fix pass automatically grants commentator `edit`/`write`.
+   - Include `recapper` as the fork-context handoff specialist.
+   - Replace the false strict-isolation statement with: explicit `tools` is an allowlist, but ambient extension discovery remains possible unless `extensions`, `subagentOnlyExtensions`, or a capability ceiling constrains it; naming a tool alone does not load its provider.
+   - Remove duplicate `builder` in model-tier examples; use real builtins only.
+
+2. In `README.md`:
+   - Replace “Builtin agents in plain English” with the same six unique roles and accurate specialties.
+   - Update the rule of thumb to use `recapper` for a clean current-state handoff, rather than repeating `commentator`.
+   - Remove stale claims that `commentator` is an alias or can make small fixes, and remove obsolete researcher tool names/install guidance.
+   - Correct `.pi` project path/root references to `.selesai`, retaining `.agents` only where runtime actually supports legacy discovery.
+   - State the true context defaults: `architect` and `recapper` fork; `builder`, `commentator`, `explorer`, and `researcher` are fresh.
+   - Remove duplicate/nonexistent “lightweight builder” examples from model-tier text.
+
+### 3. Align context and discovery references with runtime
+
+1. In `constraints-and-recipes.md`:
+   - Replace all duplicated context-default lists with the actual six-agent split.
+   - Change builder guidance from “defaults to fork; pass fresh” to “defaults to fresh; pass fork only when inherited parent context is intentionally required.”
+   - Correct duplicate `explorer` references in Fable/clarify workflow prose.
+   - Keep explicit fresh-context review guidance unchanged.
+
+2. In `execution-controls.md`:
+   - Replace canonical `.pi/agents` and `.pi/chains` paths with `.selesai/agents` and `.selesai/chains`.
+   - State that `.agents` is legacy agent discovery only; do not invent legacy chain discovery.
+   - Replace nearest-root `.pi` wording with `.selesai` or `.agents`.
+   - Rewrite the commentator workflow to show fresh context as the default and an explicit `context: "fork"` only when a branched advisory thread is intended.
+   - Correct builder example prose to state that builder is fresh by default and fork is explicit.
+   - Keep the bridge-injection caveat for `contact_supervisor`; it is accurate once the builder prompt becomes conditional.
+
+### 4. Add focused regression coverage
+
+1. Extend `agent-frontmatter.test.ts`:
+   - Replace the partial fork assertion with a complete expected map for all six builtins:
+     - `architect`, `recapper` → `fork`
+     - `builder`, `commentator`, `explorer`, `researcher` → `fresh`
+   - Assert builder’s static builtin tools do not include `contact_supervisor`.
+   - Assert researcher discovery produces:
+     - builtin tools: `read`, `web_explore`
+     - `mcpDirectTools`: `grep_app_search`, `grep_app_fetch`.
+
+2. Add `builtin-agent-documentation.test.ts`:
+   - Read source `README.md` and `skills/pi-subagents/references/prompting-and-roles.md`.
+   - Extract the first-column agent names from each respective builtin-role table.
+   - Assert each table has exactly the six names in `BUILTIN_AGENT_NAMES`, with no duplicates and no aliases.
+   - Do not test generated `dist` here; generated-copy equality is verified in Task 5.
+
+### 5. Synchronize package copies safely
+
+1. After source tests pass, copy or manually merge only the listed changed source asset files into their matching `dist/extensions/pi-subagents/` paths.
+2. Do not run root `npm run build`.
+3. Do not run broad `npm run copy-assets` if it would overwrite pre-existing dirty generated files.
+4. Verify every changed source asset is byte-identical to its matching `dist` copy:
+   ```bash
+   cmp -s src/extensions/pi-subagents/README.md dist/extensions/pi-subagents/README.md
+   # Repeat for each changed agents/ and skills/ asset listed above.
+   ```
+
+## Decisions requiring approval (do not implement in Phase 0)
+
+1. **Change builtin context defaults rather than docs:**  
+   Recommended Phase 0 action is docs-only alignment with current frontmatter/tests. Changing `builder` or `commentator` to fork would be a delegation-policy change and belongs in a later phase.
+
+2. **Give `commentator` edit/write capability:**  
+   Recommended Phase 0 action is to remove stale documentation only. If fix-pass reviewers should edit, explicitly redesign its frontmatter, acceptance semantics, single-writer guarantees, and tests later.
+
+3. **Make researcher tool providers self-contained:**  
+   Prefixing the grep.app tools as MCP tools is a correctness fix. Adding a web-agent extension path or packaging/configuring a grep.app provider is dependency/routing work and needs approval.
+
+## Verification
+
+### Commands
+
+```bash
+cd src/extensions/pi-subagents
+node --experimental-strip-types --test \
+  test/unit/agent-frontmatter.test.ts \
+  test/unit/builtin-agent-documentation.test.ts
+
+npm run test:unit
+```
+
+From repository root:
+
+```bash
+git diff --check
+git diff -- src/extensions/pi-subagents dist/extensions/pi-subagents
+cmp -s src/extensions/pi-subagents/README.md dist/extensions/pi-subagents/README.md
+```
+
+Repeat `cmp -s` for every changed mirrored asset.
+
+### Success cases
+
+- Discovery returns exactly six builtins with documented specialties.
+- Only architect and recapper resolve to fork context without an explicit run context.
+- Builder launches without requiring bridge-only tools when the bridge is inactive.
+- Builder still receives `contact_supervisor` when the bridge is active.
+- Researcher’s grep.app tools are parsed into `mcpDirectTools`.
+- Both role tables list all six roles exactly once.
+- Source and `dist` copies are identical for every changed package asset.
+
+### Failure cases
+
+- Missing MCP/provider registration still fails with the existing clear missing-tool diagnostic.
+- A builder blocked without a bridge does not guess or attempt an unavailable tool.
+- A forked run without a persisted parent session continues to fail as documented.
+
+### Regression checks
+
+- Explicit `context: "fresh"` and `context: "fork"` overrides retain precedence.
+- `commentator` remains read-only.
+- `architect`, `explorer`, `recapper`, and `researcher` remain non-writing.
+- Legacy `.agents` agent discovery remains supported.
+- Existing user model overrides and user-home skills remain untouched.
+
+## Compatibility, dependencies, risks, rollback
+
+- **Compatibility:** This preserves existing intended frontmatter behavior; only malformed tool routing and bridge-inactive builder startup are corrected.
+- **Dependencies:** existing Node test runtime with `--experimental-strip-types`; no new npm packages.
+- **Risks:** manually generated `dist` copies can conflict with current dirty artifacts; preserve/merge baseline hunks instead of regenerating broad output.
+- **Rollback:** revert only the Phase 0 source, test, and matching `dist` hunks. Do not revert baseline dirty hunks recorded before work began.
+
+```acceptance-report
+{
+  "criteriaSatisfied": [
+    {
+      "id": "criterion-1",
+      "status": "satisfied",
+      "evidence": "Concrete findings and planned fixes identify exact source paths, generated mirror paths, severity, runtime ownership, test seams, and residual risks."
+    }
+  ],
+  "changedFiles": [],
+  "testsAddedOrUpdated": [],
+  "commandsRun": [
+    {
+      "command": "read/grep inspection of recon, builtin agent markdown, runtime discovery/tool planning code, package scripts, README, skill references, and unit tests",
+      "result": "passed",
+      "summary": "Verified Phase 0 ownership, current defaults, strict tool behavior, bridge injection, test runner, and generated-asset copy mechanism."
+    },
+    {
+      "command": "git status --short / git diff",
+      "result": "not-run",
+      "summary": "No shell tool is available in this planning session; the plan requires a baseline dirty-diff capture before implementation."
+    }
+  ],
+  "validationOutput": [
+    "BUILTIN_AGENT_NAMES contains architect, builder, commentator, explorer, recapper, and researcher.",
+    "Only architect and recapper currently declare defaultContext: fork.",
+    "Builder statically requires contact_supervisor even though the bridge appends it only when active.",
+    "Researcher currently declares grep.app tools without the parser-required mcp: prefix.",
+    "Root copy-assets copies src/extensions into dist/extensions, while root build cleans dist and is unsafe for preserving existing dirty generated output."
+  ],
+  "residualRisks": [
+    "Current dirty artifacts and unrelated edits were not inspectable through git in this session; implementation must baseline and preserve them.",
+    "Researcher still depends on host MCP/web extension availability after the prefix correction.",
+    "Changing context defaults or granting commentator write capability requires separate product/architecture approval."
+  ],
+  "noStagedFiles": false,
+  "diffSummary": "No implementation was performed; this artifact is an implementation-ready Phase 0 plan.",
+  "reviewFindings": [
+    "high: skills/pi-subagents/references/prompting-and-roles.md and README.md contain duplicated/missing builtin roles and false output/capability descriptions.",
+    "high: constraints-and-recipes.md and execution-controls.md contradict builtin defaultContext frontmatter.",
+    "high: execution-controls.md and README.md contain stale .pi project discovery/root claims despite .selesai runtime configuration.",
+    "medium: agents/architect.md, agents/builder.md, and agents/researcher.md contain impossible or incorrectly routed tool instructions."
+  ],
+  "manualNotes": "Phase 0 is intentionally limited to correctness cleanup and synchronization. Policy-level delegation behavior changes are explicitly deferred."
+}
+```
+
+⧉ copy assistant: /cp e225dd