taskplane 0.1.17 → 0.2.0

package/extensions/taskplane/types.ts

@@ -15,6 +15,8 @@ export interface OrchestratorConfig {
 		batch_id_format: "timestamp" | "sequential";
 		spawn_mode: "tmux" | "subprocess";
 		tmux_prefix: string;
+		/** Optional operator identifier. Auto-detected from OS username if empty. */
+		operator_id: string;
 	};
 	dependencies: {
 		source: "prompt" | "agent";
@@ -76,6 +78,8 @@ export interface LaneAssignment {
 	taskId: string;
 	lane: number;
 	task: ParsedTask;
+	/** Repo ID this task targets (workspace mode only). Undefined in repo mode. */
+	repoId?: string;
 }
 
 /** Runtime state of the entire batch execution */
@@ -144,6 +148,7 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 		batch_id_format: "timestamp",
 		spawn_mode: "subprocess",
 		tmux_prefix: "orch",
+		operator_id: "",
 	},
 	dependencies: {
 		source: "prompt",
@@ -222,6 +227,8 @@ export interface CreateWorktreeOptions {
 	baseBranch: string;
 	/** Worktree directory prefix (e.g. "taskplane-wt") */
 	prefix: string;
+	/** Operator identifier (sanitized, e.g., "henrylach") */
+	opId: string;
 	/** Full orchestrator config (optional; used for worktree_location) */
 	config?: OrchestratorConfig;
 }
@@ -367,7 +374,8 @@ export interface DiscoveryError {
 		| "DEP_AMBIGUOUS"
 		| "DEP_SOURCE_FALLBACK"
 		| "TASK_REPO_UNRESOLVED"
-		| "TASK_REPO_UNKNOWN";
+		| "TASK_REPO_UNKNOWN"
+		| "TASK_ROUTING_STRICT";
 	message: string;
 	taskPath?: string;
 	taskId?: string;
@@ -388,6 +396,7 @@ export const FATAL_DISCOVERY_CODES: ReadonlyArray<DiscoveryError["code"]> = [
 	"PARSE_MISSING_ID",
 	"TASK_REPO_UNRESOLVED",
 	"TASK_REPO_UNKNOWN",
+	"TASK_ROUTING_STRICT",
 ] as const;
 
 /** Result of the full discovery pipeline */
@@ -477,7 +486,7 @@ export interface AllocatedTask {
  * between Step 1 (allocation) and Step 2 (execution).
  */
 export interface AllocatedLane {
-	/** Lane number (1-indexed, deterministic) */
+	/** Lane number (1-indexed, deterministic, globally unique across repos) */
 	laneNumber: number;
 	/** Lane identifier for display and logging (e.g., "lane-1") */
 	laneId: string;
@@ -495,6 +504,8 @@ export interface AllocatedLane {
 	estimatedLoad: number;
 	/** Total estimated duration in minutes (sum of task durations) */
 	estimatedMinutes: number;
+	/** Repo ID this lane targets (workspace mode only). Undefined in repo mode. */
+	repoId?: string;
 }
 
 
@@ -815,6 +826,8 @@ export interface OrchBatchRuntimeState {
 	batchId: string;
 	/** Branch that was active when /orch started — used as base for worktrees and merge target */
 	baseBranch: string;
+	/** Workspace execution mode (v2). Defaults to "repo" for backward compatibility. */
+	mode: WorkspaceMode;
 	/** Shared pause signal — set by /orch-pause, read by executeLane/executeWave */
 	pauseSignal: { paused: boolean };
 	/** All wave results in order (grows as waves complete) */
@@ -892,6 +905,7 @@ export function freshOrchBatchState(): OrchBatchRuntimeState {
 		phase: "idle",
 		batchId: "",
 		baseBranch: "",
+		mode: "repo",
 		pauseSignal: { paused: false },
 		waveResults: [],
 		currentWaveIndex: -1,
@@ -965,6 +979,8 @@ export interface MergeLaneResult {
 	result: MergeResult | null;
 	error: string | null;
 	durationMs: number;
+	/** Repo ID this lane targeted (workspace mode only). Undefined in repo mode. */
+	repoId?: string;
 }
 
 /** Overall wave merge outcome. */
@@ -975,6 +991,22 @@ export interface MergeWaveResult {
 	failedLane: number | null;
 	failureReason: string | null;
 	totalDurationMs: number;
+	/** Per-repo merge outcomes (populated in workspace mode; empty in repo mode). */
+	repoResults?: RepoMergeOutcome[];
+}
+
+/** Per-repo merge outcome within a wave merge. */
+export interface RepoMergeOutcome {
+	/** Repo ID (undefined in repo mode default group). */
+	repoId: string | undefined;
+	/** Merge status for this repo. */
+	status: "succeeded" | "failed" | "partial";
+	/** Lane results belonging to this repo. */
+	laneResults: MergeLaneResult[];
+	/** Failed lane number within this repo (null if all succeeded). */
+	failedLane: number | null;
+	/** Failure reason within this repo (null if all succeeded). */
+	failureReason: string | null;
 }
 
 // ── Merge Error Types ────────────────────────────────────────────────
@@ -1107,9 +1139,21 @@ export interface OrchDashboardViewModel {
 /**
  * Current schema version for batch-state.json.
  * Increment when the persisted schema changes in incompatible ways.
- * loadBatchState() rejects files with a different schemaVersion.
+ *
+ * Version history:
+ *   v1 — Original schema (TS-009). No repo-aware fields on task records.
+ *         Lane records had optional `repoId` but it was not validated.
+ *   v2 — Repo-aware records (TP-006). Adds `repoId` and `resolvedRepoId`
+ *         to task records. Formalizes `repoId` on lane records. Adds
+ *         `mode` field to top-level state.
+ *
+ * Compatibility policy:
+ *   - loadBatchState() accepts v1 files and auto-upconverts to v2 in memory
+ *     (via upconvertV1toV2()). The on-disk file is NOT rewritten.
+ *   - saveBatchState() always writes v2.
+ *   - Schema versions > 2 are rejected with STATE_SCHEMA_INVALID.
  */
-export const BATCH_STATE_SCHEMA_VERSION = 1;
+export const BATCH_STATE_SCHEMA_VERSION = 2;
 
 /**
  * Canonical file path for persisted batch state.
@@ -1154,6 +1198,25 @@ export class StateFileError extends Error {
  *
  * Contains everything `/orch-resume` needs to reconstruct
  * task progress without re-running discovery.
+ *
+ * Repo-aware fields (v2):
+ *   `repoId` and `resolvedRepoId` capture task-to-repo attribution
+ *   so resume can reconstruct repo routing without re-running discovery.
+ *
+ *   Mode semantics:
+ *   - **repo mode**: Both fields are `undefined`. Tasks implicitly target
+ *     the single repository (cwd). No repo routing needed.
+ *   - **workspace mode**: `repoId` is the repo ID declared in PROMPT.md
+ *     (may be `undefined` if the task didn't declare one). `resolvedRepoId`
+ *     is the final repo ID after applying the routing precedence chain
+ *     (prompt → area → workspace default). Always a non-empty string in
+ *     workspace mode for tasks that passed routing validation.
+ *
+ *   Source of truth:
+ *   - For allocated tasks: derived from `ParsedTask.promptRepoId` and
+ *     `ParsedTask.resolvedRepoId` via `serializeBatchState()`.
+ *   - For unallocated/pending tasks: derived from the same ParsedTask
+ *     fields via discovery enrichment in `persistRuntimeState()`.
  */
 export interface PersistedTaskRecord {
 	/** Task identifier (e.g., "TO-014") */
@@ -1174,6 +1237,17 @@ export interface PersistedTaskRecord {
 	doneFileFound: boolean;
 	/** Human-readable exit reason (if completed/failed) */
 	exitReason: string;
+	/**
+	 * Repo ID declared in the task's PROMPT.md metadata (v2).
+	 * Undefined in repo mode or if the task didn't declare a repo.
+	 */
+	repoId?: string;
+	/**
+	 * Resolved repo ID after applying routing precedence (v2).
+	 * Undefined in repo mode. In workspace mode, this is the final
+	 * repo target after prompt → area → workspace-default fallback.
+	 */
+	resolvedRepoId?: string;
 }
 
 /**
@@ -1181,6 +1255,21 @@ export interface PersistedTaskRecord {
  *
  * Captures worktree/branch assignment so `/orch-resume` can
  * reconnect to existing worktrees without re-allocation.
+ *
+ * Repo-aware contract (v2):
+ *   `repoId` captures which repository this lane targets.
+ *
+ *   Mode semantics:
+ *   - **repo mode**: `repoId` is `undefined`. The lane's worktree is
+ *     created from the single repository (cwd). All lanes share the
+ *     same repo implicitly.
+ *   - **workspace mode**: `repoId` is a non-empty string matching a
+ *     key in `WorkspaceConfig.repos`. All tasks assigned to this lane
+ *     target the same repo. Lane allocation guarantees repo affinity
+ *     (no lane mixes tasks from different repos).
+ *
+ *   Source of truth: derived from `AllocatedLane.repoId` during
+ *   serialization in `serializeBatchState()`.
  */
 export interface PersistedLaneRecord {
 	/** Lane number (1-indexed) */
@@ -1195,6 +1284,12 @@ export interface PersistedLaneRecord {
 	branch: string;
 	/** Task IDs assigned to this lane in execution order */
 	taskIds: string[];
+	/**
+	 * Repo ID this lane targets (v2).
+	 * Undefined in repo mode. Non-empty string in workspace mode,
+	 * matching a key in `WorkspaceConfig.repos`.
+	 */
+	repoId?: string;
 }
 
 /**
@@ -1210,6 +1305,31 @@ export interface PersistedMergeResult {
 	failedLane: number | null;
 	/** Failure reason (null if all succeeded) */
 	failureReason: string | null;
+	/**
+	 * Per-repo merge outcomes (v2, TP-009).
+	 * Populated in workspace mode when MergeWaveResult.repoResults is available.
+	 * Undefined/absent in repo mode or for older state files. Dashboard treats
+	 * absence as single-repo merge.
+	 */
+	repoResults?: PersistedRepoMergeOutcome[];
+}
+
+/**
+ * Persisted per-repo merge outcome within a wave merge.
+ * Serializable subset of RepoMergeOutcome — excludes full MergeLaneResult
+ * objects (which contain detailed merge agent result JSON) to keep state file compact.
+ */
+export interface PersistedRepoMergeOutcome {
+	/** Repo ID. Undefined for the default group in repo mode. */
+	repoId: string | undefined;
+	/** Merge status for this repo. */
+	status: "succeeded" | "failed" | "partial";
+	/** Lane numbers involved in this repo's merge. */
+	laneNumbers: number[];
+	/** Failed lane number within this repo (null if all succeeded). */
+	failedLane: number | null;
+	/** Failure reason within this repo (null if all succeeded). */
+	failureReason: string | null;
 }
 
 /**
@@ -1226,9 +1346,16 @@ export interface PersistedMergeResult {
  * - Merge results are summarized (not full MergeWaveResult) for size
  * - `updatedAt` is monotonic (epoch ms) for staleness detection
  * - `lastError` captures most recent error without PII
+ *
+ * v2 additions (TP-006):
+ * - `mode` field captures workspace vs repo mode at batch start
+ * - Task records include `repoId` and `resolvedRepoId` for repo attribution
+ * - Lane records formalize `repoId` contract per mode
+ * - v1 files are auto-upconverted: `mode` defaults to "repo", task/lane
+ *   `repoId` fields default to `undefined` (omitted from JSON)
  */
 export interface PersistedBatchState {
-	/** Schema version — must equal BATCH_STATE_SCHEMA_VERSION */
+	/** Schema version — must equal BATCH_STATE_SCHEMA_VERSION (currently 2) */
 	schemaVersion: number;
 	/** Current batch execution phase */
 	phase: OrchBatchPhase;
@@ -1236,6 +1363,13 @@ export interface PersistedBatchState {
 	batchId: string;
 	/** Branch that was active when /orch started — used as base for worktrees and merge target */
 	baseBranch: string;
+	/**
+	 * Workspace execution mode at batch start (v2).
+	 * - "repo": Single-repo mode (default, backward-compatible).
+	 * - "workspace": Multi-repo workspace mode.
+	 * Defaults to "repo" when loading v1 state files.
+	 */
+	mode: WorkspaceMode;
 	/** Epoch ms when batch started */
 	startedAt: number;
 	/** Epoch ms when state was last written */
@@ -1326,7 +1460,7 @@ export interface ReconciledTaskState {
 	/** Whether the lane worktree still exists on disk */
 	worktreeExists: boolean;
 	/** Action the resume engine should take */
-	action: "reconnect" | "mark-complete" | "mark-failed" | "re-execute" | "skip";
+	action: "reconnect" | "mark-complete" | "mark-failed" | "re-execute" | "skip" | "pending";
 }
 
 /**
@@ -1599,6 +1733,19 @@ export interface WorkspaceRoutingConfig {
 	 * Must reference a valid key in `WorkspaceConfig.repos`.
 	 */
 	defaultRepo: string;
+	/**
+	 * When true, every task MUST declare an explicit execution target
+	 * (via `## Execution Target` section or inline `**Repo:**` in PROMPT.md).
+	 * Area-level and workspace-default fallbacks are still used for
+	 * validation (unknown-repo checks) but NOT for automatic resolution.
+	 *
+	 * This prevents accidental misrouting in large multi-team workspaces
+	 * where task authors must be intentional about which repo a task targets.
+	 *
+	 * Default: false (permissive — existing precedence chain applies).
+	 * Only meaningful in workspace mode.
+	 */
+	strict?: boolean;
 }
 
 /**