@ferris1225/pi-subagents 4.1.3 → 4.1.4

package/src/dispatch.ts

@@ -1,9 +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 → 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 writer → reviewer → documenter workflows,
+ * bounded worker/reviewer fix rounds, and internal step launching. Stable
+ * thread generations, final integration, and completion ownership live in
  * thread-lifecycle.ts.
  */
 
@@ -17,12 +17,10 @@ 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,
 	type ChainStep,
 	type ManagedWorkflowOutcome,
 } from "./fixloop.ts";
@@ -407,8 +405,14 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					return step.result;
 				};
 
-				const runFixRounds = async (triggeringReviewer: SingleResult): Promise<void> => {
+				/** 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. */
+				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 workerResult = await launchStep(
@@ -416,30 +420,46 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							buildFixTaskBrief(lastReviewer, round, request.config.maxFixRounds),
 							`fix round ${round}`,
 						);
-						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 reviewResult = await launchStep(
 							"reviewer",
-							buildReReviewBrief(lastReviewer, round, workerResult, documenterResult),
+							buildReReviewBrief(lastReviewer, round, workerResult, {
+								documenterPending: enabled("documenter"),
+							}),
 							`re-review round ${round}`,
 						);
-						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;
+				};
+
+				/** 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). */
+				const runFinalDocumentation = async (
+					lastWriterResult: SingleResult | undefined,
+					finalReviewResult: SingleResult | undefined,
+				): Promise<void> => {
+					if (!canContinue() || !enabled("documenter")) return;
+					if (lastWriterResult?.agent === "documenter") return;
+					if (finalReviewResult) {
+						if (isFailedResult(finalReviewResult)) return;
+						if (reviewVerdict(getResultOutput(finalReviewResult)) === "fail") return;
+					}
+					await launchStep(
+						"documenter",
+						buildFinalDocumenterBrief(lastWriterResult, finalReviewResult),
+						"final documentation sync",
+					);
 				};
 
 				try {
@@ -448,43 +468,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",
-							);
-						}
-
-						if (
-							canContinue() &&
-							(!documenterResult || !isFailedResult(documenterResult)) &&
-							enabled("reviewer")
-						) {
-							const reviewResult = await launchStep(
-								"reviewer",
-								buildFinalReviewBrief(initialStepResult, documenterResult),
-								"final review",
-							);
+						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.
+						await runFinalDocumentation(undefined, initialStepResult);
+					} else if (enabled("reviewer")) {
+						const gateReview = await launchStep(
+							"reviewer",
+							buildFinalReviewBrief(initialStepResult, { documenterPending: enabled("documenter") }),
+							"final review",
+						);
+						if (!isFailedResult(gateReview)) {
+							let fixOutcome: Awaited<ReturnType<typeof runFixRounds>> = {};
 							if (
 								canContinue() &&
-								!isFailedResult(reviewResult) &&
-								reviewVerdict(getResultOutput(reviewResult)) === "fail" &&
+								reviewVerdict(getResultOutput(gateReview)) === "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 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.
  */
 
 import { isWriteCapableAgent, type AgentConfig } from "./agents.ts";
@@ -107,7 +109,9 @@ export function getManagedWorkflowPlan(
 	if (result.agent !== "reviewer") return undefined;
 
 	const verdict = reviewVerdict(getResultOutput(result));
-	if (verdict === "pass" && availability.documenter && availability.reviewer) {
+	// 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) {
 		return { kind: "review-pass-sync", initialRelation: "pre-documentation review" };
 	}
 	if (verdict === "fail" && availability.worker && shouldTriggerFixLoop(result, config)) {
@@ -135,77 +139,56 @@ 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.`,
+		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent chain still owns re-review and the 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 runs any enabled 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 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. */
+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
@@ -278,33 +261,36 @@ 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 final documenter runs after the gate settles. Documentation drift is
+	 * then routed to it as non-gating notes instead of failing the 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
+			? [
+				`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.`,
+			]
+			: []),
 		`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 +298,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 +323,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 +330,11 @@ 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 any unresolved "## Documentation notes" forward verbatim; the final documenter applies them after the chain settles.`,
+			]
+			: []),
 		`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");