pi-squad 0.15.1 → 0.16.0

package/README.md

@@ -41,8 +41,21 @@ The planner agent reads your codebase and creates a task breakdown automatically
 2. A **live widget** appears above the editor showing task progress
 3. **Specialist agents** spawn as separate pi processes, working in parallel where dependencies allow
 4. QA agents can trigger **automatic rework loops** when they find bugs
-5. On completion, pi receives a summary with each task's **complete, untruncated output**
-6. Multiple squads can run concurrently across different projects
+5. When agents finish, the squad enters **`review`**, not `done`; main Pi receives every complete task output as untrusted review input
+6. Main Pi independently checks the original user contract, actual diff/source, verification commands, and integration/E2E, then records acceptance with `squad_review`
+7. Multiple squads can run concurrently across different projects
+
+### Mandatory Orchestrator Review Gate
+
+Squad agents—including QA/reviewer agents—produce candidate work and evidence claims. They cannot mark a squad accepted. After all tasks finish:
+
+- Persisted status becomes `review`, never directly `done`.
+- A persistent `<squad_review_required>` system reminder tells main Pi to re-read the original conversation contract, inspect the actual diff/source, rerun verification independently, and run integration/E2E where applicable.
+- Main Pi must call `squad_review` with requirement-by-requirement contract checks, diff review, actual command/result evidence, integration/E2E evidence, and issues.
+- Only `pass` or `pass_with_issues` changes the squad to `done`; `fail` leaves it review-blocked for fixes and re-review.
+- Pending review survives Pi restarts and is restored on the next session.
+
+The completion report is explicitly labeled **untrusted and not yet accepted**. Main Pi must never merely relay it or ask whether verification should be run.
 
 ### No-Truncation Contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "scripts": {

package/src/index.ts

@@ -26,6 +26,7 @@ import { setupSquadWidget, type SquadWidgetState } from "./panel/squad-widget.js
 import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildCompletionSummary, buildFailureSummary } from "./report.js";
+import { buildOrchestratorReviewGate, recordOrchestratorReview } from "./review.js";
 
 // ============================================================================
 // State
@@ -45,14 +46,6 @@ let uiCtx: import("@earendil-works/pi-coding-agent").ExtensionContext | null = n
 const widgetState: SquadWidgetState = { squadId: null, enabled: true };
 let widgetControls: { requestUpdate: () => void; dispose: () => void } | null = null;
 
