@agent-plan/pi-adapter 0.2.19-next.9 → 0.2.19

package/dist/index.js

@@ -9,8 +9,8 @@
  *  - inject context into prompts
  */
 import { Type } from "typebox";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, 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, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask } from "@agent-plan/core";
+import { createChecklistItemId, createFeatureId, createPhaseId, 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,11 +126,14 @@ 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)" },
-    { value: "handoff write", label: "handoff write [P00x]", description: "Write a phase handoff (default: in-progress phase)" },
-    { value: "handoff clear", label: "handoff clear [P00x]", description: "Clear a phase handoff (default: in-progress phase)" },
+    { value: "handoff show", label: "handoff show [P00x]", description: "Show a phase handoff (phase ref required)" },
+    { value: "handoff write", label: "handoff write [P00x]", description: "Write a phase handoff after confirmation (phase ref required)" },
+    { value: "handoff clear", label: "handoff clear [P00x]", description: "Archive a phase handoff (phase ref required)" },
     { value: "web start", label: "web start", description: "Start the web UI" },
     { value: "web stop", label: "web stop", description: "Stop the web UI" },
     { value: "web status", label: "web status", description: "Show web UI status" },
@@ -139,6 +144,12 @@ const PLANNER_COMMAND_COMPLETIONS = [
     { value: "load", label: "load", description: "Enable planner + start web UI (LAN) and show resume summary" },
     { value: "stop", label: "stop", description: "Disable planner and shut down the web UI" },
 ];
