taskplane 0.28.5 → 0.28.7

package/dashboard/public/app.js

@@ -616,7 +616,13 @@ function renderSummary(batch) {
       const isCurrent = i === waveIdx && (batch.phase === "executing" || batch.phase === "merging");
       const isMergingChip = i === waveIdx && batch.phase === "merging";
       const cls = isDone ? "done" : isMergingChip ? "current merging" : isCurrent ? "current" : "";
-      wavesHtml += `<span class="wave-chip ${cls}">W${i + 1} [${taskIds.join(", ")}]</span>`;
+      // #484: Show lane parallelization within each wave. Group taskIds by
+      // their assigned lane: tasks on the same lane render with `→` (serial),
+      // tasks on different lanes render with ` | ` (parallel). Tooltip shows
+      // the expanded lane breakdown.
+      const { compact, tooltip } = formatWaveLaneBreakdown(taskIds, batch.lanes || [], i + 1);
+      const titleAttr = tooltip ? ` title="${escapeHtml(tooltip)}"` : "";
+      wavesHtml += `<span class="wave-chip ${cls}"${titleAttr}>W${i + 1} [${compact}]</span>`;
     });
     $summaryWaves.innerHTML = wavesHtml;
   } else {
@@ -624,6 +630,84 @@ function renderSummary(batch) {
   }
 }
 
