@agent-plan/mcp 0.2.22 → 0.2.23-next.0

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -3,15 +3,32 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { pathToFileURL } from "node:url";
-import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask, packageVersionFromModule, resolvedPackageVersion } from "@agent-plan/core";
+import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, markFeatureReadForSessionId, markPhaseReadForSessionId, markTaskReadForSessionId, contextReadEligibilityForSession, hasValidSessionAttestation, hasReadRequirementsForSession, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded } from "@agent-plan/core";
 import { serve } from "@agent-plan/server";
 import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, validateResolvedTarget } from "@agent-plan/core/naming";
-const STATUS_VALUES = ["planned", "in-progress", "paused", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
+const STATUS_VALUES = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
 const PHASE_STATUS_VALUES = ["draft", "discovery", ...STATUS_VALUES];
+const plannerSessionId = randomUUID();
+startReadSession(plannerSessionId);
 function text(textValue, structuredContent) {
     return structuredContent ? { content: [{ type: "text", text: textValue }], structuredContent } : { content: [{ type: "text", text: textValue }] };
 }
+function taskStartError(outcome, structuredContent = {}) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: [
+                    `❌ TASK START FAILED [${outcome.errorCode}]`,
+                    "started: false",
+                    outcome.message,
+                    "No task lifecycle transition was applied.",
+                    "Next required actions:",
+                    ...outcome.nextActions.map((action, index) => `${index + 1}. ${action}`),
+                ].join("\n") }],
+        structuredContent: { ...outcome, ...structuredContent },
+    };
+}
 const MCP_PACKAGE = packageVersionFromModule(import.meta.url, "@agent-plan/mcp");
 const CORE_PACKAGE = resolvedPackageVersion("@agent-plan/core", import.meta.url);
 function nowISO() {
@@ -431,6 +448,7 @@ server.registerTool("planner-feature-add", {
         phaseIds: [],
         dependsOn: [],
         statusLog: [],
+        sessionInfo: [],
         createdAt: timestamp,
         updatedAt: timestamp,
     };
@@ -450,6 +468,8 @@ server.registerTool("planner-feature-show", {
     if (!resolvedFeature.ok)
         return text(resolvedFeature.error);
     const feature = resolvedFeature.feature;
+    if (full)
+        markFeatureReadForSessionId(plannerSessionId, feature.id);
     const phases = (await st.loadAllPhases()).filter((phase) => phase.featureId === feature.id);
     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);
@@ -632,6 +652,7 @@ server.registerTool("planner-phase-add", {
             handoffReadAt: "",
             handoffHistory: [],
             statusLog: [],
+            sessionInfo: [],
         };
         await st.savePhase(phase);
         if (feature) {
@@ -657,6 +678,8 @@ server.registerTool("planner-phase-show", {
     const phase = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!phase)
         return text(`Phase not found: ${ref}`);
+    if (full)
+        markPhaseReadForSessionId(plannerSessionId, phase.id);
     const linkedRequirements = await st.linkedRequirementsForPhase(phase.id);
     const reqCount = linkedRequirements.length;
     const summary = `${phase.title} — ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}${phase.shortId ? ` · ${phase.shortId}` : ""} (${phase.status}; ${phase.tasks.length} tasks${reqCount ? `; ${reqCount} linked requirement${reqCount === 1 ? "" : "s"}` : ""})`;
@@ -818,6 +841,7 @@ server.registerTool("planner-task-add", {
         descriptionUpdatedAt: timestamp,
         notes: "",
         statusLog: [],
+        sessionInfo: [],
         decisions: [],
         acceptedDecisions: [],
         checklist: (checklist ?? []).map((item, index) => ({ id: createChecklistItemId(taskId, index + 1, item), number: index + 1, title: item, checked: false })),
@@ -841,18 +865,44 @@ server.registerTool("planner-task-add", {
 });
 server.registerTool("planner-task-show", {
     description: "Show a task by id or name.",
-    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).") },
+    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, resume checkpoint/advisory, and statusLog. Default: compact identity only (saves tokens).") },
 }, async ({ task: ref, full }) => {
     const st = await requireStore();
     const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
+    if (full)
+        markTaskReadForSessionId(plannerSessionId, found.task.id);
     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 project = await st.loadProject();
+    const pendingDeviation = found.task.status === "done" || found.task.status === "canceled" || found.task.status === "rejected"
+        ? undefined
+        : project.workDeviations
+            .filter((deviation) => deviation.resumeTaskId === found.task.id
+            && (deviation.state === "resume-required" || deviation.state === "resolved"))
+            .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+    const snapshot = found.task.pauseSnapshot ?? pendingDeviation?.snapshot ?? null;
     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}` : ""}`);
+    const sections = [summary];
+    if (found.task.description?.trim())
+        sections.push(found.task.description.trim());
+    if (snapshot || pendingDeviation) {
+        sections.push([
+            pendingDeviation
+                ? "Resume advisory: this task has a saved checkpoint that should be evaluated before selecting other work."
+                : "Resume checkpoint:",
+            snapshot ? `Checkpoint reason: ${snapshot.reason}` : "",
+            snapshot ? `Work checkpoint: ${snapshot.whatWasBeingDone}` : "",
+            snapshot ? `Resume from: ${snapshot.resumeLocation}` : "",
+            snapshot ? `How to resume: ${snapshot.howToResume}` : "",
+        ].filter(Boolean).join("\n"));
+    }
+    if (log)
+        sections.push(`Status log:\n${log}`);
+    return text(sections.join("\n\n"));
 });
 server.registerTool("planner-task-discuss", {
     description: "Persist task execution notes/checklist.",
@@ -902,8 +952,11 @@ server.registerTool("planner-task-update", {
     const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
-    if (status === "paused") {
-        return text("Use planner-task-pause or planner-task-switch to enter paused state; a structured resume checkpoint is mandatory.");
+    if (status === "in-progress" && status !== found.task.status) {
+        return text("Task start/resume transitions require planner-task-start so lifecycle state, checkpoints, and return stacks remain consistent.");
+    }
+    if (status === "done" && status !== found.task.status) {
+        return text("Task completion transitions require planner-task-complete with durable completion and verification evidence.");
     }
     // Validate motivation requirement for status transitions.
     if (status !== undefined && needsMotivation(found.task.status, status)) {
@@ -1082,12 +1135,12 @@ server.registerTool("planner-task-delete", {
     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-recommend", {
-    description: "Return the harness-agnostic recommended task: continue one active task, otherwise choose ready work by feature → phase → task priority. Reports dependency, availability, and approved deviation/resume context without starting or blocking work.",
+    description: "Return the harness-agnostic recommended task: continue one active task or the current phase, otherwise choose ready work by feature → phase → task priority. Reports dependency, availability, and approved deviation/resume context without starting or blocking work.",
     inputSchema: {},
 }, async () => {
     const st = await requireStore();
-    const [features, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
-    const result = recommendNextTask(features.features, phases, project.workDeviations);
+    const [features, phases, project, resume] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject(), st.loadResume()]);
+    const result = recommendNextTask(features.features, phases, project.workDeviations, resume?.currentPhaseId);
     if (!result.candidate)
         return text(`No task recommendation: ${result.reason}`, { kind: result.kind, reason: result.reason, activeTaskIds: result.activeCandidates?.map((candidate) => candidate.task.id) ?? [] });
     const { candidate } = result;
@@ -1101,11 +1154,11 @@ server.registerTool("planner-task-deviation", {
     inputSchema: { temporary_task: z.string().min(1), resume_task: z.string().min(1).optional(), reason: z.string().min(1) },
 }, async ({ temporary_task, resume_task, reason }) => {
     const st = await requireStore();
-    const [features, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
+    const [features, phases, project, focus] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject(), st.loadResume()]);
     const temporary = findTaskByRef(phases, features.features, temporary_task);
     if (!temporary)
         return text(`Task not found: ${temporary_task}`);
-    const selected = recommendNextTask(features.features, phases, project.workDeviations);
+    const selected = recommendNextTask(features.features, phases, project.workDeviations, focus?.currentPhaseId);
     const resume = resume_task ? findTaskByRef(phases, features.features, resume_task) : selected.candidate;
     if (!resume)
         return text(`No resume task is available. Provide resume_task explicitly. ${selected.reason}`);
@@ -1146,7 +1199,8 @@ server.registerTool("planner-task-pause", {
         resumeLocation: resume_location, howToResume: how_to_resume, relatedTaskId: "",
         pausedAt: nowISO(), pausedBy: paused_by?.trim() ?? "",
     };
-    const paused = await st.pauseTask(found.phase.id, found.task.id, snapshot);
+    invalidateReads(plannerSessionId);
+    const checkpointed = await st.pauseTask(found.phase.id, found.task.id, snapshot);
     await st.syncTaskStatusRollup(found.phase.id);
     const activeDeviation = (await st.loadProject()).workDeviations
         .filter((deviation) => (deviation.state === "approved" || deviation.state === "active")
@@ -1161,15 +1215,15 @@ server.registerTool("planner-task-pause", {
         ? `\n↩️ RESUME REQUIRED: ${taskCompositeRef(resume.task, resume.phase, features)} — ${resume.task.title}`
         : "";
     return writeAndSummarize(st, [
-        `⏸️ Task paused: ${taskCompositeRef(paused, found.phase, features)} — ${paused.title}`,
+        `💾 Resume checkpoint saved: ${taskCompositeRef(checkpointed, found.phase, features)} — ${checkpointed.title}`,
         `Why: ${snapshot.reason}`,
         `Checkpoint: ${snapshot.whatWasBeingDone}`,
         `Resume from: ${snapshot.resumeLocation}`,
         `How to resume: ${snapshot.howToResume}${resumeNotice}`,
-    ].join("\n"), { task: paused, snapshot, ...(resume ? { resumeRequired: { taskId: resume.task.id } } : {}) });
+    ].join("\n"), { task: checkpointed, snapshot, ...(resume ? { resumeRequired: { taskId: resume.task.id } } : {}) });
 });
 server.registerTool("planner-task-switch", {
-    description: "Atomically switch from active work to a temporary task, even outside normal priority order. Pauses the source with a mandatory snapshot, starts the target, and pushes a durable LIFO return target.",
+    description: "Atomically switch from active work to a temporary task, even outside normal priority order. Reuse the target's valid sessionInfo context or require the exact full tree when missing or stale. Pause the source with a mandatory snapshot, start the target, and push a durable LIFO return target.",
     inputSchema: {
         from_task: z.string().min(1),
         to_task: z.string().min(1),
@@ -1181,7 +1235,7 @@ server.registerTool("planner-task-switch", {
     },
 }, async ({ from_task, to_task, reason, what_was_being_done, resume_location, how_to_resume, switched_by }) => {
     const st = await requireStore();
-    const [featuresDoc, phases, project] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject()]);
+    const [featuresDoc, phases, project, focus] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject(), st.loadResume()]);
     const features = featuresDoc.features;
     const source = findTaskByRef(phases, features, from_task);
     const target = findTaskByRef(phases, features, to_task);
@@ -1191,8 +1245,34 @@ server.registerTool("planner-task-switch", {
         return text(`Task not found: ${to_task}`);
     if (source.task.id === target.task.id)
         return text("Source and temporary task must differ.");
-    if (source.task.status !== "in-progress" && source.task.status !== "paused") {
-        return text(`Task switch denied: source is ${source.task.status}; only in-progress or pending-resume paused work can be switched.`);
+    if (source.task.status !== "in-progress" && !source.task.pauseSnapshot) {
+        return text(`Task switch denied: source is ${source.task.status}; only in-progress or checkpointed work can be switched.`);
+    }
+    const targetFeature = target.phase.featureId ? features.find((feature) => feature.id === target.phase.featureId) : undefined;
+    const linkedRequirements = [
+        ...(await st.linkedRequirementsForPhase(target.phase.id)),
+        ...(target.phase.featureId ? await st.linkedRequirementsForFeature(target.phase.featureId) : []),
+    ].filter((requirement, index, all) => all.findIndex((candidate) => candidate.id === requirement.id) === index);
+    const linkedRequirementIds = linkedRequirements.map((requirement) => requirement.id);
+    const contextInput = {
+        sessionId: plannerSessionId,
+        taskId: target.task.id,
+        phaseId: target.phase.id,
+        ...(target.phase.featureId ? { featureId: target.phase.featureId } : {}),
+        task: target.task,
+        phase: target.phase,
+        ...(targetFeature ? { feature: targetFeature } : {}),
+        requirements: linkedRequirements,
+        requirementIds: linkedRequirementIds,
+    };
+    const contextEligibility = contextReadEligibilityForSession(contextInput);
+    if (!contextEligibility.eligible)
+        return text(`Task switch denied: context reads required. ${contextEligibility.reason}`, contextEligibility);
+    if (!hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements)) {
+        return text("Task switch denied: read the requirements linked to the target phase and feature before switching.", { requirementIds: linkedRequirementIds });
+    }
+    if (!hasValidSessionAttestation(contextInput)) {
+        await st.recordContextRead({ sessionId: plannerSessionId, phaseId: target.phase.id, taskId: target.task.id, ...(target.phase.featureId ? { featureId: target.phase.featureId } : {}), requirementIds: linkedRequirementIds });
     }
     const eligibility = checkExplicitTaskStart(features, phases, target.task.id, project.workDeviations);
     if (!eligibility.eligible)
@@ -1203,7 +1283,7 @@ server.registerTool("planner-task-switch", {
         resumeLocation: resume_location, howToResume: how_to_resume,
         relatedTaskId: target.task.id, pausedAt: timestamp, pausedBy: switched_by?.trim() ?? "",
     };
-    const selection = recommendNextTask(features, phases, project.workDeviations);
+    const selection = recommendNextTask(features, phases, project.workDeviations, focus?.currentPhaseId);
     const record = {
         id: crypto.randomUUID(), recommendedTaskId: selection.candidate?.task.id ?? source.task.id,
         temporaryTaskId: target.task.id, resumeTaskId: source.task.id, reason, snapshot,
@@ -1222,7 +1302,7 @@ server.registerTool("planner-task-switch", {
             await st.updatePhase(source.phase.id, (phase) => {
                 const task = phase.tasks.find((entry) => entry.id === source.task.id);
                 if (!task)
-                    throw new Error(`Paused source task disappeared: ${from_task}`);
+                    throw new Error(`Checkpointed source task disappeared: ${from_task}`);
                 task.pauseSnapshot = snapshot;
                 task.pauseHistory = [...task.pauseHistory, snapshot];
                 task.updatedAt = timestamp;
@@ -1230,7 +1310,7 @@ server.registerTool("planner-task-switch", {
             });
         }
         sourceCheckpointed = true;
-        if (target.task.status === "paused") {
+        if (target.task.pauseSnapshot) {
             await st.resumeTask(target.phase.id, target.task.id, timestamp);
         }
         else {
@@ -1252,7 +1332,7 @@ server.registerTool("planner-task-switch", {
         }
         targetStarted = true;
         await st.addWorkDeviation(record);
-        if (target.task.status === "paused") {
+        if (target.task.pauseSnapshot) {
             const resumedDeviation = project.workDeviations
                 .filter((deviation) => deviation.resumeTaskId === target.task.id
                 && (deviation.state === "resume-required" || deviation.state === "resolved"))
@@ -1282,45 +1362,104 @@ server.registerTool("planner-task-switch", {
     await st.syncTaskStatusRollup(source.phase.id);
     if (target.phase.id !== source.phase.id)
         await st.syncTaskStatusRollup(target.phase.id);
+    invalidateReads(plannerSessionId);
     return writeAndSummarize(st, [
         `🔀 Task switched: ${taskCompositeRef(source.task, source.phase, features)} → ${taskCompositeRef(target.task, target.phase, features)}`,
-        `Paused snapshot: ${snapshot.whatWasBeingDone}`,
+        `Resume checkpoint: ${snapshot.whatWasBeingDone}`,
         `Return target: ${taskCompositeRef(source.task, source.phase, features)} from ${snapshot.resumeLocation}`,
         `Normal priority was deliberately overridden; completing the temporary task will emit RESUME REQUIRED.`,
     ].join("\n"), { deviation: record, snapshot, resumeTaskId: source.task.id, temporaryTaskId: target.task.id });
 });
 server.registerTool("planner-task-start", {
-    description: "Set a task to in-progress or resume a paused task. BEFORE calling, use planner-task-show with full=true and planner-phase-show with full=true for the parent phase, including linked requirements. A different active task must be suspended through planner-task-switch first. Otherwise follow active/pending-resume/feature → phase → task priority guidance.",
+    description: "Set a task to in-progress or resume checkpointed work. Read the exact full task → phase → feature tree and linked requirements once per harness session; subsequent starts reuse persisted sessionInfo while entity updatedAt values remain unchanged. Every stale or denied start is an MCP isError result with started=false and exact retry actions; NEVER claim work started unless structuredContent.started is true. Success is returned only after persisted in-progress state is verified.",
     inputSchema: { task: z.string().min(1) },
 }, async ({ task: ref }) => {
-    const st = await requireStore();
+    let st;
+    try {
+        st = await requireStore();
+    }
+    catch {
+        return taskStartError(taskStartDenied("PLAN_NOT_FOUND", "No .planner/ found.", ["Initialize or load the planner, then retry planner-task-start."]));
+    }
     const features = (await st.loadFeatures()).features;
     const found = findTaskByRef(await st.loadAllPhases(), features, ref);
     if (!found)
-        return text(`Task not found: ${ref}`);
-    if (found.task.status === "in-progress")
-        return text(`Task ${found.task.id} is already in-progress.`);
+        return taskStartError(taskStartDenied("TASK_NOT_FOUND", `Task not found: ${ref}`, ["Resolve the task with planner-task-list or planner-task-show, then retry planner-task-start."]));
+    const taskRef = taskCompositeRef(found.task, found.phase, features);
+    const phaseRef = formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features));
+    const parentFeature = found.phase.featureId ? features.find((candidate) => candidate.id === found.phase.featureId) : undefined;
+    const featureRef = parentFeature ? formatFeatureRef(parentFeature.number) : "";
+    if (found.task.status === "in-progress") {
+        const outcome = taskStartSucceeded(found.task.id, true);
+        return text(`✅ Task already started: ${taskRef} — ${found.task.title} (in-progress)\nstarted: true`, { ...outcome, task: found.task });
+    }
     if (found.task.status === "done")
-        return text(`Task ${found.task.id} is done. Use planner-task-update to reopen.`);
-    const project = await st.loadProject();
-    const phases = await st.loadAllPhases();
+        return taskStartError(taskStartDenied("TASK_DONE", `Task ${taskRef} is done and was not reopened.`, [`Use planner-task-update with status=planned and a motivation to reopen ${taskRef}.`, `Repeat the required full context reads, then retry planner-task-start ${taskRef}.`], { taskId: found.task.id }));
+    const linkedRequirements = [
+        ...(await st.linkedRequirementsForPhase(found.phase.id)),
+        ...(found.phase.featureId ? await st.linkedRequirementsForFeature(found.phase.featureId) : []),
+    ].filter((requirement, index, all) => all.findIndex((candidate) => candidate.id === requirement.id) === index);
+    const linkedRequirementIds = linkedRequirements.map((requirement) => requirement.id);
+    const contextInput = {
+        sessionId: plannerSessionId,
+        taskId: found.task.id,
+        phaseId: found.phase.id,
+        ...(found.phase.featureId ? { featureId: found.phase.featureId } : {}),
+        task: found.task,
+        phase: found.phase,
+        ...(parentFeature ? { feature: parentFeature } : {}),
+        requirements: linkedRequirements,
+        requirementIds: linkedRequirementIds,
+    };
+    const contextEligibility = contextReadEligibilityForSession(contextInput);
+    if (!contextEligibility.eligible)
+        return taskStartError(taskStartDenied("CONTEXT_READ_REQUIRED", `Required context reads are incomplete or stale. ${contextEligibility.reason}`, [
+            `planner-task-show ${taskRef} with full=true`,
+            `planner-phase-show ${phaseRef} with full=true`,
+            ...(featureRef ? [`planner-feature-show ${featureRef} with full=true`] : []),
+            ...(linkedRequirementIds.length > 0 ? ["planner-requirement-list"] : []),
+            `Retry planner-task-start ${taskRef}`,
+        ], { taskId: found.task.id }), { contextEligibility });
+    if (!hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements)) {
+        return taskStartError(taskStartDenied("REQUIREMENTS_READ_REQUIRED", "Linked requirements were not read; the task remains unchanged.", ["planner-requirement-list", `Retry planner-task-start ${taskRef}`], { taskId: found.task.id, requirementIds: linkedRequirementIds }));
+    }
+    if (!hasValidSessionAttestation(contextInput)) {
+        await st.recordContextRead({ sessionId: plannerSessionId, phaseId: found.phase.id, taskId: found.task.id, ...(found.phase.featureId ? { featureId: found.phase.featureId } : {}), requirementIds: linkedRequirementIds });
+    }
+    const [project, phases, focus] = await Promise.all([st.loadProject(), st.loadAllPhases(), st.loadResume()]);
     const eligibility = checkExplicitTaskStart(features, phases, found.task.id, project.workDeviations);
     if (!eligibility.eligible)
-        return text(`Task start denied: ${eligibility.reason}`, { reason: eligibility.reason });
-    const selection = recommendNextTask(features, phases, project.workDeviations);
+        return taskStartError(taskStartDenied("START_NOT_ALLOWED", eligibility.reason, ["Resolve the reported task readiness condition, then retry planner-task-start."], { taskId: found.task.id }), { eligibility });
+    const selection = recommendNextTask(features, phases, project.workDeviations, focus?.currentPhaseId);
     if (selection.kind === "conflict") {
-        return text(`${selection.reason} Pause/reconcile active tasks before starting another task.`, {
-            activeTaskIds: selection.activeCandidates?.map((candidate) => candidate.task.id) ?? [],
-        });
+        return taskStartError(taskStartDenied("ACTIVE_TASK_CONFLICT", selection.reason, ["Pause or reconcile the active tasks.", `Retry planner-task-start ${taskRef}.`], { taskId: found.task.id }), { selection });
     }
     if (selection.kind === "active" && selection.candidate?.task.id !== found.task.id) {
-        return text(`Task start denied: ${taskCompositeRef(selection.candidate.task, selection.candidate.phase, features)} is active. Use planner-task-switch to snapshot and pause it before starting ${taskCompositeRef(found.task, found.phase, features)}.`);
+        const activeRef = taskCompositeRef(selection.candidate.task, selection.candidate.phase, features);
+        return taskStartError(taskStartDenied("ACTIVE_TASK_CONFLICT", `${activeRef} is active; ${taskRef} was not started.`, [`Use planner-task-switch to snapshot and pause ${activeRef}.`, `Retry planner-task-start ${taskRef}.`], { taskId: found.task.id }), { selection });
     }
-    if (selection.kind === "resume" && selection.candidate?.task.id !== found.task.id) {
-        return text(`Task start denied: ${taskCompositeRef(selection.candidate.task, selection.candidate.phase, features)} is pending resume. Resume it now, or use planner-task-switch from that paused task to ${taskCompositeRef(found.task, found.phase, features)} with a new checkpoint and reason.`);
+    let resumeProposal;
+    if (selection.kind === "resume" && selection.candidate && selection.candidate.task.id !== found.task.id) {
+        // Advisory only: a pending resume must be surfaced loudly, but it must
+        // not hard-block an explicit start of a different task. Capture a
+        // structured proposal so the resume-first guidance is explicit and
+        // machine-readable for the host/agent.
+        const resumeTask = selection.candidate;
+        const resumeSnapshot = resumeTask.task.pauseSnapshot
+            ?? project.workDeviations.find((deviation) => deviation.resumeTaskId === resumeTask.task.id
+                && (deviation.state === "resume-required" || deviation.state === "resolved"))?.snapshot
+            ?? null;
+        resumeProposal = buildResumeRequiredProposal({
+            ref: taskCompositeRef(resumeTask.task, resumeTask.phase, features),
+            title: resumeTask.task.title,
+            taskId: resumeTask.task.id,
+            phaseId: resumeTask.phase.id,
+            snapshot: resumeSnapshot
+                ? { reason: resumeSnapshot.reason, resumeLocation: resumeSnapshot.resumeLocation, howToResume: resumeSnapshot.howToResume }
+                : null,
+        });
     }
     // Assemble the mandatory parent context before changing task lifecycle state.
-    const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
     const [phaseWithRequirements, featureRequirements] = await Promise.all([
         st.loadPhaseWithRequirements(found.phase.id),
         parentFeature ? st.linkedRequirementsForFeature(parentFeature.id) : Promise.resolve([]),
@@ -1330,11 +1469,17 @@ server.registerTool("planner-task-start", {
     // archived only when the phase completes (auto) or the user explicitly
     // clears it.
     const advisory = selection.candidate && selection.candidate.task.id !== found.task.id
-        ? `\n\n⚠️ ${selection.kind === "resume" ? "Resume" : "Priority"} advisory: ${taskCompositeRef(selection.candidate.task, selection.candidate.phase, features)} is the automatic recommendation. Explicit task request honored.`
+        ? selection.kind === "resume"
+            ? `\n\n${(() => {
+                if (resumeProposal)
+                    return resumeProposal.text;
+                return `⚠️ Resume advisory: ${taskCompositeRef(selection.candidate.task, selection.candidate.phase, features)} has a saved checkpoint. Evaluate its resume context before continuing with this explicit task request. Explicit task request honored.`;
+            })()}`
+            : `\n\n⚠️ Priority advisory: ${taskCompositeRef(selection.candidate.task, selection.candidate.phase, features)} is the automatic recommendation. Explicit task request honored.`
         : "";
     const timestamp = nowISO();
     let updatedTask;
-    if (found.task.status === "paused") {
+    if (found.task.pauseSnapshot) {
         updatedTask = await st.resumeTask(found.phase.id, found.task.id, timestamp);
     }
     else {
@@ -1369,23 +1514,35 @@ server.registerTool("planner-task-start", {
         .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
     if (resumedDeviation)
         await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
-    const t = updatedTask ?? found.task;
-    return writeAndSummarize(st, `✅ Task started: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (in-progress)${t.shortId ? ` · ${t.shortId}` : ""}${phaseContext}${advisory}`);
+    await st.writeGenerated();
+    const persistedTask = (await st.loadPhase(found.phase.id)).tasks.find((candidate) => candidate.id === found.task.id);
+    if (!updatedTask || persistedTask?.status !== "in-progress") {
+        return taskStartError(taskStartDenied("PERSISTENCE_VERIFICATION_FAILED", `The lifecycle write could not be verified as in-progress for ${taskRef}.`, ["Inspect planner-task-show for the persisted state and retry only after resolving the persistence failure."], { taskId: found.task.id }));
+    }
+    const outcome = taskStartSucceeded(persistedTask.id);
+    return text(`✅ Task started: ${taskRef} — ${persistedTask.title} (in-progress)${persistedTask.shortId ? ` · ${persistedTask.shortId}` : ""}\nstarted: true${phaseContext}${advisory}`, {
+        ...outcome,
+        task: persistedTask,
+        ...(resumeProposal ? { resumeRequired: resumeProposal.structured } : {}),
+    });
 });
 server.registerTool("planner-task-complete", {
-    description: "Set a task to done. Fails if checklist is incomplete unless force=true.",
+    description: "Set a task to done with mandatory durable completion and verification evidence. Fails if checklist is incomplete unless force=true.",
     inputSchema: {
         task: z.string().min(1),
         force: z.boolean().optional(),
-        description_update: z.string().min(10).optional().describe("Post-hoc summary of what was done: commit hash(s), files touched, decisions made, updated code references with new line numbers. Keeps the planner alive and traceable."),
+        description_update: z.string().min(10).describe("Required evidence: shipped work, verification level including partial verification, remaining/unverified work, files, decisions, and updated code references."),
     },
 }, async ({ task: ref, force, description_update }) => {
     const st = await requireStore();
     const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
-    if (found.task.status === "paused")
-        return text("Task completion denied: resume paused work with planner-task-start before completing it, or cancel it explicitly with motivation.");
+    const completionSummary = description_update.trim();
+    if (completionSummary.length < 10)
+        return text("Task completion denied: provide at least 10 characters of durable completion and verification evidence.");
+    if (found.task.pauseSnapshot)
+        return text("Task completion denied: resume checkpointed work with planner-task-start before completing it, or cancel it explicitly with motivation.");
     const unchecked = found.task.checklist.filter((item) => !item.checked);
     if (unchecked.length > 0 && !force)
         return text(`${unchecked.length} checklist item(s) not done. Re-run with force=true to complete anyway.`);
@@ -1403,13 +1560,12 @@ server.registerTool("planner-task-complete", {
             fromStatus: previousStatus,
             toStatus: "done",
             title: `${previousStatus} → done`,
-            description: "",
+            description: completionSummary,
         };
         task.statusLog = [...(task.statusLog ?? []), entry];
-        if (description_update) {
-            const sep = task.description ? "\n\n---\n**Completion summary:**\n" : "**Completion summary:**\n";
-            task.description = task.description + sep + description_update;
-        }
+        const sep = task.description ? "\n\n---\n**Completion summary:**\n" : "**Completion summary:**\n";
+        task.description = task.description + sep + completionSummary;
+        task.descriptionUpdatedAt = timestamp;
         task.updatedAt = timestamp;
         phase.updatedAt = timestamp;
         updatedTask = task;
@@ -1432,7 +1588,7 @@ server.registerTool("planner-task-complete", {
             resumeNotice = [
                 "",
                 `↩️ RESUME REQUIRED: ${taskCompositeRef(resume.task, resume.phase, features)} — ${resume.task.title}`,
-                snapshot ? `Paused because: ${snapshot.reason}` : "Return to the preserved task before selecting new priority work.",
+                snapshot ? `Checkpoint reason: ${snapshot.reason}` : "Return to the preserved task before selecting new priority work.",
                 snapshot ? `Resume from: ${snapshot.resumeLocation}` : "",
                 snapshot ? `How to resume: ${snapshot.howToResume}` : "",
                 `Next action: planner-task-start ${taskCompositeRef(resume.task, resume.phase, features)}`,
@@ -1465,52 +1621,139 @@ server.registerTool("planner-handoff-show", {
         return text(`No handoff set on ${r.compositeRef}.`, { phaseRef: r.compositeRef, empty: true });
     return text(`Handoff for ${r.compositeRef}:\n\n${content}`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
 });
+server.registerTool("planner-requirement-list", {
+    description: "List all top-level requirements in requirements.json. Reading this list records the requirements as read for the start/resume read-enforcement (explicit requirement read, required alongside feature/phase reads).",
+    inputSchema: {},
+}, async () => {
+    const st = await requireStore();
+    const requirements = await st.loadRequirements();
+    requirements.requirements.forEach((req) => markRequirementReadForSessionId(plannerSessionId, req.id));
+    return text(requirements.requirements.map((req) => `- ${req.id} — ${req.title} (${req.status})`).join("\n") || "No requirements", { requirements });
+});
 server.registerTool("planner-handoff-write", {
-    description: "Write/refresh the entity-scoped handoff on a phase. phaseRef is required and must be the exact phase selected with the user. Never guess from in-progress status or stale context; completed/canceled phases reject new handoffs. Pass content (markdown) and a meaningful title.",
+    description: "Reconcile and refresh the single active phase handoff while synchronizing durable task, phase, and feature context. Run planner-handoff-prepare with the confirmed phaseRef first and pass its exact handoffUpdatedAt token.",
     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 (becomes the H1 / first line in lists). REQUIRED if your markdown's first heading is generic. Example: 'P049 — featureId validation: tests + adapter wiring'."),
+        title: z.string().min(3).optional().describe("Meaningful handoff title summarizing the work."),
         confirmed: z.boolean().describe("Set true only after the user explicitly confirms the proposed feature+phase target."),
-        content: z.string().min(1).describe("Handoff text (markdown)."),
+        content: z.string().min(1).describe("Full reconciled handoff text (markdown)."),
+        expectedHandoffUpdatedAt: z.string().optional().describe("Exact token returned by planner-handoff-prepare; empty when no handoff exists."),
+        reconciledExistingHandoff: z.boolean().optional().describe("Confirm that still-relevant existing handoff information was retained."),
+        taskUpdates: z.array(z.object({
+            taskRef: z.string().min(1),
+            completionSummary: z.string().min(1),
+            verification: z.string().min(1),
+            remainingWork: z.string().min(1),
+            filesTouched: z.array(z.string().min(1)).optional(),
+            decisions: z.array(z.string().min(1)).optional(),
+        })).optional(),
+        phaseUpdate: z.object({
+            progressSummary: z.string().min(1),
+            remainingWork: z.string().min(1),
+            decisions: z.array(z.string().min(1)).optional(),
+        }).optional(),
+        phaseNoUpdateReason: z.string().min(1).optional(),
+        featureUpdate: z.object({ workDone: z.string().min(1), workRemaining: z.string().min(1) }).optional(),
+        featureNoUpdateReason: z.string().min(1).optional(),
     },
-}, async ({ phaseRef, title, confirmed, content }) => {
+}, async ({ phaseRef, title, confirmed, content, expectedHandoffUpdatedAt, reconciledExistingHandoff, taskUpdates, phaseUpdate, phaseNoUpdateReason, featureUpdate, featureNoUpdateReason }) => {
     const st = await requireStore();
     let body = content.trim();
-    const firstLine = body.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
+    const firstLine = body.split(/\r?\n/).find((line) => line.trim().length > 0) ?? "";
     const firstHeadingText = firstLine.replace(/^#+\s*/, "").trim();
-    const isGeneric = !firstHeadingText || /^(handoff|canonical handoff|session handoff)$/i.test(firstHeadingText);
-    if (!title && isGeneric) {
-        return text("❌ Generic handoff title. Provide a meaningful `title` (or start your markdown with a descriptive H1) summarizing the work — e.g. 'P049 — featureId validation: tests + adapter wiring'. Generic titles like 'Handoff' or 'Canonical handoff' are not accepted.");
+    const effectiveHeadingText = title?.trim() || firstHeadingText;
+    if (!effectiveHeadingText || /^(handoff|canonical handoff|session handoff)$/i.test(effectiveHeadingText)) {
+        return text("❌ Generic handoff title. Provide a meaningful title summarizing the work.");
     }
-    if (title && title.trim()) {
-        const t = title.trim();
+    if (title?.trim()) {
         const lines = body.split(/\r?\n/);
-        const firstIdx = lines.findIndex((l) => l.trim().length > 0);
-        if (firstIdx !== -1 && /^#+\s/.test(lines[firstIdx] ?? "")) {
-            lines[firstIdx] = `# ${t}`;
-            body = lines.join("\n");
-        }
-        else {
-            body = `# ${t}\n\n${body}`;
-        }
+        const firstIdx = lines.findIndex((line) => line.trim().length > 0);
+        if (firstIdx !== -1 && /^#+\s/.test(lines[firstIdx] ?? ""))
+            lines[firstIdx] = `# ${title.trim()}`;
+        else
+            lines.unshift(`# ${title.trim()}`, "");
+        body = lines.join("\n");
     }
     const r = await resolvePhaseForHandoff(st, phaseRef);
     if (!r.ok)
         return text(`❌ ${r.error}`);
     if (!confirmed)
-        return text(`Proposal only: I would write this handoff on ${r.compositeRef}. Ask the user to confirm this exact feature/phase, then retry with confirmed=true.`, { phaseRef: r.compositeRef, confirmationRequired: true });
-    await st.setPhaseHandoff(r.phase.id, body);
-    return text(`✅ Wrote handoff on ${r.compositeRef}.`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
+        return text(`Proposal only: I would refresh this handoff on ${r.compositeRef}. Ask the user to confirm, then run planner-handoff-prepare with the exact phaseRef.`, { phaseRef: r.compositeRef, confirmationRequired: true });
+    if (expectedHandoffUpdatedAt === undefined)
+        return text("❌ Run planner-handoff-prepare first and pass expectedHandoffUpdatedAt.");
+    const phases = await st.loadAllPhases();
+    const features = (await st.loadFeatures()).features;
+    const resolvedTaskUpdates = [];
+    for (const update of taskUpdates ?? []) {
+        const found = findTaskByRef(phases, features, update.taskRef.trim());
+        if (!found || found.phase.id !== r.phase.id)
+            return text(`❌ Task ${update.taskRef} does not belong to ${r.compositeRef}.`);
+        resolvedTaskUpdates.push({
+            taskId: found.task.id,
+            completionSummary: update.completionSummary,
+            verification: update.verification,
+            remainingWork: update.remainingWork,
+            ...(update.filesTouched ? { filesTouched: update.filesTouched } : {}),
+            ...(update.decisions ? { decisions: update.decisions } : {}),
+        });
+    }
+    try {
+        const result = await st.refreshPhaseHandoff(r.phase.id, {
+            content: body,
+            expectedHandoffUpdatedAt,
+            reconciledExistingHandoff: reconciledExistingHandoff === true,
+            contextSync: {
+                taskUpdates: resolvedTaskUpdates,
+                ...(phaseUpdate ? { phaseUpdate: {
+                        progressSummary: phaseUpdate.progressSummary,
+                        remainingWork: phaseUpdate.remainingWork,
+                        ...(phaseUpdate.decisions ? { decisions: phaseUpdate.decisions } : {}),
+                    } } : {}),
+                ...(phaseNoUpdateReason ? { phaseNoUpdateReason } : {}),
+                ...(featureUpdate ? { featureUpdate } : {}),
+                ...(featureNoUpdateReason ? { featureNoUpdateReason } : {}),
+            },
+        });
+        await st.writeGenerated();
+        return text(`✅ Reconciled handoff and durable context on ${r.compositeRef}; updated ${result.updatedTaskIds.length} task(s).`, { phaseRef: r.compositeRef, phaseId: r.phase.id, ...result });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return text(`❌ Handoff refresh denied: ${message}`, { error: message });
+    }
 });
 server.registerTool("planner-handoff-prepare", {
-    description: "Prepare a canonical handoff proposal. Do not write until the agent has identified the exact feature+phase from the conversation and the user has confirmed that target.",
-}, async () => text([
-    "First identify the exact feature and phase actually discussed/worked on in this session. Do not use the first in-progress phase and do not target a phase that just became done.",
-    "Before calling planner-handoff-write, tell the user: 'I propose writing this handoff on P00x(F00x) — <phase title>. Confirm?' Wait for explicit confirmation.",
-    "After confirmation, call planner-handoff-write with that exact phaseRef. If the phase is done/canceled, do not write an operational handoff.",
-    "Pass a meaningful title. Required sections: Created at, Updated at, Reason, Current focus, What was being done, How to resume, Files touched, Blockers, Next steps, Recent decisions, Reminder.",
-    "Stored on phase.handoff; .planner/HANDOFF.md is deprecated.",
-].join("\n")));
+    description: "Identify or audit the exact handoff target. Without phaseRef, returns the confirmation workflow. With a confirmed phaseRef, returns the current handoff/version and done tasks missing durable completion evidence.",
+    inputSchema: { phaseRef: z.string().min(1).optional() },
+}, async ({ phaseRef }) => {
+    if (!phaseRef)
+        return text([
+            "First identify the exact feature and phase actually discussed/worked on in this session. Do not use a stale resume pointer or target a phase that just became done.",
+            "Tell the user: 'I propose writing this handoff on P00x(F00x) — <phase title>. Confirm?' Wait for explicit confirmation.",
+            "After confirmation, call planner-handoff-prepare again with that exact phaseRef, then reconcile its current handoff and missing task evidence through planner-handoff-write.",
+        ].join("\n"));
+    const st = await requireStore();
+    const r = await resolvePhaseForHandoff(st, phaseRef);
+    if (!r.ok)
+        return text(`❌ ${r.error}`);
+    try {
+        const audit = await st.preparePhaseHandoff(r.phase.id);
+        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}`,
+            `Base handoffUpdatedAt: ${audit.handoffUpdatedAt || "(empty)"}`,
+            "Done tasks missing durable completion/verification evidence:",
+            missing,
+            "",
+            "Existing active handoff (reconcile all still-relevant content):",
+            audit.handoff.trim() || "(none)",
+        ].join("\n"), { phaseRef: r.compositeRef, ...audit });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return text(`❌ Handoff preparation failed: ${message}`, { error: message });
+    }
+});
 server.registerTool("planner-handoff-clear", {
     description: "Clear/archive the entity-scoped handoff of a phase. phaseRef is required; never infer a phase automatically.",
     inputSchema: { phaseRef: z.string().min(1).describe("Exact phase ref: P00x | P00x(F00x) | UUID | title.") },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/mcp",
-  "version": "0.2.22",
+  "version": "0.2.23-next.0",
   "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.22",
-    "@agent-plan/server": "0.2.22"
+    "@agent-plan/core": "0.2.23-next.0",
+    "@agent-plan/server": "0.2.23-next.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",