taskplane 0.22.10 → 0.22.11

package/bin/rpc-wrapper.mjs

@@ -640,11 +640,31 @@ function querySessionStats() {
 
 // ── Route RPC events ─────────────────────────────────────────────────
 
+// Event types worth persisting to the sidecar JSONL.
+// Streaming deltas (content_block_delta, content_block_start/stop, message_start,
+// input_json_delta, etc.) are omitted — they're high-volume, large, and not used
+// by the dashboard or telemetry consumers. A single merge agent can produce 42MB+
+// of sidecar data from streaming deltas alone.
+const SIDECAR_EVENT_TYPES = new Set([
+	"agent_start",
+	"agent_end",
+	"message_end",
+	"tool_execution_start",
+	"tool_execution_end",
+	"tool_execution_update",
+	"auto_retry_start",
+	"auto_retry_end",
+	"auto_compaction_start",
+	"response",
+]);
+
 function handleEvent(event) {
 	if (!event || !event.type) return;
 
-	// Write ALL events to sidecar (redacted)
-	writeSidecarEvent(args.sidecarPath, event);
+	// Write only telemetry-relevant events to sidecar (redacted)
+	if (SIDECAR_EVENT_TYPES.has(event.type)) {
+		writeSidecarEvent(args.sidecarPath, event);
+	}
 
 	// Delegate state mutation to the extracted (testable) accumulator
 	applyEvent(state, event);

package/extensions/task-runner.ts

@@ -1121,7 +1121,7 @@ function extractVerdict(reviewContent: string): string {
 	// TP-068: Tolerate non-standard verdict formats from models that don't
 	// follow the exact template (e.g., "Changes requested", "Needs revision").
 	const lower = reviewContent.toLowerCase();
-	if (/\b(changes?\s+requested|needs?\s+revision|please\s+revise|must\s+revise)\b/.test(lower)) {
+	if (/\b(request\s+changes?|changes?\s+requested|needs?\s+revision|please\s+revise|must\s+revise)\b/.test(lower)) {
 		return "REVISE";
 	}
 	if (/\b(looks?\s+good|no\s+issues?\s+found|approved?)\b/.test(lower)) {

package/extensions/taskplane/execution.ts

@@ -915,10 +915,8 @@ export function spawnLaneSession(
 
 	// Build env vars
 	const envVars = buildLaneEnvVars(lane, task.task.promptPath, repoRoot, workspaceRoot);
-	// Pass batch ID so task-runner can include it in lane state for dashboard filtering
-	if (config.orchestrator?.batchId) {
-		envVars.ORCH_BATCH_ID = config.orchestrator.batchId;
-	}
+	// ORCH_BATCH_ID is passed via extraEnvVars from executeWave → executeLane → spawnLaneSession.
+	// The task-runner reads it to include batchId in lane-state JSON for dashboard filtering.
 	if (extraEnvVars) {
 		Object.assign(envVars, extraEnvVars);
 	}
@@ -2371,7 +2369,9 @@ export async function executeWave(
 	const wsRoot = workspaceConfig ? dirname(dirname(workspaceConfig.configPath)) : undefined;
 	const isWsMode = !!workspaceConfig;
 	const lanePromises = lanes.map(lane =>
-		executeLane(lane, config, repoRoot, wavePauseSignal, wsRoot, isWsMode),
+		executeLane(lane, config, repoRoot, wavePauseSignal, wsRoot, isWsMode, {
+			ORCH_BATCH_ID: batchId,
+		}),
 	);
 
 	// Start monitoring as a sibling async loop

package/extensions/taskplane/persistence.ts

@@ -9,7 +9,7 @@ import { join, dirname, basename } from "path";
 import { execLog } from "./execution.ts";
 import { BATCH_STATE_SCHEMA_VERSION, StateFileError, batchStatePath, BATCH_HISTORY_MAX_ENTRIES, defaultResilienceState, defaultBatchDiagnostics } from "./types.ts";
 import type { BatchHistorySummary } from "./types.ts";
-import type { AllocatedLane, DiscoveryResult, EngineEvent, EscalationContext, LaneTaskOutcome, LaneTaskStatus, MonitorState, OrchBatchPhase, OrchBatchRuntimeState, PersistedBatchState, PersistedLaneRecord, PersistedMergeResult, PersistedTaskRecord, TaskMonitorSnapshot, Tier0RecoveryPattern, WorkspaceMode } from "./types.ts";
+import type { AllocatedLane, DiscoveryResult, EngineEvent, EscalationContext, LaneTaskOutcome, LaneTaskStatus, MonitorState, OrchBatchPhase, OrchBatchRuntimeState, PersistedBatchState, PersistedLaneRecord, PersistedMergeResult, PersistedSegmentRecord, PersistedTaskRecord, TaskMonitorSnapshot, Tier0RecoveryPattern, WorkspaceMode } from "./types.ts";
 import { sleepSync } from "./worktree.ts";
 import type { PreserveFailedLaneProgressResult } from "./worktree.ts";
 
@@ -379,6 +379,29 @@ export function upconvertV2toV3(obj: Record<string, unknown>): void {
 	if (!obj.diagnostics) obj.diagnostics = defaultBatchDiagnostics();
 }
 
+/**
+ * Upconvert a v3 state object to v4 by adding the `segments` array.
+ *
+ * Added fields:
+ * - `segments`: empty array (no segment records exist in pre-v4 state)
+ *
+ * Task-level segment fields (`packetRepoId`, `packetTaskPath`,
+ * `segmentIds`, `activeSegmentId`) are optional and default to
+ * `undefined` (omitted from JSON). They are NOT backfilled here
+ * because their values depend on runtime discovery, not on
+ * migration defaults.
+ *
+ * This function is idempotent: calling it on an already-v4 object is a no-op.
+ *
+ * @param obj - Parsed state object (mutated in-place)
+ */
+export function upconvertV3toV4(obj: Record<string, unknown>): void {
+	if ((obj.schemaVersion as number) >= 4) return;
+	obj.schemaVersion = 4;
+	// Backfill v4 segments with empty array only during genuine v3→v4 migration.
+	if (!obj.segments) obj.segments = [];
+}
+
 /**
  * Validate a parsed JSON object as a PersistedBatchState.
  *
@@ -410,9 +433,9 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 			`Missing or invalid "schemaVersion" field (expected number, got ${typeof obj.schemaVersion})`,
 		);
 	}
-	// Accept v1 (auto-upconvert to v2→v3), v2 (upconvert to v3), and v3 (current).
+	// Accept v1 (auto-upconvert to v2→v3→v4), v2 (upconvert to v3→v4), v3 (upconvert to v4), and v4 (current).
 	// Reject anything else — including future versions from newer runtimes.
-	const ACCEPTED_VERSIONS = [1, 2, BATCH_STATE_SCHEMA_VERSION];
+	const ACCEPTED_VERSIONS = [1, 2, 3, BATCH_STATE_SCHEMA_VERSION];
 	if (!ACCEPTED_VERSIONS.includes(obj.schemaVersion as number)) {
 		throw new StateFileError(
 			"STATE_SCHEMA_INVALID",
@@ -754,12 +777,13 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 		}
 	}
 
-	// ── v1→v2→v3 upconversion ────────────────────────────────────
+	// ── v1→v2→v3→v4 upconversion ─────────────────────────────────
 	// Apply defaults for fields that may be absent in older state files.
 	// The on-disk file is NOT rewritten; upconversion is in-memory only.
-	// Chain: v1→v2 then v2→v3 (each is idempotent / no-op if already at target).
+	// Chain: v1→v2 then v2→v3 then v3→v4 (each is idempotent / no-op if already at target).
 	upconvertV1toV2(obj);
 	upconvertV2toV3(obj);
+	upconvertV3toV4(obj);
 
 	// ── Validate v3 resilience section ───────────────────────────
 	// After upconversion, resilience must be a valid object with correct types.
@@ -928,6 +952,127 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 				);
 			}
 		}
+		// v4 optional fields: packetRepoId, packetTaskPath (string | undefined)
+		if (t.packetRepoId !== undefined && typeof t.packetRepoId !== "string") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`tasks[${i}].packetRepoId is not a string (got ${typeof t.packetRepoId})`,
+			);
+		}
+		if (t.packetTaskPath !== undefined && typeof t.packetTaskPath !== "string") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`tasks[${i}].packetTaskPath is not a string (got ${typeof t.packetTaskPath})`,
+			);
+		}
+		// v4 optional field: segmentIds (string[] | undefined)
+		if (t.segmentIds !== undefined) {
+			if (!Array.isArray(t.segmentIds)) {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`tasks[${i}].segmentIds is not an array (got ${typeof t.segmentIds})`,
+				);
+			}
+			for (let j = 0; j < (t.segmentIds as unknown[]).length; j++) {
+				if (typeof (t.segmentIds as unknown[])[j] !== "string") {
+					throw new StateFileError(
+						"STATE_SCHEMA_INVALID",
+						`tasks[${i}].segmentIds[${j}] is not a string`,
+					);
+				}
+			}
+		}
+		// v4 optional field: activeSegmentId (string | null | undefined)
+		if (t.activeSegmentId !== undefined && t.activeSegmentId !== null && typeof t.activeSegmentId !== "string") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`tasks[${i}].activeSegmentId is not a string or null (got ${typeof t.activeSegmentId})`,
+			);
+		}
+	}
+
+	// ── Validate v4 segments array ───────────────────────────────
+	if (!Array.isArray(obj.segments)) {
+		throw new StateFileError(
+			"STATE_SCHEMA_INVALID",
+			`Missing or invalid "segments" field (expected array, got ${typeof obj.segments})`,
+		);
+	}
+	const segments = obj.segments as unknown[];
+	for (let i = 0; i < segments.length; i++) {
+		const s = segments[i] as Record<string, unknown>;
+		if (!s || typeof s !== "object") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}] is not an object`,
+			);
+		}
+		// Required string fields
+		for (const field of ["segmentId", "taskId", "repoId", "laneId", "sessionName", "worktreePath", "branch", "exitReason"] as const) {
+			if (typeof s[field] !== "string") {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].${field} is missing or not a string (got ${typeof s[field]})`,
+				);
+			}
+		}
+		// Required status field (same valid values as task status)
+		if (typeof s.status !== "string" || !VALID_TASK_STATUSES.has(s.status)) {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].status is invalid: "${s.status}" (expected one of: ${[...VALID_TASK_STATUSES].join(", ")})`,
+			);
+		}
+		// Nullable number fields: startedAt, endedAt
+		if (s.startedAt !== null && typeof s.startedAt !== "number") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].startedAt is not a number or null (got ${typeof s.startedAt})`,
+			);
+		}
+		if (s.endedAt !== null && typeof s.endedAt !== "number") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].endedAt is not a number or null (got ${typeof s.endedAt})`,
+			);
+		}
+		// Required number: retries
+		if (typeof s.retries !== "number") {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].retries is not a number (got ${typeof s.retries})`,
+			);
+		}
+		// Required array: dependsOnSegmentIds
+		if (!Array.isArray(s.dependsOnSegmentIds)) {
+			throw new StateFileError(
+				"STATE_SCHEMA_INVALID",
+				`segments[${i}].dependsOnSegmentIds is not an array (got ${typeof s.dependsOnSegmentIds})`,
+			);
+		}
+		for (let j = 0; j < (s.dependsOnSegmentIds as unknown[]).length; j++) {
+			if (typeof (s.dependsOnSegmentIds as unknown[])[j] !== "string") {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].dependsOnSegmentIds[${j}] is not a string`,
+				);
+			}
+		}
+		// Optional exitDiagnostic
+		if (s.exitDiagnostic !== undefined) {
+			if (!s.exitDiagnostic || typeof s.exitDiagnostic !== "object" || Array.isArray(s.exitDiagnostic)) {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].exitDiagnostic is not a plain object (got ${Array.isArray(s.exitDiagnostic) ? "array" : typeof s.exitDiagnostic})`,
+				);
+			}
+			if (typeof (s.exitDiagnostic as Record<string, unknown>).classification !== "string") {
+				throw new StateFileError(
+					"STATE_SCHEMA_INVALID",
+					`segments[${i}].exitDiagnostic.classification is not a string`,
+				);
+			}
+		}
 	}
 
 	// ── Capture unknown top-level fields for roundtrip preservation ──
@@ -941,6 +1086,7 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 		"totalTasks", "succeededTasks", "failedTasks", "skippedTasks", "blockedTasks",
 		"blockedTaskIds", "lastError", "errors",
 		"resilience", "diagnostics",
+		"segments",
 		"_extraFields",
 	]);
 	const extraFields: Record<string, unknown> = {};
@@ -1049,6 +1195,20 @@ export function serializeBatchState(
 				record.exitDiagnostic = outcome.exitDiagnostic;
 			}
 
+			// TP-081 v4: Serialize segment-level fields from ParsedTask or existing state
+			if (allocated?.allocatedTask.task?.packetRepoId !== undefined) {
+				(record as any).packetRepoId = allocated.allocatedTask.task.packetRepoId;
+			}
+			if (allocated?.allocatedTask.task?.packetTaskPath !== undefined) {
+				(record as any).packetTaskPath = allocated.allocatedTask.task.packetTaskPath;
+			}
+			if (allocated?.allocatedTask.task?.segmentIds !== undefined) {
+				(record as any).segmentIds = allocated.allocatedTask.task.segmentIds;
+			}
+			if (allocated?.allocatedTask.task?.activeSegmentId !== undefined) {
+				(record as any).activeSegmentId = allocated.allocatedTask.task.activeSegmentId;
+			}
+
 			return record;
 		});
 
@@ -1122,6 +1282,7 @@ export function serializeBatchState(
 		errors: [...state.errors],
 		resilience: state.resilience ?? defaultResilienceState(),
 		diagnostics: state.diagnostics ?? defaultBatchDiagnostics(),
+		segments: state.segments ?? [],
 	};
 
 	// Merge unknown fields from loaded state to preserve roundtrip fidelity.

package/extensions/taskplane/resume.ts

@@ -1167,7 +1167,9 @@ export async function resumeOrchBatch(
 			});
 
 			try {
-				spawnLaneSession(lane, allocatedTask, orchConfig, reExecRepoRoot);
+				spawnLaneSession(lane, allocatedTask, orchConfig, reExecRepoRoot, undefined, {
+					ORCH_BATCH_ID: batchState.batchId,
+				});
 				const pollResult = await pollUntilTaskComplete(
 					lane,
 					allocatedTask,

package/extensions/taskplane/types.ts

@@ -98,6 +98,26 @@ export interface ParsedTask {
 	resolvedRepoId?: string;
 	/** Optional explicit segment DAG metadata from `## Segment DAG`. */
 	explicitSegmentDag?: PromptSegmentDagMetadata;
+	/**
+	 * Repo ID that owns task packet files (v4, TP-081).
+	 * Populated by execution engine in workspace mode. Undefined in repo mode.
+	 */
+	packetRepoId?: string;
+	/**
+	 * Absolute path to task folder in the packet repo worktree (v4, TP-081).
+	 * Populated by execution engine. Undefined if not yet resolved.
+	 */
+	packetTaskPath?: string;
+	/**
+	 * Segment IDs for this task (v4, TP-081).
+	 * Populated from TaskSegmentPlan during execution.
+	 */
+	segmentIds?: string[];
+	/**
+	 * Currently active segment ID (v4, TP-081).
+	 * Null when no segment is active.
+	 */
+	activeSegmentId?: string | null;
 }
 
 /** Build a stable segment ID from task + repo identity (`<taskId>::<repoId>`). */
@@ -1015,6 +1035,12 @@ export interface OrchBatchRuntimeState {
 	 * Populated from persisted state on resume; defaults used for new batches.
 	 */
 	diagnostics?: BatchDiagnostics;
+	/**
+	 * v4 segment records carried forward across resume cycles (TP-081).
+	 * Populated from persisted state on resume; empty for new batches
+	 * and repo-mode batches.
+	 */
+	segments?: PersistedSegmentRecord[];
 	/**
 	 * Unknown top-level fields from loaded persisted state.
 	 * Carried forward so they survive serialization roundtrips.
@@ -2304,15 +2330,22 @@ export function defaultBatchDiagnostics(): BatchDiagnostics {
  *         exit summaries, batch cost). Task records gain optional
  *         `exitDiagnostic` alongside legacy `exitReason`.
  *         Both new sections are optional for v1/v2 migration paths.
+ *   v4 — Segment execution (TP-081). Adds optional `segments` array
+ *         for persisting per-segment runtime state. Task records gain
+ *         optional `packetRepoId`, `packetTaskPath`, `segmentIds`, and
+ *         `activeSegmentId` fields. All v4-specific fields are optional
+ *         for backward compatibility with v1/v2/v3 migration paths.
+ *         When migrating from v3, `segments` defaults to `[]` and
+ *         task-level segment fields default to `undefined`.
  *
  * Compatibility policy:
- *   - loadBatchState() accepts v1, v2, and v3 files. v1 and v2 are
- *     auto-upconverted to v3 in memory (chained: v1→v2→v3).
+ *   - loadBatchState() accepts v1, v2, v3, and v4 files. v1→v2→v3→v4
+ *     auto-upconverted in memory (chained).
  *     The on-disk file is NOT rewritten during load.
- *   - saveBatchState() always writes v3.
- *   - Schema versions > 3 are rejected with STATE_SCHEMA_INVALID.
+ *   - saveBatchState() always writes v4.
+ *   - Schema versions > 4 are rejected with STATE_SCHEMA_INVALID.
  */
-export const BATCH_STATE_SCHEMA_VERSION = 3;
+export const BATCH_STATE_SCHEMA_VERSION = 4;
 
 /**
  * Canonical file path for persisted batch state.
@@ -2431,6 +2464,99 @@ export interface PersistedTaskRecord {
 	 * falling back to `exitReason` for display.
 	 */
 	exitDiagnostic?: TaskExitDiagnostic;
+	/**
+	 * Repo ID that owns task packet files (PROMPT.md/STATUS.md/.DONE) (v4, TP-081).
+	 *
+	 * In workspace mode, this is the `taskPacketRepo` from routing config.
+	 * Undefined in repo mode or for pre-v4 state files.
+	 */
+	packetRepoId?: string;
+	/**
+	 * Absolute path to the task folder in the packet repo worktree (v4, TP-081).
+	 *
+	 * Used by resume to locate packet files without re-running discovery.
+	 * Undefined in repo mode or for pre-v4 state files.
+	 */
+	packetTaskPath?: string;
+	/**
+	 * Segment IDs belonging to this task (v4, TP-081).
+	 *
+	 * Array of segment ID strings (`<taskId>::<repoId>`).
+	 * Empty array for repo-mode tasks or single-repo tasks.
+	 * Undefined for pre-v4 state files.
+	 */
+	segmentIds?: string[];
+	/**
+	 * Currently executing segment ID (v4, TP-081).
+	 *
+	 * Null when no segment is active (all completed or not started).
+	 * Undefined for pre-v4 state files.
+	 */
+	activeSegmentId?: string | null;
+}
+
+// ── Segment-Level Persisted State (v4, TP-081) ──────────────────────
+
+/**
+ * Segment execution status within a batch.
+ *
+ * State machine mirrors `LaneTaskStatus` but applies at segment granularity:
+ *   pending → running → succeeded
+ *                     → failed
+ *                     → stalled
+ *   pending → skipped  (prior segment failed, or task skipped)
+ *
+ * @since v4 (TP-081)
+ */
+export type PersistedSegmentStatus = "pending" | "running" | "succeeded" | "failed" | "stalled" | "skipped";
+
+/**
+ * Persisted record of a single segment's execution state.
+ *
+ * A segment is a repo-scoped execution unit within a task. Each task
+ * may have one or more segments (one per repo the task touches).
+ *
+ * Contains everything `/orch-resume` needs to reconstruct segment-level
+ * progress without re-running discovery.
+ *
+ * @since v4 (TP-081)
+ */
+export interface PersistedSegmentRecord {
+	/** Stable segment identifier (`<taskId>::<repoId>`, e.g., "TP-002::api") */
+	segmentId: string;
+	/** Parent task identifier */
+	taskId: string;
+	/** Repo ID this segment targets */
+	repoId: string;
+	/** Segment execution status */
+	status: PersistedSegmentStatus;
+	/** Lane ID the segment executed on (e.g., "lane-1"), empty if not yet assigned */
+	laneId: string;
+	/** TMUX session name used for this segment */
+	sessionName: string;
+	/** Absolute path to the worktree used for this segment */
+	worktreePath: string;
+	/** Git branch name checked out for this segment */
+	branch: string;
+	/** Epoch ms when segment execution started (null if not yet started) */
+	startedAt: number | null;
+	/** Epoch ms when segment execution ended (null if still pending/running) */
+	endedAt: number | null;
+	/** Number of retry attempts for this segment */
+	retries: number;
+	/**
+	 * Segment IDs this segment depends on (intra-task DAG edges).
+	 * Empty array for the first segment in a task or for tasks with no intra-task deps.
+	 */
+	dependsOnSegmentIds: string[];
+	/**
+	 * Structured exit diagnostic for this segment.
+	 * Optional: absent for segments that haven't exited yet.
+	 * Uses the same `TaskExitDiagnostic` shape from diagnostics.ts.
+	 */
+	exitDiagnostic?: TaskExitDiagnostic;
+	/** Human-readable exit reason (legacy compat, same as task-level) */
+	exitReason: string;
 }
 
 /**
@@ -2545,9 +2671,17 @@ export interface PersistedRepoMergeOutcome {
  *   data alongside legacy `exitReason` string).
  * - Both sections are required in v3. Migration from v1/v2 fills
  *   conservative defaults (see `defaultResilienceState()` / `defaultBatchDiagnostics()`).
+ *
+ * v4 additions (TP-081):
+ * - `segments` array (required): per-segment execution records for multi-repo
+ *   task execution. Empty array in repo mode or for pre-v4 migration.
+ * - Task records gain optional `packetRepoId`, `packetTaskPath`, `segmentIds`,
+ *   and `activeSegmentId` for segment-level tracking.
+ * - Migration from v3 fills `segments` as `[]` and leaves task-level segment
+ *   fields as `undefined`.
  */
 export interface PersistedBatchState {
-	/** Schema version — must equal BATCH_STATE_SCHEMA_VERSION (currently 3) */
+	/** Schema version — must equal BATCH_STATE_SCHEMA_VERSION (currently 4) */
 	schemaVersion: number;
 	/** Current batch execution phase */
 	phase: OrchBatchPhase;
@@ -2596,14 +2730,24 @@ export interface PersistedBatchState {
 	errors: string[];
 	/**
 	 * Resilience state for retry/recovery tracking (v3, TP-030).
-	 * Required in v3. Migration from v1/v2 fills conservative defaults.
+	 * Required in v3+. Migration from v1/v2 fills conservative defaults.
 	 */
 	resilience: ResilienceState;
 	/**
 	 * Batch-level diagnostics for cost tracking and exit summaries (v3, TP-030).
-	 * Required in v3. Migration from v1/v2 fills conservative defaults.
+	 * Required in v3+. Migration from v1/v2 fills conservative defaults.
 	 */
 	diagnostics: BatchDiagnostics;
+	/**
+	 * Per-segment execution records for multi-repo task execution (v4, TP-081).
+	 *
+	 * Each entry represents one repo-scoped segment of a task. In repo mode
+	 * or for single-repo tasks, this array is empty (segment tracking is
+	 * implicit via task records).
+	 *
+	 * Required in v4. Migration from v1/v2/v3 fills empty array.
+	 */
+	segments: PersistedSegmentRecord[];
 	/**
 	 * Unknown top-level fields captured during deserialization.
 	 * Preserved on roundtrip to avoid data loss from future schema extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.22.10",
+  "version": "0.22.11",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/templates/agents/task-worker.md

@@ -201,8 +201,29 @@ a reviewer agent. The tool takes two parameters: `step` (number) and `type`
 documentation/delivery). These are low-risk steps where review overhead exceeds
 value.
 
+### ⚠️ CRITICAL: Plan review happens BEFORE implementation
+
+**The plan review MUST happen BEFORE you write any code for that step.**
+The entire purpose of plan review is to catch design issues, missing cases, and
+wrong approaches BEFORE you spend tokens implementing them. If you implement
+first and then request plan review, the reviewer's feedback is wasted — the
+code is already written.
+
+**Correct sequence:**
+1. Hydrate step checkboxes (expand the plan)
+2. Commit the hydrated STATUS.md
+3. **Call `review_step(step=N, type="plan")` — BEFORE writing any code**
+4. Handle verdict (APPROVE → implement; REVISE → fix plan, re-review)
+5. Implement the step (write code, check off items)
+6. Commit implementation
+7. Call `review_step(step=N, type="code")` — AFTER implementation
+
+**WRONG sequence (violates the protocol):**
+1. ~~Hydrate, implement, check off, commit, THEN call plan review~~ ❌
+   This makes plan review pointless — the work is already done.
+
 **Handling verdicts:**
-- **APPROVE** → proceed to next step
+- **APPROVE** → proceed (to implementation after plan review; to next step after code review)
 - **RETHINK** → reconsider your plan approach, adjust, then implement
 - **REVISE** → read the review file in `.reviews/` for detailed feedback,
   address the issues, commit fixes, then **call `review_step` again** for re-review.
@@ -211,14 +232,16 @@ value.
 
 **Example flow for a Review Level 2 task, Step 3:**
 1. Read Step 3 requirements
-2. Call `review_step(step=3, type="plan")` → get plan feedback
-3. Capture baseline: run `git rev-parse HEAD` and save the SHA
-4. Implement Step 3
-5. Commit changes
-6. Call `review_step(step=3, type="code", baseline="<saved SHA>")` → get code feedback
-7. If REVISE: fix issues, commit, call `review_step(step=3, type="code")` again
-8. Repeat 7 until APPROVE (max 2 code review cycles per step)
-9. Move to Step 4
+2. Hydrate Step 3 checkboxes, commit STATUS.md
+3. Call `review_step(step=3, type="plan")` → get plan feedback (**NO CODE YET**)
+4. If REVISE: adjust plan, re-request plan review
+5. If APPROVE: capture baseline SHA (`git rev-parse HEAD`)
+6. Implement Step 3 (write code, check off items)
+7. Commit changes
+8. Call `review_step(step=3, type="code", baseline="<saved SHA>")` → get code feedback
+9. If REVISE: fix issues, commit, call `review_step(step=3, type="code")` again
+10. Repeat 9 until APPROVE (max 2 code review cycles per step)
+11. Move to Step 4
 
 If the `review_step` tool is not available (e.g., non-orchestrated mode), skip
 this protocol entirely — the task-runner handles reviews externally.