@henryqw/pi-subagent 15.1.2 → 15.1.4

package/README.md

@@ -80,14 +80,19 @@ See the [orchestration guide](./docs/orchestration.md) for full delegation, tran
 
 The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill guides Main's planning and orchestration. It adds no runtime code, config, or Role installation.
 
+Implementers remove only task-created temporary, generated, or ignored artifacts. Required deliverables and unrelated files stay intact. They never use `git clean` or blanket deletion, and unclear paths block.
+
+For known regressions with a runner that supports test-name filtering, use a test-name filter. Keep broad package or workspace checks to one caller-owned final validation after relevant units integrate. Flow itself does not run that check.
+
 Before delegating:
 
+- Keep trivial, single-owner, mechanically verifiable edits in Main.
+- For literal UI or copy defects, search the exact text first. Read only its producer and nearby assertions unless ownership remains unclear.
 - Find concrete outcomes that can ship on their own.
 - Split only those outcomes. Give each one owner and a focused check.
 - Run independent work in parallel.
 - Prefer parallel delegation when at least two outcomes are independent.
-- For naturally multi-part work, roughly three to five useful units can help.
-- This is a guide, not a quota. Never create units just to reach it.
+- Use only as many units as independent outcomes require. Never create units to reach a count.
 
 Its ordinary review loop is optional. Use it only when the caller or repository policy explicitly requires judgment review.
 
@@ -118,6 +123,7 @@ A Flow has 1–8 units with unique non-empty IDs and allows one active Flow. It
 - Flow runs each declared command with its arguments. That validation is authoritative for objective checks.
 - Without `review`, Flow fast-forwards the exact validated tip.
 - With `review`, the Reviewer receives the exact `{base, tip, patchPath}` packet and must return exactly `PASS` before the same integration path. Use `review` only for stated judgment that validation cannot decide.
+- Trust a successful Flow result. Do not re-read integrated files or repeat its validation merely to confirm it.
 
 A Role selects base tools, extensions, named Skills, instructions, and optional worktree isolation. Named Skills resolve from Main's effective Pi registry. Unavailable names warn and skip.
 

package/docs/orchestration.md

@@ -110,16 +110,16 @@ Flow has no dependency graph, saved state, automatic retry, aggregate review, or
 
 ## Per-delegation resources and isolation
 
-For `delegate_task`, every single entry, parallel sibling, and chain step independently:
+`delegate_task` first preflights every requested Role name, so an initially unknown Role starts no sibling. Then, after receiving an executor permit, every single entry, parallel sibling, and chain step independently:
 
-1. loads its selected Role;
-2. resolves its route and named Skills from the latest effective Pi context after receiving an executor permit;
+1. reloads its effective Role by requested name;
+2. resolves its route and named Skills from the latest effective Pi context;
 3. creates its Role launch policy; and
-4. when the Role requests `isolation: worktree`, creates a worktree identified by the tool call, mode, and input index.
+4. when the reloaded Role requests `isolation: worktree`, creates a worktree identified by the tool call, mode, and input index.
 
 Separate deterministic identities produce separate worktree paths and branches. Parallel siblings cannot collide, and a chain does not base one step's worktree on the preceding step's branch. `{previous}` passes text only. There is no implicit shared worktree or hidden workflow state.
 
-A worktree starts from Main's current `HEAD`. Clean worktrees with no child commits are pruned; committed, dirty, switched, unmeasurable, or otherwise recoverable work is preserved and reported. Non-git directories and repositories with an unborn `HEAD` use Main's working directory. Git submodules reject worktree isolation, and setup failure in a real repository throws rather than silently sharing Main's checkout. This generic fallback remains unchanged: the bundled delegated-development Skill separately refuses to begin without a committed Git `HEAD`.
+A worktree starts from Main's current `HEAD`. Clean worktrees with no child commits are pruned; committed, dirty, switched, unmeasurable, or otherwise recoverable work is preserved and reported. For `delegate_task`, non-git directories and repositories with an unborn `HEAD` use Main's working directory. Git submodules reject worktree isolation, and setup failure in a real repository throws rather than silently sharing Main's checkout. `delegate_flow` requires a Git repository with a committed `HEAD`.
 
 If steps must share files, make that an explicit caller decision: use an intentionally shared workspace, merge preserved child commits, or pass state through a caller-owned store. Do not rely on chain order to imply filesystem sharing.
 

