@ferris1225/pi-subagents 4.1.4 → 4.1.5

package/src/dispatch.ts

@@ -1,8 +1,9 @@
 /**
  * The `subagent` tool: dispatches explorer/worker/cleaner/documenter/reviewer agents as isolated pi
  * child processes, single or parallel. Owns the public dispatch contract,
- * per-run status tracking, managed writer → reviewer → documenter workflows,
- * bounded worker/reviewer fix rounds, and internal step launching. Stable
+ * per-run status tracking, managed worker/cleaner → reviewer workflows with a
+ * conditional documenter, bounded worker/reviewer fix rounds, and internal
+ * step launching. Stable
  * thread generations, final integration, and completion ownership live in
  * thread-lifecycle.ts.
  */
@@ -21,6 +22,7 @@ import {
 	buildFinalReviewBrief,
 	buildFixTaskBrief,
 	buildReReviewBrief,
+	documentationDisposition,
 	type ChainStep,
 	type ManagedWorkflowOutcome,
 } from "./fixloop.ts";
@@ -30,6 +32,8 @@ import {
 	monitor,
 	statusIcon,
 	type RunChainMeta,
+	type WorkflowStage,
+	type WorkflowStageStatus,
 } from "./monitor.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import {
@@ -85,6 +89,14 @@ export function defaultIsolationMode(mode: "single" | "parallel", agentName: str
 	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
 }
 
