@ferris1225/pi-subagents 4.1.3 → 4.1.5

package/src/dispatch.ts

@@ -1,9 +1,10 @@
 /**
  * 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 → documenter → reviewer workflows,
- * reviewer auto-fix rounds, and internal step launching. Stable thread
- * generations, final integration, and completion ownership live in
+ * 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.
  */
 
@@ -17,12 +18,11 @@ import { discoverAgents, resolveAgentTools, type AgentConfig } from "./agents.ts
 import { loadConfig } from "./config.ts";
 import { formatUsage, queuedResult } from "./format.ts";
 import {
-	buildDocumenterTaskBrief,
+	buildFinalDocumenterBrief,
 	buildFinalReviewBrief,
 	buildFixTaskBrief,
-	buildPostWriterDocumenterBrief,
 	buildReReviewBrief,
-	buildReviewPassDocumenterBrief,
+	documentationDisposition,
 	type ChainStep,
 	type ManagedWorkflowOutcome,
 } from "./fixloop.ts";
@@ -32,6 +32,8 @@ import {
 	monitor,
 	statusIcon,
 	type RunChainMeta,
+	type WorkflowStage,
+	type WorkflowStageStatus,
 } from "./monitor.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import {
@@ -87,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> {
@@ -169,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) {
@@ -389,57 +399,162 @@ 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;
+					}
 				};
 
