@agent-plan/pi-adapter 0.2.19-next.1 → 0.2.19-next.11

package/dist/index.js

@@ -9,7 +9,7 @@
  *  - inject context into prompts
  */
 import { Type } from "typebox";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, withFeatureLock, needsMotivation, findPhaseByRef, buildRecap } from "@agent-plan/core";
+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 { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -68,6 +68,29 @@ setWriteNotifyHook(() => {
 let previousContextPercent = 0;
 let autoHandoffTriggered = false;
 let plannerSessionEnabled = false;
+// In-process guard bypass (per session, NOT persisted/shared). The edit/write
+// guard is advisory in Pi (warns "NO ACTIVE TASK" but does not block). When a
+// bypass is active the warning is silenced for the window. Lives in memory only:
+// not on disk, not in git, not shared across agents/sessions on the same folder.
+let guardBypassUntil = "";
+function authorizeGuardBypass(durationMinutes = 15) {
+    const until = new Date(Date.now() + durationMinutes * 60_000).toISOString();
+    guardBypassUntil = until;
+    return until;
+}
+function clearGuardBypass() { guardBypassUntil = ""; }
+function isGuardBypassed() {
+    if (!guardBypassUntil)
+        return false;
+    const until = Date.parse(guardBypassUntil);
+    if (!Number.isFinite(until))
+        return false;
+    if (until <= Date.now()) {
+        guardBypassUntil = "";
+        return false;
+    }
+    return true;
+}
 let startupResumePromptPending = false;
 let startupResumeSummaryPending = false;
 let plannerHeavyInitDone = false; // runs migrate/heal/refreshResume once per session, not every turn
@@ -393,7 +416,7 @@ async function buildHandoffMarkdown(st, reason, overrides) {
         ...recentActivityLines,
         "",
         "## Reminder",
-        "- When work is fully resumed and this handoff is no longer needed, clear the phase handoff with handoff clear <ref> (or /planner handoff clear).",
+        "- This handoff is KEPT until a task in this phase starts (then auto-archived to .planner/handoff-archive/) or the phase completes. No need to clear it manually.",
     ].join("\n");
 }
 async function writeProjectHandoff(st, reason, overrides) {
@@ -489,6 +512,9 @@ function statusIcon(status) {
     };
     return icons[status] ?? "❓";
 }
+function pad(n) {
+    return String(n).padStart(3, "0");
+}
 function applyTaskLifecycleDates(task, nextStatus, now) {
     const previousStatus = task.status;
     if (nextStatus === "in-progress" && !task.startedAt) {
@@ -734,6 +760,10 @@ export default function planPiExtension(pi) {
                 const handoffs = await st.listHandoffs().catch(() => []);
                 if (handoffs.length > 0) {
                     ctx.ui.notify(`ℹ️  ${handoffs.length} phase handoff(s) pending — review with /planner handoff list.`, "info");
+                    // Mark each handoff as read (recap presented). Do NOT clear — content is
+                    // kept until a task in the phase starts (auto-archived) or phase completes.
+                    for (const h of handoffs)
+                        await st.markHandoffRead(h.phaseId).catch(() => { });
                 }
             }
             // If the user declined enablement, skip EVERYTHING (no web prompt, no migration, no summary).
@@ -862,6 +892,8 @@ export default function planPiExtension(pi) {
             return; // nothing to enforce yet
         if (guard.inProgressTaskIds.length > 0)
             return; // a task is open → we're good
+        if (isGuardBypassed())
+            return; // user authorized proceeding without a task
         const focusHint = guard.focusTaskId
             ? `Il task più probabile è ${guard.focusTaskId} — ${guard.focusTaskTitle}. Avvialo con: \`/planner task start ${guard.focusTaskId}\``
             : `Scegli un task dal piano e avvialo con \`/planner task start <taskId>\`.`;
@@ -1117,19 +1149,6 @@ export default function planPiExtension(pi) {
                 ?? phases.find((phase) => phase.title.toLowerCase().includes(normalized))
                 ?? null;
         }
-        function findTaskByRef(phases, ref) {
-            const normalized = ref.trim().toLowerCase();
-            if (!normalized)
-                return null;
-            for (const phase of phases) {
-                const task = phase.tasks.find((entryTask) => entryTask.id.toLowerCase() === normalized
-                    || entryTask.title.toLowerCase() === normalized
-                    || entryTask.title.toLowerCase().includes(normalized));
-                if (task)
-                    return { phase, task };
-            }
-            return null;
-        }
         function profile_packageManager(pkg, lockfile) {
             if (pkg?.packageManager)
                 return pkg.packageManager;
@@ -1334,7 +1353,7 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const now = nowISO();
-                const featureNumber = (await st.loadFeatures()).features.length + 1;
+                const featureNumber = await st.allocFeatureNumber();
                 const shortId = createShortId(await st.assignedShortIds());
                 const priority = await st.nextPriority("feature");
                 const feature = {
@@ -1363,7 +1382,7 @@ export default function planPiExtension(pi) {
                     return doc;
                 });
                 await st.writeGenerated();
-                ctx.ui.notify(`Feature created: ${feature.id} — ${feature.name}`, "info");
+                ctx.ui.notify(`Feature created: ${formatFeatureRef(feature.number)}${feature.shortId ? ` +MI+ ${feature.shortId}` : ""} +EM+ ${feature.name}`, "info");
                 return;
             }
             if (b === "show") {
@@ -1444,7 +1463,7 @@ export default function planPiExtension(pi) {
                 });
                 feature = updatedDoc.features.find((entry) => entry.id === featureId) ?? feature;
                 await st.writeGenerated();
-                ctx.ui.notify(`Feature updated: ${feature.id} — ${feature.name} (${feature.status})`, "info");
+                ctx.ui.notify(`Feature updated: ${formatFeatureRef(feature.number)}${feature.shortId ? ` +MI+ ${feature.shortId}` : ""} +EM+ ${feature.name} (${feature.status})`, "info");
                 return;
             }
             if (b === "delete") {
@@ -1521,7 +1540,7 @@ export default function planPiExtension(pi) {
                 await withFeatureLock(feature.id, async () => {
                     const phases = await st.loadAllPhases();
                     const featurePhases = phases.filter((p) => p.featureId === feature.id);
-                    const number = featurePhases.reduce((max, p) => Math.max(max, p.number), 0) + 1;
+                    const number = await st.allocPhaseNumber();
                     const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
                     const id = createPhaseId();
                     const shortId = createShortId(await st.assignedShortIds());
@@ -1532,6 +1551,8 @@ export default function planPiExtension(pi) {
                         openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                         createdAt: nowISO(), updatedAt: nowISO(),
                         handoff: "", handoffUpdatedAt: "",
+                        handoffReadAt: "",
+                        handoffHistory: [],
                     };
                     await st.savePhase(phase);
                     await st.updateFeatures((doc) => {
@@ -1546,7 +1567,7 @@ export default function planPiExtension(pi) {
                 });
                 if (!phase)
                     return;
-                ctx.ui.notify(`Phase created: ${phase.id} — ${title} (feature ${feature.name})`, "info");
+                ctx.ui.notify(`Phase created: ${formatPhaseRef(phase.number, feature.number)} — ${title}${phase.shortId ? ` · ${phase.shortId}` : ""} (feature ${feature.name})`, "info");
                 const startDiscuss = await ctx.ui.input("Start phase discuss now? Type yes to continue");
                 if (isYes(startDiscuss)) {
                     await handlePlanner(`phase discuss ${phase.id}`, ctx);
@@ -1571,7 +1592,7 @@ export default function planPiExtension(pi) {
                 phase.status = "discovery";
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
-                ctx.ui.notify(`Discovery for ${phase.id}…`, "info");
+                ctx.ui.notify(`Discovery for ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}…`, "info");
                 // ── Recap: give full context before planning tasks ──
                 const recapPlan = await st.loadAll();
                 const recapProject = recapPlan.project;
@@ -1636,7 +1657,7 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Phase ${phase.id} is now **planned**.`, "info");
+                ctx.ui.notify(`Phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))} is now **planned**.${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "show") {
@@ -1684,7 +1705,7 @@ export default function planPiExtension(pi) {
                 }
                 await st.deletePhase(phase.id);
                 await st.writeGenerated();
-                ctx.ui.notify(`Phase deleted: ${phase.id}`, "info");
+                ctx.ui.notify(`Phase deleted: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "update") {
@@ -1736,7 +1757,7 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Phase updated: ${phase.id} — ${phase.title} (${phase.status})`, "info");
+                ctx.ui.notify(`Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))} — ${phase.title} (${phase.status})${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
             }
             ctx.ui.notify(`Unknown phase action "${b}". Try: add, show, discuss, delete, update`, "warning");
@@ -1762,7 +1783,7 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const shortName = clampSlug(title, 30, `task-${Date.now().toString(36)}`);
-                const taskNum = phase.tasks.length + 1;
+                const taskNum = await st.allocTaskNumber();
                 const taskId = createTaskId();
                 const shortId = createShortId(await st.assignedShortIds());
                 const priority = await st.nextPriority("task", phase.id);
@@ -1794,7 +1815,7 @@ export default function planPiExtension(pi) {
             }
             if (b === "discuss") {
                 const phases = await st.loadAllPhases();
-                let resolved = subArgs.trim() ? findTaskByRef(phases, subArgs.trim()) : null;
+                let resolved = subArgs.trim() ? findTaskByRef(phases, (await st.loadFeatures()).features, subArgs.trim()) : null;
                 if (!resolved) {
                     const phase = await pickPhase();
                     if (!phase) {
@@ -1828,14 +1849,14 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Task ${task.id} discussed and updated.`, "info");
+                ctx.ui.notify(`Task ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} discussed and updated.`, "info");
                 return;
             }
             if (b === "show") {
                 let phase = null;
                 let task = null;
                 if (subArgs.trim()) {
-                    const resolved = findTaskByRef(await st.loadAllPhases(), subArgs.trim());
+                    const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
                     phase = resolved?.phase ?? null;
                     task = resolved?.task ?? null;
                 }
@@ -1897,7 +1918,7 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = nowISO();
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Task deleted: ${task.id}`, "info");
+                ctx.ui.notify(`Task deleted: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")}${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "update") {
@@ -1946,14 +1967,14 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = now;
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`Task updated: ${task.id} — ${task.title} (${task.status})`, "info");
+                ctx.ui.notify(`Task updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (${task.status})${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "start") {
                 let phase = null;
                 let task = null;
                 if (subArgs.trim()) {
-                    const resolved = findTaskByRef(await st.loadAllPhases(), subArgs.trim());
+                    const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
                     phase = resolved?.phase ?? null;
                     task = resolved?.task ?? null;
                 }
@@ -1977,12 +1998,16 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
                     return;
                 }
-                // Hygiene notice (non-blocking): surface an existing handoff but never
-                // block task_start — the handoff is a captured-context artifact, not a
-                // lock (a small modification after writing a handoff should start without
-                // forcing deletion, which would lose context).
-                if ((await st.listHandoffs()).length > 0) {
-                    ctx.ui.notify("ℹ️  One or more phases have a pending handoff — if relevant to the task you're starting, read it with /planner handoff show <ref>, then clear with /planner handoff clear. Proceeding with task start.", "info");
+                // Auto-archive the handoff on THIS task's phase (reason: task-started) —
+                // the agent is now actively working, so the captured context is consumed.
+                // Other phases' handoffs are left untouched (informational, non-blocking).
+                if ((phase.handoff ?? "") !== "") {
+                    await st.clearPhaseHandoff(phase.id, "task-started").catch(() => { });
+                    ctx.ui.notify("📦 Archived handoff for this phase (task started) — recover via /planner handoff list + .planner/handoff-archive/.", "info");
+                }
+                const _otherHandoffs = (await st.listHandoffs()).filter((h) => h.phaseId !== phase.id);
+                if (_otherHandoffs.length > 0) {
+                    ctx.ui.notify(`ℹ️  ${_otherHandoffs.length} other phase handoff(s) pending — review with /planner handoff list if relevant.`, "info");
                 }
                 const now = nowISO();
                 // Record status change in the incremental statusLog.
@@ -2001,14 +2026,14 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = now;
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`✅ Task started: ${task.id} — ${task.title} (in-progress)`, "info");
+                ctx.ui.notify(`✅ Task started: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (in-progress)${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "complete") {
                 let phase = null;
                 let task = null;
                 if (subArgs.trim()) {
-                    const resolved = findTaskByRef(await st.loadAllPhases(), subArgs.trim());
+                    const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
                     phase = resolved?.phase ?? null;
                     task = resolved?.task ?? null;
                 }
@@ -2056,7 +2081,7 @@ export default function planPiExtension(pi) {
                 phase.updatedAt = now;
                 await st.savePhase(phase);
                 await st.writeGenerated();
-                ctx.ui.notify(`✅ Task completed: ${task.id} — ${task.title} (done)`, "info");
+                ctx.ui.notify(`✅ Task completed: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (done)${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
             }
             ctx.ui.notify(`Unknown task action "${b}". Try: add, show, discuss, delete, update, start, complete`, "warning");
@@ -2139,7 +2164,7 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(r.error, "warning");
                     return;
                 }
-                await st.clearPhaseHandoff(r.phase.id);
+                await st.clearPhaseHandoff(r.phase.id, "manual");
                 ctx.ui.notify(`Cleared handoff on ${r.compositeRef}`, "info");
                 return;
             }
@@ -2221,12 +2246,12 @@ export default function planPiExtension(pi) {
             try {
                 if (a === "bypass") {
                     const mins = parseInt(subArgs.trim(), 10);
-                    const until = await st.authorizeGuardBypass(Number.isFinite(mins) && mins > 0 ? mins : 15);
-                    ctx.ui.notify(`Guard bypass authorized until ${until}. edit/write will work without a task in-progress for that window.`, "info");
+                    const until = authorizeGuardBypass(Number.isFinite(mins) && mins > 0 ? mins : 15);
+                    ctx.ui.notify(`Guard bypass authorized until ${until}. edit/write advisory warnings silenced for that window (per-session, not shared).`, "info");
                 }
                 else {
-                    await st.clearGuardBypass();
-                    ctx.ui.notify("Guard bypass revoked. edit/write now requires a task in-progress again.", "info");
+                    clearGuardBypass();
+                    ctx.ui.notify("Guard bypass revoked. edit/write advisory warnings re-enabled.", "info");
                 }
             }
             catch (e) {
@@ -2583,7 +2608,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "plan_repair",
         label: "Plan Repair",
-        description: "Repair dangling feature→phase references and report plan integrity (duplicate phase ids, dangling phase refs). Safe to run anytime; run if the planner reports ENOENT/phase not found or after manual edits to .planner/.",
+        description: "Repair dangling feature→phase references, rebuild phase containment from each task's own phaseId (heals the migrateToGlobalSequence task-shuffle bug), and report plan integrity (duplicate phase ids, dangling phase refs). Safe to run anytime; run if the planner reports ENOENT/phase not found, tasks appear in the wrong phase, or after manual edits to .planner/.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -2591,9 +2616,11 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const report = await st.repair();
             const m = report.migrated;
+            const c = report.containment;
             const lines = [
                 `Repair complete.`,
                 `Migration: renamed=${m.renamed}, repaired=${m.repaired} refs, inferred=${m.inferred}.`,
+                `Containment: ${c.changed} phase file${c.changed === 1 ? "" : "s"} rewritten (tasks regrouped by their own phaseId), ${c.tasks} tasks scanned, ${c.orphan} orphan.`,
                 `Integrity: duplicatePhaseIds=${report.integrity.duplicatePhaseIds.length}, danglingPhaseIds=${report.integrity.danglingPhaseIds.length}.`,
             ];
             if (report.integrity.danglingPhaseIds.length)
@@ -2666,7 +2693,7 @@ export default function planPiExtension(pi) {
             const r = await resolvePhaseForHandoff(st, undefined);
             if (!r.ok)
                 return { content: [{ type: "text", text: `⚠️ plan_delete_handoff is deprecated — use handoff_clear. ${r.error}` }], details: { deprecated: true, error: r.error } };
-            await st.clearPhaseHandoff(r.phase.id);
+            await st.clearPhaseHandoff(r.phase.id, "manual");
             return { content: [{ type: "text", text: `⚠️ plan_delete_handoff is deprecated — cleared handoff on ${r.compositeRef} (phase.handoff). Prefer handoff_clear.` }], details: { deprecated: true, phaseRef: r.compositeRef, phaseId: r.phase.id } };
         },
     });
@@ -2764,36 +2791,36 @@ export default function planPiExtension(pi) {
             const r = await resolvePhaseForHandoff(st, params.phaseRef);
             if (!r.ok)
                 return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
-            await st.clearPhaseHandoff(r.phase.id);
-            return { content: [{ type: "text", text: `✅ Cleared handoff on ${r.compositeRef}. (handoffUpdatedAt preserved as audit)` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
+            await st.clearPhaseHandoff(r.phase.id, "manual");
+            return { content: [{ type: "text", text: `✅ Cleared handoff on ${r.compositeRef} (handoffUpdatedAt preserved as audit; archived to .planner/handoff-archive/).` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id } };
         },
     });
     pi.registerTool({
         name: "plan_authorize_bypass",
         label: "Plan Authorize Guard Bypass",
-        description: "Authorize a temporary guard bypass (default 15 minutes) so edit/write tools can proceed even when no task is in-progress. Use this ONLY after the user explicitly authorizes proceeding without a task. Harness-agnostic: stored in resume.json so all adapters respect it.",
+        description: "Authorize a temporary guard bypass (default 15 minutes) so the edit/write advisory guard stops warning when no task is in-progress. Per-session in-memory: not persisted, not shared across agents. Use ONLY after the user explicitly authorizes proceeding without a task.",
         parameters: Type.Object({
             durationMinutes: Type.Optional(Type.Number({ description: "Bypass window in minutes. Default 15." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
-            const st = await requirePlan(ctx);
-            if (!st)
+            const ok = await requirePlan(ctx);
+            if (!ok)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const mins = params.durationMinutes ?? 15;
-            const until = await st.authorizeGuardBypass(mins);
-            return { content: [{ type: "text", text: `Guard bypass authorized until ${until}. edit/write is allowed without a task in-progress for ${mins} minutes.` }], details: { until } };
+            const until = authorizeGuardBypass(mins);
+            return { content: [{ type: "text", text: `Guard bypass authorized until ${until}. Advisory edit/write warnings silenced for ${mins} minutes (per-session, not shared).` }], details: { until } };
         },
     });
     pi.registerTool({
         name: "plan_clear_bypass",
         label: "Plan Clear Guard Bypass",
-        description: "Revoke any active guard bypass so edit/write again requires a task in-progress.",
+        description: "Revoke the per-session guard bypass so the edit/write advisory warnings resume.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
-            const st = await requirePlan(ctx);
-            if (!st)
+            const ok = await requirePlan(ctx);
+            if (!ok)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            await st.clearGuardBypass();
+            clearGuardBypass();
             return { content: [{ type: "text", text: "Guard bypass revoked." }], details: { cleared: true } };
         },
     });
@@ -2801,38 +2828,44 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "feature_list",
         label: "Feature List",
-        description: "List all features with their ids, statuses, and phase counts.",
-        parameters: Type.Object({}),
-        async execute(_id, _params, _signal, _onUpdate, ctx) {
+        description: "List features (compact: F00x · shortId — name (status; N phases, M tasks)). Use this to discover refs cheaply — do NOT read .planner/ files or plan_get full=true to find entities.",
+        parameters: Type.Object({ featureRef: Type.Optional(Type.String({ description: "Optional: filter to one feature (F00x/shortId/UUID/name)" })) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const features = (await st.loadFeatures()).features;
+            const all = (await st.loadFeatures()).features;
+            const ref = params.featureRef?.trim();
+            const matchF = (f) => !ref || formatFeatureRef(f.number) === ref || f.shortId === ref || f.id === ref || f.name.toLowerCase() === ref.toLowerCase();
+            const features = all.filter(matchF);
             const phases = await st.loadAllPhases();
             const summary = features.map((f) => {
                 const fp = phases.filter((p) => p.featureId === f.id);
-                return `- ${statusIcon(f.status)} ${f.id} — ${f.name} (${fp.length} phases, ${fp.reduce((t, p) => t + p.tasks.length, 0)} tasks)`;
+                return `- ${formatFeatureRef(f.number)}${f.shortId ? ` · ${f.shortId}` : ""} — ${f.name} (${f.status}; ${fp.length} phases, ${fp.reduce((t, p) => t + p.tasks.length, 0)} tasks)`;
             }).join("\n");
-            return { content: [{ type: "text", text: summary || "No features" }], details: { features } };
+            return { content: [{ type: "text", text: summary || "No features" }], details: {} };
         },
     });
     pi.registerTool({
         name: "feature_get",
         label: "Feature Get",
-        description: "Read full details of a feature, including its phases and their tasks.",
+        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description.",
         parameters: Type.Object({
-            featureId: Type.String({ description: "Feature ID, e.g. feature-001-dynamic-header" }),
+            featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
+            full: Type.Optional(Type.Boolean({ description: "If true, include the feature description. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const features = (await st.loadFeatures()).features;
-            const feature = features.find((f) => f.id === params.featureId);
+            const ref = params.featureId.trim();
+            const feature = features.find((f) => formatFeatureRef(f.number) === ref || f.shortId === ref || f.id === ref || f.name.toLowerCase() === ref.toLowerCase());
             if (!feature)
-                return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
+                return { content: [{ type: "text", text: `Feature not found: ${ref}` }], details: {} };
             const phases = (await st.loadAllPhases()).filter((p) => p.featureId === feature.id);
-            return { content: [{ type: "text", text: `${statusIcon(feature.status)} ${feature.name} (${feature.id}) — ${phases.length} phases` }], details: { feature, phases } };
+            const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases)`;
+            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${feature.description || ""}` : summary }], details: {} };
         },
     });
     pi.registerTool({
@@ -2855,7 +2888,7 @@ export default function planPiExtension(pi) {
             const priority = await st.nextPriority("feature");
             const feature = {
                 id: createFeatureId(),
-                number: currentFeatures.length + 1,
+                number: await st.allocFeatureNumber(),
                 shortId,
                 priority,
                 name: params.name,
@@ -2881,7 +2914,7 @@ export default function planPiExtension(pi) {
                 return doc;
             });
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Feature created: ${feature.id}` }], details: feature };
+            return { content: [{ type: "text", text: `✅ Feature created: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
         },
     });
     pi.registerTool({
@@ -2889,7 +2922,7 @@ export default function planPiExtension(pi) {
         label: "Feature Update",
         description: "Update one or more fields of a feature. Only provided fields are changed. IMPORTANT: feature status is derived from child phases/tasks, so do not update feature.status directly unless truly necessary.",
         parameters: Type.Object({
-            featureId: Type.String({ description: "Feature ID" }),
+            featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
             name: Type.Optional(Type.String({ description: "New name" })),
             description: Type.Optional(Type.String({ description: "New description" })),
             status: Type.Optional(Type.String({ description: "New status: planned|in-progress|done|blocked|canceled. Avoid setting this directly unless you truly need an override: feature status is derived from child phases/tasks." })),
@@ -2956,7 +2989,7 @@ export default function planPiExtension(pi) {
             if (!feature)
                 return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Feature updated: ${feature.id} (${feature.status})` }], details: feature };
+            return { content: [{ type: "text", text: `✅ Feature updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
         },
     });
     pi.registerTool({
@@ -2964,7 +2997,7 @@ export default function planPiExtension(pi) {
         label: "Feature Delete",
         description: "Delete a feature. Its phases are unlinked (featureId cleared) but NOT deleted unless cascade=true.",
         parameters: Type.Object({
-            featureId: Type.String({ description: "Feature ID to delete" }),
+            featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name to delete" }),
             cascade: Type.Optional(Type.Boolean({ description: "If true, also delete all phases belonging to this feature. Default: false" })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
@@ -2998,40 +3031,52 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "phase_list",
         label: "Phase List",
-        description: "List all phases (optionally filtered by featureId) with id, status, and task counts.",
+        description: "List phases (compact: F00x/P00x · shortId — title (status; N tasks) [F00x]). Filters: featureRef, status. Cheap discovery — do NOT read .planner/ files or plan_get full=true.",
         parameters: Type.Object({
-            featureId: Type.Optional(Type.String({ description: "If provided, only list phases of this feature" })),
+            featureRef: Type.Optional(Type.String({ description: "Optional: filter to one feature (F00x/shortId/UUID/name)" })),
+            status: Type.Optional(Type.String({ description: "Optional: filter by status name" })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
             let phases = await st.loadAllPhases();
-            if (params.featureId)
-                phases = phases.filter((p) => p.featureId === params.featureId);
-            const summary = phases.map((p) => `- ${statusIcon(p.status)} ${p.id} — ${p.title} (${p.tasks.length} tasks, feature ${p.featureId ?? "none"})`).join("\n");
-            return { content: [{ type: "text", text: summary || "No phases" }], details: { phases } };
+            const fref = params.featureRef?.trim();
+            if (fref) {
+                const f = features.find((x) => formatFeatureRef(x.number) === fref || x.shortId === fref || x.id === fref || x.name.toLowerCase() === fref.toLowerCase());
+                if (!f)
+                    return { content: [{ type: "text", text: `Feature not found: ${fref}` }], details: {} };
+                phases = phases.filter((p) => p.featureId === f.id);
+            }
+            if (params.status)
+                phases = phases.filter((p) => p.status === params.status);
+            const summary = phases.map((p) => {
+                const fNum = featureNumberOfPhase(p, features);
+                const fTag = fNum !== undefined ? ` [F${pad(fNum)}]` : "";
+                return `- ${formatPhaseRef(p.number, fNum)}${p.shortId ? ` · ${p.shortId}` : ""} — ${p.title} (${p.status}; ${p.tasks.length} tasks)${fTag}`;
+            }).join("\n");
+            return { content: [{ type: "text", text: summary || "No phases" }], details: {} };
         },
     });
     pi.registerTool({
         name: "phase_get",
         label: "Phase Get",
-        description: "Read full details of a phase, including its tasks.",
+        description: "Show a phase. Compact identity by default (saves tokens); pass full=true to include the description.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID, e.g. phase-01-setup" }),
+            phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title" }),
+            full: Type.Optional(Type.Boolean({ description: "If true, include the phase description. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            let phase;
-            try {
-                phase = await st.loadPhase(params.phaseId);
-            }
-            catch {
+            const features = (await st.loadFeatures()).features;
+            const phase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
+            if (!phase)
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
-            }
-            return { content: [{ type: "text", text: `${statusIcon(phase.status)} ${phase.title} (${phase.id}) — ${phase.tasks.length} tasks` }], details: phase };
+            const 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: {} };
         },
     });
     pi.registerTool({
@@ -3055,7 +3100,7 @@ export default function planPiExtension(pi) {
             await withFeatureLock(params.featureId, async () => {
                 const phases = await st.loadAllPhases();
                 const featurePhases = phases.filter((p) => p.featureId === params.featureId);
-                const number = featurePhases.reduce((max, p) => Math.max(max, p.number), 0) + 1;
+                const number = await st.allocPhaseNumber();
                 const id = createPhaseId();
                 const shortId = createShortId(await st.assignedShortIds());
                 const priority = await st.nextPriority("phase", params.featureId);
@@ -3072,6 +3117,8 @@ export default function planPiExtension(pi) {
                     openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                     createdAt: now, updatedAt: now,
                     handoff: "", handoffUpdatedAt: "",
+                    handoffReadAt: "",
+                    handoffHistory: [],
                 };
                 await st.savePhase(phase);
                 // Atomic: serialize concurrent phase_create linking to the same feature.
@@ -3087,7 +3134,8 @@ export default function planPiExtension(pi) {
             });
             if (!phase)
                 return { content: [{ type: "text", text: "Phase creation failed." }], details: {} };
-            return { content: [{ type: "text", text: `Phase created: ${phase.id}` }], details: phase };
+            const phaseCreateFeatures = (await st.loadFeatures()).features;
+            return { content: [{ type: "text", text: `✅ Phase created: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseCreateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
         },
     });
     pi.registerTool({
@@ -3095,7 +3143,7 @@ export default function planPiExtension(pi) {
         label: "Phase Update",
         description: "Update one or more fields of a phase. Only provided fields are changed. Supports re-linking to a feature via featureId. IMPORTANT: phase status is derived from task statuses, so do not update phase.status directly unless truly necessary.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID" }),
+            phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title" }),
             title: Type.Optional(Type.String({ description: "New title" })),
             status: Type.Optional(Type.String({ description: "New status: draft|discovery|planned|in-progress|done|blocked|canceled. Avoid setting this directly unless you truly need an override: phase status is derived from task statuses." })),
             summary: Type.Optional(Type.String({ description: "New summary" })),
@@ -3176,7 +3224,8 @@ export default function planPiExtension(pi) {
             phase.updatedAt = nowISO();
             await st.savePhase(phase);
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Phase updated: ${phase.id} (${phase.status})` }], details: phase };
+            const phaseUpdateFeatures = (await st.loadFeatures()).features;
+            return { content: [{ type: "text", text: `✅ Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseUpdateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
         },
     });
     pi.registerTool({
@@ -3184,7 +3233,7 @@ export default function planPiExtension(pi) {
         label: "Phase Delete",
         description: "Delete a phase. Its tasks are deleted with it (cascade). Unlinks the phase from its feature.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID to delete" }),
+            phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title to delete" }),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3216,42 +3265,64 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "task_list",
         label: "Task List",
-        description: "List tasks of a phase with id, status, and title.",
+        description: "List tasks (compact: F00x/P00x/T00x · shortId — title (status)). Filters: featureRef, phaseRef, status. Omit all to list every task. Cheap discovery — do NOT read .planner/ files or plan_get full=true.",
         parameters: Type.Object({
-            phaseId: Type.String({ description: "Phase ID" }),
+            featureRef: Type.Optional(Type.String({})),
+            phaseRef: Type.Optional(Type.String({})),
+            status: Type.Optional(Type.String({ description: "Optional: filter by status name" })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            let phase;
-            try {
-                phase = await st.loadPhase(params.phaseId);
-            }
-            catch {
-                return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            let phases = await st.loadAllPhases();
+            const fref = params.featureRef?.trim();
+            if (fref) {
+                const f = features.find((x) => formatFeatureRef(x.number) === fref || x.shortId === fref || x.id === fref || x.name.toLowerCase() === fref.toLowerCase());
+                if (!f)
+                    return { content: [{ type: "text", text: `Feature not found: ${fref}` }], details: {} };
+                phases = phases.filter((p) => p.featureId === f.id);
+            }
+            const pref = params.phaseRef?.trim();
+            if (pref) {
+                const p = findPhaseByRef(phases, features, pref);
+                if (!p)
+                    return { content: [{ type: "text", text: `Phase not found: ${pref}` }], details: {} };
+                phases = [p];
+            }
+            const out = [];
+            for (const phase of phases) {
+                for (const task of phase.tasks) {
+                    if (params.status && task.status !== params.status)
+                        continue;
+                    out.push(`- ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${pad(task.number)}${task.shortId ? ` · ${task.shortId}` : ""} — ${task.title} (${task.status})`);
+                }
             }
-            const summary = phase.tasks.map((t) => `- ${statusIcon(t.status)} ${t.id} — ${t.title}`).join("\n");
-            return { content: [{ type: "text", text: summary || "No tasks" }], details: { tasks: phase.tasks } };
+            return { content: [{ type: "text", text: out.join("\n") || "No tasks" }], details: {} };
         },
     });
     pi.registerTool({
         name: "task_get",
         label: "Task Get",
-        description: "Read full details of a single task.",
+        description: "Show a task. Compact identity by default (saves tokens); pass full=true to include the description + statusLog.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
+            full: Type.Optional(Type.Boolean({ description: "If true, include the task description + statusLog. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const phases = await st.loadAllPhases();
-            const phase = phases.find((p) => p.tasks.some((t) => t.id === params.taskId));
-            const task = phase?.tasks.find((t) => t.id === params.taskId);
-            if (!task || !phase)
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            return { content: [{ type: "text", text: `${statusIcon(task.status)} ${task.title} (${task.id}) — phase ${phase.id}` }], details: { task, phaseId: phase.id } };
+            const summary = `${found.task.title} — ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}${found.task.shortId ? ` · ${found.task.shortId}` : ""} (${found.task.status})`;
+            if (!params.full)
+                return { content: [{ type: "text", text: summary }], details: {} };
+            const log = (found.task.statusLog ?? []).map((e) => `  - ${e.date.slice(0, 10)} ${e.title}`).join("\n");
+            return { content: [{ type: "text", text: `${summary}\n\n${found.task.description || ""}${log ? `\n\nStatus log:\n${log}` : ""}` }], details: {} };
         },
     });
     pi.registerTool({
@@ -3284,7 +3355,7 @@ export default function planPiExtension(pi) {
             const initialStatus = params.status ?? "planned";
             const existingPhase = await st.loadPhase(params.phaseId);
             const task = {
-                id: taskId, phaseId: params.phaseId, number: existingPhase.tasks.length + 1, shortId, priority, shortName,
+                id: taskId, phaseId: params.phaseId, number: await st.allocTaskNumber(), shortId, priority, shortName,
                 title: params.title,
                 status: initialStatus,
                 description: params.description ?? "",
@@ -3315,7 +3386,7 @@ export default function planPiExtension(pi) {
         label: "Task Update",
         description: "Update one or more fields of a task. Only provided fields are changed. Do NOT use this tool to start or complete work; use task_start and task_complete for lifecycle transitions so startedAt/completedAt stay correct.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
             title: Type.Optional(Type.String({ description: "New title" })),
             status: Type.Optional(Type.String({ description: "New status: planned|in-progress|done|blocked|canceled|rejected|deferred|waiting" })),
             description: Type.Optional(Type.String({ description: "New description" })),
@@ -3403,7 +3474,7 @@ export default function planPiExtension(pi) {
         label: "Task Delete",
         description: "Delete a task from its phase.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID to delete" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to delete" }),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3429,7 +3500,7 @@ export default function planPiExtension(pi) {
         label: "Task Start",
         description: "Set a task to in-progress. Use this BEFORE starting implementation work on any task. Sets startedAt timestamp automatically.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID to start" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to start" }),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3467,7 +3538,7 @@ export default function planPiExtension(pi) {
         label: "Task Complete",
         description: "Mark a task as done. Sets completedAt and startedAt (if missing) automatically. Checks for unchecked checklist items and warns unless force=true.",
         parameters: Type.Object({
-            taskId: Type.String({ description: "Task ID to complete" }),
+            taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to complete" }),
             force: Type.Optional(Type.Boolean({ description: "Skip checklist completion check. Default: false" })),
             description_update: Type.Optional(Type.String({ description: "Post-hoc summary: commit hash(s), files touched, decisions made, updated code references with new line numbers. Keeps the planner alive and traceable." })),
         }),
@@ -3607,6 +3678,7 @@ export default function planPiExtension(pi) {
             // add seconds of latency on every turn if run unconditionally.
             if (!plannerHeavyInitDone) {
                 await migrateToUuids(st);
+                await migrateToGlobalSequence(st).catch(() => null);
                 await st.ensureShortIdsAndPriority().catch(() => null);
                 await ensureProjectLanguagePreferences(st).catch(() => null);
                 await maybeHealStatuses(st, ctx);
@@ -3688,12 +3760,12 @@ export default function planPiExtension(pi) {
                 : hasActiveWork
                     ? plan.features.features.find((feature) => feature.status === "in-progress") ?? null
                     : null;
-            const nextActivity = hasActiveWork
-                ? (resume.nextSteps[0]
-                    ?? (currentTask ? `Resume task ${currentTask.id} — ${taskLabel(currentTask)}` : currentPhase ? `Resume phase ${currentPhase.id} — ${phaseLabel(currentPhase)}` : "Resume the active work stream"))
-                : (handoffs.length > 0
-                    ? "Read the most recent phase handoff (handoff show <ref>), validate it against current plan ordering and dependencies, then pick the next task."
-                    : "Review the current plan and choose the next task.");
+            const 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 webServer = server;
             const webLocalUrl = webServer?.localUrl ?? webServer?.url ?? "";
             const webLanUrl = webServer?.lanUrl ?? "";
@@ -3744,12 +3816,12 @@ export default function planPiExtension(pi) {
                 "═══════════════════════════════════════════════════════════════",
                 "MANDATORY OPERATIONAL PROTOCOL (violation = execution failure):",
                 "═══════════════════════════════════════════════════════════════",
-                "1. HANDOFF HYGIENE: If one or more phases have a pending handoff (entity-scoped, phase.handoff), present the list, read the relevant one with handoff show <ref>, then CLEAR it with handoff clear <ref> once consumed. Handoffs are non-blocking context artifacts, not locks — they never block task_start.",
+                "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: When you mention a feature/phase/task in chat, use its composite ID (F00x / P00x / T00x, e.g. T003(P002/F001)) or its 5-char shortId (e.g. UUXD1) — NEVER a raw UUID like bd6ed366. Tool responses already show these refs (compositeRef, shortId); reuse them.",
+                "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.",
                 "═══════════════════════════════════════════════════════════════",
                 "",
                 // ── Project details ──
@@ -3780,7 +3852,7 @@ export default function planPiExtension(pi) {
                 resume.currentPhaseId ? `  current phase: ${resume.currentPhaseId}` : "  current phase: (none)",
                 resume.inProgressTaskIds.length ? `  in-progress tasks: ${resume.inProgressTaskIds.join(", ")}` : "  in-progress tasks: (none)",
                 resume.blockers.length ? `  blockers: ${resume.blockers.join("; ")}` : "  blockers: (none)",
-                resume.nextSteps.length ? `  next steps: ${resume.nextSteps.join("; ")}` : "  next steps: (none)",
+                resume.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}` : "",
                 "",
                 recentActivity.length ? "Recent activity (most recent first):" : "",
@@ -3824,7 +3896,7 @@ export default function planPiExtension(pi) {
                 ...handoffs.map((h, i) => `  [${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`),
                 handoffs.length > 0 ? "Read the relevant one with handoff show <ref> (or /planner handoff show <ref>) as previous-session context, but validate it against the current planner state, ordering, and dependencies before treating any target as the next task." : "",
                 handoffs.length > 0 ? "If planner state shows no task/phase in-progress, do NOT present a handoff target as the current focus; present it only as a candidate to validate." : "",
-                handoffs.length > 0 ? "Once a handoff is fully consumed and work is safely resumed, clear it with handoff clear <ref> (or /planner handoff clear)." : "",
+                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",
             ].filter(Boolean).join("\n");
             contextBlockCache = contextBlock;