@agent-plan/mcp 0.2.22 → 0.2.23

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":";AAwjDA,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/dist/index.js

@@ -4,10 +4,10 @@ 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, 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, markFeatureRead, markPhaseRead, markTaskRead, contextReadEligibility, hasReadRequirements, markRequirementRead, invalidateReads } 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];
 function text(textValue, structuredContent) {
     return structuredContent ? { content: [{ type: "text", text: textValue }], structuredContent } : { content: [{ type: "text", text: textValue }] };
@@ -450,6 +450,8 @@ server.registerTool("planner-feature-show", {
     if (!resolvedFeature.ok)
         return text(resolvedFeature.error);
     const feature = resolvedFeature.feature;
+    if (full)
+        markFeatureRead(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);
@@ -657,6 +659,8 @@ server.registerTool("planner-phase-show", {
     const phase = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!phase)
         return text(`Phase not found: ${ref}`);
+    if (full)
+        markPhaseRead(phase.id, phase.featureId);
     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"}` : ""})`;
@@ -841,18 +845,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)
+        markTaskRead(found.task.id, found.phase.id, found.phase.featureId);
     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 +932,8 @@ 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.");
     }
     // Validate motivation requirement for status transitions.
     if (status !== undefined && needsMotivation(found.task.status, status)) {
@@ -1082,12 +1112,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 +1131,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 +1176,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();
+    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,12 +1192,12 @@ 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.",
@@ -1181,7 +1212,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 +1222,18 @@ 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 contextEligibility = contextReadEligibility(target.task.id, target.phase.id, target.phase.featureId);
+    if (!contextEligibility.eligible)
+        return text(`Task switch denied: context reads required. ${contextEligibility.reason}`, contextEligibility);
+    const linkedRequirementIds = [
+        ...(await st.linkedRequirementsForPhase(target.phase.id)).map((requirement) => requirement.id),
+        ...(target.phase.featureId ? (await st.linkedRequirementsForFeature(target.phase.featureId)).map((requirement) => requirement.id) : []),
+    ];
+    if (!hasReadRequirements(linkedRequirementIds)) {
+        return text("Task switch denied: read the requirements linked to the target phase and feature before switching.", { requirementIds: linkedRequirementIds });
     }
     const eligibility = checkExplicitTaskStart(features, phases, target.task.id, project.workDeviations);
     if (!eligibility.eligible)
@@ -1203,7 +1244,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 +1263,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 +1271,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 +1293,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,15 +1323,16 @@ 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();
     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. BEFORE calling, use planner-task-show(full=true), then planner-phase-show(full=true), then planner-feature-show(full=true) for the same lineage, in that exact order. Read linked requirements with planner-requirement-list when present. A different active task must first be suspended through planner-task-switch.",
     inputSchema: { task: z.string().min(1) },
 }, async ({ task: ref }) => {
     const st = await requireStore();
@@ -1302,12 +1344,21 @@ server.registerTool("planner-task-start", {
         return text(`Task ${found.task.id} is already in-progress.`);
     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();
+    const contextEligibility = contextReadEligibility(found.task.id, found.phase.id, found.phase.featureId);
+    if (!contextEligibility.eligible)
+        return text(`Task start denied: context reads required. ${contextEligibility.reason}`, contextEligibility);
+    const linkedRequirementIds = [
+        ...(await st.linkedRequirementsForPhase(found.phase.id)).map((requirement) => requirement.id),
+        ...(found.phase.featureId ? (await st.linkedRequirementsForFeature(found.phase.featureId)).map((requirement) => requirement.id) : []),
+    ];
+    if (!hasReadRequirements(linkedRequirementIds)) {
+        return text("Task start denied: read the requirements linked to the task's phase and feature first.", { 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);
+    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) ?? [],
@@ -1316,8 +1367,26 @@ server.registerTool("planner-task-start", {
     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)}.`);
     }
-    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;
@@ -1330,11 +1399,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 {
@@ -1370,7 +1445,9 @@ server.registerTool("planner-task-start", {
     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}`);
+    return writeAndSummarize(st, `✅ Task started: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (in-progress)${t.shortId ? ` · ${t.shortId}` : ""}${phaseContext}${advisory}`, {
+        ...(resumeProposal ? { resumeRequired: resumeProposal.structured } : {}),
+    });
 });
 server.registerTool("planner-task-complete", {
     description: "Set a task to done. Fails if checklist is incomplete unless force=true.",
@@ -1384,8 +1461,8 @@ server.registerTool("planner-task-complete", {
     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.");
+    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.`);
@@ -1432,7 +1509,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,6 +1542,15 @@ 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) => markRequirementRead(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.",
     inputSchema: {
@@ -1478,8 +1564,10 @@ server.registerTool("planner-handoff-write", {
     let body = content.trim();
     const firstLine = body.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
     const firstHeadingText = firstLine.replace(/^#+\s*/, "").trim();
-    const isGeneric = !firstHeadingText || /^(handoff|canonical handoff|session handoff)$/i.test(firstHeadingText);
-    if (!title && isGeneric) {
+    const genericTitlePattern = /^(handoff|canonical handoff|session handoff)$/i;
+    const effectiveHeadingText = title?.trim() ? title.trim() : firstHeadingText;
+    const isGeneric = !effectiveHeadingText || genericTitlePattern.test(effectiveHeadingText);
+    if (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.");
     }
     if (title && title.trim()) {

package/package.json

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