-				const runFixRounds = async (triggeringReviewer: SingleResult): Promise<void> => {
+				/** 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 }> => {
 					let lastReviewer = triggeringReviewer;
+					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 (!canContinue() || isFailedResult(workerResult)) break;
-
-						let documenterResult: SingleResult | undefined;
-						if (enabled("documenter")) {
-							documenterResult = await launchStep(
-								"documenter",
-								buildDocumenterTaskBrief(workerResult, round, lastReviewer),
-								`docs round ${round}`,
-							);
-							if (!canContinue() || isFailedResult(documenterResult)) break;
-						}
+						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, documenterResult),
+							buildReReviewBrief(lastReviewer, round, workerResult, {
+								documenterPending: enabled("documenter"),
+							}),
 							`re-review round ${round}`,
+							{ timelineRelation: reReviewRelation, childRelation: reReviewRelation },
 						);
-						if (!canContinue() || isFailedResult(reviewResult)) break;
+						if (isFailedResult(reviewResult) || !canContinue()) break;
+						outcome.lastReview = reviewResult;
 						const verdict = reviewVerdict(getResultOutput(reviewResult));
 						// REVIEW_PASS settles. No verdict is advisory/malformed and must never
 						// trigger another writer. Only an explicit REVIEW_FAIL consumes a fix.
 						if (verdict !== "fail") break;
 						lastReviewer = reviewResult;
 					}
+					return outcome;
+				};
+
+				/** 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") {
+						removeDocumentationStage();
+						return;
+					}
+					if (finalReviewResult) {
+						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 },
+					);
 				};
 
 				try {
@@ -448,43 +563,36 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					// never create an already-aborted downstream child.
 					if (!canContinue()) return { kind: request.plan.kind, steps };
 					if (request.plan.kind === "auto-fix") {
-						await runFixRounds(initialStepResult);
-					} else {
-						let documenterResult: SingleResult | undefined;
-						if (request.plan.kind === "review-pass-sync") {
-							documenterResult = await launchStep(
-								"documenter",
-								buildReviewPassDocumenterBrief(initialStepResult),
-								"documentation sync",
-							);
-						} else if (initialStepResult.agent !== "documenter" && enabled("documenter")) {
-							documenterResult = await launchStep(
-								"documenter",
-								buildPostWriterDocumenterBrief(initialStepResult),
-								"documentation sync",
-							);
-						}
-
+						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. 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 },
+						);
+						let fixOutcome: Awaited<ReturnType<typeof runFixRounds>> = {};
 						if (
+							!isFailedResult(gateReview) &&
 							canContinue() &&
-							(!documenterResult || !isFailedResult(documenterResult)) &&
-							enabled("reviewer")
+							reviewVerdict(getResultOutput(gateReview)) === "fail" &&
+							enabled("worker") &&
+							request.config.maxFixRounds > 0
 						) {
-							const reviewResult = await launchStep(
-								"reviewer",
-								buildFinalReviewBrief(initialStepResult, documenterResult),
-								"final review",
-							);
-							if (
-								canContinue() &&
-								!isFailedResult(reviewResult) &&
-								reviewVerdict(getResultOutput(reviewResult)) === "fail" &&
-								enabled("worker") &&
-								request.config.maxFixRounds > 0
-							) {
-								await runFixRounds(reviewResult);
-							}
+							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);
 					}
 					return { kind: request.plan.kind, steps };
 				} finally {

package/src/fixloop.ts

@@ -1,12 +1,14 @@
 /**
  * Managed workflow policy and handoff formatting.
  *
- * Successful top-level writers can continue through documentation sync and an
- * independent final review. A direct passing reviewer is also forced through
- * documentation sync plus a fresh review when documenter is enabled. Any final
- * gate failure may then use the established worker → optional documenter →
- * reviewer fix rounds. 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";
@@ -56,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 {
@@ -99,15 +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));
-	if (verdict === "pass" && availability.documenter && availability.reviewer) {
+	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)) {
@@ -135,77 +156,58 @@ 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 documentation sync and final review.`,
+		`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; optional documentation sync and a fresh reviewer still run before final delivery.`,
+			: `This is the last auto-fix round; the workflow conditionally runs any needed final documentation sync and then delivers.`,
 	].join("\n");
 }
 
-interface DocumentationBriefOptions {
-	title: string;
-	reports: Array<{ label: string; result: SingleResult }>;
-	closing: string;
-}
-
-function buildDocumentationBrief(options: DocumentationBriefOptions): string {
-	const reportSections = options.reports.flatMap(({ label, result }) => [
-		`${label}:`,
-		`---`,
-		getResultOutput(result),
-		`---`,
-		``,
-	]);
+/** 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,
+): string {
+	const reportSections = [
+		...(lastWriterResult
+			? [
+				`The last writer (${lastWriterResult.agent}) reported:`,
+				`---`,
+				getResultOutput(lastWriterResult),
+				`---`,
+				``,
+			]
+			: []),
+		...(finalReviewResult
+			? [
+				`The final gate review reported:`,
+				`---`,
+				getResultOutput(finalReviewResult),
+				`---`,
+				``,
+			]
+			: []),
+	];
 	return [
-		options.title,
+		`Final documentation sync: the review gate settled and you are the last managed stage before delivery.`,
 		``,
 		...reportSections,
-		`Inspect the actual git diff (the complete pending diff) and relevant implementation; the report is only a lead.`,
-		`Synchronize stale README/docs, examples, API comments, docstrings, and explanatory comments with the behavior that will be committed.`,
+		`Inspect the actual git diff (the complete pending diff) and relevant implementation; the reports are only leads.`,
+		`Apply every documentation note the reviews recorded, then synchronize stale README/docs, examples, API comments, docstrings, and explanatory comments with the behavior that will be committed.`,
 		`Change documentation surfaces only; never alter runtime behavior or tests to make prose true.`,
 		`Make zero edits when the diff creates no documentation drift.`,
-		`Do NOT commit, push, publish, tag, or release; do not bump versions. ${options.closing}`,
+		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent workflow delivers directly after you; no fresh reviewer runs.`,
 		`Report exact documentation/comment paths changed, or state explicitly that no sync was needed.`,
 	].join("\n");
 }
 
-/** Build the pre-commit documentation handoff after one auto-fix worker. */
-export function buildDocumenterTaskBrief(
-	workerResult: SingleResult,
-	round: number,
-	reviewerResult?: SingleResult,
-): string {
-	return buildDocumentationBrief({
-		title: `Documentation sync after auto-fix round ${round}.`,
-		reports: [
-			...(reviewerResult ? [{ label: "The triggering reviewer reported", result: reviewerResult }] : []),
-			{ label: "The worker reported", result: workerResult },
-		],
-		closing: "a fresh reviewer gate runs after you.",
-	});
-}
-
-/** Build the automatic documentation stage after a successful top-level writer. */
-export function buildPostWriterDocumenterBrief(writerResult: SingleResult): string {
-	return buildDocumentationBrief({
-		title: `Documentation sync after successful top-level ${writerResult.agent}.`,
-		reports: [{ label: `The ${writerResult.agent} reported`, result: writerResult }],
-		closing: "the managed workflow owns any final reviewer and delivery.",
-	});
-}
-
-/** A direct passing review cannot be the final gate while documenter is enabled:
- * the preliminary report is context, but the actual pending diff is authoritative. */
-export function buildReviewPassDocumenterBrief(reviewerResult: SingleResult): string {
-	return buildDocumentationBrief({
-		title: "Documentation sync required before accepting a direct passing review.",
-		reports: [{ label: "The preliminary reviewer reported", result: reviewerResult }],
-		closing: "the preliminary pass is not final and a fresh reviewer gate runs after you.",
-	});
-}
-
 /**
  * One step of an auto-fix chain as delivered: the run id (so the condensed
  * summary can point at per-run detail via subagent_status), the result, and
@@ -264,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,
@@ -278,33 +280,40 @@ export function formatManagedWorkflowSummary(
 	);
 }
 
-/** Build the first independent final gate after a top-level writer or required
- * post-pass documentation sync. Reports carry intent; the actual pending diff
- * remains authoritative. */
+export interface GateBriefOptions {
+	/** 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;
+}
+
+/** Build the code gate that runs directly after a top-level writer, before any
+ * documentation. Reports carry intent; the actual pending diff remains
+ * authoritative. */
 export function buildFinalReviewBrief(
 	initialResult: SingleResult,
-	documenterResult?: SingleResult,
+	options: GateBriefOptions,
 ): string {
-	const documenterSection = documenterResult
-		? [
-			``,
-			`The documenter's full sync report:`,
-			`---`,
-			getResultOutput(documenterResult),
-			`---`,
-		]
-		: [];
 	return [
-		`Fresh final gate for a managed ${initialResult.agent} workflow.`,
+		`Fresh code gate for a managed ${initialResult.agent} workflow.`,
 		``,
 		`The top-level ${initialResult.agent}'s full report:`,
 		`---`,
 		getResultOutput(initialResult),
 		`---`,
-		...documenterSection,
 		``,
-		`Run \`git status\` and \`git diff\` and inspect the actual pending code and documentation; reports are context, not proof.`,
-		`Remain read-only. Verify correctness, regressions, tests, documentation drift, and that documenter was the last writer when it ran.`,
+		`Run \`git status\` and \`git diff\` and inspect the actual pending code; the report is context, not proof.`,
+		`Remain read-only. Verify correctness, regressions, and tests.`,
+		...(options.documenterPending
+			? [
+				`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");
@@ -312,29 +321,19 @@ export function buildFinalReviewBrief(
 
 /**
  * The re-review brief handed to the reviewer after a worker fix round. Includes
- * the prior review, worker report, and optional documenter report so the
- * reviewer can adjudicate rejections instead of restating findings. The
- * convergence contract keeps rounds from ping-ponging: rule on the open
- * findings once, add only defects this round's edits introduced, never re-open
- * a verified resolution.
+ * the prior review and worker report so the reviewer can adjudicate rejections
+ * instead of restating findings. The convergence contract keeps rounds from
+ * ping-ponging: rule on the open findings once, add only defects this round's
+ * edits introduced, never re-open a verified resolution.
  */
 export function buildReReviewBrief(
 	reviewerResult: SingleResult,
 	round: number,
 	workerResult: SingleResult,
-	documenterResult?: SingleResult,
+	options: GateBriefOptions = { documenterPending: false },
 ): string {
 	const review = getResultOutput(reviewerResult);
 	const workerReport = getResultOutput(workerResult);
-	const documenterSection = documenterResult
-		? [
-			``,
-			`The documenter's pre-commit sync report:`,
-			`---`,
-			getResultOutput(documenterResult),
-			`---`,
-		]
-		: [];
 	return [
 		`Re-review after auto-fix round ${round}.`,
 		``,
@@ -347,7 +346,6 @@ export function buildReReviewBrief(
 		`---`,
 		workerReport,
 		`---`,
-		...documenterSection,
 		``,
 		`Rule on EVERY previous finding: resolved, or still open. A finding the worker rejected must be`,
 		`adjudicated ONCE — accept the rejection unless you can concretely refute the worker's reasoning;`,
@@ -355,6 +353,14 @@ export function buildReReviewBrief(
 		`Run \`git diff\` to see what changed, then add NEW findings only when they are defects this round's`,
 		`edits introduced or exposed (or a load-bearing issue the earlier review genuinely missed).`,
 		`Do NOT re-open a finding you verified as resolved.`,
+		...(options.documenterPending
+			? [
+				`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");