+/** A completed nested command followed by a space is now receiving free-form
+ * arguments (entity refs, titles, etc.), not another command completion. */
+function hasPlannerCommandArgument(prefix) {
+    const normalized = prefix.trimStart().toLowerCase();
+    return PLANNER_COMMAND_COMPLETIONS.some((item) => normalized.startsWith(`${item.value.toLowerCase()} `));
+}
 // ─── Helpers ────────────────────────────────────────────────────────────
 function nowISO() {
     return new Date().toISOString();
@@ -196,7 +207,7 @@ async function maybeHealStatuses(st, ctx) {
 function normalizeLanguagePref(value) {
     return value?.trim() ?? "";
 }
-async function ensureProjectLanguagePreferences(st) {
+async function ensureProjectLanguagePreferences(st, persist = true) {
     const project = await st.loadProject();
     const contentLanguage = normalizeLanguagePref(project.contentLanguage);
     const chatLanguage = normalizeLanguagePref(project.chatLanguage);
@@ -204,7 +215,8 @@ async function ensureProjectLanguagePreferences(st) {
         if (project.contentLanguage !== contentLanguage || project.chatLanguage !== chatLanguage) {
             project.contentLanguage = contentLanguage;
             project.chatLanguage = chatLanguage;
-            await st.saveProject(project);
+            if (persist)
+                await st.saveProject(project);
         }
         return project;
     }
@@ -212,7 +224,8 @@ async function ensureProjectLanguagePreferences(st) {
         const fallback = contentLanguage || chatLanguage;
         project.contentLanguage = contentLanguage || fallback;
         project.chatLanguage = chatLanguage || fallback;
-        await st.saveProject(project);
+        if (persist)
+            await st.saveProject(project);
         return project;
     }
     return project;
@@ -250,6 +263,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(),
@@ -263,7 +304,8 @@ async function buildHandoffMarkdown(st, reason, overrides) {
     const latestTaskUpdate = [...allTasks].sort((left, right) => right.task.updatedAt.localeCompare(left.task.updatedAt))[0] ?? null;
     const latestPhaseUpdate = [...plan.phases].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0] ?? null;
     const latestFeatureUpdate = [...plan.features.features].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0] ?? null;
-    const currentPhase = plan.phases.find((phase) => phase.id === resume.currentPhaseId)
+    const currentPhase = (overrides?.phaseId ? plan.phases.find((phase) => phase.id === overrides.phaseId) : undefined)
+        ?? plan.phases.find((phase) => phase.id === resume.currentPhaseId)
         ?? plan.phases.find((phase) => phase.tasks.some((task) => resume.inProgressTaskIds.includes(task.id)))
         ?? plan.phases.find((phase) => phase.status === "in-progress")
         ?? nonTerminalTasks[0]?.phase
@@ -352,8 +394,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 +421,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 +458,7 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ...recentActivityLines,
         "",
         "## Reminder",
-        "- This handoff is KEPT until a task in this phase starts (then auto-archived to .planner/handoff-archive/) or the phase completes. No need to clear it manually.",
+        "- This handoff remains active until every task in this phase is done/canceled, a newer handoff replaces it, or the user explicitly clears it. Reading or starting a task never clears it.",
     ].join("\n");
 }
 async function writeProjectHandoff(st, reason, overrides) {
@@ -620,6 +662,9 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
         return;
     const host = visibility === "lan" ? "0.0.0.0" : "127.0.0.1";
     const port = await pickProjectPort(ctx, requestedPort);
+    // A started server must be reflected in the next context block; the cache
+    // may hold a stale "Web UI: not running" block from a stop+prompt pair.
+    contextBlockDirty = true;
     try {
         server = await serve({
             port,
@@ -632,26 +677,26 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
         });
     }
     catch (e) {
-        // EADDRINUSE or other listen failure: retry on a random free port.
-        if (e instanceof Error && /EADDRINUSE|EACCES|EADDRNOTAVAIL/.test(e.message)) {
-            try {
-                server = await serve({
-                    port: 0,
-                    host,
-                    planRoot: resolvePlanRoot(ctx.cwd),
-                    staticDir: resolveStaticDir(),
-                    quiet: true,
-                    uiConfig: readUiConfig(ctx),
-                    isBusy: () => planBusy,
-                });
-                ctx.ui.notify(`Planner web server: port ${port} busy (another planner instance on this project?), started on ${server?.url ?? "?"} instead.`, "info");
-            }
-            catch (e2) {
-                ctx.ui.notify(`Failed to start web server (also retry failed): ${e2 instanceof Error ? e2.message : String(e2)}`, "error");
-            }
+        // Any listen failure at startup is potentially transient — EADDRINUSE from
+        // a racy port scan (another process grabbed the port between our check and
+        // bind), EMFILE/ENFILE under heavy load, EAGAIN, etc. Retry ONCE on a random
+        // free port (port 0) so a planner load never silently ends up with no server.
+        // serve() throws here only during startup binding/serving setup; if the retry
+        // also fails, surface the error to the user.
+        try {
+            server = await serve({
+                port: 0,
+                host,
+                planRoot: resolvePlanRoot(ctx.cwd),
+                staticDir: resolveStaticDir(),
+                quiet: true,
+                uiConfig: readUiConfig(ctx),
+                isBusy: () => planBusy,
+            });
+            ctx.ui.notify(`Planner web server: port ${port} unavailable (${e instanceof Error ? e.message : String(e)}), started on ${server?.url ?? "?"} instead.`, "info");
         }
-        else {
-            ctx.ui.notify(`Failed to start web server: ${e instanceof Error ? e.message : String(e)}`, "error");
+        catch (e2) {
+            ctx.ui.notify(`Failed to start web server (also retry failed): ${e2 instanceof Error ? e2.message : String(e2)}`, "error");
         }
     }
     if (server) {
@@ -684,12 +729,26 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
         catch { }
     }
 }
+function disablePlannerSession() {
+    plannerSessionEnabled = false;
+    startupResumePromptPending = false;
+    startupResumeSummaryPending = false;
+    startupResumeSummaryText = "";
+    if (startupResumeSummaryTimer)
+        clearTimeout(startupResumeSummaryTimer);
+    startupResumeSummaryTimer = null;
+    contextBlockCache = "";
+    contextBlockDirty = true;
+}
 async function stopServer() {
     if (server) {
         await server.close();
         server = null;
     }
     capturedPi?.appendEntry("plan-web-state", { running: false });
+    // The cached context block embeds the web UI address; after stop it must
+    // not keep claiming the dashboard is running (T241 — context invalidation).
+    contextBlockDirty = true;
 }
 // ─── Extension factory ──────────────────────────────────────────────────
 export default function planPiExtension(pi) {
@@ -708,6 +767,9 @@ export default function planPiExtension(pi) {
                     }
                     const argPrefix = match[2];
                     const prefix = argPrefix === undefined ? match[1] : argPrefix;
+                    if (argPrefix !== undefined && hasPlannerCommandArgument(argPrefix)) {
+                        return null;
+                    }
                     const normalized = (argPrefix ?? "").trimStart().toLowerCase();
                     const items = PLANNER_COMMAND_COMPLETIONS
                         .filter((item) => !normalized || item.value.startsWith(normalized))
@@ -747,9 +809,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");
@@ -760,8 +823,8 @@ 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.
+                    // Mark each handoff as read (recap presented). Do NOT clear — reading/load
+                    // is non-mutating; only phase completion, replacement, or explicit clear archives it.
                     for (const h of handoffs)
                         await st.markHandoffRead(h.phaseId).catch(() => { });
                 }
@@ -931,8 +994,45 @@ export default function planPiExtension(pi) {
     });
     // ── Commands ───────────────────────────────────────────────────────
     // ── Planner handler (reusable from multiple commands) ──────────
+    const plannerInteractionCancelled = Symbol("planner-interaction-cancelled");
+    /**
+     * Pi returns `undefined` when Escape closes an input/editor/select. Treat
+     * that as a transaction-wide cancellation, not as an omitted optional
+     * field: interactive planner commands must never keep prompting or write a
+     * partial edit after Escape.
+     */
+    function withCancellablePlannerUi(ctx) {
+        const cancellableCtx = Object.create(ctx);
+        const ui = new Proxy(ctx.ui, {
+            get(target, property, receiver) {
+                const member = Reflect.get(target, property, receiver);
+                if (typeof member !== "function")
+                    return member;
+                if (property === "input" || property === "editor" || property === "select") {
+                    return async (...args) => {
+                        const result = await member.apply(target, args);
+                        if (result === undefined || result === null)
+                            throw plannerInteractionCancelled;
+                        return result;
+                    };
+                }
+                return member.bind(target);
+            },
+        });
+        Object.defineProperty(cancellableCtx, "ui", { value: ui, enumerable: true });
+        return cancellableCtx;
+    }
     async function handlePlanner(args, ctx) {
-        await withPlanBusy(() => runPlanner(args, ctx));
+        try {
+            await withPlanBusy(() => runPlanner(args, withCancellablePlannerUi(ctx)));
+        }
+        catch (error) {
+            if (error === plannerInteractionCancelled) {
+                ctx.ui.notify("Cancelled — no changes saved.", "info");
+                return;
+            }
+            throw error;
+        }
     }
     async function runPlanner(args, ctx) {
         const parts = args.trim().split(/\s+/).filter(Boolean);
@@ -942,6 +1042,7 @@ export default function planPiExtension(pi) {
             "init",
             "show",
             "repair",
+            "cleanup-orphans",
             "project discuss",
             "project language",
             "feature list",
@@ -975,9 +1076,9 @@ 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" +
-            "Handoff actions: /planner handoff list | show [P00x] | write [P00x] | clear [P00x] | prepare";
+        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 (prepare proposes a target and asks for confirmation)";
         if (!a) {
             const action = await ctx.ui.select("Planner action", PLANNER_MENU_ACTIONS);
             if (!action) {
@@ -997,6 +1098,14 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const oldProject = await st.loadProject();
+                // Collect the replacement metadata before deleting the existing plan;
+                // Escape must leave the old project intact.
+                const name = await ctx.ui.input(`Project title [${oldProject.name}]`);
+                if (!name?.trim()) {
+                    ctx.ui.notify("Aborted", "warning");
+                    return;
+                }
+                const description = await ctx.ui.input(`Short project description [${oldProject.description || ""}]`);
                 ctx.ui.notify("Resetting project... all current plan data will be lost.", "warning");
                 if (server) {
                     ctx.ui.notify("Stopping active web server...", "info");
@@ -1004,12 +1113,6 @@ export default function planPiExtension(pi) {
                     server = null;
                 }
                 await rm(st.root, { recursive: true, force: true });
-                const name = await ctx.ui.input(`Project title [${oldProject.name}]`);
-                if (!name?.trim()) {
-                    ctx.ui.notify("Aborted", "warning");
-                    return;
-                }
-                const description = await ctx.ui.input(`Short project description [${oldProject.description || ""}]`);
                 await st.init(name.trim());
                 const project = await st.loadProject();
                 project.description = description?.trim() ?? oldProject.description;
@@ -1132,22 +1235,33 @@ export default function planPiExtension(pi) {
                 ?? features.find((feature) => feature.name.toLowerCase().includes(normalized))
                 ?? null;
         }
-        function findPhaseByRef(phases, ref) {
-            const normalized = ref.trim().toLowerCase();
-            if (!normalized)
-                return null;
-            const pMatch = normalized.match(/^p(\d+)$/);
-            if (pMatch) {
-                const n = parseInt(pMatch[1], 10);
-                const byNum = phases.find((p) => p.number === n);
-                if (byNum)
-                    return byNum;
-            }
-            return phases.find((phase) => phase.shortId && phase.shortId.toLowerCase() === normalized)
-                ?? phases.find((phase) => phase.id.toLowerCase() === normalized)
-                ?? phases.find((phase) => phase.title.toLowerCase() === normalized)
-                ?? phases.find((phase) => phase.title.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 profile_packageManager(pkg, lockfile) {
             if (pkg?.packageManager)
@@ -1162,7 +1276,7 @@ export default function planPiExtension(pi) {
                 return "npm";
             return "";
         }
-        async function scanCodebase() {
+        async function scanCodebase(persist = true) {
             const root = ctx.cwd;
             const rootFiles = [];
             const directories = [];
@@ -1244,7 +1358,8 @@ export default function planPiExtension(pi) {
                 tree,
                 ambient,
             };
-            await st.saveCodebaseProfile(profile);
+            if (persist)
+                await st.saveCodebaseProfile(profile);
             return profile;
         }
         // ═══════════════════════════════════════════════════════════════
@@ -1256,8 +1371,8 @@ export default function planPiExtension(pi) {
                 return;
             }
             if (b === "discuss") {
-                const project = await ensureProjectLanguagePreferences(st);
-                const profile = await scanCodebase();
+                const project = await ensureProjectLanguagePreferences(st, false);
+                const profile = await scanCodebase(false);
                 ctx.ui.notify(`Codebase scanned: ${profile.directories.length} dirs, ${profile.rootFiles.length} root files${profile.packageJson?.name ? `, pkg ${profile.packageJson.name}` : ""}.`, "info");
                 ctx.ui.notify("Opening text editors for the initial project profile. These will serve as the foundation for the agent's deep discovery process.", "info");
                 const goal = await ctx.ui.editor("Project goal: What is the main, single-focus objective of this project?", project.goal || "");
@@ -1284,6 +1399,7 @@ export default function planPiExtension(pi) {
                         : project.acceptedDecisions,
                 };
                 await st.saveProject(draftProject);
+                await st.saveCodebaseProfile(profile);
                 await st.writeGenerated();
                 ctx.ui.notify("Initial profile saved. The agent will now take over as Lead Architect to conduct discovery.", "info");
                 if (capturedPi) {
@@ -1321,7 +1437,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") {
@@ -1353,13 +1469,13 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const now = nowISO();
-                const featureNumber = await st.allocFeatureNumber();
-                const shortId = createShortId(await st.assignedShortIds());
+                const id = createFeatureId();
+                const identity = await st.allocateEntityIdentity("feature", id);
                 const priority = await st.nextPriority("feature");
                 const feature = {
-                    id: createFeatureId(),
-                    number: featureNumber,
-                    shortId,
+                    id,
+                    number: identity.number,
+                    shortId: identity.shortId,
                     priority,
                     name: nameInput.trim(),
                     description: description?.trim() ?? "",
@@ -1374,6 +1490,7 @@ export default function planPiExtension(pi) {
                     acceptedDecisions: [],
                     phaseIds: [],
                     dependsOn: [],
+                    statusLog: [],
                     createdAt: now,
                     updatedAt: now,
                 };
@@ -1411,6 +1528,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;
@@ -1509,7 +1664,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;
         }
         // ═══════════════════════════════════════════════════════════════
@@ -1536,23 +1691,27 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Phase creation cancelled: no feature selected.", "warning");
                     return;
                 }
+                // This belongs to the creation transaction: Escape before the phase
+                // is persisted cancels the whole command rather than creating a phase
+                // and only then abandoning the follow-up question.
+                const startDiscuss = await ctx.ui.input("Start phase discuss now? Type yes to continue");
                 let phase;
                 await withFeatureLock(feature.id, async () => {
                     const phases = await st.loadAllPhases();
                     const featurePhases = phases.filter((p) => p.featureId === feature.id);
-                    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());
+                    const identity = await st.allocateEntityIdentity("phase", id);
                     const priority = await st.nextPriority("phase", feature.id);
                     phase = {
-                        id, number, shortId, priority, slug, title, featureId: feature.id, status: "draft", discussedAt: "", contextReady: false, contextReadyReason: "", summary: "", description: "", notes: "",
+                        id, number: identity.number, shortId: identity.shortId, priority, slug, title, featureId: feature.id, status: "draft", discussedAt: "", contextReady: false, contextReadyReason: "", summary: "", description: "", notes: "",
                         goals: [], nonGoals: [], dependencies: [], dependsOn: [], risks: [],
                         openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                         createdAt: nowISO(), updatedAt: nowISO(),
                         handoff: "", handoffUpdatedAt: "",
                         handoffReadAt: "",
                         handoffHistory: [],
+                        statusLog: [],
                     };
                     await st.savePhase(phase);
                     await st.updateFeatures((doc) => {
@@ -1568,7 +1727,6 @@ export default function planPiExtension(pi) {
                 if (!phase)
                     return;
                 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);
                 }
@@ -1577,7 +1735,7 @@ export default function planPiExtension(pi) {
             if (b === "discuss") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = findPhaseByRef(await st.loadAllPhases(), subArgs.trim());
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1589,9 +1747,6 @@ export default function planPiExtension(pi) {
                 if (phase.status !== "draft" && phase.status !== "discovery" && phase.status !== "planned") {
                     ctx.ui.notify(`Phase is already "${phase.status}". Re-discuss works best on draft/discovery/planned phases.`, "info");
                 }
-                phase.status = "discovery";
-                phase.updatedAt = nowISO();
-                await st.savePhase(phase);
                 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();
@@ -1663,7 +1818,7 @@ export default function planPiExtension(pi) {
             if (b === "show") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1689,7 +1844,7 @@ export default function planPiExtension(pi) {
             if (b === "delete") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1711,7 +1866,7 @@ export default function planPiExtension(pi) {
             if (b === "update") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1768,7 +1923,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") {
@@ -1782,14 +1937,16 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Aborted", "warning");
                     return;
                 }
+                // Keep the optional follow-up inside the creation transaction so
+                // Escape can still cancel before a task is persisted.
+                const startDiscuss = await ctx.ui.input("Start task discuss now? Type yes to continue");
                 const shortName = clampSlug(title, 30, `task-${Date.now().toString(36)}`);
-                const taskNum = await st.allocTaskNumber();
                 const taskId = createTaskId();
-                const shortId = createShortId(await st.assignedShortIds());
+                const identity = await st.allocateEntityIdentity("task", taskId);
                 const priority = await st.nextPriority("task", phase.id);
                 const now = nowISO();
                 const task = {
-                    id: taskId, phaseId: phase.id, number: taskNum, shortId, priority, shortName,
+                    id: taskId, phaseId: phase.id, number: identity.number, shortId: identity.shortId, priority, shortName,
                     title: title.trim(), status: "planned",
                     description: "",
                     notes: "",
@@ -1807,7 +1964,6 @@ export default function planPiExtension(pi) {
                 await st.savePhase(phase);
                 await st.writeGenerated();
                 ctx.ui.notify(`Task created: ${taskId} — ${title}`, "info");
-                const startDiscuss = await ctx.ui.input("Start task discuss now? Type yes to continue");
                 if (isYes(startDiscuss)) {
                     await handlePlanner(`task discuss ${taskId}`, ctx);
                 }
@@ -1839,7 +1995,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,
@@ -1890,7 +2046,7 @@ export default function planPiExtension(pi) {
             if (b === "delete") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1924,7 +2080,7 @@ export default function planPiExtension(pi) {
             if (b === "update") {
                 let phase = null;
                 if (subArgs.trim()) {
-                    phase = await st.loadPhase(subArgs.trim()).catch(() => null);
+                    phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim()) ?? null;
                 }
                 if (!phase) {
                     phase = await pickPhase();
@@ -1966,6 +2122,7 @@ export default function planPiExtension(pi) {
                 task.updatedAt = now;
                 phase.updatedAt = now;
                 await st.savePhase(phase);
+                await st.syncTaskStatusRollup(phase.id);
                 await st.writeGenerated();
                 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;
@@ -1998,17 +2155,9 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
                     return;
                 }
-                // 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/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");
-                }
+                // A pending handoff is context, not a lock: task start RETAINS it.
+                // It is archived only when the phase completes (auto) or the user
+                // explicitly clears it.
                 const now = nowISO();
                 // Record status change in the incremental statusLog.
                 const prevStatus = task.status;
@@ -2025,6 +2174,7 @@ export default function planPiExtension(pi) {
                 task.updatedAt = now;
                 phase.updatedAt = now;
                 await st.savePhase(phase);
+                await st.syncTaskStatusRollup(phase.id);
                 await st.writeGenerated();
                 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;
@@ -2079,12 +2229,80 @@ export default function planPiExtension(pi) {
                 applyTaskLifecycleDates(task, "done", now);
                 task.updatedAt = now;
                 phase.updatedAt = now;
-                await st.savePhase(phase);
+                const clearedRef = await st.syncTaskStatusRollup(phase.id);
+                await st.writeGenerated();
+                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}` : ""}${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}`, "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(`✅ 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");
+                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) ──
@@ -2130,6 +2348,11 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("No text provided; nothing written.", "info");
                     return;
                 }
+                const confirmed = await ctx.ui.confirm(`Write this handoff on ${r.compositeRef}?`, "Write handoff");
+                if (!confirmed) {
+                    ctx.ui.notify("Handoff write cancelled.", "info");
+                    return;
+                }
                 await st.setPhaseHandoff(r.phase.id, text);
                 ctx.ui.notify(`Wrote handoff on ${r.compositeRef}`, "info");
                 return;
@@ -2139,22 +2362,17 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Agent bridge unavailable; use /planner handoff write for an auto-generated handoff.", "warning");
                     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" +
-                    "The handoff MUST be a structured markdown document containing at minimum:\n" +
+                await capturedPi.sendUserMessage("Prepare a canonical session handoff proposal. Do not write anything yet. First identify from this conversation and the latest planner lifecycle events the exact feature and phase where the decisions/work belong. Never use the first in-progress phase or a stale resume pointer as a target.\n\n" +
+                    "If the last phase was just completed, do not create an operational handoff for it; its existing handoff must have been archived by the phase-done lifecycle. If another non-done phase is the real continuation, identify that phase explicitly.\n\n" +
+                    "Before calling `handoff_write`, tell the user exactly: `I propose writing this handoff on P00x(F00x) — <phase title>. Confirm?` Wait for an explicit confirmation. Only after confirmation call `handoff_write` with that exact phaseRef. If the target is ambiguous, ask the user to identify the feature and phase instead of guessing.\n\n" +
+                    "After confirmation, the handoff MUST contain at minimum:\n" +
                     "- `Created at:` and `Updated at:` lines (ISO timestamps)\n" +
                     "- `Reason:` why this handoff is being written\n" +
-                    "- `## Current focus`: the current feature (id + name + status), phase (id + title + status) and task (id + title + status). Derive them from the plan data.\n" +
-                    "- `## What was being done`: a concrete 3–10 line narrative of the work in progress, based on our conversation and the current task notes/description.\n" +
-                    "- `## How to resume`: explicit, ordered steps to pick the work back up (next command / tool / file to open / build to run).\n" +
-                    "- `## Files touched`: explicit file paths modified during this session.\n" +
-                    "- `## Blockers`: any open blockers, or `None recorded`.\n" +
-                    "- `## Next steps`: the immediate next steps.\n" +
-                    "- `## Recent decisions`: accepted decisions made this session, if any.\n" +
-                    "- `## Reminder`: note that when the work is fully resumed, the agent should clear the phase handoff using `handoff_clear`.\n\n" +
-                    "The handoff is stored on the phase.handoff field of the current in-progress phase (entity-scoped). " +
-                    (handoffs.length > 0 ? "A previous phase handoff exists; refresh its `Updated at` and merge/replace stale sections. " : "") +
-                    "Once written, confirm to me with a one-line summary.");
+                    "- `## Current focus`: feature, phase and task refs/titles/statuses derived from the confirmed target\n" +
+                    "- `## What was being done`: the concrete decisions/work from this session\n" +
+                    "- `## How to resume`: explicit ordered steps\n" +
+                    "- `## Files touched`, `## Blockers`, `## Next steps`, and `## Recent decisions`\n" +
+                    "Pass a meaningful title beginning with the confirmed phase ref. Generic titles are rejected. Handoffs are stored on phase.handoff; `.planner/HANDOFF.md` is deprecated.");
                 ctx.ui.notify("Instructing the agent to prepare the phase handoff…", "info");
                 return;
             }
@@ -2223,7 +2441,26 @@ export default function planPiExtension(pi) {
             const m = report.migrated;
             const dup = report.integrity.duplicatePhaseIds.length;
             const dang = report.integrity.danglingPhaseIds.length;
-            ctx.ui.notify(`Repair done: renamed ${m.renamed}, repaired ${m.repaired} refs, inferred ${m.inferred}. Integrity: ${dup} duplicate, ${dang} dangling.`, "info");
+            ctx.ui.notify(`Repair done: renamed ${m.renamed}, repaired ${m.repaired} refs, inferred ${m.inferred}, archived ${report.handoffs.archived} stale handoff(s). 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 ──
@@ -2279,6 +2516,10 @@ export default function planPiExtension(pi) {
                 startupResumeSummaryPending = false;
                 startupResumeSummaryTimer = null;
             }, 60000);
+            // Safety timeout must not keep the Node process alive on its own
+            // (relevant for test hosts that load this entrypoint). Inside Pi the
+            // process is long-lived, so unref is a no-op there.
+            startupResumeSummaryTimer.unref?.();
             // Build the recap and embed it in the trigger content. The trigger
             // message is the channel that reliably reaches the agent on a triggered
             // turn (before_agent_start's systemPrompt injection is NOT applied to
@@ -2303,7 +2544,7 @@ export default function planPiExtension(pi) {
             return;
         }
         if (a === "stop" || a === "disable") {
-            plannerSessionEnabled = false;
+            disablePlannerSession();
             await stopServer().catch(() => { });
             try {
                 capturedPi?.appendEntry("plan-web-state", { running: false });
@@ -2319,6 +2560,11 @@ export default function planPiExtension(pi) {
         description: "Grouped planner command. Use /planner <TAB> for subcommands or /planner to open the menu.",
         getArgumentCompletions: (prefix) => {
             const normalized = prefix.trim().toLowerCase();
+            // Once a complete command path is followed by whitespace, the remaining
+            // text is a free-form human ref/title. Returning the fallback menu here
+            // lets Pi select `init` and replace input such as `feature update F001`.
+            if (hasPlannerCommandArgument(prefix))
+                return null;
             const filtered = PLANNER_COMMAND_COMPLETIONS.filter((item) => item.value.startsWith(normalized));
             return filtered.length > 0 ? filtered : PLANNER_COMMAND_COMPLETIONS;
         },
@@ -2595,7 +2841,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);
@@ -2621,6 +2867,7 @@ export default function planPiExtension(pi) {
                 `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.`,
+                `Handoffs: archived=${report.handoffs.archived} stale completed/canceled handoff(s).`,
                 `Integrity: duplicatePhaseIds=${report.integrity.duplicatePhaseIds.length}, danglingPhaseIds=${report.integrity.danglingPhaseIds.length}.`,
             ];
             if (report.integrity.danglingPhaseIds.length)
@@ -2630,6 +2877,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",
@@ -2649,9 +2928,12 @@ 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. phaseRef is required and must be the exact phase confirmed with the user; never infer a target from current status or resume pointers. Completed/canceled phases reject new handoffs.",
         parameters: Type.Object({
+            phaseRef: Type.String({ description: "Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title." }),
+            confirmed: Type.Boolean({ description: "Set true only after the user explicitly confirms the proposed feature+phase target." }),
             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({
@@ -2663,7 +2945,14 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const resolved = await resolvePhaseForHandoff(st, params.phaseRef);
+            if (!resolved.ok)
+                return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated (writes to phase.handoff, not .planner/HANDOFF.md). ${resolved.error}` }], details: { deprecated: true, error: resolved.error } };
+            if (!params.confirmed)
+                return { content: [{ type: "text", text: `Proposal only: I would write this handoff on ${resolved.compositeRef}. Ask the user to confirm this exact feature/phase, then retry with confirmed=true.` }], details: { deprecated: true, phaseRef: resolved.compositeRef, confirmationRequired: true } };
             const markdown = await buildHandoffMarkdown(st, params.reason?.trim() || "manual tool handoff", {
+                phaseId: resolved.phase.id,
+                ...(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
@@ -2674,23 +2963,20 @@ export default function planPiExtension(pi) {
                     }
                     : {}),
             });
-            const r = await resolvePhaseForHandoff(st, undefined);
-            if (!r.ok)
-                return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated (writes to phase.handoff, not .planner/HANDOFF.md). ${r.error}` }], details: { deprecated: true, error: r.error } };
-            await st.setPhaseHandoff(r.phase.id, markdown);
-            return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated — wrote handoff on ${r.compositeRef} (phase.handoff field) instead of .planner/HANDOFF.md. Prefer the handoff_write tool.` }], details: { deprecated: true, phaseRef: r.compositeRef, phaseId: r.phase.id } };
+            await st.setPhaseHandoff(resolved.phase.id, markdown);
+            return { content: [{ type: "text", text: `⚠️ plan_write_handoff is deprecated — wrote handoff on ${resolved.compositeRef} (phase.handoff field) instead of .planner/HANDOFF.md. Prefer the handoff_write tool.` }], details: { deprecated: true, phaseRef: resolved.compositeRef, phaseId: resolved.phase.id } };
         },
     });
     pi.registerTool({
         name: "plan_delete_handoff",
         label: "Plan Delete Handoff",
-        description: "DEPRECATED — clears the entity-scoped handoff of the current in-progress phase. Prefer handoff_clear.",
-        parameters: Type.Object({}),
-        async execute(_id, _params, _signal, _onUpdate, ctx) {
+        description: "DEPRECATED — clears/archives the entity-scoped handoff of a phase. phaseRef is required. Prefer handoff_clear.",
+        parameters: Type.Object({ phaseRef: Type.String({ description: "Exact phase ref: P00x | P00x(F00x) | UUID | title." }) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const r = await resolvePhaseForHandoff(st, undefined);
+            const r = await resolvePhaseForHandoff(st, params.phaseRef);
             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, "manual");
@@ -2698,8 +2984,8 @@ export default function planPiExtension(pi) {
         },
     });
     // 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.
+    // UUID | title. A write target is always explicit: never guess from the
+    // first in-progress phase or a stale resume pointer.
     async function resolvePhaseForHandoff(st, ref) {
         const phases = await st.loadAllPhases();
         const features = (await st.loadFeatures()).features;
@@ -2707,16 +2993,12 @@ export default function planPiExtension(pi) {
         if (ref && ref.trim()) {
             phase = findPhaseByRef(phases, features, ref.trim());
         }
-        else {
-            phase = phases.find((p) => p.status === "in-progress")
-                ?? phases.find((p) => p.tasks.some((t) => t.status === "in-progress"));
-        }
         if (!phase) {
             return {
                 ok: false,
                 error: ref && ref.trim()
                     ? `Phase not found: "${ref.trim()}". Use P00x, P00x(F00x), UUID, or title.`
-                    : "No in-progress phase. Specify a phaseRef (P00x or P00x(F00x)).",
+                    : "A phaseRef is required. First identify the exact feature and phase with the user, then pass P00x or P00x(F00x).",
             };
         }
         const feat = phase.featureId ? features.find((f) => f.id === phase.featureId) : undefined;
@@ -2741,8 +3023,8 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_show",
         label: "Handoff Show",
-        description: "Read the entity-scoped handoff of a phase. phaseRef accepts P00x, P00x(F00x), UUID, or title. Omit to target the current in-progress phase.",
-        parameters: Type.Object({ phaseRef: Type.Optional(Type.String({ description: "Phase ref: P00x | P00x(F00x) | UUID | title. Default: current in-progress phase." })) }),
+        description: "Read the entity-scoped handoff of a phase. phaseRef is required and accepts P00x, P00x(F00x), UUID, or title. Never infer a phase automatically.",
+        parameters: Type.Object({ phaseRef: Type.String({ description: "Exact phase ref: P00x | P00x(F00x) | UUID | title. Ask the user when the target is ambiguous." }) }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
@@ -2759,9 +3041,11 @@ 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. phaseRef is required and must be the exact phase selected with the user. Pass content (or markdown_content) AND a meaningful `title` summarizing the work (e.g. 'P049 — featureId validation: tests + adapter wiring'). Never guess the phase from in-progress status or stale context. Completed/canceled phases reject new handoffs.",
         parameters: Type.Object({
-            phaseRef: Type.Optional(Type.String({ description: "Phase ref. Default: current in-progress phase." })),
+            phaseRef: Type.String({ description: "Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title." }),
+            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'." })),
+            confirmed: Type.Boolean({ description: "Set true only after the user explicitly confirms the proposed feature+phase target." }),
             content: Type.Optional(Type.String({ description: "Handoff text (plain)." })),
             markdown_content: Type.Optional(Type.String({ description: "Handoff text (markdown). Preferred over content." })),
         }),
@@ -2769,12 +3053,38 @@ 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 } };
+            if (!params.confirmed) {
+                return { content: [{ type: "text", text: `Proposal only: I would write this handoff on ${r.compositeRef}. Ask the user to confirm this exact feature/phase, then retry with confirmed=true.` }], details: { phaseRef: r.compositeRef, confirmationRequired: true } };
+            }
             await st.setPhaseHandoff(r.phase.id, body);
             return { content: [{ type: "text", text: `✅ Wrote handoff on ${r.compositeRef}.` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
         },
@@ -2782,8 +3092,8 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_clear",
         label: "Handoff Clear",
-        description: "Clear the entity-scoped handoff of a phase (sets handoff to empty, keeps handoffUpdatedAt as an audit trail). phaseRef optional (default: current in-progress phase).",
-        parameters: Type.Object({ phaseRef: Type.Optional(Type.String({ description: "Phase ref. Default: current in-progress phase." })) }),
+        description: "Clear the entity-scoped handoff of a phase (archives it and keeps handoffUpdatedAt as an audit trail). phaseRef is required; never infer a phase automatically.",
+        parameters: Type.Object({ phaseRef: Type.String({ description: "Exact phase ref: P00x | P00x(F00x) | UUID | title." }) }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
@@ -2792,7 +3102,7 @@ export default function planPiExtension(pi) {
             if (!r.ok)
                 return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
             await st.clearPhaseHandoff(r.phase.id, "manual");
-            return { content: [{ type: "text", text: `✅ Cleared handoff on ${r.compositeRef} (handoffUpdatedAt preserved as audit; archived to .planner/handoff-archive/).` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
+            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({
@@ -2849,7 +3159,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "feature_get",
         label: "Feature Get",
-        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description.",
+        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description and derived linked requirements.",
         parameters: Type.Object({
             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." })),
@@ -2860,12 +3170,17 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const features = (await st.loadFeatures()).features;
             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: ${ref}` }], details: {} };
+            const resolvedFeature = resolveFeatureRefStrict(features, ref);
+            if (!resolvedFeature.ok)
+                return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
+            const feature = resolvedFeature.feature;
             const phases = (await st.loadAllPhases()).filter((p) => p.featureId === feature.id);
-            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: {} };
+            const linkedRequirements = await st.linkedRequirementsForFeature(feature.id);
+            const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases${linkedRequirements.length ? `; ${linkedRequirements.length} linked requirement${linkedRequirements.length === 1 ? "" : "s"}` : ""})`;
+            const requirementsBlock = linkedRequirements.length > 0
+                ? `\n\nLinked requirements:\n${linkedRequirements.map((requirement) => `- ${requirement.title} (${requirement.status})`).join("\n")}`
+                : "\n\nLinked requirements:\n- None linked to this feature.";
+            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${feature.description || ""}${requirementsBlock}` : summary }], details: { linkedRequirements } };
         },
     });
     pi.registerTool({
@@ -2884,12 +3199,13 @@ export default function planPiExtension(pi) {
             const now = nowISO();
             const status = params.status ?? "planned";
             const currentFeatures = (await st.loadFeatures()).features;
-            const shortId = createShortId(await st.assignedShortIds());
+            const id = createFeatureId();
+            const identity = await st.allocateEntityIdentity("feature", id);
             const priority = await st.nextPriority("feature");
             const feature = {
-                id: createFeatureId(),
-                number: await st.allocFeatureNumber(),
-                shortId,
+                id,
+                number: identity.number,
+                shortId: identity.shortId,
                 priority,
                 name: params.name,
                 description: params.description ?? "",
@@ -2904,6 +3220,7 @@ export default function planPiExtension(pi) {
                 acceptedDecisions: [],
                 phaseIds: [],
                 dependsOn: [],
+                statusLog: [],
                 createdAt: now,
                 updatedAt: now,
             };
@@ -2917,6 +3234,51 @@ export default function planPiExtension(pi) {
             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({
         name: "feature_update",
         label: "Feature Update",
@@ -2944,10 +3306,36 @@ 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;
+            const mutableFields = [
+                "name",
+                "description",
+                "status",
+                "startDate",
+                "endDate",
+                "workDone",
+                "workRemaining",
+                "priority",
+                "acceptedDecisions",
+            ];
+            const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+            if (receivedFields.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Not updated — no mutable fields were received. No planner data was changed. If you attempted a large description, it may have exceeded the tool payload limit.",
+                        }],
+                    details: { updated: false, reason: "no-mutable-fields" },
+                };
+            }
             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)
@@ -2985,11 +3373,17 @@ 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: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
+            return {
+                content: [{
+                        type: "text",
+                        text: `✅ Feature updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`,
+                    }],
+                details: { ...feature, updated: true, updatedFields: receivedFields },
+            };
         },
     });
     pi.registerTool({
@@ -3004,21 +3398,23 @@ 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 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;
                 }
@@ -3062,7 +3458,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "phase_get",
         label: "Phase Get",
-        description: "Show a phase. Compact identity by default (saves tokens); pass full=true to include the description.",
+        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 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." })),
@@ -3075,8 +3471,13 @@ export default function planPiExtension(pi) {
             const phase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
             if (!phase)
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
-            const summary = `${phase.title} — ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}${phase.shortId ? ` · ${phase.shortId}` : ""} (${phase.status}; ${phase.tasks.length} tasks)`;
-            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${phase.description || ""}` : summary }], details: {} };
+            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({
@@ -3096,18 +3497,26 @@ 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 = await st.allocPhaseNumber();
+            await withFeatureLock(featureId, async () => {
                 const id = createPhaseId();
-                const shortId = createShortId(await st.assignedShortIds());
-                const priority = await st.nextPriority("phase", params.featureId);
+                const identity = await st.allocateEntityIdentity("phase", id);
+                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,
+                    id, number: identity.number, shortId: identity.shortId, priority, slug: normalizeSlug(params.title), title: params.title,
+                    featureId,
                     status: params.status ?? "draft",
                     discussedAt: "",
                     contextReady: false,
@@ -3119,11 +3528,12 @@ export default function planPiExtension(pi) {
                     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;
@@ -3170,14 +3580,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);
@@ -3207,14 +3623,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;
@@ -3228,6 +3652,77 @@ export default function planPiExtension(pi) {
             return { content: [{ type: "text", text: `✅ Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseUpdateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
         },
     });
+    pi.registerTool({
+        name: "decision_record",
+        label: "Decision Record",
+        description: "Record a user-agreed decision on both a feature and one of its phases. This is planner metadata work, not a code edit. The decision is appended without overwriting existing history.",
+        parameters: Type.Object({
+            featureId: Type.String({ description: "Parent feature ref: F00x, shortId, UUID, or name" }),
+            phaseId: Type.String({ description: "Active phase ref: P00x, shortId, UUID, or title" }),
+            title: Type.String({ minLength: 1, description: "Short human-readable decision title" }),
+            decision: Type.String({ minLength: 1, description: "The agreed decision" }),
+            rationale: Type.String({ minLength: 1, description: "Why the decision was made" }),
+            implementationNotes: Type.String({ minLength: 1, description: "Concrete follow-up or preservation notes" }),
+        }),
+        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 resolvedPhase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId);
+            if (!resolvedPhase)
+                return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
+            if (resolvedPhase.featureId !== resolvedFeature.feature.id) {
+                return { content: [{ type: "text", text: `Phase ${formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features))} does not belong to feature ${formatFeatureRef(resolvedFeature.feature.number)}.` }], details: {} };
+            }
+            const acceptedAt = nowISO();
+            const acceptedDecision = {
+                id: crypto.randomUUID(),
+                title: params.title.trim(),
+                decision: params.decision.trim(),
+                rationale: params.rationale.trim(),
+                implementationNotes: params.implementationNotes.trim(),
+                acceptedAt,
+            };
+            await withFeatureLock(resolvedFeature.feature.id, async () => {
+                let featureWritten = false;
+                try {
+                    await st.updateFeatures((doc) => {
+                        const feature = doc.features.find((entry) => entry.id === resolvedFeature.feature.id);
+                        if (!feature)
+                            throw new Error(`Resolved feature no longer exists: ${resolvedFeature.feature.id}`);
+                        feature.acceptedDecisions = [...(feature.acceptedDecisions ?? []), acceptedDecision];
+                        feature.updatedAt = acceptedAt;
+                        return doc;
+                    });
+                    featureWritten = true;
+                    await st.updatePhase(resolvedPhase.id, (phase) => {
+                        phase.acceptedDecisions = [...(phase.acceptedDecisions ?? []), acceptedDecision];
+                        phase.updatedAt = acceptedAt;
+                        return phase;
+                    });
+                }
+                catch (error) {
+                    // Best-effort compensation keeps a failed dual-write from reporting
+                    // success with a decision persisted only on the feature.
+                    if (featureWritten) {
+                        await st.updateFeatures((doc) => {
+                            const feature = doc.features.find((entry) => entry.id === resolvedFeature.feature.id);
+                            if (feature)
+                                feature.acceptedDecisions = (feature.acceptedDecisions ?? []).filter((entry) => entry.id !== acceptedDecision.id);
+                            return doc;
+                        }).catch(() => { });
+                    }
+                    throw error;
+                }
+            });
+            await st.writeGenerated();
+            return { content: [{ type: "text", text: `✅ Decision recorded on ${formatFeatureRef(resolvedFeature.feature.number)} and ${formatPhaseRef(resolvedPhase.number, resolvedFeature.feature.number)}: ${acceptedDecision.title}` }], details: acceptedDecision };
+        },
+    });
     pi.registerTool({
         name: "phase_delete",
         label: "Phase Delete",
@@ -3239,19 +3734,24 @@ 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: {} };
             }
-            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;
@@ -3330,32 +3830,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 identity = await st.allocateEntityIdentity("task", taskId);
+            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: await st.allocTaskNumber(), shortId, priority, shortName,
+                id: taskId, phaseId, number: identity.number, shortId: identity.shortId, priority, shortName,
                 title: params.title,
                 status: initialStatus,
                 description: params.description ?? "",
@@ -3363,7 +3883,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 : "",
@@ -3371,14 +3894,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({
@@ -3409,15 +3933,29 @@ 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;
+            // Validate the motivation requirement for restrictive status transitions,
+            // mirroring the MCP adapter and the /planner task update command
+            // (AGENTS.md rule 8 — rejected writes must leave the files unchanged).
+            if (params.status !== undefined &&
+                params.status !== found.task.status &&
+                needsMotivation(found.task.status, params.status)) {
+                if (!params.motivation || !params.motivation.trim()) {
+                    return {
+                        content: [{ type: "text", text: `Status transition "${found.task.status} → ${params.status}" requires a motivation. Provide the "motivation" parameter with a detailed explanation of why this change is needed.` }],
+                        details: {},
+                    };
+                }
+            }
             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)
@@ -3433,7 +3971,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,
@@ -3465,6 +4003,7 @@ export default function planPiExtension(pi) {
             }
             if (!updatedTask)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
+            await st.syncTaskStatusRollup(found.phase.id);
             await st.writeGenerated();
             return { content: [{ type: "text", text: `Task updated: ${updatedTask.id} (${updatedTask.status})` }], details: updatedTask };
         },
@@ -3480,13 +4019,13 @@ 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));
-            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;
             });
@@ -3495,10 +4034,65 @@ export default function planPiExtension(pi) {
         },
     });
     // ── task start / complete tools ──────────────────────────────────
+    pi.registerTool({
+        name: "task_recommend",
+        label: "Task Recommend",
+        description: "Return the recommended next task without starting work: continue one active task, otherwise choose ready work by feature → phase → task priority. Reports approved deviation/resume context and never blocks an explicit user choice.",
+        parameters: Type.Object({}),
+        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, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
+            const result = recommendNextTask(features.features, phases, project.workDeviations);
+            if (!result.candidate)
+                return { content: [{ type: "text", text: `No task recommendation: ${result.reason}` }], details: result };
+            const { candidate } = result;
+            const reference = `${formatPhaseRef(candidate.phase.number, featureNumberOfPhase(candidate.phase, features.features))}/T${String(candidate.task.number).padStart(3, "0")}`;
+            return {
+                content: [{ type: "text", text: `Recommended (${result.kind}): ${reference} — ${candidate.task.title}\n${result.reason}${result.deviation ? `\nDeviation: ${result.deviation.id}; resume target ${result.deviation.resumeTaskId}.` : ""}` }],
+                details: result,
+            };
+        },
+    });
+    pi.registerTool({
+        name: "task_deviation",
+        label: "Task Deviation",
+        description: "Record a user-approved temporary task deviation. It preserves the recommended/resume task but never starts, pauses, or blocks work; use normal task lifecycle tools for those transitions.",
+        parameters: Type.Object({
+            temporary_task: Type.String({ description: "Temporary task ref" }),
+            resume_task: Type.Optional(Type.String({ description: "Task to resume; defaults to the current recommendation" })),
+            reason: Type.String({ description: "Why this approved temporary deviation is needed" }),
+        }),
+        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, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
+            const temporary = findTaskByRef(phases, features.features, params.temporary_task.trim());
+            if (!temporary)
+                return { content: [{ type: "text", text: `Task not found: ${params.temporary_task}` }], details: {} };
+            const selected = recommendNextTask(features.features, phases, project.workDeviations);
+            const resume = params.resume_task ? findTaskByRef(phases, features.features, params.resume_task.trim()) : selected.candidate;
+            if (!resume)
+                return { content: [{ type: "text", text: `No resume task is available. Provide resume_task explicitly. ${selected.reason}` }], details: selected };
+            if (temporary.task.id === resume.task.id)
+                return { content: [{ type: "text", text: "A temporary task must differ from its resume target." }], details: {} };
+            if (temporary.task.status !== "planned")
+                return { content: [{ type: "text", text: `Temporary task is not startable: ${temporary.task.status}.` }], details: {} };
+            const timestamp = nowISO();
+            const record = { id: crypto.randomUUID(), recommendedTaskId: selected.candidate?.task.id ?? resume.task.id, temporaryTaskId: temporary.task.id, resumeTaskId: resume.task.id, reason: params.reason, requestedBy: "user", approvedBy: "user", state: "approved", createdAt: timestamp, activatedAt: "", resolvedAt: "" };
+            await st.addWorkDeviation(record);
+            await st.writeGenerated();
+            const tempRef = `${formatPhaseRef(temporary.phase.number, featureNumberOfPhase(temporary.phase, features.features))}/T${String(temporary.task.number).padStart(3, "0")}`;
+            const resumeRef = `${formatPhaseRef(resume.phase.number, featureNumberOfPhase(resume.phase, features.features))}/T${String(resume.task.number).padStart(3, "0")}`;
+            return { content: [{ type: "text", text: `✅ Approved deviation: ${tempRef} temporarily overrides ${resumeRef}. Resume target retained.` }], details: { deviation: record } };
+        },
+    });
     pi.registerTool({
         name: "task_start",
         label: "Task Start",
-        description: "Set a task to in-progress. Use this BEFORE starting implementation work on any task. Sets startedAt timestamp automatically.",
+        description: "Set a task to in-progress. BEFORE calling, read feature_get(full=true) for the parent feature and its linked requirements, then phase_get(full=true) for the parent phase and its linked requirements, then task_get(full=true). Continue an already in-progress task; otherwise select ready work by feature → phase → task priority (lower number first), respecting dependencies and blocked/waiting states. Sets startedAt automatically and returns the ordered feature/phase requirements briefing.",
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to start" }),
         }),
@@ -3506,19 +4100,40 @@ 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 === "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 project = await st.loadProject();
+            const phases = await st.loadAllPhases();
+            const eligibility = checkExplicitTaskStart(features, phases, task.id, project.workDeviations);
+            if (!eligibility.eligible)
+                return { content: [{ type: "text", text: `Task start denied: ${eligibility.reason}` }], details: eligibility };
+            const selection = recommendNextTask(features, phases, project.workDeviations);
+            // Assemble the mandatory parent context before changing task lifecycle state.
+            // The output order is feature + its requirements, then phase + its requirements.
+            const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
+            const [phaseWithRequirements, featureRequirements] = await Promise.all([
+                st.loadPhaseWithRequirements(found.phase.id),
+                parentFeature ? st.linkedRequirementsForFeature(parentFeature.id) : Promise.resolve([]),
+            ]);
+            const phaseContext = buildPhaseContextBlock(phaseWithRequirements, parentFeature, phaseWithRequirements.linkedRequirements ?? [], featureRequirements);
+            const advisory = selection.kind === "conflict"
+                ? `\n\n⚠️ ${selection.reason} Explicit task request honored; reconcile active work before relying on automatic recommendations.`
+                : selection.candidate && selection.candidate.task.id !== task.id
+                    ? selection.kind === "active"
+                        ? `\n\n⚠️ Active-task advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} is already in progress. Explicit task request honored.`
+                        : `\n\n⚠️ Priority advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} is the automatic recommendation. Explicit task request honored.`
+                    : "";
             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);
@@ -3527,10 +4142,14 @@ export default function planPiExtension(pi) {
                 startedTask = t;
                 return phase;
             });
+            await st.syncTaskStatusRollup(found.phase.id);
+            const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === task.id && deviation.state === "approved");
+            if (approvedDeviation)
+                await st.setWorkDeviationState(approvedDeviation.id, "active", now);
             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 };
+            return { content: [{ type: "text", text: `✅ Task started: ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${String(startedTask.number).padStart(3, "0")} — ${startedTask.title} (in-progress)${startedTask.shortId ? ` · ${startedTask.shortId}` : ""}${phaseContext}${advisory}` }], details: startedTask };
         },
     });
     pi.registerTool({
@@ -3546,11 +4165,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);
@@ -3562,8 +4181,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);
@@ -3576,10 +4195,135 @@ export default function planPiExtension(pi) {
                 completedTask = t;
                 return phase;
             });
+            const clearedRef = await st.syncTaskStatusRollup(found.phase.id);
+            const completedDeviation = (await st.loadProject()).workDeviations
+                .filter((deviation) => (deviation.state === "approved" || deviation.state === "active") && deviation.temporaryTaskId === task.id)
+                .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+            if (completedDeviation)
+                await st.setWorkDeviationState(completedDeviation.id, "resolved", now);
             await st.writeGenerated();
             if (!completedTask)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            return { content: [{ type: "text", text: `✅ Task completed: ${completedTask.id} — ${completedTask.title} (done)` }], details: completedTask };
+            return { content: [{ type: "text", text: `✅ Task completed: ${completedTask.id} — ${completedTask.title} (done)${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}` }], 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) ──
@@ -3656,7 +4400,7 @@ export default function planPiExtension(pi) {
         description: "Disable the planner for this project and stop the web dashboard. Alias: planner-disable. Planner operations are NOT code edits.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, _ctx) {
-            plannerSessionEnabled = false;
+            disablePlannerSession();
             await stopServer().catch(() => { });
             try {
                 capturedPi?.appendEntry("plan-web-state", { running: false });
@@ -3673,15 +4417,9 @@ export default function planPiExtension(pi) {
         if (!(await st.exists()))
             return;
         try {
-            // Heavy one-time-per-session init: migration, language prefs, status
-            // healing, and a fresh resume. These write/scan the whole plan and would
-            // add seconds of latency on every turn if run unconditionally.
+            // Session initialization must not mutate canonical planner entities.
+            // Migrations/backfills/repairs are explicit tools; resume is `.local`.
             if (!plannerHeavyInitDone) {
-                await migrateToUuids(st);
-                await migrateToGlobalSequence(st).catch(() => null);
-                await st.ensureShortIdsAndPriority().catch(() => null);
-                await ensureProjectLanguagePreferences(st).catch(() => null);
-                await maybeHealStatuses(st, ctx);
                 await st.refreshResume();
                 plannerHeavyInitDone = true;
             }
@@ -3711,8 +4449,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) => {
@@ -3725,21 +4464,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)))
@@ -3756,16 +4483,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 = 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. (Legacy resume.json nextSteps may be stale — the handoff is authoritative.)"
-                : hasActiveWork
-                    ? (resume.nextSteps[0]
-                        ?? (currentTask ? `Resume task ${currentTask.id} — ${taskLabel(currentTask)}` : currentPhase ? `Resume phase ${currentPhase.id} — ${phaseLabel(currentPhase)}` : "Resume the active work stream"))
-                    : "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 ?? "";
@@ -3778,15 +4540,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)";
@@ -3808,96 +4561,63 @@ 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) ──
-                "",
-                "═══════════════════════════════════════════════════════════════",
-                "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> for context. Handoffs are KEPT until a task in the phase starts (auto-archived to .planner/handoff-archive/) or the phase completes — no manual clear needed. They 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 & FAST LOOKUP: Feature/Phase/Task numbers are GLOBALLY unique (one P003, one T007 in the whole plan) — bare P00x/T00x is a valid unambiguous ref. PREFER the 5-char shortId (e.g. UUXD1) or composite F00x/P00x/T00x in chat; NEVER a raw UUID. To FIND an entity: call feature_list / phase_list / task_list (compact, ~2K tokens for the whole plan) — do NOT read .planner/*.json files or plan_get full=true (~32K tokens) to locate an entity. To ACT: pass the ref directly to the action tool (task_start/complete/update/phase_update accept F00x/P00x/T00x, bare P00x/T00x, shortId, UUID, title). To read a description: call task_get / phase_get / feature_get with full=true for that ONE entity. Tool responses already show shortId + compositeRef; reuse them.",
-                "═══════════════════════════════════════════════════════════════",
+                "Operational rules:",
+                "- Handoffs are context, not locks. Read the relevant handoff with handoff show <ref> before resuming.",
+                "- BEFORE work: read feature_get(full=true) for the parent feature and its linked requirements, then phase_get(full=true) for the parent phase and its linked requirements, then task_get(full=true); only then call task_start before any code edit/write. AFTER finishing a task: task_complete.",
+                "- Record every new decision or user-agreed modification in both the relevant feature and phase before treating the discussion as 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.",
+                "- Prioritize work: continue an in-progress task; otherwise choose ready work feature → phase → task by ascending priority, respecting dependencies and blocked/waiting states. 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.",
                 "",
-                // ── 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("; ")}${handoffs.length > 0 ? " (⚠️ may be stale — handoff is authoritative)" : resume.nextStepsUpdatedAt ? ` (last updated ${resume.nextStepsUpdatedAt}, may be stale)` : ""}` : "  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 ? "Handoffs are KEPT until a task in the phase starts (auto-archived to .planner/handoff-archive/) or the phase completes — read with handoff show <ref> for context; no manual clear needed." : "",
-                "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;