@agent-plan/mcp 0.2.27 → 0.2.29

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1437,10 +1437,7 @@ server.registerTool("planner-phase-update", {
     const staleParentRefs = descriptionFreshness?.diagnostics
         .filter((entry) => entry.state === "stale" && entry.ownerId === persisted.featureId)
         .map((entry) => entry.ownerRef) ?? [];
-    const freshnessNotice = staleParentRefs.length > 0
-        ? `\n⚠️ Parent description review required: ${staleParentRefs.join(", ")}. Run planner-description-freshness for the non-mutating reconciliation preview.`
-        : "";
-    return text(`✅ Phase updated: ${formatPhaseRef(persisted.number, featureNumberOfPhase(persisted, refreshedFeatures))} — ${persisted.title}${persisted.shortId ? ` · ${persisted.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.${freshnessNotice}`, { phase: persisted, updated: true, updatedFields: receivedFields, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) });
+    return text(`✅ Phase updated: ${formatPhaseRef(persisted.number, featureNumberOfPhase(persisted, refreshedFeatures))} — ${persisted.title}${persisted.shortId ? ` · ${persisted.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`, { phase: persisted, updated: true, updatedFields: receivedFields, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) });
 });
 server.registerTool("planner-phase-delete", {
     description: "Delete a phase and unlink it from features.",
@@ -1748,60 +1745,62 @@ server.registerTool("planner-task-update", {
     }
     let updatedTask;
     const timestamp = nowISO();
-    await st.updatePhase(found.phase.id, (phase) => {
-        const task = phase.tasks.find((entry) => entry.id === found.task.id);
-        if (!task)
-            return phase;
-        if (title !== undefined)
-            task.title = title.trim();
-        if (priority !== undefined)
-            task.priority = priority;
-        if (description !== undefined)
-            task.description = description.trim();
-        if (rawDescriptionRef !== undefined) {
-            const descriptionRef = normalizeDescriptionRef(rawDescriptionRef);
-            if (descriptionRef)
-                task.descriptionRef = descriptionRef;
-            else
-                delete task.descriptionRef;
-        }
-        if (notes !== undefined)
-            task.notes = notes.trim();
-        if (decisions !== undefined)
-            task.decisions = decisions.map((item) => item.trim()).filter(Boolean);
-        if (checklist !== undefined) {
-            task.checklist = checklist.map((item, index) => ({
-                id: createChecklistItemId(task.id, index + 1, item),
-                number: index + 1,
-                title: item.trim(),
-                checked: false,
-            }));
-        }
-        if (subtasks !== undefined) {
-            const existingIds = new Set(task.subtasks.map((item) => item.id));
-            if (subtasks.some((item) => item.id !== undefined && !existingIds.has(item.id))) {
-                throw new PlanStoreError("Subtask IDs must belong to the target task.", undefined, { errorCode: "SUBTASK_ID_INVALID" });
+    try {
+        await st.updateTask(found.phase.id, found.task.id, (task) => {
+            if (title !== undefined)
+                task.title = title.trim();
+            if (priority !== undefined)
+                task.priority = priority;
+            if (description !== undefined)
+                task.description = description.trim();
+            if (rawDescriptionRef !== undefined) {
+                const descriptionRef = normalizeDescriptionRef(rawDescriptionRef);
+                if (descriptionRef)
+                    task.descriptionRef = descriptionRef;
+                else
+                    delete task.descriptionRef;
             }
-            task.subtasks = subtasks.map((item) => ({ id: item.id ?? randomUUID(), title: item.title.trim(), description: item.description?.trim() ?? "", status: item.status ?? "planned", createdAt: task.subtasks.find((candidate) => candidate.id === item.id)?.createdAt ?? timestamp, updatedAt: timestamp }));
-        }
-        if (status !== undefined && status !== task.status) {
-            // Record status change in the incremental statusLog.
-            const entry = {
-                id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${task.status}-${status}`),
-                date: timestamp,
-                fromStatus: task.status,
-                toStatus: status,
-                title: motivation?.split("\n")[0]?.trim() || `${task.status} → ${status}`,
-                description: motivation?.trim() || "",
-            };
-            task.statusLog = [...(task.statusLog ?? []), entry];
-            applyTaskLifecycleDates(task, status, timestamp);
-        }
-        task.updatedAt = timestamp;
-        phase.updatedAt = timestamp;
-        updatedTask = task;
-        return phase;
-    });
+            if (notes !== undefined)
+                task.notes = notes.trim();
+            if (decisions !== undefined)
+                task.decisions = decisions.map((item) => item.trim()).filter(Boolean);
+            if (checklist !== undefined) {
+                task.checklist = checklist.map((item, index) => ({
+                    id: createChecklistItemId(task.id, index + 1, item),
+                    number: index + 1,
+                    title: item.trim(),
+                    checked: false,
+                }));
+            }
+            if (subtasks !== undefined) {
+                const existingIds = new Set(task.subtasks.map((item) => item.id));
+                if (subtasks.some((item) => item.id !== undefined && !existingIds.has(item.id))) {
+                    throw new PlanStoreError("Subtask IDs must belong to the target task.", undefined, { errorCode: "SUBTASK_ID_INVALID" });
+                }
+                task.subtasks = subtasks.map((item) => ({ id: item.id ?? randomUUID(), title: item.title.trim(), description: item.description?.trim() ?? "", status: item.status ?? "planned", createdAt: task.subtasks.find((candidate) => candidate.id === item.id)?.createdAt ?? timestamp, updatedAt: timestamp }));
+            }
+            if (status !== undefined && status !== task.status) {
+                // Record status change in the incremental statusLog.
+                const entry = {
+                    id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${task.status}-${status}`),
+                    date: timestamp,
+                    fromStatus: task.status,
+                    toStatus: status,
+                    title: motivation?.split("\n")[0]?.trim() || `${task.status} → ${status}`,
+                    description: motivation?.trim() || "",
+                };
+                task.statusLog = [...(task.statusLog ?? []), entry];
+                applyTaskLifecycleDates(task, status, timestamp);
+            }
+            task.updatedAt = timestamp;
+            updatedTask = task;
+            return task;
+        });
+    }
+    catch (error) {
+        const details = error instanceof PlanStoreError ? error.details : undefined;
+        return { ...text(`Task update failed: ${error instanceof Error ? error.message : "unknown error"}`, { updated: false, errorCode: details?.errorCode ?? "TASK_UPDATE_FAILED" }), isError: true };
+    }
     await st.syncTaskStatusRollup(found.phase.id);
     const features = (await st.loadFeatures()).features;
     const t = updatedTask ?? found.task;
@@ -1827,13 +1826,10 @@ server.registerTool("planner-task-update", {
     const staleParentRefs = descriptionFreshness?.diagnostics
         .filter((entry) => entry.state === "stale" && ownerIds.has(entry.ownerId))
         .map((entry) => entry.ownerRef) ?? [];
-    const freshnessNotice = staleParentRefs.length > 0
-        ? `\n⚠️ Parent description review required: ${staleParentRefs.join(", ")}. Run planner-description-freshness for the non-mutating reconciliation preview.`
-        : "";
     const details = resumeRequired
         ? { task: t, updated: true, updatedFields: receivedFields, resumeRequired, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) }
         : { task: t, updated: true, updatedFields: receivedFields, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) };
-    return writeAndSummarize(st, `✅ Task updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.${freshnessNotice}${resumeNotice}`, details);
+    return writeAndSummarize(st, `✅ Task updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.${resumeNotice}`, details);
 });
 server.registerTool("planner-task-checklist-toggle", {
     description: "Tick/untick a task checklist item (a 'step') without rewriting the whole list. Accepts the item as C{n} (e.g. C2), the item id, or the title (case-insensitive, first match). Pass checked=true/false to set explicitly, or omit to toggle. Use this instead of writing DONE in step titles. Items are numbered C1/C2… per task.",
@@ -2564,8 +2560,8 @@ server.registerTool("planner-handoff-show", {
         && phase.handoffAudit.contentLength === phase.handoff.length);
     const resumeReady = persistenceVerified && Boolean(phase.handoffAudit?.resumeReadyAt);
     const status = resumeReady
-        ? "Resume-ready: persisted read-back and source reconciliation completed."
-        : "NOT resume-ready: after reading this entire persisted body, call planner-handoff-verify with its contentHash and a fresh comparison against every required source. If any gap exists, rewrite instead of verifying.";
+        ? "Resume-ready: persisted compact capsule read-back completed."
+        : "NOT resume-ready: after reading this persisted capsule, call planner-handoff-verify with its contentHash. The planner derives legacy evidence from persisted state; rewrite only if the capsule itself omits resume-critical context.";
     return text(`Handoff for ${r.compositeRef}\n${status}\nContent hash: ${contentHash}\n\n${phaseWorkMap.content}\n\nBefore proposing new work, reread the canonical phase and relevant sibling task full view; do not duplicate an already-owned capability.\n\n${bounded.content}`, {
         phaseRef: r.compositeRef,
         phaseId: r.phase.id,
@@ -2579,15 +2575,15 @@ server.registerTool("planner-handoff-show", {
     });
 });
 server.registerTool("planner-handoff-verify", {
-    description: "Finalize one persisted handoff as resume-ready only after planner-handoff-show has displayed the entire body and the agent has compared it again with conversation corrections, planner entities, working tree/diff, verification/runtime evidence, and peer output. Any discovered omission blocks verification and requires prepare+rewrite.",
+    description: "Finalize one persisted handoff as resume-ready after planner-handoff-show confirms the persisted compact resume capsule. Legacy sourceReviews and omissionsFound evidence remains accepted but is optional; the planner derives omitted evidence from persisted state.",
     inputSchema: {
         phaseRef: z.string().min(1),
         expectedContentHash: z.string().regex(/^[a-f0-9]{64}$/),
         sourceReviews: z.array(z.object({
             source: z.enum(["conversation", "planner-entities", "working-tree", "verification-runtime", "peer-agent-output"]),
             detail: z.string().min(12),
-        })),
-        omissionsFound: z.array(z.string().min(1)),
+        })).optional().describe("Optional legacy evidence; omitted for compact handoffs."),
+        omissionsFound: z.array(z.string().min(1)).optional().describe("Optional read-back gaps; omit when the persisted capsule is complete."),
     },
 }, async ({ phaseRef, expectedContentHash, sourceReviews, omissionsFound }) => {
     const st = await requireStore();
@@ -2595,7 +2591,11 @@ server.registerTool("planner-handoff-verify", {
     if (!r.ok)
         return text(`❌ ${r.error}`, { resumeReady: false });
     try {
-        const result = await st.verifyPhaseHandoffReadBack(r.phase.id, { expectedContentHash, sourceReviews, omissionsFound });
+        const result = await st.verifyPhaseHandoffReadBack(r.phase.id, {
+            expectedContentHash,
+            ...(sourceReviews ? { sourceReviews } : {}),
+            ...(omissionsFound ? { omissionsFound } : {}),
+        });
         await st.writeGenerated();
         return text(`✅ Handoff on ${r.compositeRef} is resume-ready after persisted read-back and source reconciliation.`, {
             phaseRef: r.compositeRef,
@@ -2881,7 +2881,7 @@ server.registerTool("planner-idea-promotion-finalize", {
     return text(`Idea promoted: ${formatIdeaRef(promoted.number)} → ${promoted.promotion.targetRef}`, { idea: promoted, promoted: true, targetRef: promoted.promotion.targetRef });
 });
 server.registerTool("planner-handoff-write", {
-    description: "Persist a reconciled handoff candidate with durable context synchronization and mandatory audits. The result always has resumeReady=false until a separate planner-handoff-show read-back and planner-handoff-verify source reconciliation succeeds. Run planner-handoff-prepare first; link extended detail from committed .planner/docs/ Markdown.",
+    description: "Persist a compact reconciled handoff candidate with durable context synchronization. The result always has resumeReady=false until a separate planner-handoff-show read-back and planner-handoff-verify succeeds. Run planner-handoff-prepare first; provide only resume-critical context and link optional extended detail from .planner/docs/ Markdown.",
     inputSchema: {
         phaseRef: z.string().min(1).describe("Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title."),
         title: z.string().min(3).optional().describe("Meaningful handoff title summarizing the work."),
@@ -2897,7 +2897,7 @@ server.registerTool("planner-handoff-write", {
                 status: z.enum(["captured", "not-applicable"]),
                 detail: z.string().min(1),
             })),
-        }).optional().describe("Mandatory for confirmed writes; every category from planner-handoff-prepare must be present."),
+        }).optional().describe("Optional legacy completeness evidence. Compact handoffs omit this duplicate prose."),
         coldStartInventory: z.object({
             version: z.literal(HANDOFF_COLD_START_INVENTORY_VERSION),
             sourceReviews: z.array(z.object({ source: z.string().min(1), detail: z.string().min(1) })),
@@ -2906,7 +2906,7 @@ server.registerTool("planner-handoff-write", {
                 items: z.array(z.string().min(1)),
                 notApplicableReason: z.string().min(1).optional().describe("Optional explanation only; every category still requires a concrete item, using an explicit verified-negative statement when nothing exists."),
             })),
-        }).optional().describe("Mandatory for confirmed writes. Every concrete item must appear verbatim in the handoff or a validated supporting document."),
+        }).optional().describe("Optional legacy cold-start evidence. Compact handoffs omit this duplicate prose."),
         supportingDocuments: z.array(z.object({
             path: z.string().min(1).describe("Committed Markdown path under .planner/docs/."),
             description: z.string().min(1).describe("What the document contains and why the next agent needs it."),
@@ -2993,7 +2993,7 @@ server.registerTool("planner-handoff-write", {
             },
         });
         await st.writeGenerated();
-        return text(`⚠️ Handoff candidate persisted on ${r.compositeRef}, but it is NOT resume-ready yet. Required next action: call planner-handoff-show ${r.compositeRef}, read the entire persisted body, compare it again with every required source, then call planner-handoff-verify with the returned contentHash. If that review finds any gap, run prepare+write again instead of verifying.`, {
+        return text(`⚠️ Handoff candidate persisted on ${r.compositeRef}, but it is NOT resume-ready yet. Required next action: call planner-handoff-show ${r.compositeRef}, read the persisted compact capsule, then call planner-handoff-verify with the returned contentHash. Rewrite only if resume-critical context is missing.`, {
             phaseRef: r.compositeRef,
             phaseId: r.phase.id,
             updatedTaskIds: result.updatedTaskIds,
@@ -3004,8 +3004,7 @@ server.registerTool("planner-handoff-write", {
             verificationRequired: true,
             nextActions: [
                 `Call planner-handoff-show ${r.compositeRef} and read the entire persisted body.`,
-                "Compare the persisted body against conversation corrections, planner entities, working tree/diff, verification/runtime evidence, and peer-agent output.",
-                "If any omission exists, run planner-handoff-prepare and planner-handoff-write again; otherwise call planner-handoff-verify with the shown contentHash.",
+                "Call planner-handoff-verify with the shown contentHash; legacy sourceReviews and omissionsFound are optional because the planner derives omitted evidence from persisted state.",
             ],
         });
     }
@@ -3017,7 +3016,7 @@ server.registerTool("planner-handoff-write", {
     }
 });
 server.registerTool("planner-handoff-prepare", {
-    description: "Identify or audit the exact handoff target. With a confirmed phaseRef, returns the canonical scaffold, a bounded priority-ordered phase work map with sibling goals/dependencies/capability ownership, the current token, missing task evidence, mandatory audits, and the 24,000-character inline budget. Reread the canonical phase and relevant sibling tasks before proposing work.",
+    description: "Identify or prepare the exact handoff target. With a confirmed phaseRef, returns a compact resume scaffold, bounded priority-ordered phase work map, current token, missing task evidence, and inline budget. Reread the canonical phase and relevant sibling tasks before proposing work.",
     inputSchema: { phaseRef: z.string().min(1).optional() },
 }, async ({ phaseRef }) => {
     if (!phaseRef)
@@ -3032,9 +3031,10 @@ server.registerTool("planner-handoff-prepare", {
         return text(`❌ ${r.error}`);
     try {
         const audit = await st.preparePhaseHandoff(r.phase.id);
+        const { completenessCategories: _completenessCategories, coldStartSourceReviews: _coldStartSourceReviews, coldStartInventoryCategories: _coldStartInventoryCategories, ...compactAudit } = audit;
         const missing = audit.missingCompletionTasks.map((task) => `- T${String(task.number).padStart(3, "0")} — ${task.title}`).join("\n") || "- None";
         return text([
-            `Handoff preparation audit for ${r.compositeRef}`,
+            `Handoff preparation for ${r.compositeRef}`,
             `Base handoffUpdatedAt: ${audit.handoffUpdatedAt || "(empty)"}`,
             "Required human inputs before drafting:",
             ...audit.requiredHumanInputs.map((input) => `- ${input.id} — ${input.description}`),
@@ -3045,18 +3045,18 @@ server.registerTool("planner-handoff-prepare", {
             "Done tasks missing durable completion/verification evidence:",
             missing,
             "",
-            `Required completeness audit v${audit.completenessVersion} — every category must be captured or marked not-applicable with a substantive reason:`,
-            ...audit.completenessCategories.map((entry) => `- ${entry.id} — ${entry.label}`),
-            "",
-            `Required cold-start source review v${audit.coldStartInventoryVersion} — inspect and substantively summarize every source before drafting:`,
-            ...audit.coldStartSourceReviews.map((entry) => `- ${entry.id} — ${entry.label}`),
-            "Required cold-start inventory — every category needs a concrete item (use an explicit verified-negative statement when nothing exists), and every item must appear verbatim in the handoff or a validated supporting document:",
-            ...audit.coldStartInventoryCategories.map((entry) => `- ${entry.id} — ${entry.label}`),
-            `Maximum canonical inline content: ${audit.maxContentChars} characters. Link extended material from .planner/docs/.`,
+            "Compact handoff contract: include only the exact focus/resume point, current or partial state, constraints, blockers, decisions, verification, and ordered next actions needed by the next agent.",
+            "No Markdown heading is mandatory: concise free-form resume prose is accepted. Use headings only when they make the capsule clearer.",
+            "Completeness audit and cold-start evidence are planner-owned metadata; do not copy their categories or source reviews into Markdown.",
+            `Inline target: ${audit.targetContentChars} characters; absolute compatibility ceiling: ${audit.maxContentChars}. Extended detail is externalized automatically when needed.`,
             "",
             "Existing active handoff (reconcile all still-relevant content):",
             audit.handoff.trim() || "(none)",
-        ].join("\n"), { phaseRef: r.compositeRef, ...audit });
+        ].join("\n"), {
+            phaseRef: r.compositeRef,
+            ...compactAudit,
+            evidenceContract: "Planner-owned completeness and cold-start evidence is derived from persisted state; no category inventory is required from the agent.",
+        });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/package.json

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