-/** Reviewer instructions appended to squad-completed notifications —
- * makes the main session behave like the QA/verification agents do. */
-const REVIEW_INSTRUCTIONS =
-	"Before reporting success to the user, REVIEW the work like a QA agent would: " +
-	"(1) check task outputs for QA verdicts (## Verdict: PASS/FAIL) and verification evidence (commands + results); " +
-	"(2) if a task claimed done without evidence, run its Verify command yourself; " +
-	"(3) report to the user what was verified (with evidence) and flag anything unverified — don't just relay the summary.";
-
 /**
  * Resolve a model string (or null = session default) to its context window.
  * Reads uiCtx lazily so it always uses the live session's registry.
@@ -215,14 +208,33 @@ export default function (pi: ExtensionAPI) {
 
 	// Inject squad awareness before each LLM call
 	pi.on("before_agent_start", async (event, ctx) => {
-		if (!squadEnabled) return;
+		// Review gates are project-wide and survive focus changes, new squads, and
+		// disabling normal squad operations. Unaccepted work must stay visible.
+		const pendingReviewGates = store.findActiveSquads()
+			.filter((s) => s.cwd === ctx.cwd && s.status === "review")
+			.map((s) => ({ squad: s, gate: buildOrchestratorReviewGate(s, store.loadAllTasks(s.id)) }));
+		if (!squadEnabled) {
+			if (pendingReviewGates.length === 0) return;
+			return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+		}
 
 		// When a squad is active, inject its status
 		if (activeSquadId) {
 			const squad = store.loadSquad(activeSquadId);
-			if (!squad) return;
+			if (!squad) {
+				activeSquadId = null;
+				if (pendingReviewGates.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				}
+				return;
+			}
 			const tasks = store.loadAllTasks(activeSquadId);
-			if (tasks.length === 0) return;
+			if (tasks.length === 0) {
+				if (pendingReviewGates.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				}
+				return;
+			}
 
 			const doneCount = tasks.filter((t) => t.status === "done").length;
 			const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
@@ -241,6 +253,8 @@ export default function (pi: ExtensionAPI) {
 				`Status: ${squad.status} | ${doneCount}/${tasks.length} tasks | $${totalCost.toFixed(2)}`,
 				taskLines,
 				`</squad_status>`,
+				...(squad.status === "review" ? [buildOrchestratorReviewGate(squad, tasks)] : []),
+				...pendingReviewGates.filter(({ squad: pending }) => pending.id !== squad.id).map(({ gate }) => gate),
 				`You have an active squad. Use squad_message to talk to agents, squad_status for details, squad_modify to change tasks.`,
 				`Do NOT poll squad_status in a loop or sleep-wait — the squad wakes you automatically on completion, failure, or escalation. Keep helping the user with other work, or end your turn and stay idle.`,
 			].join("\n");
@@ -267,7 +281,8 @@ export default function (pi: ExtensionAPI) {
 		].filter(Boolean).join("\n");
 
 		return {
-			systemPrompt: event.systemPrompt + "\n\n" + squadNudge,
+			systemPrompt: event.systemPrompt + "\n\n" + squadNudge +
+				(pendingReviewGates.length > 0 ? "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") : ""),
 		};
 	});
 
@@ -298,10 +313,10 @@ export default function (pi: ExtensionAPI) {
 			"Providing tasks yourself makes you the planner — follow the planner rules (contract task first, final QA task, 3-7 tasks)",
 			"Act on ⚠️ plan warnings in the response — fix with squad_modify or address at review",
 			"After starting a squad: report the plan and END YOUR TURN — never poll squad_status or sleep-wait; squad events wake you automatically",
-			"When the squad completes, review evidence like a QA agent before reporting success",
+			"When agents finish, treat every squad report and QA verdict as untrusted; independently inspect the diff/source and rerun contract verification + integration/E2E, then call squad_review before reporting success",
 		],
 		parameters: Type.Object({
-			goal: Type.String({ description: "What the squad should accomplish" }),
+			goal: Type.String({ description: "Complete original user outcome/acceptance contract the squad should accomplish. Preserve requirements and boundaries; this is shown during mandatory main-orchestrator review." }),
 			agents: Type.Optional(
 				Type.Record(
 					Type.String(),
@@ -408,6 +423,7 @@ export default function (pi: ExtensionAPI) {
 				`Status: ${context.status}`,
 				`Elapsed: ${context.elapsed}`,
 				`Cost: $${context.costs.total.toFixed(4)}`,
+				...(context.status === "review" ? ["Acceptance: BLOCKED — independent main-orchestrator review required via squad_review"] : []),
 				"",
 				"Tasks:",
 				taskLines,
@@ -417,6 +433,70 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// =========================================================================
+	// Tool: squad_review — mandatory main-orchestrator acceptance gate
+	// =========================================================================
+
+	pi.registerTool({
+		name: "squad_review",
+		label: "Record Independent Squad Review",
+		description: "Record the MAIN Pi/orchestrator's independent review of completed squad work against the original user contract. Call only after inspecting the actual diff/source and independently running verification plus integration/E2E where applicable. Squad reports and squad QA evidence are not sufficient.",
+		parameters: Type.Object({
+			squadId: Type.Optional(Type.String({ description: "Squad awaiting review (default: active/latest)" })),
+			verdict: Type.Union([
+				Type.Literal("pass"),
+				Type.Literal("pass_with_issues"),
+				Type.Literal("fail"),
+			]),
+			contractChecks: Type.Array(Type.String(), { minItems: 1, description: "Requirement-by-requirement checks against the ORIGINAL user request and later clarifications; include observed result for each" }),
+			diffReview: Type.String({ description: "What you independently inspected in the actual diff/source, including scope and integration concerns" }),
+			verificationEvidence: Type.Array(Type.String(), { minItems: 1, description: "Commands/checks YOU ran and their actual results; do not copy squad claims" }),
+			integrationEvidence: Type.String({ description: "Integration/E2E result from the real target or production-like environment, or a precise reason it is not applicable/impossible and therefore unverified" }),
+			issues: Type.Array(Type.String(), { description: "Every discovered or remaining issue; required for fail/pass_with_issues" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			let id = params.squadId;
+			if (!id && activeSquadId && store.loadSquad(activeSquadId)?.status === "review") {
+				id = activeSquadId;
+			}
+			if (!id) {
+				id = store.listSquadsForProject(ctx.cwd)
+					.filter((s) => s.status === "review")
+					.sort((a, b) => b.created.localeCompare(a.created))[0]?.id;
+			}
+			if (!id) {
+				return { content: [{ type: "text" as const, text: "No squad is awaiting orchestrator review." }], details: undefined };
+			}
+
+			const squad = store.loadSquad(id);
+			if (!squad) {
+				return { content: [{ type: "text" as const, text: `Squad '${id}' not found.` }], details: undefined };
+			}
+
+			try {
+				recordOrchestratorReview(squad, {
+					verdict: params.verdict,
+					contractChecks: params.contractChecks,
+					diffReview: params.diffReview,
+					verificationEvidence: params.verificationEvidence,
+					integrationEvidence: params.integrationEvidence,
+					issues: params.issues,
+				});
+			} catch (error) {
+				return { content: [{ type: "text" as const, text: `Review rejected: ${(error as Error).message}` }], details: undefined };
+			}
+
+			store.saveSquad(squad);
+			forceWidgetUpdate();
+			const accepted = squad.status === "done";
+			const text = accepted
+				? `Independent orchestrator review recorded for '${id}' (${params.verdict}). The squad is now accepted as done.`
+				: `Independent review FAILED for '${id}'. The squad remains review-required. Fix every issue, rerun verification/E2E, then submit a fresh squad_review.`;
+			return { content: [{ type: "text" as const, text }], details: undefined };
+		},
+	});
+
 	// =========================================================================
 	// Tool: squad_message
 	// =========================================================================
@@ -518,16 +598,17 @@ export default function (pi: ExtensionAPI) {
 					scheduler.onEvent((event: SchedulerEvent) => {
 						forceWidgetUpdate();
 						switch (event.type) {
-							case "squad_completed": {
+							case "squad_review_required": {
 								const tasks = store.loadAllTasks(squadId);
 								const summary = buildCompletionSummary(tasks);
 								const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 								const s = schedulers.get(squadId); if (s) s.updateContext();
-								// followUp + triggerTurn: wake an idle main agent to review;
-								// if it's mid-conversation with the human, deliver after it finishes
+								const squad = store.loadSquad(squadId)!;
+								// Wake the main agent into an explicit acceptance gate. Agent reports
+								// are untrusted inputs; only independent orchestrator evidence can pass it.
 								pi.sendMessage({
-									customType: "squad-completed",
-									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\nSummary:\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}\n\n${REVIEW_INSTRUCTIONS}`,
+									customType: "squad-review-required",
+									content: `[squad] TASK EXECUTION FINISHED for "${squadId}" — WORK IS UNTRUSTED AND NOT YET ACCEPTED.\n\nSquad claims (review inputs only):\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}\n\n${buildOrchestratorReviewGate(squad, tasks)}`,
 									display: true,
 								}, { triggerTurn: true, deliverAs: "followUp" });
 								schedulers.delete(squadId);
@@ -723,6 +804,24 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 
+		// Restore pending acceptance gates after a main-session restart. Review is
+		// persisted state, not a one-shot completion message that can be missed.
+		const pendingReviews = store.findActiveSquads()
+			.filter((s) => s.cwd === ctx.cwd && s.status === "review");
+		if (pendingReviews.length > 0) {
+			const squad = pendingReviews.sort((a, b) => b.created.localeCompare(a.created))[0];
+			activeSquadId = squad.id;
+			widgetState.squadId = squad.id;
+			widgetState.enabled = true;
+			widgetControls?.requestUpdate();
+			const tasks = store.loadAllTasks(squad.id);
+			pi.sendMessage({
+				customType: "squad-review-required",
+				content: `[squad] Restored mandatory orchestrator review for "${squad.id}" after session restart. The work remains untrusted and not accepted.\n\n${buildOrchestratorReviewGate(squad, tasks)}`,
+				display: true,
+			});
+		}
+
 		// Register Ctrl+Q terminal input handler for panel toggle
 		if (ctx.hasUI) {
 			ctx.ui.onTerminalInput((data) => {
@@ -1008,7 +1107,7 @@ export default function (pi: ExtensionAPI) {
 							const tasks = store.loadAllTasks(s.id);
 							const done = tasks.filter((t) => t.status === "done").length;
 							const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
-							const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "failed" ? "✗" : "·";
+							const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "review" ? "◆" : s.status === "failed" ? "✗" : "·";
 							return `${icon} ${s.id} [${s.status}] ${done}/${tasks.length} $${cost.toFixed(2)}`;
 						}),
 					];
@@ -1318,7 +1417,7 @@ async function pickSquad(
 		const tasks = store.loadAllTasks(s.id);
 		const done = tasks.filter((t) => t.status === "done").length;
 		const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
-		const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "failed" ? "✗" : "·";
+		const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "review" ? "◆" : s.status === "failed" ? "✗" : "·";
 		const project = showProject ? ` — ${s.cwd.split("/").pop()}` : "";
 		return `${icon} ${s.id} [${s.status}] ${done}/${tasks.length} $${cost.toFixed(2)}${project}`;
 	});
@@ -1563,7 +1662,7 @@ async function startSquad(
 		// Update widget on every scheduler event
 		forceWidgetUpdate();
 		switch (event.type) {
-				case "squad_completed": {
+				case "squad_review_required": {
 				const tasks = store.loadAllTasks(squadId);
 				const summary = buildCompletionSummary(tasks);
 				const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
@@ -1573,15 +1672,16 @@ async function startSquad(
 				if (completedSched) {
 					completedSched.updateContext();
 				}
+				const squad = store.loadSquad(squadId)!;
 
-				// followUp + triggerTurn: wake an idle main agent to review; if it's
-				// mid-conversation with the human, deliver after it finishes
+				// Wake the main agent into an explicit acceptance gate. Never frame
+				// agent execution or squad QA as trusted completion.
 				pi.sendMessage({
-					customType: "squad-completed",
-					content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\n` +
-						`Summary:\n${summary}\n\n` +
+					customType: "squad-review-required",
+					content: `[squad] TASK EXECUTION FINISHED for "${squadId}" — WORK IS UNTRUSTED AND NOT YET ACCEPTED.\n\n` +
+						`Squad claims (review inputs only):\n${summary}\n\n` +
 						`Total cost: $${totalCost.toFixed(4)}\n\n` +
-						REVIEW_INSTRUCTIONS,
+						buildOrchestratorReviewGate(squad, tasks),
 					display: true,
 				}, { triggerTurn: true, deliverAs: "followUp" });
 

package/src/panel/squad-widget.ts

@@ -79,6 +79,7 @@ export function setupSquadWidget(
 
 		const sIcon = squad.status === "done" ? th.fg("success", "✓")
 			: squad.status === "failed" ? th.fg("error", "✗")
+			: squad.status === "review" ? th.fg("warning", "◆")
 			: th.fg("warning", "⏳");
 
 		lines.push(
@@ -141,6 +142,8 @@ export function setupSquadWidget(
 			? th.fg("success", `✓ squad ${doneCount}/${tasks.length}`)
 			: squad.status === "failed"
 			? th.fg("error", `✗ squad ${doneCount}/${tasks.length}`)
+			: squad.status === "review"
+			? th.fg("warning", `◆ squad review required`)
 			: th.fg("accent", `⏳ squad ${doneCount}/${tasks.length} $${totalCost.toFixed(2)}`);
 
 		return { lines, cacheKey, statusText };
@@ -215,7 +218,7 @@ export function setupSquadWidget(
 			return;
 		}
 		const squad = store.loadSquad(state.squadId);
-		const isActive = squad && (squad.status === "running" || squad.status === "paused");
+		const isActive = squad && (squad.status === "running" || squad.status === "paused" || squad.status === "review");
 		if (isActive && !durationTimer) {
 			durationTimer = setInterval(() => render(), 5000);
 		} else if (!isActive && durationTimer) {

package/src/review.ts

@@ -0,0 +1,107 @@
+import type { Squad, Task } from "./types.js";
+
+export type OrchestratorReviewVerdict = "pass" | "pass_with_issues" | "fail";
+
+export interface OrchestratorReviewInput {
+	verdict: OrchestratorReviewVerdict;
+	contractChecks: string[];
+	diffReview: string;
+	verificationEvidence: string[];
+	integrationEvidence: string;
+	issues: string[];
+}
+
+/** Move a squad from agent execution into mandatory independent main-session review. */
+export function beginOrchestratorReview(squad: Squad): void {
+	squad.status = "review";
+	squad.review = {
+		status: "pending",
+		requestedAt: new Date().toISOString(),
+		completedAt: null,
+		verdict: null,
+		contractChecks: [],
+		diffReview: "",
+		verificationEvidence: [],
+		integrationEvidence: "",
+		issues: [],
+	};
+}
+
+/**
+ * Validate and record the orchestrator's independent review evidence.
+ * A failing review deliberately leaves the squad behind the review gate.
+ */
+export function recordOrchestratorReview(squad: Squad, input: OrchestratorReviewInput): void {
+	if (squad.status !== "review" || !squad.review) {
+		throw new Error(`Squad '${squad.id}' is not awaiting orchestrator review`);
+	}
+
+	const contractChecks = cleanList(input.contractChecks);
+	const verificationEvidence = cleanList(input.verificationEvidence);
+	const issues = cleanList(input.issues);
+	const diffReview = input.diffReview.trim();
+	const integrationEvidence = input.integrationEvidence.trim();
+
+	if (contractChecks.length === 0) {
+		throw new Error("contractChecks must map the original user requirements to observed results");
+	}
+	if (!diffReview) {
+		throw new Error("diffReview must describe the independently inspected changes and scope");
+	}
+	if (verificationEvidence.length === 0) {
+		throw new Error("verificationEvidence must include commands/checks and their actual results");
+	}
+	if (!integrationEvidence) {
+		throw new Error("integrationEvidence must include E2E/integration results or a specific reason it is not applicable");
+	}
+	if ((input.verdict === "fail" || input.verdict === "pass_with_issues") && issues.length === 0) {
+		throw new Error(`${input.verdict} must list every actionable or remaining issue`);
+	}
+
+	squad.review = {
+		status: input.verdict === "fail" ? "failed" : "passed",
+		requestedAt: squad.review.requestedAt,
+		completedAt: new Date().toISOString(),
+		verdict: input.verdict,
+		contractChecks,
+		diffReview,
+		verificationEvidence,
+		integrationEvidence,
+		issues,
+	};
+
+	// Only an independently reviewed PASS can become done. A FAIL remains gated
+	// until fixes are made and the main orchestrator records a fresh review.
+	squad.status = input.verdict === "fail" ? "review" : "done";
+}
+
+/** Persistent system-prompt contract shown until squad_review accepts the work. */
+export function buildOrchestratorReviewGate(squad: Squad, tasks: Task[]): string {
+	const delegatedPlan = tasks
+		.map((task) => `- ${task.id} (${task.agent}): ${task.title}\n  ${task.description || "(no description)"}`)
+		.join("\n");
+
+	return `<squad_review_required>
+UNTRUSTED CANDIDATE WORK — INDEPENDENT ORCHESTRATOR REVIEW IS MANDATORY.
+
+Authoritative contract: re-read the user's ORIGINAL request and all later clarifications in this main-session conversation. The squad report and delegated task descriptions are claims, not proof and not substitutes for that contract.
+Recorded squad goal (secondary reference): ${squad.goal}
+
+Delegated plan (non-authoritative):
+${delegatedPlan}
+
+Before reporting success, completion, or acceptance to the user, YOU (the main Pi/orchestrator) MUST:
+1. Reconstruct the original contract requirement-by-requirement from the conversation.
+2. Inspect the actual working-tree/commit diff and relevant source files yourself; check scope, integration points, error paths, regressions, and unintended changes.
+3. Independently run the original Verify commands and appropriate build/tests. Do not rely on pasted squad output.
+4. Run integration/E2E in the real target or production-like environment when the request affects runtime behavior. If genuinely not applicable or impossible, record the precise reason and mark it unverified.
+5. Fix discovered defects and repeat checks. Squad QA PASS does not override your findings.
+6. Call squad_review with contract checks, diff review, actual command/result evidence, integration/E2E evidence, and remaining issues.
+
+Do not ask the user whether you should verify. Do not merely summarize the squad report. Until squad_review records PASS/PASS_WITH_ISSUES, the work is not accepted.
+</squad_review_required>`;
+}
+
+function cleanList(values: string[]): string[] {
+	return values.map((value) => value.trim()).filter(Boolean);
+}