+/**
+ * Compute lane parallelization for a wave's tasks (#484).
+ *
+ * Returns:
+ *   - `compact`: a string like "TP-165 → TP-166 | TP-168 | TP-167" suitable
+ *     for the wave-chip body. Tasks on the same lane are joined by ` → `
+ *     (in lane execution order, not just appearance order); separate lanes
+ *     are joined by ` | `.
+ *   - `tooltip`: a multi-line string like
+ *     "W1\n  L1: TP-165 → TP-166\n  L2: TP-168\n  L3: TP-167" suitable for
+ *     the chip's `title` attribute. Empty string when no lane data is
+ *     available (future waves not yet provisioned).
+ *
+ * When lane data is missing for one or more tasks (e.g., the wave has not
+ * yet been provisioned, or task hasn't been assigned), unassigned tasks
+ * are shown with the previous flat formatting and no tooltip is generated
+ * — this preserves backward compatibility with future-wave display.
+ */
+function formatWaveLaneBreakdown(taskIds, lanes, waveNumber) {
+  if (!Array.isArray(taskIds) || taskIds.length === 0) {
+    return { compact: "", tooltip: "" };
+  }
+  // Build taskId → laneNumber map for the lanes that have any of these tasks.
+  const taskToLane = new Map();
+  for (const lane of lanes) {
+    if (!lane || !Array.isArray(lane.taskIds)) continue;
+    for (const tid of lane.taskIds) {
+      // First lane to claim a task wins (lanes shouldn't overlap, but be defensive).
+      if (!taskToLane.has(tid)) taskToLane.set(tid, lane.laneNumber);
+    }
+  }
+  // If no task in this wave has lane data, fall back to flat display.
+  const hasAnyLaneData = taskIds.some((t) => taskToLane.has(t));
+  if (!hasAnyLaneData) {
+    return { compact: taskIds.join(", "), tooltip: "" };
+  }
+  // Group taskIds by lane. Preserve appearance order across lanes.
+  // Within a lane, preserve the lane's own taskIds order so `→` reflects
+  // execution order, not the order taskIds happens to appear here.
+  const laneOrder = []; // lane numbers in order they first appear in taskIds
+  const laneToTasks = new Map(); // laneNumber → ordered taskIds for this wave
+  const unassigned = []; // taskIds not in any lane (shouldn't happen but be defensive)
+  for (const tid of taskIds) {
+    const ln = taskToLane.get(tid);
+    if (ln === undefined) {
+      unassigned.push(tid);
+      continue;
+    }
+    if (!laneToTasks.has(ln)) {
+      laneToTasks.set(ln, []);
+      laneOrder.push(ln);
+    }
+    laneToTasks.get(ln).push(tid);
+  }
+  // Sort each lane's tasks by their position in the lane.taskIds array
+  // so `→` always reflects execution order on that lane.
+  for (const ln of laneOrder) {
+    const lane = lanes.find((l) => l && l.laneNumber === ln);
+    if (lane && Array.isArray(lane.taskIds)) {
+      const orderIndex = new Map(lane.taskIds.map((t, idx) => [t, idx]));
+      laneToTasks.get(ln).sort((a, b) => (orderIndex.get(a) ?? 0) - (orderIndex.get(b) ?? 0));
+    }
+  }
+  // Build compact representation.
+  const laneSegments = laneOrder.map((ln) => laneToTasks.get(ln).join(" → "));
+  if (unassigned.length > 0) laneSegments.push(unassigned.join(", "));
+  const compact = laneSegments.join(" | ");
+  // Build tooltip representation.
+  const tooltipLines = [`W${waveNumber}`];
+  for (const ln of laneOrder) {
+    tooltipLines.push(`  L${ln}: ${laneToTasks.get(ln).join(" → ")}`);
+  }
+  if (unassigned.length > 0) {
+    tooltipLines.push(`  (unassigned): ${unassigned.join(", ")}`);
+  }
+  return { compact, tooltip: tooltipLines.join("\n") };
+}
+
 // ─── Render: Lanes + Tasks (integrated) ─────────────────────────────────────
 
 function renderLanesTasks(batch, sessions) {
@@ -858,11 +942,16 @@ function renderLanesTasks(batch, sessions) {
         ? `<button class="viewer-eye-btn${isViewingStatus ? ' active' : ''}" onclick="viewStatusMd('${escapeHtml(task.taskId)}')" title="View STATUS.md">👁</button>`
         : '';
 
+      // #485: Show task title (from PROMPT.md `# Task: <ID> - <title>`) under
+      // the task-id when available. Falls back to just the ID when missing.
+      const titleHtml = task.taskTitle
+        ? `<div class="task-title-subtitle">${escapeHtml(task.taskTitle)}</div>`
+        : "";
       html += `
         <div class="task-row">
           <span class="task-icon"><span class="status-dot ${task.status}"></span></span>
           <span class="task-actions">${eyeHtml}</span>
-          <span class="task-id status-${task.status}">${escapeHtml(task.taskId)}${showRepos ? repoBadgeHtml(tRepo, "repo-badge-task") : ""}</span>
+          <span class="task-id status-${task.status}"><div class="task-id-line">${escapeHtml(task.taskId)}${showRepos ? repoBadgeHtml(tRepo, "repo-badge-task") : ""}</div>${titleHtml}</span>
           <span><span class="status-badge status-${task.status}"><span class="status-dot ${task.status}"></span> ${task.status}</span></span>
           <span class="task-duration">${dur}</span>
           <span>${progressHtml}</span>

package/dashboard/public/style.css

@@ -625,6 +625,28 @@ body {
   font-family: var(--font-mono);
   font-weight: 600;
   font-size: 0.85rem;
+  /* #485: task-id may now contain a stacked task-id-line + task-title-subtitle */
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0; /* allow inner ellipsis to work */
+}
+
+.task-id-line {
+  /* The original TP-XXX line; preserves the previous single-line look */
+  white-space: nowrap;
+}
+
+.task-title-subtitle {
+  /* #485: human-readable task title under the ID */
+  font-family: var(--font-sans, inherit);
+  font-weight: 400;
+  font-size: 0.72rem;
+  color: var(--text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 100%;
 }
 
 .task-duration {

package/dashboard/server.cjs

@@ -160,6 +160,52 @@ function resolveTaskFolder(task, state) {
   return task.taskFolder;
 }
 
+/**
+ * Read the task title from a task folder's PROMPT.md.
+ *
+ * Extracts the human-readable title from the first `# Task:` heading. The
+ * heading format is `# Task: <ID> - <title>` per the create-taskplane-task
+ * skill's prompt template. Returns null when PROMPT.md is missing, the
+ * pattern doesn't match, or any read error occurs.
+ *
+ * Cached per-folder for the lifetime of this server process: PROMPT.md is
+ * immutable above the `---` divider so the title never changes mid-batch.
+ * Cache is keyed by absolute task folder path. (#485)
+ */
+const _taskTitleCache = new Map();
+function parseTaskTitle(taskFolder) {
+  if (!taskFolder) return null;
+  const cacheKey = path.resolve(taskFolder);
+  if (_taskTitleCache.has(cacheKey)) return _taskTitleCache.get(cacheKey);
+
+  // Look at both the canonical folder and the archive fallback (matches
+  // parseStatusMd's two-candidate strategy).
+  const candidates = [taskFolder];
+  const taskId = path.basename(taskFolder);
+  const archiveBase = taskFolder.replace(/[/\\]tasks[/\\][^/\\]+$/, "/tasks/archive/" + taskId);
+  if (archiveBase !== taskFolder) candidates.push(archiveBase);
+
+  for (const folder of candidates) {
+    const promptPath = path.join(folder, "PROMPT.md");
+    try {
+      const content = fs.readFileSync(promptPath, "utf-8");
+      // Match `# Task: <ID> - <title>` (the canonical first-line heading).
+      const match = content.match(/^# Task:\s*\S+\s*[-\u2014\u2013]\s*(.+?)\s*$/m);
+      if (match) {
+        const title = match[1].trim();
+        _taskTitleCache.set(cacheKey, title);
+        return title;
+      }
+    } catch {
+      // PROMPT.md missing or unreadable in this candidate — try the next.
+      continue;
+    }
+  }
+  // Cache the negative result too, so we don't re-attempt on every poll.
+  _taskTitleCache.set(cacheKey, null);
+  return null;
+}
+
 function parseStatusMd(taskFolder) {
   const candidates = [taskFolder];
   const taskId = path.basename(taskFolder);
@@ -1102,13 +1148,17 @@ function buildDashboardState() {
   const tasks = (state.tasks || []).map((task) => {
     const effectiveFolder = resolveTaskFolder(task, state);
     let statusData = null;
+    let taskTitle = null;
     if (effectiveFolder) {
       statusData = parseStatusMd(effectiveFolder);
+      // #485: read the human-readable title from PROMPT.md once, surface
+      // alongside taskId so the dashboard can show it as a subtitle.
+      taskTitle = parseTaskTitle(effectiveFolder);
     }
     if (!task.doneFileFound && effectiveFolder) {
       task.doneFileFound = checkDoneFile(effectiveFolder);
     }
-    return { ...task, statusData };
+    return { ...task, statusData, taskTitle };
   });
 
   // TP-107: Load Runtime V2 data when available

package/extensions/taskplane/agent-bridge-extension.ts

@@ -132,6 +132,59 @@ function writeSegmentExpansionRequest(request: SegmentExpansionRequest): string
 	return finalPath;
 }
 
+/**
+ * TP-186 — Death-spiral guard helper for `review_step`.
+ *
+ * Inspects STATUS.md to determine whether the worker has prematurely set the
+ * given step's section heading to `**Status:** ✅ Complete`. The guard fires
+ * for `code` and `test` review types only — plan reviews fire BEFORE
+ * implementation, when an empty STATUS is correct.
+ *
+ * Returns `true` ONLY if the step's section explicitly carries the
+ * `**Status:** ✅ Complete` line. The top-of-file (task-level) `**Status:**`
+ * field does not trip this guard because it is not inside any `### Step N:`
+ * section. All-checkboxes-checked is also NOT a trigger — it is the normal
+ * pre-code-review state.
+ *
+ * Designed to fail-open: any I/O error or a missing step heading returns
+ * `false` (the review proceeds). The prompt-side Recovery Recipe is the
+ * primary defense; this guard is a hard backstop, not a gatekeeper.
+ *
+ * @param statusPath absolute path to the worker's STATUS.md
+ * @param stepNum the step number being reviewed
+ * @returns true iff the step is marked Complete in STATUS.md
+ */
+export function isStepMarkedComplete(statusPath: string, stepNum: number): boolean {
+	let content: string;
+	try {
+		content = readFileSync(statusPath, "utf-8");
+	} catch {
+		return false;
+	}
+
+	const lines = content.split(/\r?\n/);
+	const stepHeadingRe = new RegExp(`^###\\s+Step\\s+${stepNum}\\b`);
+	const nextStepHeadingRe = /^###\s+Step\s+\d+\b/;
+
+	let inSection = false;
+	for (const line of lines) {
+		if (!inSection) {
+			if (stepHeadingRe.test(line)) inSection = true;
+			continue;
+		}
+		// Stop scanning at the next step heading.
+		if (nextStepHeadingRe.test(line)) break;
+		// Match a literal status line within this step's section.
+		// Examples that should match:
+		//   **Status:** ✅ Complete
+		//   **Status:** ✅ Complete (note ...)
+		if (/^\s*\*\*Status:\*\*\s*✅\s*Complete\b/.test(line)) {
+			return true;
+		}
+	}
+	return false;
+}
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "notify_supervisor",
@@ -632,6 +685,26 @@ export default function (pi: ExtensionAPI) {
 			const reviewsDir = process.env.TASKPLANE_REVIEWS_DIR || join(taskFolder, ".reviews");
 			if (!existsSync(reviewsDir)) mkdirSync(reviewsDir, { recursive: true });
 
+			// ── TP-186 death-spiral guard ─────────────────────────────────
+			// Refuse to spawn a code/test reviewer on a step that is already
+			// marked `**Status:** ✅ Complete` in STATUS.md. The worker has
+			// violated the Order of Operations contract; the only safe path
+			// is to revert STATUS first, then re-call review_step. Plan
+			// reviews are exempt because they fire BEFORE implementation.
+			if (reviewType !== "plan" && isStepMarkedComplete(statusPath, stepNum)) {
+				const taskIdMatch = statusPath.match(/[\\/]([A-Z]{2,}-\d+)[^\\/]*[\\/]STATUS\.md$/);
+				const taskId = taskIdMatch ? taskIdMatch[1] : "<TASK-ID>";
+				const refusal = [
+					`REFUSED: Step ${stepNum} is already marked \`**Status:** ✅ Complete\` in STATUS.md.`,
+					`Per the Order of Operations rule, code review must run BEFORE you mark a step Complete.`,
+					`Follow the Recovery Recipe in the worker prompt:`,
+					`  1. Revert the step's Status to \`🟨 In Progress\` in STATUS.md`,
+					`  2. Commit: chore(${taskId}): revert premature step-${stepNum} completion`,
+					`  3. Re-call review_step(step=${stepNum}, type="${reviewType}", baseline=<sha>)`,
+				].join("\n");
+				return { content: [{ type: "text" as const, text: refusal }], details: undefined };
+			}
+
 			// Read review counter from STATUS.md
 			let reviewCounter = 0;
 			try {

package/package.json

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

package/templates/agents/task-worker.md

@@ -278,9 +278,79 @@ code is already written.
 6. Commit implementation
 7. Call `review_step(step=N, type="code")` — AFTER implementation
 
-**WRONG sequence (violates the protocol):**
-1. ~~Hydrate, implement, check off, commit, THEN call plan review~~ ❌
-   This makes plan review pointless — the work is already done.
+### ⚠️ MANDATORY: Order of Operations for steps with code review
+
+**For any step that requires a code review (Review Level ≥ 2), the following
+order is MANDATORY. Workers MUST NOT mark a step `Status: ✅ Complete` in
+STATUS.md before the code review for that step has returned APPROVE.**
+
+1. **Implement** the step's checkbox items (write code, edit docs, etc.) —
+   check each box `[x]` in STATUS.md as you finish that item, but leave the
+   step's `**Status:**` heading set to `🟨 In Progress`.
+2. **Commit** the implementation:
+   `git add -A && git commit -m "feat(TASK-ID): step N implementation"`
+3. **Call** `review_step(step=N, type="code", baseline=<sha>)`.
+4. If the verdict is **REVISE**: read the review file in `.reviews/`, apply
+   the fixes, commit them, and call `review_step` again. Repeat until APPROVE
+   (max 2 code review cycles per step).
+5. If the verdict is **APPROVE**: NOW update the step's `**Status:**` heading
+   to `✅ Complete` in STATUS.md and commit the status update.
+6. **Move to step N+1.**
+
+The key invariant: **`Status: ✅ Complete` is the worker's commitment that the
+reviewer has signed off on the step.** It is not an in-progress marker. Setting
+it before APPROVE creates a contradiction the worker cannot recover from on
+its own — STATUS says done while the reviewer says revise.
+
+Individual checkboxes (`- [x] item text`) inside the step MAY be checked while
+implementation is in flight — they record per-item progress. The **step-level
+`Status:` heading** (the line that reads `**Status:** ✅ Complete` in STATUS.md)
+is the only field governed by this rule.
+
+### Recovery: "I marked the step Complete, then the reviewer returned REVISE"
+
+If you violated the Order of Operations and set `**Status:** ✅ Complete` for
+a step before the code review returned APPROVE, **you can recover without
+operator intervention**. Follow this recipe exactly:
+
+1. **Revert STATUS.md** for the affected step:
+   - Change the step's `**Status:** ✅ Complete` heading back to
+     `**Status:** 🟨 In Progress`.
+   - Leave the individual `- [x]` checkboxes alone — they record real work
+     that was done.
+   - If the top-of-file `**Current Step:**` field was advanced past this
+     step, set it back to this step's name.
+2. **Commit** the revert with a dedicated message:
+   `git commit -am "chore(TASK-ID): revert premature step-N completion"`
+3. **Handle the REVISE through the normal recipe:** read the review file in
+   `.reviews/`, add Issues-Found items as new checkboxes inside the step
+   (using the standard "After a REVISE Review" flow above), commit those
+   hydration changes, fix the issues, commit the fixes, then call
+   `review_step(step=N, type="code")` again.
+4. Once the reviewer returns APPROVE, follow Order of Operations step 5 and
+   set `**Status:** ✅ Complete` for real.
+
+Do NOT skip step 1. Leaving STATUS in the contradictory state (`Complete` +
+an open REVISE) is the failure mode this recipe exists to undo. The engine's
+`review_step` tool now refuses to run on a step already marked Complete and
+will return a `REFUSED` verdict pointing back at this recipe.
+
+### ❌ FORBIDDEN sequences (these break the review contract)
+
+Workers MUST NOT do any of the following:
+
+1. ~~Mark a step `**Status:** ✅ Complete` before its code review (Level ≥ 2)
+   has returned APPROVE.~~ This is the **death-spiral anti-pattern**: if
+   the reviewer subsequently returns REVISE, the worker enters a state
+   contradiction it cannot resolve and the lane is lost. If you did this
+   accidentally, follow the Recovery Recipe above.
+2. ~~Hydrate, implement, check off, commit, THEN call plan review~~ — this
+   makes plan review pointless; the work is already written.
+3. ~~Skip the code review and proceed to the next step on a Review Level ≥ 2
+   task~~ — the merge agent will reject the lane.
+
+These rules sit alongside the existing "NEVER add, remove, or renumber steps"
+rule from STATUS.md Hydration → Rules.
 
 **Handling verdicts:**
 - **APPROVE** → proceed (to implementation after plan review; to next step after code review)
@@ -288,6 +358,12 @@ code is already written.
 - **REVISE** → read the review file in `.reviews/` for detailed feedback,
   address the issues, commit fixes, then **call `review_step` again** for re-review.
   The same reviewer evaluates whether your fixes address its concerns.
+- **REFUSED** → the engine's `review_step` guard rejected your call because the
+  step is already marked `**Status:** ✅ Complete` in STATUS.md while you're
+  trying to run a `code` or `test` review on it. This is the death-spiral
+  precondition. Follow the Recovery Recipe above (revert the premature status
+  update, commit the revert, then call `review_step` again — it will run
+  this time because the step is no longer marked Complete).
 - **UNAVAILABLE** → reviewer failed, proceed with caution
 
 **Example flow for a Review Level 2 task, Step 3:**