taskplane 0.22.3 → 0.22.5

package/dashboard/server.cjs

@@ -792,7 +792,17 @@ function computeBatchTotalCost(laneStates, telemetry) {
 function buildDashboardState() {
   const state = loadBatchState();
   const tmuxSessions = getTmuxSessions();
-  const laneStates = loadLaneStates();
+  const rawLaneStates = loadLaneStates();
+  // Filter stale lane states from previous batches.
+  // Lane state files persist across batches (same filename), so without
+  // filtering the dashboard shows telemetry from old runs.
+  const currentBatchId = state?.batchId || null;
+  const laneStates = {};
+  for (const [key, ls] of Object.entries(rawLaneStates)) {
+    if (!currentBatchId || !ls.batchId || ls.batchId === currentBatchId) {
+      laneStates[key] = ls;
+    }
+  }
   const telemetry = loadTelemetryData(state);
   const batchTotalCost = computeBatchTotalCost(laneStates, telemetry);
   const supervisor = loadSupervisorData(state);

package/extensions/task-runner.ts

@@ -447,6 +447,7 @@ function writeLaneState(state: TaskState): void {
 			reviewerOutputTokens: state.reviewerOutputTokens || 0,
 			reviewerCacheReadTokens: state.reviewerCacheReadTokens || 0,
 			reviewerCacheWriteTokens: state.reviewerCacheWriteTokens || 0,
+			batchId: process.env.ORCH_BATCH_ID || null,
 			timestamp: Date.now(),
 		};
 		writeFileSync(filePath, JSON.stringify(data) + "\n");
@@ -2973,8 +2974,35 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 		} else {
-			// ── Quality Gate Disabled (default) ──────────────────────
-			// Unchanged behavior — create .DONE immediately.
+			// ── Empty completion guard ────────────────────────────────
+			// Detect tasks where the worker checked off STATUS.md without
+			// modifying any source files. This catches "shortcut" completions
+			// where the worker concludes work is "already done" without
+			// implementing anything.
+			if (isOrchestratedMode()) {
+				try {
+					const diffResult = spawnSync("git", ["diff", "--name-only", "HEAD"], {
+						cwd: task.taskFolder, encoding: "utf-8", timeout: 10_000,
+					});
+					const changedFiles = (diffResult.stdout || "").split("\n").filter(Boolean);
+					const sourceChanges = changedFiles.filter(f =>
+						!f.endsWith("STATUS.md") && !f.endsWith(".DONE") &&
+						!f.includes(".reviews/") && !f.endsWith("dependencies.json")
+					);
+					if (sourceChanges.length === 0) {
+						logExecution(statusPath, "⚠️ Empty completion",
+							"Worker marked all steps complete but no source files were modified. " +
+							"Only STATUS.md changes detected. This may indicate the worker shortcut " +
+							"the task without implementing. .DONE will still be created, but this " +
+							"should be investigated.");
+						console.error(`[task-runner] WARNING: Task ${task.taskId} completed with zero source file changes`);
+					}
+				} catch {
+					// Best effort — don't block .DONE creation on git check failure
+				}
+			}
+
+			// Create .DONE
 			const donePath = join(task.taskFolder, ".DONE");
 			writeFileSync(donePath, `Completed: ${new Date().toISOString()}\nTask: ${task.taskId}\n`);
 			updateStatusField(statusPath, "Status", "✅ Complete");

package/extensions/taskplane/config-loader.ts

@@ -43,6 +43,7 @@ import type {
 	TaskplaneConfig,
 	TaskRunnerSection,
 	OrchestratorSection,
+	WorkspaceSectionConfig,
 	UserPreferences,
 } from "./config-schema.ts";
 
@@ -270,6 +271,71 @@ function mapOrchestratorYaml(raw: any): Partial<OrchestratorSection> {
 	return result;
 }
 
+/**
+ * Normalize a workspace section loaded from JSON/YAML into camelCase shape.
+ *
+ * Compatibility: if `routing.taskPacketRepo` is missing, defaults to
+ * `routing.defaultRepo` and emits a warning message.
+ */
+function normalizeWorkspaceSection(
+	rawWorkspace: any,
+	sourcePath: string,
+): WorkspaceSectionConfig | undefined {
+	if (!rawWorkspace || typeof rawWorkspace !== "object" || Array.isArray(rawWorkspace)) {
+		return undefined;
+	}
+
+	const rawRepos = rawWorkspace.repos;
+	if (!rawRepos || typeof rawRepos !== "object" || Array.isArray(rawRepos)) {
+		return undefined;
+	}
+
+	const rawRouting = rawWorkspace.routing;
+	if (!rawRouting || typeof rawRouting !== "object" || Array.isArray(rawRouting)) {
+		return undefined;
+	}
+
+	const repos: WorkspaceSectionConfig["repos"] = {};
+	for (const [repoId, repoVal] of Object.entries(rawRepos as Record<string, any>)) {
+		if (!repoVal || typeof repoVal !== "object" || Array.isArray(repoVal)) continue;
+		const repoObj = repoVal as Record<string, any>;
+		if (typeof repoObj.path !== "string" || repoObj.path.trim() === "") continue;
+		repos[repoId] = {
+			path: repoObj.path,
+			...(typeof repoObj.defaultBranch === "string" && repoObj.defaultBranch.trim()
+				? { defaultBranch: repoObj.defaultBranch }
+				: {}),
+		};
+	}
+
+	const defaultRepo = typeof rawRouting.defaultRepo === "string" ? rawRouting.defaultRepo.trim() : "";
+	const tasksRoot = typeof rawRouting.tasksRoot === "string" ? rawRouting.tasksRoot.trim() : "";
+	let taskPacketRepo = typeof rawRouting.taskPacketRepo === "string" ? rawRouting.taskPacketRepo.trim() : "";
+
+	if (!taskPacketRepo && defaultRepo) {
+		taskPacketRepo = defaultRepo;
+		console.error(
+			`[taskplane] config compatibility: workspace.routing.taskPacketRepo is missing in ${sourcePath}; defaulting to workspace.routing.defaultRepo ('${defaultRepo}'). Add workspace.routing.taskPacketRepo explicitly.`,
+		);
+	}
+
+	if (!tasksRoot || !defaultRepo || !taskPacketRepo) {
+		return undefined;
+	}
+
+	const strict = rawRouting.strict === true;
+
+	return {
+		repos,
+		routing: {
+			tasksRoot,
+			defaultRepo,
+			taskPacketRepo,
+			...(strict ? { strict: true } : {}),
+		},
+	};
+}
+
 
 // ── Config File Path Resolution ──────────────────────────────────────
 
@@ -354,6 +420,12 @@ function loadJsonConfig(configRoot: string): TaskplaneConfig | null {
 	if (parsed.orchestrator) {
 		deepMerge(config.orchestrator, parsed.orchestrator);
 	}
+	if (parsed.workspace) {
+		const normalizedWorkspace = normalizeWorkspaceSection(parsed.workspace, jsonPath);
+		if (normalizedWorkspace) {
+			config.workspace = normalizedWorkspace;
+		}
+	}
 
 	return config;
 }
@@ -438,6 +510,29 @@ function loadOrchestratorYaml(configRoot: string): OrchestratorSection {
 	}
 }
 
+/**
+ * Load optional workspace routing config from legacy `taskplane-workspace.yaml`.
+ *
+ * This file is fallback-only for workspace metadata when JSON `workspace`
+ * section is not present. Malformed files are ignored here — strict validation
+ * still happens in workspace runtime loading (`workspace.ts`).
+ */
+function loadWorkspaceYaml(configRoot: string): WorkspaceSectionConfig | undefined {
+	const yamlPath = resolveConfigFilePath(configRoot, "taskplane-workspace.yaml");
+	if (!existsSync(yamlPath)) return undefined;
+
+	try {
+		const raw = readFileSync(yamlPath, "utf-8");
+		const loaded = yamlParse(raw) as any;
+		if (!loaded || typeof loaded !== "object") return undefined;
+
+		const converted = convertStructuralKeys(loaded);
+		return normalizeWorkspaceSection(converted, yamlPath);
+	} catch {
+		return undefined;
+	}
+}
+
 
 // ── User Preferences (Layer 2) ───────────────────────────────────────
 
@@ -586,9 +681,17 @@ export function applyUserPreferences(config: TaskplaneConfig, prefs: UserPrefere
  * in either location. This allows pointer-resolved roots (e.g.,
  * `<configRepo>/.taskplane/`) where files are scaffolded directly
  * without a `.pi/` subdirectory.
+ *
+ * Includes optional workspace YAML (`taskplane-workspace.yaml`) so
+ * workspace-only roots participate in config-root resolution.
  */
 export function hasConfigFiles(root: string): boolean {
-	const files = [PROJECT_CONFIG_FILENAME, "task-runner.yaml", "task-orchestrator.yaml"];
+	const files = [
+		PROJECT_CONFIG_FILENAME,
+		"task-runner.yaml",
+		"task-orchestrator.yaml",
+		"taskplane-workspace.yaml",
+	];
 	for (const f of files) {
 		if (existsSync(join(root, ".pi", f)) || existsSync(join(root, f))) return true;
 	}
@@ -637,6 +740,7 @@ export function resolveConfigRoot(cwd: string, pointerConfigRoot?: string): stri
  *   Layer 1 — Project config:
  *     1. `.pi/taskplane-config.json` — JSON-first (new format)
  *     2. `.pi/task-runner.yaml` + `.pi/task-orchestrator.yaml` — YAML fallback
+ *        (+ optional `.pi/taskplane-workspace.yaml` workspace section mapping)
  *     3. Defaults — if no config files exist
  *
  *   Layer 2 — User preferences (applied on top of Layer 1):
@@ -671,10 +775,12 @@ export function loadProjectConfig(cwd: string, pointerConfigRoot?: string): Task
 		// Fall back to YAML
 		const taskRunner = loadTaskRunnerYaml(configRoot);
 		const orchestrator = loadOrchestratorYaml(configRoot);
+		const workspace = loadWorkspaceYaml(configRoot);
 		config = {
 			configVersion: CONFIG_VERSION,
 			taskRunner,
 			orchestrator,
+			...(workspace ? { workspace } : {}),
 		};
 	}
 
@@ -710,10 +816,12 @@ export function loadLayer1Config(cwd: string, pointerConfigRoot?: string): Taskp
 	// Fall back to YAML
 	const taskRunner = loadTaskRunnerYaml(configRoot);
 	const orchestrator = loadOrchestratorYaml(configRoot);
+	const workspace = loadWorkspaceYaml(configRoot);
 	return {
 		configVersion: CONFIG_VERSION,
 		taskRunner,
 		orchestrator,
+		...(workspace ? { workspace } : {}),
 	};
 }
 

package/extensions/taskplane/config-schema.ts

@@ -415,6 +415,37 @@ export interface OrchestratorSection {
 }
 
 
+// ── Workspace Section Interfaces ─────────────────────────────────────
+
+/** Workspace repo definition (JSON config shape). */
+export interface WorkspaceRepoSectionConfig {
+	/** Repo root path (relative to workspace root or absolute). */
+	path: string;
+	/** Optional default branch override. */
+	defaultBranch?: string;
+}
+
+/** Workspace routing definition (JSON config shape). */
+export interface WorkspaceRoutingSectionConfig {
+	/** Shared task packet root directory. */
+	tasksRoot: string;
+	/** Default repo for unqualified operations. */
+	defaultRepo: string;
+	/** Packet-home repo owning PROMPT/STATUS/.DONE. */
+	taskPacketRepo: string;
+	/** Strict repo routing mode. */
+	strict?: boolean;
+}
+
+/** Optional workspace section in taskplane-config.json. */
+export interface WorkspaceSectionConfig {
+	/** Repo map keyed by repo ID. */
+	repos: Record<string, WorkspaceRepoSectionConfig>;
+	/** Routing contract for workspace mode. */
+	routing: WorkspaceRoutingSectionConfig;
+}
+
+
 // ── Unified Config ───────────────────────────────────────────────────
 
 /**
@@ -442,6 +473,8 @@ export interface TaskplaneConfig {
 	taskRunner: TaskRunnerSection;
 	/** Orchestrator settings */
 	orchestrator: OrchestratorSection;
+	/** Optional workspace config (JSON-first; legacy YAML fallback supported). */
+	workspace?: WorkspaceSectionConfig;
 }
 
 

