taskplane 0.27.0 → 0.28.0

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 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.27.0",
+  "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).