@agent-plan/mcp 0.2.26 → 0.2.28

package/dist/index.js

@@ -5,7 +5,7 @@ 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, findIdeaByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, markFeatureReadForSessionId, markPhaseReadForSessionId, markTaskReadForSessionId, contextReadEligibilityForSession, hasValidSessionAttestation, hasReadRequirementsForSession, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded, noMutableFieldsReceived, normalizeDescriptionRef, projectGuidelinesReadStateForSession, reconcileRequirementMacroTasks, RequirementMacroTaskError, HANDOFF_COMPLETENESS_AUDIT_VERSION, HANDOFF_COMPLETENESS_CATEGORIES, MAX_HANDOFF_CONTENT_CHARS, HandoffContractError } from "@agent-plan/core";
+import { PlanStore, PlanStoreError, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, findIdeaByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, buildPhaseWorkMap, buildBoundedAcceptedDecisionContext, renderAcceptedDecisionsSection, checkExplicitTaskStart, recommendNextTask, recommendNextWork, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, runtimeCapabilities, runtimePackagesDiagnostic, markCanonicalFullReadForSessionId, contextReadEligibilityForSession, requirementReadEligibilityForSession, hasValidSessionAttestation, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded, noMutableFieldsReceived, normalizeDescriptionRef, projectGuidelinesReadStateForSession, reconcileRequirementMacroTasks, RequirementMacroTaskError, HANDOFF_COMPLETENESS_AUDIT_VERSION, HANDOFF_COMPLETENESS_CATEGORIES, HANDOFF_COLD_START_INVENTORY_VERSION, HANDOFF_COLD_START_INVENTORY_CATEGORIES, MAX_HANDOFF_CONTENT_CHARS, handoffContentHash, HandoffContractError } from "@agent-plan/core";
 import { serve } from "@agent-plan/server";
 import { createChecklistItemId, createFeatureId, createPhaseId, createRequirementId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, formatIdeaRef, validateResolvedTarget } from "@agent-plan/core/naming";
 const STATUS_VALUES = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
@@ -28,6 +28,9 @@ function handoffContractFailure(error) {
         structuredContent: { errorCode: error.code, ...error.details },
     };
 }
+function handoffPreflightFailure(errorCode, message, details = {}) {
+    return { isError: true, content: [{ type: "text", text: `❌ Handoff refresh denied [${errorCode}]: ${message}` }], structuredContent: { errorCode, persisted: false, ...details } };
+}
 function boundedHandoffForTransport(content) {
     if (content.length <= MAX_HANDOFF_CONTENT_CHARS)
         return { content, fullLength: content.length, truncated: false };
@@ -89,6 +92,15 @@ function mutationNoFieldsFailure(input) {
         structuredContent: { ...outcome },
     };
 }
+function acceptedDecisionMutationFailure(error, outcome) {
+    if (!(error instanceof PlanStoreError) || !String(error.details?.errorCode ?? "").startsWith("ACCEPTED_DECISION_"))
+        throw error;
+    return {
+        isError: true,
+        content: [{ type: "text", text: `❌ Accepted Decision mutation failed [${error.details?.errorCode}]: ${error.message}` }],
+        structuredContent: { [outcome]: false, ...error.details },
+    };
+}
 function legacyContextMigrationSummary(preview) {
     return [
         `Legacy context present: ${preview.hasLegacyContext ? "yes" : "no"}`,
@@ -119,10 +131,12 @@ function mcpContextReadActions(eligibility, refs, projectGuidelinesReadRequired,
             return [`planner-task-show ${refs.task} with full=true`];
         if (read.kind === "phase")
             return [`planner-phase-show ${refs.phase} with full=true`];
-        return refs.feature ? [`planner-feature-show ${refs.feature} with full=true`] : [];
+        if (read.kind === "feature")
+            return refs.feature ? [`planner-feature-show ${refs.feature} with full=true`] : [];
+        return [];
     }));
     if (requirementReadRequired)
-        actions.push("planner-requirement-list");
+        actions.push(`planner-requirement-list with phaseRef=${refs.phase}`);
     actions.push(retryAction);
     return actions;
 }
