taskplane 0.1.14 → 0.1.16

package/extensions/taskplane/types.ts

@@ -12,7 +12,6 @@ export interface OrchestratorConfig {
 		max_lanes: number;
 		worktree_location: "sibling" | "subdirectory";
 		worktree_prefix: string;
-		integration_branch: string;
 		batch_id_format: "timestamp" | "sequential";
 		spawn_mode: "tmux" | "subprocess";
 		tmux_prefix: string;
@@ -60,6 +59,10 @@ export interface ParsedTask {
 	promptPath: string;
 	areaName: string;
 	status: "pending" | "complete";
+	/** Repo ID declared in the PROMPT metadata (e.g., "api", "frontend"). Undefined if not declared. */
+	promptRepoId?: string;
+	/** Resolved repo ID after routing precedence (workspace mode only). Undefined in repo mode. */
+	resolvedRepoId?: string;
 }
 
 /** A wave: a group of tasks whose dependencies are all satisfied */
@@ -106,6 +109,8 @@ export interface TaskArea {
 	path: string;
 	prefix: string;
 	context: string;
+	/** Optional repo ID for routing tasks in this area (workspace mode only). */
+	repoId?: string;
 }
 
 /** Subset of task-runner.yaml that the orchestrator needs */
@@ -136,7 +141,6 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 		max_lanes: 3,
 		worktree_location: "subdirectory",
 		worktree_prefix: "taskplane-wt",
-		integration_branch: "main",
 		batch_id_format: "timestamp",
 		spawn_mode: "subprocess",
 		tmux_prefix: "orch",
@@ -361,12 +365,31 @@ export interface DiscoveryError {
 		| "DEP_UNRESOLVED"
 		| "DEP_PENDING"
 		| "DEP_AMBIGUOUS"
-		| "DEP_SOURCE_FALLBACK";
+		| "DEP_SOURCE_FALLBACK"
+		| "TASK_REPO_UNRESOLVED"
+		| "TASK_REPO_UNKNOWN";
 	message: string;
 	taskPath?: string;
 	taskId?: string;
 }
 
+/**
+ * Discovery error codes that are fatal (block planning/execution).
+ *
+ * Used by formatDiscoveryResults, extension.ts, and engine.ts for
+ * consistent fatal-error classification. Keep in sync with the
+ * DiscoveryError.code union above.
+ */
+export const FATAL_DISCOVERY_CODES: ReadonlyArray<DiscoveryError["code"]> = [
+	"DUPLICATE_ID",
+	"DEP_UNRESOLVED",
+	"DEP_PENDING",
+	"DEP_AMBIGUOUS",
+	"PARSE_MISSING_ID",
+	"TASK_REPO_UNRESOLVED",
+	"TASK_REPO_UNKNOWN",
+] as const;
+
 /** Result of the full discovery pipeline */
 export interface DiscoveryResult {
 	pending: Map<string, ParsedTask>;
@@ -790,6 +813,8 @@ export interface OrchBatchRuntimeState {
 	phase: OrchBatchPhase;
 	/** Unique batch identifier (timestamp format, e.g., "20260308T214300") */
 	batchId: string;
+	/** Branch that was active when /orch started — used as base for worktrees and merge target */
+	baseBranch: string;
 	/** Shared pause signal — set by /orch-pause, read by executeLane/executeWave */
 	pauseSignal: { paused: boolean };
 	/** All wave results in order (grows as waves complete) */
@@ -866,6 +891,7 @@ export function freshOrchBatchState(): OrchBatchRuntimeState {
 	return {
 		phase: "idle",
 		batchId: "",
+		baseBranch: "",
 		pauseSignal: { paused: false },
 		waveResults: [],
 		currentWaveIndex: -1,
@@ -1208,6 +1234,8 @@ export interface PersistedBatchState {
 	phase: OrchBatchPhase;
 	/** Unique batch identifier (timestamp format) */
 	batchId: string;
+	/** Branch that was active when /orch started — used as base for worktrees and merge target */
+	baseBranch: string;
 	/** Epoch ms when batch started */
 	startedAt: number;
 	/** Epoch ms when state was last written */
@@ -1516,3 +1544,215 @@ export interface BatchHistorySummary {
 /** Max number of batch history entries to retain. */
 export const BATCH_HISTORY_MAX_ENTRIES = 100;
 
+
+// ── Workspace Mode Types ─────────────────────────────────────────────
+
+/**
+ * Workspace execution mode.
+ *
+ * Mode behavior contract:
+ * - **"repo"** (default): No workspace config file present. The orchestrator
+ *   treats `cwd` as both the workspace root and the single repo root.
+ *   All existing monorepo behavior is preserved unchanged.
+ * - **"workspace"**: A `.pi/taskplane-workspace.yaml` file is present and
+ *   valid. The orchestrator runs from a non-git workspace root that
+ *   coordinates multiple repos and a shared task root.
+ *
+ * Mode determination rules:
+ * 1. No workspace config file → repo mode (non-fatal default, silent).
+ * 2. Workspace config file present + invalid → fatal error with actionable
+ *    `WorkspaceConfigError` (never silently falls back to repo mode).
+ * 3. Workspace config file present + valid → workspace mode.
+ */
+export type WorkspaceMode = "repo" | "workspace";
+
+/**
+ * Configuration for a single repository within a workspace.
+ *
+ * Each repo is identified by a stable ID (e.g., "api", "frontend")
+ * that is used for routing tasks to repos and for display purposes.
+ */
+export interface WorkspaceRepoConfig {
+	/** Stable identifier for this repo (e.g., "api", "frontend") */
+	id: string;
+	/** Absolute filesystem path to the repo root (must be a git repo) */
+	path: string;
+	/** Optional default branch override (e.g., "develop", "main"). Falls back to repo HEAD. */
+	defaultBranch?: string;
+}
+
+/**
+ * Routing configuration for workspace mode.
+ *
+ * Controls where tasks are discovered and which repo receives
+ * unqualified operations.
+ */
+export interface WorkspaceRoutingConfig {
+	/**
+	 * Absolute path to the shared tasks root directory.
+	 * All task areas are resolved relative to this path.
+	 * Must exist on disk.
+	 */
+	tasksRoot: string;
+	/**
+	 * Default repo ID for operations that don't specify a repo.
+	 * Must reference a valid key in `WorkspaceConfig.repos`.
+	 */
+	defaultRepo: string;
+}
+
+/**
+ * Top-level workspace configuration.
+ *
+ * Loaded from `.pi/taskplane-workspace.yaml` when present.
+ * Immutable after initial validation — never mutated at runtime.
+ */
+export interface WorkspaceConfig {
+	/** Active workspace mode */
+	mode: WorkspaceMode;
+	/** Map of repo ID → repo configuration. At least one repo required in workspace mode. */
+	repos: Map<string, WorkspaceRepoConfig>;
+	/** Routing configuration (tasks root, default repo) */
+	routing: WorkspaceRoutingConfig;
+	/** Absolute path to the workspace config file that was loaded */
+	configPath: string;
+}
+
+/**
+ * Canonical execution context for the orchestrator.
+ *
+ * This is the primary runtime context threaded through orchestrator
+ * entry points. It replaces the previous pattern of passing raw `cwd`
+ * as the sole repo root.
+ *
+ * In repo mode, `workspaceRoot` and `repoRoot` are the same directory.
+ * In workspace mode, `workspaceRoot` is the non-git coordination root
+ * and `repoRoot` is the default repo from the workspace config.
+ *
+ * Design rationale:
+ * - Step 2 (wire orchestrator startup) will construct this from config
+ *   loading results and thread it into `executeOrchBatch()` and friends.
+ * - `repoRoot` is always a git repository, preserving the invariant
+ *   that git operations (worktree, branch, merge) have a valid target.
+ * - `workspaceConfig` is null in repo mode (no workspace file loaded).
+ */
+export interface ExecutionContext {
+	/** Absolute path to the workspace root (cwd in repo mode, workspace dir in workspace mode) */
+	workspaceRoot: string;
+	/** Absolute path to the default/primary git repo root */
+	repoRoot: string;
+	/** Active workspace mode */
+	mode: WorkspaceMode;
+	/** Workspace configuration (null in repo mode) */
+	workspaceConfig: WorkspaceConfig | null;
+	/** Loaded task runner configuration */
+	taskRunnerConfig: TaskRunnerConfig;
+	/** Loaded orchestrator configuration */
+	orchestratorConfig: OrchestratorConfig;
+}
+
+
+// ── Workspace Validation Error Types ─────────────────────────────────
+
+/**
+ * Error codes for workspace configuration validation failures.
+ *
+ * Each code maps to a deterministic validation rule from the workspace
+ * config loading pipeline. Codes are stable and machine-branchable.
+ *
+ * - WORKSPACE_FILE_READ_ERROR: Config file exists but cannot be read (permissions, encoding)
+ * - WORKSPACE_FILE_PARSE_ERROR: Config file contains invalid YAML
+ * - WORKSPACE_MISSING_REPOS: No repos defined in workspace config (at least one required)
+ * - WORKSPACE_REPO_PATH_MISSING: A repo entry has no `path` field
+ * - WORKSPACE_REPO_PATH_NOT_FOUND: A repo's `path` does not exist on disk
+ * - WORKSPACE_REPO_NOT_GIT: A repo's `path` exists but is not a git repository
+ * - WORKSPACE_MISSING_TASKS_ROOT: `routing.tasks_root` is missing or empty
+ * - WORKSPACE_TASKS_ROOT_NOT_FOUND: `routing.tasks_root` path does not exist on disk
+ * - WORKSPACE_MISSING_DEFAULT_REPO: `routing.default_repo` is missing or empty
+ * - WORKSPACE_DEFAULT_REPO_NOT_FOUND: `routing.default_repo` references a repo ID not in the repos map
+ * - WORKSPACE_DUPLICATE_REPO_PATH: Two or more repos share the same filesystem path
+ * - WORKSPACE_SCHEMA_INVALID: Config file has valid YAML but missing/invalid top-level structure
+ */
+export type WorkspaceConfigErrorCode =
+	| "WORKSPACE_FILE_READ_ERROR"
+	| "WORKSPACE_FILE_PARSE_ERROR"
+	| "WORKSPACE_MISSING_REPOS"
+	| "WORKSPACE_REPO_PATH_MISSING"
+	| "WORKSPACE_REPO_PATH_NOT_FOUND"
+	| "WORKSPACE_REPO_NOT_GIT"
+	| "WORKSPACE_MISSING_TASKS_ROOT"
+	| "WORKSPACE_TASKS_ROOT_NOT_FOUND"
+	| "WORKSPACE_MISSING_DEFAULT_REPO"
+	| "WORKSPACE_DEFAULT_REPO_NOT_FOUND"
+	| "WORKSPACE_DUPLICATE_REPO_PATH"
+	| "WORKSPACE_SCHEMA_INVALID";
+
+/**
+ * Typed error class for workspace configuration failures.
+ *
+ * Thrown during workspace config loading/validation when the config file
+ * is present but invalid. Never thrown when no config file exists (that
+ * case silently falls back to repo mode).
+ *
+ * Follows the established pattern of typed error classes in this module
+ * (WorktreeError, ExecutionError, MergeError, StateFileError, ResumeError).
+ */
+export class WorkspaceConfigError extends Error {
+	code: WorkspaceConfigErrorCode;
+	/** Optional repo ID that triggered the error (for repo-specific validation failures) */
+	repoId?: string;
+	/** Optional filesystem path related to the error */
+	relatedPath?: string;
+
+	constructor(code: WorkspaceConfigErrorCode, message: string, repoId?: string, relatedPath?: string) {
+		super(message);
+		this.name = "WorkspaceConfigError";
+		this.code = code;
+		this.repoId = repoId;
+		this.relatedPath = relatedPath;
+	}
+}
+
+
+// ── Workspace Defaults ───────────────────────────────────────────────
+
+/**
+ * Canonical filename for workspace configuration.
+ * Resolved relative to workspace root: `.pi/taskplane-workspace.yaml`
+ */
+export const WORKSPACE_CONFIG_FILENAME = "taskplane-workspace.yaml";
+
+/**
+ * Resolve the absolute path to the workspace config file.
+ * @param workspaceRoot - Absolute path to the workspace root
+ */
+export function workspaceConfigPath(workspaceRoot: string): string {
+	return join(workspaceRoot, ".pi", WORKSPACE_CONFIG_FILENAME);
+}
+
+/**
+ * Create a default ExecutionContext for repo mode.
+ *
+ * Used when no workspace config file is present. The workspace root
+ * and repo root are the same directory (cwd), preserving existing
+ * monorepo behavior exactly.
+ *
+ * @param cwd - Current working directory (treated as both workspace and repo root)
+ * @param taskRunnerConfig - Loaded task runner config (or defaults)
+ * @param orchestratorConfig - Loaded orchestrator config (or defaults)
+ */
+export function createRepoModeContext(
+	cwd: string,
+	taskRunnerConfig: TaskRunnerConfig,
+	orchestratorConfig: OrchestratorConfig,
+): ExecutionContext {
+	return {
+		workspaceRoot: cwd,
+		repoRoot: cwd,
+		mode: "repo",
+		workspaceConfig: null,
+		taskRunnerConfig,
+		orchestratorConfig,
+	};
+}
+