@agent-plan/mcp 0.2.19-next.0 → 0.2.19-next.10

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA+5BA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAg8BA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/dist/index.js

@@ -4,9 +4,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import * as z from "zod/v4";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef } from "@agent-plan/core";
+import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, migrateToGlobalSequence } from "@agent-plan/core";
 import { serve } from "@agent-plan/server";
-import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef } from "@agent-plan/core/naming";
+import { createChecklistItemId, createFeatureId, createPhaseId, createShortId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef } from "@agent-plan/core/naming";
 const STATUS_VALUES = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
 const PHASE_STATUS_VALUES = ["draft", "discovery", ...STATUS_VALUES];
 function text(textValue, structuredContent) {
@@ -31,6 +31,7 @@ async function requireStore() {
     if (!planBackfillDone) {
         planBackfillDone = true;
         await st.ensureShortIdsAndPriority().catch(() => { });
+        await migrateToGlobalSequence(st).catch(() => { });
     }
     return st;
 }
@@ -55,65 +56,17 @@ async function ensureWebStarted() {
         return { localUrl: "" };
     }
 }
-/** Build a consolidated planner recap (project state + active work + pending
- *  handoff + web URL). Harness-agnostic equivalent of Pi's buildStartupResumeSummary. */
-async function buildRecapText(st, web) {
-    const [plan, resume, handoffs] = await Promise.all([st.loadAll(), st.loadResume(), st.listHandoffs()]);
-    const allTasks = plan.phases.flatMap((p) => p.tasks.map((t) => ({ phase: p, task: t })));
-    const totalF = plan.features.features.length;
-    const doneF = plan.features.features.filter((f) => f.status === "done").length;
-    const activeF = plan.features.features.filter((f) => f.status === "in-progress").length;
-    const totalP = plan.phases.length;
-    const doneP = plan.phases.filter((p) => p.status === "done").length;
-    const activeP = plan.phases.filter((p) => p.status === "in-progress" || p.status === "discovery").length;
-    const totalT = allTasks.length;
-    const doneT = allTasks.filter(({ task }) => task.status === "done").length;
-    const activeT = allTasks.filter(({ task }) => task.status === "in-progress").length;
-    const inProgress = allTasks.filter(({ task }) => task.status === "in-progress");
-    const focus = inProgress[0];
-    const focusFeature = focus ? plan.features.features.find((f) => f.id === focus.phase.featureId) : undefined;
-    const lines = [];
-    lines.push("## Planner recap");
-    const name = plan.project.name || "(unnamed project)";
-    lines.push(`Project: ${name}${plan.project.goal ? " — " + plan.project.goal : ""}`);
-    lines.push(`Progress: Features ${doneF}/${totalF} done (${activeF} active) · Phases ${doneP}/${totalP} done (${activeP} active) · Tasks ${doneT}/${totalT} done (${activeT} active)`);
-    if (focus) {
-        lines.push(`Current focus: ${focusFeature?.name ?? "?"} / ${focus.phase.title} / ${focus.task.title} (in-progress)`);
-    }
-    else {
-        lines.push("Current focus: no active task — review the plan and pick the next concrete task");
-    }
-    if (resume?.nextSteps?.length)
-        lines.push(`Next step: ${resume.nextSteps[0]}`);
-    if (handoffs.length > 0) {
-        lines.push("", `## Pending phase handoffs (${handoffs.length})`);
-        handoffs.forEach((h, i) => lines.push(`[${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`));
-        lines.push("", "→ Read the relevant one with planner-handoff-show <ref> (validate against current state), then call planner-handoff-clear <ref> once consumed (delete-on-resume).");
-    }
-    else if (activeT === 0) {
-        lines.push("", "No phase handoff pending and no task in-progress. Use planner-task-add / planner-task-start to begin work.");
-    }
-    if (web.localUrl) {
-        lines.push("", "## Web UI", `🌐 ${web.localUrl}${web.lanUrl ? " (LAN: " + web.lanUrl + ")" : ""}`);
-    }
-    return lines.join("\n");
-}
 function findFeatureByRef(features, ref) {
     const normalized = ref.trim().toLowerCase();
     return features.find((feature) => feature.id.toLowerCase() === normalized)
         ?? features.find((feature) => feature.name.toLowerCase() === normalized)
         ?? features.find((feature) => feature.name.toLowerCase().includes(normalized));
 }