+function workflowStageStatus(result: SingleResult): WorkflowStageStatus {
+	if (isFailedResult(result)) return "failed";
+	if (result.agent !== "reviewer") return "done";
+	const verdict = reviewVerdict(getResultOutput(result));
+	if (verdict === "fail") return "changes";
+	return verdict === "pass" ? "done" : "failed";
+}
+
 const managedRepositoryRootTails = new Map<string, Promise<void>>();
 
 async function canonicalManagedRepositoryRoot(cwd: string): Promise<string> {
@@ -167,15 +179,15 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		name: "subagent",
 		label: "Subagent",
 		description: [
-			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel.",
-			"Built-ins: explorer for broad read-only reconnaissance; worker for implementation; cleaner for explicitly authorized cleanup, removal, simplification, and duplicate-code consolidation; documenter for pre-commit diff sync or explicitly requested whole-codebase comment/README/docs maintenance; reviewer for generic read-only assessments and final gates.",
-			"Work starts in the background; successful top-level writers automatically continue through enabled documenter/reviewer stages and return one final completion. Results resume the main agent and are already shown to the user, so do not poll, duplicate downstream roles, or restate them. Give each child a self-contained brief because it has no conversation memory.",
+			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel; keep small known-target work in the main thread with direct tools.",
+			"Built-ins: explorer for broad read-only reconnaissance (a retrieval index, never a gate); worker for implementation; cleaner as a separate explicitly authorized cleanup/removal/simplification/deduplication entry; documenter for explicit docs/comments work or conditional final diff sync; reviewer for generic read-only assessments and independent code gates.",
+			"Work starts in the background. Successful worker/cleaner runs keep one enabled reviewer gate and bounded fix loop; documenter runs afterward only when REVIEW_PASS reports DOCUMENTATION: NEEDED or omits the marker, with a reviewer-disabled fallback. A top-level documenter delivers directly. Results resume the main agent and are already shown, so do not poll, duplicate downstream roles, or restate them.",
 			"Single tasks default to shared; parallel workers default to detached Git worktrees. Only write-capable agents can use worktree isolation, and failures never fall back silently to shared.",
 			"A selected-model or provider failure continues the retained session on the current main model; ordinary tool/task failures do not.",
 			"Use subagent_control to steer/retarget an active top-level child, park/stop a managed downstream stage, or resume/fork retained context by stable run id.",
 		].join(" "),
 		promptSnippet:
-			"Dispatch isolated background agents: explorer (recon), worker (implementation), cleaner (authorized cleanup/deduplication), documenter (docs sync), reviewer (read-only assessment/gate); enabled post-writer stages run automatically, results resume automatically, and the workflow delivers once. Use direct tools for trivial work.",
+			"Dispatch isolated background agents for broad recon, self-contained implementation, authorized cleanup, explicit docs, or independent review; keep small known-target work on direct tools. Worker/cleaner gates and only needed/conservative docs sync run automatically, results resume automatically, and each workflow delivers once.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -387,27 +399,90 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const enabled = (name: string): boolean =>
 					request.agents.some((candidate) => candidate.name === name);
 				const canContinue = (): boolean => runtime.sessionActive && !request.signal.aborted;
+
+				// Keep a live parent-owned projection because settled internal rows are
+				// intentionally removed. Only real/currently planned stages enter it.
+				const initialStageRelation = initialStepResult.agent === "worker"
+					? "implement"
+					: initialStepResult.agent === "cleaner"
+						? "cleanup"
+						: "review";
+				const workflowStages: WorkflowStage[] = [{
+					agent: initialStepResult.agent,
+					relation: initialStageRelation,
+					status: workflowStageStatus(initialStepResult),
+				}];
+				let reviewStage: WorkflowStage | undefined;
+				if (request.plan.kind === "post-writer" && enabled("reviewer")) {
+					reviewStage = { agent: "reviewer", relation: "review", status: "pending" };
+					workflowStages.push(reviewStage);
+				}
+				let documentationStage: WorkflowStage | undefined;
+				if (enabled("documenter")) {
+					documentationStage = { agent: "documenter", relation: "docs", status: "pending" };
+					workflowStages.push(documentationStage);
+				}
+				const publishWorkflowStages = (): void => {
+					monitor.setWorkflowStages(request.parentRunId, workflowStages);
+				};
+				const insertBeforeDocumentation = (stage: WorkflowStage): void => {
+					const documentationIndex = documentationStage
+						? workflowStages.indexOf(documentationStage)
+						: -1;
+					if (documentationIndex === -1) workflowStages.push(stage);
+					else workflowStages.splice(documentationIndex, 0, stage);
+				};
+				const removeDocumentationStage = (): void => {
+					if (!documentationStage) return;
+					const index = workflowStages.indexOf(documentationStage);
+					if (index !== -1) workflowStages.splice(index, 1);
+					documentationStage = undefined;
+					publishWorkflowStages();
+				};
+				publishWorkflowStages();
+
 				const launchStep = async (
 					agentName: string,
 					task: string,
 					relation: string,
+					projection: {
+						stage?: WorkflowStage;
+						timelineRelation?: string;
+						childRelation?: string;
+					} = {},
 				): Promise<SingleResult> => {
 					if (!enabled(agentName)) {
 						throw new Error(`Managed workflow cannot launch disabled or missing agent "${agentName}".`);
 					}
-					const step = await launchInWorkflow(request, agentName, task, {
-						groupId: request.groupId,
-						relationLabel: relation,
-						parentRunId: request.parentRunId,
-					});
-					request.rememberLatest(step.result);
-					steps.push({ ...step, relation });
-					return step.result;
+					const stage: WorkflowStage = projection.stage ?? {
+						agent: agentName,
+						relation: projection.timelineRelation ?? relation,
+						status: "pending",
+					};
+					if (!projection.stage) insertBeforeDocumentation(stage);
+					stage.status = "active";
+					publishWorkflowStages();
+					try {
+						const step = await launchInWorkflow(request, agentName, task, {
+							groupId: request.groupId,
+							relationLabel: projection.childRelation ?? relation,
+							parentRunId: request.parentRunId,
+						});
+						stage.status = workflowStageStatus(step.result);
+						publishWorkflowStages();
+						request.rememberLatest(step.result);
+						steps.push({ ...step, relation });
+						return step.result;
+					} catch (error) {
+						stage.status = "failed";
+						publishWorkflowStages();
+						throw error;
+					}
 				};
 
-				/** Bounded worker → reviewer fix rounds. Documentation sync deliberately
-				 * stays out of the rounds: code fixes would invalidate it, and one final
-				 * documenter covers the settled diff once. */
+				/** Bounded worker → reviewer fix rounds. A conditional documentation sync
+				 * deliberately stays out of the rounds: code fixes would invalidate it,
+				 * and the terminal review classifies whether the settled diff needs one. */
 				const runFixRounds = async (
 					triggeringReviewer: SingleResult,
 				): Promise<{ lastReview?: SingleResult; lastWorker?: SingleResult }> => {
@@ -415,20 +490,24 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					const outcome: { lastReview?: SingleResult; lastWorker?: SingleResult } = {};
 					for (let round = 1; round <= request.config.maxFixRounds; round++) {
 						if (!canContinue()) break;
+						const fixRelation = `fix ${round}/${request.config.maxFixRounds}`;
 						const workerResult = await launchStep(
 							"worker",
 							buildFixTaskBrief(lastReviewer, round, request.config.maxFixRounds),
 							`fix round ${round}`,
+							{ timelineRelation: fixRelation, childRelation: fixRelation },
 						);
 						if (isFailedResult(workerResult) || !canContinue()) break;
 						outcome.lastWorker = workerResult;
 
+						const reReviewRelation = `re-review ${round}/${request.config.maxFixRounds}`;
 						const reviewResult = await launchStep(
 							"reviewer",
 							buildReReviewBrief(lastReviewer, round, workerResult, {
 								documenterPending: enabled("documenter"),
 							}),
 							`re-review round ${round}`,
+							{ timelineRelation: reReviewRelation, childRelation: reReviewRelation },
 						);
 						if (isFailedResult(reviewResult) || !canContinue()) break;
 						outcome.lastReview = reviewResult;
@@ -441,24 +520,40 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					return outcome;
 				};
 
-				/** One final documentation sync after the gate settles. It is skipped
-				 * when documenter is disabled, the last writer already was a
-				 * documenter with no code fixes after it, or the chain ended on a
-				 * failing/crashed gate (docs for rejected code would be rework). */
+				/** Run the low-cost final documentation sync only when the terminal REVIEW_PASS
+				 * reports drift or omits the new marker. A failed process, missing verdict, or
+				 * REVIEW_FAIL never writes docs. With no reviewer, retain the conservative
+				 * writer → documenter fallback. */
 				const runFinalDocumentation = async (
 					lastWriterResult: SingleResult | undefined,
 					finalReviewResult: SingleResult | undefined,
 				): Promise<void> => {
 					if (!canContinue() || !enabled("documenter")) return;
-					if (lastWriterResult?.agent === "documenter") return;
+					if (lastWriterResult?.agent === "documenter") {
+						removeDocumentationStage();
+						return;
+					}
 					if (finalReviewResult) {
-						if (isFailedResult(finalReviewResult)) return;
-						if (reviewVerdict(getResultOutput(finalReviewResult)) === "fail") return;
+						if (isFailedResult(finalReviewResult)) {
+							removeDocumentationStage();
+							return;
+						}
+						const reviewOutput = getResultOutput(finalReviewResult);
+						if (
+							reviewVerdict(reviewOutput) !== "pass" ||
+							documentationDisposition(reviewOutput) === "clean"
+						) {
+							removeDocumentationStage();
+							return;
+						}
 					}
+					documentationStage ??= { agent: "documenter", relation: "docs", status: "pending" };
+					if (!workflowStages.includes(documentationStage)) workflowStages.push(documentationStage);
 					await launchStep(
 						"documenter",
 						buildFinalDocumenterBrief(lastWriterResult, finalReviewResult),
 						"final documentation sync",
+						{ stage: documentationStage },
 					);
 				};
 
@@ -471,30 +566,30 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						const fixOutcome = await runFixRounds(initialStepResult);
 						await runFinalDocumentation(fixOutcome.lastWorker, fixOutcome.lastReview ?? initialStepResult);
 					} else if (request.plan.kind === "review-pass-sync") {
-						// The direct passing review already gated the pending code; sync
-						// docs once and deliver without a second gate.
+						// The direct passing review already gated the pending code. Its
+						// disposition requested (or conservatively defaulted to) one docs sync.
 						await runFinalDocumentation(undefined, initialStepResult);
 					} else if (enabled("reviewer")) {
 						const gateReview = await launchStep(
 							"reviewer",
 							buildFinalReviewBrief(initialStepResult, { documenterPending: enabled("documenter") }),
 							"final review",
+							{ stage: reviewStage },
 						);
-						if (!isFailedResult(gateReview)) {
-							let fixOutcome: Awaited<ReturnType<typeof runFixRounds>> = {};
-							if (
-								canContinue() &&
-								reviewVerdict(getResultOutput(gateReview)) === "fail" &&
-								enabled("worker") &&
-								request.config.maxFixRounds > 0
-							) {
-								fixOutcome = await runFixRounds(gateReview);
-							}
-							await runFinalDocumentation(
-								fixOutcome.lastWorker ?? initialStepResult,
-								fixOutcome.lastReview ?? gateReview,
-							);
+						let fixOutcome: Awaited<ReturnType<typeof runFixRounds>> = {};
+						if (
+							!isFailedResult(gateReview) &&
+							canContinue() &&
+							reviewVerdict(getResultOutput(gateReview)) === "fail" &&
+							enabled("worker") &&
+							request.config.maxFixRounds > 0
+						) {
+							fixOutcome = await runFixRounds(gateReview);
 						}
+						await runFinalDocumentation(
+							fixOutcome.lastWorker ?? initialStepResult,
+							fixOutcome.lastReview ?? gateReview,
+						);
 					} else {
 						// No gate configured: the documenter is the only downstream stage.
 						await runFinalDocumentation(initialStepResult, undefined);

package/src/fixloop.ts

@@ -1,14 +1,14 @@
 /**
  * Managed workflow policy and handoff formatting.
  *
- * Successful top-level writers continue through an independent code review
- * gate; bounded worker → reviewer fix rounds close its findings; one final
- * documentation sync runs after the gate settles, so code fixes never
- * invalidate an earlier docs pass and reviewers stay focused on code. A direct
- * passing reviewer gets that same single final documentation sync instead of a
- * second gate; a direct failing reviewer uses the same fix rounds plus the
- * final sync. Internal steps are launched by dispatch directly, so they never
- * re-enter this top-level policy or wake the main agent mid-chain.
+ * Successful top-level worker/cleaner runs continue through an independent
+ * code review gate; bounded worker → reviewer fix rounds close its findings.
+ * Reviewers classify documentation drift explicitly, so the low-cost final
+ * documenter runs only when needed (or conservatively when an older/custom
+ * reviewer omits the marker). Direct passing/failing gates use the same policy.
+ * Top-level documenters are explicit standalone writing tasks. Internal steps
+ * are launched by dispatch directly, so they never re-enter this policy or wake
+ * the main agent mid-chain.
  */
 
 import { isWriteCapableAgent, type AgentConfig } from "./agents.ts";
@@ -58,6 +58,20 @@ export function workflowAgentAvailability(
 	};
 }
 
+export type DocumentationDisposition = "clean" | "needed";
+
+/** Only the last standalone documentation disposition line counts. Inline
+ * examples and prose are ignored so a prompt echo cannot suppress a needed
+ * conservative sync. */
+export function documentationDisposition(output: string): DocumentationDisposition | undefined {
+	const lines = output.split("\n");
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const match = /^\s*DOCUMENTATION:\s*(CLEAN|NEEDED)\s*$/i.exec(lines[index]);
+		if (match) return match[1].toUpperCase() === "CLEAN" ? "clean" : "needed";
+	}
+	return undefined;
+}
+
 export type ManagedWorkflowKind = "auto-fix" | "post-writer" | "review-pass-sync";
 
 export interface ManagedWorkflowPlan {
@@ -101,17 +115,20 @@ export function getManagedWorkflowPlan(
 			initialRelation: result.agent === "cleaner" ? "initial cleanup" : "initial implementation",
 		};
 	}
-	if (result.agent === "documenter") {
-		return availability.reviewer
-			? { kind: "post-writer", initialRelation: "documentation pass" }
-			: undefined;
-	}
+	// A top-level documenter is already an explicit docs/comments write task. It
+	// owns the writer lane but delivers directly without an automatic code gate.
+	if (result.agent === "documenter") return undefined;
 	if (result.agent !== "reviewer") return undefined;
 
-	const verdict = reviewVerdict(getResultOutput(result));
-	// The pass stands as the code gate; documenter then syncs docs once and the
-	// workflow delivers without a second gate.
-	if (verdict === "pass" && availability.documenter) {
+	const output = getResultOutput(result);
+	const verdict = reviewVerdict(output);
+	// The pass stands as the code gate. Run the conditional documenter only for
+	// explicit drift or when an older/custom reviewer omitted the marker.
+	if (
+		verdict === "pass" &&
+		availability.documenter &&
+		documentationDisposition(output) !== "clean"
+	) {
 		return { kind: "review-pass-sync", initialRelation: "pre-documentation review" };
 	}
 	if (verdict === "fail" && availability.worker && shouldTriggerFixLoop(result, config)) {
@@ -139,19 +156,21 @@ export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, m
 		`Fix EVERY finding in the reviewer's findings list — there is no severity triage; all of them get fixed.`,
 		`If a finding is factually wrong or clearly out of scope, say so explicitly instead of fixing it.`,
 		`Do NOT refactor unrelated code beyond what the findings require.`,
-		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent chain still owns re-review and the final documentation sync.`,
+		`Synchronize any existing README/docs/examples/comments directly affected by your fixes; do not broaden into standalone documentation maintenance.`,
+		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent chain still owns re-review and any conditional final documentation sync.`,
 		`After editing, run the project's format/build/tests when they exist and report`,
 		`exactly what you changed (paths + short rationale) so a reviewer can verify.`,
 		remaining > 0
 			? `A reviewer will re-review your changes automatically after you finish.`
-			: `This is the last auto-fix round; the workflow runs any enabled final documentation sync and then delivers.`,
+			: `This is the last auto-fix round; the workflow conditionally runs any needed final documentation sync and then delivers.`,
 	].join("\n");
 }
 
-/** Build the single documentation handoff that runs after the review gate
- * settles. The last writer's report (top-level writer or final fix-round
- * worker) and the terminal gate review are leads; the pending diff stays
- * authoritative. At most one of the two is undefined in every managed flow. */
+/** Build the single documentation handoff selected after the review gate
+ * settles or as the reviewer-disabled fallback. The last writer's report
+ * (top-level writer or final fix-round worker) and the terminal gate review are
+ * leads; the pending diff stays authoritative. At most one of the two is
+ * undefined in every managed flow. */
 export function buildFinalDocumenterBrief(
 	lastWriterResult?: SingleResult,
 	finalReviewResult?: SingleResult,
@@ -247,7 +266,7 @@ export function formatChainSummary(
 	);
 }
 
-/** One clear final delivery for all newly managed writer/documenter workflows. */
+/** One clear final delivery for post-writer and direct reviewer → documenter workflows. */
 export function formatManagedWorkflowSummary(
 	steps: readonly ChainStep[],
 	terminalResult: SingleResult = steps[steps.length - 1]!.result,
@@ -262,8 +281,9 @@ export function formatManagedWorkflowSummary(
 }
 
 export interface GateBriefOptions {
-	/** A final documenter runs after the gate settles. Documentation drift is
-	 * then routed to it as non-gating notes instead of failing the gate. */
+	/** A conditional final documenter is available after the gate settles.
+	 * Documentation drift is then routed to it as non-gating notes instead of
+	 * failing the code gate. */
 	documenterPending: boolean;
 }
 
@@ -286,11 +306,14 @@ export function buildFinalReviewBrief(
 		`Remain read-only. Verify correctness, regressions, and tests.`,
 		...(options.documenterPending
 			? [
-				`Documentation sync runs AFTER this gate, so documentation drift is not a gate finding: record needed`,
-				`documentation updates as a separate short "## Documentation notes" list for the final documenter,`,
-				`and fail the gate only for code or test findings.`,
+				`A conditional documentation sync is available AFTER this gate, so documentation drift is not a code-gate finding.`,
+				`If documentation is stale, add a separate short "## Documentation notes" list and emit the standalone line`,
+				`DOCUMENTATION: NEEDED. If no documentation update is needed, emit DOCUMENTATION: CLEAN instead.`,
+				`Always emit exactly one of those standalone documentation lines; fail the gate only for code or test findings.`,
 			]
-			: []),
+			: [
+				`No documenter is pending, so documentation drift is an ordinary gate finding.`,
+			]),
 		`This is an acceptance gate, not an advisory audit. End with exactly one standalone machine verdict line:`,
 		`VERDICT: REVIEW_PASS when no finding remains, otherwise VERDICT: REVIEW_FAIL.`,
 	].join("\n");
@@ -332,9 +355,12 @@ export function buildReReviewBrief(
 		`Do NOT re-open a finding you verified as resolved.`,
 		...(options.documenterPending
 			? [
-				`Carry any unresolved "## Documentation notes" forward verbatim; the final documenter applies them after the chain settles.`,
+				`Carry unresolved "## Documentation notes" forward and add any newly exposed drift there; documentation drift is not a code-gate finding.`,
+				`Emit exactly one standalone documentation disposition line: DOCUMENTATION: NEEDED when that notes section is required, otherwise DOCUMENTATION: CLEAN.`,
 			]
-			: []),
+			: [
+				`No documenter is pending, so unresolved documentation drift remains an ordinary gate finding.`,
+			]),
 		`REQUEST_CHANGES only while an open finding remains; otherwise APPROVE.`,
 		`End with your machine-readable verdict line as usual (VERDICT: REVIEW_PASS / REVIEW_FAIL).`,
 	].join("\n");

