taskplane 0.22.12 → 0.22.14

package/extensions/taskplane/merge.ts

@@ -2,7 +2,7 @@
  * Merge orchestration, merge agents, merge worktree
  * @module orch/merge
  */
-import { readFileSync, writeFileSync, existsSync, unlinkSync, copyFileSync, mkdirSync, rmSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, unlinkSync, copyFileSync, mkdirSync, rmSync, readdirSync } from "fs";
 import { readFile as fsReadFile } from "fs/promises";
 import { execSync, spawnSync } from "child_process";
 import { join, dirname, resolve, relative } from "path";
@@ -1841,16 +1841,48 @@ export async function mergeWave(
 	// ── Stage workspace task artifacts into merge worktree ──────────
 	// TP-035: Tightened artifact staging — only allowlisted task-owned files
 	// are staged. The allowlist is derived per-task-folder from completed lanes:
-	// exactly `.DONE`, `STATUS.md`, and `REVIEW_VERDICT.json` (when present).
+	// `.DONE`, `STATUS.md`, `REVIEW_VERDICT.json`, and `.reviews/**` files.
 	// Files outside known task folders, worktree internals, and repo-escape
 	// paths are rejected. Uses resolve+relative path containment consistent
 	// with ensureTaskFilesCommitted() in execution.ts.
 	if (mergeWorkDir) {
 		// Build the set of allowed artifact paths (repo-root-relative) from
 		// the completed lanes' task folders.
+		//
+		// Allowlist policy:
+		// - task marker files: .DONE, STATUS.md, REVIEW_VERDICT.json
+		// - review outputs under task-local .reviews/**
 		const ALLOWED_ARTIFACT_NAMES = [".DONE", "STATUS.md", "REVIEW_VERDICT.json"];
+		const ALLOWED_ARTIFACT_DIRS = [".reviews"];
 		const resolvedRepoRoot = resolve(repoRoot);
 		const allowedRelPaths = new Set<string>();
+		const relPathToWorktree = new Map<string, string>();
+
+		const listFilesRecursively = (rootDir: string): string[] => {
+			if (!existsSync(rootDir)) return [];
+			const files: string[] = [];
+			const walk = (dir: string): void => {
+				let entries;
+				try {
+					entries = readdirSync(dir, { withFileTypes: true });
+				} catch {
+					return;
+				}
+				for (const entry of entries) {
+					const absPath = join(dir, entry.name);
+					if (entry.isDirectory()) {
+						walk(absPath);
+						continue;
+					}
+					if (!entry.isFile()) continue;
+					const relPath = relative(rootDir, absPath).replace(/\\/g, "/");
+					if (!relPath || relPath.startsWith("..") || relPath.startsWith("/")) continue;
+					files.push(relPath);
+				}
+			};
+			walk(rootDir);
+			return files;
+		};
 
 		for (const lane of orderedLanes) {
 			for (const allocTask of lane.tasks) {
@@ -1867,7 +1899,24 @@ export async function mergeWave(
 				}
 
 				for (const name of ALLOWED_ARTIFACT_NAMES) {
-					allowedRelPaths.add(`${relFolder}/${name}`);
+					const rp = `${relFolder}/${name}`;
+					allowedRelPaths.add(rp);
+					relPathToWorktree.set(rp, join(lane.worktreePath, rp));
+				}
+
+				for (const dirName of ALLOWED_ARTIFACT_DIRS) {
+					const laneDir = join(lane.worktreePath, relFolder, dirName);
+					for (const relFile of listFilesRecursively(laneDir)) {
+						const rp = `${relFolder}/${dirName}/${relFile}`;
+						allowedRelPaths.add(rp);
+						relPathToWorktree.set(rp, join(lane.worktreePath, rp));
+					}
+
+					const repoDir = join(repoRoot, relFolder, dirName);
+					for (const relFile of listFilesRecursively(repoDir)) {
+						const rp = `${relFolder}/${dirName}/${relFile}`;
+						allowedRelPaths.add(rp);
+					}
 				}
 			}
 		}
@@ -1875,12 +1924,44 @@ export async function mergeWave(
 		if (allowedRelPaths.size > 0) {
 			let staged = 0;
 			let skipped = 0;
+			let preserved = 0;
 
 			for (const relPath of allowedRelPaths) {
-				const srcPath = join(repoRoot, relPath);
-				if (!existsSync(srcPath)) continue; // File not present (e.g., no REVIEW_VERDICT.json) — skip silently
-
 				const destPath = join(mergeWorkDir, relPath);
+
+				// TP-099: If the file already exists in mergeWorkDir (from lane merge),
+				// do NOT overwrite it — the lane merge brought the correct worker-updated
+				// version (e.g., STATUS.md with checked items, execution log, discoveries).
+				// Overwriting from repoRoot would revert to the pre-execution template.
+				if (existsSync(destPath)) {
+					preserved++;
+					continue;
+				}
+
+				// File missing from mergeWorkDir — backfill from best available source.
+				// Primary: lane worktree (has worker-generated .DONE/STATUS/.reviews content).
+				// Fallback: repoRoot (original task folder, with path containment check).
+				const worktreeSrc = relPathToWorktree.get(relPath);
+				let srcPath: string | null = null;
+
+				// Try lane worktree first (trusted engine-allocated path)
+				if (worktreeSrc && existsSync(worktreeSrc)) {
+					srcPath = worktreeSrc;
+				} else {
+					// Fallback to repoRoot with path containment check (TP-035 hardening)
+					const repoRootSrc = join(repoRoot, relPath);
+					if (existsSync(repoRootSrc)) {
+						const resolvedSrc = resolve(repoRootSrc);
+						const srcRelToRepo = relative(resolvedRepoRoot, resolvedSrc).replace(/\\/g, "/");
+						if (srcRelToRepo.startsWith("..") || srcRelToRepo.startsWith("/")) {
+							execLog("merge", `W${waveIndex}`, `skipping artifact source outside repo root`, { path: relPath, src: repoRootSrc });
+							continue;
+						}
+						srcPath = repoRootSrc;
+					}
+				}
+				if (!srcPath) continue; // File not present anywhere — skip silently
+
 				try {
 					mkdirSync(dirname(destPath), { recursive: true });
 					copyFileSync(srcPath, destPath);
@@ -1894,13 +1975,14 @@ export async function mergeWave(
 			}
 
 			if (staged > 0) {
-				spawnSync("git", ["commit", "-m", `checkpoint: wave ${waveIndex} task artifacts (.DONE, STATUS.md, REVIEW_VERDICT.json)`], { cwd: mergeWorkDir });
+				spawnSync("git", ["commit", "-m", `checkpoint: wave ${waveIndex} task artifacts (.DONE, STATUS.md, REVIEW_VERDICT.json, .reviews/*)`], { cwd: mergeWorkDir });
 				execLog("merge", `W${waveIndex}`, `committed ${staged} task artifact(s) to merge worktree`, {
 					skipped,
+					preserved,
 					allowedCandidates: allowedRelPaths.size,
 				});
 			} else {
-				execLog("merge", `W${waveIndex}`, `no task artifacts to stage (0 of ${allowedRelPaths.size} candidates present/changed)`);
+				execLog("merge", `W${waveIndex}`, `no task artifacts to stage (0 of ${allowedRelPaths.size} candidates present/changed, ${preserved} preserved from lane merge)`);
 			}
 
 			// Keep both .DONE and STATUS.md in develop's working tree:

package/extensions/taskplane/supervisor-primer.md

@@ -770,6 +770,12 @@ You have these orchestrator tools available:
 **Note:** `orch_retry_task`, `orch_skip_task`, and `orch_force_merge` require the batch to be paused/stopped first.
 If the batch is actively running, call `orch_pause()` first.
 
+**Diagnostic & Recovery Tools (TP-096):**
+- `read_agent_status(lane?)` — Read STATUS.md + telemetry for a lane (step, progress, context %, cost, elapsed). Omit lane for all lanes.
+- `trigger_wrap_up(lane)` — Write `.task-wrap-up` signal to gracefully stop a worker on a lane.
+- `read_lane_logs(lane)` — Read stderr/crash logs and exit diagnostics for a lane.
+- `list_active_agents()` — List all tmux sessions with role, lane, task, context %, elapsed, cost.
+
 Plus general tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
 for inspecting files, running git commands, and editing batch state.
 

package/package.json

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

package/templates/agents/task-worker.md

@@ -53,12 +53,11 @@ edit STATUS.md
 
 Then **check for wrap-up signal:**
 ```bash
-if test -f "<TASK_FOLDER>/.task-wrap-up" || test -f "<TASK_FOLDER>/.wiggum-wrap-up"; then
+if test -f "<TASK_FOLDER>/.task-wrap-up"; then
   echo "WRAP_UP_SIGNAL"
 fi
 ```
-Primary signal file is `.task-wrap-up`; `.wiggum-wrap-up` is legacy and still supported.
-If either signal exists, STOP immediately after this checkpoint.
+If the signal exists, STOP immediately after this checkpoint.
 
 If you do work but don't edit STATUS.md, that work is INVISIBLE to the
 orchestrator and you will be re-spawned to do it again.
@@ -262,6 +261,19 @@ Do NOT:
 - Modify docs listed in `task-runner.yaml → protected_docs` without explicit approval
 - Expand task scope — add tech debt instead
 
+## Steering Messages
+
+During orchestrated runs, the supervisor may send steering messages to adjust
+your approach. These messages appear in your conversation as user messages at
+turn boundaries. They are also logged in the STATUS.md execution log as
+`⚠️ Steering` entries for audit visibility.
+
+When you receive a steering message:
+1. **Read it carefully** — it contains course corrections from the supervisor
+2. **Adjust your approach** as directed
+3. **Continue working** — do not stop or restart; incorporate the guidance naturally
+4. Steering messages are authoritative — treat them like direct instructions
+
 ## Error Handling
 
 - If stuck on the same issue after 3 attempts, document the blocker in STATUS.md