@@ -150,21 +164,44 @@ async function requireStore() {
 // In-process web server handle, managed by the planner-web tool and planner-load.
 // Lives as long as this MCP stdio process (i.e. the host session). Null when not running.
 let webHandle = null;
-/** Start the web dashboard on LAN (0.0.0.0:0, OS-assigned port) if not already
- *  running. Returns the local/LAN URLs. No-op (empty url) when no .planner/ exists. */
+function plannerWebMetadata(web) {
+    const address = web.lanUrl || web.localUrl;
+    let host = web.bindHost ?? "";
+    let port = 0;
+    if (address) {
+        try {
+            const parsed = new URL(address);
+            host = parsed.hostname;
+            port = Number(parsed.port);
+        }
+        catch {
+            // Preserve the original address when a custom server returns a non-standard URL.
+        }
+    }
+    return {
+        running: Boolean(web.localUrl),
+        address,
+        localUrl: web.localUrl,
+        lanUrl: web.lanUrl ?? "",
+        host,
+        port,
+        mode: web.mode ?? "",
+        ...(web.error ? { errorCode: "PLANNER_WEB_START_FAILED", error: web.error } : {}),
+    };
+}
 async function ensureWebStarted() {
     if (webHandle)
-        return { localUrl: webHandle.localUrl, lanUrl: webHandle.lanUrl, mode: webHandle.mode };
+        return { localUrl: webHandle.localUrl, lanUrl: webHandle.lanUrl, mode: webHandle.mode, bindHost: webHandle.bindHost };
     const root = planRoot();
     const st = new PlanStore(root);
     if (!(await st.exists()))
-        return { localUrl: "" };
+        return { localUrl: "", error: "Planner workspace does not exist." };
     try {
         webHandle = await serve({ planRoot: root, host: "0.0.0.0", port: 0, quiet: true });
-        return { localUrl: webHandle.localUrl, lanUrl: webHandle.lanUrl, mode: webHandle.mode };
+        return { localUrl: webHandle.localUrl, lanUrl: webHandle.lanUrl, mode: webHandle.mode, bindHost: webHandle.bindHost };
     }
-    catch {
-        return { localUrl: "" };
+    catch (error) {
+        return { localUrl: "", error: error instanceof Error ? error.message : String(error) };
     }
 }
 function findFeatureByRef(features, ref) {
@@ -219,6 +256,33 @@ function featureNumberOfPhase(phase, features) {
 function taskCompositeRef(task, phase, features) {
     return `${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${String(task.number).padStart(3, "0")}`;
 }
+async function resolveAcceptedDecisionTarget(st, targetType, targetRef) {
+    if (targetType === "project") {
+        const project = await st.loadProject();
+        return { ok: true, owner: { kind: "project" }, ref: project.name };
+    }
+    const ref = targetRef?.trim();
+    if (!ref)
+        return { ok: false, error: `targetRef is required for ${targetType} accepted decisions.` };
+    const [featuresDoc, phases] = await Promise.all([st.loadFeatures(), st.loadAllPhases()]);
+    const features = featuresDoc.features;
+    if (targetType === "feature") {
+        const resolved = resolveFeatureRefStrict(features, ref);
+        if (!resolved.ok)
+            return { ok: false, error: resolved.error };
+        return { ok: true, owner: { kind: "feature", featureId: resolved.feature.id }, ref: formatFeatureRef(resolved.feature.number) };
+    }
+    if (targetType === "phase") {
+        const phase = findPhaseByRef(phases, features, ref);
+        if (!phase)
+            return { ok: false, error: `Phase not found: ${ref}` };
+        return { ok: true, owner: { kind: "phase", phaseId: phase.id }, ref: formatPhaseRef(phase.number, featureNumberOfPhase(phase, features)) };
+    }
+    const found = findTaskByRef(phases, features, ref);
+    if (!found)
+        return { ok: false, error: `Task not found: ${ref}` };
+    return { ok: true, owner: { kind: "task", phaseId: found.phase.id, taskId: found.task.id }, ref: taskCompositeRef(found.task, found.phase, features) };
+}
 function applyTaskLifecycleDates(task, nextStatus, now) {
     const previousStatus = task.status;
     if (nextStatus === "in-progress" && !task.startedAt)
@@ -275,17 +339,22 @@ async function resolvePhaseForHandoff(st, ref) {
     return { ok: true, phase, compositeRef: formatPhaseRef(phase.number, feat?.number) };
 }
 server.registerTool("planner-version", {
-    description: "Report the versions of the Agent Plan MCP server and core package actually loaded by this process. Available without an initialized .planner/ workspace.",
+    description: "Report loaded Agent Plan MCP/core runtime provenance plus plan schema and allocation compatibility. Available without an initialized .planner/ workspace.",
 }, async () => {
+    const packages = runtimePackagesDiagnostic([MCP_PACKAGE, CORE_PACKAGE]);
+    const capabilities = runtimeCapabilities();
     const versions = {
         [MCP_PACKAGE.name]: MCP_PACKAGE.version,
         [CORE_PACKAGE.name]: CORE_PACKAGE.version,
     };
     return text([
-        "Agent Plan runtime versions",
-        `${MCP_PACKAGE.name}: ${MCP_PACKAGE.version}`,
-        `${CORE_PACKAGE.name}: ${CORE_PACKAGE.version}`,
-    ].join("\n"), { versions });
+        "Agent Plan runtime diagnostics",
+        "Runtime packages (loaded package manifests):",
+        `- ${MCP_PACKAGE.name}: loaded ${MCP_PACKAGE.version}`,
+        `- ${CORE_PACKAGE.name}: loaded ${CORE_PACKAGE.version}`,
+        `Plan schema: manifest schemaVersion ${capabilities.planSchema.manifestSchemaVersion}`,
+        `Allocation registry: v${capabilities.allocationRegistry.version}; supported kinds: ${capabilities.allocationRegistry.supportedKinds.join(", ")}`,
+    ].join("\n"), { versions, packages, capabilities });
 });
 server.registerTool("planner-export", {
     description: "Export the project plan as a Markdown report. Supports a concise summary or full hierarchical detail.",
@@ -340,13 +409,26 @@ server.registerTool("planner-init", {
     return writeAndSummarize(st, `.planner/ initialized for "${project.name}"`);
 });
 server.registerTool("planner-show", {
-    description: "Show a compact planner overview: project metadata, counts, and a one-line summary of each feature (F00x · shortId — name (status; N phases, M tasks)). Does NOT include full descriptions, phases, or tasks — use planner-feature-list / planner-phase-list / planner-task-list for discovery and planner-*-show for full detail of a single entity. Keeps the result small to avoid token overflow.",
+    description: "Show a compact planner overview with explicit active-task evidence: project metadata, counts, authoritative active task refs (or a verified-empty state), and a one-line summary of each feature. Never infer that no task is active from omitted task detail. Use planner-feature-list / planner-phase-list / planner-task-list for discovery and planner-*-show for full entity detail.",
 }, async () => {
     const st = await requireStore();
     const features = (await st.loadFeatures()).features;
     const phases = await st.loadAllPhases();
-    const totalTasks = phases.reduce((total, phase) => total + phase.tasks.length, 0);
+    const allTasks = phases.flatMap((phase) => phase.tasks.map((task) => ({ phase, task })));
+    const totalTasks = allTasks.length;
+    const activeTasks = allTasks
+        .filter(({ task }) => task.status === "in-progress")
+        .map(({ phase, task }) => ({
+        id: task.id,
+        ref: taskCompositeRef(task, phase, features),
+        title: task.title,
+        phaseId: phase.id,
+        featureId: phase.featureId ?? null,
+        status: task.status,
+    }));
+    const activeTaskState = activeTasks.length === 0 ? "none" : activeTasks.length === 1 ? "single" : "conflict";
     const project = await st.loadProject();
+    const projectDecisionContext = buildBoundedAcceptedDecisionContext([{ scope: "project", decisions: project.acceptedDecisions }]);
     const manifest = await st.loadManifest();
     const featureLines = features.map((feature) => {
         const featurePhases = phases.filter((phase) => phase.featureId === feature.id);
@@ -358,7 +440,11 @@ server.registerTool("planner-show", {
         `Description: ${project.description || "(not set)"}`,
         ...(project.descriptionRef ? [`Description ref: ${project.descriptionRef}`] : []),
         `Goal: ${project.goal || "(not set)"}`,
+        projectDecisionContext.content,
         `Features: ${features.length}  |  Phases: ${phases.length}  |  Tasks: ${totalTasks}`,
+        activeTasks.length === 0
+            ? "Active tasks: none (verified from all persisted phase task statuses)"
+            : `Active tasks (${activeTasks.length})${activeTaskState === "conflict" ? " — CONFLICT: multiple tasks are in progress" : ""}:\n${activeTasks.map((task) => `- ${task.ref} — ${task.title} (in-progress)`).join("\n")}`,
         `Updated: ${manifest.updatedAt || "(unknown)"}`,
         "",
         "Features:",
@@ -366,8 +452,17 @@ server.registerTool("planner-show", {
     ].join("\n");
     // Compact structured overview (no full plan: avoids 1M+ char token overflow).
     const overview = {
-        project: { name: project.name, description: project.description || null, descriptionRef: project.descriptionRef || null, goal: project.goal || null, updatedAt: manifest.updatedAt || null },
-        counts: { features: features.length, phases: phases.length, tasks: totalTasks },
+        project: {
+            name: project.name,
+            description: project.description || null,
+            descriptionRef: project.descriptionRef || null,
+            goal: project.goal || null,
+            acceptedDecisions: project.acceptedDecisions,
+            updatedAt: manifest.updatedAt || null,
+        },
+        counts: { features: features.length, phases: phases.length, tasks: totalTasks, activeTasks: activeTasks.length },
+        activeTaskState,
+        activeTasks,
         features: features.map((feature) => ({
             ref: formatFeatureRef(feature.number),
             shortId: feature.shortId || null,
@@ -379,6 +474,16 @@ server.registerTool("planner-show", {
     };
     return text(summary, { overview });
 });
+server.registerTool("planner-description-freshness", {
+    description: "Preview deterministic child-to-parent description drift. Returns exact stale phase/feature refs and leaf-to-root reconciliation steps without rewriting user-authored descriptions.",
+}, async () => {
+    const st = await requireStore();
+    const freshness = await st.previewDescriptionReconciliation();
+    if (!freshness.reconciliationRequired)
+        return text("Description hierarchy is fresh; no parent reconciliation is required.", { ...freshness });
+    const lines = freshness.reconciliationPreview.map((step) => `- ${step.ownerRef} after ${step.causedByRef}: ${step.action}`);
+    return text(`Parent description reconciliation required (${freshness.staleParentRefs.length}):\n${lines.join("\n")}`, { ...freshness });
+});
 server.registerTool("planner-repair", {
     description: "Repair dangling feature→phase references, rebuild phase containment from each task's own phaseId (heals the migrateToGlobalSequence task-shuffle bug where tasks land in the wrong phase file), and report integrity.",
 }, async () => {
@@ -421,12 +526,11 @@ server.registerTool("planner-project-language", {
     },
 }, async ({ contentLanguage, chatLanguage }) => {
     const st = await requireStore();
-    const project = await st.loadProject();
-    if (contentLanguage !== undefined)
-        project.contentLanguage = contentLanguage.trim();
-    if (chatLanguage !== undefined)
-        project.chatLanguage = chatLanguage.trim();
-    await st.saveProject(project);
+    const project = await st.updateProject((current) => ({
+        ...current,
+        ...(contentLanguage !== undefined ? { contentLanguage: contentLanguage.trim() } : {}),
+        ...(chatLanguage !== undefined ? { chatLanguage: chatLanguage.trim() } : {}),
+    }));
     return writeAndSummarize(st, `Saved language preferences: content=${project.contentLanguage || "(unset)"}, chat=${project.chatLanguage || "(unset)"}`);
 });
 server.registerTool("planner-project-discuss", {
@@ -485,8 +589,28 @@ server.registerTool("planner-project-discuss", {
         project.globalRules = params.globalRules.map((entry) => entry.trim()).filter(Boolean);
     if (params.decisions !== undefined)
         project.decisions = params.decisions.map((entry) => entry.trim()).filter(Boolean);
-    await st.saveProject(project);
-    return writeAndSummarize(st, `Project discussed/updated: ${project.name}. Fields saved: ${receivedFields.join(", ")}.`, { project, discussed: true, updatedFields: receivedFields });
+    const persisted = await st.updateProject((current) => {
+        const next = {
+            ...current,
+            ...(params.description !== undefined ? { description: params.description.trim() } : {}),
+            ...(params.goal !== undefined ? { goal: params.goal.trim() } : {}),
+            ...(params.scope !== undefined ? { scope: params.scope.map((entry) => entry.trim()).filter(Boolean) } : {}),
+            ...(params.outOfScope !== undefined ? { outOfScope: params.outOfScope.map((entry) => entry.trim()).filter(Boolean) } : {}),
+            ...(params.technologies !== undefined ? { technologies: params.technologies.map((entry) => entry.trim()).filter(Boolean) } : {}),
+            ...(params.tools !== undefined ? { tools: params.tools.map((entry) => entry.trim()).filter(Boolean) } : {}),
+            ...(params.globalRules !== undefined ? { globalRules: params.globalRules.map((entry) => entry.trim()).filter(Boolean) } : {}),
+            ...(params.decisions !== undefined ? { decisions: params.decisions.map((entry) => entry.trim()).filter(Boolean) } : {}),
+        };
+        if (params.descriptionRef !== undefined) {
+            const descriptionRef = normalizeDescriptionRef(params.descriptionRef);
+            if (descriptionRef)
+                next.descriptionRef = descriptionRef;
+            else
+                delete next.descriptionRef;
+        }
+        return next;
+    });
+    return writeAndSummarize(st, `Project discussed/updated: ${persisted.name}. Fields saved: ${receivedFields.join(", ")}.`, { project: persisted, discussed: true, updatedFields: receivedFields });
 });
 server.registerTool("planner-project-guidelines-show", {
     description: "Read the canonical Project Guidelines / Coding Standard section for this project. Call this when planner-task-start or planner-task-switch nextActions require it, and keep the guidance in working memory while doing task work.",
@@ -511,12 +635,10 @@ server.registerTool("planner-project-guidelines-update", {
 }, async ({ content }) => {
     const st = await requireStore();
     const project = await st.loadProject();
-    project.projectGuidelines = {
-        content: content.trim(),
-        updatedAt: project.projectGuidelines.updatedAt,
-        sessionInfo: project.projectGuidelines.sessionInfo,
-    };
-    await st.saveProject(project);
+    await st.updateProject((current) => ({
+        ...current,
+        projectGuidelines: { ...current.projectGuidelines, content: content.trim() },
+    }), { expectedGuidelinesUpdatedAt: project.projectGuidelines.updatedAt });
     const refreshed = await st.loadProject();
     return writeAndSummarize(st, refreshed.projectGuidelines.content
         ? `Project Guidelines updated. Updated at ${refreshed.projectGuidelines.updatedAt}.`
@@ -634,6 +756,123 @@ server.registerTool("planner-task-list", {
     const out = items.map((task) => `- ${task.ref}${task.shortId ? ` · ${task.shortId}` : ""} — ${task.title} (${task.status}${task.priority > 0 ? `; priority ${task.priority}` : ""})`);
     return text(out.join("\n") || "No tasks", { tasks: items });
 });
+server.registerTool("planner-accepted-decision-create", {
+    description: "Create an accepted decision on the project, feature, phase, or task without replacing the full acceptedDecisions array.",
+    inputSchema: {
+        targetType: z.enum(["project", "feature", "phase", "task"]),
+        targetRef: z.string().optional().describe("Feature/phase/task ref. Omit for targetType=project."),
+        title: z.string().min(1),
+        decision: z.string().optional(),
+        rationale: z.string().optional(),
+        implementationNotes: z.string().optional(),
+    },
+}, async ({ targetType, targetRef, title, decision, rationale, implementationNotes }) => {
+    const st = await requireStore();
+    const target = await resolveAcceptedDecisionTarget(st, targetType, targetRef);
+    if (!target.ok)
+        return { isError: true, content: [{ type: "text", text: target.error }], structuredContent: { created: false, errorCode: "ACCEPTED_DECISION_TARGET_NOT_FOUND" } };
+    const createInput = {
+        title,
+        ...(decision !== undefined ? { decision } : {}),
+        ...(rationale !== undefined ? { rationale } : {}),
+        ...(implementationNotes !== undefined ? { implementationNotes } : {}),
+    };
+    try {
+        const acceptedDecision = await st.createAcceptedDecision(target.owner, createInput);
+        return writeAndSummarize(st, `Accepted decision created on ${target.ref}: ${acceptedDecision.title}`, {
+            created: true,
+            targetType,
+            targetRef: target.ref,
+            acceptedDecision,
+        });
+    }
+    catch (error) {
+        return acceptedDecisionMutationFailure(error, "created");
+    }
+});
+server.registerTool("planner-accepted-decision-update", {
+    description: "Update one accepted decision in place while preserving its id and acceptedAt timestamp.",
+    inputSchema: {
+        targetType: z.enum(["project", "feature", "phase", "task"]),
+        targetRef: z.string().optional().describe("Feature/phase/task ref. Omit for targetType=project."),
+        decisionId: z.string().min(1),
+        title: z.string().optional(),
+        decision: z.string().optional(),
+        rationale: z.string().optional(),
+        implementationNotes: z.string().optional(),
+    },
+}, async ({ targetType, targetRef, decisionId, title, decision, rationale, implementationNotes }) => {
+    const mutableFields = ["title", "decision", "rationale", "implementationNotes"];
+    const receivedFields = mutableFields.filter((field) => ({ title, decision, rationale, implementationNotes })[field] !== undefined);
+    if (receivedFields.length === 0) {
+        return mutationNoFieldsFailure({
+            entity: "acceptedDecision",
+            ref: decisionId,
+            operation: "update",
+            mutableFields,
+            retryCommand: "planner-accepted-decision-update with title, decision, rationale, or implementationNotes",
+            readBackCommand: "planner-show or the owning entity show tool",
+        });
+    }
+    const st = await requireStore();
+    const target = await resolveAcceptedDecisionTarget(st, targetType, targetRef);
+    if (!target.ok)
+        return { isError: true, content: [{ type: "text", text: target.error }], structuredContent: { updated: false, errorCode: "ACCEPTED_DECISION_TARGET_NOT_FOUND" } };
+    const updateInput = {
+        ...(title !== undefined ? { title } : {}),
+        ...(decision !== undefined ? { decision } : {}),
+        ...(rationale !== undefined ? { rationale } : {}),
+        ...(implementationNotes !== undefined ? { implementationNotes } : {}),
+    };
+    try {
+        const acceptedDecision = await st.updateAcceptedDecision(target.owner, decisionId, updateInput);
+        return writeAndSummarize(st, `Accepted decision updated on ${target.ref}: ${acceptedDecision.title}`, {
+            updated: true,
+            targetType,
+            targetRef: target.ref,
+            acceptedDecision,
+        });
+    }
+    catch (error) {
+        return acceptedDecisionMutationFailure(error, "updated");
+    }
+});
+server.registerTool("planner-accepted-decision-delete", {
+    description: "Delete one accepted decision from the project, feature, phase, or task without replacing the full acceptedDecisions array.",
+    inputSchema: {
+        targetType: z.enum(["project", "feature", "phase", "task"]),
+        targetRef: z.string().optional().describe("Feature/phase/task ref. Omit for targetType=project."),
+        decisionId: z.string().min(1),
+        confirmed: z.boolean().describe("Must be true to confirm deleting this accepted decision."),
+    },
+}, async ({ targetType, targetRef, decisionId, confirmed }) => {
+    const st = await requireStore();
+    const target = await resolveAcceptedDecisionTarget(st, targetType, targetRef);
+    if (!target.ok)
+        return { isError: true, content: [{ type: "text", text: target.error }], structuredContent: { deleted: false, errorCode: "ACCEPTED_DECISION_TARGET_NOT_FOUND" } };
+    if (!confirmed) {
+        return text(`Delete not confirmed for accepted decision ${decisionId} on ${target.ref}. Retry with confirmed=true.`, {
+            deleted: false,
+            confirmRequired: true,
+            targetType,
+            targetRef: target.ref,
+            decisionId,
+        });
+    }
+    try {
+        const acceptedDecision = await st.deleteAcceptedDecision(target.owner, decisionId);
+        return writeAndSummarize(st, `Accepted decision deleted from ${target.ref}: ${acceptedDecision.title}`, {
+            deleted: true,
+            targetType,
+            targetRef: target.ref,
+            decisionId,
+            acceptedDecision,
+        });
+    }
+    catch (error) {
+        return acceptedDecisionMutationFailure(error, "deleted");
+    }
+});
 server.registerTool("planner-feature-add", {
     description: "Create a feature with a rich description. REQUIRED: description must include code references (file:line), current implementation state (what exists, what is unimplemented), systems/structs/traits involved, concrete goals, and behaviors to preserve. The description is the primary context for future agents resuming this feature; one-liners cause misalignment.",
     inputSchema: {
@@ -643,44 +882,46 @@ server.registerTool("planner-feature-add", {
     },
 }, async ({ name, description, status }) => {
     const st = await requireStore();
-    const timestamp = nowISO();
-    const effectiveStatus = status ?? "planned";
-    const existingFeatures = (await st.loadFeatures()).features;
-    const id = createFeatureId();
-    const identity = await st.allocateEntityIdentity("feature", id);
-    const priority = await st.nextPriority("feature");
-    const feature = {
-        id,
-        number: identity.number,
-        shortId: identity.shortId,
-        priority,
-        name: name.trim(),
-        description: description?.trim() ?? "",
-        descriptionUpdatedAt: timestamp,
-        status: effectiveStatus,
-        discussedAt: "",
-        contextReady: false,
-        contextReadyReason: "",
-        startDate: effectiveStatus === "in-progress" ? new Date().toISOString().slice(0, 10) : "",
-        endDate: effectiveStatus === "done" ? new Date().toISOString().slice(0, 10) : "",
-        workDone: "",
-        workRemaining: "",
-        acceptedDecisions: [],
-        phaseIds: [],
-        dependsOn: [],
-        statusLog: [],
-        sessionInfo: [],
-        createdAt: timestamp,
-        updatedAt: timestamp,
-    };
-    await st.updateFeatures((doc) => {
-        doc.features.push(feature);
-        return doc;
+    return st.runBatch(async () => {
+        const timestamp = nowISO();
+        const effectiveStatus = status ?? "planned";
+        const existingFeatures = (await st.loadFeatures()).features;
+        const id = createFeatureId();
+        const identity = await st.allocateEntityIdentity("feature", id);
+        const priority = await st.nextPriority("feature");
+        const feature = {
+            id,
+            number: identity.number,
+            shortId: identity.shortId,
+            priority,
+            name: name.trim(),
+            description: description?.trim() ?? "",
+            descriptionUpdatedAt: timestamp,
+            status: effectiveStatus,
+            discussedAt: "",
+            contextReady: false,
+            contextReadyReason: "",
+            startDate: effectiveStatus === "in-progress" ? new Date().toISOString().slice(0, 10) : "",
+            endDate: effectiveStatus === "done" ? new Date().toISOString().slice(0, 10) : "",
+            workDone: "",
+            workRemaining: "",
+            acceptedDecisions: [],
+            phaseIds: [],
+            dependsOn: [],
+            statusLog: [],
+            sessionInfo: [],
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+        await st.updateFeatures((doc) => {
+            doc.features.push(feature);
+            return doc;
+        });
+        return writeAndSummarize(st, `✅ Feature created: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}`);
     });
-    return writeAndSummarize(st, `✅ Feature created: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}`);
 });
 server.registerTool("planner-feature-show", {
-    description: "Show a feature by id or name.",
+    description: "Show a feature by id or name. Pass full=true for the description and every canonical Accepted Decision field.",
     inputSchema: { feature: z.string().min(1).describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the feature description. Default: compact identity only (saves tokens).") },
 }, async ({ feature: ref, full }, extra) => {
     const plannerSessionId = plannerSessionIdFor(extra);
@@ -690,12 +931,22 @@ 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)`;
     const descriptionRefBlock = feature.descriptionRef ? `\n\nDescription reference:\n- ${feature.descriptionRef}` : "";
-    return text(full ? `${summary}\n\n${feature.description || ""}${descriptionRefBlock}` : summary, full ? { feature: { ref: formatFeatureRef(feature.number), description: feature.description, descriptionRef: feature.descriptionRef || "" } } : undefined);
+    if (!full)
+        return text(summary);
+    const decisionBlock = renderAcceptedDecisionsSection("Accepted Decisions", feature.acceptedDecisions);
+    const result = text(`${summary}\n\n${feature.description || ""}${descriptionRefBlock}\n\n${decisionBlock}`, {
+        feature: {
+            ref: formatFeatureRef(feature.number),
+            description: feature.description,
+            descriptionRef: feature.descriptionRef || "",
+            acceptedDecisions: feature.acceptedDecisions,
+        },
+    });
+    markCanonicalFullReadForSessionId(plannerSessionId, "feature", feature, result.content[0].text);
+    return result;
 });
 server.registerTool("planner-feature-discuss", {
     description: "Persist feature discovery/governance fields and mark the feature context as ready.",
@@ -848,20 +1099,20 @@ server.registerTool("planner-feature-delete", {
         return text(resolvedFeature.error);
     const feature = resolvedFeature.feature;
     const phases = (await st.loadAllPhases()).filter((phase) => phase.featureId === feature.id);
-    await st.updateFeatures((doc) => {
-        doc.features = doc.features.filter((entry) => entry.id !== feature.id);
-        return doc;
-    });
-    for (const phase of phases) {
-        if (cascade) {
-            await st.deletePhase(phase.id);
-        }
-        else {
-            phase.featureId = undefined;
-            phase.updatedAt = nowISO();
-            await st.savePhase(phase);
+    await st.runBatch(async () => {
+        await st.updateFeatures((doc) => {
+            doc.features = doc.features.filter((entry) => entry.id !== feature.id);
+            return doc;
+        });
+        for (const phase of phases) {
+            if (cascade) {
+                await st.deletePhase(phase.id);
+            }
+            else {
+                await st.updatePhase(phase.id, (current) => ({ ...current, featureId: undefined, updatedAt: nowISO() }));
+            }
         }
-    }
+    });
     return writeAndSummarize(st, `Feature deleted: ${feature.id}${cascade ? `; deleted ${phases.length} phases` : `; unlinked ${phases.length} phases`}`, { deleted: feature.id, affectedPhases: phases.length, cascade: Boolean(cascade) });
 });
 server.registerTool("planner-phase-add", {
@@ -888,7 +1139,7 @@ server.registerTool("planner-phase-add", {
         return text(`Resolved feature ${featureRef} no longer exists. Refusing to create phase.`);
     const lockKey = feature?.id ?? "__unscoped__";
     let phase;
-    await withFeatureLock(lockKey, async () => {
+    await st.runBatch(() => withFeatureLock(lockKey, async () => {
         const phases = await st.loadAllPhases();
         const featurePhases = feature ? phases.filter((phase) => phase.featureId === feature.id) : phases;
         const timestamp = nowISO();
@@ -942,13 +1193,13 @@ server.registerTool("planner-phase-add", {
             });
         }
         await st.writeGenerated();
-    });
+    }));
     if (!phase)
         return text("Phase creation failed.");
     return writeAndSummarize(st, `✅ Phase created: ${formatPhaseRef(phase.number, feature?.number)} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}`);
 });
 server.registerTool("planner-phase-show", {
-    description: "Show a phase by id or name, including derived linked requirements in the full view.",
+    description: "Show a phase by id or name, including every canonical Accepted Decision field and derived linked requirements in the full view.",
     inputSchema: { phase: z.string().min(1).describe("Phase ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."), full: z.boolean().optional().describe("If true, include the phase description. Default: compact identity only (saves tokens).") },
 }, async ({ phase: ref, full }, extra) => {
     const plannerSessionId = plannerSessionIdFor(extra);
@@ -957,16 +1208,27 @@ 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"}` : ""})`;
     const descriptionRefBlock = phase.descriptionRef ? `\n\nDescription reference:\n- ${phase.descriptionRef}` : "";
     const requirementsBlock = reqCount > 0
-        ? `\n\nLinked requirements:\n${linkedRequirements.map((requirement) => `- ${requirement.title} (${requirement.status})`).join("\n")}`
+        ? `\n\nLinked requirements:\n${linkedRequirements.map((requirement) => `- ${requirement.title}`).join("\n")}`
         : "";
-    return text(full ? `${summary}\n\n${phase.description || ""}${descriptionRefBlock}${requirementsBlock}` : summary, {
+    if (!full)
+        return text(summary, {
+            phase: {
+                ref: formatPhaseRef(phase.number, featureNumberOfPhase(phase, features)),
+                shortId: phase.shortId,
+                title: phase.title,
+                summary: phase.summary,
+                status: phase.status,
+                taskCount: phase.tasks.length,
+            },
+            linkedRequirements,
+        });
+    const decisionBlock = renderAcceptedDecisionsSection("Accepted Decisions", phase.acceptedDecisions);
+    const result = text(`${summary}\n\n${phase.description || ""}${descriptionRefBlock}${requirementsBlock}\n\n${decisionBlock}`, {
         phase: {
             ref: formatPhaseRef(phase.number, featureNumberOfPhase(phase, features)),
             shortId: phase.shortId,
@@ -974,22 +1236,28 @@ server.registerTool("planner-phase-show", {
             summary: phase.summary,
             status: phase.status,
             taskCount: phase.tasks.length,
-            ...(full ? { description: phase.description, descriptionRef: phase.descriptionRef || "" } : {}),
+            description: phase.description,
+            descriptionRef: phase.descriptionRef || "",
+            acceptedDecisions: phase.acceptedDecisions,
         },
         linkedRequirements,
     });
+    markCanonicalFullReadForSessionId(plannerSessionId, "phase", phase, result.content[0].text);
+    return result;
 });
 server.registerTool("planner-phase-discuss", {
-    description: "Persist phase discovery fields and mark phase planned.",
+    description: "Persist phase discovery fields and mark governance context ready without overriding derived status.",
     inputSchema: {
         phase: z.string().min(1).describe("Phase ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
-        goal: z.string().optional(),
+        goal: z.string().optional().describe("Backward-compatible single main goal."),
+        goals: z.array(z.string()).optional().describe("Replace the phase goals list."),
         summary: z.string().optional(),
         scope: z.string().optional(),
         descriptionRef: z.string().optional().describe("Optional markdown reference under .planner/docs/ for the full phase description."),
         nonGoals: z.array(z.string()).optional(),
         dependencies: z.array(z.string()).optional(),
         risks: z.array(z.string()).optional(),
+        openQuestions: z.array(z.string()).optional(),
         completionCriteria: z.array(z.string()).optional(),
     },
 }, async ({ phase: ref, ...updates }) => {
@@ -998,7 +1266,7 @@ server.registerTool("planner-phase-discuss", {
     const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
-    const mutableFields = ["goal", "summary", "scope", "descriptionRef", "nonGoals", "dependencies", "risks", "completionCriteria"];
+    const mutableFields = ["goal", "goals", "summary", "scope", "descriptionRef", "nonGoals", "dependencies", "risks", "openQuestions", "completionCriteria"];
     const receivedFields = mutableFields.filter((field) => updates[field] !== undefined);
     if (receivedFields.length === 0) {
         return mutationNoFieldsFailure({
@@ -1017,7 +1285,9 @@ server.registerTool("planner-phase-discuss", {
         });
     }
     const phase = await st.updatePhase(found.id, (entry) => {
-        if (updates.goal !== undefined)
+        if (updates.goals !== undefined)
+            entry.goals = updates.goals.map((item) => item.trim()).filter(Boolean);
+        else if (updates.goal !== undefined)
             entry.goals = [updates.goal.trim()].filter(Boolean);
         if (updates.summary !== undefined)
             entry.summary = updates.summary.trim();
@@ -1036,19 +1306,20 @@ server.registerTool("planner-phase-discuss", {
             entry.dependencies = updates.dependencies.map((item) => item.trim()).filter(Boolean);
         if (updates.risks !== undefined)
             entry.risks = updates.risks.map((item) => item.trim()).filter(Boolean);
+        if (updates.openQuestions !== undefined)
+            entry.openQuestions = updates.openQuestions.map((item) => item.trim()).filter(Boolean);
         if (updates.completionCriteria !== undefined)
             entry.completionCriteria = updates.completionCriteria.map((item) => item.trim()).filter(Boolean);
-        entry.status = "planned";
         entry.discussedAt = nowISO();
         entry.contextReady = true;
         entry.contextReadyReason = "Updated through planner-phase-discuss MCP tool.";
         entry.updatedAt = nowISO();
         return entry;
     });
-    return writeAndSummarize(st, `✅ Phase discussed/planned: ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`, { phase, discussed: true, updatedFields: receivedFields });
+    return writeAndSummarize(st, `✅ Phase discussed/context ready: ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`, { phase, discussed: true, contextReady: true, updatedFields: receivedFields });
 });
 server.registerTool("planner-phase-update", {
-    description: "Update phase fields.",
+    description: "Update phase fields, including parent relinking and planning metadata. Derived status remains read-only.",
     inputSchema: {
         phase: z.string().min(1),
         title: z.string().optional(),
@@ -1056,7 +1327,15 @@ server.registerTool("planner-phase-update", {
         summary: z.string().optional(),
         description: z.string().optional(),
         descriptionRef: z.string().optional().describe("Optional markdown reference under .planner/docs/ for the full phase description."),
+        featureId: z.string().optional().describe("Feature ref to relink this phase to, or an empty string to unlink it."),
         priority: z.number().int().nonnegative().optional().describe("Display order within the feature (lower = higher)."),
+        goals: z.array(z.string()).optional(),
+        nonGoals: z.array(z.string()).optional(),
+        dependencies: z.array(z.string()).optional(),
+        risks: z.array(z.string()).optional(),
+        openQuestions: z.array(z.string()).optional(),
+        decisions: z.array(z.string()).optional(),
+        completionCriteria: z.array(z.string()).optional(),
     },
 }, async ({ phase: ref, ...updates }) => {
     const st = await requireStore();
@@ -1067,7 +1346,7 @@ server.registerTool("planner-phase-update", {
     if (updates.status !== undefined) {
         return derivedStatusReadOnlyResult("phase", formatPhaseRef(found.number, featureNumberOfPhase(found, features)), updates.status, found.status);
     }
-    const mutableFields = ["title", "summary", "description", "descriptionRef", "priority"];
+    const mutableFields = ["title", "summary", "description", "descriptionRef", "featureId", "priority", "goals", "nonGoals", "dependencies", "risks", "openQuestions", "decisions", "completionCriteria"];
     const receivedFields = mutableFields.filter((field) => updates[field] !== undefined);
     if (receivedFields.length === 0) {
         return mutationNoFieldsFailure({
@@ -1085,26 +1364,83 @@ server.registerTool("planner-phase-update", {
             },
         });
     }
-    const phase = await st.updatePhase(found.id, (entry) => {
-        if (updates.title !== undefined)
-            entry.title = updates.title.trim();
-        if (updates.summary !== undefined)
-            entry.summary = updates.summary.trim();
-        if (updates.description !== undefined)
-            entry.description = updates.description.trim();
-        if (updates.descriptionRef !== undefined) {
-            const descriptionRef = normalizeDescriptionRef(updates.descriptionRef);
-            if (descriptionRef)
-                entry.descriptionRef = descriptionRef;
-            else
-                delete entry.descriptionRef;
+    const previousFeatureId = found.featureId;
+    let nextFeatureId = previousFeatureId;
+    if (updates.featureId !== undefined) {
+        if (updates.featureId.trim() === "") {
+            nextFeatureId = undefined;
         }
-        if (updates.priority !== undefined)
-            entry.priority = updates.priority;
-        entry.updatedAt = nowISO();
-        return entry;
+        else {
+            const resolvedFeature = resolveFeatureRefStrict(features, updates.featureId);
+            if (!resolvedFeature.ok)
+                return text(resolvedFeature.error);
+            nextFeatureId = resolvedFeature.feature.id;
+        }
+    }
+    let phase;
+    await st.runBatch(async () => {
+        phase = await st.updatePhase(found.id, (entry) => {
+            if (updates.title !== undefined) {
+                entry.title = updates.title.trim();
+                entry.slug = normalizeSlug(updates.title);
+            }
+            if (updates.summary !== undefined)
+                entry.summary = updates.summary.trim();
+            if (updates.description !== undefined)
+                entry.description = updates.description.trim();
+            if (updates.descriptionRef !== undefined) {
+                const descriptionRef = normalizeDescriptionRef(updates.descriptionRef);
+                if (descriptionRef)
+                    entry.descriptionRef = descriptionRef;
+                else
+                    delete entry.descriptionRef;
+            }
+            if (updates.featureId !== undefined)
+                entry.featureId = nextFeatureId;
+            if (updates.priority !== undefined)
+                entry.priority = updates.priority;
+            if (updates.goals !== undefined)
+                entry.goals = updates.goals.map((item) => item.trim()).filter(Boolean);
+            if (updates.nonGoals !== undefined)
+                entry.nonGoals = updates.nonGoals.map((item) => item.trim()).filter(Boolean);
+            if (updates.dependencies !== undefined)
+                entry.dependencies = updates.dependencies.map((item) => item.trim()).filter(Boolean);
+            if (updates.risks !== undefined)
+                entry.risks = updates.risks.map((item) => item.trim()).filter(Boolean);
+            if (updates.openQuestions !== undefined)
+                entry.openQuestions = updates.openQuestions.map((item) => item.trim()).filter(Boolean);
+            if (updates.decisions !== undefined)
+                entry.decisions = updates.decisions.map((item) => item.trim()).filter(Boolean);
+            if (updates.completionCriteria !== undefined)
+                entry.completionCriteria = updates.completionCriteria.map((item) => item.trim()).filter(Boolean);
+            entry.updatedAt = nowISO();
+            return entry;
+        });
+        if (updates.featureId !== undefined && nextFeatureId !== previousFeatureId) {
+            await st.updateFeatures((document) => {
+                for (const feature of document.features) {
+                    if (feature.id === previousFeatureId)
+                        feature.phaseIds = feature.phaseIds.filter((phaseId) => phaseId !== found.id);
+                    if (feature.id === nextFeatureId && !feature.phaseIds.includes(found.id))
+                        feature.phaseIds.push(found.id);
+                }
+                return document;
+            });
+        }
+        await st.writeGenerated();
     });
-    return writeAndSummarize(st, `✅ Phase updated: ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`, { phase, updated: true, updatedFields: receivedFields });
+    const persisted = phase;
+    const refreshedFeatures = (await st.loadFeatures()).features;
+    const descriptionFreshness = receivedFields.some((field) => field === "description" || field === "descriptionRef")
+        ? await st.previewDescriptionReconciliation()
+        : null;
+    const staleParentRefs = descriptionFreshness?.diagnostics
+        .filter((entry) => entry.state === "stale" && entry.ownerId === persisted.featureId)
+        .map((entry) => entry.ownerRef) ?? [];
+    const freshnessNotice = staleParentRefs.length > 0
+        ? `\n⚠️ Parent description review required: ${staleParentRefs.join(", ")}. Run planner-description-freshness for the non-mutating reconciliation preview.`
+        : "";
+    return text(`✅ Phase updated: ${formatPhaseRef(persisted.number, featureNumberOfPhase(persisted, refreshedFeatures))} — ${persisted.title}${persisted.shortId ? ` · ${persisted.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.${freshnessNotice}`, { phase: persisted, updated: true, updatedFields: receivedFields, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) });
 });
 server.registerTool("planner-phase-delete", {
     description: "Delete a phase and unlink it from features.",
@@ -1114,11 +1450,13 @@ server.registerTool("planner-phase-delete", {
     const phase = findPhaseByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!phase)
         return text(`Phase not found: ${ref}`);
-    await st.deletePhase(phase.id);
-    await st.updateFeatures((doc) => {
-        for (const feature of doc.features)
-            feature.phaseIds = feature.phaseIds.filter((id) => id !== phase.id);
-        return doc;
+    await st.runBatch(async () => {
+        await st.deletePhase(phase.id);
+        await st.updateFeatures((doc) => {
+            for (const feature of doc.features)
+                feature.phaseIds = feature.phaseIds.filter((id) => id !== phase.id);
+            return doc;
+        });
     });
     const dFeat = (await st.loadFeatures()).features.find((f) => f.id === phase.featureId);
     return writeAndSummarize(st, `Phase deleted: ${formatPhaseRef(phase.number, dFeat?.number)}${phase.shortId ? ` · ${phase.shortId}` : ""}`, { deleted: phase.id });
@@ -1134,70 +1472,73 @@ server.registerTool("planner-task-add", {
     },
 }, async ({ feature: featureRef, phase: ref, title, description, checklist }) => {
     const st = await requireStore();
-    const features = (await st.loadFeatures()).features;
-    if (!featureRef?.trim())
-        return text("feature is required: a task must belong to a feature.");
-    const resolvedFeature = resolveFeatureRefStrict(features, featureRef);
-    if (!resolvedFeature.ok)
-        return text(resolvedFeature.error);
-    const featureValidation = await validateResolvedTarget("feature", resolvedFeature.feature.id, () => st.loadFeatures().then((doc) => doc.features.find((f) => f.id === resolvedFeature.feature.id)).catch(() => undefined));
-    if (!featureValidation.ok)
-        return text(featureValidation.error);
-    const feature = resolvedFeature.feature;
-    if (!feature)
-        return text(`Resolved feature ${featureRef} no longer exists. Refusing to create task.`);
-    const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
-    if (!found)
-        return text(`Phase not found: ${ref}`);
-    if (found.featureId !== feature.id)
-        return text(`Phase ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} does not belong to feature ${formatFeatureRef(feature.number)}. Refusing to create task.`);
-    const phaseValidation = await validateResolvedTarget("phase", found.id, () => st.loadPhase(found.id).catch(() => undefined));
-    if (!phaseValidation.ok)
-        return text(phaseValidation.error);
-    const existingPhase = await st.loadPhase(found.id);
-    if (!existingPhase)
-        return text(`Resolved phase ${found.id} no longer exists. Refusing to create task.`);
-    const timestamp = nowISO();
-    const taskId = createTaskId();
-    const identity = await st.allocateEntityIdentity("task", taskId);
-    const priority = await st.nextPriority("task", found.id);
-    const task = {
-        id: taskId,
-        phaseId: found.id,
-        number: identity.number,
-        shortId: identity.shortId,
-        priority,
-        shortName: clampSlug(title, 30, `task-${Date.now().toString(36)}`),
-        title: title.trim(),
-        status: "planned",
-        description: description?.trim() ?? "",
-        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 })),
-        subtasks: [],
-        dependsOn: [],
-        pauseSnapshot: null,
-        pauseHistory: [],
-        startedAt: "",
-        completedAt: "",
-        createdAt: timestamp,
-        updatedAt: timestamp,
-    };
-    await st.updatePhase(found.id, (entry) => {
-        entry.tasks.push(task);
-        entry.taskIds.push(task.id);
-        entry.updatedAt = timestamp;
-        return entry;
+    return st.runBatch(async () => {
+        const features = (await st.loadFeatures()).features;
+        if (!featureRef?.trim())
+            return text("feature is required: a task must belong to a feature.");
+        const resolvedFeature = resolveFeatureRefStrict(features, featureRef);
+        if (!resolvedFeature.ok)
+            return text(resolvedFeature.error);
+        const featureValidation = await validateResolvedTarget("feature", resolvedFeature.feature.id, () => st.loadFeatures().then((doc) => doc.features.find((f) => f.id === resolvedFeature.feature.id)).catch(() => undefined));
+        if (!featureValidation.ok)
+            return text(featureValidation.error);
+        const feature = resolvedFeature.feature;
+        if (!feature)
+            return text(`Resolved feature ${featureRef} no longer exists. Refusing to create task.`);
+        const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
+        if (!found)
+            return text(`Phase not found: ${ref}`);
+        if (found.featureId !== feature.id)
+            return text(`Phase ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} does not belong to feature ${formatFeatureRef(feature.number)}. Refusing to create task.`);
+        const phaseValidation = await validateResolvedTarget("phase", found.id, () => st.loadPhase(found.id).catch(() => undefined));
+        if (!phaseValidation.ok)
+            return text(phaseValidation.error);
+        const existingPhase = await st.loadPhase(found.id);
+        if (!existingPhase)
+            return text(`Resolved phase ${found.id} no longer exists. Refusing to create task.`);
+        const timestamp = nowISO();
+        const taskId = createTaskId();
+        const identity = await st.allocateEntityIdentity("task", taskId);
+        const priority = await st.nextPriority("task", found.id);
+        const task = {
+            id: taskId,
+            phaseId: found.id,
+            number: identity.number,
+            shortId: identity.shortId,
+            priority,
+            shortName: clampSlug(title, 30, `task-${Date.now().toString(36)}`),
+            title: title.trim(),
+            status: "planned",
+            description: description?.trim() ?? "",
+            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 })),
+            subtasks: [],
+            dependsOn: [],
+            pauseSnapshot: null,
+            pauseHistory: [],
+            startedAt: "",
+            completedAt: "",
+            activeOwnerSession: "",
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+        await st.updatePhase(found.id, (entry) => {
+            entry.tasks.push(task);
+            entry.taskIds.push(task.id);
+            entry.updatedAt = timestamp;
+            return entry;
+        });
+        const finalFeatures = (await st.loadFeatures()).features;
+        return writeAndSummarize(st, `✅ Task created: ${taskCompositeRef(task, found, finalFeatures)} — ${task.title} (planned)${task.shortId ? ` · ${task.shortId}` : ""}`);
     });
-    const finalFeatures = (await st.loadFeatures()).features;
-    return writeAndSummarize(st, `✅ Task created: ${taskCompositeRef(task, found, finalFeatures)} — ${task.title} (planned)${task.shortId ? ` · ${task.shortId}` : ""}`);
 });
 server.registerTool("planner-task-show", {
-    description: "Show a task by id or name.",
+    description: "Show a task by id or name. Pass full=true for every canonical Accepted Decision field plus execution and resume context.",
     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 }, extra) => {
     const plannerSessionId = plannerSessionIdFor(extra);
@@ -1205,8 +1546,6 @@ server.registerTool("planner-task-show", {
     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)
@@ -1238,7 +1577,17 @@ server.registerTool("planner-task-show", {
     }
     if (log)
         sections.push(`Status log:\n${log}`);
-    return text(sections.join("\n\n"), { task: { ref: taskCompositeRef(found.task, found.phase, features), description: found.task.description, descriptionRef: found.task.descriptionRef || "" } });
+    sections.push(renderAcceptedDecisionsSection("Accepted Decisions", found.task.acceptedDecisions));
+    const result = text(sections.join("\n\n"), {
+        task: {
+            ref: taskCompositeRef(found.task, found.phase, features),
+            description: found.task.description,
+            descriptionRef: found.task.descriptionRef || "",
+            acceptedDecisions: found.task.acceptedDecisions,
+        },
+    });
+    markCanonicalFullReadForSessionId(plannerSessionId, "task", found.task, result.content[0].text);
+    return result;
 });
 server.registerTool("planner-task-discuss", {
     description: "Persist task execution notes/checklist.",
@@ -1297,6 +1646,48 @@ server.registerTool("planner-task-discuss", {
     const t = updatedTask ?? found.task;
     return writeAndSummarize(st, `✅ Task discussed/updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`, { task: t, discussed: true, updatedFields: receivedFields });
 });
+server.registerTool("planner-task-dependency-add", {
+    description: "Add a validated task dependency atomically; rejects self-dependencies, foreign tasks, and cycles.",
+    inputSchema: { task: z.string().min(1), dependsOn: z.string().min(1) },
+}, async ({ task: ref, dependsOn }, extra) => {
+    const st = await requireStore();
+    const features = (await st.loadFeatures()).features;
+    const found = findTaskByRef(await st.loadAllPhases(), features, ref);
+    const dependency = findTaskByRef(await st.loadAllPhases(), features, dependsOn);
+    if (!found || !dependency)
+        return { ...text("Dependency target not found.", { updated: false, errorCode: "DEPENDENCY_TASK_NOT_FOUND" }), isError: true };
+    try {
+        const result = await st.addTaskDependency(found.phase.id, found.task.id, dependency.task.id);
+        await st.writeGenerated();
+        return text(`✅ Dependency added: ${taskCompositeRef(found.task, found.phase, features)} depends on ${taskCompositeRef(dependency.task, dependency.phase, features)}.`, { updated: true, task: result });
+    }
+    catch (error) {
+        const details = error instanceof PlanStoreError ? error.details : undefined;
+        return { ...text(error instanceof Error ? error.message : "Dependency update failed.", { updated: false, errorCode: details?.errorCode ?? "DEPENDENCY_UPDATE_FAILED" }), isError: true };
+    }
+});
+server.registerTool("planner-task-dependency-delete", {
+    description: "Remove a task dependency atomically after explicit confirmation.",
+    inputSchema: { task: z.string().min(1), dependsOn: z.string().min(1), confirmed: z.boolean() },
+}, async ({ task: ref, dependsOn, confirmed }) => {
+    if (!confirmed)
+        return { ...text("Explicit confirmation is required to remove a dependency.", { updated: false, errorCode: "CONFIRMATION_REQUIRED" }), isError: true };
+    const st = await requireStore();
+    const features = (await st.loadFeatures()).features;
+    const found = findTaskByRef(await st.loadAllPhases(), features, ref);
+    const dependency = findTaskByRef(await st.loadAllPhases(), features, dependsOn);
+    if (!found || !dependency)
+        return { ...text("Dependency target not found.", { updated: false, errorCode: "DEPENDENCY_TASK_NOT_FOUND" }), isError: true };
+    try {
+        const result = await st.deleteTaskDependency(found.phase.id, found.task.id, dependency.task.id);
+        await st.writeGenerated();
+        return text("✅ Dependency removed.", { updated: true, task: result });
+    }
+    catch (error) {
+        const details = error instanceof PlanStoreError ? error.details : undefined;
+        return { ...text(error instanceof Error ? error.message : "Dependency deletion failed.", { updated: false, errorCode: details?.errorCode ?? "DEPENDENCY_DELETE_FAILED" }), isError: true };
+    }
+});
 server.registerTool("planner-task-update", {
     description: "Update task fields. A motivation is REQUIRED when changing to blocked, canceled, deferred, rejected, waiting, or back to planned from another status.",
     inputSchema: {
@@ -1305,11 +1696,14 @@ server.registerTool("planner-task-update", {
         status: z.enum(STATUS_VALUES).optional(),
         description: z.string().optional(),
         descriptionRef: z.string().optional().describe("Optional markdown reference under .planner/docs/ for the full task description."),
+        notes: z.string().optional().describe("Implementation notes."),
+        decisions: z.array(z.string()).optional().describe("Replace the task decisions list."),
         motivation: z.string().optional(),
         priority: z.number().int().nonnegative().optional().describe("Display order within the phase (lower = higher)."),
         checklist: z.array(z.string()).optional().describe("Replace the task checklist (implementation steps, plain strings). Agents should tick steps via planner-task-checklist-toggle, not write DONE in titles."),
+        subtasks: z.array(z.object({ id: z.string().optional(), title: z.string().min(1), description: z.string().optional(), status: z.enum(STATUS_VALUES).optional() })).optional().describe("Replace subtasks; existing IDs must belong to this task and omitted IDs are planner-generated."),
     },
-}, async ({ task: ref, title, status, description, descriptionRef: rawDescriptionRef, motivation, priority, checklist }) => {
+}, async ({ task: ref, title, status, description, descriptionRef: rawDescriptionRef, notes, decisions, motivation, priority, checklist, subtasks }) => {
     const st = await requireStore();
     const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
@@ -1327,8 +1721,8 @@ server.registerTool("planner-task-update", {
                 `Provide the \"motivation\" parameter with a detailed explanation of why this change is needed.`);
         }
     }
-    const mutableFields = ["title", "status", "description", "descriptionRef", "motivation", "priority", "checklist"];
-    const updateInputs = { title, status, description, descriptionRef: rawDescriptionRef, motivation, priority, checklist };
+    const mutableFields = ["title", "status", "description", "descriptionRef", "notes", "decisions", "motivation", "priority", "checklist", "subtasks"];
+    const updateInputs = { title, status, description, descriptionRef: rawDescriptionRef, notes, decisions, motivation, priority, checklist, subtasks };
     const receivedFields = mutableFields.filter((field) => updateInputs[field] !== undefined);
     if (receivedFields.length === 0) {
         return mutationNoFieldsFailure({
@@ -1346,43 +1740,70 @@ server.registerTool("planner-task-update", {
             },
         });
     }
+    if (subtasks !== undefined) {
+        const existingIds = new Set(found.task.subtasks.map((item) => item.id));
+        if (subtasks.some((item) => item.id !== undefined && !existingIds.has(item.id))) {
+            return { ...text("Subtask IDs must belong to the target task.", { updated: false, errorCode: "SUBTASK_ID_INVALID" }), isError: true };
+        }
+    }
     let updatedTask;
     const timestamp = nowISO();
-    await st.updatePhase(found.phase.id, (phase) => {
-        const task = phase.tasks.find((entry) => entry.id === found.task.id);
-        if (!task)
-            return phase;
-        if (title !== undefined)
-            task.title = title.trim();
-        if (priority !== undefined)
-            task.priority = priority;
-        if (description !== undefined)
-            task.description = description.trim();
-        if (rawDescriptionRef !== undefined) {
-            const descriptionRef = normalizeDescriptionRef(rawDescriptionRef);
-            if (descriptionRef)
-                task.descriptionRef = descriptionRef;
-            else
-                delete task.descriptionRef;
-        }
-        if (status !== undefined && status !== task.status) {
-            // Record status change in the incremental statusLog.
-            const entry = {
-                id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${task.status}-${status}`),
-                date: timestamp,
-                fromStatus: task.status,
-                toStatus: status,
-                title: motivation?.split("\n")[0]?.trim() || `${task.status} → ${status}`,
-                description: motivation?.trim() || "",
-            };
-            task.statusLog = [...(task.statusLog ?? []), entry];
-            applyTaskLifecycleDates(task, status, timestamp);
-        }
-        task.updatedAt = timestamp;
-        phase.updatedAt = timestamp;
-        updatedTask = task;
-        return phase;
-    });
+    try {
+        await st.updateTask(found.phase.id, found.task.id, (task) => {
+            if (title !== undefined)
+                task.title = title.trim();
+            if (priority !== undefined)
+                task.priority = priority;
+            if (description !== undefined)
+                task.description = description.trim();
+            if (rawDescriptionRef !== undefined) {
+                const descriptionRef = normalizeDescriptionRef(rawDescriptionRef);
+                if (descriptionRef)
+                    task.descriptionRef = descriptionRef;
+                else
+                    delete task.descriptionRef;
+            }
+            if (notes !== undefined)
+                task.notes = notes.trim();
+            if (decisions !== undefined)
+                task.decisions = decisions.map((item) => item.trim()).filter(Boolean);
+            if (checklist !== undefined) {
+                task.checklist = checklist.map((item, index) => ({
+                    id: createChecklistItemId(task.id, index + 1, item),
+                    number: index + 1,
+                    title: item.trim(),
+                    checked: false,
+                }));
+            }
+            if (subtasks !== undefined) {
+                const existingIds = new Set(task.subtasks.map((item) => item.id));
+                if (subtasks.some((item) => item.id !== undefined && !existingIds.has(item.id))) {
+                    throw new PlanStoreError("Subtask IDs must belong to the target task.", undefined, { errorCode: "SUBTASK_ID_INVALID" });
+                }
+                task.subtasks = subtasks.map((item) => ({ id: item.id ?? randomUUID(), title: item.title.trim(), description: item.description?.trim() ?? "", status: item.status ?? "planned", createdAt: task.subtasks.find((candidate) => candidate.id === item.id)?.createdAt ?? timestamp, updatedAt: timestamp }));
+            }
+            if (status !== undefined && status !== task.status) {
+                // Record status change in the incremental statusLog.
+                const entry = {
+                    id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${task.status}-${status}`),
+                    date: timestamp,
+                    fromStatus: task.status,
+                    toStatus: status,
+                    title: motivation?.split("\n")[0]?.trim() || `${task.status} → ${status}`,
+                    description: motivation?.trim() || "",
+                };
+                task.statusLog = [...(task.statusLog ?? []), entry];
+                applyTaskLifecycleDates(task, status, timestamp);
+            }
+            task.updatedAt = timestamp;
+            updatedTask = task;
+            return task;
+        });
+    }
+    catch (error) {
+        const details = error instanceof PlanStoreError ? error.details : undefined;
+        return { ...text(`Task update failed: ${error instanceof Error ? error.message : "unknown error"}`, { updated: false, errorCode: details?.errorCode ?? "TASK_UPDATE_FAILED" }), isError: true };
+    }
     await st.syncTaskStatusRollup(found.phase.id);
     const features = (await st.loadFeatures()).features;
     const t = updatedTask ?? found.task;
@@ -1401,7 +1822,20 @@ server.registerTool("planner-task-update", {
             }
         }
     }
-    return writeAndSummarize(st, `✅ Task updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.${resumeNotice}`, resumeRequired ? { task: t, updated: true, updatedFields: receivedFields, resumeRequired } : { task: t, updated: true, updatedFields: receivedFields });
+    const descriptionFreshness = receivedFields.some((field) => field === "description" || field === "descriptionRef")
+        ? await st.previewDescriptionReconciliation()
+        : null;
+    const ownerIds = new Set([found.phase.id, found.phase.featureId].filter((id) => Boolean(id)));
+    const staleParentRefs = descriptionFreshness?.diagnostics
+        .filter((entry) => entry.state === "stale" && ownerIds.has(entry.ownerId))
+        .map((entry) => entry.ownerRef) ?? [];
+    const freshnessNotice = staleParentRefs.length > 0
+        ? `\n⚠️ Parent description review required: ${staleParentRefs.join(", ")}. Run planner-description-freshness for the non-mutating reconciliation preview.`
+        : "";
+    const details = resumeRequired
+        ? { task: t, updated: true, updatedFields: receivedFields, resumeRequired, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) }
+        : { task: t, updated: true, updatedFields: receivedFields, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) };
+    return writeAndSummarize(st, `✅ Task updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.${freshnessNotice}${resumeNotice}`, details);
 });
 server.registerTool("planner-task-checklist-toggle", {
     description: "Tick/untick a task checklist item (a 'step') without rewriting the whole list. Accepts the item as C{n} (e.g. C2), the item id, or the title (case-insensitive, first match). Pass checked=true/false to set explicitly, or omit to toggle. Use this instead of writing DONE in step titles. Items are numbered C1/C2… per task.",
@@ -1523,18 +1957,55 @@ 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 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.",
+    description: "Return the harness-agnostic next-work chain: active task if present, otherwise the lowest-priority ready feature → phase → task, plus bounded typed claims. Only persisted resume-ready handoffs are actionable; Markdown prose and terminal archives are not authority. Does not start or block work.",
     inputSchema: {},
 }, async () => {
     const st = await requireStore();
-    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;
+    const [features, phases, project, resume, handoffs, archivedHandoffs] = await Promise.all([
+        st.loadFeatures(),
+        st.loadAllPhases(),
+        st.loadProject(),
+        st.loadResume(),
+        st.listHandoffs(),
+        st.listArchivedHandoffs(),
+    ]);
+    const result = recommendNextWork(features.features, phases, project.workDeviations, resume?.currentPhaseId, "", {
+        handoffs: handoffs.map((handoff) => ({
+            compositeRef: handoff.compositeRef,
+            firstLine: handoff.firstLine,
+            resumeReady: handoff.resumeReady,
+        })),
+        archivedHandoffs: archivedHandoffs.map(({ compositeRef, firstLine, reason }) => ({ compositeRef, firstLine, reason })),
+    });
+    const { selection } = result;
+    if (!selection.candidate)
+        return text(`No work recommendation: ${selection.reason}${result.claims.length ? `\nClaims:\n${result.claims.map((claim) => `- ${claim.kind} (${claim.source}): ${claim.ref || claim.title} — ${claim.reason}`).join("\n")}` : ""}`, {
+            kind: selection.kind,
+            reason: selection.reason,
+            activeTaskIds: selection.activeCandidates?.map((candidate) => candidate.task.id) ?? [],
+            activeTask: result.activeTask,
+            nextFeature: result.nextFeature,
+            nextPhase: result.nextPhase,
+            nextTask: result.nextTask,
+            claims: result.claims,
+            selection,
+        });
+    const { candidate } = selection;
     const ref = taskCompositeRef(candidate.task, candidate.phase, features.features);
-    return text(`Recommended (${result.kind}): ${ref} — ${candidate.task.title}\n${result.reason}${result.deviation ? `\nDeviation: ${result.deviation.id}; resume target ${result.deviation.resumeTaskId}.` : ""}`, {
-        kind: result.kind, taskId: candidate.task.id, phaseId: candidate.phase.id, featureId: candidate.feature?.id, deviation: result.deviation,
+    const activeRef = result.activeTask ? `Active task: ${result.activeTask.id} — ${result.activeTask.title}\n` : "";
+    const claimsText = result.claims.length ? `\nClaims:\n${result.claims.map((claim) => `- ${claim.kind} (${claim.source}): ${claim.ref || claim.title} — ${claim.reason}`).join("\n")}` : "";
+    return text(`${activeRef}Next work (${selection.kind}): ${ref} — ${candidate.task.title}\n${selection.reason}${selection.deviation ? `\nDeviation: ${selection.deviation.id}; resume target ${selection.deviation.resumeTaskId}.` : ""}${claimsText}`, {
+        kind: selection.kind,
+        taskId: candidate.task.id,
+        phaseId: candidate.phase.id,
+        featureId: candidate.feature?.id,
+        deviation: selection.deviation,
+        activeTask: result.activeTask,
+        nextFeature: result.nextFeature,
+        nextPhase: result.nextPhase,
+        nextTask: result.nextTask,
+        claims: result.claims,
+        selection,
     });
 });
 server.registerTool("planner-task-deviation", {
@@ -1638,6 +2109,9 @@ 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.`);
     }
+    if (source.task.status === "in-progress" && source.task.activeOwnerSession && source.task.activeOwnerSession !== plannerSessionId) {
+        return text(`Task switch denied: source task is owned by another session.`);
+    }
     const targetFeature = target.phase.featureId ? features.find((feature) => feature.id === target.phase.featureId) : undefined;
     const linkedRequirements = [
         ...(await st.linkedRequirementsForPhase(target.phase.id)),
@@ -1656,7 +2130,8 @@ server.registerTool("planner-task-switch", {
         requirementIds: linkedRequirementIds,
     };
     const contextEligibility = contextReadEligibilityForSession(contextInput);
-    const requirementsReady = hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
+    const requirementEligibility = requirementReadEligibilityForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
+    const requirementsReady = requirementEligibility.eligible;
     const projectGuidelinesReadState = projectGuidelinesReadStateForSession(project, plannerSessionId);
     const projectGuidelinesReady = projectGuidelinesReadState === "valid" || projectGuidelinesReadState === "not-required";
     const targetTaskRef = taskCompositeRef(target.task, target.phase, features);
@@ -1671,7 +2146,7 @@ server.registerTool("planner-task-switch", {
         return text(`Task switch denied: context reads required. ${contextEligibility.reason}`, { ...contextEligibility, nextActions });
     }
     if (!requirementsReady) {
-        return text("Task switch denied: read the requirements linked to the target phase and feature before switching.", { requirementIds: linkedRequirementIds, nextActions: ["planner-requirement-list", `Retry planner-task-switch to ${targetTaskRef}`] });
+        return text(`Task switch denied: ${requirementEligibility.reason}`, { requirementIds: linkedRequirementIds, requirementEligibility, nextActions: [`planner-requirement-list with phaseRef=${targetPhaseRef}`, `Retry planner-task-switch to ${targetTaskRef}`] });
     }
     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 });
@@ -1685,7 +2160,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, focus?.currentPhaseId);
+    const selection = recommendNextTask(features, phases, project.workDeviations, focus?.currentPhaseId, plannerSessionId);
     const record = {
         id: crypto.randomUUID(), recommendedTaskId: selection.candidate?.task.id ?? source.task.id,
         temporaryTaskId: target.task.id, resumeTaskId: source.task.id, reason, snapshot,
@@ -1696,74 +2171,77 @@ server.registerTool("planner-task-switch", {
     const sourceWasActive = source.task.status === "in-progress";
     let sourceCheckpointed = false;
     let targetStarted = false;
-    try {
-        if (sourceWasActive) {
-            await st.pauseTask(source.phase.id, source.task.id, snapshot);
-        }
-        else {
-            await st.updatePhase(source.phase.id, (phase) => {
-                const task = phase.tasks.find((entry) => entry.id === source.task.id);
-                if (!task)
-                    throw new Error(`Checkpointed source task disappeared: ${from_task}`);
-                task.pauseSnapshot = snapshot;
-                task.pauseHistory = [...task.pauseHistory, snapshot];
-                task.updatedAt = timestamp;
-                return phase;
-            });
-        }
-        sourceCheckpointed = true;
-        if (target.task.pauseSnapshot) {
-            await st.resumeTask(target.phase.id, target.task.id, timestamp);
-        }
-        else {
-            await st.updatePhase(target.phase.id, (phase) => {
-                const task = phase.tasks.find((entry) => entry.id === target.task.id);
-                if (!task)
-                    throw new Error(`Temporary task disappeared: ${to_task}`);
-                const previousStatus = task.status;
-                applyTaskLifecycleDates(task, "in-progress", timestamp);
-                task.statusLog = [...task.statusLog, {
-                        id: createChecklistItemId(task.id, task.statusLog.length + 1, `${previousStatus}-in-progress`),
-                        date: timestamp, fromStatus: previousStatus, toStatus: "in-progress",
-                        title: `${previousStatus} → in-progress`, description: `Temporary switch from ${source.task.title}.`,
-                    }];
-                task.updatedAt = timestamp;
-                phase.updatedAt = timestamp;
-                return phase;
-            });
-        }
-        targetStarted = true;
-        await st.addWorkDeviation(record);
-        if (target.task.pauseSnapshot) {
-            const resumedDeviation = project.workDeviations
-                .filter((deviation) => deviation.resumeTaskId === target.task.id
-                && (deviation.state === "resume-required" || deviation.state === "resolved"))
-                .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
-            if (resumedDeviation)
-                await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
-        }
-    }
-    catch (error) {
-        if (targetStarted) {
-            await st.updatePhase(target.phase.id, (phase) => {
-                phase.tasks = phase.tasks.map((task) => task.id === target.task.id ? target.task : task);
-                return phase;
-            }).catch(() => { });
-        }
-        if (sourceCheckpointed) {
-            if (sourceWasActive)
-                await st.resumeTask(source.phase.id, source.task.id, nowISO()).catch(() => { });
-            else
+    await st.runBatch(async () => {
+        try {
+            if (sourceWasActive) {
+                await st.pauseTask(source.phase.id, source.task.id, snapshot);
+            }
+            else {
                 await st.updatePhase(source.phase.id, (phase) => {
-                    phase.tasks = phase.tasks.map((task) => task.id === source.task.id ? source.task : task);
+                    const task = phase.tasks.find((entry) => entry.id === source.task.id);
+                    if (!task)
+                        throw new Error(`Checkpointed source task disappeared: ${from_task}`);
+                    task.pauseSnapshot = snapshot;
+                    task.pauseHistory = [...task.pauseHistory, snapshot];
+                    task.updatedAt = timestamp;
+                    return phase;
+                });
+            }
+            sourceCheckpointed = true;
+            if (target.task.pauseSnapshot) {
+                await st.resumeTask(target.phase.id, target.task.id, timestamp, plannerSessionId);
+            }
+            else {
+                await st.updatePhase(target.phase.id, (phase) => {
+                    const task = phase.tasks.find((entry) => entry.id === target.task.id);
+                    if (!task)
+                        throw new Error(`Temporary task disappeared: ${to_task}`);
+                    const previousStatus = task.status;
+                    applyTaskLifecycleDates(task, "in-progress", timestamp);
+                    task.activeOwnerSession = plannerSessionId;
+                    task.statusLog = [...task.statusLog, {
+                            id: createChecklistItemId(task.id, task.statusLog.length + 1, `${previousStatus}-in-progress`),
+                            date: timestamp, fromStatus: previousStatus, toStatus: "in-progress",
+                            title: `${previousStatus} → in-progress`, description: `Temporary switch from ${source.task.title}.`,
+                        }];
+                    task.updatedAt = timestamp;
+                    phase.updatedAt = timestamp;
+                    return phase;
+                });
+            }
+            targetStarted = true;
+            await st.addWorkDeviation(record);
+            if (target.task.pauseSnapshot) {
+                const resumedDeviation = project.workDeviations
+                    .filter((deviation) => deviation.resumeTaskId === target.task.id
+                    && (deviation.state === "resume-required" || deviation.state === "resolved"))
+                    .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0];
+                if (resumedDeviation)
+                    await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
+            }
+        }
+        catch (error) {
+            if (targetStarted) {
+                await st.updatePhase(target.phase.id, (phase) => {
+                    phase.tasks = phase.tasks.map((task) => task.id === target.task.id ? target.task : task);
                     return phase;
                 }).catch(() => { });
+            }
+            if (sourceCheckpointed) {
+                if (sourceWasActive)
+                    await st.resumeTask(source.phase.id, source.task.id, nowISO(), (source.task.activeOwnerSession || plannerSessionId)).catch(() => { });
+                else
+                    await st.updatePhase(source.phase.id, (phase) => {
+                        phase.tasks = phase.tasks.map((task) => task.id === source.task.id ? source.task : task);
+                        return phase;
+                    }).catch(() => { });
+            }
+            throw error;
         }
-        throw error;
-    }
-    await st.syncTaskStatusRollup(source.phase.id);
-    if (target.phase.id !== source.phase.id)
-        await st.syncTaskStatusRollup(target.phase.id);
+        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)}`,
@@ -1772,6 +2250,26 @@ server.registerTool("planner-task-switch", {
         `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-reopen", {
+    description: "Atomically reopen a completed task. Requires confirmed=true; retains completion evidence and never pauses another task.",
+    inputSchema: { task: z.string().min(1), confirmed: z.boolean().optional().default(false) },
+}, async ({ task: ref, confirmed }, extra) => {
+    const st = await requireStore();
+    const features = (await st.loadFeatures()).features;
+    const found = findTaskByRef(await st.loadAllPhases(), features, ref);
+    if (!found)
+        return { ...text(`Task not found: ${ref}`, { reopened: false, errorCode: "TASK_NOT_FOUND" }), isError: true };
+    try {
+        const reopened = await st.reopenTask(found.phase.id, found.task.id, { confirmed, ownerSessionId: plannerSessionIdFor(extra) });
+        await st.syncTaskStatusRollup(found.phase.id);
+        await st.writeGenerated();
+        return text(`✅ Task reopened: ${taskCompositeRef(reopened, found.phase, features)} — ${reopened.title} (in-progress)`, { reopened: true, task: reopened });
+    }
+    catch (error) {
+        const details = error instanceof PlanStoreError ? error.details : undefined;
+        return { ...text(`Task reopen denied: ${error instanceof Error ? error.message : "unknown error"}`, { reopened: false, errorCode: details?.errorCode ?? "TASK_REOPEN_FAILED" }), isError: true };
+    }
+});
 server.registerTool("planner-task-start", {
     description: "Set a task to in-progress or resume checkpointed work. Call this tool before reading context so it can reuse valid sessionInfo attestations; if denied, perform only the missing/stale reads listed in nextActions, then retry. Reads may be performed in any order within the current session. If nextActions includes planner-project-guidelines-show, read that section and keep it in working memory while doing task work. Every denied start is an MCP isError result with started=false; 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) },
@@ -1784,149 +2282,153 @@ server.registerTool("planner-task-start", {
     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 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 === "done")
-        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}.`, `Retry planner-task-start ${taskRef}. If it then reports read prerequisites, perform only the missing or stale nextActions before retrying again.`], { taskId: found.task.id }));
-    const project = await st.loadProject();
-    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);
-    const requirementsReady = hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
-    const projectGuidelinesReadState = projectGuidelinesReadStateForSession(project, plannerSessionId);
-    const projectGuidelinesReady = projectGuidelinesReadState === "valid" || projectGuidelinesReadState === "not-required";
-    if (!projectGuidelinesReady)
-        return taskStartError(taskStartDenied("PROJECT_GUIDELINES_READ_REQUIRED", `Project Guidelines must be read before task work. Current state: ${projectGuidelinesReadState}.`, mcpContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, true, !requirementsReady, `Retry planner-task-start ${taskRef}`), { taskId: found.task.id }), { projectGuidelinesReadState, contextEligibility });
-    if (!contextEligibility.eligible)
-        return taskStartError(taskStartDenied("CONTEXT_READ_REQUIRED", `Required context reads are incomplete or stale. ${contextEligibility.reason}`, mcpContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, false, !requirementsReady, `Retry planner-task-start ${taskRef}`), { taskId: found.task.id }), { contextEligibility });
-    if (!requirementsReady) {
-        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 });
-    }
-    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 });
-    }
-    const [phases, focus] = await Promise.all([st.loadAllPhases(), st.loadResume()]);
-    const eligibility = checkExplicitTaskStart(features, phases, found.task.id, project.workDeviations);
-    if (!eligibility.eligible)
-        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 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) {
-        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 });
-    }
-    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 [phaseWithRequirements, featureRequirements] = await Promise.all([
-        st.loadPhaseWithRequirements(found.phase.id),
-        parentFeature ? st.linkedRequirementsForFeature(parentFeature.id) : Promise.resolve([]),
-    ]);
-    const phaseContext = buildPhaseContextBlock(phaseWithRequirements, parentFeature, phaseWithRequirements.linkedRequirements ?? [], featureRequirements);
-    // A pending handoff is context, not a lock: task start RETAINS it. It is
-    // archived only when the phase completes (auto) or the user explicitly
-    // clears it.
-    const advisory = selection.candidate && selection.candidate.task.id !== found.task.id
-        ? 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.pauseSnapshot) {
-        updatedTask = await st.resumeTask(found.phase.id, found.task.id, timestamp);
-    }
-    else {
-        await st.updatePhase(found.phase.id, (phase) => {
-            const task = phase.tasks.find((entry) => entry.id === found.task.id);
-            if (!task)
+    return st.runBatch(async () => {
+        const features = (await st.loadFeatures()).features;
+        const found = findTaskByRef(await st.loadAllPhases(), features, ref);
+        if (!found)
+            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 === "done")
+            return taskStartError(taskStartDenied("TASK_DONE", `Task ${taskRef} is done and was not reopened.`, [`Use planner-task-reopen with task=${taskRef} and confirmed=true after explicit user confirmation.`, `Retry planner-task-start ${taskRef} only if reopening is not the intended operation.`], { taskId: found.task.id }));
+        const project = await st.loadProject();
+        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);
+        const requirementEligibility = requirementReadEligibilityForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
+        const requirementsReady = requirementEligibility.eligible;
+        const projectGuidelinesReadState = projectGuidelinesReadStateForSession(project, plannerSessionId);
+        const projectGuidelinesReady = projectGuidelinesReadState === "valid" || projectGuidelinesReadState === "not-required";
+        if (!projectGuidelinesReady)
+            return taskStartError(taskStartDenied("PROJECT_GUIDELINES_READ_REQUIRED", `Project Guidelines must be read before task work. Current state: ${projectGuidelinesReadState}.`, mcpContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, true, !requirementsReady, `Retry planner-task-start ${taskRef}`), { taskId: found.task.id }), { projectGuidelinesReadState, contextEligibility });
+        if (!contextEligibility.eligible)
+            return taskStartError(taskStartDenied("CONTEXT_READ_REQUIRED", `Required context reads are incomplete or stale. ${contextEligibility.reason}`, mcpContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, false, !requirementsReady, `Retry planner-task-start ${taskRef}`), { taskId: found.task.id }), { contextEligibility });
+        if (!requirementsReady) {
+            return taskStartError(taskStartDenied("REQUIREMENTS_READ_REQUIRED", `Linked requirements were not read; the task remains unchanged. ${requirementEligibility.reason}`, [`planner-requirement-list with phaseRef=${phaseRef}`, `Retry planner-task-start ${taskRef}`], { taskId: found.task.id, requirementIds: linkedRequirementIds }), { requirementEligibility });
+        }
+        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 });
+        }
+        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 });
+        }
+        const [phases, focus] = await Promise.all([st.loadAllPhases(), st.loadResume()]);
+        const eligibility = checkExplicitTaskStart(features, phases, found.task.id, project.workDeviations);
+        if (!eligibility.eligible)
+            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, plannerSessionId);
+        if (selection.kind === "conflict") {
+            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) {
+            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 });
+        }
+        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 [phaseWithRequirements, featureRequirements] = await Promise.all([
+            st.loadPhaseWithRequirements(found.phase.id),
+            parentFeature ? st.linkedRequirementsForFeature(parentFeature.id) : Promise.resolve([]),
+        ]);
+        const phaseContext = buildPhaseContextBlock(phaseWithRequirements, parentFeature, phaseWithRequirements.linkedRequirements ?? [], featureRequirements, found.task, project);
+        // A pending handoff is context, not a lock: task start RETAINS it. It is
+        // archived only when the phase completes (auto) or the user explicitly
+        // clears it.
+        const advisory = selection.candidate && selection.candidate.task.id !== found.task.id
+            ? 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.pauseSnapshot) {
+            updatedTask = await st.resumeTask(found.phase.id, found.task.id, timestamp, plannerSessionId);
+        }
+        else {
+            await st.updatePhase(found.phase.id, (phase) => {
+                const task = phase.tasks.find((entry) => entry.id === found.task.id);
+                if (!task)
+                    return phase;
+                const previousStatus = task.status;
+                applyTaskLifecycleDates(task, "in-progress", timestamp);
+                const entry = {
+                    id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${previousStatus}-in-progress`),
+                    date: timestamp,
+                    fromStatus: previousStatus,
+                    toStatus: "in-progress",
+                    title: `${previousStatus} → in-progress`,
+                    description: "",
+                };
+                task.activeOwnerSession = plannerSessionId;
+                task.statusLog = [...(task.statusLog ?? []), entry];
+                task.updatedAt = timestamp;
+                phase.updatedAt = timestamp;
+                updatedTask = task;
                 return phase;
-            const previousStatus = task.status;
-            applyTaskLifecycleDates(task, "in-progress", timestamp);
-            const entry = {
-                id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${previousStatus}-in-progress`),
-                date: timestamp,
-                fromStatus: previousStatus,
-                toStatus: "in-progress",
-                title: `${previousStatus} → in-progress`,
-                description: "",
-            };
-            task.statusLog = [...(task.statusLog ?? []), entry];
-            task.updatedAt = timestamp;
-            phase.updatedAt = timestamp;
-            updatedTask = task;
-            return phase;
+            });
+        }
+        await st.syncTaskStatusRollup(found.phase.id);
+        const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === found.task.id && deviation.state === "approved");
+        if (approvedDeviation)
+            await st.setWorkDeviationState(approvedDeviation.id, "active", timestamp);
+        const resumedDeviation = 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];
+        if (resumedDeviation)
+            await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
+        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 } : {}),
         });