package/src/monitor.ts

@@ -20,6 +20,15 @@ import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 
 export type RunStatus = "queued" | "running" | "steering" | "interrupting" | "parked" | "done" | "failed";
 export type ContinuationKind = "resume-retained" | "resume-appended" | "fork-retained" | "fork-appended" | "retarget";
+export type WorkflowStageStatus = "done" | "active" | "pending" | "changes" | "failed";
+
+/** Ephemeral projection of one real or currently planned managed stage. It is
+ * live monitor state only; durable results remain the per-run chain records. */
+export interface WorkflowStage {
+	agent: string;
+	relation: string;
+	status: WorkflowStageStatus;
+}
 
 export function isRunActiveStatus(status: RunStatus): boolean {
 	return status === "queued" || status === "running" || status === "steering" || status === "interrupting";
@@ -65,6 +74,9 @@ export interface RunView {
 	/** This stable top-level row currently owns a multi-stage managed workflow.
 	 * Its elapsed time is workflow-wide; active child rows own stage telemetry. */
 	managedWorkflow?: boolean;
+	/** Live-only stage timeline retained on the parent while completed internal
+	 * child rows leave the monitor. */
+	workflowStages?: WorkflowStage[];
 }
 
 /** Optional metadata for documenter/reviewer/fix children of a stable parent run. */
@@ -481,6 +493,18 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		run.managedWorkflow = active || undefined;
+		if (!active) run.workflowStages = undefined;
+		this.notify();
+	}
+
+	/** Replace the live workflow projection atomically so renderers never observe
+	 * a half-updated fix/re-review plan. */
+	setWorkflowStages(id: number, stages: readonly WorkflowStage[]): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.workflowStages = stages.length > 0
+			? stages.map((stage) => ({ ...stage }))
+			: undefined;
 		this.notify();
 	}
 