package/examples/roles/implementer.md

@@ -14,12 +14,12 @@ skills: []
 isolation: worktree
 ---
 
-Implement the bounded outcome, not a preassigned file list. Work in the assigned cwd. Read applicable repository instructions and domain context first; inspect the relevant flow, callers, and tests before editing. Preserve unrelated work. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies. Do not add speculative work. Stop when the outcome is complete or blocked.
+Implement the bounded outcome, not a preassigned file list. Work in the assigned cwd. Read applicable repository instructions and domain context; inspect the relevant flow, callers, and tests before editing. Preserve unrelated work. Fix the root cause with the smallest complete diff using existing patterns and dependencies. Add no speculative work. Stop when complete or blocked.
 
-For ordinary delegation, run focused validation needed to establish correctness. For Flow, the declared validation gate is authoritative: run only narrow development checks while implementing and do not duplicate that final gate.
+Run focused checks required by the task. Before reporting, remove only task-created, non-deliverable temporary, generated, or ignored files. Preserve required deliverables, unrelated and pre-existing files, and user data. Never use `git clean` or blanket deletion. If ownership or necessity is uncertain, report the exact path as a blocker.
 
-Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
+Access credentials or the network, create extra artifacts, or broaden scope only when the task requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-Commit completed scoped changes locally unless the task says otherwise. Do not create or manage another worktree. Never push or open a pull request without explicit authorization. For Flow, leave the assigned worktree and branch intact.
+Commit completed scoped changes unless the task says otherwise. Do not create or manage another worktree. Leave the assigned worktree and branch intact. Never push or open a pull request without explicit authorization.
 
-Report briefly: outcome, commit, checks run, and remaining risks. Do not repeat Flow's Git-derived evidence.
+Report briefly: outcome, commit, checks, and remaining risks.

package/examples/roles/reviewer.md

@@ -10,11 +10,8 @@ extensions: []
 skills: []
 ---
 
-Review read-only in exactly two modes:
+Review the supplied candidate read-only. Use only supplied requirements and named files or evidence; do not prepare Git or broaden discovery. If evidence is insufficient, say so and stop.
 
-1. Ordinary delegation: use supplied requirements and named files/evidence only. Do not prepare Git, require a commit/Review Packet, or broaden discovery. If evidence is insufficient, say so and stop.
-2. Flow exact review: only with an explicit judgment criterion, use the same assigned Unit Worktree and exact Review Packet `{base, tip, patchPath}`. Treat the exact patch at `patchPath` as authoritative; read only referenced files/context. Declared validation is authoritative for objective verification. Judge only the explicit criterion; never infer a diff from another branch/worktree.
+Report only actionable correctness risks introduced by the change, not style preferences, speculative hypotheticals, or unrelated pre-existing issues. Run no commands or tests. Never edit, write, commit, push, manage Git or worktrees, or invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-Report only actionable correctness risks introduced by the change—not style preferences, speculative hypotheticals, or unrelated pre-existing issues. Use only `read`, `grep`, `find`, and `ls`; run no commands/tests and never edit, write, commit, push, or manage Git/worktrees. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
-
-Output exactly `PASS` when there are no findings. Otherwise output findings only, ordered by severity, with file:line evidence, impact, and smallest valid fix; any finding blocks approval. Never combine `PASS` with findings. Stop when supplied evidence is covered; in Flow, stop after its criterion.
+Output exactly `PASS` when there are no findings. Otherwise output findings only, ordered by severity, with file:line evidence, impact, and the smallest valid fix. Any finding blocks approval; never combine `PASS` with findings. Stop when the supplied evidence is covered.

