@agent-plan/pi-adapter 0.2.19-next.4 → 0.2.19-next.6

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AA6uBtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA67F9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AAgvBtF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAs9F9D"}

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";
@@ -512,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) {
@@ -1146,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;
@@ -1363,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 = {
@@ -1392,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") {
@@ -1473,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") {
@@ -1550,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());
@@ -1577,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);
@@ -1602,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;
@@ -1667,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") {
@@ -1715,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") {
@@ -1767,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");
@@ -1793,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);
@@ -1825,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) {
@@ -1859,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;
                 }
@@ -1928,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") {
@@ -1977,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;
                 }
@@ -2036,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;
                 }
@@ -2091,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");
@@ -2836,38 +2826,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({
@@ -2890,7 +2886,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,
@@ -2924,7 +2920,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." })),
@@ -2999,7 +2995,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) {
@@ -3033,40 +3029,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({
@@ -3090,7 +3098,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);
@@ -3133,7 +3141,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" })),
@@ -3223,7 +3231,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);
@@ -3255,42 +3263,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({
@@ -3323,7 +3353,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 ?? "",
@@ -3354,7 +3384,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" })),
@@ -3442,7 +3472,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);
@@ -3468,7 +3498,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);
@@ -3506,7 +3536,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." })),
         }),
@@ -3646,6 +3676,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);
@@ -3788,7 +3819,7 @@ export default function planPiExtension(pi) {
                 "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, PREFER its 5-char shortId (globally unique, e.g. UUXD1). The composite T00x is per-phase and AMBIGUOUS unless fully qualified as T00x(P00x/F00x) — do NOT use bare 'T00x'. NEVER a raw UUID like bd6ed366. Tool responses already show shortId + compositeRef; 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 ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/pi-adapter",
-  "version": "0.2.19-next.4",
+  "version": "0.2.19-next.6",
   "private": false,
   "description": "Pi agent extension for Agent Plan — structured project planning in .planner/",
   "keywords": [
@@ -28,8 +28,8 @@
   "dependencies": {
     "typebox": "^1.1.24",
     "zod": "^3.24.0",
-    "@agent-plan/core": "0.2.19-next.4",
-    "@agent-plan/server": "0.2.19-next.4"
+    "@agent-plan/core": "0.2.19-next.6",
+    "@agent-plan/server": "0.2.19-next.6"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.74.0",