-function findTaskByRef(phases, ref) {
-    const normalized = ref.trim().toLowerCase();
-    for (const phase of phases) {
-        const task = phase.tasks.find((entry) => entry.id.toLowerCase() === normalized
-            || entry.title.toLowerCase() === normalized
-            || entry.title.toLowerCase().includes(normalized));
-        if (task)
-            return { phase, task };
-    }
-    return undefined;
+function featureNumberOfPhase(phase, features) {
+    return phase.featureId ? features.find((f) => f.id === phase.featureId)?.number : undefined;
+}
+function taskCompositeRef(task, phase, features) {
+    return `${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${String(task.number).padStart(3, "0")}`;
 }
 function applyTaskLifecycleDates(task, nextStatus, now) {
     const previousStatus = task.status;
@@ -209,7 +162,7 @@ server.registerTool("planner-init", {
     if (goal !== undefined)
         project.goal = goal.trim();
     await st.saveProject(project);
-    return writeAndSummarize(st, `.planner/ initialized for "${project.name}"`, { project });
+    return writeAndSummarize(st, `.planner/ initialized for "${project.name}"`);
 });
 server.registerTool("planner-show", {
     description: "Show the current planner overview.",
@@ -227,11 +180,11 @@ server.registerTool("planner-show", {
     ].join("\n"), { plan });
 });
 server.registerTool("planner-repair", {
-    description: "Repair dangling feature→phase references and report integrity.",
+    description: "Repair dangling feature→phase references, rebuild phase containment from each task's own phaseId (heals the migrateToGlobalSequence task-shuffle bug where tasks land in the wrong phase file), and report integrity.",
 }, async () => {
     const st = await requireStore();
     const report = await st.repair();
-    return text(`Repair done: renamed ${report.migrated.renamed}, repaired ${report.migrated.repaired} refs, inferred ${report.migrated.inferred}. Integrity: ${report.integrity.duplicatePhaseIds.length} duplicate, ${report.integrity.danglingPhaseIds.length} dangling.`, { report });
+    return text(`Repair done: renamed ${report.migrated.renamed}, repaired ${report.migrated.repaired} refs, inferred ${report.migrated.inferred}. Containment: ${report.containment.changed} phase files rewritten (${report.containment.tasks} tasks scanned, ${report.containment.orphan} orphan). Integrity: ${report.integrity.duplicatePhaseIds.length} duplicate, ${report.integrity.danglingPhaseIds.length} dangling.`, { report });
 });
 server.registerTool("planner-project-language", {
     description: "Persist preferred languages for plan content and chat.",
@@ -247,7 +200,7 @@ server.registerTool("planner-project-language", {
     if (chatLanguage !== undefined)
         project.chatLanguage = chatLanguage.trim();
     await st.saveProject(project);
-    return writeAndSummarize(st, `Saved language preferences: content=${project.contentLanguage || "(unset)"}, chat=${project.chatLanguage || "(unset)"}`, { project });
+    return writeAndSummarize(st, `Saved language preferences: content=${project.contentLanguage || "(unset)"}, chat=${project.chatLanguage || "(unset)"}`);
 });
 server.registerTool("planner-project-discuss", {
     description: "Record/update project-level discovery fields. This is the MCP equivalent of grouped project discuss without Pi UI prompts.",
@@ -278,20 +231,73 @@ server.registerTool("planner-project-discuss", {
     if (params.decisions !== undefined)
         project.decisions = params.decisions.map((entry) => entry.trim()).filter(Boolean);
     await st.saveProject(project);
-    return writeAndSummarize(st, `Project discussed/updated: ${project.name}`, { project });
+    return writeAndSummarize(st, `Project discussed/updated: ${project.name}`);
 });
 server.registerTool("planner-feature-list", {
-    description: "List features with phase/task counts.",
-}, async () => {
+    description: "List features (compact: F00x · shortId — name (status; N phases, M tasks)). Pass featureRef to filter. Use this to discover refs cheaply — do NOT read .planner/ files or planner-plan-get full=true to find entities.",
+    inputSchema: { featureRef: z.string().optional().describe("Optional: filter to one feature (F00x/shortId/UUID/name).") },
+}, async ({ featureRef }) => {
     const st = await requireStore();
-    const features = (await st.loadFeatures()).features;
+    const allFeatures = (await st.loadFeatures()).features;
+    const features = featureRef ? allFeatures.filter((f) => f.id === findFeatureByRef(allFeatures, featureRef)?.id) : allFeatures;
     const phases = await st.loadAllPhases();
     const lines = features.map((feature) => {
         const featurePhases = phases.filter((phase) => phase.featureId === feature.id);
         const taskCount = featurePhases.reduce((total, phase) => total + phase.tasks.length, 0);
-        return `- ${feature.id} — ${feature.name} (${feature.status}; ${featurePhases.length} phases, ${taskCount} tasks)`;
+        return `- ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} — ${feature.name} (${feature.status}; ${featurePhases.length} phases, ${taskCount} tasks)`;
     });
-    return text(lines.join("\n") || "No features", { features });
+    return text(lines.join("\n") || "No features");
+});
+server.registerTool("planner-phase-list", {
+    description: "List phases (compact: F00x/P00x · shortId — title (status; N tasks) [F00x]). Filters: featureRef, status. Cheap discovery — do NOT read .planner/ files or planner-plan-get full=true.",
+    inputSchema: { featureRef: z.string().optional().describe("Optional: filter to one feature (F00x/shortId/UUID/name)."), status: z.string().optional().describe("Optional: filter by status name.") },
+}, async ({ featureRef, status }) => {
+    const st = await requireStore();
+    const features = (await st.loadFeatures()).features;
+    let phases = await st.loadAllPhases();
+    if (featureRef) {
+        const f = findFeatureByRef(features, featureRef);
+        if (!f)
+            return text(`Feature not found: ${featureRef}`);
+        phases = phases.filter((p) => p.featureId === f.id);
+    }
+    if (status)
+        phases = phases.filter((p) => p.status === status);
+    const lines = phases.map((phase) => {
+        const fNum = featureNumberOfPhase(phase, features);
+        const fTag = fNum !== undefined ? ` [F${String(fNum).padStart(3, "0")}]` : "";
+        return `- ${formatPhaseRef(phase.number, fNum)}${phase.shortId ? ` · ${phase.shortId}` : ""} — ${phase.title} (${phase.status}; ${phase.tasks.length} tasks)${fTag}`;
+    });
+    return text(lines.join("\n") || "No phases");
+});
+server.registerTool("planner-task-list", {
+    description: "List tasks (compact: F00x/P00x/T00x · shortId — title (status)). Filters: featureRef, phaseRef, status. Cheap discovery — do NOT read .planner/ files or planner-plan-get full=true.",
+    inputSchema: { featureRef: z.string().optional(), phaseRef: z.string().optional(), status: z.string().optional().describe("Optional: filter by status name.") },
+}, async ({ featureRef, phaseRef, status }) => {
+    const st = await requireStore();
+    const features = (await st.loadFeatures()).features;
+    let phases = await st.loadAllPhases();
+    if (featureRef) {
+        const f = findFeatureByRef(features, featureRef);
+        if (!f)
+            return text(`Feature not found: ${featureRef}`);
+        phases = phases.filter((p) => p.featureId === f.id);
+    }
+    if (phaseRef) {
+        const p = findPhaseByRef(phases, features, phaseRef);
+        if (!p)
+            return text(`Phase not found: ${phaseRef}`);
+        phases = [p];
+    }
+    const out = [];
+    for (const phase of phases) {
+        for (const task of phase.tasks) {
+            if (status && task.status !== status)
+                continue;
+            out.push(`- ${taskCompositeRef(task, phase, features)}${task.shortId ? ` · ${task.shortId}` : ""} — ${task.title} (${task.status})`);
+        }
+    }
+    return text(out.join("\n") || "No tasks");
 });
 server.registerTool("planner-feature-add", {
     description: "Create a feature with a rich description. REQUIRED: description must include code references (file:line), current implementation state (what exists, what is unimplemented), systems/structs/traits involved, concrete goals, and behaviors to preserve. The description is the primary context for future agents resuming this feature; one-liners cause misalignment.",
@@ -309,7 +315,7 @@ server.registerTool("planner-feature-add", {
     const priority = await st.nextPriority("feature");
     const feature = {
         id: createFeatureId(),
-        number: existingFeatures.length + 1,
+        number: await st.allocFeatureNumber(),
         shortId,
         priority,
         name: name.trim(),
@@ -332,24 +338,25 @@ server.registerTool("planner-feature-add", {
         doc.features.push(feature);
         return doc;
     });
-    return writeAndSummarize(st, `Feature created: ${feature.id} — ${feature.name}`, { feature });
+    return writeAndSummarize(st, `✅ Feature created: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}`);
 });
 server.registerTool("planner-feature-show", {
     description: "Show a feature by id or name.",
-    inputSchema: { feature: z.string().min(1).describe("Feature id or name") },
-}, async ({ feature: ref }) => {
+    inputSchema: { feature: z.string().min(1).describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the feature description. Default: compact identity only (saves tokens).") },
+}, async ({ feature: ref, full }) => {
     const st = await requireStore();
     const features = (await st.loadFeatures()).features;
     const feature = findFeatureByRef(features, ref);
     if (!feature)
         return text(`Feature not found: ${ref}`);
     const phases = (await st.loadAllPhases()).filter((phase) => phase.featureId === feature.id);
-    return text(`${feature.name} (${feature.id}) — ${feature.status}; ${phases.length} phases`, { feature, phases });
+    const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases)`;
+    return text(full ? `${summary}\n\n${feature.description || ""}` : summary);
 });
 server.registerTool("planner-feature-update", {
     description: "Update a feature.",
     inputSchema: {
-        feature: z.string().min(1).describe("Feature id or name"),
+        feature: z.string().min(1).describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
         name: z.string().optional(),
         description: z.string().optional(),
         status: z.enum(STATUS_VALUES).optional(),
@@ -389,12 +396,12 @@ server.registerTool("planner-feature-update", {
         return doc;
     });
     const result = updated.features.find((entry) => entry.id === feature.id);
-    return writeAndSummarize(st, `Feature updated: ${result.id} — ${result.name}`, { feature: result });
+    return writeAndSummarize(st, `✅ Feature updated: ${formatFeatureRef(result.number)} — ${result.name}${result.shortId ? ` · ${result.shortId}` : ""}`);
 });
 server.registerTool("planner-feature-delete", {
     description: "Delete a feature. By default, phases are unlinked rather than deleted.",
     inputSchema: {
-        feature: z.string().min(1).describe("Feature id or name"),
+        feature: z.string().min(1).describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
         cascade: z.boolean().optional().describe("Also delete phases belonging to this feature"),
     },
 }, async ({ feature: ref, cascade }) => {
@@ -424,7 +431,7 @@ server.registerTool("planner-phase-add", {
     description: "Create a phase with a rich description. REQUIRED: description must include code references (file:line), current implementation state, dependencies, specific files/systems to modify, and behaviors to preserve. The description is the primary context for future agents; one-liners cause misalignment.",
     inputSchema: {
         title: z.string().min(1),
-        feature: z.string().optional().describe("Feature id or name"),
+        feature: z.string().optional().describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
         summary: z.string().optional().describe("One-line summary of the phase"),
         description: z.string().min(50, "Description must be at least 50 characters — include code references (file:line), current state, structs/traits involved, concrete work items, behaviors to preserve. Prefix with 'design-only' for pre-implementation design tasks.").describe("Required code references (file:line), current state, structs/traits involved, concrete work items, behaviors to preserve. Not a one-liner."),
     },
@@ -444,7 +451,7 @@ server.registerTool("planner-phase-add", {
         const priority = await st.nextPriority("phase", feature?.id);
         phase = {
             id: createPhaseId(),
-            number: featurePhases.reduce((max, entry) => Math.max(max, entry.number), 0) + 1,
+            number: await st.allocPhaseNumber(),
             shortId,
             priority,
             slug: normalizeSlug(title),
@@ -472,6 +479,8 @@ server.registerTool("planner-phase-add", {
             updatedAt: timestamp,
             handoff: "",
             handoffUpdatedAt: "",
+            handoffReadAt: "",
+            handoffHistory: [],
         };
         await st.savePhase(phase);
         if (feature) {
@@ -486,22 +495,24 @@ server.registerTool("planner-phase-add", {
     });
     if (!phase)
         return text("Phase creation failed.");
-    return writeAndSummarize(st, `Phase created: ${phase.id} — ${phase.title}`, { phase });
+    return writeAndSummarize(st, `✅ Phase created: ${formatPhaseRef(phase.number, feature?.number)} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}`);
 });
 server.registerTool("planner-phase-show", {
     description: "Show a phase by id or name.",
-    inputSchema: { phase: z.string().min(1).describe("Phase id or name") },
-}, async ({ phase: ref }) => {
+    inputSchema: { phase: z.string().min(1).describe("Phase ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the phase description. Default: compact identity only (saves tokens).") },
+}, async ({ phase: ref, full }) => {
     const st = await requireStore();
-    const phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
+    const features = (await st.loadFeatures()).features;
+    const phase = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!phase)
         return text(`Phase not found: ${ref}`);
-    return text(`${phase.title} (${phase.id}) — ${phase.status}; ${phase.tasks.length} tasks`, { phase });
+    const summary = `${phase.title} — ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}${phase.shortId ? ` · ${phase.shortId}` : ""} (${phase.status}; ${phase.tasks.length} tasks)`;
+    return text(full ? `${summary}\n\n${phase.description || ""}` : summary);
 });
 server.registerTool("planner-phase-discuss", {
     description: "Persist phase discovery fields and mark phase planned.",
     inputSchema: {
-        phase: z.string().min(1).describe("Phase id or name"),
+        phase: z.string().min(1).describe("Phase ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
         goal: z.string().optional(),
         summary: z.string().optional(),
         scope: z.string().optional(),
@@ -512,7 +523,8 @@ server.registerTool("planner-phase-discuss", {
     },
 }, async ({ phase: ref, ...updates }) => {
     const st = await requireStore();
-    const found = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
+    const features = (await st.loadFeatures()).features;
+    const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
     const phase = await st.updatePhase(found.id, (entry) => {
@@ -537,7 +549,7 @@ server.registerTool("planner-phase-discuss", {
         entry.updatedAt = nowISO();
         return entry;
     });
-    return writeAndSummarize(st, `Phase discussed/planned: ${phase.id} — ${phase.title}`, { phase });
+    return writeAndSummarize(st, `✅ Phase discussed/planned: ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}`);
 });
 server.registerTool("planner-phase-update", {
     description: "Update phase fields.",
@@ -551,7 +563,8 @@ server.registerTool("planner-phase-update", {
     },
 }, async ({ phase: ref, ...updates }) => {
     const st = await requireStore();
-    const found = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
+    const features = (await st.loadFeatures()).features;
+    const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
     const phase = await st.updatePhase(found.id, (entry) => {
@@ -568,7 +581,7 @@ server.registerTool("planner-phase-update", {
         entry.updatedAt = nowISO();
         return entry;
     });
-    return writeAndSummarize(st, `Phase updated: ${phase.id} — ${phase.title}`, { phase });
+    return writeAndSummarize(st, `✅ Phase updated: ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}`);
 });
 server.registerTool("planner-phase-delete", {
     description: "Delete a phase and unlink it from features.",
@@ -584,12 +597,13 @@ server.registerTool("planner-phase-delete", {
             feature.phaseIds = feature.phaseIds.filter((id) => id !== phase.id);
         return doc;
     });
-    return writeAndSummarize(st, `Phase deleted: ${phase.id}`, { deleted: phase.id });
+    const dFeat = (await st.loadFeatures()).features.find((f) => f.id === phase.featureId);
+    return writeAndSummarize(st, `Phase deleted: ${formatPhaseRef(phase.number, dFeat?.number)}${phase.shortId ? ` · ${phase.shortId}` : ""}`, { deleted: phase.id });
 });
 server.registerTool("planner-task-add", {
     description: "Create a task with a rich description. REQUIRED: description must include code references (file:line), what already exists vs what needs to be built, specific structs/traits/systems to modify, concrete implementation steps, and edge cases to handle. The description is the execution context for agents; one-liners cause misalignment.",
     inputSchema: {
-        phase: z.string().min(1).describe("Phase id or name"),
+        phase: z.string().min(1).describe("Phase ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
         title: z.string().min(1),
         description: z.string().min(50, "Description must be at least 50 characters — include code references (file:line), current state vs desired state, structs/traits to modify, concrete implementation steps, edge cases. Prefix with 'design-only' for pre-implementation design tasks.").describe("Required code references (file:line), current state vs desired state, structs/traits to modify, concrete implementation steps, edge cases. Not a one-liner."),
         checklist: z.array(z.string()).optional(),
@@ -606,7 +620,7 @@ server.registerTool("planner-task-add", {
     const task = {
         id: taskId,
         phaseId: found.id,
-        number: found.tasks.length + 1,
+        number: await st.allocTaskNumber(),
         shortId,
         priority,
         shortName: clampSlug(title, 30, `task-${Date.now().toString(36)}`),
@@ -625,23 +639,29 @@ server.registerTool("planner-task-add", {
         createdAt: timestamp,
         updatedAt: timestamp,
     };
-    const phase = await st.updatePhase(found.id, (entry) => {
+    await st.updatePhase(found.id, (entry) => {
         entry.tasks.push(task);
         entry.taskIds.push(task.id);
         entry.updatedAt = timestamp;
         return entry;
     });
-    return writeAndSummarize(st, `Task created: ${task.id} — ${task.title}`, { task, phase });
+    const features = (await st.loadFeatures()).features;
+    return writeAndSummarize(st, `✅ Task created: ${taskCompositeRef(task, found, features)} — ${task.title} (planned)${task.shortId ? ` · ${task.shortId}` : ""}`);
 });
 server.registerTool("planner-task-show", {
     description: "Show a task by id or name.",
-    inputSchema: { task: z.string().min(1).describe("Task id or name") },
-}, async ({ task: ref }) => {
+    inputSchema: { task: z.string().min(1).describe("Task ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the task description + statusLog. Default: compact identity only (saves tokens).") },
+}, async ({ task: ref, full }) => {
     const st = await requireStore();
-    const found = findTaskByRef(await st.loadAllPhases(), ref);
+    const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
-    return text(`${found.task.title} (${found.task.id}) — ${found.task.status}; phase ${found.phase.id}`, { task: found.task, phase: found.phase });
+    const features = (await st.loadFeatures()).features;
+    const summary = `${found.task.title} — ${taskCompositeRef(found.task, found.phase, features)}${found.task.shortId ? ` · ${found.task.shortId}` : ""} (${found.task.status}; phase ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))})`;
+    if (!full)
+        return text(summary);
+    const log = (found.task.statusLog ?? []).map((e) => `  - ${e.date.slice(0, 10)} ${e.title}`).join("\n");
+    return text(`${summary}\n\n${found.task.description || ""}${log ? `\n\nStatus log:\n${log}` : ""}`);
 });
 server.registerTool("planner-task-discuss", {
     description: "Persist task execution notes/checklist.",
@@ -652,7 +672,7 @@ server.registerTool("planner-task-discuss", {
     },
 }, async ({ task: ref, description, checklist }) => {
     const st = await requireStore();
-    const found = findTaskByRef(await st.loadAllPhases(), ref);
+    const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
     let updatedTask;
@@ -669,7 +689,9 @@ server.registerTool("planner-task-discuss", {
         updatedTask = task;
         return phase;
     });
-    return writeAndSummarize(st, `Task discussed/updated: ${found.task.id}`, { task: updatedTask ?? found.task });
+    const features = (await st.loadFeatures()).features;
+    const t = updatedTask ?? found.task;
+    return writeAndSummarize(st, `✅ Task discussed/updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}`);
 });
 server.registerTool("planner-task-update", {
     description: "Update task fields. A motivation is REQUIRED when changing to blocked, canceled, deferred, rejected, waiting, or back to planned from another status.",
@@ -683,7 +705,7 @@ server.registerTool("planner-task-update", {
     },
 }, async ({ task: ref, title, status, description, motivation, priority }) => {
     const st = await requireStore();
-    const found = findTaskByRef(await st.loadAllPhases(), ref);
+    const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
     // Validate motivation requirement for status transitions.
@@ -724,14 +746,16 @@ server.registerTool("planner-task-update", {
         return phase;
     });
     await st.syncTaskStatusRollup(found.phase.id);
-    return writeAndSummarize(st, `Task updated: ${found.task.id}`, { task: updatedTask ?? found.task });
+    const features = (await st.loadFeatures()).features;
+    const t = updatedTask ?? found.task;
+    return writeAndSummarize(st, `✅ Task updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}`);
 });
 server.registerTool("planner-task-delete", {
     description: "Delete a task.",
     inputSchema: { task: z.string().min(1) },
 }, async ({ task: ref }) => {
     const st = await requireStore();
-    const found = findTaskByRef(await st.loadAllPhases(), ref);
+    const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
     await st.updatePhase(found.phase.id, (phase) => {
@@ -741,23 +765,30 @@ server.registerTool("planner-task-delete", {
         return phase;
     });
     await st.syncTaskStatusRollup(found.phase.id);
-    return writeAndSummarize(st, `Task deleted: ${found.task.id}`, { deleted: found.task.id });
+    const tdFeatures = (await st.loadFeatures()).features;
+    return writeAndSummarize(st, `Task deleted: ${taskCompositeRef(found.task, found.phase, tdFeatures)}${found.task.shortId ? ` · ${found.task.shortId}` : ""}`, { deleted: found.task.id });
 });
 server.registerTool("planner-task-start", {
     description: "Set a task to in-progress.",
     inputSchema: { task: z.string().min(1) },
 }, async ({ task: ref }) => {
     const st = await requireStore();
-    // Hygiene notice (non-blocking): surface an existing handoff but never block
-    // task_start — the handoff is a captured-context artifact, not a lock (e.g. a
-    // small modification after writing a handoff should start without forcing
-    // deletion, which would lose context).
-    const handoffNotice = (await st.listHandoffs()).length > 0
-        ? "ℹ️  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.\n"
-        : "";
-    const found = findTaskByRef(await st.loadAllPhases(), ref);
+    const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
+    // 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).
+    const allHandoffs = await st.listHandoffs();
+    let handoffNotice = "";
+    if ((found.phase.handoff ?? "") !== "") {
+        await st.clearPhaseHandoff(found.phase.id, "task-started").catch(() => { });
+        handoffNotice = "📦 Archived handoff for this phase (task started) — recover via planner-handoff-list + .planner/handoff-archive/.\n";
+    }
+    const _otherHandoffs = allHandoffs.filter((h) => h.phaseId !== found.phase.id);
+    if (_otherHandoffs.length > 0) {
+        handoffNotice += `ℹ️  ${_otherHandoffs.length} other phase handoff(s) pending — review with planner-handoff-list if relevant.\n`;
+    }
     const timestamp = nowISO();
     let updatedTask;
     await st.updatePhase(found.phase.id, (phase) => {
@@ -782,7 +813,9 @@ server.registerTool("planner-task-start", {
         return phase;
     });
     await st.syncTaskStatusRollup(found.phase.id);
-    return writeAndSummarize(st, `${handoffNotice}✅ Task started: ${found.task.id}`, { task: updatedTask ?? found.task });
+    const features = (await st.loadFeatures()).features;
+    const t = updatedTask ?? found.task;
+    return writeAndSummarize(st, `${handoffNotice}✅ Task started: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (in-progress)${t.shortId ? ` · ${t.shortId}` : ""}`);
 });
 server.registerTool("planner-task-complete", {
     description: "Set a task to done. Fails if checklist is incomplete unless force=true.",
@@ -793,7 +826,7 @@ server.registerTool("planner-task-complete", {
     },
 }, async ({ task: ref, force, description_update }) => {
     const st = await requireStore();
-    const found = findTaskByRef(await st.loadAllPhases(), ref);
+    const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
     const unchecked = found.task.checklist.filter((item) => !item.checked);
@@ -827,7 +860,9 @@ server.registerTool("planner-task-complete", {
         return phase;
     });
     const clearedRef = await st.syncTaskStatusRollup(found.phase.id);
-    return writeAndSummarize(st, `✅ Task completed: ${found.task.id}${clearedRef ? ` — phase handoff auto-cleared (${clearedRef})` : ""}`, { task: updatedTask ?? found.task });
+    const features = (await st.loadFeatures()).features;
+    const t = updatedTask ?? found.task;
+    return writeAndSummarize(st, `✅ Task completed: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (done)${t.shortId ? ` · ${t.shortId}` : ""}${clearedRef ? ` — phase handoff auto-cleared (${clearedRef})` : ""}`);
 });
 server.registerTool("planner-handoff-list", {
     description: "List all phases with a non-empty entity-scoped handoff (phase.handoff field). Returns composite refs (P00x / P00x(F00x)) with the first line and last-updated time.",
@@ -881,8 +916,8 @@ server.registerTool("planner-handoff-clear", {
     const r = await resolvePhaseForHandoff(st, phaseRef);
     if (!r.ok)
         return text(`❌ ${r.error}`);
-    await st.clearPhaseHandoff(r.phase.id);
-    return text(`✅ Cleared handoff on ${r.compositeRef}. (handoffUpdatedAt preserved as audit)`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
+    await st.clearPhaseHandoff(r.phase.id, "manual");
+    return text(`✅ Cleared handoff on ${r.compositeRef} (handoffUpdatedAt preserved as audit; archived to .planner/handoff-archive/).`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
 server.registerTool("planner-web", {
     description: "Manage the planner web dashboard (start/status/stop) from MCP stdio. Runs an in-process HTTP+WS server bound to LAN; it lives as long as this MCP process. plan-root comes from AGENT_PLAN_ROOT or cwd()/.planner.",
@@ -931,7 +966,7 @@ server.registerTool("planner-load", {
     if (!(await st.exists()))
         return text("No .planner/ found at " + planRoot() + ". Run planner-init first.");
     const web = await ensureWebStarted();
-    const recap = await buildRecapText(st, web);
+    const recap = await buildRecap(st, web, { harness: "mcp" });
     return text(recap);
 });
 server.registerTool("planner-disable", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/mcp",
-  "version": "0.2.19-next.0",
+  "version": "0.2.19-next.10",
   "private": false,
   "description": "MCP server for Agent Plan, exposing planner-* tools over stdio.",
   "license": "MIT",
@@ -41,8 +41,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
     "zod": "^3.24.0",
-    "@agent-plan/core": "0.2.19-next.0",
-    "@agent-plan/server": "0.2.19-next.0"
+    "@agent-plan/core": "0.2.19-next.10",
+    "@agent-plan/server": "0.2.19-next.10"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",