-    }
-    await st.syncTaskStatusRollup(found.phase.id);
-    const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === found.task.id && deviation.state === "approved");
-    if (approvedDeviation)
-        await st.setWorkDeviationState(approvedDeviation.id, "active", timestamp);
-    const resumedDeviation = 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];
-    if (resumedDeviation)
-        await st.setWorkDeviationState(resumedDeviation.id, "resumed", timestamp);
-    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", {
@@ -2014,11 +2516,11 @@ server.registerTool("planner-handoff-list", {
         return text("No phase handoffs set.", { count: 0, total: 0, page: 1, pageSize, totalPages: 1, handoffs: [] });
     const result = boundedPage(list, page, pageSize);
     const { items, ...pageInfo } = result;
-    const lines = items.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt}; ${e.contentLength} chars)`);
+    const lines = items.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt}; ${e.contentLength} chars; ${e.resumeReady ? "resume-ready" : "verification required"})`);
     return text(`Phase handoffs — page ${pageInfo.page}/${pageInfo.totalPages} (${pageInfo.total} total):\n${lines.join("\n")}`, { count: items.length, ...pageInfo, handoffs: items });
 });
 server.registerTool("planner-handoff-show", {
-    description: "Read the entity-scoped handoff of a phase. phaseRef is required; never infer a phase from in-progress status or stale context.",
+    description: "Read the active entity-scoped handoff of a phase, or its latest terminal archive, together with a bounded priority-ordered phase work map. Reread the canonical phase and relevant sibling tasks before proposing work so capability ownership is not duplicated. phaseRef is required; never infer a phase from in-progress status or stale context.",
     inputSchema: { phaseRef: z.string().min(1).describe("Exact phase ref: P00x | P00x(F00x) | UUID | title. Ask the user when ambiguous.") },
 }, async ({ phaseRef }) => {
     const st = await requireStore();
@@ -2027,26 +2529,138 @@ server.registerTool("planner-handoff-show", {
         return text(`❌ ${r.error}`);
     const phase = await st.loadPhase(r.phase.id);
     const bounded = boundedHandoffForTransport(phase.handoff);
-    if (!bounded.content.trim())
-        return text(`No handoff set on ${r.compositeRef}.`, { phaseRef: r.compositeRef, phaseId: r.phase.id, content: "", empty: true, handoffAudit: phase.handoffAudit });
-    return text(`Handoff for ${r.compositeRef}:\n\n${bounded.content}`, { phaseRef: r.compositeRef, phaseId: r.phase.id, ...bounded, handoffAudit: phase.handoffAudit });
+    if (!bounded.content.trim()) {
+        const archived = (await st.listArchivedHandoffs()).find((entry) => entry.phaseId === phase.id
+            && new Set(["phase-done", "phase-rejected", "phase-canceled"]).has(entry.reason));
+        if (archived) {
+            const archivedContent = boundedHandoffForTransport(archived.content);
+            const supportingDocuments = phase.handoffAudit?.supportingDocuments ?? [];
+            const documentLines = supportingDocuments.map((document) => `- ${document.path} — ${document.description}`);
+            return text([
+                `Archived terminal-phase handoff for ${r.compositeRef} (${archived.reason}; archived ${archived.archivedAt})`,
+                ...(documentLines.length ? ["Supporting documents:", ...documentLines] : []),
+                "",
+                archivedContent.content,
+            ].join("\n"), {
+                phaseRef: r.compositeRef,
+                phaseId: phase.id,
+                active: false,
+                archived: true,
+                archiveReason: archived.reason,
+                archivedAt: archived.archivedAt,
+                archiveFile: archived.file,
+                ...archivedContent,
+                supportingDocuments,
+                empty: false,
+                resumeReady: false,
+                handoffAudit: phase.handoffAudit,
+            });
+        }
+        return text(`No handoff set on ${r.compositeRef}.`, { phaseRef: r.compositeRef, phaseId: r.phase.id, content: "", empty: true, resumeReady: false, handoffAudit: phase.handoffAudit });
+    }
+    const feature = (await st.loadFeatures()).features.find((entry) => entry.id === phase.featureId);
+    const phaseWorkMap = buildPhaseWorkMap(phase, feature?.number);
+    const contentHash = handoffContentHash(phase.handoff);
+    const persistenceVerified = Boolean(phase.handoffAudit
+        && phase.handoffAudit.contentHash === contentHash
+        && phase.handoffAudit.contentLength === phase.handoff.length);
+    const resumeReady = persistenceVerified && Boolean(phase.handoffAudit?.resumeReadyAt);
+    const status = resumeReady
+        ? "Resume-ready: persisted compact capsule read-back completed."
+        : "NOT resume-ready: after reading this persisted capsule, call planner-handoff-verify with its contentHash. The planner derives legacy evidence from persisted state; rewrite only if the capsule itself omits resume-critical context.";
+    return text(`Handoff for ${r.compositeRef}\n${status}\nContent hash: ${contentHash}\n\n${phaseWorkMap.content}\n\nBefore proposing new work, reread the canonical phase and relevant sibling task full view; do not duplicate an already-owned capability.\n\n${bounded.content}`, {
+        phaseRef: r.compositeRef,
+        phaseId: r.phase.id,
+        phaseWorkMap,
+        ...bounded,
+        contentHash,
+        persistenceVerified,
+        resumeReady,
+        verificationRequired: !resumeReady,
+        handoffAudit: phase.handoffAudit,
+    });
+});
+server.registerTool("planner-handoff-verify", {
+    description: "Finalize one persisted handoff as resume-ready after planner-handoff-show confirms the persisted compact resume capsule. Legacy sourceReviews and omissionsFound evidence remains accepted but is optional; the planner derives omitted evidence from persisted state.",
+    inputSchema: {
+        phaseRef: z.string().min(1),
+        expectedContentHash: z.string().regex(/^[a-f0-9]{64}$/),
+        sourceReviews: z.array(z.object({
+            source: z.enum(["conversation", "planner-entities", "working-tree", "verification-runtime", "peer-agent-output"]),
+            detail: z.string().min(12),
+        })).optional().describe("Optional legacy evidence; omitted for compact handoffs."),
+        omissionsFound: z.array(z.string().min(1)).optional().describe("Optional read-back gaps; omit when the persisted capsule is complete."),
+    },
+}, async ({ phaseRef, expectedContentHash, sourceReviews, omissionsFound }) => {
+    const st = await requireStore();
+    const r = await resolvePhaseForHandoff(st, phaseRef);
+    if (!r.ok)
+        return text(`❌ ${r.error}`, { resumeReady: false });
+    try {
+        const result = await st.verifyPhaseHandoffReadBack(r.phase.id, {
+            expectedContentHash,
+            ...(sourceReviews ? { sourceReviews } : {}),
+            ...(omissionsFound ? { omissionsFound } : {}),
+        });
+        await st.writeGenerated();
+        return text(`✅ Handoff on ${r.compositeRef} is resume-ready after persisted read-back and source reconciliation.`, {
+            phaseRef: r.compositeRef,
+            ...result,
+            resumeReady: true,
+            verificationRequired: false,
+        });
+    }
+    catch (error) {
+        if (error instanceof HandoffContractError)
+            return handoffContractFailure(error);
+        const message = error instanceof Error ? error.message : String(error);
+        return text(`❌ Handoff read-back verification denied: ${message}`, { resumeReady: false, error: message });
+    }
 });
 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 (_args, extra) => {
+    description: "List declarative product Requirements: user, business, or system outcomes. Requirements never contain coding standards, best practices, formatting, verification process, or other Project Guidelines. Pass phaseRef to deliver and attest only the Requirements linked to that phase or its owning feature; an unscoped inventory does not satisfy task-start read gates.",
+    inputSchema: {
+        phaseRef: z.string().min(1).optional().describe("Optional target phase ref. When supplied, return full target-relevant requirements and record only those delivered requirements as read."),
+    },
+}, async ({ phaseRef }, extra) => {
     const plannerSessionId = plannerSessionIdFor(extra);
     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 });
+    if (!phaseRef?.trim()) {
+        return text(requirements.requirements.map((req) => `- ${req.id} — ${req.title}`).join("\n") || "No requirements", {
+            requirements,
+            attestedRequirementIds: [],
+            readScope: "inventory",
+        });
+    }
+    const features = (await st.loadFeatures()).features;
+    const phase = findPhaseByRef(await st.loadAllPhases(), features, phaseRef.trim());
+    if (!phase)
+        return { ...text(`Phase not found: ${phaseRef}`, { attestedRequirementIds: [] }), isError: true };
+    const delivered = [
+        ...(await st.linkedRequirementsForPhase(phase.id)),
+        ...(phase.featureId ? await st.linkedRequirementsForFeature(phase.featureId) : []),
+    ].filter((requirement, index, all) => all.findIndex((candidate) => candidate.id === requirement.id) === index);
+    delivered.forEach((requirement) => markRequirementReadForSessionId(plannerSessionId, requirement.id));
+    const targetRef = formatPhaseRef(phase.number, featureNumberOfPhase(phase, features));
+    const body = delivered.map((requirement) => [
+        `- ${requirement.id} — ${requirement.title}`,
+        `  Description: ${requirement.description || "None"}`,
+        `  Linked phases: ${requirement.linkedPhaseIds.join(", ") || "None"}`,
+        `  Macro tasks: ${requirement.macroTasks.map((item) => `${item.title} (${item.status})`).join("; ") || "None"}`,
+    ].join("\n")).join("\n");
+    return text(body || `No requirements linked to ${targetRef}`, {
+        requirements: { ...requirements, requirements: delivered },
+        attestedRequirementIds: delivered.map((requirement) => requirement.id),
+        readScope: "target",
+        target: { phaseId: phase.id, phaseRef: targetRef, featureId: phase.featureId },
+    });
 });
 server.registerTool("planner-requirement-create", {
-    description: "Create a top-level requirement with optional nested macro tasks. Requirement and macro-task IDs/timestamps are assigned by the planner.",
+    description: "Create a declarative product Requirement describing a user, business, or system outcome, with optional nested macro tasks. Never store coding standards, best practices, formatting, verification process, or other Project Guidelines here; use planner-project-guidelines-update instead. Requirements have no lifecycle status. Requirement and macro-task IDs/timestamps are assigned by the planner.",
     inputSchema: {
         title: z.string().min(1),
         description: z.string().optional(),
-        status: z.enum(STATUS_VALUES).optional(),
         linkedPhaseIds: z.array(z.string().min(1)),
         macroTasks: z.array(z.object({
             title: z.string().min(1),
@@ -2054,7 +2668,7 @@ server.registerTool("planner-requirement-create", {
             status: z.enum(STATUS_VALUES).optional(),
         })).optional(),
     },
-}, async ({ title, description, status, linkedPhaseIds, macroTasks }) => {
+}, async ({ title, description, linkedPhaseIds, macroTasks }) => {
     const st = await requireStore();
     const links = await resolveRequirementPhaseRefs(st, linkedPhaseIds);
     if (!links.ok)
@@ -2076,25 +2690,22 @@ server.registerTool("planner-requirement-create", {
         id: createRequirementId(),
         title: title.trim(),
         description: description?.trim() ?? "",
-        status: status ?? "planned",
         macroTasks: normalizedMacroTasks,
         linkedPhaseIds: links.linkedPhaseIds,
         createdAt: now,
         updatedAt: now,
         sessionInfo: [],
     };
-    const requirements = await st.loadRequirements();
-    await st.saveRequirements({ requirements: [...requirements.requirements, requirement] });
+    await st.updateRequirements((document) => ({ requirements: [...document.requirements, requirement] }));
     await st.writeGenerated();
     return writeAndSummarize(st, `Requirement created: ${requirement.id}.`, { requirement, created: true });
 });
 server.registerTool("planner-requirement-update", {
-    description: "Update a requirement’s human-owned title, description, status, linked phases, or complete ordered macro-task list. Existing macro-task IDs and timestamps remain planner-managed; omit an ID to add a task.",
+    description: "Update a Requirement’s product outcome, linked phases, or complete ordered macro-task list. Never store coding standards, best practices, formatting, verification process, or other Project Guidelines here; use planner-project-guidelines-update instead. Requirements have no lifecycle status. Existing macro-task IDs and timestamps remain planner-managed; omit an ID to add a task.",
     inputSchema: {
         requirementId: z.string().min(1),
         title: z.string().min(1).optional(),
         description: z.string().optional(),
-        status: z.enum(STATUS_VALUES).optional(),
         linkedPhaseIds: z.array(z.string().min(1)).optional(),
         macroTasks: z.array(z.object({
             id: z.string().min(1).optional(),
@@ -2103,41 +2714,45 @@ server.registerTool("planner-requirement-update", {
             status: z.enum(STATUS_VALUES),
         })).optional(),
     },
-}, async ({ requirementId, title, description, status, linkedPhaseIds, macroTasks }) => {
+}, async ({ requirementId, title, description, linkedPhaseIds, macroTasks }) => {
     const st = await requireStore();
     const requirements = await st.loadRequirements();
     const current = requirements.requirements.find((requirement) => requirement.id === requirementId);
     if (!current)
         return text(`❌ Requirement not found: ${requirementId}`, { updated: false, errorCode: "NOT_FOUND" });
+    if (title === undefined && description === undefined && linkedPhaseIds === undefined && macroTasks === undefined) {
+        return mutationNoFieldsFailure({
+            entity: "requirement",
+            ref: requirementId,
+            operation: "update",
+            mutableFields: ["title", "description", "linkedPhaseIds", "macroTasks"],
+            retryCommand: `planner-requirement-update ${requirementId}`,
+        });
+    }
     const links = linkedPhaseIds === undefined ? { ok: true, linkedPhaseIds: current.linkedPhaseIds } : await resolveRequirementPhaseRefs(st, linkedPhaseIds);
     if (!links.ok)
         return text(`❌ ${links.error}`, { updated: false, errorCode: "REQUIREMENT_PHASE_LINK_INVALID" });
     const now = nowISO();
-    let normalizedMacroTasks = current.macroTasks;
-    if (macroTasks !== undefined) {
-        try {
-            normalizedMacroTasks = reconcileRequirementMacroTasks(current.macroTasks, macroTasks.map((task) => ({
-                ...(task.id !== undefined ? { id: task.id } : {}),
-                title: task.title,
-                ...(task.description !== undefined ? { description: task.description } : {}),
-                status: task.status,
-            })), now);
-        }
-        catch (error) {
-            const message = error instanceof RequirementMacroTaskError ? error.message : "Invalid macro tasks.";
-            return text(`❌ ${message}`, { updated: false, errorCode: "REQUIREMENT_MACRO_TASK_INVALID" });
-        }
+    let next;
+    try {
+        next = await st.updateRequirement(current.id, (canonical) => ({
+            ...canonical,
+            ...(title !== undefined ? { title: title.trim() } : {}),
+            ...(description !== undefined ? { description: description.trim() } : {}),
+            ...(linkedPhaseIds !== undefined ? { linkedPhaseIds: links.linkedPhaseIds } : {}),
+            ...(macroTasks !== undefined ? { macroTasks: reconcileRequirementMacroTasks(canonical.macroTasks, macroTasks.map((task) => ({
+                    ...(task.id !== undefined ? { id: task.id } : {}),
+                    title: task.title,
+                    ...(task.description !== undefined ? { description: task.description } : {}),
+                    status: task.status,
+                })), now) } : {}),
+            updatedAt: now,
+        }));
+    }
+    catch (error) {
+        const message = error instanceof RequirementMacroTaskError ? error.message : "Invalid macro tasks.";
+        return text(`❌ ${message}`, { updated: false, errorCode: "REQUIREMENT_MACRO_TASK_INVALID" });
     }
-    const next = {
-        ...current,
-        ...(title !== undefined ? { title: title.trim() } : {}),
-        ...(description !== undefined ? { description: description.trim() } : {}),
-        ...(status !== undefined ? { status } : {}),
-        linkedPhaseIds: links.linkedPhaseIds,
-        macroTasks: normalizedMacroTasks,
-        updatedAt: now,
-    };
-    await st.saveRequirements({ requirements: requirements.requirements.map((requirement) => requirement.id === current.id ? next : requirement) });
     await st.writeGenerated();
     return writeAndSummarize(st, `Requirement updated: ${next.id}.`, { requirement: next, updated: true });
 });
@@ -2146,13 +2761,16 @@ server.registerTool("planner-requirement-delete", {
     inputSchema: { requirementId: z.string().min(1) },
 }, async ({ requirementId }) => {
     const st = await requireStore();
-    const requirements = await st.loadRequirements();
-    const next = requirements.requirements.filter((requirement) => requirement.id !== requirementId);
-    if (next.length === requirements.requirements.length)
+    let deleted = false;
+    await st.updateRequirements((document) => {
+        const requirements = document.requirements.filter((requirement) => requirement.id !== requirementId);
+        deleted = requirements.length !== document.requirements.length;
+        return deleted ? { requirements } : document;
+    });
+    if (!deleted)
         return text(`❌ Requirement not found: ${requirementId}`, { deleted: false, errorCode: "NOT_FOUND" });
-    await st.saveRequirements({ requirements: next });
     await st.writeGenerated();
-    return writeAndSummarize(st, `Requirement deleted: ${requirementId}.`, { deleted: requirementId });
+    return writeAndSummarize(st, `Requirement deleted: ${requirementId}.`, { deleted: true, requirementId });
 });
 function ideaPromotionTarget(st, type, ref) {
     return Promise.all([st.loadFeatures(), st.loadAllPhases()]).then(([featuresDoc, phases]) => {
@@ -2201,8 +2819,15 @@ server.registerTool("planner-idea-update", {
     const current = findIdeaByRef((await st.loadIdeas()).ideas, ref);
     if (!current)
         return text(`Idea not found: ${ref}`, { errorCode: "NOT_FOUND", updated: false });
-    if (title === undefined && description === undefined)
-        return text("No mutable idea fields were received.", { errorCode: "NO_MUTABLE_FIELDS_RECEIVED", updated: false });
+    if (title === undefined && description === undefined) {
+        return mutationNoFieldsFailure({
+            entity: "idea",
+            ref,
+            operation: "update",
+            mutableFields: ["title", "description"],
+            retryCommand: `planner-idea-update ${ref}`,
+        });
+    }
     const idea = await st.updateIdea(current.id, { ...(title !== undefined ? { title } : {}), ...(description !== undefined ? { description } : {}) });
     await st.writeGenerated();
     return text(`Idea updated: ${formatIdeaRef(idea.number)} — ${idea.title}`, { idea, updated: true });
@@ -2262,10 +2887,11 @@ server.registerTool("planner-idea-promotion-finalize", {
     return text(`Idea promoted: ${formatIdeaRef(promoted.number)} → ${promoted.promotion.targetRef}`, { idea: promoted, promoted: true, targetRef: promoted.promotion.targetRef });
 });
 server.registerTool("planner-handoff-write", {
-    description: "Reconcile one active handoff with durable context synchronization and a mandatory versioned completeness audit. Run planner-handoff-prepare first; link extended detail from committed .planner/docs/ Markdown.",
+    description: "Persist a compact reconciled handoff candidate with durable context synchronization. The result always has resumeReady=false until a separate planner-handoff-show read-back and planner-handoff-verify succeeds. Run planner-handoff-prepare first; provide only resume-critical context and link optional extended detail from .planner/docs/ Markdown.",
     inputSchema: {
         phaseRef: z.string().min(1).describe("Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title."),
         title: z.string().min(3).optional().describe("Meaningful handoff title summarizing the work."),
+        reason: z.string().min(1).optional().describe("Why work is stopping and why a cold agent needs this handoff. Required for confirmed writes; rendered by the planner, not in Markdown."),
         confirmed: z.boolean().describe("Set true only after the user explicitly confirms the proposed feature+phase target."),
         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."),
@@ -2277,7 +2903,16 @@ server.registerTool("planner-handoff-write", {
                 status: z.enum(["captured", "not-applicable"]),
                 detail: z.string().min(1),
             })),
-        }).optional().describe("Mandatory for confirmed writes; every category from planner-handoff-prepare must be present."),
+        }).optional().describe("Optional legacy completeness evidence. Compact handoffs omit this duplicate prose."),
+        coldStartInventory: z.object({
+            version: z.literal(HANDOFF_COLD_START_INVENTORY_VERSION),
+            sourceReviews: z.array(z.object({ source: z.string().min(1), detail: z.string().min(1) })),
+            entries: z.array(z.object({
+                category: z.string().min(1).describe(`One required cold-start category id: ${HANDOFF_COLD_START_INVENTORY_CATEGORIES.map((entry) => entry.id).join(", ")}`),
+                items: z.array(z.string().min(1)),
+                notApplicableReason: z.string().min(1).optional().describe("Optional explanation only; every category still requires a concrete item, using an explicit verified-negative statement when nothing exists."),
+            })),
+        }).optional().describe("Optional legacy cold-start evidence. Compact handoffs omit this duplicate prose."),
         supportingDocuments: z.array(z.object({
             path: z.string().min(1).describe("Committed Markdown path under .planner/docs/."),
             description: z.string().min(1).describe("What the document contains and why the next agent needs it."),
@@ -2299,7 +2934,7 @@ server.registerTool("planner-handoff-write", {
         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, expectedHandoffUpdatedAt, reconciledExistingHandoff, completenessAudit, supportingDocuments, taskUpdates, phaseUpdate, phaseNoUpdateReason, featureUpdate, featureNoUpdateReason }) => {
+}, async ({ phaseRef, title, reason, confirmed, content, expectedHandoffUpdatedAt, reconciledExistingHandoff, completenessAudit, coldStartInventory, supportingDocuments, taskUpdates, phaseUpdate, phaseNoUpdateReason, featureUpdate, featureNoUpdateReason }) => {
     const st = await requireStore();
     let body = content.trim();
     const firstLine = body.split(/\r?\n/).find((line) => line.trim().length > 0) ?? "";
@@ -2323,7 +2958,9 @@ server.registerTool("planner-handoff-write", {
     if (!confirmed)
         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.");
+        return handoffPreflightFailure("HANDOFF_PREFLIGHT_REQUIRED", "Run planner-handoff-prepare first and pass expectedHandoffUpdatedAt.");
+    if (!reason?.trim())
+        return handoffPreflightFailure("HANDOFF_REASON_REQUIRED", "Handoff reason is required before persistence. Created at and Updated at are generated by the planner; do not add them to Markdown.", { requiredInputs: ["title", "reason"], generatedMetadata: ["Created at", "Updated at"] });
     const phases = await st.loadAllPhases();
     const features = (await st.loadFeatures()).features;
     const resolvedTaskUpdates = [];
@@ -2342,10 +2979,12 @@ server.registerTool("planner-handoff-write", {
     }
     try {
         const result = await st.refreshPhaseHandoff(r.phase.id, {
+            reason: reason.trim(),
             content: body,
             expectedHandoffUpdatedAt,
             reconciledExistingHandoff: reconciledExistingHandoff === true,
             ...(completenessAudit ? { completenessAudit: completenessAudit } : {}),
+            ...(coldStartInventory ? { coldStartInventory: coldStartInventory } : {}),
             ...(supportingDocuments ? { supportingDocuments } : {}),
             contextSync: {
                 taskUpdates: resolvedTaskUpdates,
@@ -2360,12 +2999,19 @@ server.registerTool("planner-handoff-write", {
             },
         });
         await st.writeGenerated();
-        return text(`✅ Reconciled handoff and durable context on ${r.compositeRef}; updated ${result.updatedTaskIds.length} task(s).`, {
+        return text(`⚠️ Handoff candidate persisted on ${r.compositeRef}, but it is NOT resume-ready yet. Required next action: call planner-handoff-show ${r.compositeRef}, read the persisted compact capsule, then call planner-handoff-verify with the returned contentHash. Rewrite only if resume-critical context is missing.`, {
             phaseRef: r.compositeRef,
             phaseId: r.phase.id,
             updatedTaskIds: result.updatedTaskIds,
             handoffUpdatedAt: result.handoffUpdatedAt,
             handoffAudit: result.handoffAudit,
+            persisted: true,
+            resumeReady: false,
+            verificationRequired: true,
+            nextActions: [
+                `Call planner-handoff-show ${r.compositeRef} and read the entire persisted body.`,
+                "Call planner-handoff-verify with the shown contentHash; legacy sourceReviews and omissionsFound are optional because the planner derives omitted evidence from persisted state.",
+            ],
         });
     }
     catch (error) {
@@ -2376,7 +3022,7 @@ server.registerTool("planner-handoff-write", {
     }
 });
 server.registerTool("planner-handoff-prepare", {
-    description: "Identify or audit the exact handoff target. With a confirmed phaseRef, returns the current token, missing task evidence, mandatory completeness categories, and the 24,000-character inline budget.",
+    description: "Identify or prepare the exact handoff target. With a confirmed phaseRef, returns a compact resume scaffold, bounded priority-ordered phase work map, current token, missing task evidence, and inline budget. Reread the canonical phase and relevant sibling tasks before proposing work.",
     inputSchema: { phaseRef: z.string().min(1).optional() },
 }, async ({ phaseRef }) => {
     if (!phaseRef)
@@ -2391,20 +3037,32 @@ server.registerTool("planner-handoff-prepare", {
         return text(`❌ ${r.error}`);
     try {
         const audit = await st.preparePhaseHandoff(r.phase.id);
+        const { completenessCategories: _completenessCategories, coldStartSourceReviews: _coldStartSourceReviews, coldStartInventoryCategories: _coldStartInventoryCategories, ...compactAudit } = audit;
         const missing = audit.missingCompletionTasks.map((task) => `- T${String(task.number).padStart(3, "0")} — ${task.title}`).join("\n") || "- None";
         return text([
-            `Handoff preparation audit for ${r.compositeRef}`,
+            `Handoff preparation for ${r.compositeRef}`,
             `Base handoffUpdatedAt: ${audit.handoffUpdatedAt || "(empty)"}`,
+            "Required human inputs before drafting:",
+            ...audit.requiredHumanInputs.map((input) => `- ${input.id} — ${input.description}`),
+            "Planner-generated metadata (do not add these to Markdown): Created at, Updated at, Reason.",
+            "Use this exact scaffold before drafting; replace every angle-bracket placeholder and retain every heading:",
+            audit.draftTemplate,
+            "",
             "Done tasks missing durable completion/verification evidence:",
             missing,
             "",
-            `Required completeness audit v${audit.completenessVersion} — every category must be captured or marked not-applicable with a substantive reason:`,
-            ...audit.completenessCategories.map((entry) => `- ${entry.id} — ${entry.label}`),
-            `Maximum canonical inline content: ${audit.maxContentChars} characters. Link extended material from .planner/docs/.`,
+            "Compact handoff contract: include only the exact focus/resume point, current or partial state, constraints, blockers, decisions, verification, and ordered next actions needed by the next agent.",
+            "No Markdown heading is mandatory: concise free-form resume prose is accepted. Use headings only when they make the capsule clearer.",
+            "Completeness audit and cold-start evidence are planner-owned metadata; do not copy their categories or source reviews into Markdown.",
+            `Inline target: ${audit.targetContentChars} characters; absolute compatibility ceiling: ${audit.maxContentChars}. Extended detail is externalized automatically when needed.`,
             "",
             "Existing active handoff (reconcile all still-relevant content):",
             audit.handoff.trim() || "(none)",
-        ].join("\n"), { phaseRef: r.compositeRef, ...audit });
+        ].join("\n"), {
+            phaseRef: r.compositeRef,
+            ...compactAudit,
+            evidenceContract: "Planner-owned completeness and cold-start evidence is derived from persisted state; no category inventory is required from the agent.",
+        });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -2430,40 +3088,44 @@ server.registerTool("planner-web", {
 }, async ({ action }) => {
     if (action === "start") {
         if (webHandle) {
-            return text(`planner-web already running: ${webHandle.localUrl}${webHandle.lanUrl ? ` — LAN: ${webHandle.lanUrl}` : ""} (mode: ${webHandle.mode})`);
+            const web = { localUrl: webHandle.localUrl, lanUrl: webHandle.lanUrl, mode: webHandle.mode, bindHost: webHandle.bindHost };
+            return text(`planner-web already running: ${webHandle.localUrl}${webHandle.lanUrl ? ` — LAN: ${webHandle.lanUrl}` : ""} (mode: ${webHandle.mode})`, plannerWebMetadata(web));
         }
         const root = planRoot();
         const storeCheck = new PlanStore(root);
         if (!(await storeCheck.exists())) {
-            return text(`planner-web start: no .planner/ found at ${root}. Run planner-init first.`);
+            return text(`planner-web start: no .planner/ found at ${root}. Run planner-init first.`, { running: false, address: "", localUrl: "", lanUrl: "", host: "", port: 0, mode: "", errorCode: "PLANNER_NOT_INITIALIZED" });
         }
         try {
             // port: 0 → OS assigns a free port (no conflict with plan-server CLI / Pi).
             // host: 0.0.0.0 → bind LAN (reachable from other devices), like Pi /planner load.
             webHandle = await serve({ planRoot: root, host: "0.0.0.0", port: 0, quiet: true });
-            return text(`planner-web started: ${webHandle.localUrl}${webHandle.lanUrl ? ` — LAN: ${webHandle.lanUrl}` : ""} (mode: ${webHandle.mode})`);
+            const web = { localUrl: webHandle.localUrl, lanUrl: webHandle.lanUrl, mode: webHandle.mode, bindHost: webHandle.bindHost };
+            return text(`planner-web started: ${webHandle.localUrl}${webHandle.lanUrl ? ` — LAN: ${webHandle.lanUrl}` : ""} (mode: ${webHandle.mode})`, plannerWebMetadata(web));
         }
         catch (err) {
             webHandle = null;
-            return text(`planner-web start failed: ${err.message}`);
+            const web = { localUrl: "", error: err.message };
+            return text(`planner-web start failed: ${web.error}`, plannerWebMetadata(web));
         }
     }
     if (action === "stop") {
         if (!webHandle)
-            return text("planner-web not running.");
+            return text("planner-web not running.", { running: false, address: "", localUrl: "", lanUrl: "", host: "", port: 0, mode: "" });
         const stoppedUrl = webHandle.localUrl;
         await webHandle.close().catch(() => { });
         webHandle = null;
-        return text(`planner-web stopped (was ${stoppedUrl}).`);
+        return text(`planner-web stopped (was ${stoppedUrl}).`, { running: false, address: "", localUrl: "", lanUrl: "", host: "", port: 0, mode: "" });
     }
     // status
     if (webHandle) {
-        return text(`planner-web running: ${webHandle.localUrl}${webHandle.lanUrl ? ` — LAN: ${webHandle.lanUrl}` : ""} (mode: ${webHandle.mode}, bindHost: ${webHandle.bindHost})`);
+        const web = { localUrl: webHandle.localUrl, lanUrl: webHandle.lanUrl, mode: webHandle.mode, bindHost: webHandle.bindHost };
+        return text(`planner-web running: ${webHandle.localUrl}${webHandle.lanUrl ? ` — LAN: ${webHandle.lanUrl}` : ""} (mode: ${webHandle.mode}, bindHost: ${webHandle.bindHost})`, plannerWebMetadata(web));
     }
-    return text("planner-web not running. Use planner-web with action=start to start the dashboard.");
+    return text("planner-web not running. Use planner-web with action=start to start the dashboard.", { running: false, address: "", localUrl: "", lanUrl: "", host: "", port: 0, mode: "" });
 });
 server.registerTool("planner-load", {
-    description: "Load/refresh the planner on explicit user request (NOT automatic): starts the web dashboard on LAN and returns a consolidated recap (project state, active task, pending handoff, web URL). This is the MCP equivalent of Pi /planner load. Call it ONLY when the user runs /planner load or /planner recap (or asks to load the planner). Present the recap verbatim in that reply, including its final prominent Web UI line. A pending handoff is read-only context: NEVER call planner-handoff-show or planner-handoff-clear as part of load/recap. Archive it only when every phase task is done/canceled, when replacing it with a new handoff, or after an explicit user handoff-clear request. Do NOT start the planner/web or show the web URL unless the user explicitly asks (load/recap/web status).",
+    description: "Load/refresh the planner on explicit user request (NOT automatic): starts the web dashboard on LAN and returns a consolidated recap plus bounded canonical Accepted Decision agentContext (project, feature, phase, and task scopes). This is the MCP equivalent of Pi /planner load. Call it ONLY when the user runs /planner load or /planner recap (or asks to load the planner). Present the recap verbatim in that reply, including its final prominent Web UI line. A pending handoff is read-only context: NEVER call planner-handoff-show or planner-handoff-clear as part of load/recap. Archive it only when every phase task is done/canceled, when replacing it with a new handoff, or after an explicit user handoff-clear request. Do NOT start the planner/web or show the web URL unless the user explicitly asks (load/recap/web status).",
 }, async (extra) => {
     const st = store();
     if (!(await st.exists()))
@@ -2484,10 +3146,23 @@ server.registerTool("planner-load", {
     await st.syncGrillMeSkill();
     const web = await ensureWebStarted();
     const recap = await buildRecap(st, web, { harness: "mcp" });
+    const plan = await st.loadAll();
+    const acceptedDecisionContext = buildBoundedAcceptedDecisionContext([
+        { scope: "project", decisions: plan.project.acceptedDecisions },
+        ...plan.features.features.map((feature) => ({ scope: `feature ${formatFeatureRef(feature.number)}`, decisions: feature.acceptedDecisions })),
+        ...plan.phases.map((phase) => ({ scope: `phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}`, decisions: phase.acceptedDecisions })),
+        ...plan.phases.flatMap((phase) => phase.tasks.map((task) => ({
+            scope: `task ${taskCompositeRef(task, phase, plan.features.features)}`,
+            decisions: task.acceptedDecisions,
+        }))),
+    ]);
     const visibleRecap = preparation.changed ? `${preparation.legacyProjectContext.summary}\n\n${recap}` : recap;
     return {
         content: [{ type: "text", text: visibleRecap }],
         structuredContent: {
+            loaded: true,
+            recap: { text: visibleRecap },
+            webUi: plannerWebMetadata(web),
             preparation: preparation.legacyProjectContext,
             agentContext: {
                 kind: "planner-usage-skill",
@@ -2495,7 +3170,8 @@ server.registerTool("planner-load", {
                 status: plannerSkill.status,
                 customized: plannerSkill.customized,
                 message: plannerSkill.message,
-                instruction: "Read and retain this project-local planner usage skill. Do not quote it in the human-facing recap.",
+                instruction: "Read and retain this project-local planner usage skill and Accepted Decision context. Do not quote it or the Accepted Decision context in the human-facing recap.",
+                acceptedDecisions: acceptedDecisionContext,
             },
         },
     };