@agent-plan/mcp 0.2.22-next.2 → 0.2.22-next.4

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAmjDA,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,7 +4,7 @@ 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, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, markFeatureRead, markPhaseRead, markTaskRead, parentReadAdvisory, requirementReadAdvisory, markRequirementRead, invalidateReads } 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", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
@@ -450,7 +450,8 @@ server.registerTool("planner-feature-show", {
     if (!resolvedFeature.ok)
         return text(resolvedFeature.error);
     const feature = resolvedFeature.feature;
-    markFeatureRead(feature.id);
+    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);
@@ -658,7 +659,8 @@ server.registerTool("planner-phase-show", {
     const phase = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!phase)
         return text(`Phase not found: ${ref}`);
-    markPhaseRead(phase.id, phase.featureId);
+    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"}` : ""})`;
@@ -849,7 +851,8 @@ server.registerTool("planner-task-show", {
     const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
-    markTaskRead(found.task.id, found.phase.id, found.phase.featureId);
+    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)
@@ -929,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 (found.task.pauseSnapshot && status === "in-progress" && status !== found.task.status) {
-        return text("Resume checkpoint lifecycle transitions require planner-task-start so the checkpoint and return stack remain consistent.");
+    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)) {
@@ -1109,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;
@@ -1128,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}`);
@@ -1209,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);
@@ -1222,6 +1225,16 @@ server.registerTool("planner-task-switch", {
     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)
         return text(`Task switch denied: ${eligibility.reason}`);
@@ -1231,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,
@@ -1310,22 +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);
-    const targetReadAdvisory = parentReadAdvisory(target.phase.featureId, target.phase.id);
-    const targetRequirementAdvisory = requirementReadAdvisory([
-        ...(await st.linkedRequirementsForPhase(target.phase.id)).map((r) => r.id),
-        ...(target.phase.featureId ? (await st.linkedRequirementsForFeature(target.phase.featureId)).map((r) => r.id) : []),
-    ]);
+    invalidateReads();
     return writeAndSummarize(st, [
         `🔀 Task switched: ${taskCompositeRef(source.task, source.phase, features)} → ${taskCompositeRef(target.task, target.phase, features)}`,
         `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.`,
-        ...(targetReadAdvisory ? [targetReadAdvisory.trimStart()] : []),
-        ...(targetRequirementAdvisory ? [targetRequirementAdvisory.trimStart()] : []),
-    ].join("\n"), { deviation: record, snapshot, resumeTaskId: source.task.id, temporaryTaskId: target.task.id, ...(targetReadAdvisory || targetRequirementAdvisory ? { readRequired: true } : {}) });
+    ].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 checkpointed work. 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();
@@ -1337,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) ?? [],
@@ -1429,14 +1445,8 @@ server.registerTool("planner-task-start", {
     if (resumedDeviation)
         await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
     const t = updatedTask ?? found.task;
-    const readAdvisory = parentReadAdvisory(parentFeature?.id, found.phase.id);
-    const requirementAdvisory = requirementReadAdvisory([
-        ...(phaseWithRequirements.linkedRequirements ?? []).map((r) => r.id),
-        ...featureRequirements.map((r) => r.id),
-    ]);
-    return writeAndSummarize(st, `✅ Task started: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (in-progress)${t.shortId ? ` · ${t.shortId}` : ""}${phaseContext}${advisory}${readAdvisory}${requirementAdvisory}`, {
+    return writeAndSummarize(st, `✅ Task started: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (in-progress)${t.shortId ? ` · ${t.shortId}` : ""}${phaseContext}${advisory}`, {
         ...(resumeProposal ? { resumeRequired: resumeProposal.structured } : {}),
-        ...(readAdvisory || requirementAdvisory ? { readRequired: true } : {}),
     });
 });
 server.registerTool("planner-task-complete", {

package/package.json

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