package/extensions/delegate-flow.ts

@@ -20,7 +20,7 @@ import {
 import { Type, type Static } from "typebox";
 import { Check } from "typebox/value";
 import { MODEL_CLASS_GUIDANCE } from "./model-class-policy.ts";
-import { TASK_NAME_CONTRACT, TaskNameSchema, normalizeTaskName } from "./task-name.ts";
+import { TaskNameSchema, normalizeTaskName } from "./task-name.ts";
 
 const MAX_UNITS = 8;
 const GIT_TIMEOUT_MS = 30_000;
@@ -247,7 +247,7 @@ function reviewerTask(unit: FlowUnitRequest, review: string, packet: { base: str
 		...unit.validation.map((validation) => `- ${JSON.stringify(validation)}`),
 		"",
 		`Review Packet: ${JSON.stringify(packet)}`,
-		"Review only the criterion above. Read the exact patch as authoritative and emit exactly PASS only when there are zero findings.",
+		"In the assigned Unit Worktree, treat the exact patch at patchPath as authoritative. Read only referenced context, judge only the criterion above, and never infer a diff from another branch or worktree.",
 	].join("\n");
 }
 
@@ -550,7 +550,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		const tip = oid(tipResult.stdout, "Unit HEAD");
 		const branchTip = oid(await requireGit(["rev-parse", "--verify", `refs/heads/${unit.worktree.branch}^{commit}`], unit.worktree.cwd, signal), "Unit branch tip");
 		if (tip !== branchTip) return { block: `Unit ${JSON.stringify(unit.request.id)} branch no longer names its checked-out HEAD.` };
-		const status = await requireGit(["status", "--porcelain=v1", "--untracked-files=all"], unit.worktree.cwd, signal);
+		const status = await requireGit(["status", "--porcelain=v1", "--untracked-files=all", "--ignore-submodules=none"], unit.worktree.cwd, signal);
 		if (status) return { block: `Unit Worktree is dirty:\n${capOutput(status)}` };
 		const flags = await inspectIndexFlags(unit.worktree.cwd, git, signal);
 		if (flags.failure) throw new Error(`Unit index inspection failed: ${flags.failure}`);
@@ -770,10 +770,10 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		description: "Run 1–8 independent Implementers in isolated Unit Worktrees, validate and serially fast-forward each tip, with exact review only for units that declare a judgment criterion.",
 		promptSnippet: "Run a deterministic parallel-implementation, serial-verification Flow",
 		promptGuidelines: [
-			"Use delegate_flow only for cohesive units expected to commute: make independent commuting outcomes separate units rather than combining them merely to reduce Implementer count; sequence dependent work outside delegate_flow. On naturally multi-part work, actively look for roughly 3–5 useful units, but never manufacture units, split one invariant across multiple units, assign overlapping mutable ownership, or use a quota. Combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
-			`${TASK_NAME_CONTRACT.promptGuidance} Each delegate_flow unit must own one concrete outcome with one focused validation story: include explicit bounded requirements and its authoritative direct command/argument validation gate. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Add review only for an explicit judgment that validation cannot establish.`,
-			`For each delegate_flow unit, ${MODEL_CLASS_GUIDANCE}`,
-			"If a Flow blocks, inspect its classification and call delegate_flow_continue once with explicit repair guidance; modelClass may replace that one repair's current class.",
+			"Use delegate_flow only for independent commuting units; sequence dependent work elsewhere. Separate independently useful outcomes, but never manufacture units, split an invariant, or overlap mutable ownership. Combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
+			"Each delegate_flow unit needs one bounded outcome, explicit requirements, and an authoritative command/argument validation gate. Discover unclear scope first. Add review only for judgment validation cannot establish.",
+			`For delegate_flow, ${MODEL_CLASS_GUIDANCE}`,
+			"If delegate_flow blocks, inspect its classification and call delegate_flow_continue once with explicit repair guidance; modelClass may replace that repair's current class.",
 		],
 		parameters: DelegateFlowSchema,
 		prepareArguments: parseDelegateFlow,

package/extensions/subagent.ts

@@ -54,8 +54,6 @@ import {
 	type ParsedWorkflow,
 	type WorkflowEntry,
 } from "./workflow.ts";
-import { TASK_NAME_CONTRACT } from "./task-name.ts";
-
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 80;
 const MAX_WIDGET_ITEMS = 8;
@@ -596,11 +594,10 @@ export default function subagentExtension(
 		description: `Delegate one selected single, parallel, or chain workflow of bounded tasks to isolated Pi Subagents. Roles: ${roleSummary()}.`,
 		promptSnippet: "Delegate one bounded single, parallel, or chain workflow to isolated roles",
 		promptGuidelines: [
-			"Call delegate_task with exactly one mode: role+name+task in single mode for one atomic task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output; prefer parallel mode whenever at least two independent outcomes exist and each is independently deliverable and independently verifiable; do not combine independent outcomes merely to reduce child count. Sequence dependent work in chain entries, and never divide one invariant across multiple entries.",
-			`${TASK_NAME_CONTRACT.promptGuidance} Every delegate_task entry must own one concrete outcome with one focused validation story: state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; if the affected flow or scope is not yet known, perform bounded read-only discovery first; never pass the parent request unchanged. For naturally multi-part delegate_task work, you may look for roughly 3–5 useful entries, but do not manufacture entries or enforce a quota.`,
-			`For each delegate_task entry, ${MODEL_CLASS_GUIDANCE} A direct model replaces only the selected route's model; its thinking level stays unchanged.`,
-			"Parallel mutating delegate_task entries must own non-overlapping files and changes. Read-only delegate_task entries may inspect overlapping sources when their questions and deliverables differ. Keep integration and cross-cutting decisions in Main.",
-			"delegate_task background applies to the whole selected workflow and returns before results exist; use it only when the user explicitly asks for non-blocking work.",
+			"Use delegate_task with exactly one mode: role+name+task for one task, tasks for 1–8 independent tasks, or chain for 1–8 dependent tasks using {previous}. Prefer parallel whenever at least two outcomes are independently deliverable and verifiable; never split one invariant.",
+			"Each delegate_task entry needs one bounded outcome, scope and exclusions, context and constraints, deliverable, and focused validation. Discover unclear scope first; never pass the parent request unchanged. Parallel mutations need non-overlapping ownership; read-only tasks may overlap only for distinct questions. Keep integration and cross-cutting decisions in Main.",
+			`For delegate_task, ${MODEL_CLASS_GUIDANCE} A direct model replaces only the selected route's model; its thinking level stays unchanged.`,
+			"Use delegate_task background only when the user explicitly requests non-blocking work.",
 		],
 		parameters: WorkflowSchema,
 		prepareArguments(args) {
@@ -619,10 +616,9 @@ export default function subagentExtension(
 			};
 			throwIfAborted();
 			let workflow: ParsedWorkflow;
-			let roles: Role[];
 			try {
 				workflow = parseWorkflow(params);
-				roles = loadRoles();
+				const roles = loadRoles();
 				const knownRoles = new Set(roles.map(({ name }) => name));
 				for (const { role } of workflow.delegations) {
 					if (!knownRoles.has(role)) {
@@ -633,7 +629,22 @@ export default function subagentExtension(
 				throw boundedError(error);
 			}
 			throwIfAborted();
-			const rolesByName = new Map(roles.map((role) => [role.name, role]));
+			const reloadRole = (name: string): Role => {
+				let freshRoles: Role[];
+				try {
+					freshRoles = loadRoles();
+				} catch (error) {
+					throw boundedError(new Error(
+						`Couldn't reload Subagent role ${JSON.stringify(name)} after it waited for an executor permit. Fix the Role configuration and retry: ${error instanceof Error ? error.message : String(error)}`,
+						{ cause: error },
+					));
+				}
+				const role = freshRoles.find((candidate) => candidate.name === name);
+				if (role) return role;
+				throw boundedError(new Error(
+					`Subagent role ${JSON.stringify(name)} disappeared while waiting for an executor permit. Restore it and retry. Available roles: ${freshRoles.map(({ name: available }) => available).join(", ") || "none"}.`,
+				));
+			};
 
 			// Resolve against the latest known session context after each FIFO permit.
 			const launchCtx = () => latestCtx ?? ctx;
@@ -681,7 +692,6 @@ export default function subagentExtension(
 			const runWorkflow = async (workflowSignal: AbortSignal | undefined, emitToolUpdates: boolean) => {
 				try {
 					return await runForegroundWorkflow<EphemeralSubagentResult>(toolCallId, foregroundWorkflow, async (entry: WorkflowEntry) => {
-					const role = rolesByName.get(entry.delegation.role)!;
 					let model: string | undefined;
 					let thinkingLevel: string | undefined;
 					let worktree: WorktreeInfo | undefined;
@@ -701,7 +711,7 @@ export default function subagentExtension(
 							id: entry.id,
 							index: entry.index,
 							name: entry.delegation.name,
-							role: role.name,
+							role: entry.delegation.role,
 							...(model === undefined ? {} : { model }),
 							...(thinkingLevel === undefined ? {} : { thinkingLevel }),
 							...(worktreePayload === undefined ? {} : { worktreePayload }),
@@ -723,6 +733,7 @@ export default function subagentExtension(
 							prepare: async () => {
 								// Route and effective Role resources resolve only after this entry's
 								// shared executor permit, before isolated state is created.
+								const role = reloadRole(entry.delegation.role);
 								const launch = resolveLaunch(role, entry.delegation);
 								notifyMissingSkills(role, launch);
 								model = modelReference(launch.model);

package/extensions/task-name.ts

@@ -3,13 +3,11 @@ import { Type, type Static } from "typebox";
 
 const TASK_NAME_MAX_LENGTH = 29 as const;
 const TASK_NAME_LIMIT_WORDING = `about five words and fewer than ${TASK_NAME_MAX_LENGTH + 1} characters`;
-const TASK_NAME_WORDING = `short descriptive name of ${TASK_NAME_LIMIT_WORDING}`;
 
 export const TASK_NAME_CONTRACT = {
 	minLength: 1,
 	maxLength: TASK_NAME_MAX_LENGTH,
 	description: `Short descriptive task name, ${TASK_NAME_LIMIT_WORDING}; C0/C1 control characters are rejected.`,
-	promptGuidance: `Use a ${TASK_NAME_WORDING} without C0/C1 control characters.`,
 	controlRanges: DISPLAY_TEXT_CONTRACT.controlRanges,
 	pattern: DISPLAY_TEXT_CONTRACT.pattern,
 } as const;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "15.1.2",
+  "version": "15.1.4",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent-delegated-development/SKILL.md

@@ -1,61 +1,38 @@
 ---
 name: pi-subagent-delegated-development
-description: Use Delegate Flow, or coordinate explicitly required judgment review for ordinary delegated implementation.
+description: Use only when implementation merits delegation for isolation, parallelism, long-running execution, or explicit judgment; then choose Delegate Flow or ordinary delegation.
 ---
 
 # Delegated Development
 
-You are Main, the planner/orchestrator: slice work and choose `delegate_flow` or `delegate_task` as described below. Do not implement child work yourself or use external model tools, push, publish, or release.
+Keep a trivial, single-owner, mechanically verifiable edit in Main when its producer and regression assertion are known. Delegate only when isolation, independent parallel work, long-running execution, or explicit judgment materially helps.
 
-## Slice
+You are Main, the planner/orchestrator. Follow the selected tool's guidelines for mode, decomposition, task packets, ownership, validation, and model routing. Do not implement child work, use external model tools, push, publish, or release.
 
-Before slicing, identify applicable repository prohibitions. If the request or plan conflicts with them, stop and resolve the conflict before delegation. Copy them into every affected task and into `review` when automated validation cannot establish compliance; never replace repository policy with generic preservation or migration assumptions. When compatibility is disallowed, require deletion of replaced paths and forbid legacy readers, aliases, adapters, dual schemas, deprecation paths, and compatibility fallbacks.
+## Before delegation
 
-Run a concise decomposition pass. Identify independently deliverable concrete outcomes. Maximize safe parallelism at those boundaries: give each outcome focused validation and clear ownership, and parallelize commuting work. Prefer parallel delegation when at least two independent outcomes exist. For naturally multi-part work, roughly 3–5 useful units is a guide, not a quota. Never manufacture units.
+- Apply repository prohibitions. Resolve conflicts first and copy relevant rules into affected tasks. Include them in `review` only when validation cannot prove compliance. Repository policy overrides generic preservation or migration assumptions. If compatibility is disallowed, require deletion of replaced paths and forbid legacy readers, aliases, adapters, dual schemas, deprecation paths, and fallbacks.
+- For a literal UI or copy defect, search the exact quoted text first, then read only its producer and nearby regression assertions. Broaden only when ownership remains unclear.
+- Name neighboring behavior that must stay unchanged. Include the exact test name or error when known CI evidence exists; never claim a validation command matches unknown CI.
+- A Flow unit must fit one Implementer launch before the configured maximum runtime. Cohesion does not justify combining separately verifiable milestones. Split oversized dependent work into serial one-unit Flows after each milestone integrates, or use ordinary sequencing.
 
-Before selecting a Flow unit, require that one Implementer launch can plausibly finish before the configured maximum runtime. Cohesion alone is not enough when work has multiple preservable, separately verifiable milestones. Use `delegate_flow` for independent units expected to commute. Keep work together or sequence it when splitting would divide an invariant, overlap mutable ownership, or create coordination. Combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants. Units inside one Flow remain independent and commuting. Dependent work remains outside Flow. Split oversized dependent work into serial one-unit Flows after each milestone integrates; otherwise sequence it in one task or ordinary caller-controlled sequencing.
-
-Give every unit a bounded objective, owned scope and exclusions, and its direct validation command/argument array. Each task packet must name the neighboring behavior that must stay unchanged. Include the exact test name or error when known CI evidence exists. Never claim a validation command matches unknown CI.
-
-Each delegation must own one concrete outcome with one focused validation story. Order declared validation from the cheapest focused check to broader required checks. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Do not pass the parent request unchanged. Choose `modelClass` according to the delegation tool's guidance. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
+For a known regression, use an exact test-name filter when supported; for Node: `node --test --test-name-pattern "exact test name" test/example.test.ts`. Keep unit validation focused. Run any required broad or cross-unit check once in Main after integration. Do not duplicate checks against the same state. Flow has no post-merge validation.
 
 ## Runtime Flow
 
-The runtime owns the unit worktrees and all Git identity, rebasing, committed-state inspection, declared validation, conditional exact read-only review, fast-forward integration, and cleanup. Declared validation is the authority for objective verification. A validated unit without `review` skips review evidence and Reviewer launch, then integrates its exact validated tip. A unit with `review` receives the existing exact `{base, tip, patchPath}` protocol and must receive exactly `PASS` before integration.
-
-Trust the structured Flow outcome. Never edit a child worktree, manage its branches, prepare review evidence, reimplement Flow, or manually integrate its changes. Do not repeat Flow validation after it has completed or integrated a unit.
-
-A successful Flow owns integration and cleanup. A blocked outcome is repairable once: provide one explicit continuation and no more:
-
-```ts
-delegate_flow_continue({ guidance: "Address the reported block and complete the bounded unit.", modelClass: "balanced" })
-```
-
-Make the guidance specific to the reported implementation, validation, or review failure. Omit `modelClass` to retain an explicit blocked-unit class or otherwise use each frozen Role's default; supply it only to replace both defaults for that one repair. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect each exact retained path reported by the runtime directly, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution. Do not run `git worktree list` merely to rediscover a retained path.
-
-A cleanup warning does not undo successful integration. Report a cleanup warning from a successful Flow as-is. Do not investigate it unless the user asks or cleanup is part of acceptance.
-
-## Ordinary delegation
-
-Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Choose `modelClass` according to the delegation tool's guidance. A direct `model` replaces only the selected route's model. The route keeps its thinking level. Keep integration and cross-cutting decisions in Main.
-
-### Optional evidence loop for implementation
-
-Use this caller-managed loop only when the caller or repository policy explicitly requires judgment review. It is not required for every ordinary implementation.
-
-After implementation and focused validation, launch `delegate_task` with `role: "reviewer"` to select the effective `reviewer` Role. A same-named user Role remains effective. The task packet must state:
+The runtime owns unit worktrees, Git identity, rebasing, committed-state inspection, declared validation, conditional exact read-only review, fast-forward integration, and cleanup. Validation is authoritative. Without `review`, Flow integrates the exact validated tip. With `review`, it supplies `{base, tip, patchPath}` and requires exactly `PASS`.
 
-- the read-only scope;
-- the exact acceptance criteria;
-- exact candidate evidence visible from the Reviewer's working directory and the supplied validation evidence;
-- the exact output contract: return `PASS` alone on approval, or findings only.
+Trust the structured Flow outcome. Never edit child worktrees, manage branches, prepare review evidence, reimplement Flow, or integrate manually. After successful integration, do not re-read implementation, tests, manifests, or commit stats merely to confirm it. Check Main's status only for a caller-owned requirement. Do not repeat Flow validation.
 
-Do not launch the Reviewer unless it can see the actual candidate. For an isolated implementation candidate, use `delegate_flow` instead of composing an ordinary review against Main's unchanged checkout.
+For a repairable block, call `delegate_flow_continue` once with guidance specific to the failure. Omit `modelClass` to retain the unit class or frozen Role defaults; supply it only to replace both defaults for that repair. On terminal failure, inspect the exact retained paths reported by Flow, then reslice or recover in Main. Do not retry Flow, guess a rebase resolution, or rediscover a reported path with `git worktree list`.
 
-Empty Reviewer output is a failure. Retry only when explicit caller policy requires one; otherwise surface the failure and block completion. If that retry is also empty, surface the second empty result and block completion.
+Report a cleanup warning from a successful Flow as-is. Investigate only when the user asks or cleanup is acceptance.
 
-If the initial review returns findings, repair them together. Run one focused validation of the repaired inputs before one focused re-review. Its task packet must restate the read-only scope, exact output contract, original findings, original acceptance criteria, exact repaired-candidate evidence, and validation evidence.
+## Optional ordinary review
 
-Only `PASS` completes the loop. Focused re-review findings block completion and must be surfaced. Do not start another repair/review round.
+Use a caller-managed review only when the caller or repository policy explicitly requires judgment. Never layer it onto Flow.
 
-Do not layer this loop onto `delegate_flow`. Flow already owns exact review evidence, exact `PASS` approval, validation replay, one repair continuation, and no automatic retry.
+1. After implementation and focused validation, call `delegate_task` with `role: "reviewer"`; a same-named user Role remains effective.
+2. Supply read-only scope, acceptance criteria, validation evidence, visible candidate evidence, and the output contract: `PASS` alone or findings only. If the Reviewer cannot see an isolated candidate, use Flow instead.
+3. Empty output fails. Retry only when explicit policy requires it; a second empty result blocks completion.
+4. On findings, repair them together, validate once, and re-review once with the original criteria, findings, and repaired evidence. Only `PASS` completes the loop; surface further findings and stop.