@agent-plan/pi-adapter 0.2.19-next.2 → 0.2.19-next.20

package/dist/index.js

@@ -9,8 +9,8 @@
  *  - inject context into prompts
  */
 import { Type } from "typebox";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, withFeatureLock, needsMotivation, findPhaseByRef, buildRecap } from "@agent-plan/core";
-import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, featureNumberOfPhase } from "@agent-plan/core/naming";
+import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock } from "@agent-plan/core";
+import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
@@ -105,11 +105,13 @@ const PLANNER_COMMAND_COMPLETIONS = [
     { value: "init", label: "init", description: "Initialize planner in this project" },
     { value: "show", label: "show", description: "Show planner overview" },
     { value: "repair", label: "repair", description: "Repair planner integrity" },
+    { value: "cleanup-orphans", label: "cleanup-orphans", description: "List and remove orphan phase files" },
     { value: "project discuss", label: "project discuss", description: "Run project discovery" },
     { value: "project language", label: "project language", description: "Set persistent language preferences" },
     { value: "feature list", label: "feature list", description: "List features" },
     { value: "feature add", label: "feature add", description: "Create a feature" },
     { value: "feature show", label: "feature show", description: "Show a feature" },
+    { value: "feature discuss", label: "feature discuss", description: "Discuss a feature" },
     { value: "feature update", label: "feature update", description: "Update a feature" },
     { value: "feature delete", label: "feature delete", description: "Delete a feature" },
     { value: "phase add", label: "phase add", description: "Add a phase" },
@@ -124,6 +126,9 @@ const PLANNER_COMMAND_COMPLETIONS = [
     { value: "task delete", label: "task delete", description: "Delete a task" },
     { value: "task start", label: "task start", description: "Mark a task in-progress" },
     { value: "task complete", label: "task complete", description: "Mark a task done" },
+    { value: "task checklist-add", label: "task checklist-add", description: "Add a checklist step: /planner task checklist-add <T00x> <title>" },
+    { value: "task checklist-remove", label: "task checklist-remove", description: "Remove a step: /planner task checklist-remove <T00x> <C{n}|title>" },
+    { value: "task checklist-toggle", label: "task checklist-toggle", description: "Tick/untick a step: /planner task checklist-toggle <T00x> <C{n}|title> [on|off]" },
     { value: "handoff list", label: "handoff list", description: "List phases with a handoff" },
     { value: "handoff prepare", label: "handoff prepare", description: "Tell the agent to write the handoff (legacy file-based)" },
     { value: "handoff show", label: "handoff show [P00x]", description: "Show a phase handoff (default: in-progress phase)" },
@@ -250,6 +255,34 @@ function phaseLabel(phase) {
 function taskLabel(task) {
     return `T${formatSequence(task.number)} — ${task.title}`;
 }
+function resolveFeatureRefStrict(features, ref) {
+    const raw = ref.trim();
+    if (!raw)
+        return { ok: false, error: "Feature ref is required." };
+    const normalized = raw.toLowerCase();
+    const byNumber = normalized.match(/^f(\d+)$/)
+        ? features.find((feature) => feature.number === parseInt(normalized.slice(1), 10))
+        : undefined;
+    if (byNumber)
+        return { ok: true, feature: byNumber };
+    const byShortId = features.find((feature) => feature.shortId?.toLowerCase() === normalized);
+    if (byShortId)
+        return { ok: true, feature: byShortId };
+    const byId = features.find((feature) => feature.id.toLowerCase() === normalized);
+    if (byId)
+        return { ok: true, feature: byId };
+    const exactName = features.filter((feature) => feature.name.toLowerCase() === normalized);
+    if (exactName.length === 1)
+        return { ok: true, feature: exactName[0] };
+    if (exactName.length > 1)
+        return { ok: false, error: `Ambiguous feature ref: ${raw}. Multiple features have that exact name; use F00x, shortId, or UUID.` };
+    const partialName = features.filter((feature) => feature.name.toLowerCase().includes(normalized));
+    if (partialName.length === 1)
+        return { ok: true, feature: partialName[0] };
+    if (partialName.length > 1)
+        return { ok: false, error: `Ambiguous feature ref: ${raw}. Matches: ${partialName.map((feature) => formatFeatureRef(feature.number)).join(", ")}. Use a specific F00x, shortId, or UUID.` };
+    return { ok: false, error: `Feature not found: ${raw}` };
+}
 async function buildHandoffMarkdown(st, reason, overrides) {
     const [plan, resume, activity] = await Promise.all([
         st.loadAll(),
@@ -352,8 +385,8 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ".planner/features/",
         currentPhase ? `.planner/phases/${currentPhase.id}.json` : "",
         latestPhaseUpdate && latestPhaseUpdate.id !== currentPhase?.id ? `.planner/phases/${latestPhaseUpdate.id}.json` : "",
-        ".planner/resume.json",
-        ".planner/generated/PLAN.md",
+        ".planner/.local/resume.json",
+        ".planner/.local/generated/PLAN.md",
     ].filter(Boolean);
     const recentActivityLines = recentActivity.length > 0
         ? recentActivity.map((entry) => `- ${entry.at} [${entry.type}] ${entry.ref}: ${entry.summary}`)
@@ -379,7 +412,7 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ? ["", `## Current Task Statuses (phase ${currentPhase.id})`, ...currentPhaseTaskLines]
         : [];
     return [
-        "# Handoff",
+        `# ${overrides?.title?.trim() || `Handoff — ${reason}`}`,
         "",
         `Created at: ${createdAt}`,
         `Updated at: ${updatedAt}`,
@@ -416,7 +449,7 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ...recentActivityLines,
         "",
         "## Reminder",
-        "- When work is fully resumed and this handoff is no longer needed, clear the phase handoff with handoff clear <ref> (or /planner handoff clear).",
+        "- This handoff is KEPT until a task in this phase starts (then auto-archived to .planner/.local/handoff-archive/) or the phase completes. No need to clear it manually.",
     ].join("\n");
 }
 async function writeProjectHandoff(st, reason, overrides) {
@@ -512,6 +545,9 @@ function statusIcon(status) {
     };
     return icons[status] ?? "❓";
 }
+function pad(n) {
+    return String(n).padStart(3, "0");
+}
 function applyTaskLifecycleDates(task, nextStatus, now) {
     const previousStatus = task.status;
     if (nextStatus === "in-progress" && !task.startedAt) {
@@ -744,9 +780,10 @@ export default function planPiExtension(pi) {
             // ── Step 1: Enable gating ───────────────────────────────────────
             // No blocking prompt in session_start: ctx.ui.input()/select() do not
             // render for NPM-loaded ESM extensions during session_start (they hang
-            // until the safety-net timeout). The planner is always DISABLED at
-            // startup; the user enables it with '/planner load' (which also starts
-            // the web UI on LAN and triggers the resume summary showing the URL).
+            // until the safety-net timeout). Tracked upstream via planner task
+            // T151 · EBRST. The planner is always DISABLED at startup; the user
+            // enables it with '/planner load' (which also starts the web UI on LAN
+            // and triggers the resume summary showing the URL).
             let enablePlanner = false;
             if (exists) {
                 ctx.ui.notify("Planner detected in this project. Run '/planner load' to enable the planner and start the web UI (LAN).", "info");
@@ -757,6 +794,10 @@ export default function planPiExtension(pi) {
                 const handoffs = await st.listHandoffs().catch(() => []);
                 if (handoffs.length > 0) {
                     ctx.ui.notify(`ℹ️  ${handoffs.length} phase handoff(s) pending — review with /planner handoff list.`, "info");
+                    // Mark each handoff as read (recap presented). Do NOT clear — content is
+                    // kept until a task in the phase starts (auto-archived) or phase completes.
+                    for (const h of handoffs)
+                        await st.markHandoffRead(h.phaseId).catch(() => { });
                 }
             }
             // If the user declined enablement, skip EVERYTHING (no web prompt, no migration, no summary).
@@ -935,6 +976,7 @@ export default function planPiExtension(pi) {
             "init",
             "show",
             "repair",
+            "cleanup-orphans",
             "project discuss",
             "project language",
             "feature list",
@@ -968,8 +1010,8 @@ export default function planPiExtension(pi) {
             "load",
             "stop",
         ];
-        const SUB_HELP = "Available: init, show, repair, project, feature, phase, task, discuss, handoff, web, export, export-full, bypass, clear-bypass, load, stop\n" +
-            "Try: /planner <TAB>  |  /planner feature list  |  /planner task start  |  /planner export-full\n" +
+        const SUB_HELP = "Available: init, show, repair, cleanup-orphans, project, feature, phase, task, discuss, handoff, web, export, export-full, bypass, clear-bypass, load, stop\n" +
+            "Try: /planner <TAB>  |  /planner feature list  |  /planner task start  |  /planner cleanup-orphans\n" +
             "Handoff actions: /planner handoff list | show [P00x] | write [P00x] | clear [P00x] | prepare";
         if (!a) {
             const action = await ctx.ui.select("Planner action", PLANNER_MENU_ACTIONS);
@@ -1125,6 +1167,34 @@ export default function planPiExtension(pi) {
                 ?? features.find((feature) => feature.name.toLowerCase().includes(normalized))
                 ?? null;
         }
+        function resolveFeatureRef(features, ref) {
+            const raw = ref.trim();
+            if (!raw)
+                return { ok: false, error: "Feature ref is required." };
+            const normalized = raw.toLowerCase();
+            const byNumber = normalized.match(/^f(\d+)$/)
+                ? features.find((feature) => feature.number === parseInt(normalized.slice(1), 10))
+                : undefined;
+            if (byNumber)
+                return { ok: true, feature: byNumber };
+            const byShortId = features.find((feature) => feature.shortId?.toLowerCase() === normalized);
+            if (byShortId)
+                return { ok: true, feature: byShortId };
+            const byId = features.find((feature) => feature.id.toLowerCase() === normalized);
+            if (byId)
+                return { ok: true, feature: byId };
+            const exactName = features.filter((feature) => feature.name.toLowerCase() === normalized);
+            if (exactName.length == 1)
+                return { ok: true, feature: exactName[0] };
+            if (exactName.length > 1)
+                return { ok: false, error: `Ambiguous feature ref: ${raw}. Multiple features have that exact name; use F00x, shortId, or UUID.` };
+            const partialName = features.filter((feature) => feature.name.toLowerCase().includes(normalized));
+            if (partialName.length == 1)
+                return { ok: true, feature: partialName[0] };
+            if (partialName.length > 1)
+                return { ok: false, error: `Ambiguous feature ref: ${raw}. Matches: ${partialName.map((feature) => formatFeatureRef(feature.number)).join(", ")}. Use a specific F00x, shortId, or UUID.` };
+            return { ok: false, error: `Feature not found: ${raw}` };
+        }
         function findPhaseByRef(phases, ref) {
             const normalized = ref.trim().toLowerCase();
             if (!normalized)
@@ -1142,19 +1212,6 @@ export default function planPiExtension(pi) {
                 ?? phases.find((phase) => phase.title.toLowerCase().includes(normalized))
                 ?? null;
         }
-        function findTaskByRef(phases, ref) {
-            const normalized = ref.trim().toLowerCase();
-            if (!normalized)
-                return null;
-            for (const phase of phases) {
-                const task = phase.tasks.find((entryTask) => entryTask.id.toLowerCase() === normalized
-                    || entryTask.title.toLowerCase() === normalized
-                    || entryTask.title.toLowerCase().includes(normalized));
-                if (task)
-                    return { phase, task };
-            }
-            return null;
-        }
         function profile_packageManager(pkg, lockfile) {
             if (pkg?.packageManager)
                 return pkg.packageManager;
@@ -1327,7 +1384,7 @@ export default function planPiExtension(pi) {
         // ═══════════════════════════════════════════════════════════════
         if (a === "feature") {
             if (!b) {
-                ctx.ui.notify("feature actions: list  |  add [name]  |  show [id|name]  |  update [id|name]  |  delete [id|name]", "info");
+                ctx.ui.notify("feature actions: list  |  add [name]  |  show [id|name]  |  discuss [id|name]  |  update [id|name]  |  delete [id|name]", "info");
                 return;
             }
             if (b === "list") {
@@ -1359,7 +1416,7 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const now = nowISO();
-                const featureNumber = (await st.loadFeatures()).features.length + 1;
+                const featureNumber = await st.allocFeatureNumber();
                 const shortId = createShortId(await st.assignedShortIds());
                 const priority = await st.nextPriority("feature");
                 const feature = {
@@ -1380,6 +1437,7 @@ export default function planPiExtension(pi) {
                     acceptedDecisions: [],
                     phaseIds: [],
                     dependsOn: [],
+                    statusLog: [],
                     createdAt: now,
                     updatedAt: now,
                 };
@@ -1388,7 +1446,7 @@ export default function planPiExtension(pi) {
                     return doc;
                 });
                 await st.writeGenerated();
-                ctx.ui.notify(`Feature created: ${feature.id} — ${feature.name}`, "info");
+                ctx.ui.notify(`Feature created: ${formatFeatureRef(feature.number)}${feature.shortId ? ` +MI+ ${feature.shortId}` : ""} +EM+ ${feature.name}`, "info");
                 return;
             }
             if (b === "show") {
@@ -1417,6 +1475,44 @@ export default function planPiExtension(pi) {
                 ].filter(Boolean).join("\n"), "info");
                 return;
             }
+            if (b === "discuss") {
+                const featuresDoc = await st.loadFeatures();
+                let feature = subArgs.trim() ? findFeatureByRef(featuresDoc.features, subArgs.trim()) : null;
+                if (!feature) {
+                    feature = await pickFeature();
+                    if (!feature) {
+                        ctx.ui.notify("No features to discuss. Create one first.", "warning");
+                        return;
+                    }
+                }
+                const description = await ctx.ui.editor("Feature description / scope / current implementation state", feature.description || "");
+                const workDone = await ctx.ui.editor("Work done / already decided", feature.workDone || "");
+                const workRemaining = await ctx.ui.editor("Work remaining / next work", feature.workRemaining || "");
+                const dependencies = await ctx.ui.input(`Dependencies (comma-separated) [${feature.dependsOn.join(", ") || ""}]`);
+                const featureId = feature.id;
+                const updatedDoc = await st.updateFeatures((doc) => {
+                    const target = doc.features.find((entry) => entry.id === featureId);
+                    if (!target)
+                        return doc;
+                    if (description !== undefined)
+                        target.description = description.trim();
+                    if (workDone !== undefined)
+                        target.workDone = workDone.trim();
+                    if (workRemaining !== undefined)
+                        target.workRemaining = workRemaining.trim();
+                    if (dependencies !== undefined)
+                        target.dependsOn = splitCsv(dependencies);
+                    target.discussedAt = nowISO();
+                    target.contextReady = true;
+                    target.contextReadyReason = "Updated through /planner feature discuss.";
+                    target.updatedAt = nowISO();
+                    return doc;
+                });
+                feature = updatedDoc.features.find((entry) => entry.id === featureId) ?? feature;
+                await st.writeGenerated();
+                ctx.ui.notify(`Feature discussed/updated: ${formatFeatureRef(feature.number)}${feature.shortId ? ` +MI+ ${feature.shortId}` : ""} +EM+ ${feature.name}`, "info");
+                return;
+            }
             if (b === "update") {
                 const featuresDoc = await st.loadFeatures();
                 let feature = subArgs.trim() ? findFeatureByRef(featuresDoc.features, subArgs.trim()) : null;
@@ -1469,7 +1565,7 @@ export default function planPiExtension(pi) {
                 });
                 feature = updatedDoc.features.find((entry) => entry.id === featureId) ?? feature;
                 await st.writeGenerated();
-                ctx.ui.notify(`Feature updated: ${feature.id} — ${feature.name} (${feature.status})`, "info");
+                ctx.ui.notify(`Feature updated: ${formatFeatureRef(feature.number)}${feature.shortId ? ` +MI+ ${feature.shortId}` : ""} +EM+ ${feature.name} (${feature.status})`, "info");
                 return;
             }
             if (b === "delete") {
@@ -1515,7 +1611,7 @@ export default function planPiExtension(pi) {
                 ctx.ui.notify(`Feature deleted: ${featureId}${phases.length > 0 ? cascade ? `; deleted ${affectedPhases} phase(s)` : `; unlinked ${affectedPhases} phase(s)` : ""}`, "info");
                 return;
             }
-            ctx.ui.notify(`Unknown feature action "${b}". Try: list, add, show, update, delete`, "warning");
+            ctx.ui.notify(`Unknown feature action "${b}". Try: list, add, show, discuss, update, delete`, "warning");
             return;
         }
         // ═══════════════════════════════════════════════════════════════
@@ -1546,7 +1642,7 @@ export default function planPiExtension(pi) {
                 await withFeatureLock(feature.id, async () => {
                     const phases = await st.loadAllPhases();
                     const featurePhases = phases.filter((p) => p.featureId === feature.id);
-                    const number = featurePhases.reduce((max, p) => Math.max(max, p.number), 0) + 1;
+                    const number = await st.allocPhaseNumber();
                     const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
                     const id = createPhaseId();
                     const shortId = createShortId(await st.assignedShortIds());
@@ -1557,6 +1653,9 @@ export default function planPiExtension(pi) {
                         openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                         createdAt: nowISO(), updatedAt: nowISO(),
                         handoff: "", handoffUpdatedAt: "",
+                        handoffReadAt: "",
+                        handoffHistory: [],
+                        statusLog: [],
                     };
                     await st.savePhase(phase);
                     await st.updateFeatures((doc) => {
@@ -1571,7 +1670,7 @@ export default function planPiExtension(pi) {
                 });
                 if (!phase)
                     return;
-                ctx.ui.notify(`Phase created: ${phase.id} — ${title} (feature ${feature.name})`, "info");
+                ctx.ui.notify(`Phase created: ${formatPhaseRef(phase.number, feature.number)} — ${title}${phase.shortId ? ` · ${phase.shortId}` : ""} (feature ${feature.name})`, "info");
                 const startDiscuss = await ctx.ui.input("Start phase discuss now? Type yes to continue");
                 if (isYes(startDiscuss)) {
                     await handlePlanner(`phase discuss ${phase.id}`, ctx);
@@ -1596,7 +1695,7 @@ export default function planPiExtension(pi) {
                 phase.status = "discovery";
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
-                ctx.ui.notify(`Discovery for ${phase.id}…`, "info");
+                ctx.ui.notify(`Discovery for ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}…`, "info");
                 // ── Recap: give full context before planning tasks ──
                 const recapPlan = await st.loadAll();
                 const recapProject = recapPlan.project;
@@ -1661,7 +1760,7 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Phase ${phase.id} is now **planned**.`, "info");
+                ctx.ui.notify(`Phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))} is now **planned**.${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "show") {
@@ -1709,7 +1808,7 @@ export default function planPiExtension(pi) {
                 }
                 await st.deletePhase(phase.id);
                 await st.writeGenerated();
-                ctx.ui.notify(`Phase deleted: ${phase.id}`, "info");
+                ctx.ui.notify(`Phase deleted: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "update") {
@@ -1761,7 +1860,7 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Phase updated: ${phase.id} — ${phase.title} (${phase.status})`, "info");
+                ctx.ui.notify(`Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))} — ${phase.title} (${phase.status})${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
             }
             ctx.ui.notify(`Unknown phase action "${b}". Try: add, show, discuss, delete, update`, "warning");
@@ -1772,7 +1871,7 @@ export default function planPiExtension(pi) {
         // ═══════════════════════════════════════════════════════════════
         if (a === "task") {
             if (!b) {
-                ctx.ui.notify("task actions: add  |  show [id]  |  discuss [id|name]  |  delete  |  update  |  start [id]  |  complete [id]", "info");
+                ctx.ui.notify("task actions: add  |  show [id]  |  discuss [id|name]  |  delete  |  update  |  start [id]  |  complete [id]  |  checklist-add <T00x> <title>  |  checklist-remove <T00x> <C{n}|title>  |  checklist-toggle <T00x> <C{n}|title> [on|off]", "info");
                 return;
             }
             if (b === "add") {
@@ -1787,7 +1886,7 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const shortName = clampSlug(title, 30, `task-${Date.now().toString(36)}`);
-                const taskNum = phase.tasks.length + 1;
+                const taskNum = await st.allocTaskNumber();
                 const taskId = createTaskId();
                 const shortId = createShortId(await st.assignedShortIds());
                 const priority = await st.nextPriority("task", phase.id);
@@ -1819,7 +1918,7 @@ export default function planPiExtension(pi) {
             }
             if (b === "discuss") {
                 const phases = await st.loadAllPhases();
-                let resolved = subArgs.trim() ? findTaskByRef(phases, subArgs.trim()) : null;
+                let resolved = subArgs.trim() ? findTaskByRef(phases, (await st.loadFeatures()).features, subArgs.trim()) : null;
                 if (!resolved) {
                     const phase = await pickPhase();
                     if (!phase) {
@@ -1843,7 +1942,7 @@ export default function planPiExtension(pi) {
                 if (description?.trim())
                     task.description = description.trim();
                 if (checklistSeed?.trim()) {
-                    task.checklist = splitCsv(checklistSeed).map((itemTitle, index) => ({
+                    task.checklist = splitCsv(checklistSeed).map((itemTitle, index) => ({ number: index + 1,
                         id: createChecklistItemId(task.id, index + 1, itemTitle),
                         title: itemTitle,
                         checked: false,
@@ -1853,14 +1952,14 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Task ${task.id} discussed and updated.`, "info");
+                ctx.ui.notify(`Task ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} discussed and updated.`, "info");
                 return;
             }
             if (b === "show") {
                 let phase = null;
                 let task = null;
                 if (subArgs.trim()) {
-                    const resolved = findTaskByRef(await st.loadAllPhases(), subArgs.trim());
+                    const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
                     phase = resolved?.phase ?? null;
                     task = resolved?.task ?? null;
                 }
@@ -1922,7 +2021,7 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Task deleted: ${task.id}`, "info");
+                ctx.ui.notify(`Task deleted: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")}${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "update") {
@@ -1971,14 +2070,14 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = now;
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Task updated: ${task.id} — ${task.title} (${task.status})`, "info");
+                ctx.ui.notify(`Task updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (${task.status})${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "start") {
                 let phase = null;
                 let task = null;
                 if (subArgs.trim()) {
-                    const resolved = findTaskByRef(await st.loadAllPhases(), subArgs.trim());
+                    const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
                     phase = resolved?.phase ?? null;
                     task = resolved?.task ?? null;
                 }
@@ -2002,12 +2101,16 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
                     return;
                 }
-                // Hygiene notice (non-blocking): surface an existing handoff but never
-                // block task_start — the handoff is a captured-context artifact, not a
-                // lock (a small modification after writing a handoff should start without
-                // forcing deletion, which would lose context).
-                if ((await st.listHandoffs()).length > 0) {
-                    ctx.ui.notify("ℹ️  One or more phases have a pending handoff — if relevant to the task you're starting, read it with /planner handoff show <ref>, then clear with /planner handoff clear. Proceeding with task start.", "info");
+                // Auto-archive the handoff on THIS task's phase (reason: task-started) —
+                // the agent is now actively working, so the captured context is consumed.
+                // Other phases' handoffs are left untouched (informational, non-blocking).
+                if ((phase.handoff ?? "") !== "") {
+                    await st.clearPhaseHandoff(phase.id, "task-started").catch(() => { });
+                    ctx.ui.notify("📦 Archived handoff for this phase (task started) — recover via /planner handoff list + .planner/.local/handoff-archive/.", "info");
+                }
+                const _otherHandoffs = (await st.listHandoffs()).filter((h) => h.phaseId !== phase.id);
+                if (_otherHandoffs.length > 0) {
+                    ctx.ui.notify(`ℹ️  ${_otherHandoffs.length} other phase handoff(s) pending — review with /planner handoff list if relevant.`, "info");
                 }
                 const now = nowISO();
                 // Record status change in the incremental statusLog.
@@ -2026,14 +2129,14 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = now;
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`✅ Task started: ${task.id} — ${task.title} (in-progress)`, "info");
+                ctx.ui.notify(`✅ Task started: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (in-progress)${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "complete") {
                 let phase = null;
                 let task = null;
                 if (subArgs.trim()) {
-                    const resolved = findTaskByRef(await st.loadAllPhases(), subArgs.trim());
+                    const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
                     phase = resolved?.phase ?? null;
                     task = resolved?.task ?? null;
                 }
@@ -2081,10 +2184,78 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = now;
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`✅ Task completed: ${task.id} — ${task.title} (done)`, "info");
+                ctx.ui.notify(`✅ Task completed: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (done)${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
+                return;
+            }
+            // checklist-add <T00x> <title>  /  checklist-remove <T00x> <C{n}|title>  /  checklist-toggle <T00x> <C{n}|title> [on|off]
+            if (b === "checklist-add" || b === "checklist-remove" || b === "checklist-toggle") {
+                const [taskRef, ...itemParts] = rest;
+                const itemText = itemParts.join(" ").trim();
+                if (!taskRef || !itemText) {
+                    ctx.ui.notify(`Usage: /planner task ${b} <T00x> <${b === "checklist-add" ? "title" : "C{n}|title"}>${b === "checklist-toggle" ? " [on|off]" : ""}`, "warning");
+                    return;
+                }
+                const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, taskRef.trim());
+                if (!resolved) {
+                    ctx.ui.notify(`Task not found: ${taskRef}`, "warning");
+                    return;
+                }
+                let checked;
+                if (b === "checklist-toggle") {
+                    const m = itemText.match(/\s+(on|off)$/i);
+                    if (m) {
+                        checked = m[1].toLowerCase() === "on";
+                    }
+                }
+                const selector = b === "checklist-toggle" ? itemText.replace(/\s+(on|off)$/i, "").trim() : itemText;
+                let msg = "";
+                await st.updatePhase(resolved.phase.id, (phase) => {
+                    const task = phase.tasks.find((t) => t.id === resolved.task.id);
+                    if (!task) {
+                        msg = `Task not found: ${taskRef}`;
+                        return phase;
+                    }
+                    const ck = task.checklist ?? [];
+                    if (b === "checklist-add") {
+                        const item = addChecklistItem(ck, task.id, selector);
+                        ck.push(item);
+                        task.checklist = ck;
+                        msg = `Added C${item.number} "${item.title}" (${ck.length} items)`;
+                    }
+                    else if (b === "checklist-remove") {
+                        if (ck.length === 0) {
+                            msg = `Task "${task.title}" has no checklist.`;
+                            return phase;
+                        }
+                        const removed = removeChecklistItem(ck, selector);
+                        if (!removed) {
+                            msg = `No checklist item matching "${selector}".`;
+                            return phase;
+                        }
+                        msg = `Removed C${removed.number} "${removed.title}" (${ck.length} items left)`;
+                    }
+                    else {
+                        if (ck.length === 0) {
+                            msg = `Task "${task.title}" has no checklist.`;
+                            return phase;
+                        }
+                        const target = toggleChecklistItem(ck, selector, checked);
+                        if (!target) {
+                            msg = `No checklist item matching "${selector}".`;
+                            return phase;
+                        }
+                        const doneCount = ck.filter((i) => i.checked).length;
+                        msg = `C${target.number} "${target.title}" → ${target.checked ? "done" : "open"} (${doneCount}/${ck.length} checked)`;
+                    }
+                    task.updatedAt = nowISO();
+                    phase.updatedAt = nowISO();
+                    return phase;
+                });
+                await st.writeGenerated();
+                ctx.ui.notify(`✅ ${msg}`, "info");
                 return;
             }
-            ctx.ui.notify(`Unknown task action "${b}". Try: add, show, discuss, delete, update, start, complete`, "warning");
+            ctx.ui.notify(`Unknown task action "${b}". Try: add, show, discuss, delete, update, start, complete, checklist-add, checklist-remove, checklist-toggle`, "warning");
             return;
         }
         // ── discuss (legacy alias) ──
@@ -2140,7 +2311,9 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const handoffs = await st.listHandoffs();
-                await capturedPi.sendUserMessage("Prepare the canonical session handoff now and write it on the current in-progress phase using the `handoff_write` tool (entity-scoped, stored on phase.handoff — .planner/HANDOFF.md is deprecated).\n\n" +
+                await capturedPi.sendUserMessage("Prepare the canonical session handoff now and write it on the phase the user explicitly identifies as the one just worked on in this session, using the `handoff_write` tool (entity-scoped, stored on phase.handoff — .planner/HANDOFF.md is deprecated).\n\n" +
+                    "Pass a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring') — it becomes the H1 / first line in handoff lists. Generic titles like 'Handoff' or 'Canonical handoff' are REJECTED.\n\n" +
+                    "WARNING: Do not default to 'current in-progress phase' or a stale resume pointer. If the user just completed P058, write the handoff on P058 (or its continuation P061), not on P031 just because P031 is marked in-progress or has an existing handoff.\n\n" +
                     "The handoff MUST be a structured markdown document containing at minimum:\n" +
                     "- `Created at:` and `Updated at:` lines (ISO timestamps)\n" +
                     "- `Reason:` why this handoff is being written\n" +
@@ -2164,7 +2337,7 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(r.error, "warning");
                     return;
                 }
-                await st.clearPhaseHandoff(r.phase.id);
+                await st.clearPhaseHandoff(r.phase.id, "manual");
                 ctx.ui.notify(`Cleared handoff on ${r.compositeRef}`, "info");
                 return;
             }
@@ -2226,6 +2399,25 @@ export default function planPiExtension(pi) {
             ctx.ui.notify(`Repair done: renamed ${m.renamed}, repaired ${m.repaired} refs, inferred ${m.inferred}. Integrity: ${dup} duplicate, ${dang} dangling.`, "info");
             return;
         }
+        if (a === "cleanup-orphans") {
+            const found = await st.listOrphanPhases();
+            if (found.length === 0) {
+                ctx.ui.notify("No orphan phases found.", "info");
+                return;
+            }
+            const lines = [
+                `Found ${found.length} orphan phase${found.length === 1 ? "" : "s"}:`,
+                ...found.map((phase) => `- ${phase.compositeRef}${phase.shortId ? ` · ${phase.shortId}` : ""} — ${phase.title} (${phase.reason})`),
+            ];
+            const confirmed = await ctx.ui.confirm(lines.join("\n\n"), "Delete orphan phase files?");
+            if (!confirmed) {
+                ctx.ui.notify("Cleanup aborted.", "warning");
+                return;
+            }
+            const report = await st.cleanupOrphanPhases();
+            ctx.ui.notify(`Removed ${report.removed.length} orphan phase${report.removed.length === 1 ? "" : "s"}.`, "info");
+            return;
+        }
         // ── export ──
         if (a === "export" || a === "export-full") {
             const isFull = a === "export-full" || subArgs.includes("--full");
@@ -2595,7 +2787,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_render",
         label: "Plan Render",
-        description: "Regenerate all generated markdown views in .planner/generated/. Call after any data change to keep docs in sync.",
+        description: "Regenerate all generated markdown views in .planner/.local/generated/. Call after any data change to keep docs in sync.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -2608,7 +2800,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_repair",
         label: "Plan Repair",
-        description: "Repair dangling feature→phase references and report plan integrity (duplicate phase ids, dangling phase refs). Safe to run anytime; run if the planner reports ENOENT/phase not found or after manual edits to .planner/.",
+        description: "Repair dangling feature→phase references, rebuild phase containment from each task's own phaseId (heals the migrateToGlobalSequence task-shuffle bug), and report plan integrity (duplicate phase ids, dangling phase refs). Safe to run anytime; run if the planner reports ENOENT/phase not found, tasks appear in the wrong phase, or after manual edits to .planner/.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -2616,9 +2808,11 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const report = await st.repair();
             const m = report.migrated;
+            const c = report.containment;
             const lines = [
                 `Repair complete.`,
                 `Migration: renamed=${m.renamed}, repaired=${m.repaired} refs, inferred=${m.inferred}.`,
+                `Containment: ${c.changed} phase file${c.changed === 1 ? "" : "s"} rewritten (tasks regrouped by their own phaseId), ${c.tasks} tasks scanned, ${c.orphan} orphan.`,
                 `Integrity: duplicatePhaseIds=${report.integrity.duplicatePhaseIds.length}, danglingPhaseIds=${report.integrity.danglingPhaseIds.length}.`,
             ];
             if (report.integrity.danglingPhaseIds.length)
@@ -2628,6 +2822,38 @@ export default function planPiExtension(pi) {
             return { content: [{ type: "text", text: lines.join("\n") }], details: report };
         },
     });
+    pi.registerTool({
+        name: "plan_cleanup_orphan_phases",
+        label: "Plan Cleanup Orphan Phases",
+        description: "Discover phase files that no longer resolve to a valid owning feature, and optionally delete them. Run once with confirm=false (default) to inspect, then rerun with confirm=true to remove them.",
+        parameters: Type.Object({
+            confirm: Type.Optional(Type.Boolean({ description: "Set true to actually delete the discovered orphan phase files. Default: false (dry-run/list only)." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const found = await st.listOrphanPhases();
+            if (!params.confirm) {
+                if (found.length === 0)
+                    return { content: [{ type: "text", text: "No orphan phases found." }], details: { found: [] } };
+                const lines = [
+                    `Found ${found.length} orphan phase${found.length === 1 ? "" : "s"}.`,
+                    ...found.map((phase) => `- ${phase.compositeRef}${phase.shortId ? ` · ${phase.shortId}` : ""} — ${phase.title} (${phase.reason})`),
+                    "Rerun with confirm=true to delete these orphan phase files.",
+                ];
+                return { content: [{ type: "text", text: lines.join("\n") }], details: { found, confirmRequired: true } };
+            }
+            const report = await st.cleanupOrphanPhases();
+            if (report.removed.length === 0)
+                return { content: [{ type: "text", text: "No orphan phases found." }], details: report };
+            const lines = [
+                `Removed ${report.removed.length} orphan phase${report.removed.length === 1 ? "" : "s"}.`,
+                ...report.removed.map((phase) => `- ${phase.compositeRef}${phase.shortId ? ` · ${phase.shortId}` : ""} — ${phase.title}`),
+            ];
+            return { content: [{ type: "text", text: lines.join("\n") }], details: report };
+        },
+    });
     pi.registerTool({
         name: "plan_get_handoff",
         label: "Plan Get Handoff",
@@ -2647,9 +2873,10 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_write_handoff",
         label: "Plan Write Handoff",
-        description: "DEPRECATED — writes to the entity-scoped phase.handoff (not .planner/HANDOFF.md). Prefer handoff_write. Write or refresh the canonical phase handoff. Capture full design context, not just operational resume steps: pass extraSections with locked decisions, architecture (with file:line refs), mode/state flows, plugin/API contracts, data mappings, files touched, and known gaps so a resuming agent doesn't re-discover decisions already made.",
+        description: "DEPRECATED — writes to the entity-scoped phase.handoff (not .planner/HANDOFF.md). Prefer handoff_write. Write or refresh the canonical phase handoff. Capture full design context, not just operational resume steps: pass extraSections with locked decisions, architecture (with file:line refs), mode/state flows, plugin/API contracts, data mappings, files touched, and known gaps so a resuming agent doesn't re-discover decisions already made. IMPORTANT: write the handoff on the phase the user explicitly identifies as the one just worked on in this session; do not default to a stale 'current phase' pointer or an existing handoff on a different phase.",
         parameters: Type.Object({
             reason: Type.Optional(Type.String({ description: "Why the handoff is being written" })),
+            title: Type.Optional(Type.String({ description: "Meaningful handoff title summarizing the work (becomes the H1 / first line in lists). Example: 'P049 — featureId validation: tests + adapter wiring'." })),
             whatWasBeingDone: Type.Optional(Type.String({ description: "Optional override for the current work summary" })),
             howToResume: Type.Optional(Type.String({ description: "Optional override for resume instructions" })),
             extraSections: Type.Optional(Type.Array(Type.Object({
@@ -2662,6 +2889,7 @@ export default function planPiExtension(pi) {
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const markdown = await buildHandoffMarkdown(st, params.reason?.trim() || "manual tool handoff", {
+                ...(params.title?.trim() ? { title: params.title.trim() } : {}),
                 ...(params.whatWasBeingDone?.trim() ? { whatWasBeingDone: params.whatWasBeingDone.trim() } : {}),
                 ...(params.howToResume?.trim() ? { howToResume: params.howToResume.trim() } : {}),
                 ...(params.extraSections && params.extraSections.length > 0
@@ -2691,13 +2919,16 @@ export default function planPiExtension(pi) {
             const r = await resolvePhaseForHandoff(st, undefined);
             if (!r.ok)
                 return { content: [{ type: "text", text: `⚠️ plan_delete_handoff is deprecated — use handoff_clear. ${r.error}` }], details: { deprecated: true, error: r.error } };
-            await st.clearPhaseHandoff(r.phase.id);
+            await st.clearPhaseHandoff(r.phase.id, "manual");
             return { content: [{ type: "text", text: `⚠️ plan_delete_handoff is deprecated — cleared handoff on ${r.compositeRef} (phase.handoff). Prefer handoff_clear.` }], details: { deprecated: true, phaseRef: r.compositeRef, phaseId: r.phase.id } };
         },
     });
     // Resolve a phase for entity-scoped handoff tools. ref = P00x | P00x(F00x) |
     // UUID | title; omitted -> current in-progress phase (phase.status, or the
     // phase containing an in-progress task). Returns the phase + its composite ref.
+    // NOTE: callers must NOT treat the resolved phase as a directive; it is a
+    // fallback pointer that may be stale if the agent worked on a different
+    // workstream in this session.
     async function resolvePhaseForHandoff(st, ref) {
         const phases = await st.loadAllPhases();
         const features = (await st.loadFeatures()).features;
@@ -2757,9 +2988,10 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_write",
         label: "Handoff Write",
-        description: "Write/refresh the entity-scoped handoff on a phase. Pass content (or markdown_content). phaseRef optional (default: current in-progress phase). Captures design context for a resuming agent on that phase.",
+        description: "Write/refresh the entity-scoped handoff on a phase. Pass content (or markdown_content) AND a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring'). The title becomes the H1 and the first line shown in handoff lists; generic titles like 'Handoff' or 'Canonical handoff' are REJECTED. phaseRef optional (default: current in-progress phase). IMPORTANT: defaulting to 'current in-progress phase' is a fallback only; write the handoff on the phase the user explicitly identifies as the one just worked on in this session, and do not update an existing handoff on a different phase unless the user confirms.",
         parameters: Type.Object({
             phaseRef: Type.Optional(Type.String({ description: "Phase ref. Default: current in-progress phase." })),
+            title: Type.Optional(Type.String({ description: "Meaningful handoff title summarizing the work (becomes the H1 / first line in lists). REQUIRED if your markdown's first heading is generic. Example: 'P049 — featureId validation: tests + adapter wiring'." })),
             content: Type.Optional(Type.String({ description: "Handoff text (plain)." })),
             markdown_content: Type.Optional(Type.String({ description: "Handoff text (markdown). Preferred over content." })),
         }),
@@ -2767,9 +2999,32 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const body = (params.markdown_content ?? params.content ?? "").trim();
+            let body = (params.markdown_content ?? params.content ?? "").trim();
             if (!body)
                 return { content: [{ type: "text", text: "❌ Provide the handoff text (content or markdown_content)." }], details: { error: "empty text" } };
+            const title = params.title?.trim();
+            // Derive the current first non-empty line (H1) of the supplied body.
+            const firstLine = body.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
+            const firstHeadingText = firstLine.replace(/^#+\s*/, "").trim();
+            const isGeneric = !firstHeadingText || /^(handoff|canonical handoff|session handoff)$/i.test(firstHeadingText);
+            if (!title && isGeneric) {
+                return {
+                    content: [{ type: "text", text: "❌ Generic handoff title. Provide a meaningful `title` (or start your markdown with a descriptive H1) summarizing the work — e.g. 'P049 — featureId validation: tests + adapter wiring'. Generic titles like 'Handoff' or 'Canonical handoff' are not accepted." }],
+                    details: { error: "generic title", firstHeadingText },
+                };
+            }
+            // Normalize: if a title is provided, replace or prepend the H1 so the first line is the title.
+            if (title) {
+                const lines = body.split(/\r?\n/);
+                const firstIdx = lines.findIndex((l) => l.trim().length > 0);
+                if (firstIdx !== -1 && /^#+\s/.test(lines[firstIdx] ?? "")) {
+                    lines[firstIdx] = `# ${title}`;
+                    body = lines.join("\n");
+                }
+                else {
+                    body = `# ${title}\n\n${body}`;
+                }
+            }
             const r = await resolvePhaseForHandoff(st, params.phaseRef);
             if (!r.ok)
                 return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
@@ -2789,8 +3044,8 @@ export default function planPiExtension(pi) {
             const r = await resolvePhaseForHandoff(st, params.phaseRef);
             if (!r.ok)
                 return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
-            await st.clearPhaseHandoff(r.phase.id);
-            return { content: [{ type: "text", text: `✅ Cleared handoff on ${r.compositeRef}. (handoffUpdatedAt preserved as audit)` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
+            await st.clearPhaseHandoff(r.phase.id, "manual");
+            return { content: [{ type: "text", text: `✅ Cleared handoff on ${r.compositeRef} (handoffUpdatedAt preserved as audit; archived to .planner/.local/handoff-archive/).` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
         },
     });
     pi.registerTool({
@@ -2826,38 +3081,44 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "feature_list",
         label: "Feature List",
-        description: "List all features with their ids, statuses, and phase counts.",
-        parameters: Type.Object({}),
-        async execute(_id, _params, _signal, _onUpdate, ctx) {
+        description: "List features (compact: F00x · shortId — name (status; N phases, M tasks)). Use this to discover refs cheaply — do NOT read .planner/ files or plan_get full=true to find entities.",
+        parameters: Type.Object({ featureRef: Type.Optional(Type.String({ description: "Optional: filter to one feature (F00x/shortId/UUID/name)" })) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const features = (await st.loadFeatures()).features;
+            const all = (await st.loadFeatures()).features;
+            const ref = params.featureRef?.trim();
+            const matchF = (f) => !ref || formatFeatureRef(f.number) === ref || f.shortId === ref || f.id === ref || f.name.toLowerCase() === ref.toLowerCase();
+            const features = all.filter(matchF);
             const phases = await st.loadAllPhases();
             const summary = features.map((f) => {
                 const fp = phases.filter((p) => p.featureId === f.id);
-                return `- ${statusIcon(f.status)} ${f.id} — ${f.name} (${fp.length} phases, ${fp.reduce((t, p) => t + p.tasks.length, 0)} tasks)`;
+                return `- ${formatFeatureRef(f.number)}${f.shortId ? ` · ${f.shortId}` : ""} — ${f.name} (${f.status}; ${fp.length} phases, ${fp.reduce((t, p) => t + p.tasks.length, 0)} tasks)`;
             }).join("\n");
-            return { content: [{ type: "text", text: summary || "No features" }], details: { features } };
+            return { content: [{ type: "text", text: summary || "No features" }], details: {} };
         },
     });
     pi.registerTool({
         name: "feature_get",
         label: "Feature Get",
-        description: "Read full details of a feature, including its phases and their tasks.",
+        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description.",
         parameters: Type.Object({
-            featureId: Type.String({ description: "Feature ID, e.g. feature-001-dynamic-header" }),
+            featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
+            full: Type.Optional(Type.Boolean({ description: "If true, include the feature description. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const features = (await st.loadFeatures()).features;
-            const feature = features.find((f) => f.id === params.featureId);
+            const ref = params.featureId.trim();
+            const feature = features.find((f) => formatFeatureRef(f.number) === ref || f.shortId === ref || f.id === ref || f.name.toLowerCase() === ref.toLowerCase());
             if (!feature)
-                return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
+                return { content: [{ type: "text", text: `Feature not found: ${ref}` }], details: {} };
             const phases = (await st.loadAllPhases()).filter((p) => p.featureId === feature.id);
-            return { content: [{ type: "text", text: `${statusIcon(feature.status)} ${feature.name} (${feature.id}) — ${phases.length} phases` }], details: { feature, phases } };
+            const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases)`;
+            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${feature.description || ""}` : summary }], details: {} };
         },
     });
     pi.registerTool({
@@ -2880,7 +3141,7 @@ export default function planPiExtension(pi) {
             const priority = await st.nextPriority("feature");
             const feature = {
                 id: createFeatureId(),
-                number: currentFeatures.length + 1,
+                number: await st.allocFeatureNumber(),
                 shortId,
                 priority,
                 name: params.name,
@@ -2896,6 +3157,7 @@ export default function planPiExtension(pi) {
                 acceptedDecisions: [],
                 phaseIds: [],
                 dependsOn: [],
+                statusLog: [],
                 createdAt: now,
                 updatedAt: now,
             };
@@ -2906,7 +3168,52 @@ export default function planPiExtension(pi) {
                 return doc;
             });
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Feature created: ${feature.id}` }], details: feature };
+            return { content: [{ type: "text", text: `✅ Feature created: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
+        },
+    });
+    pi.registerTool({
+        name: "feature_discuss",
+        label: "Feature Discuss",
+        description: "Persist feature discovery/governance fields so the feature context is ready before detailed implementation planning.",
+        parameters: Type.Object({
+            featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
+            description: Type.Optional(Type.String({ description: "Current implementation state, scope, and goals for this feature" })),
+            workDone: Type.Optional(Type.String({ description: "What is already implemented / decided" })),
+            workRemaining: Type.Optional(Type.String({ description: "What still needs to be done" })),
+            dependencies: Type.Optional(Type.Array(Type.String(), { description: "Cross-feature or external dependencies" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedFeature = resolveFeatureRefStrict(features, params.featureId);
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const featureId = resolvedFeature.feature.id;
+            const updatedDoc = await st.updateFeatures((doc) => {
+                const feature = doc.features.find((f) => f.id === featureId);
+                if (!feature)
+                    return doc;
+                if (params.description !== undefined)
+                    feature.description = params.description;
+                if (params.workDone !== undefined)
+                    feature.workDone = params.workDone;
+                if (params.workRemaining !== undefined)
+                    feature.workRemaining = params.workRemaining;
+                if (params.dependencies !== undefined)
+                    feature.dependsOn = params.dependencies.map((item) => item.trim()).filter(Boolean);
+                feature.discussedAt = nowISO();
+                feature.contextReady = true;
+                feature.contextReadyReason = "Updated through feature_discuss tool.";
+                feature.updatedAt = nowISO();
+                return doc;
+            });
+            const feature = updatedDoc.features.find((f) => f.id === featureId);
+            if (!feature)
+                return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
+            await st.writeGenerated();
+            return { content: [{ type: "text", text: `✅ Feature discussed/updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
         },
     });
     pi.registerTool({
@@ -2914,7 +3221,7 @@ export default function planPiExtension(pi) {
         label: "Feature Update",
         description: "Update one or more fields of a feature. Only provided fields are changed. IMPORTANT: feature status is derived from child phases/tasks, so do not update feature.status directly unless truly necessary.",
         parameters: Type.Object({
-            featureId: Type.String({ description: "Feature ID" }),
+            featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
             name: Type.Optional(Type.String({ description: "New name" })),
             description: Type.Optional(Type.String({ description: "New description" })),
             status: Type.Optional(Type.String({ description: "New status: planned|in-progress|done|blocked|canceled. Avoid setting this directly unless you truly need an override: feature status is derived from child phases/tasks." })),
@@ -2936,10 +3243,15 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedFeature = resolveFeatureRefStrict(features, params.featureId);
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const featureId = resolvedFeature.feature.id;
             let foundDoc;
             try {
                 foundDoc = await st.updateFeatures((doc) => {
-                    const feature = doc.features.find((f) => f.id === params.featureId);
+                    const feature = doc.features.find((f) => f.id === featureId);
                     if (!feature)
                         return doc; // not found: no-op, handled below
                     if (params.name !== undefined)
@@ -2977,11 +3289,11 @@ export default function planPiExtension(pi) {
             catch (e) {
                 return { content: [{ type: "text", text: `Update failed: ${e}` }], details: {} };
             }
-            const feature = foundDoc?.features.find((f) => f.id === params.featureId);
+            const feature = foundDoc?.features.find((f) => f.id === featureId);
             if (!feature)
                 return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Feature updated: ${feature.id} (${feature.status})` }], details: feature };
+            return { content: [{ type: "text", text: `✅ Feature updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
         },
     });
     pi.registerTool({
@@ -2989,28 +3301,30 @@ export default function planPiExtension(pi) {
         label: "Feature Delete",
         description: "Delete a feature. Its phases are unlinked (featureId cleared) but NOT deleted unless cascade=true.",
         parameters: Type.Object({
-            featureId: Type.String({ description: "Feature ID to delete" }),
+            featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name to delete" }),
             cascade: Type.Optional(Type.Boolean({ description: "If true, also delete all phases belonging to this feature. Default: false" })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedFeature = resolveFeatureRefStrict(features, params.featureId);
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const featureId = resolvedFeature.feature.id;
             let deleted = false;
             await st.updateFeatures((doc) => {
                 const before = doc.features.length;
-                doc.features = doc.features.filter((f) => f.id !== params.featureId);
+                doc.features = doc.features.filter((f) => f.id !== featureId);
                 if (doc.features.length !== before)
                     deleted = true;
                 return doc;
             });
-            if (!deleted) {
-                return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
-            }
             let cascadeCount = 0;
             if (params.cascade) {
                 const phases = await st.loadAllPhases();
-                for (const phase of phases.filter((p) => p.featureId === params.featureId)) {
+                for (const phase of phases.filter((p) => p.featureId === featureId)) {
                     await st.deletePhase(phase.id);
                     cascadeCount += 1;
                 }
@@ -3023,40 +3337,57 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "phase_list",
         label: "Phase List",
-        description: "List all phases (optionally filtered by featureId) with id, status, and task counts.",
+        description: "List phases (compact: F00x/P00x · shortId — title (status; N tasks) [F00x]). Filters: featureRef, status. Cheap discovery — do NOT read .planner/ files or plan_get full=true.",
         parameters: Type.Object({
-            featureId: Type.Optional(Type.String({ description: "If provided, only list phases of this feature" })),
+            featureRef: Type.Optional(Type.String({ description: "Optional: filter to one feature (F00x/shortId/UUID/name)" })),
+            status: Type.Optional(Type.String({ description: "Optional: filter by status name" })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
             let phases = await st.loadAllPhases();
-            if (params.featureId)
-                phases = phases.filter((p) => p.featureId === params.featureId);
-            const summary = phases.map((p) => `- ${statusIcon(p.status)} ${p.id} — ${p.title} (${p.tasks.length} tasks, feature ${p.featureId ?? "none"})`).join("\n");
-            return { content: [{ type: "text", text: summary || "No phases" }], details: { phases } };
+            const fref = params.featureRef?.trim();
+            if (fref) {
+                const f = features.find((x) => formatFeatureRef(x.number) === fref || x.shortId === fref || x.id === fref || x.name.toLowerCase() === fref.toLowerCase());
+                if (!f)
+                    return { content: [{ type: "text", text: `Feature not found: ${fref}` }], details: {} };
+                phases = phases.filter((p) => p.featureId === f.id);
+            }
+            if (params.status)
+                phases = phases.filter((p) => p.status === params.status);
+            const summary = phases.map((p) => {
+                const fNum = featureNumberOfPhase(p, features);
+                const fTag = fNum !== undefined ? ` [F${pad(fNum)}]` : "";
+                return `- ${formatPhaseRef(p.number, fNum)}${p.shortId ? ` · ${p.shortId}` : ""} — ${p.title} (${p.status}; ${p.tasks.length} tasks)${fTag}`;
+            }).join("\n");
+            return { content: [{ type: "text", text: summary || "No phases" }], details: {} };
         },
     });
     pi.registerTool({
         name: "phase_get",
         label: "Phase Get",
-        description: "Read full details of a phase, including its tasks.",
+        description: "Show a phase. Compact identity by default (saves tokens); pass full=true to include the description and derived linked requirements.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID, e.g. phase-01-setup" }),
+            phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title" }),
+            full: Type.Optional(Type.Boolean({ description: "If true, include the phase description. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            let phase;
-            try {
-                phase = await st.loadPhase(params.phaseId);
-            }
-            catch {
+            const features = (await st.loadFeatures()).features;
+            const phase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
+            if (!phase)
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
-            }
-            return { content: [{ type: "text", text: `${statusIcon(phase.status)} ${phase.title} (${phase.id}) — ${phase.tasks.length} tasks` }], details: phase };
+            const linkedRequirements = await st.linkedRequirementsForPhase(phase.id);
+            const reqCount = linkedRequirements.length;
+            const summary = `${phase.title} — ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}${phase.shortId ? ` · ${phase.shortId}` : ""} (${phase.status}; ${phase.tasks.length} tasks${reqCount ? `; ${reqCount} linked requirement${reqCount === 1 ? "" : "s"}` : ""})`;
+            const requirementsBlock = reqCount > 0
+                ? `\n\nLinked requirements:\n${linkedRequirements.map((requirement) => `- ${requirement.title} (${requirement.status})`).join("\n")}`
+                : "";
+            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${phase.description || ""}${requirementsBlock}` : summary }], details: { linkedRequirements } };
         },
     });
     pi.registerTool({
@@ -3076,18 +3407,27 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             if (!params.featureId?.trim())
                 return { content: [{ type: "text", text: "featureId is required: a phase must belong to a feature." }], details: {} };
+            const createPhaseFeatures = (await st.loadFeatures()).features;
+            const resolvedFeature = resolveFeatureRefStrict(createPhaseFeatures, params.featureId);
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const featureId = resolvedFeature.feature.id;
+            const featureValidation = await validateResolvedTarget("feature", featureId, () => st.loadFeatures().then((doc) => doc.features.find((f) => f.id === featureId)).catch(() => undefined));
+            if (!featureValidation.ok)
+                return { content: [{ type: "text", text: featureValidation.error }], details: {} };
+            const existingFeature = (await st.loadFeatures()).features.find((f) => f.id === featureId);
+            if (!existingFeature)
+                return { content: [{ type: "text", text: `Resolved feature ${featureId} no longer exists. Refusing to create phase.` }], details: {} };
             let phase;
-            await withFeatureLock(params.featureId, async () => {
-                const phases = await st.loadAllPhases();
-                const featurePhases = phases.filter((p) => p.featureId === params.featureId);
-                const number = featurePhases.reduce((max, p) => Math.max(max, p.number), 0) + 1;
+            await withFeatureLock(featureId, async () => {
+                const number = await st.allocPhaseNumber();
                 const id = createPhaseId();
                 const shortId = createShortId(await st.assignedShortIds());
-                const priority = await st.nextPriority("phase", params.featureId);
+                const priority = await st.nextPriority("phase", featureId);
                 const now = nowISO();
                 phase = {
                     id, number, shortId, priority, slug: normalizeSlug(params.title), title: params.title,
-                    featureId: params.featureId,
+                    featureId,
                     status: params.status ?? "draft",
                     discussedAt: "",
                     contextReady: false,
@@ -3097,11 +3437,14 @@ export default function planPiExtension(pi) {
                     openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                     createdAt: now, updatedAt: now,
                     handoff: "", handoffUpdatedAt: "",
+                    handoffReadAt: "",
+                    handoffHistory: [],
+                    statusLog: [],
                 };
                 await st.savePhase(phase);
                 // Atomic: serialize concurrent phase_create linking to the same feature.
                 await st.updateFeatures((doc) => {
-                    const feature = doc.features.find((f) => f.id === params.featureId);
+                    const feature = doc.features.find((f) => f.id === featureId);
                     if (feature && !feature.phaseIds.includes(phase.id)) {
                         feature.phaseIds.push(phase.id);
                         feature.updatedAt = now;
@@ -3112,7 +3455,8 @@ export default function planPiExtension(pi) {
             });
             if (!phase)
                 return { content: [{ type: "text", text: "Phase creation failed." }], details: {} };
-            return { content: [{ type: "text", text: `Phase created: ${phase.id}` }], details: phase };
+            const phaseCreateFeatures = (await st.loadFeatures()).features;
+            return { content: [{ type: "text", text: `✅ Phase created: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseCreateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
         },
     });
     pi.registerTool({
@@ -3120,7 +3464,7 @@ export default function planPiExtension(pi) {
         label: "Phase Update",
         description: "Update one or more fields of a phase. Only provided fields are changed. Supports re-linking to a feature via featureId. IMPORTANT: phase status is derived from task statuses, so do not update phase.status directly unless truly necessary.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID" }),
+            phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title" }),
             title: Type.Optional(Type.String({ description: "New title" })),
             status: Type.Optional(Type.String({ description: "New status: draft|discovery|planned|in-progress|done|blocked|canceled. Avoid setting this directly unless you truly need an override: phase status is derived from task statuses." })),
             summary: Type.Optional(Type.String({ description: "New summary" })),
@@ -3147,14 +3491,20 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedPhase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
+            if (!resolvedPhase)
+                return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
+            const phaseId = resolvedPhase.id;
             let phase;
             try {
-                phase = await st.loadPhase(params.phaseId);
+                phase = await st.loadPhase(phaseId);
             }
             catch {
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
             }
             const prevFeatureId = phase.featureId;
+            let nextFeatureIdForUpdate = prevFeatureId;
             if (params.title !== undefined) {
                 phase.title = params.title;
                 phase.slug = normalizeSlug(params.title);
@@ -3184,14 +3534,22 @@ export default function planPiExtension(pi) {
             if (params.completionCriteria !== undefined)
                 phase.completionCriteria = params.completionCriteria;
             if (params.featureId !== undefined) {
-                const nextFeatureId = params.featureId === "" ? undefined : params.featureId;
-                phase.featureId = nextFeatureId;
-                if (nextFeatureId !== prevFeatureId) {
+                if (params.featureId === "") {
+                    nextFeatureIdForUpdate = undefined;
+                }
+                else {
+                    const resolvedFeature = resolveFeatureRefStrict(features, params.featureId);
+                    if (!resolvedFeature.ok)
+                        return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+                    nextFeatureIdForUpdate = resolvedFeature.feature.id;
+                }
+                phase.featureId = nextFeatureIdForUpdate;
+                if (nextFeatureIdForUpdate !== prevFeatureId) {
                     await st.updateFeatures((doc) => {
                         for (const f of doc.features) {
                             if (f.id === prevFeatureId)
                                 f.phaseIds = f.phaseIds.filter((pid) => pid !== phase.id);
-                            if (f.id === nextFeatureId && !f.phaseIds.includes(phase.id))
+                            if (f.id === nextFeatureIdForUpdate && !f.phaseIds.includes(phase.id))
                                 f.phaseIds.push(phase.id);
                         }
                         return doc;
@@ -3201,7 +3559,8 @@ export default function planPiExtension(pi) {
             phase.updatedAt = nowISO();
             await st.savePhase(phase);
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Phase updated: ${phase.id} (${phase.status})` }], details: phase };
+            const phaseUpdateFeatures = (await st.loadFeatures()).features;
+            return { content: [{ type: "text", text: `✅ Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseUpdateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
         },
     });
     pi.registerTool({
@@ -3209,25 +3568,30 @@ export default function planPiExtension(pi) {
         label: "Phase Delete",
         description: "Delete a phase. Its tasks are deleted with it (cascade). Unlinks the phase from its feature.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID to delete" }),
+            phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title to delete" }),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedPhase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
+            if (!resolvedPhase)
+                return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
+            const phaseId = resolvedPhase.id;
             let phase;
             try {
-                phase = await st.loadPhase(params.phaseId);
+                phase = await st.loadPhase(phaseId);
             }
             catch {
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
             }
-            await st.deletePhase(params.phaseId);
+            await st.deletePhase(phaseId);
             if (phase.featureId) {
                 await st.updateFeatures((doc) => {
                     const feature = doc.features.find((f) => f.id === phase.featureId);
                     if (feature) {
-                        feature.phaseIds = feature.phaseIds.filter((pid) => pid !== params.phaseId);
+                        feature.phaseIds = feature.phaseIds.filter((pid) => pid !== phaseId);
                         feature.updatedAt = nowISO();
                     }
                     return doc;
@@ -3241,42 +3605,64 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "task_list",
         label: "Task List",
-        description: "List tasks of a phase with id, status, and title.",
+        description: "List tasks (compact: F00x/P00x/T00x · shortId — title (status)). Filters: featureRef, phaseRef, status. Omit all to list every task. Cheap discovery — do NOT read .planner/ files or plan_get full=true.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID" }),
+            featureRef: Type.Optional(Type.String({})),
+            phaseRef: Type.Optional(Type.String({})),
+            status: Type.Optional(Type.String({ description: "Optional: filter by status name" })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            let phase;
-            try {
-                phase = await st.loadPhase(params.phaseId);
+            const features = (await st.loadFeatures()).features;
+            let phases = await st.loadAllPhases();
+            const fref = params.featureRef?.trim();
+            if (fref) {
+                const f = features.find((x) => formatFeatureRef(x.number) === fref || x.shortId === fref || x.id === fref || x.name.toLowerCase() === fref.toLowerCase());
+                if (!f)
+                    return { content: [{ type: "text", text: `Feature not found: ${fref}` }], details: {} };
+                phases = phases.filter((p) => p.featureId === f.id);
             }
-            catch {
-                return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
+            const pref = params.phaseRef?.trim();
+            if (pref) {
+                const p = findPhaseByRef(phases, features, pref);
+                if (!p)
+                    return { content: [{ type: "text", text: `Phase not found: ${pref}` }], details: {} };
+                phases = [p];
             }
-            const summary = phase.tasks.map((t) => `- ${statusIcon(t.status)} ${t.id} — ${t.title}`).join("\n");
-            return { content: [{ type: "text", text: summary || "No tasks" }], details: { tasks: phase.tasks } };
+            const out = [];
+            for (const phase of phases) {
+                for (const task of phase.tasks) {
+                    if (params.status && task.status !== params.status)
+                        continue;
+                    out.push(`- ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${pad(task.number)}${task.shortId ? ` · ${task.shortId}` : ""} — ${task.title} (${task.status})`);
+                }
+            }
+            return { content: [{ type: "text", text: out.join("\n") || "No tasks" }], details: {} };
         },
     });
     pi.registerTool({
         name: "task_get",
         label: "Task Get",
-        description: "Read full details of a single task.",
+        description: "Show a task. Compact identity by default (saves tokens); pass full=true to include the description + statusLog.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
+            full: Type.Optional(Type.Boolean({ description: "If true, include the task description + statusLog. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const phases = await st.loadAllPhases();
-            const phase = phases.find((p) => p.tasks.some((t) => t.id === params.taskId));
-            const task = phase?.tasks.find((t) => t.id === params.taskId);
-            if (!task || !phase)
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            return { content: [{ type: "text", text: `${statusIcon(task.status)} ${task.title} (${task.id}) — phase ${phase.id}` }], details: { task, phaseId: phase.id } };
+            const summary = `${found.task.title} — ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}${found.task.shortId ? ` · ${found.task.shortId}` : ""} (${found.task.status})`;
+            if (!params.full)
+                return { content: [{ type: "text", text: summary }], details: {} };
+            const log = (found.task.statusLog ?? []).map((e) => `  - ${e.date.slice(0, 10)} ${e.title}`).join("\n");
+            return { content: [{ type: "text", text: `${summary}\n\n${found.task.description || ""}${log ? `\n\nStatus log:\n${log}` : ""}` }], details: {} };
         },
     });
     pi.registerTool({
@@ -3284,32 +3670,52 @@ export default function planPiExtension(pi) {
         label: "Task Create",
         description: "Add a task to a phase with a RICH description. REQUIRED: description must include code references (file:line), what already exists vs what needs to be built, specific structs/traits/systems to modify, concrete implementation steps, and edge cases to handle. The description is the execution context for agents; one-liners cause misalignment. Status defaults to planned.",
         parameters: Type.Object({
+            featureId: Type.String({ description: "Feature ID the phase belongs to (required)" }),
             phaseId: Type.String({ description: "Phase ID the task belongs to" }),
             title: Type.String({ description: "Task title" }),
             description: Type.String({ description: "REQUIRED — execution context: code references (file:line), current state vs desired state, structs/traits to modify, concrete implementation steps, edge cases. Not a one-liner. Prefix with 'design-only' for pre-implementation design tasks.", minLength: 50 }),
             status: Type.Optional(Type.String({ description: "Initial status. Default: planned" })),
             shortName: Type.Optional(Type.String({ description: "Short slug for the task id. Auto-derived from title if omitted." })),
+            checklist: Type.Optional(Type.Array(Type.String(), { description: "Initial checklist items (plain strings). Seeded as C1, C2, … (unchecked)." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            // Verify phase exists first (fast-fail before generating an id).
-            try {
-                await st.loadPhase(params.phaseId);
-            }
-            catch {
+            if (!params.featureId?.trim())
+                return { content: [{ type: "text", text: "featureId is required: a task must belong to a feature." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedFeature = resolveFeatureRefStrict(features, params.featureId.trim());
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const featureValidation = await validateResolvedTarget("feature", resolvedFeature.feature.id, () => st.loadFeatures().then((doc) => doc.features.find((f) => f.id === resolvedFeature.feature.id)).catch(() => undefined));
+            if (!featureValidation.ok)
+                return { content: [{ type: "text", text: featureValidation.error }], details: {} };
+            const feature = resolvedFeature.feature;
+            const existingFeature = features.find((f) => f.id === feature.id);
+            if (!existingFeature)
+                return { content: [{ type: "text", text: `Resolved feature ${feature.id} no longer exists. Refusing to create task.` }], details: {} };
+            // Resolve the phase ref (accepts F00x/P00x, bare P00x, shortId, UUID, title).
+            const resolvedPhase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
+            if (!resolvedPhase)
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
-            }
+            if (resolvedPhase.featureId !== feature.id)
+                return { content: [{ type: "text", text: `Phase ${formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features))} does not belong to feature ${formatFeatureRef(feature.number)}. Refusing to create task.` }], details: {} };
+            const phaseId = resolvedPhase.id;
+            const phaseValidation = await validateResolvedTarget("phase", phaseId, () => st.loadPhase(phaseId).catch(() => undefined));
+            if (!phaseValidation.ok)
+                return { content: [{ type: "text", text: phaseValidation.error }], details: {} };
+            const existingPhase = await st.loadPhase(phaseId);
+            if (!existingPhase)
+                return { content: [{ type: "text", text: `Resolved phase ${phaseId} no longer exists. Refusing to create task.` }], details: {} };
             const shortName = clampSlug(params.shortName ?? params.title, 30, `task-${Date.now().toString(36)}`); // clamp+strip trailing dash; never empty
             const taskId = createTaskId();
             const shortId = createShortId(await st.assignedShortIds());
-            const priority = await st.nextPriority("task", params.phaseId);
+            const priority = await st.nextPriority("task", phaseId);
             const now = nowISO();
             const initialStatus = params.status ?? "planned";
-            const existingPhase = await st.loadPhase(params.phaseId);
             const task = {
-                id: taskId, phaseId: params.phaseId, number: existingPhase.tasks.length + 1, shortId, priority, shortName,
+                id: taskId, phaseId, number: await st.allocTaskNumber(), shortId, priority, shortName,
                 title: params.title,
                 status: initialStatus,
                 description: params.description ?? "",
@@ -3317,7 +3723,10 @@ export default function planPiExtension(pi) {
                 statusLog: [],
                 decisions: [],
                 acceptedDecisions: [],
-                checklist: [], subtasks: [],
+                checklist: params.checklist
+                    ? params.checklist.map((itemTitle, index) => ({ number: index + 1, id: createChecklistItemId(taskId, index + 1, itemTitle), title: itemTitle, checked: false }))
+                    : [],
+                subtasks: [],
                 dependsOn: [],
                 startedAt: initialStatus === "in-progress" || initialStatus === "done" ? now : "",
                 completedAt: initialStatus === "done" ? now : "",
@@ -3325,14 +3734,15 @@ export default function planPiExtension(pi) {
             };
             // Atomic read-modify-write on the phase file: serializes concurrent
             // task_create calls on the SAME phaseId (batch) so tasks don't get lost.
-            await st.updatePhase(params.phaseId, (phase) => {
+            await st.updatePhase(phaseId, (phase) => {
                 phase.tasks.push(task);
                 phase.taskIds.push(taskId);
                 phase.updatedAt = now;
                 return phase;
             });
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Task created: ${taskId}` }], details: task };
+            const taskRef = `${formatPhaseRef(resolvedPhase.number, feature.number)}/T${String(task.number).padStart(3, "0")}`;
+            return { content: [{ type: "text", text: `Task created: ${taskRef} — ${task.title}${task.shortId ? ` · ${task.shortId}` : ""}` }], details: task };
         },
     });
     pi.registerTool({
@@ -3340,7 +3750,7 @@ export default function planPiExtension(pi) {
         label: "Task Update",
         description: "Update one or more fields of a task. Only provided fields are changed. Do NOT use this tool to start or complete work; use task_start and task_complete for lifecycle transitions so startedAt/completedAt stay correct.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
             title: Type.Optional(Type.String({ description: "New title" })),
             status: Type.Optional(Type.String({ description: "New status: planned|in-progress|done|blocked|canceled|rejected|deferred|waiting" })),
             description: Type.Optional(Type.String({ description: "New description" })),
@@ -3363,15 +3773,16 @@ export default function planPiExtension(pi) {
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             // Find the phase hosting this task first.
-            const allPhases = await st.loadAllPhases();
-            const hostPhase = allPhases.find((p) => p.tasks.some((t) => t.id === params.taskId));
-            if (!hostPhase)
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            const hostPhase = found.phase;
             const now = nowISO();
             let updatedTask;
             try {
                 const updatedPhase = await st.updatePhase(hostPhase.id, (phase) => {
-                    const task = phase.tasks.find((t) => t.id === params.taskId);
+                    const task = phase.tasks.find((t) => t.id === found.task.id);
                     if (!task)
                         return phase;
                     if (params.title !== undefined)
@@ -3387,7 +3798,7 @@ export default function planPiExtension(pi) {
                     if (params.acceptedDecisions !== undefined)
                         task.acceptedDecisions = params.acceptedDecisions;
                     if (params.checklist !== undefined) {
-                        task.checklist = params.checklist.map((itemTitle, index) => ({
+                        task.checklist = params.checklist.map((itemTitle, index) => ({ number: index + 1,
                             id: createChecklistItemId(task.id, index + 1, itemTitle),
                             title: itemTitle,
                             checked: false,
@@ -3428,19 +3839,19 @@ export default function planPiExtension(pi) {
         label: "Task Delete",
         description: "Delete a task from its phase.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID to delete" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to delete" }),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const phases = await st.loadAllPhases();
-            const hostPhase = phases.find((p) => p.tasks.some((t) => t.id === params.taskId));
-            if (!hostPhase)
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            await st.updatePhase(hostPhase.id, (phase) => {
-                phase.tasks = phase.tasks.filter((t) => t.id !== params.taskId);
-                phase.taskIds = phase.taskIds.filter((id) => id !== params.taskId);
+            await st.updatePhase(found.phase.id, (phase) => {
+                phase.tasks = phase.tasks.filter((t) => t.id !== found.task.id);
+                phase.taskIds = phase.taskIds.filter((id) => id !== found.task.id);
                 phase.updatedAt = nowISO();
                 return phase;
             });
@@ -3454,25 +3865,25 @@ export default function planPiExtension(pi) {
         label: "Task Start",
         description: "Set a task to in-progress. Use this BEFORE starting implementation work on any task. Sets startedAt timestamp automatically.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID to start" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to start" }),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const phases = await st.loadAllPhases();
-            const hostPhase = phases.find((p) => p.tasks.some((t) => t.id === params.taskId));
-            const task = hostPhase?.tasks.find((t) => t.id === params.taskId);
-            if (!task || !hostPhase)
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            const task = found.task;
             if (task.status === "in-progress")
                 return { content: [{ type: "text", text: `Task ${task.id} is already in-progress.` }], details: task };
             if (task.status === "done")
                 return { content: [{ type: "text", text: `Task ${task.id} is done. Use task_update to reopen.` }], details: task };
             const now = nowISO();
             let startedTask;
-            await st.updatePhase(hostPhase.id, (phase) => {
-                const t = phase.tasks.find((x) => x.id === params.taskId);
+            await st.updatePhase(found.phase.id, (phase) => {
+                const t = phase.tasks.find((x) => x.id === found.task.id);
                 if (!t)
                     return phase;
                 applyTaskLifecycleDates(t, "in-progress", now);
@@ -3484,7 +3895,9 @@ export default function planPiExtension(pi) {
             await st.writeGenerated();
             if (!startedTask)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            return { content: [{ type: "text", text: `✅ Task started: ${startedTask.id} — ${startedTask.title} (in-progress)` }], details: startedTask };
+            const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
+            const phaseContext = buildPhaseContextBlock(found.phase, parentFeature);
+            return { content: [{ type: "text", text: `✅ Task started: ${startedTask.id} — ${startedTask.title} (in-progress)${phaseContext}` }], details: startedTask };
         },
     });
     pi.registerTool({
@@ -3492,7 +3905,7 @@ export default function planPiExtension(pi) {
         label: "Task Complete",
         description: "Mark a task as done. Sets completedAt and startedAt (if missing) automatically. Checks for unchecked checklist items and warns unless force=true.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID to complete" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to complete" }),
             force: Type.Optional(Type.Boolean({ description: "Skip checklist completion check. Default: false" })),
             description_update: Type.Optional(Type.String({ description: "Post-hoc summary: commit hash(s), files touched, decisions made, updated code references with new line numbers. Keeps the planner alive and traceable." })),
         }),
@@ -3500,11 +3913,11 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const phases = await st.loadAllPhases();
-            const hostPhase = phases.find((p) => p.tasks.some((t) => t.id === params.taskId));
-            const task = hostPhase?.tasks.find((t) => t.id === params.taskId);
-            if (!task || !hostPhase)
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            const task = found.task;
             if (task.status === "done")
                 return { content: [{ type: "text", text: `Task ${task.id} is already done.` }], details: task };
             const unchecked = task.checklist.filter((item) => !item.checked);
@@ -3516,8 +3929,8 @@ export default function planPiExtension(pi) {
             }
             const now = nowISO();
             let completedTask;
-            await st.updatePhase(hostPhase.id, (phase) => {
-                const t = phase.tasks.find((x) => x.id === params.taskId);
+            await st.updatePhase(found.phase.id, (phase) => {
+                const t = phase.tasks.find((x) => x.id === found.task.id);
                 if (!t)
                     return phase;
                 applyTaskLifecycleDates(t, "done", now);
@@ -3536,6 +3949,125 @@ export default function planPiExtension(pi) {
             return { content: [{ type: "text", text: `✅ Task completed: ${completedTask.id} — ${completedTask.title} (done)` }], details: completedTask };
         },
     });
+    pi.registerTool({
+        name: "task_checklist_toggle",
+        label: "Task Checklist Toggle",
+        description: "Tick/untick a task checklist item (a 'step') without rewriting the whole list. Accepts the item as C{n} (e.g. C2), item id, or title (case-insensitive, first match). Pass checked=true/false to set explicitly, or omit to toggle. Use this instead of writing DONE in step titles. Items are numbered C1/C2… per task.",
+        parameters: Type.Object({
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
+            item: Type.String({ description: "Checklist item selector: C{n} (e.g. C2), item id, or title (case-insensitive)" }),
+            checked: Type.Optional(Type.Boolean({ description: "Set explicitly: true=done, false=open. Omit to toggle." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, params.taskId.trim());
+            if (!found)
+                return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            let result = "";
+            await st.updatePhase(found.phase.id, (phase) => {
+                const task = phase.tasks.find((t) => t.id === found.task.id);
+                if (!task) {
+                    result = `Task not found: ${params.taskId}`;
+                    return phase;
+                }
+                const ck = task.checklist ?? [];
+                if (ck.length === 0) {
+                    result = `Task "${found.task.title}" has no checklist.`;
+                    return phase;
+                }
+                const target = toggleChecklistItem(ck, params.item, params.checked);
+                if (!target) {
+                    result = `No checklist item matching "${params.item}".`;
+                    return phase;
+                }
+                task.updatedAt = nowISO();
+                phase.updatedAt = nowISO();
+                const doneCount = ck.filter((i) => i.checked).length;
+                result = `C${target.number} "${target.title}" → ${target.checked ? "done" : "open"} (${doneCount}/${ck.length} checked)`;
+                return phase;
+            });
+            await st.writeGenerated();
+            return { content: [{ type: "text", text: `✅ ${result}` }], details: {} };
+        },
+    });
+    pi.registerTool({
+        name: "task_checklist_add",
+        label: "Task Checklist Add",
+        description: "Add a single checklist item (a 'step') to a task without rewriting the list. The new item is appended as C{n} (next progressive number, stable id, unchecked). Use this to subdivide a task into smaller steps INSTEAD of spawning sub-tasks — the checklist keeps description, notes, statusLog and steps concentrated in one task (sub-tasks disperse context). Also use for granular adds instead of replacing the whole checklist via task_update.",
+        parameters: Type.Object({
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
+            title: Type.String({ description: "Checklist item text (a single step)" }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, params.taskId.trim());
+            if (!found)
+                return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            let result = "";
+            await st.updatePhase(found.phase.id, (phase) => {
+                const task = phase.tasks.find((t) => t.id === found.task.id);
+                if (!task) {
+                    result = `Task not found: ${params.taskId}`;
+                    return phase;
+                }
+                const ck = task.checklist ?? [];
+                const item = addChecklistItem(ck, task.id, params.title);
+                ck.push(item);
+                task.checklist = ck;
+                task.updatedAt = nowISO();
+                phase.updatedAt = nowISO();
+                result = `Added C${item.number} "${item.title}" (${ck.length} items)`;
+                return phase;
+            });
+            await st.writeGenerated();
+            return { content: [{ type: "text", text: `✅ ${result}` }], details: {} };
+        },
+    });
+    pi.registerTool({
+        name: "task_checklist_remove",
+        label: "Task Checklist Remove",
+        description: "Remove a single checklist item (a 'step') from a task by C{n} (e.g. C2), item id, or title (case-insensitive). Remaining items are renumbered C1..Cn for readability; their stable ids are preserved. Use this for granular removes instead of replacing the whole checklist via task_update.",
+        parameters: Type.Object({
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
+            item: Type.String({ description: "Checklist item selector: C{n} (e.g. C2), item id, or title (case-insensitive)" }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, params.taskId.trim());
+            if (!found)
+                return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            let result = "";
+            await st.updatePhase(found.phase.id, (phase) => {
+                const task = phase.tasks.find((t) => t.id === found.task.id);
+                if (!task) {
+                    result = `Task not found: ${params.taskId}`;
+                    return phase;
+                }
+                const ck = task.checklist ?? [];
+                if (ck.length === 0) {
+                    result = `Task "${found.task.title}" has no checklist.`;
+                    return phase;
+                }
+                const removed = removeChecklistItem(ck, params.item);
+                if (!removed) {
+                    result = `No checklist item matching "${params.item}".`;
+                    return phase;
+                }
+                task.updatedAt = nowISO();
+                phase.updatedAt = nowISO();
+                result = `Removed C${removed.number} "${removed.title}" (${ck.length} items left)`;
+                return phase;
+            });
+            await st.writeGenerated();
+            return { content: [{ type: "text", text: `✅ ${result}` }], details: {} };
+        },
+    });
     // ── Web lifecycle tools (agent-callable; parity with @agent-plan/mcp planner-web) ──
     // These let the agent manage the web dashboard directly, without relying
     // on the /planner slash command (which is not intercepted when the planner
@@ -3632,6 +4164,7 @@ export default function planPiExtension(pi) {
             // add seconds of latency on every turn if run unconditionally.
             if (!plannerHeavyInitDone) {
                 await migrateToUuids(st);
+                await migrateToGlobalSequence(st).catch(() => null);
                 await st.ensureShortIdsAndPriority().catch(() => null);
                 await ensureProjectLanguagePreferences(st).catch(() => null);
                 await maybeHealStatuses(st, ctx);
@@ -3664,8 +4197,9 @@ export default function planPiExtension(pi) {
             const profile = await st.loadCodebaseProfile();
             const resume = await st.loadResume().catch(() => null) ?? await st.refreshResume();
             const activity = await st.loadActivityLog();
-            const recentActivity = activity.entries.slice(-8).reverse();
+            const recentActivity = activity.entries.slice(-3).reverse();
             const handoffs = await st.listHandoffs();
+            const featureById = new Map(plan.features.features.map((feature) => [feature.id, feature]));
             const phaseById = new Map(plan.phases.map((phase) => [phase.id, phase]));
             const orderedPhases = [
                 ...plan.features.features.flatMap((feature) => {
@@ -3678,21 +4212,9 @@ export default function planPiExtension(pi) {
                 ...plan.phases.filter((phase) => !phase.featureId)
                     .sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
             ];
-            const phaseLines = orderedPhases
-                .map((p) => `- ${statusIcon(p.status)} \`${p.id}\` — ${phaseLabel(p)} (${p.status})`)
-                .join("\n");
-            const active = orderedPhases
-                .filter((p) => p.status === "in-progress")
-                .map((p) => `\`${p.id}\``)
-                .join(", ");
-            const doneFeaturesCount = plan.features.features.filter((f) => f.status === "done").length;
-            const activeFeaturesCount = plan.features.features.filter((f) => f.status === "in-progress").length;
-            const donePhasesCount = plan.phases.filter((p) => p.status === "done").length;
-            const activePhasesCount = plan.phases.filter((p) => p.status === "in-progress" || p.status === "discovery").length;
-            const totalTasksCount = orderedPhases.reduce((total, phase) => total + phase.tasks.length, 0);
-            const doneTasksCount = orderedPhases.reduce((total, phase) => total + phase.tasks.filter((task) => task.status === "done").length, 0);
-            const activeTasksCount = orderedPhases.reduce((total, phase) => total + phase.tasks.filter((task) => task.status === "in-progress").length, 0);
-            const hasActiveWork = activeFeaturesCount > 0 || activePhasesCount > 0 || activeTasksCount > 0;
+            const hasActiveWork = plan.features.features.some((feature) => feature.status === "in-progress")
+                || plan.phases.some((phase) => phase.status === "in-progress" || phase.status === "discovery")
+                || orderedPhases.some((phase) => phase.tasks.some((task) => task.status === "in-progress"));
             const currentPhase = hasActiveWork
                 ? orderedPhases.find((phase) => phase.id === resume.currentPhaseId && (phase.status === "in-progress" || phase.tasks.some((task) => resume.inProgressTaskIds.includes(task.id))))
                     ?? orderedPhases.find((phase) => phase.tasks.some((task) => resume.inProgressTaskIds.includes(task.id)))
@@ -3709,16 +4231,51 @@ export default function planPiExtension(pi) {
                     ?? null)
                 : null;
             const currentFeature = hasActiveWork && currentPhase?.featureId
-                ? plan.features.features.find((feature) => feature.id === currentPhase.featureId) ?? null
+                ? featureById.get(currentPhase.featureId) ?? null
                 : hasActiveWork
                     ? plan.features.features.find((feature) => feature.status === "in-progress") ?? null
                     : null;
-            const nextActivity = hasActiveWork
-                ? (resume.nextSteps[0]
-                    ?? (currentTask ? `Resume task ${currentTask.id} — ${taskLabel(currentTask)}` : currentPhase ? `Resume phase ${currentPhase.id} — ${phaseLabel(currentPhase)}` : "Resume the active work stream"))
-                : (handoffs.length > 0
-                    ? "Read the most recent phase handoff (handoff show <ref>), validate it against current plan ordering and dependencies, then pick the next task."
-                    : "Review the current plan and choose the next task.");
+            const currentFeatureRef = currentFeature ? formatFeatureRef(currentFeature.number) : "";
+            const currentPhaseRef = currentPhase ? formatPhaseRef(currentPhase.number, currentFeature?.number) : "";
+            const currentTaskRef = currentTask && currentPhase
+                ? `${formatPhaseRef(currentPhase.number, currentFeature?.number)}/T${pad(currentTask.number)}`
+                : "";
+            const phaseStatusOrder = ["draft", "discovery", "planned", "in-progress", "blocked", "done", "canceled"];
+            const phaseStatusCounts = new Map(phaseStatusOrder.map((status) => [status, 0]));
+            for (const phase of plan.phases) {
+                phaseStatusCounts.set(phase.status, (phaseStatusCounts.get(phase.status) ?? 0) + 1);
+            }
+            const phaseCountsSummary = phaseStatusOrder
+                .map((status) => `${status}=${phaseStatusCounts.get(status) ?? 0}`)
+                .join(" ");
+            const activeTaskMap = new Map();
+            for (const phase of orderedPhases) {
+                const featureNumber = phase.featureId ? featureById.get(phase.featureId)?.number : undefined;
+                for (const task of phase.tasks) {
+                    if (!resume.inProgressTaskIds.includes(task.id) && task.status !== "in-progress")
+                        continue;
+                    activeTaskMap.set(task.id, { phase, task, featureNumber });
+                }
+            }
+            const inProgressTaskLines = [...activeTaskMap.values()]
+                .sort((left, right) => left.task.number - right.task.number || left.task.createdAt.localeCompare(right.task.createdAt))
+                .map(({ phase, task, featureNumber }) => `${formatPhaseRef(phase.number, featureNumber)}/T${pad(task.number)} — ${task.title}`);
+            const otherActiveOrBlockedPhases = orderedPhases
+                .filter((phase) => phase.id !== currentPhase?.id && (phase.status === "in-progress" || phase.status === "discovery" || phase.status === "blocked"))
+                .slice(0, 6)
+                .map((phase) => {
+                const featureNumber = phase.featureId ? featureById.get(phase.featureId)?.number : undefined;
+                return `${statusIcon(phase.status)} ${formatPhaseRef(phase.number, featureNumber)} — ${phase.title} (${phase.status})`;
+            });
+            const openQuestions = plan.phases
+                .flatMap((phase) => phase.openQuestions.map((question) => `[${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}] ${question}`))
+                .slice(0, 8);
+            const acceptedDecisions = [
+                ...project.acceptedDecisions.map((decision) => `[project] ${decision.title}`),
+                ...plan.features.features.flatMap((feature) => feature.acceptedDecisions.map((decision) => `[feature ${formatFeatureRef(feature.number)}] ${decision.title}`)),
+                ...plan.phases.flatMap((phase) => phase.acceptedDecisions.map((decision) => `[phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}] ${decision.title}`)),
+                ...plan.phases.flatMap((phase) => phase.tasks.flatMap((task) => task.acceptedDecisions.map((decision) => `[task ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}/T${pad(task.number)}] ${decision.title}`))),
+            ].slice(0, 20);
             const webServer = server;
             const webLocalUrl = webServer?.localUrl ?? webServer?.url ?? "";
             const webLanUrl = webServer?.lanUrl ?? "";
@@ -3731,15 +4288,6 @@ export default function planPiExtension(pi) {
             catch { }
             const webUrl = webLocalUrl;
             const webUrlFull = webLanUrl ? `${webLocalUrl} (LAN: ${webLanUrl})` : webLocalUrl;
-            const openQuestions = plan.phases
-                .flatMap((p) => p.openQuestions.map((q) => `[${p.id}] ${q}`))
-                .slice(0, 12);
-            const acceptedDecisions = [
-                ...project.acceptedDecisions.map((d) => `[project] ${d.title}`),
-                ...plan.features.features.flatMap((f) => f.acceptedDecisions.map((d) => `[feature ${f.id}] ${d.title}`)),
-                ...plan.phases.flatMap((p) => p.acceptedDecisions.map((d) => `[phase ${p.id}] ${d.title}`)),
-                ...plan.phases.flatMap((p) => p.tasks.flatMap((t) => t.acceptedDecisions.map((d) => `[task ${t.id}] ${d.title}`))),
-            ].slice(0, 20);
             const pkgSummary = profile?.packageJson
                 ? `name=${profile.packageJson.name ?? "?"} pm=${profile.packageJson.packageManager ?? "npm"} scripts=${Object.keys(profile.packageJson.scripts).join(",") || "none"} deps=${Object.keys(profile.packageJson.dependencies).length} devDeps=${Object.keys(profile.packageJson.devDependencies).length}`
                 : "(no package.json)";
@@ -3761,96 +4309,62 @@ export default function planPiExtension(pi) {
             // Build/refresh the context block (slow path: cache miss).
             const contextBlock = [
                 `[Plan Context — ${project.name}]`,
-                // ── Web UI status (prominent — agent must surface URL in its summary) ──
                 webUrl ? `🌐 WEB UI RUNNING: ${webUrlFull}${webPort ? ` (port ${webPort})` : ""}. Include this address+port at the end of your resume summary.` : `Web UI: not running. Start it with '/planner web start'.`,
                 "",
-                // ── MANDATORY OPERATIONAL PROTOCOL (top priority, non-negotiable) ──
+                "Operational rules:",
+                "- Handoffs are context, not locks. Read the relevant handoff with handoff show <ref> before resuming.",
+                "- BEFORE any code edit/write: task_start. AFTER finishing a task: task_complete.",
+                "- Use task_update with motivation for blocked/canceled/rejected/deferred/waiting/planned(from non-planned).",
+                "- Planner ops (status/handoff/planner metadata) are NOT code edits; they are always allowed.",
+                "- Prefer shortId or F00x/P00x/T00x refs. Find via feature_list / phase_list / task_list; read one entity via *_get(full=true).",
+                "- If edit/write guard blocks you, start the right task or use an explicit bypass.",
                 "",
-                "═══════════════════════════════════════════════════════════════",
-                "MANDATORY OPERATIONAL PROTOCOL (violation = execution failure):",
-                "═══════════════════════════════════════════════════════════════",
-                "1. HANDOFF HYGIENE: If one or more phases have a pending handoff (entity-scoped, phase.handoff), present the list, read the relevant one with handoff show <ref>, then CLEAR it with handoff clear <ref> once consumed. Handoffs are non-blocking context artifacts, not locks — they never block task_start.",
-                "2. TASK LIFECYCLE: BEFORE coding ANY file: call task_start. AFTER finishing work on ANY task: call task_complete. No exceptions. No 'I'll do it later'. NOTE: Planner operations (plan_write_handoff / /planner handoff, task_start, task_complete, task_update, status reads) are NOT code edits. They are ALWAYS allowed regardless of task state — you may write/refresh the handoff even when no task is in-progress (e.g., all tasks done, or capturing state mid-flight). Never refuse to write a handoff because 'no task is open'; that is incorrect.",
-                "3. IMMEDIATE SYNC: Update task status AT THE EXACT MOMENT of transition. Start = task_start NOW. Done = task_complete NOW. Blocked = task_update with motivation NOW. Never batch status updates.",
-                "4. BLOCKED MOTIVATION: Transitions to blocked/canceled/rejected/deferred/waiting/planned(from non-planned) MUST include a detailed 'motivation' parameter. Write it as if the next person has zero context.",
-                "5. NO SHORTCUTS: If a tool blocks you, follow the protocol. Bypasses are for emergencies only, not for convenience.",
-                "6. ENTITY REFERENCES: When you mention a feature/phase/task in chat, use its composite ID (F00x / P00x / T00x, e.g. T003(P002/F001)) or its 5-char shortId (e.g. UUXD1) — NEVER a raw UUID like bd6ed366. Tool responses already show these refs (compositeRef, shortId); reuse them.",
-                "═══════════════════════════════════════════════════════════════",
-                "",
-                // ── Project details ──
                 `Goal: ${project.goal || "(not set)"}`,
                 project.description ? `Description: ${project.description}` : "",
                 `Stack: ${[...project.technologies, ...project.tools].join(", ") || "(not set)"}`,
                 `Codebase: ${pkgSummary} | dirs=${profile?.directories.join(",") || "none"} | scanned=${profile?.scannedAt ?? "never"}`,
                 `Ambient: ${ambientSummary}`,
                 "",
-                "Global rules (re-read before every phase/task start):",
-                project.globalRules.length ? project.globalRules.map((r) => `- ${r}`).join("\n") : "- (none)",
-                "",
-                "Workflow rules:",
-                `  before phase start: ${project.workflowRules.beforePhaseStart.join(" | ") || "(none)"}`,
-                `  before task start: ${project.workflowRules.beforeTaskStart.join(" | ") || "(none)"}`,
-                `  after phase complete: ${project.workflowRules.afterPhaseComplete.join(" | ") || "(none)"}`,
+                "Global rules:",
+                project.globalRules.length ? project.globalRules.map((rule) => `- ${rule}`).join("\n") : "- (none)",
                 "",
+                `Workflow: before phase=${project.workflowRules.beforePhaseStart.join(" | ") || "(none)"}; before task=${project.workflowRules.beforeTaskStart.join(" | ") || "(none)"}; after phase=${project.workflowRules.afterPhaseComplete.join(" | ") || "(none)"}`,
                 `Scope: ${project.scope.join(", ") || "(none)"}`,
                 `Out of scope: ${project.outOfScope.join(", ") || "(none)"}`,
                 "",
                 acceptedDecisions.length ? "Accepted decisions (do not re-litigate):" : "",
-                ...acceptedDecisions.map((d) => `- ${d}`),
+                ...acceptedDecisions.map((decision) => `- ${decision}`),
                 openQuestions.length ? "" : "",
                 openQuestions.length ? "Open questions:" : "",
-                ...openQuestions.map((q) => `- ${q}`),
+                ...openQuestions.map((question) => `- ${question}`),
                 "",
-                "Resume focus (where we are now):",
-                resume.currentPhaseId ? `  current phase: ${resume.currentPhaseId}` : "  current phase: (none)",
-                resume.inProgressTaskIds.length ? `  in-progress tasks: ${resume.inProgressTaskIds.join(", ")}` : "  in-progress tasks: (none)",
+                "Resume focus (stale/fallback pointer — may not match the phase you actually worked on in this session):",
+                currentFeatureRef ? `  current feature pointer: ${currentFeatureRef} — ${currentFeature?.name}` : "  current feature pointer: (none)",
+                currentPhaseRef ? `  current phase pointer: ${currentPhaseRef} — ${currentPhase?.title}` : "  current phase pointer: (none)",
+                currentTaskRef ? `  current task pointer: ${currentTaskRef} — ${currentTask?.title}` : "  current task pointer: (none)",
+                inProgressTaskLines.length ? `  in-progress tasks: ${inProgressTaskLines.join("; ")}` : "  in-progress tasks: (none)",
                 resume.blockers.length ? `  blockers: ${resume.blockers.join("; ")}` : "  blockers: (none)",
-                resume.nextSteps.length ? `  next steps: ${resume.nextSteps.join("; ")}` : "  next steps: (none)",
-                resume.lastSessionSummary ? `  last session: ${resume.lastSessionSummary}` : "",
+                handoffs.length === 0 && resume.nextSteps.length
+                    ? `  next step: ${resume.nextSteps[0]}${resume.nextStepsUpdatedAt ? ` (updated ${resume.nextStepsUpdatedAt})` : ""}`
+                    : "",
+                "",
+                "CRITICAL: The 'Resume focus' pointers above are persisted across sessions. They are NOT necessarily the phase you worked on right now. When asked to write a handoff, use the phase the user explicitly identifies as the one just completed in this session, not a stale pointer.",
                 "",
-                recentActivity.length ? "Recent activity (most recent first):" : "",
-                ...recentActivity.map((e) => `- ${e.at} [${e.type}] ${e.ref}: ${e.summary}`),
+                "Phase overview:",
+                `  counts: ${phaseCountsSummary}`,
+                currentPhaseRef ? `  current: ${currentPhaseRef} — ${currentPhase?.title} (${currentPhase?.status})` : "  current: (none)",
+                otherActiveOrBlockedPhases.length ? "  other active/blocked:" : "  other active/blocked: (none)",
+                ...otherActiveOrBlockedPhases.map((line) => `  - ${line}`),
                 "",
-                `${plan.phases.length} phases defined.`,
-                "Current phases:",
-                phaseLines || "  _none_",
-                active ? `Active: ${active}` : "",
+                recentActivity.length ? "Recent activity:" : "",
+                ...recentActivity.map((entry) => `- ${entry.at} [${entry.type}] ${entry.ref}: ${entry.summary}`),
                 "",
-                "Primary command UX:",
-                "- Use `/planner <TAB>` for grouped subcommand suggestions.",
-                "- Use `/planner` with no args to open the navigable planner menu.",
-                "- Feature commands: planner feature list|add|show|update|delete.",
-                "- Phase commands: planner phase add|show|discuss|update|delete.",
-                "- Task commands: planner task add|show|discuss|update|delete|start|complete.",
-                "- Handoff commands: planner handoff prepare|show|write|clear.",
-                "- Web/session commands: planner web start|stop|status, planner export|export-full, planner load, planner disable, planner repair.",
-                "Legacy flat aliases may also exist for backward compatibility, but prefer grouped `/planner ...` forms.",
-                "Planner discuss mode is Agent Plan only: ignore GSD workflows/skills/commands unless the user explicitly asks for GSD.",
-                `Language preferences: plan content=${project.contentLanguage || "(not set)"}; chat=${project.chatLanguage || "(not set)"}.`,
-                "If these language preferences are already set, follow them automatically and do NOT ask again in later sessions.",
-                "Ask for language only if BOTH preferences are unset.",
-                "If one preference is set and the other is unset, infer the missing one from the saved value and persist it immediately with project_set_language_preferences without asking the user again.",
-                "Persist accepted decisions into project data, not only chat. Use acceptedDecisions on project/feature/phase/task when the user accepts a decision or solution.",
-                "If you are creating a planner from an existing plan or document, do NOT leave project title, project description, project goal, or top-level requirements empty when the source material provides them.",
-                "When deriving a project title from an existing document, prefer a concise human project title; if the candidate title is long or compound, ask the user to confirm before using it.",
-                "Before starting any phase/task, emit a recap of current state and ask the user if requirements/dependencies changed before planning tasks.",
+                handoffs.length > 0 ? "Pending phase handoffs (entity-scoped; may be on a stale phase — validate before treating as current focus):" : "",
+                ...handoffs.map((handoff, index) => `  [${index + 1}] ${handoff.compositeRef} — ${handoff.updatedAt} — "${handoff.firstLine}"`),
+                handoffs.length > 0 ? "Use handoff show <ref> for context. A pending handoff is a candidate to validate; do not default to it as the current focus unless it matches the phase you actually worked on in this session." : "",
                 "",
-                "TASK STATUS RULES (strict — do not skip):",
-                "- BEFORE you start implementation work on ANY task, you MUST call task_start to set it to in-progress. This sets startedAt.",
-                "- AFTER you finish implementation work on ANY task, you MUST call task_complete to set it to done. This sets completedAt.",
-                "- Phase and feature statuses are DERIVED from task statuses. They are not the primary source of truth.",
-                "- Therefore, if not strictly necessary, do NOT change phase.status or feature.status directly. Move the task statuses instead and let rollup derive the parent statuses.",
-                "- The extension blocks edit/write when no task is in-progress (bash stays free so git pull/build/test work). If you hit that block, either call task_start, OR ask the user to authorize a one-time bypass (they can run /planner bypass, or you can call plan_authorize_bypass) and then retry.",
-                "- If you forget these task status calls, the derived rollup breaks: phase/feature can stay stale, the dashboard shows wrong active work, and resume focus is wrong.",
-                "- Before your final answer after implementation work, either call task_complete if the task is finished, or explicitly tell the user the task remains in-progress.",
-                "- Use task_complete with force=true only if you have a good reason to skip the checklist check.",
-                "- To reopen a completed task, use task_start (recommended) or task_update.",
-                handoffs.length > 0 ? `Pending phase handoffs (${handoffs.length}):` : "",
-                ...handoffs.map((h, i) => `  [${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`),
-                handoffs.length > 0 ? "Read the relevant one with handoff show <ref> (or /planner handoff show <ref>) as previous-session context, but validate it against the current planner state, ordering, and dependencies before treating any target as the next task." : "",
-                handoffs.length > 0 ? "If planner state shows no task/phase in-progress, do NOT present a handoff target as the current focus; present it only as a candidate to validate." : "",
-                handoffs.length > 0 ? "Once a handoff is fully consumed and work is safely resumed, clear it with handoff clear <ref> (or /planner handoff clear)." : "",
-                "Plan tools available: project_set_language_preferences, plan_init, project_update, requirement_list, requirement_create, requirement_update, requirement_delete, plan_get, feature_list, feature_get, feature_create, feature_update, feature_delete, phase_list, phase_get, phase_create, phase_update, phase_delete, task_list, task_get, task_create, task_update, task_delete, task_start, task_complete, plan_render, plan_get_handoff, plan_write_handoff, plan_delete_handoff, handoff_list, handoff_show, handoff_write, handoff_clear, plan_authorize_bypass, plan_clear_bypass",
+                `Language: content=${project.contentLanguage || "(not set)"}; chat=${project.chatLanguage || "(not set)"}`,
+                "Planner discuss mode is Agent Plan only: ignore GSD workflows unless the user explicitly asks for GSD.",
             ].filter(Boolean).join("\n");
             contextBlockCache = contextBlock;
             contextBlockDirty = false;