@@ -615,6 +639,7 @@ export class MonitorStore {
 		run.usage = emptyUsage();
 		run.activity = undefined;
 		run.managedWorkflow = undefined;
+		run.workflowStages = undefined;
 		run.activeSince = undefined;
 		run.endedAt = undefined;
 		run.elapsedMs = Math.max(run.elapsedMs, meta?.elapsedMs ?? 0);

package/src/prompt.ts

@@ -29,14 +29,7 @@ export function buildDelegationDirective(
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
 	];
-	const reviewedWriterNames = [
-		...codeWriterNames,
-		...(hasDocumenter ? ["documenter"] : []),
-	];
-	const automaticWriterRoute = [
-		...(hasReviewer ? ["reviewer"] : []),
-		...(hasDocumenter ? ["documenter"] : []),
-	].join(" → ");
+	const reviewedWriterNames = [...codeWriterNames];
 	const namedWorktreeTargets = [
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
@@ -47,34 +40,43 @@ export function buildDelegationDirective(
 		: namedWorktreeTargets.length === 1
 			? `${namedWorktreeTargets[0]} or another`
 			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
+	const managedWriterWorkflowRule = reviewedWriterNames.length === 0
+		? undefined
+		: hasReviewer && hasDocumenter
+			? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate. Only REVIEW_PASS can authorize documenter, which runs for DOCUMENTATION: NEEDED or a missing marker; the workflow delivers once. Never duplicate stages.`
+			: hasReviewer
+				? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate and then deliver once; never duplicate the gate.`
+				: hasDocumenter
+					? `With reviewer disabled, successful top-level ${reviewedWriterNames.join("/")} runs use documenter as the conservative final fallback and then deliver once; never duplicate the fallback.`
+					: undefined;
 
 	const dispatchRules = [
-		"Handle simple work inline with direct tools: one-line lookups, known-target reads/edits, and quick questions do not justify a child process.",
+		"Keep small, known-target work in the main thread with direct tools: lookups and focused reads/edits do not justify a child context.",
 		...(hasExplorer
 			? [
-				"Use `explorer` proactively when reconnaissance becomes broad or crosses files: mapping unfamiliar code, tracing symbols/dependencies, or answering multi-file location/reference questions. Treat its output only as a retrieval index; re-read load-bearing files before edits or decisions about deletion, security, compatibility, persistence, or dynamic reachability. Use a stronger model/specialist for complex dynamic, concurrent, migration, or security-sensitive analysis.",
+				"Use `explorer` proactively only for broad or cross-file reconnaissance: mapping unfamiliar code, tracing symbols/dependencies, or finding multi-file references. It is a lightweight retrieval index, never an automatic gate. Re-read load-bearing files before edits or high-risk decisions. Use a stronger model/specialist for dynamic, concurrent, migration, or security analysis.",
 			]
 			: []),
 		...(hasWorker
-			? ["Use `worker` for a self-contained implementation, fix, refactor, or test task whose separate context pays for itself."]
+			? ["Use `worker` for a self-contained implementation, fix, refactor, or test whose separate context pays for itself—not a small known-target edit."]
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance. Once dispatched, it applies every safe proven in-scope cut without item-by-item approval; zero edits is valid only if none is proved. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only as the separate evidence-first entry for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance; never substitute it for \`worker\`. It applies every safe proven in-scope cut without item-by-item approval. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
 			]
 			: []),
 		...(hasDocumenter
 			? [
-				`Use \`documenter\` directly for explicit whole-codebase maintenance or standalone documentation work.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already auto-sync the actual diff once after the review gate; never dispatch a duplicate.` : ""} Zero edits is valid and broad mode is never inferred. It changes docs/comments only and never runtime behavior, versions, or release state.`,
+				`Use \`documenter\` directly only for explicit whole-codebase maintenance or standalone documentation/comment work; a top-level documenter delivers directly without an automatic reviewer.${codeWriterNames.length > 0 ? ` ${codeWriterNames.join("/")} must sync existing docs they directly affect; runtime runs documenter only after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback—never dispatch a duplicate.` : ""} It never changes runtime behavior, versions, or release state.`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for read-only assessments or an explicit gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get a fresh read-only reviewer gate.` : ""} Advisory output has no VERDICT: it stays read-only and does not authorize follow-up edits.`,
+				`Use \`reviewer\` for read-only assessments or a gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get one fresh read-only reviewer gate, independent of the writer.` : ""} Advisory output has no VERDICT and cannot authorize follow-up edits${hasDocumenter ? "; gates classify docs separately for the enabled documenter." : "."}`,
 			]
 			: []),
-		"Brief every child with the complete goal, exact paths, constraints, and expected output. It has no memory of this conversation.",
-		"Children are leaf processes without delegation tools. Do not ask them to spawn sub-agents; use `subagent_control fork` on a parked/settled retained thread for an independent continuation.",
+		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory.",
+		"Children are leaf processes without delegation tools; use `subagent_control fork` on a parked/settled thread for an independent continuation.",
 		...(hasMultiple
 			? [
 				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
@@ -86,24 +88,20 @@ export function buildDelegationDirective(
 	];
 
 	const handoffRules = [
-		"Dispatch returns immediately and ends this turn. Never sleep, poll, or call `subagent_wait` to hold the turn; results arrive as messages that automatically resume the main agent, even mid-turn.",
-		"Use `subagent_wait` with explicit `timeoutMs` only when the user specifically asks you to remain in-turn and wait. Its default lookup is non-blocking.",
-		"A result is already shown to the user. Do not restate, paraphrase, or re-summarize it; add only your conclusion or next action, often one line.",
+		"Dispatch ends this turn; results resume the main agent, even mid-turn. Never sleep, poll, or call `subagent_wait` to hold the turn.",
+		"Use `subagent_wait` with explicit `timeoutMs` only when the user asks to wait in-turn; its default lookup is non-blocking.",
+		"Results are already shown. Do not restate, paraphrase, or re-summarize them; add only your conclusion or next action.",
 		"A delivered result does not mean siblings are finished. Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
 	];
 
 	const verificationRules = [
 		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
-		...(automaticWriterRoute && reviewedWriterNames.length > 0
-			? [
-				`Successful top-level write roles automatically continue through enabled downstream roles (${automaticWriterRoute}) to one final delivery; never duplicate stages.`,
-			]
-			: []),
+		...(managedWriterWorkflowRule ? [managedWriterWorkflowRule] : []),
 		...(hasReviewer
 			? [
 				...(hasDocumenter
 					? [
-						`A direct REVIEW_PASS is final for code: runtime runs the final documentation sync once and delivers. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps auto-fix; maxFixRounds limits worker fixes only, not the final documentation sync." : "cannot start fixes while worker/fix rounds are disabled."}`,
+						`A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps bounded worker/reviewer auto-fix, with docs considered only after its terminal REVIEW_PASS." : "cannot start fixes while worker/fix rounds are disabled."}`,
 					]
 					: []),
 				"Resolve every gate finding; do not bypass the configured auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
@@ -116,7 +114,7 @@ export function buildDelegationDirective(
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-The \`subagent\` tool starts specialized leaf agents in isolated Pi child processes and context windows. It returns immediately; completion messages automatically resume the main agent.
+The \`subagent\` tool starts isolated Pi child processes and context windows. Completions automatically resume the main agent.
 
 Available agents:
 ${catalog}