feat(pi-subagent): add opinionated delegated development (#169)

Author: HenryQW

docs/adr/016-pi-subagent-architecture.md

@@ -14,6 +14,7 @@ Delegation needs portable user-owned capabilities, shared model policy, bounded
 - Model and thinking routes remain separate from Role capability. They resolve through `@henryqw/pi-task-models`; fallback is attempted only before launch, and a started child is never retried.
 - Each `delegate_task` runs one bounded task in an ephemeral `pi --mode json -p --no-session` child with abort propagation, configurable idle/hard deadlines, and bounded concurrency. Main owns decomposition, integration, and cross-cutting decisions.
 - Main-visible streaming updates, results, and errors are capped at 50 KiB. Unused JSON event payloads are discarded before buffering.
+- The bundled delegated-development Skill is Main-side policy only: it fails before delegation without a committed Git `HEAD`, reviews only an exact verified base-to-tip committed patch with referenced files, and merges only the reviewed commit. It does not change the generic non-Git/unborn-`HEAD` fallback.
 - Generic managed Herdr hosting is a separate library surface for workers that must survive orchestrator pauses or restarts. Callers retain domain prompts, state, and lifecycle decisions.
 - The TUI widget projects active ephemeral children and briefly shows terminal status; it owns no lifecycle state.
 

package-lock.json

@@ -37,8 +37,8 @@ System-owned identity binding reviewer verdict to run, review kind, Local Issue,
 _Avoid_: Reviewer correlation field, model token
 
 **Review Packet**:
-Canonical fresh reviewer handoff containing delivery context, Local Issue, worktree, base, and Required Gate. Existing reviewers receive only changed gate, findings, or resolution data.
-_Avoid_: Reviewer prompt variant, echoed orchestration state
+Canonical fresh reviewer handoff containing delivery context, Local Issue, worktree, base, Required Gate, and a read-only exact binary patch artifact. The artifact is atomically persisted privately under the run directory after base/commit verification and identifies its path, base, commit, byte count, SHA-256, and deterministic child-branch or explicit integration-head context; its patch body is never in the prompt. Existing reviewers receive only changed gate, findings, or resolution data.
+_Avoid_: Reviewer prompt variant, inline diff, echoed orchestration state
 
 **Local Issue**:
 Immutable work definition identified by a stable string within a Delivery Graph.

packages/pi-auto-dag/CONTEXT.md

@@ -102,7 +102,7 @@ Pass the exact graph object to `auto_dag_execute`. It is immutable for the durat
 
 1. The caller normalizes an approved plan into the exact graph and calls `auto_dag_execute`. Planning is externally owned (for example by `/ship`).
 2. Auto DAG validates structure, then shows one TUI confirmation bound to the SHA-256 of the exact graph. It display-escapes every exact `testing` command that will later run through `sh -c`, alongside both fixed Roles. Execution never starts without this confirmation.
-3. Ready tasks share one Git base at the frozen HEAD. Each gets a child worktree, the fixed implementer Role, one required commit, and the exact `testing` command through `sh -c`. The fixed reviewer Role sees the commit and gate evidence; approval requires system-owned exit code `0`.
+3. Ready tasks share one Git base at the frozen HEAD. Each gets a child worktree, the fixed implementer Role, one required commit, and the exact `testing` command through `sh -c`. A fresh fixed reviewer Role receives the commit, gate evidence, and a read-only run-private exact binary patch reference (path, base, commit, size, SHA-256); the patch body is never in its prompt. Approval requires system-owned exit code `0`.
 4. After each wave passes, commits are cherry-picked by Local Issue ID and the next wave starts. A cherry-pick conflict returns that task to its workers.
 5. After every implementation task, Final Check runs on clean integration `HEAD`; product failure repairs through the owning Local Issue.
 6. When all gates pass, Auto DAG pushes one branch and opens exactly one PR. Ownership ends there; post-PR sweep and CI status are caller-owned (for example `/ship`).

packages/pi-auto-dag/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-auto-dag",
-  "version": "8.0.3",
+  "version": "8.0.4",
   "description": "Execute Delivery Graphs through Pi and Herdr.",
   "keywords": [
     "pi-package",
@@ -31,7 +31,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.3"
   },
   "dependencies": {
-    "@henryqw/pi-subagent": "^4.0.0",
+    "@henryqw/pi-subagent": "^4.1.0",
     "proper-lockfile": "^4.1.2",
     "typebox": "1.3.15"
   },

packages/pi-auto-dag/package.json

@@ -15,7 +15,7 @@ import { assertAttachedBranch, deleteExpectedBranch, ensureChildWorktree, findAp
 import { assertRunBoundary } from "./intake.ts";
 import type { LocalIssue, ProjectConfig, RunState, RunTaskState, SubmitReviewEnvelope, WorkerEnvelope } from "./model.ts";
 import { actionTicketPath, ensureActionTicket, type ReviewKind } from "./review-ticket.ts";
-import { reviewPrompt, type ReviewPromptMode } from "./review.ts";
+import { persistReviewPatch, reviewPrompt, reviewPromptMode, type ReviewPromptMode } from "./review.ts";
 import { issueById, replaceTask, task, type Uuid } from "./state.ts";
 import {
 	clearLifecycleCleanupBlock,
@@ -396,18 +396,31 @@ async function ensureFinalRepairReviewer(
 	});
 	current = task(state, issue.id);
 	const needsInstruction = Boolean(current.reviewer_instruction_pending) || mode === "review" || started !== "existing";
-	const promptMode: ReviewPromptMode = !needsInstruction
-		? "resend"
-		: started !== "existing" || current.review_rounds === 1
-			? "full"
-			: "update";
+	const base = nonEmptyString(current.repair_base, "final repair base");
+	const promptMode: ReviewPromptMode = reviewPromptMode(
+		needsInstruction,
+		started,
+		current.review_packet_base,
+		current.review_packet_commit,
+		base,
+		commit,
+	);
 	await ensureActionTicket(
 		actionTicketPath(state.main_worktree, state.run_id, issue.id, "lifecycle", "reviewer"),
 		{ attempt: current.attempts, review_round: positiveInteger(current.review_rounds, "final-gate repair review round"), role: "reviewer", review_id: lifecycleReviewId(state, issue, current, "final_repair") },
 		state.main_worktree,
 		state.run_id,
 		options.uuid,
 	);
+	const patch = promptMode === "full" ? await persistReviewPatch({
+		runner: options.runner,
+		mainWorktree: state.main_worktree,
+		runId: state.run_id,
+		worktree: nonEmptyString(current.worktree, "final repair worktree"),
+		base,
+		commit,
+		context: { type: "child_branch", branch: nonEmptyString(current.branch, "final repair branch") },
+	}) : undefined;
 	const amendments = gateCommandAmendments(state, issue.id);
 	await promptManagedSubagent(workerHost(state), agent, reviewPrompt({
 		kind: "final_repair",
@@ -416,15 +429,20 @@ async function ensureFinalRepairReviewer(
 		worktree: nonEmptyString(current.worktree, "final repair worktree"),
 		base: nonEmptyString(current.repair_base, "final repair base"),
 		gate: requiredTaskGate(current, commit, "Final-gate repair"),
+		patch,
 		prior_findings: current.review_findings,
 		resolution: state.resolutions[owner.id],
 		context: {
 			owner_issue: workerIssueContext(owner, false),
 			...(amendments.length ? { gate_command_amendments: amendments } : {}),
 		},
 	}, promptMode), workerHostOptions(options));
-	if (needsInstruction) {
-		state = await save(replaceTask(state, issue.id, { ...task(state, issue.id), reviewer_instruction_pending: undefined }), options);
+	if (needsInstruction || promptMode === "full") {
+		state = await save(replaceTask(state, issue.id, {
+			...task(state, issue.id),
+			reviewer_instruction_pending: undefined,
+			...(promptMode === "full" ? { review_packet_base: base, review_packet_commit: commit } : {}),
+		}), options);
 	}
 	return state;
 }
@@ -538,10 +556,14 @@ async function ensureRepairWorktree(state: RunState, issue: LocalIssue, options:
 
 async function verifyRepairCommit(state: RunState, issue: LocalIssue, commit: string, options: FinalRepairOptions): Promise<string> {
 	const current = task(state, issue.id);
+	const branch = nonEmptyString(current.branch, "final-gate repair branch");
+	if (branch !== repairBranch(state, repairOwner(state, current).id, positiveInteger(current.repair_attempt, "final-gate repair attempt"))) {
+		throw new Error(`Final-gate repair branch is not its deterministic child branch: ${branch}`);
+	}
 	return await verifyOneCommit(
 		state,
 		nonEmptyString(current.worktree, "final-gate repair worktree"),
-		nonEmptyString(current.branch, "final-gate repair branch"),
+		branch,
 		nonEmptyString(current.repair_base, "final-gate repair base"),
 		commit,
 		"Final-gate repair",

packages/pi-auto-dag/src/final-repair.ts

@@ -15,7 +15,7 @@ import { assertRunBoundary } from "./intake.ts";
 import { assertAttachedBranch, ensureChildWorktree, verifySingleCommit } from "./git.ts";
 import type { LocalIssue, ProjectConfig, RunState, RunTaskState } from "./model.ts";
 import { actionTicketPath, ensureActionTicket, reviewId } from "./review-ticket.ts";
-import { recordGateExecution, reviewPrompt as reviewWorkerPrompt, type ReviewPromptMode } from "./review.ts";
+import { persistReviewPatch, recordGateExecution, reviewPrompt as reviewWorkerPrompt, reviewPromptMode, type ReviewPatchReference, type ReviewPromptMode } from "./review.ts";
 import { replaceTask, task, type Uuid } from "./state.ts";
 import { hasReviewFindings, lifecycleWorkerLaunch, saveRunState as save } from "./worker-protocol.ts";
 import { workerAgentName, workerDeliveryContext, workerHost, workerHostOptions, workerIssueContext, type RoleLaunchResolver, type WorkerLaunch, type WorkerRole } from "./worker.ts";
@@ -226,24 +226,38 @@ export async function ensureReviewer(
 		state = await save(replaceTask(state, issue.id, { ...current, reviewer_instruction_pending: true }), options);
 		current = task(state, issue.id);
 	}
-	const promptMode: ReviewPromptMode = !needsInstruction
-		? "resend"
-		: started !== "existing" || current.review_rounds === 1
-			? "full"
-			: "update";
+	const base = nonEmptyString(current.wave_base, `Run Task ${issue.id} wave_base`);
+	const promptMode: ReviewPromptMode = reviewPromptMode(
+		needsInstruction,
+		started,
+		current.review_packet_base,
+		current.review_packet_commit,
+		base,
+		commit,
+	);
 	await ensureActionTicket(
 		actionTicketPath(state.main_worktree, state.run_id, issue.id, "implementation", "reviewer"),
 		{ attempt: current.attempts, review_round: positiveInteger(current.review_rounds, `Run Task ${issue.id} review round`), role: "reviewer", review_id: taskReviewId(state, issue.id, current) },
 		state.main_worktree,
 		state.run_id,
 		options.uuid,
 	);
-	await promptManagedSubagent(workerHost(state), agent, reviewerPrompt(state, issue, current, promptMode), workerHostOptions(options));
-	if (task(state, issue.id).reviewer_instruction_pending || task(state, issue.id).resolution_pending) {
+	const patch = promptMode === "full" ? await persistReviewPatch({
+		runner: options.runner,
+		mainWorktree: state.main_worktree,
+		runId: state.run_id,
+		worktree: nonEmptyString(current.worktree, `Run Task ${issue.id} worktree`),
+		base,
+		commit,
+		context: { type: "child_branch", branch: nonEmptyString(current.branch, `Run Task ${issue.id} branch`) },
+	}) : undefined;
+	await promptManagedSubagent(workerHost(state), agent, reviewerPrompt(state, issue, current, promptMode, patch), workerHostOptions(options));
+	if (task(state, issue.id).reviewer_instruction_pending || task(state, issue.id).resolution_pending || promptMode === "full") {
 		state = await save(replaceTask(state, issue.id, {
 			...task(state, issue.id),
 			reviewer_instruction_pending: undefined,
 			resolution_pending: undefined,
+			...(promptMode === "full" ? { review_packet_base: base, review_packet_commit: commit } : {}),
 		}), options);
 	}
 	return state;
@@ -359,6 +373,7 @@ function reviewerPrompt(
 	issue: LocalIssue,
 	current: RunTaskState,
 	mode: ReviewPromptMode,
+	patch?: ReviewPatchReference,
 ): Record<string, unknown> {
 	const amendments = gateCommandAmendments(state, issue.id);
 	return reviewWorkerPrompt({
@@ -368,6 +383,7 @@ function reviewerPrompt(
 		worktree: nonEmptyString(current.worktree, `Run Task ${issue.id} worktree`),
 		base: nonEmptyString(current.wave_base, `Run Task ${issue.id} wave_base`),
 		gate: requiredTaskGate(current, nonEmptyString(current.commit, `Run Task ${issue.id} review commit`), `Run Task ${issue.id}`),
+		patch,
 		prior_findings: current.review_findings,
 		resolution: state.resolutions[issue.id],
 		...(amendments.length ? { context: { gate_command_amendments: amendments } } : {}),

packages/pi-auto-dag/src/implementation-workers.ts

@@ -120,6 +120,9 @@ export interface RunTaskState {
 	review_exit_code?: number;
 	review_stdout?: GateOutputEvidence;
 	review_stderr?: GateOutputEvidence;
+	/** Base and commit last delivered to the reviewer in a full packet. */
+	review_packet_base?: string;
+	review_packet_commit?: string;
 	/** Failed Required Gate evidence invalidated by explicit infrastructure retry. */
 	required_gate_invalidations?: RequiredGateInvalidation[];
 	review_findings?: string[];

packages/pi-auto-dag/src/model.ts

@@ -8,7 +8,7 @@ import { assertRunBoundary } from "./intake.ts";
 import type { LocalIssue, ProjectConfig, PullRequestIdentity, RunState, RunTaskState, SubmitReviewEnvelope, WorkerEnvelope } from "./model.ts";
 import { assertSamePullRequest, parsePullRequest, viewOpenPullRequest } from "./pull-request.ts";
 import { actionTicketPath, ensureActionTicket, type ReviewKind } from "./review-ticket.ts";
-import { reviewPrompt, type ReviewPromptMode } from "./review.ts";
+import { persistReviewPatch, reviewPrompt, reviewPromptMode, type ReviewPromptMode } from "./review.ts";
 import { replaceTask, task, type Uuid } from "./state.ts";
 import {
 	finalCheck,
@@ -104,6 +104,7 @@ async function ensureFinalReviewer(
 	let current = task(state, issue.id);
 	const commit = nonEmptyString(current.commit, "final-check commit");
 	if (commit !== state.integration_head) throw new Error("Final-check commit does not match the integration HEAD");
+	await commandOutput(options.runner, "git", ["merge-base", "--is-ancestor", state.source_commit, commit], state.main_worktree);
 	state = await ensureFinalGate(state, issue, commit, config.required_gate_timeout_ms, options);
 	current = task(state, issue.id);
 	const gate = requiredTaskGate(current, commit, "Final check");
@@ -138,18 +139,31 @@ async function ensureFinalReviewer(
 	});
 	current = task(state, issue.id);
 	const needsInstruction = Boolean(current.reviewer_instruction_pending) || mode === "review" || started !== "existing";
-	const promptMode: ReviewPromptMode = !needsInstruction
-		? "resend"
-		: started !== "existing" || current.review_rounds === 1
-			? "full"
-			: "update";
+	const base = state.source_commit;
+	const promptMode: ReviewPromptMode = reviewPromptMode(
+		needsInstruction,
+		started,
+		current.review_packet_base,
+		current.review_packet_commit,
+		base,
+		commit,
+	);
 	await ensureActionTicket(
 		actionTicketPath(state.main_worktree, state.run_id, issue.id, "lifecycle", "reviewer"),
 		{ attempt: current.attempts, review_round: positiveInteger(current.review_rounds, "final-check review round"), role: "reviewer", review_id: lifecycleReviewId(state, issue, current, "final_check") },
 		state.main_worktree,
 		state.run_id,
 		options.uuid,
 	);
+	const patch = promptMode === "full" ? await persistReviewPatch({
+		runner: options.runner,
+		mainWorktree: state.main_worktree,
+		runId: state.run_id,
+		worktree: state.main_worktree,
+		base,
+		commit,
+		context: { type: "integration_head" },
+	}) : undefined;
 	const amendments = gateCommandAmendments(state, issue.id);
 	await promptManagedSubagent(workerHost(state), agent, reviewPrompt({
 		kind: "final_check",
@@ -158,10 +172,15 @@ async function ensureFinalReviewer(
 		worktree: state.main_worktree,
 		base: state.source_commit,
 		gate: requiredTaskGate(current, commit, "Final check"),
+		patch,
 		...(amendments.length ? { context: { gate_command_amendments: amendments } } : {}),
 	}, promptMode), workerHostOptions(options));
-	if (needsInstruction) {
-		state = await save(replaceTask(state, issue.id, { ...task(state, issue.id), reviewer_instruction_pending: undefined }), options);
+	if (needsInstruction || promptMode === "full") {
+		state = await save(replaceTask(state, issue.id, {
+			...task(state, issue.id),
+			reviewer_instruction_pending: undefined,
+			...(promptMode === "full" ? { review_packet_base: base, review_packet_commit: commit } : {}),
+		}), options);
 	}
 	return state;
 }