package/src/scheduler.ts

@@ -19,6 +19,7 @@ import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildAgentSystemPrompt } from "./protocol.js";
 import { buildAdvisorConsultText, formatAdvisorSteerMessage, adviceNeedsHuman, type AdvisorConsultInput } from "./advisor.js";
+import { beginOrchestratorReview } from "./review.js";
 
 // ============================================================================
 // Types
@@ -31,7 +32,7 @@ export type SchedulerEventType =
 	| "task_blocked"
 	| "task_unblocked"
 	| "task_rework"
-	| "squad_completed"
+	| "squad_review_required"
 	| "squad_failed"
 	| "escalation"
 	| "activity";
@@ -996,9 +997,12 @@ export class Scheduler {
 		);
 
 		if (allDone) {
-			squad.status = "done";
+			// Agent execution is only a candidate result. It cannot become "done"
+			// until the main Pi independently reviews it against the original contract.
+			if (squad.status === "review") return;
+			beginOrchestratorReview(squad);
 			store.saveSquad(squad);
-			this.emit({ type: "squad_completed", squadId: this.squadId });
+			this.emit({ type: "squad_review_required", squadId: this.squadId });
 		} else if (anyFailed && !anyInProgress) {
 			// All remaining tasks are blocked/failed with no way forward
 			const blockedCount = tasks.filter((t) => t.status === "blocked").length;

package/src/skills/squad-supervisor/SKILL.md

@@ -152,23 +152,30 @@ Use `squad_modify` when:
 - **`pause`** / **`resume`**: Stop/restart the entire squad
 - **`cancel`**: Abort everything (user changed their mind)
 
-## After Squad Completes — Reviewing Completed Work
-
-When you receive `[squad] Squad completed`, you are the last line of review. Do NOT just relay the summary:
-1. **Check verdicts**: scan task outputs for QA verdicts (`## Verdict: PASS/FAIL/PASS WITH ISSUES`) and note any `PASS WITH ISSUES` minor issues
-2. **Check evidence**: each task's output should include verification evidence (commands + results). If a task claimed done without evidence, run its Verify command yourself (build, test, curl — whatever the task description specified)
-3. **Spot-check integration**: individual tasks passing doesn't guarantee the integrated result works — run the end-to-end check when one exists (app builds, server starts, main flow works)
-4. **Report with evidence**: tell the user what was verified (with the commands/results), and explicitly flag anything unverified or concerning
-5. Suggest next steps if applicable
-
-Example:
-> Squad finished all 4 tasks:
-> - API endpoints created at `/api/auth` and `/api/users`
-> - JWT middleware with RS256 validation
-> - 12 tests passing
-> - README updated with API docs
+## After Agents Finish — Mandatory Independent Orchestrator Review
+
+Agent execution finishing is **not completion or acceptance**. When you receive `[squad] TASK EXECUTION FINISHED` / `<squad_review_required>`, every squad output—including QA PASS—is an untrusted claim. You are the independent acceptance authority.
+
+You MUST do all of this before telling the user the work succeeded:
+1. **Re-read the original contract**: reconstruct every requirement, boundary, and later clarification from the user's main-session conversation. The squad goal/task plan is only a secondary aid and cannot narrow the original request.
+2. **Inspect reality, not reports**: read the actual working-tree/commit diff and relevant source. Check every changed line for correctness, scope, integration points, unintended changes, error paths, security, and regressions.
+3. **Independently verify**: run the original Verify commands, build, and relevant tests yourself. Do not count command output pasted by squad agents as your evidence.
+4. **Run integration/E2E**: individual task/QA passes do not prove the integrated system. Exercise the real user flow in the target or production-like environment whenever runtime behavior changed. If impossible or genuinely inapplicable, state exactly why and mark it unverified—never silently skip it.
+5. **Fix and repeat**: if you find defects, fix them (or route explicit rework), then rerun the affected checks. Squad QA does not overrule your findings.
+6. **Record the gate**: call `squad_review` with requirement-by-requirement contract checks, your diff review, actual command/result evidence, integration/E2E evidence, and all issues. Until that tool records PASS/PASS_WITH_ISSUES, the squad remains `review` rather than `done`.
+7. **Report only reviewed facts**: clearly separate what you personally verified, remaining issues, and anything unverified.
+
+Never ask “Want me to run the tests/E2E?” after agents finish. Run required acceptance checks immediately. Never merely relay or paraphrase the squad summary.
+
+Example after independent review:
+> Independent orchestrator review complete against the original 7 acceptance criteria:
+> - Inspected `git diff --stat` and the auth/router/test changes; no unrelated files changed
+> - `npm test`: 42/42 passed; `npm run build`: passed
+> - Production-like E2E: login → refresh → protected route → logout passed
+> - Found and fixed a cookie-domain defect missed by squad QA; reran unit + E2E successfully
+> - `squad_review`: PASS
 >
-> Total cost: $1.23. Want me to run the full test suite or deploy?
+> Remaining unverified: none.
 
 ## Decision Framework
 
@@ -181,5 +188,5 @@ Example:
 | User says "tell the backend agent to..." | `squad_message` to that agent |
 | User says "add a task for..." | `squad_modify` with `add_task` |
 | User says "cancel/stop" | `squad_modify` with `cancel` |
-| Squad completes | Summarize results, suggest next steps |
+| Agents finish | Independently review against original contract, inspect diff, run verification + integration/E2E, call `squad_review`; only then report acceptance |
 | Squad fails | Report what failed, offer options (retry, modify, cancel) |

package/src/store.ts

@@ -269,11 +269,11 @@ export function listSquads(): string[] {
 }
 
 export function findActiveSquads(): Squad[] {
-	// Includes "failed": failure is recoverable (resume resets failed tasks), so
-	// failed squads must stay discoverable. All callers filter by status.
+	// Includes "failed" (recoverable) and "review" (main-orchestrator gate), so
+	// neither state disappears across session restarts. All callers filter by status.
 	return listSquads()
 		.map((id) => loadSquad(id))
-		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused" || s.status === "failed"));
+		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused" || s.status === "failed" || s.status === "review"));
 }
 
 /** List squads filtered by project cwd. If no cwd, returns all. */

package/src/types.ts

@@ -71,11 +71,24 @@ export const DEFAULT_SQUAD_SETTINGS: SquadSettings = {
 // Squad
 // ============================================================================
 
-export type SquadStatus = "planning" | "running" | "paused" | "done" | "failed";
+export type SquadStatus = "planning" | "running" | "paused" | "review" | "done" | "failed";
+
+export interface SquadReview {
+	status: "pending" | "passed" | "failed";
+	requestedAt: string;
+	completedAt: string | null;
+	verdict: "pass" | "pass_with_issues" | "fail" | null;
+	contractChecks: string[];
+	diffReview: string;
+	verificationEvidence: string[];
+	integrationEvidence: string;
+	issues: string[];
+}
 
 export interface SquadConfig {
 	maxConcurrency: number;
 	autoUnblock: boolean;
+	/** @deprecated Independent main-orchestrator review is always required. */
 	reviewOnComplete: boolean;
 	/** Max rework attempts when QA fails a task (0 = no rework, just fail) */
 	maxRetries: number;
@@ -84,7 +97,7 @@ export interface SquadConfig {
 export const DEFAULT_SQUAD_CONFIG: SquadConfig = {
 	maxConcurrency: 2,
 	autoUnblock: true,
-	reviewOnComplete: false,
+	reviewOnComplete: true,
 	maxRetries: 2,
 };
 
@@ -99,6 +112,8 @@ export interface Squad {
 	/** Agent name → overrides. Keys must exist in .pi/squad/agents/ */
 	agents: Record<string, SquadAgentEntry>;
 	config: SquadConfig;
+	/** Mandatory independent main-session review; absent on legacy/running squads. */
+	review?: SquadReview;
 }
 
 // ============================================================================