package/extensions/taskplane/execution.ts

@@ -475,7 +475,7 @@ export function buildLaneEnvVars(
 
 	const vars: Record<string, string> = {
 		TASK_AUTOSTART: relativePath,
-		TASK_RUNNER_SPAWN_MODE: "subprocess",
+		TASK_RUNNER_SPAWN_MODE: "tmux",
 		TASK_RUNNER_TMUX_PREFIX: lane.tmuxSessionName,
 		ORCH_SIDECAR_DIR: join(workspaceRoot || repoRoot, ".pi"),
 		NODE_PATH: nodePath,
@@ -915,6 +915,10 @@ 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;
+	}
 	if (extraEnvVars) {
 		Object.assign(envVars, extraEnvVars);
 	}

package/extensions/taskplane/extension.ts

@@ -1457,6 +1457,8 @@ export default function (pi: ExtensionAPI) {
 	 * and return early with a user-facing error when null.
 	 */
 	let execCtx: ExecutionContext | null = null;
+	/** Last startup error message to surface consistently through command guards. */
+	let execCtxInitError: string | null = null;
 
 	// ── Widget Rendering ─────────────────────────────────────────────
 
@@ -1477,17 +1479,18 @@ export default function (pi: ExtensionAPI) {
 
 	// ── Command Guard ────────────────────────────────────────────────
 
+	function getExecCtxInitErrorMessage(): string {
+		return execCtxInitError ??
+			"❌ Orchestrator not initialized. Startup failed before execution context was created.\nRestart the session after fixing configuration/setup issues.";
+	}
+
 	/**
 	 * Guard: returns true if execution context is initialized, false otherwise.
 	 * Emits a user-facing error notification when the context is missing.
 	 */
 	function requireExecCtx(ctx: ExtensionContext): boolean {
 		if (execCtx) return true;
-		ctx.ui.notify(
-			"❌ Orchestrator not initialized. Workspace configuration failed at startup.\n" +
-			"Fix the workspace config or remove it to use repo mode, then restart.",
-			"error",
-		);
+		ctx.ui.notify(getExecCtxInitErrorMessage(), "error");
 		return false;
 	}
 
@@ -1720,7 +1723,7 @@ export default function (pi: ExtensionAPI) {
 
 		if (!execCtx) {
 			return {
-				message: "❌ Orchestrator not initialized. Workspace configuration failed at startup.\nFix the workspace config or remove it to use repo mode, then restart.",
+				message: getExecCtxInitErrorMessage(),
 				error: true,
 			};
 		}
@@ -2050,7 +2053,7 @@ export default function (pi: ExtensionAPI) {
 	function doOrchResume(force: boolean, ctx: ExtensionContext): { message: string; error?: boolean } {
 		if (!execCtx) {
 			return {
-				message: "❌ Orchestrator not initialized. Workspace configuration failed at startup.\nFix the workspace config or remove it to use repo mode, then restart.",
+				message: getExecCtxInitErrorMessage(),
 				error: true,
 			};
 		}
@@ -2786,7 +2789,7 @@ export default function (pi: ExtensionAPI) {
 	): Promise<{ message: string; error?: boolean; level?: "info" | "warning" | "error" }> {
 		if (!execCtx) {
 			return {
-				message: "❌ Orchestrator not initialized. Workspace configuration failed at startup.\nFix the workspace config or remove it to use repo mode, then restart.",
+				message: getExecCtxInitErrorMessage(),
 				error: true,
 			};
 		}
@@ -3653,24 +3656,35 @@ export default function (pi: ExtensionAPI) {
 		orchWidgetCtx = ctx;
 
 		// ── Build execution context (config + workspace mode detection) ──
-		// Reset execCtx before loading to prevent stale state on re-init
+		// Reset startup state before loading to prevent stale errors on re-init.
 		execCtx = null;
+		execCtxInitError = null;
 		try {
 			execCtx = buildExecutionContext(ctx.cwd, loadOrchestratorConfig, loadTaskRunnerConfig);
 		} catch (err: unknown) {
 			if (err instanceof WorkspaceConfigError) {
-				// Workspace config is present but invalid — fatal startup error.
-				// Leave execCtx null; command guard will block all commands except abort.
-				ctx.ui.notify(
-					`❌ Workspace configuration error [${err.code}]\n\n` +
-					`${err.message}\n\n` +
-					`Fix the workspace config at .pi/taskplane-workspace.yaml or remove it to use repo mode.\n` +
-					`Orchestrator commands are disabled until this is resolved.`,
-					"error",
-				);
+				// Startup is fatal when workspace config is invalid OR repo-mode setup
+				// requirements are not met (non-git cwd without workspace config).
+				const setupError = err.code === "WORKSPACE_SETUP_REQUIRED";
+				execCtxInitError = setupError
+					? (
+						`❌ Orchestrator startup blocked [${err.code}]\n\n` +
+						`${err.message}\n\n` +
+						`Orchestrator commands are disabled until this setup issue is resolved.`
+					)
+					: (
+						`❌ Workspace configuration error [${err.code}]\n\n` +
+						`${err.message}\n\n` +
+						`Fix the workspace config at .pi/taskplane-workspace.yaml (or taskplane-config.json workspace section), then restart.\n` +
+						`Orchestrator commands are disabled until this is resolved.`
+					);
+
+				ctx.ui.notify(execCtxInitError, "error");
 				ctx.ui.setStatus(
 					"task-orchestrator",
-					"🔀 Orchestrator · ❌ startup failed (workspace config error)",
+					setupError
+						? "🔀 Orchestrator · ❌ startup failed (setup required)"
+						: "🔀 Orchestrator · ❌ startup failed (workspace config error)",
 				);
 				return;
 			}

package/extensions/taskplane/types.ts

@@ -2832,10 +2832,11 @@ export const BATCH_HISTORY_MAX_ENTRIES = 100;
  *   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
+ * 1. 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.
+ * 2. Workspace config file present + valid → workspace mode.
+ * 3. No workspace config + cwd is a git repo → repo mode.
+ * 4. No workspace config + cwd is not a git repo → `WORKSPACE_SETUP_REQUIRED`.
  */
 export type WorkspaceMode = "repo" | "workspace";
 
@@ -2872,6 +2873,15 @@ export interface WorkspaceRoutingConfig {
 	 * Must reference a valid key in `WorkspaceConfig.repos`.
 	 */
 	defaultRepo: string;
+	/**
+	 * Repo ID that owns task packet files (PROMPT.md/STATUS.md/.DONE/.reviews).
+	 *
+	 * Required at runtime. Legacy workspace YAML without this field is
+	 * compatibility-mapped to `defaultRepo` during load with a warning.
+	 *
+	 * Invariant: `tasksRoot` must resolve inside `repos[taskPacketRepo].path`.
+	 */
+	taskPacketRepo: string;
 	/**
 	 * When true, every task MUST declare an explicit execution target
 	 * (via `## Execution Target` section or inline `**Repo:**` in PROMPT.md).
@@ -2964,6 +2974,10 @@ export interface ExecutionContext {
  * - 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_TASK_PACKET_REPO_NOT_FOUND: `routing.task_packet_repo` references a repo ID not in the repos map
+ * - WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO: `routing.tasks_root` resolves outside `repos[routing.task_packet_repo].path`
+ * - WORKSPACE_TASK_AREA_OUTSIDE_TASKS_ROOT: A configured task-area path resolves outside `routing.tasks_root`
+ * - WORKSPACE_SETUP_REQUIRED: No workspace config and cwd is not a git repository
  * - 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
  */
@@ -2978,10 +2992,12 @@ export type WorkspaceConfigErrorCode =
 	| "WORKSPACE_TASKS_ROOT_NOT_FOUND"
 	| "WORKSPACE_MISSING_DEFAULT_REPO"
 	| "WORKSPACE_DEFAULT_REPO_NOT_FOUND"
+	| "WORKSPACE_TASK_PACKET_REPO_NOT_FOUND"
+	| "WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO"
+	| "WORKSPACE_TASK_AREA_OUTSIDE_TASKS_ROOT"
+	| "WORKSPACE_SETUP_REQUIRED"
 	| "WORKSPACE_DUPLICATE_REPO_PATH"
-	| "WORKSPACE_SCHEMA_INVALID";
-
-/**
+	| "WORKSPACE_SCHEMA_INVALID";/**
  * Typed error class for workspace configuration failures.
  *
  * Thrown during workspace config loading/validation when the config file

package/extensions/taskplane/workspace.ts

@@ -2,8 +2,9 @@
  * Workspace configuration loading and validation.
  *
  * Detects workspace mode by checking for `.pi/taskplane-workspace.yaml`.
- * When the file is absent, the orchestrator runs in repo mode (default).
  * When the file is present, it must be valid — invalid files are fatal.
+ * When absent, `loadWorkspaceConfig()` returns null and `buildExecutionContext()`
+ * decides repo-mode eligibility (cwd must be a git repository).
  *
  * Validation order (deterministic, fail-fast):
  * 1. File existence check → absent = repo mode (return null)
@@ -20,6 +21,8 @@
  * 9. routing.tasks_root exists → WORKSPACE_TASKS_ROOT_NOT_FOUND
  * 10. routing.default_repo present → WORKSPACE_MISSING_DEFAULT_REPO
  * 11. routing.default_repo valid → WORKSPACE_DEFAULT_REPO_NOT_FOUND
+ * 12. routing.task_packet_repo valid (or compat fallback) → WORKSPACE_TASK_PACKET_REPO_NOT_FOUND
+ * 13. routing.tasks_root inside packet-home repo → WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO
  *
  * Path normalization rules:
  * - Relative paths are resolved against workspaceRoot.
@@ -95,6 +98,16 @@ function resolveAbsolutePath(p: string, base: string): string {
 	}
 }
 
+/**
+ * True when `childPath` is the same path as `parentPath` or contained within it.
+ * Uses canonicalized paths for cross-platform, case-insensitive comparison.
+ */
+function isPathWithinContainer(childPath: string, parentPath: string): boolean {
+	const child = canonicalizePath(childPath, "");
+	const parent = canonicalizePath(parentPath, "");
+	return child === parent || child.startsWith(`${parent}/`);
+}
+
 
 // ── Pointer Resolution ───────────────────────────────────────────────
 
@@ -498,7 +511,50 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
 		);
 	}
 
-	// ── 12. routing.strict (optional boolean, default false) ─────
+	// 12. routing.task_packet_repo (required by v1 contract)
+	// Compatibility policy: if omitted, default to routing.default_repo and
+	// emit a warning so legacy configs remain deterministic.
+	const hasTaskPacketRepo = Object.prototype.hasOwnProperty.call(rawRouting, "task_packet_repo");
+	const rawTaskPacketRepo = rawRouting.task_packet_repo;
+	let taskPacketRepoId = defaultRepoId;
+
+	if (hasTaskPacketRepo) {
+		if (typeof rawTaskPacketRepo !== "string" || rawTaskPacketRepo.trim() === "") {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_SCHEMA_INVALID",
+				"Workspace config 'routing.task_packet_repo' must be a non-empty string when provided.",
+				undefined,
+				configFile,
+			);
+		}
+		taskPacketRepoId = rawTaskPacketRepo.trim();
+	} else {
+		console.error(
+			`[taskplane] workspace compatibility: 'routing.task_packet_repo' is missing in ${configFile}; defaulting to routing.default_repo ('${defaultRepoId}'). Add 'routing.task_packet_repo' explicitly.`,
+		);
+	}
+
+	if (!repos.has(taskPacketRepoId)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_TASK_PACKET_REPO_NOT_FOUND",
+			`routing.task_packet_repo '${taskPacketRepoId}' does not match any repo ID. Available repos: ${Array.from(repos.keys()).join(", ")}`,
+			undefined,
+			configFile,
+		);
+	}
+
+	// 13. tasks_root must be inside repos[task_packet_repo].path
+	const packetRepoPath = repos.get(taskPacketRepoId)!.path;
+	if (!isPathWithinContainer(tasksRootAbsolute, packetRepoPath)) {
+		throw new WorkspaceConfigError(
+			"WORKSPACE_TASKS_ROOT_OUTSIDE_PACKET_REPO",
+			`routing.tasks_root '${tasksRootAbsolute}' must be inside packet-home repo '${taskPacketRepoId}' (${packetRepoPath}). Update routing.tasks_root or routing.task_packet_repo.`,
+			undefined,
+			tasksRootAbsolute,
+		);
+	}
+
+	// ── 14. routing.strict (optional boolean, default false) ─────
 	const rawStrict = rawRouting.strict;
 	if (rawStrict !== undefined) {
 		// null (from bare `strict:` or `strict: null` in YAML) is rejected
@@ -518,6 +574,7 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
 	const routing: WorkspaceRoutingConfig = {
 		tasksRoot: tasksRootAbsolute,
 		defaultRepo: defaultRepoId,
+		taskPacketRepo: taskPacketRepoId,
 		...(strict ? { strict: true } : {}),
 	};
 
@@ -531,6 +588,39 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
 }
 
 
+// ── Cross-Config Validation ─────────────────────────────────────────
+
+/**
+ * Enforce that every configured task area resolves inside workspace routing.tasksRoot.
+ *
+ * This is a cross-config invariant and therefore runs after both workspace and
+ * task-runner configs are loaded.
+ */
+export function validateTaskAreasWithinTasksRoot(
+	workspaceRoot: string,
+	workspaceConfig: WorkspaceConfig,
+	taskRunnerConfig: import("./types.ts").TaskRunnerConfig,
+): void {
+	const tasksRoot = workspaceConfig.routing.tasksRoot;
+	const areaEntries = Object.entries(taskRunnerConfig.task_areas ?? {}).sort((a, b) =>
+		a[0].localeCompare(b[0])
+	);
+
+	for (const [areaName, area] of areaEntries) {
+		const areaPathRaw = (area?.path ?? "").trim();
+		const areaAbsolute = resolveAbsolutePath(areaPathRaw, workspaceRoot);
+		if (!isPathWithinContainer(areaAbsolute, tasksRoot)) {
+			throw new WorkspaceConfigError(
+				"WORKSPACE_TASK_AREA_OUTSIDE_TASKS_ROOT",
+				`Task area '${areaName}' path '${areaAbsolute}' must be inside routing.tasks_root '${tasksRoot}'. Move the area under tasks_root or update task_areas.${areaName}.path.`,
+				undefined,
+				areaAbsolute,
+			);
+		}
+	}
+}
+
+
 // ── Execution Context Builder ────────────────────────────────────────
 
 /**
@@ -543,8 +633,14 @@ export function loadWorkspaceConfig(workspaceRoot: string): WorkspaceConfig | nu
  * @param loadOrchConfig - Orchestrator config loader (for testability)
  * @param loadTaskConfig - Task runner config loader (for testability)
  * @returns ExecutionContext ready for orchestrator consumption
- * @throws WorkspaceConfigError if workspace config is present but invalid
+ * @throws WorkspaceConfigError if workspace config is present but invalid,
+ *   or when no workspace config exists and `cwd` is not a git repository.
  */
+function isInsideGitRepo(cwd: string): boolean {
+	const probe = runGit(["rev-parse", "--is-inside-work-tree"], cwd);
+	return probe.ok && probe.stdout.trim() === "true";
+}
+
 export function buildExecutionContext(
 	cwd: string,
 	loadOrchConfig: (root: string, pointerConfigRoot?: string) => import("./types.ts").OrchestratorConfig,
@@ -553,6 +649,19 @@ export function buildExecutionContext(
 	const workspaceConfig = loadWorkspaceConfig(cwd);
 
 	if (workspaceConfig === null) {
+		// Deterministic mode guard: without workspace config, repo mode is only
+		// valid when cwd is a git repository.
+		if (!isInsideGitRepo(cwd)) {
+			const wsConfigFile = workspaceConfigPath(cwd);
+			throw new WorkspaceConfigError(
+				"WORKSPACE_SETUP_REQUIRED",
+				`No workspace config found at ${wsConfigFile}, and current directory is not a git repository: ${cwd}. ` +
+				`Run Taskplane from a git repository, or create ${wsConfigFile} (taskplane init) to use workspace mode.`,
+				undefined,
+				cwd,
+			);
+		}
+
 		// Repo mode: pointer is ignored entirely. Config loads from cwd.
 		const orchestratorConfig = loadOrchConfig(cwd);
 		const taskRunnerConfig = loadTaskConfig(cwd);
@@ -580,6 +689,9 @@ export function buildExecutionContext(
 	const orchestratorConfig = loadOrchConfig(cwd, pointerConfigRoot);
 	const taskRunnerConfig = loadTaskConfig(cwd, pointerConfigRoot);
 
+	// Cross-config invariant: every task-area path must live under routing.tasks_root.
+	validateTaskAreasWithinTasksRoot(cwd, workspaceConfig, taskRunnerConfig);
+
 	const defaultRepo = workspaceConfig.repos.get(workspaceConfig.routing.defaultRepo)!;
 	return {
 		workspaceRoot: cwd,

package/package.json

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

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

@@ -354,6 +354,30 @@ files and make sure their file scopes reflect that.
 
 ---
 
+## Preventing Empty Completions
+
+Workers can shortcut tasks by observing that existing code "already satisfies"
+requirements and checking off items without implementing anything. This is the
+most dangerous failure mode — it produces false completions that waste the entire
+pipeline.
+
+**Defense: Make deliverables concrete and verifiable.**
+
+| ❌ Vague (shortcuttable) | ✅ Concrete (verifiable) |
+|--------------------------|------------------------|
+| "Add taskPacketRepo support" | "Add `taskPacketRepo` field to `WorkspaceRoutingConfig` in types.ts" |
+| "Enforce mode selection" | "Add `validateWorkspaceMode()` function in workspace.ts that throws on invalid state" |
+| "Update config loading" | "Modify `loadWorkspaceConfig()` to parse and validate `taskPacketRepo` from JSON config" |
+| "Add tests" | "Create `tests/packet-home-contract.test.ts` with tests for: valid config, missing field error, invariant violation" |
+
+**Rules for task creators:**
+- Every implementation step MUST name specific files to create or modify
+- "Add X" means "write new code that doesn't exist yet" — if it might already exist, say "verify X exists and add tests, or implement if missing"
+- Include at least one NEW test file per task — workers can't shortcut test creation
+- Each step's artifacts list must include at least one source file (not just STATUS.md)
+
+---
+
 ## Key Principles
 
 - **Documentation in every task.** Without "Must Update" and "Check If Affected"

package/templates/agents/task-worker.md

@@ -173,6 +173,15 @@ When a reviewer returns REVISE with specific feedback items:
 - Do NOT expand task scope beyond what the steps require
 - If you discover something out of scope, note it in STATUS.md Discoveries table
 
+## Completion Integrity
+
+**Every checked checkbox MUST correspond to a real code change, test, or document edit.** You must NOT check off items by simply observing that existing code appears to satisfy them. Specifically:
+
+- **If you believe work is already done:** You must still verify by running tests against the specific requirements AND document what you verified. Check off the item only after confirming with evidence (test output, code inspection notes in STATUS.md).
+- **"No source files changed" is a red flag.** If you complete a task without modifying any source files (only STATUS.md), something is wrong. Every implementation task requires code changes. If you genuinely believe no changes are needed, log a detailed explanation in STATUS.md Discoveries and escalate — do NOT mark the task as complete.
+- **A step that requires "Add X to Y" means you write the code.** Reading existing code and deciding it already satisfies the requirement is not implementation. If the existing code truly covers it, write a test that proves it, and document the finding.
+- **Checking boxes without doing work is the most serious failure mode.** It wastes the entire batch pipeline (review, merge, integration) and produces a false completion that blocks dependent tasks.
+
 ## Review Protocol
 
 If you have access to a `review_step` tool, use it at step boundaries to spawn