taskplane 0.26.1 → 0.28.0

package/extensions/taskplane/persistence.ts

@@ -1359,6 +1359,9 @@ export function serializeBatchState(
 		endedAt: state.endedAt,
 		currentWaveIndex: state.currentWaveIndex,
 		totalWaves: state.totalWaves,
+		// TP-166: Persist task-level wave metadata for correct display after resume
+		...(state.taskLevelWaveCount != null ? { taskLevelWaveCount: state.taskLevelWaveCount } : {}),
+		...(state.roundToTaskWave != null ? { roundToTaskWave: [...state.roundToTaskWave] } : {}),
 		wavePlan,
 		lanes: laneRecords,
 		tasks: taskRecords,

package/extensions/taskplane/resume.ts

@@ -7,7 +7,7 @@ import { join } from "path";
 
 import { assembleDiagnosticInput, emitDiagnosticReports } from "./diagnostic-reports.ts";
 import { runDiscovery } from "./discovery.ts";
-import { executeOrchBatch } from "./engine.ts";
+import { executeOrchBatch, resolveDisplayWaveNumber } from "./engine.ts";
 import { buildReviewerEnv, computeTransitiveDependents, execLog, executeLaneV2, executeWave, resolveCanonicalTaskPaths } from "./execution.ts";
 import type { MonitorUpdateCallback, RuntimeBackend } from "./execution.ts";
 import { selectRuntimeBackend } from "./engine.ts";
@@ -158,9 +158,14 @@ export function reconstructAllocatedLanes(
 			if (persistedTask?.resolvedRepoId !== undefined) {
 				taskStub.resolvedRepoId = persistedTask.resolvedRepoId;
 			}
-			if (persistedTask?.taskFolder) {
-				taskStub.taskFolder = persistedTask.taskFolder;
-			}
+			// TP-169: Always set taskFolder on stub, even if empty string.
+			// Previously, the falsy check `if (persistedTask?.taskFolder)` skipped
+			// empty-string values, leaving taskFolder as `undefined` on the stub.
+			// This caused crashes in buildExecutionUnit and merge code when
+			// accessing `task.task.taskFolder` on dynamically-expanded segments
+			// whose persisted records had taskFolder="" (the default from
+			// serializeBatchState before enrichment).
+			taskStub.taskFolder = persistedTask?.taskFolder ?? "";
 			if ((persistedTask as any)?.packetRepoId !== undefined) {
 				(taskStub as any).packetRepoId = (persistedTask as any).packetRepoId;
 			}
@@ -1324,6 +1329,10 @@ export async function resumeOrchBatch(
 	// Preserve pauseSignal if already set during "launching" phase (TP-040)
 	if (!batchState.pauseSignal?.paused) batchState.pauseSignal = { paused: false };
 	batchState.totalWaves = persistedState.totalWaves;
+	// TP-166: Restore task-level wave metadata for correct display.
+	// Normalize: fall back to totalWaves for pre-TP-166 state files.
+	batchState.taskLevelWaveCount = persistedState.taskLevelWaveCount ?? persistedState.totalWaves;
+	batchState.roundToTaskWave = persistedState.roundToTaskWave ? [...persistedState.roundToTaskWave] : undefined;
 	batchState.totalTasks = persistedState.totalTasks;
 	batchState.succeededTasks = resumePoint.completedTaskIds.length;
 	batchState.failedTasks = resumePoint.failedTaskIds.length;
@@ -1372,6 +1381,42 @@ export async function resumeOrchBatch(
 		batchState._extraFields = persistedState._extraFields;
 	}
 
+	// ── 6b. TP-169: Verify orch branch exists in all workspace repos ────
+	// During the original batch start, the orch branch was created in every
+	// workspace repo. On resume, we verify it still exists. If it's missing
+	// in any repo (e.g., deleted by user, corrupted), re-create it from the
+	// repo's current branch so that worktree creation doesn't silently fall
+	// back to the base branch, bypassing orch branch isolation.
+	if (workspaceConfig && batchState.orchBranch) {
+		for (const [repoId, repoConf] of workspaceConfig.repos) {
+			const rRoot = repoConf.path;
+			const check = runGit(["rev-parse", "--verify", `refs/heads/${batchState.orchBranch}`], rRoot);
+			if (!check.ok) {
+				// Orch branch missing in this repo — re-create from current HEAD
+				const repoBranch = getCurrentBranch(rRoot) || "HEAD";
+				const createRes = runGit(["branch", batchState.orchBranch, repoBranch], rRoot);
+				if (createRes.ok) {
+					execLog("resume", batchState.batchId, `re-created missing orch branch in ${repoId}`, {
+						orchBranch: batchState.orchBranch,
+						base: repoBranch,
+					});
+					onNotify(
+						`⚠️ Orch branch "${batchState.orchBranch}" was missing in repo "${repoId}" — re-created from ${repoBranch}`,
+						"warning",
+					);
+				} else {
+					const errMsg = `Failed to re-create orch branch "${batchState.orchBranch}" in repo "${repoId}": ${createRes.stderr}. ` +
+						`Cannot resume without orch branch isolation.`;
+					execLog("resume", batchState.batchId, errMsg, {
+						orchBranch: batchState.orchBranch,
+						error: createRes.stderr,
+					});
+					throw new Error(errMsg);
+				}
+			}
+		}
+	}
+
 	// ── 7. Re-run discovery for ParsedTask metadata ──────────────
 	// We need fresh ParsedTask data (taskFolder, promptPath) for execution.
 	// Use "all" to discover all areas.
@@ -1767,12 +1812,17 @@ export async function resumeOrchBatch(
 		persistedState.tasks.map((task) => [task.taskId, task.status] as const),
 	);
 
+	// TP-166: Use task-level wave metadata for correct display.
+	const roundToTaskWave = batchState.roundToTaskWave;
+	const taskLevelWaveCount = batchState.taskLevelWaveCount;
+
 	for (let waveIdx = resumePoint.resumeWaveIndex; waveIdx < wavePlan.length; waveIdx++) {
 		// Check pause signal
 		if (batchState.pauseSignal.paused) {
 			batchState.phase = "paused";
 			persistRuntimeState("pause-before-wave", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
-			onNotify(`⏸️  Batch paused before wave ${waveIdx + 1}.`, "warning");
+			const { displayWave: pauseWave } = resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount);
+			onNotify(`⏸️  Batch paused before wave ${pauseWave}.`, "warning");
 			break;
 		}
 
@@ -1807,7 +1857,7 @@ export async function resumeOrchBatch(
 			// All tasks are terminal but the merge may have failed/been interrupted.
 			if (resumePoint.mergeRetryWaveIndexes.includes(waveIdx)) {
 				execLog("resume", batchState.batchId, `wave ${waveIdx + 1}: all tasks done but merge needs retry`);
-				onNotify(`🔀 Wave ${waveIdx + 1}: retrying merge (tasks already complete, merge was missing/failed)`, "info");
+				onNotify(`🔀 Wave ${resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave}: retrying merge (tasks already complete, merge was missing/failed)`, "info");
 
 				// Reconstruct lanes for this wave from persisted state
 				const waveTaskIds = new Set(wavePlan[waveIdx]);
@@ -1922,7 +1972,7 @@ export async function resumeOrchBatch(
 				batchState.mergeResults.push(mergeRetryResult);
 
 				if (mergeRetryResult.status === "succeeded") {
-					onNotify(`✅ Wave ${waveIdx + 1} merge retry succeeded`, "info");
+					onNotify(`✅ Wave ${resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave} merge retry succeeded`, "info");
 					// Clean up merged branches
 					for (const lr of mergeRetryResult.laneResults) {
 						if (!lr.error && (lr.result?.status === "SUCCESS" || lr.result?.status === "CONFLICT_RESOLVED")) {
@@ -1932,7 +1982,7 @@ export async function resumeOrchBatch(
 					}
 				} else {
 					onNotify(
-						`⚠️ Wave ${waveIdx + 1} merge retry ${mergeRetryResult.status}: ${mergeRetryResult.failureReason || "unknown"}`,
+						`⚠️ Wave ${resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave} merge retry ${mergeRetryResult.status}: ${mergeRetryResult.failureReason || "unknown"}`,
 						"warning",
 					);
 					// Apply merge failure policy (same as normal wave merge failure)
@@ -1954,10 +2004,13 @@ export async function resumeOrchBatch(
 			continue;
 		}
 
-		onNotify(
-			ORCH_MESSAGES.orchWaveStart(waveIdx + 1, wavePlan.length, waveTasks.length, Math.min(waveTasks.length, orchConfig.orchestrator.max_lanes)),
-			"info",
-		);
+		{
+			const { displayWave, displayTotal } = resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount);
+			onNotify(
+				ORCH_MESSAGES.orchWaveStart(displayWave, displayTotal, waveTasks.length, Math.min(waveTasks.length, orchConfig.orchestrator.max_lanes)),
+				"info",
+			);
+		}
 
 		const handleResumeMonitorUpdate: MonitorUpdateCallback = (monitorState) => {
 			const changed = syncTaskOutcomesFromMonitor(monitorState, allTaskOutcomes);
@@ -2064,7 +2117,7 @@ export async function resumeOrchBatch(
 					frontierSummary +
 					`  Lane: ${laneForTask?.laneId ?? "unknown"} (lane ${laneForTask?.laneNumber ?? "?"})\n` +
 					`  Partial progress preserved: ${hasPartialProgress ? "yes" : "no"}\n` +
-					`  Batch: wave ${waveIdx + 1}/${batchState.totalWaves}, ` +
+					`  Batch: wave ${resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave}/${taskLevelWaveCount ?? batchState.totalWaves}, ` +
 					`${batchState.succeededTasks} succeeded, ${batchState.failedTasks} failed\n\n` +
 					`Available actions:\n` +
 					`  - orch_status() to inspect current state\n` +
@@ -2088,16 +2141,19 @@ export async function resumeOrchBatch(
 		persistRuntimeState("wave-execution-complete", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
 
 		const elapsedSec = Math.round((waveResult.endedAt - waveResult.startedAt) / 1000);
-		onNotify(
-			ORCH_MESSAGES.orchWaveComplete(
-				waveIdx + 1,
-				waveResult.succeededTaskIds.length,
-				waveResult.failedTaskIds.length,
-				waveResult.skippedTaskIds.length,
-				elapsedSec,
-			),
-			waveResult.failedTaskIds.length > 0 ? "warning" : "info",
-		);
+		{
+			const { displayWave: completeDisplayWave } = resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount);
+			onNotify(
+				ORCH_MESSAGES.orchWaveComplete(
+					completeDisplayWave,
+					waveResult.succeededTaskIds.length,
+					waveResult.failedTaskIds.length,
+					waveResult.skippedTaskIds.length,
+					elapsedSec,
+				),
+				waveResult.failedTaskIds.length > 0 ? "warning" : "info",
+			);
+		}
 
 		// Check failure policy
 		if (waveResult.stoppedEarly) {
@@ -2144,7 +2200,7 @@ export async function resumeOrchBatch(
 			if (mergeableLaneCount > 0) {
 				batchState.phase = "merging";
 				persistRuntimeState("merge-start", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
-				onNotify(ORCH_MESSAGES.orchMergeStart(waveIdx + 1, mergeableLaneCount), "info");
+				onNotify(ORCH_MESSAGES.orchMergeStart(resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave, mergeableLaneCount), "info");
 
 				mergeResult = await mergeWaveByRepo(
 					waveResult.allocatedLanes,
@@ -2197,10 +2253,10 @@ export async function resumeOrchBatch(
 				const mergeTotalSec = Math.round(mergeResult.totalDurationMs / 1000);
 
 				if (mergeResult.status === "succeeded") {
-					onNotify(ORCH_MESSAGES.orchMergeComplete(waveIdx + 1, mergedCount, mergeTotalSec), "info");
+					onNotify(ORCH_MESSAGES.orchMergeComplete(resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave, mergedCount, mergeTotalSec), "info");
 				} else {
 					onNotify(
-						ORCH_MESSAGES.orchMergeFailed(waveIdx + 1, mergeResult.failedLane ?? 0, mergeResult.failureReason || "unknown"),
+						ORCH_MESSAGES.orchMergeFailed(resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave, mergeResult.failedLane ?? 0, mergeResult.failureReason || "unknown"),
 						"error",
 					);
 
@@ -2231,14 +2287,14 @@ export async function resumeOrchBatch(
 				// Downstream retry/update paths assume the current wave has an entry.
 				batchState.mergeResults.push(mergeResult);
 				onNotify(
-					ORCH_MESSAGES.orchMergeFailed(waveIdx + 1, mergeResult.failedLane, mergeResult.failureReason || "unknown"),
+					ORCH_MESSAGES.orchMergeFailed(resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave, mergeResult.failedLane, mergeResult.failureReason || "unknown"),
 					"error",
 				);
 			} else {
-				onNotify(ORCH_MESSAGES.orchMergeSkipped(waveIdx + 1), "info");
+				onNotify(ORCH_MESSAGES.orchMergeSkipped(resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave), "info");
 			}
 		} else {
-			onNotify(ORCH_MESSAGES.orchMergeSkipped(waveIdx + 1), "info");
+			onNotify(ORCH_MESSAGES.orchMergeSkipped(resolveDisplayWaveNumber(waveIdx, roundToTaskWave, taskLevelWaveCount).displayWave), "info");
 		}
 
 		// ── TP-033: Safe-stop on rollback failure ─────────────────
@@ -2755,7 +2811,7 @@ export async function resumeOrchBatch(
 				summary:
 					`✅ Batch ${batchState.batchId} completed\n` +
 					`  ${batchState.succeededTasks}/${batchState.totalTasks} tasks succeeded\n` +
-					`  ${batchState.totalWaves} wave(s), duration: ${durationStr}\n` +
+					`  ${batchState.taskLevelWaveCount ?? batchState.totalWaves} wave(s), duration: ${durationStr}\n` +
 					`  Merged to orch branch: ${batchState.orchBranch}\n\n` +
 					`Ready for integration. Run orch_integrate() or review first.`,
 				context: {

package/extensions/taskplane/supervisor-primer.md

@@ -718,6 +718,7 @@ or check status manually. The engine wakes you up when you're needed.
 | `task-failure` | ⚠️ | A task failed after deterministic recovery was exhausted |
 | `merge-failure` | ⚠️ | Wave merge failed and batch paused |
 | `batch-complete` | ✅/⚠️ | Batch finished (all waves done, with or without failures) |
+| `worker-exit-intercept` | 🔄 | A worker exited without making progress — session still alive, awaiting instructions |
 
 ### Alert Format
 
@@ -1011,6 +1012,60 @@ BATCH COMPLETE: {batchId}
 | merge-failure | Agent timeout, no result | `orch_resume(force=true)` to retry | Automatic |
 | batch-complete | All succeeded | Report → suggest `orch_integrate` | Report only |
 | batch-complete | Some failed | Report with failure details | Report only |
+| worker-exit-intercept | Worker analyzing, not editing | `send_agent_message` with targeted instructions | Automatic |
+| worker-exit-intercept | Worker genuinely stuck | "skip" or "let it fail" to close session | Supervised |
+| worker-exit-intercept | Unknown reason | Read STATUS.md, diagnose, then instruct or close | Automatic |
+
+---
+
+## 13c. Worker Exit Interception (TP-172)
+
+When a worker agent produces a text-only response (no tool calls, no file
+edits) without having made visible progress (no checkbox updates), the
+lane-runner **intercepts the exit** instead of closing the session. The worker
+process remains alive with its full conversation context preserved.
+
+**You receive a `worker-exit-intercept` alert** with:
+- Lane number and task ID
+- Current step and unchecked checkboxes
+- Worker's last assistant message (truncated to 500 chars)
+- Iteration count and no-progress count
+
+### Response Protocol
+
+1. **Read the worker's message** — understand why it wants to exit.
+   Common patterns:
+   - "I've analyzed the code and I'm not sure how to proceed"
+   - "I need more information about X"
+   - Generic summary without any file edits
+
+2. **Decide** — based on diagnosis:
+   - **If the worker needs direction:** Send targeted instructions via
+     `send_agent_message(to, content)` with specific guidance on what to
+     implement, which file to edit, or which approach to take.
+   - **If the task is genuinely blocked:** Reply with `"skip"` or
+     `"let it fail"` to close the session normally.
+
+3. **Send your response** — The lane-runner polls for your reply for
+   60 seconds. If you don't respond in time, the session closes and
+   the normal corrective re-spawn mechanism takes over.
+
+### Example Instructions
+
+```
+send_agent_message(
+  to: "orch-henrylach-lane-1-worker",
+  content: "Stop analyzing and start implementing. Edit agent-host.ts line 605:
+    replace the closeStdin() call with the interception logic described in
+    PROMPT.md Step 1. Write the code now — don't read more files."
+)
+```
+
+### Interception Limits
+
+Each worker session can be intercepted at most **2 times** (configurable via
+`maxExitInterceptions`). After the limit is reached, the session closes
+normally and the stall detector handles subsequent iterations.
 
 ---
 

package/extensions/taskplane/types.ts

@@ -125,6 +125,11 @@ export interface ParsedTask {
 	 * Null when no segment is active.
 	 */
 	activeSegmentId?: string | null;
+	/**
+	 * Step-to-segment checkbox mapping parsed from PROMPT.md `#### Segment:` markers.
+	 * Populated by discovery (Phase A, TP-173). Undefined if not yet parsed.
+	 */
+	stepSegmentMap?: StepSegmentMapping[];
 }
 
 /** Build a stable segment ID from task + repo identity (`<taskId>::<repoId>[::N]`). */
@@ -152,6 +157,21 @@ export function buildExpansionRequestId(timestamp = Date.now()): string {
 	return `exp-${ts}-${random5}`;
 }
 
+// ── Step-Segment Mapping (Phase A: segment-scoped worker visibility) ────
+
+/** A group of checkboxes scoped to a single repo within a step. */
+export interface SegmentCheckboxGroup {
+	repoId: string;
+	checkboxes: string[];
+}
+
+/** Maps a step to its repo-scoped checkbox groups. */
+export interface StepSegmentMapping {
+	stepNumber: number;
+	stepName: string;
+	segments: SegmentCheckboxGroup[];
+}
+
 /** One repo-scoped segment node for a task. */
 export interface TaskSegmentNode {
 	segmentId: SegmentId;
@@ -569,7 +589,10 @@ export interface DiscoveryError {
 		| "TASK_REPO_UNKNOWN"
 		| "TASK_ROUTING_STRICT"
 		| "SEGMENT_DAG_INVALID"
-		| "SEGMENT_REPO_UNKNOWN";
+		| "SEGMENT_REPO_UNKNOWN"
+		| "SEGMENT_STEP_DUPLICATE_REPO"
+		| "SEGMENT_STEP_EMPTY"
+		| "SEGMENT_STEP_REPO_INVALID";
 	message: string;
 	taskPath?: string;
 	taskId?: string;
@@ -593,6 +616,7 @@ export const FATAL_DISCOVERY_CODES: ReadonlyArray<DiscoveryError["code"]> = [
 	"TASK_ROUTING_STRICT",
 	"SEGMENT_DAG_INVALID",
 	"SEGMENT_REPO_UNKNOWN",
+	"SEGMENT_STEP_DUPLICATE_REPO",
 ] as const;
 
 /** Result of the full discovery pipeline */
@@ -1109,8 +1133,20 @@ export interface OrchBatchRuntimeState {
 	waveResults: WaveExecutionResult[];
 	/** Current wave index (0-based into waves array, -1 if not started) */
 	currentWaveIndex: number;
-	/** Total number of waves planned */
+	/** Total number of waves planned (segment rounds — internal) */
 	totalWaves: number;
+	/**
+	 * Number of dependency-driven task-level waves (TP-166).
+	 * Used for operator-facing "Wave X of Y" display. When undefined,
+	 * falls back to `totalWaves` for backward compatibility.
+	 */
+	taskLevelWaveCount?: number;
+	/**
+	 * Maps each segment round index (0-based) to its parent task-level
+	 * wave index (0-based). Updated when continuation rounds are inserted.
+	 * Used with `resolveDisplayWaveNumber()` for correct display. (TP-166)
+	 */
+	roundToTaskWave?: number[];
 	/** Set of task IDs blocked for future waves (from skip-dependents policy) */
 	blockedTaskIds: Set<string>;
 	/** Epoch ms when batch started */
@@ -2020,6 +2056,7 @@ export type SupervisorAlertCategory =
 	| "merge-failure"
 	| "batch-complete"
 	| "agent-message"
+	| "worker-exit-intercept"
 	| "segment-expansion-requested"
 	| "segment-expansion-approved"
 	| "segment-expansion-rejected";
@@ -2921,6 +2958,16 @@ export interface PersistedBatchState {
 	currentWaveIndex: number;
 	/** Total number of waves in the plan */
 	totalWaves: number;
+	/**
+	 * Number of dependency-driven task-level waves (TP-166).
+	 * Undefined for batches created before TP-166; falls back to totalWaves.
+	 */
+	taskLevelWaveCount?: number;
+	/**
+	 * Maps segment round index (0-based) to parent task-level wave (0-based).
+	 * Undefined for batches created before TP-166.
+	 */
+	roundToTaskWave?: number[];
 	/** Wave plan: array of arrays of task IDs per wave */
 	wavePlan: string[][];
 	/** Per-lane configuration records */
@@ -4017,7 +4064,9 @@ export type RuntimeAgentEventType =
 	// Review / bridge
 	| "review_requested"
 	| "review_completed"
-	| "review_failed";
+	| "review_failed"
+	// Exit interception (TP-172)
+	| "exit_intercepted";
 
 // ── Runtime V2 Path Helpers (TP-102) ─────────────────────────────────
 

package/package.json

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

package/skills/create-taskplane-task/SKILL.md

@@ -369,6 +369,64 @@ files and make sure their file scopes reflect that.
 
 ---
 
+## Multi-Repo Segment Markers
+
+When a task spans multiple repos (e.g., shared-libs + web-client), the skill
+must generate **segment markers** inside each step so the orchestrator can
+route checkboxes to the correct repo's worker.
+
+### Workflow
+
+1. Read workspace config to identify available repos and their roles
+2. Analyze the task description and file scope — determine which repos are involved
+3. Group work into steps by logical goal, with segments per repo within each step
+4. Write PROMPT.md with `#### Segment: <repoId>` markers in every step
+5. Write STATUS.md with matching structure
+
+### Marker Format
+
+Within each step, use level-4 headings to separate work by repo:
+
+```markdown
+### Step 1: Create utilities and API client
+
+#### Segment: shared-libs
+
+- [ ] Create string utility module
+- [ ] Export from package index
+
+#### Segment: web-client
+
+- [ ] Add API client wrapper
+- [ ] Wire into app initialization
+```
+
+### Ordering Rules
+
+Order steps so that dependencies flow correctly:
+
+1. **Shared/common work** → early steps (e.g., shared libraries, schemas)
+2. **Per-repo implementation** → middle steps (consumers of shared work)
+3. **Integration/documentation** → final steps (always in the packet repo)
+
+The final documentation/delivery step always uses `#### Segment: <packet-repo>`
+where `<packet-repo>` is the repo that contains the task's PROMPT.md.
+
+### Guidelines
+
+- **Always write explicit markers.** Never rely on the engine's single-segment
+  fallback for multi-repo tasks. Every step must have at least one
+  `#### Segment: <repoId>` marker.
+- **Max 10 segments per task.** Tasks spanning more repos should be split into
+  separate tasks with dependencies.
+- **Single-repo tasks do not need segment markers.** The engine's fallback
+  handles them correctly. Only add markers when file scope spans multiple repos.
+- **When pre-decomposition isn't possible** (e.g., the worker must discover
+  which repos are affected), include guidance about using
+  `request_segment_expansion` for dynamic expansion at runtime.
+
+---
+
 ## Preventing Empty Completions
 
 Workers can shortcut tasks by observing that existing code "already satisfies"

package/skills/create-taskplane-task/references/prompt-template.md

@@ -88,6 +88,37 @@ Review Level 0 is ONLY for trivial changes. Most M+ tasks need Level ≥1.
 **Artifacts:**
 - `path/to/file` (new | modified)
 
+> **Multi-repo variant:** When file scope spans multiple repos, use
+> `#### Segment: <repoId>` markers within each step instead of flat checkboxes.
+> Replace the single-repo Step 1 above with segment-annotated steps like:
+>
+> ```markdown
+> ### Step 1: [Name]
+>
+> #### Segment: shared-libs
+>
+> - [ ] Create string utility module
+> - [ ] Export from package index
+>
+> #### Segment: web-client
+>
+> - [ ] Add API client wrapper
+> - [ ] Wire into app initialization
+>
+> ### Step [N]: Documentation & Delivery
+>
+> #### Segment: [packet-repo]
+>
+> - [ ] "Must Update" docs modified
+> - [ ] Discoveries logged in STATUS.md
+> ```
+>
+> Rules:
+> - Always use explicit `#### Segment: <repoId>` markers (never rely on fallback)
+> - Order: shared/common repos → per-repo impl → integration/docs (packet repo)
+> - Final documentation/delivery step always uses the packet repo
+> - Max 10 segments per task; split larger tasks with dependencies
+
 ### Step [N-1]: Testing & Verification
 
 > ZERO test failures allowed. This step runs the FULL test suite as a quality gate.
@@ -191,6 +222,14 @@ this from PROMPT.md.
 
 - [ ] [High-level placeholder — worker will expand]
 
+[Multi-repo variant — use segment markers matching PROMPT.md:]
+
+#### Segment: [repo-a]
+- [ ] [Item in repo-a]
+
+#### Segment: [repo-b]
+- [ ] [Item in repo-b]
+
 ---
 
 ### Step [N-1]: Testing & Verification

package/templates/agents/task-worker-segment.md

@@ -0,0 +1,44 @@
+---
+name: task-worker-segment
+description: Segment-scoped worker for multi-repo polyrepo tasks — works only on assigned segment checkboxes
+tools: read,write,edit,bash,grep,find,ls
+# model:
+---
+## Segment-Scoped Execution Rules
+
+You are executing ONE SEGMENT of a multi-segment polyrepo task. Your iteration
+prompt lists which checkboxes are yours under "Your checkboxes for this step:".
+
+**YOUR RULES (these override any conflicting general rules):**
+
+1. **Only work on YOUR checkboxes** — the ones listed under "Your checkboxes
+   for this step:" in your iteration prompt. Do NOT work on checkboxes listed
+   under "Other segments in this step (NOT yours)."
+
+2. **When all YOUR checkboxes are checked, your segment is done — exit.**
+   Do not continue to other steps. Do not look for more work. Your segment
+   is complete.
+
+3. **Do NOT modify files in repos not available in your worktree.** You are
+   in a specific repo's worktree. Files in other repos are not accessible.
+
+4. **If you discover work needed in another repo**, use `request_segment_expansion`
+   with step definitions describing what the next segment's worker should do.
+   Include a `context` field explaining what you built and what the next worker
+   needs to know.
+
+5. **If your assigned checkbox list is empty**, do NOT exit as complete. Log a
+   blocker in STATUS.md and escalate — something is wrong with the task setup.
+
+## Context from Prior Segments
+
+If your prompt includes "Context from prior segment," this was written by a
+worker who discovered the need for your work. Read it carefully — it contains
+knowledge about what was built in a prior segment that you need to build on.
+
+## Checkpoint Discipline
+
+Same as the base worker prompt: check off each checkbox IMMEDIATELY after
+completing it. Commit at step boundaries. The only difference is that your
+"step" may contain only a subset of the full step's checkboxes (your segment's
+portion).