@agent-plan/mcp 0.2.25 → 0.2.27

package/dist/index.js

@@ -5,9 +5,9 @@ import * as z from "zod/v4";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { pathToFileURL } from "node:url";
-import { PlanStore, ExportService, withFeatureLock, needsMotivation, findPhaseByRef, findTaskByRef, buildRecap, addChecklistItem, removeChecklistItem, toggleChecklistItem, buildPhaseContextBlock, checkExplicitTaskStart, recommendNextTask, buildResumeRequiredProposal, packageVersionFromModule, resolvedPackageVersion, markFeatureReadForSessionId, markPhaseReadForSessionId, markTaskReadForSessionId, contextReadEligibilityForSession, hasValidSessionAttestation, hasReadRequirementsForSession, markRequirementReadForSessionId, startReadSession, invalidateReads, taskStartDenied, taskStartSucceeded } 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, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, validateResolvedTarget } from "@agent-plan/core/naming";
+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"];
 const PHASE_STATUS_VALUES = ["draft", "discovery", ...STATUS_VALUES];
 const fallbackPlannerSessionId = `mcp-process:${randomUUID()}`;
@@ -21,6 +21,38 @@ function plannerSessionIdFor(extra) {
 function text(textValue, structuredContent) {
     return structuredContent ? { content: [{ type: "text", text: textValue }], structuredContent } : { content: [{ type: "text", text: textValue }] };
 }
+function handoffContractFailure(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: `❌ Handoff refresh denied [${error.code}]: ${error.message}` }],
+        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 };
+    const suffix = "\n\n[Legacy handoff truncated for transport safety. Move extended detail to a linked file under .planner/docs/ and refresh the handoff.]";
+    return {
+        content: `${content.slice(0, MAX_HANDOFF_CONTENT_CHARS - suffix.length)}${suffix}`,
+        fullLength: content.length,
+        truncated: true,
+    };
+}
+function boundedPage(items, page, pageSize) {
+    const size = Math.min(25, Math.max(1, Math.trunc(pageSize)));
+    const totalPages = Math.max(1, Math.ceil(items.length / size));
+    const currentPage = Math.min(totalPages, Math.max(1, Math.trunc(page)));
+    return {
+        items: items.slice((currentPage - 1) * size, currentPage * size),
+        page: currentPage,
+        pageSize: size,
+        total: items.length,
+        totalPages,
+    };
+}
 function derivedStatusReadOnlyResult(entity, ref, attemptedStatus, effectiveStatus) {
     const childKind = entity === "feature" ? "phases" : "tasks";
     const retryAction = entity === "feature"
@@ -52,6 +84,32 @@ function derivedStatusReadOnlyResult(entity, ref, attemptedStatus, effectiveStat
         },
     };
 }
+function mutationNoFieldsFailure(input) {
+    const outcome = noMutableFieldsReceived(input);
+    return {
+        isError: true,
+        content: [{ type: "text", text: outcome.message }],
+        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"}`,
+        `Guideline additions: ${preview.guidelineAdditions.length} (${preview.skippedGuidelineDuplicates} duplicate(s) skipped)`,
+        `Accepted decision additions: ${preview.acceptedDecisionAdditions.length} (${preview.skippedDecisionDuplicates} duplicate(s) skipped)`,
+        `Legacy counts: globalRules=${preview.legacyCounts.globalRules}, workflowRules=${preview.legacyCounts.workflowRules}, decisions=${preview.legacyCounts.decisions}`,
+        `Fields cleared on apply: ${preview.fieldsClearedOnApply.join(", ") || "none"}`,
+    ].join("\n");
+}
 function taskStartError(outcome, structuredContent = {}) {
     return {
         isError: true,
@@ -66,16 +124,19 @@ function taskStartError(outcome, structuredContent = {}) {
         structuredContent: { ...outcome, ...structuredContent },
     };
 }
-function mcpContextReadActions(eligibility, refs, requirementReadRequired, retryAction) {
-    const actions = (eligibility.requiredReads ?? []).flatMap((read) => {
+function mcpContextReadActions(eligibility, refs, projectGuidelinesReadRequired, requirementReadRequired, retryAction) {
+    const actions = projectGuidelinesReadRequired ? ["planner-project-guidelines-show"] : [];
+    actions.push(...(eligibility.requiredReads ?? []).flatMap((read) => {
         if (read.kind === "task")
             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;
 }
@@ -103,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) {
@@ -172,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)
@@ -194,6 +305,21 @@ const server = new McpServer({
     name: "agent-plan-planner",
     version: MCP_PACKAGE.version,
 });
+async function resolveRequirementPhaseRefs(st, refs) {
+    if (!refs || refs.length === 0)
+        return { ok: false, error: "linkedPhaseIds must contain at least one phase reference." };
+    const [phases, features] = await Promise.all([st.loadAllPhases(), st.loadFeatures()]);
+    const linkedPhaseIds = [];
+    for (const rawRef of refs) {
+        const ref = rawRef.trim();
+        const phase = ref ? findPhaseByRef(phases, features.features, ref) : undefined;
+        if (!phase)
+            return { ok: false, error: `Linked phase not found: ${rawRef}` };
+        if (!linkedPhaseIds.includes(phase.id))
+            linkedPhaseIds.push(phase.id);
+    }
+    return { ok: true, linkedPhaseIds };
+}
 async function resolvePhaseForHandoff(st, ref) {
     const phases = await st.loadAllPhases();
     const features = (await st.loadFeatures()).features;
@@ -213,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.",
@@ -278,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);
@@ -294,8 +438,13 @@ server.registerTool("planner-show", {
     const summary = [
         `📋 ${project.name}`,
         `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:",
@@ -303,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, 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,
@@ -316,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 () => {
@@ -358,17 +526,18 @@ 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", {
     description: "Record/update project-level discovery fields. This is the MCP equivalent of grouped project discuss without Pi UI prompts.",
     inputSchema: {
+        description: z.string().optional(),
+        descriptionRef: z.string().optional().describe("Optional markdown reference under .planner/docs/ for the full project description."),
         goal: z.string().optional(),
         scope: z.array(z.string()).optional(),
         outOfScope: z.array(z.string()).optional(),
@@ -380,6 +549,32 @@ server.registerTool("planner-project-discuss", {
 }, async (params) => {
     const st = await requireStore();
     const project = await st.loadProject();
+    const mutableFields = ["description", "descriptionRef", "goal", "scope", "outOfScope", "technologies", "tools", "globalRules", "decisions"];
+    const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+    if (receivedFields.length === 0) {
+        return mutationNoFieldsFailure({
+            entity: "project",
+            ref: project.name,
+            operation: "discuss",
+            mutableFields,
+            retryCommand: "planner-project-discuss with a concise description summary and the intended metadata",
+            readBackCommand: "planner-show",
+            descriptionFallback: {
+                inputField: "description",
+                storedField: "project description",
+                descriptionRefField: "descriptionRef",
+            },
+        });
+    }
+    if (params.description !== undefined)
+        project.description = params.description.trim();
+    if (params.descriptionRef !== undefined) {
+        const descriptionRef = normalizeDescriptionRef(params.descriptionRef);
+        if (descriptionRef)
+            project.descriptionRef = descriptionRef;
+        else
+            delete project.descriptionRef;
+    }
     if (params.goal !== undefined)
         project.goal = params.goal.trim();
     if (params.scope !== undefined)
@@ -394,26 +589,102 @@ 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}`);
+    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.",
+}, async (extra) => {
+    const plannerSessionId = plannerSessionIdFor(extra);
+    const st = await requireStore();
+    const project = await st.loadProject();
+    if (project.projectGuidelines.content.trim()) {
+        await st.recordProjectGuidelinesRead({ sessionId: plannerSessionId });
+    }
+    const refreshed = await st.loadProject();
+    const content = refreshed.projectGuidelines.content.trim();
+    return text(content
+        ? ["## Project Guidelines", content].join("\n\n")
+        : "No project guidelines set.", { projectGuidelines: refreshed.projectGuidelines, readRecorded: Boolean(content) });
+});
+server.registerTool("planner-project-guidelines-update", {
+    description: "Replace the canonical Project Guidelines / Coding Standard text that agents must read on load and before starting or switching task work.",
+    inputSchema: {
+        content: z.string().describe("Full Project Guidelines markdown/text. Pass an empty string to clear the section."),
+    },
+}, async ({ content }) => {
+    const st = await requireStore();
+    const project = await st.loadProject();
+    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}.`
+        : "Project Guidelines cleared.", { updated: true, projectGuidelines: refreshed.projectGuidelines });
+});
+server.registerTool("planner-project-context-migrate", {
+    description: "Preview or explicitly apply the lossless migration of legacy project globalRules/workflowRules into Project Guidelines and legacy decisions into structured accepted decisions. Ordinary planner loads never run this migration.",
+    inputSchema: {
+        apply: z.boolean().default(false).describe("False previews without mutation. True explicitly applies the previewed migration and clears only the migrated legacy fields."),
+    },
+}, async ({ apply }) => {
+    const st = await requireStore();
+    const preview = await st.previewLegacyProjectContextMigration();
+    if (!apply) {
+        return text([`Project context migration preview (no changes applied).`, legacyContextMigrationSummary(preview), preview.hasLegacyContext ? "Retry with apply=true to confirm." : "No migration is needed."].join("\n"), { applied: false, preview });
+    }
+    const result = await st.migrateLegacyProjectContext();
+    return writeAndSummarize(st, [result.applied ? "Legacy project context migration applied and verified." : "No legacy project context required migration.", legacyContextMigrationSummary(result.preview)].join("\n"), { ...result });
 });
 server.registerTool("planner-feature-list", {
-    description: "List features (compact: F00x · shortId — name (status; N phases, M tasks)). Pass featureRef to filter. Use this to discover refs cheaply — do NOT read .planner/ files or planner-plan-get full=true to find entities.",
+    description: "List features (compact: F00x · shortId — name (status; priority N; N phases, M tasks)). Pass featureRef to filter. Use this to discover refs cheaply — do NOT read .planner/ files or planner-plan-get full=true to find entities.",
     inputSchema: { featureRef: z.string().optional().describe("Optional: filter to one feature (F00x/shortId/UUID/name).") },
 }, async ({ featureRef }) => {
     const st = await requireStore();
     const allFeatures = (await st.loadFeatures()).features;
     const features = featureRef ? allFeatures.filter((f) => f.id === findFeatureByRef(allFeatures, featureRef)?.id) : allFeatures;
     const phases = await st.loadAllPhases();
-    const lines = features.map((feature) => {
+    const items = features.map((feature) => {
         const featurePhases = phases.filter((phase) => phase.featureId === feature.id);
         const taskCount = featurePhases.reduce((total, phase) => total + phase.tasks.length, 0);
-        return `- ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} — ${feature.name} (${feature.status}; ${featurePhases.length} phases, ${taskCount} tasks)`;
+        return {
+            id: feature.id,
+            ref: formatFeatureRef(feature.number),
+            shortId: feature.shortId,
+            name: feature.name,
+            status: feature.status,
+            priority: feature.priority,
+            phaseCount: featurePhases.length,
+            taskCount,
+        };
     });
-    return text(lines.join("\n") || "No features");
+    const lines = items.map((feature) => `- ${feature.ref}${feature.shortId ? ` · ${feature.shortId}` : ""} — ${feature.name} (${feature.status}${feature.priority > 0 ? `; priority ${feature.priority}` : ""}; ${feature.phaseCount} phases, ${feature.taskCount} tasks)`);
+    return text(lines.join("\n") || "No features", { features: items });
 });
 server.registerTool("planner-phase-list", {
-    description: "List phases (compact: F00x/P00x · shortId — title (status; N tasks) [F00x]). Filters: featureRef, status. Cheap discovery — do NOT read .planner/ files or planner-plan-get full=true.",
+    description: "List phases (compact: F00x/P00x · shortId — title (status; priority N; N tasks) [F00x]). Filters: featureRef, status. Cheap discovery — do NOT read .planner/ files or planner-plan-get full=true.",
     inputSchema: { featureRef: z.string().optional().describe("Optional: filter to one feature (F00x/shortId/UUID/name)."), status: z.string().optional().describe("Optional: filter by status name.") },
 }, async ({ featureRef, status }) => {
     const st = await requireStore();
@@ -427,15 +698,27 @@ server.registerTool("planner-phase-list", {
     }
     if (status)
         phases = phases.filter((p) => p.status === status);
-    const lines = phases.map((phase) => {
+    const items = phases.map((phase) => {
         const fNum = featureNumberOfPhase(phase, features);
-        const fTag = fNum !== undefined ? ` [F${String(fNum).padStart(3, "0")}]` : "";
-        return `- ${formatPhaseRef(phase.number, fNum)}${phase.shortId ? ` · ${phase.shortId}` : ""} — ${phase.title} (${phase.status}; ${phase.tasks.length} tasks)${fTag}`;
+        return {
+            id: phase.id,
+            ref: formatPhaseRef(phase.number, fNum),
+            shortId: phase.shortId,
+            title: phase.title,
+            status: phase.status,
+            priority: phase.priority,
+            taskCount: phase.tasks.length,
+            featureNumber: fNum,
+        };
     });
-    return text(lines.join("\n") || "No phases");
+    const lines = items.map((phase) => {
+        const fTag = phase.featureNumber !== undefined ? ` [F${String(phase.featureNumber).padStart(3, "0")}]` : "";
+        return `- ${phase.ref}${phase.shortId ? ` · ${phase.shortId}` : ""} — ${phase.title} (${phase.status}${phase.priority > 0 ? `; priority ${phase.priority}` : ""}; ${phase.taskCount} tasks)${fTag}`;
+    });
+    return text(lines.join("\n") || "No phases", { phases: items });
 });
 server.registerTool("planner-task-list", {
-    description: "List tasks (compact: F00x/P00x/T00x · shortId — title (status)). Filters: featureRef, phaseRef, status. Cheap discovery — do NOT read .planner/ files or planner-plan-get full=true.",
+    description: "List tasks (compact: F00x/P00x/T00x · shortId — title (status; priority N)). Filters: featureRef, phaseRef, status. Cheap discovery — do NOT read .planner/ files or planner-plan-get full=true.",
     inputSchema: { featureRef: z.string().optional(), phaseRef: z.string().optional(), status: z.string().optional().describe("Optional: filter by status name.") },
 }, async ({ featureRef, phaseRef, status }) => {
     const st = await requireStore();
@@ -453,15 +736,142 @@ server.registerTool("planner-task-list", {
             return text(`Phase not found: ${phaseRef}`);
         phases = [p];
     }
-    const out = [];
+    const items = [];
     for (const phase of phases) {
         for (const task of phase.tasks) {
             if (status && task.status !== status)
                 continue;
-            out.push(`- ${taskCompositeRef(task, phase, features)}${task.shortId ? ` · ${task.shortId}` : ""} — ${task.title} (${task.status})`);
+            items.push({
+                id: task.id,
+                ref: taskCompositeRef(task, phase, features),
+                shortId: task.shortId,
+                title: task.title,
+                status: task.status,
+                priority: task.priority,
+                phaseId: phase.id,
+                ...(phase.featureId ? { featureId: phase.featureId } : {}),
+            });
         }
     }
-    return text(out.join("\n") || "No tasks");
+    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.",
@@ -472,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);
@@ -519,34 +931,72 @@ server.registerTool("planner-feature-show", {
     if (!resolvedFeature.ok)
         return text(resolvedFeature.error);
     const feature = resolvedFeature.feature;
-    if (full)
-        markFeatureReadForSessionId(plannerSessionId, feature.id);
     const phases = (await st.loadAllPhases()).filter((phase) => phase.featureId === feature.id);
     const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases)`;
-    return text(full ? `${summary}\n\n${feature.description || ""}` : summary);
+    const descriptionRefBlock = feature.descriptionRef ? `\n\nDescription reference:\n- ${feature.descriptionRef}` : "";
+    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.",
     inputSchema: {
         feature: z.string().min(1).describe("Feature ref. Accepts F00x, shortId, UUID, or title."),
         description: z.string().optional().describe("Current implementation state, scope, and goals for this feature."),
+        descriptionRef: z.string().optional().describe("Optional markdown reference under .planner/docs/ for the full feature description."),
         workDone: z.string().optional().describe("What is already implemented / decided."),
         workRemaining: z.string().optional().describe("What still needs to be done."),
         dependencies: z.array(z.string()).optional().describe("Cross-feature or external dependencies."),
     },
-}, async ({ feature: ref, description, workDone, workRemaining, dependencies }) => {
+}, async ({ feature: ref, description, descriptionRef: rawDescriptionRef, workDone, workRemaining, dependencies }) => {
     const st = await requireStore();
     const features = (await st.loadFeatures()).features;
     const resolvedFeature = resolveFeatureRefStrict(features, ref);
     if (!resolvedFeature.ok)
         return text(resolvedFeature.error);
     const feature = resolvedFeature.feature;
+    const mutableFields = ["description", "descriptionRef", "workDone", "workRemaining", "dependencies"];
+    const discussInputs = { description, descriptionRef: rawDescriptionRef, workDone, workRemaining, dependencies };
+    const receivedFields = mutableFields.filter((field) => discussInputs[field] !== undefined);
+    if (receivedFields.length === 0) {
+        return mutationNoFieldsFailure({
+            entity: "feature",
+            ref: formatFeatureRef(feature.number),
+            operation: "discuss",
+            mutableFields,
+            retryCommand: `planner-feature-discuss ${formatFeatureRef(feature.number)}`,
+            readBackCommand: `planner-feature-show ${formatFeatureRef(feature.number)} with full=true`,
+            descriptionFallback: {
+                entityId: feature.id,
+                inputField: "description",
+                storedField: "feature description",
+                descriptionRefField: "descriptionRef",
+            },
+        });
+    }
     const updated = await st.updateFeatures((doc) => {
         const target = doc.features.find((entry) => entry.id === feature.id);
         if (!target)
             return doc;
         if (description !== undefined)
             target.description = description.trim();
+        if (rawDescriptionRef !== undefined) {
+            const descriptionRef = normalizeDescriptionRef(rawDescriptionRef);
+            if (descriptionRef)
+                target.descriptionRef = descriptionRef;
+            else
+                delete target.descriptionRef;
+        }
         if (workDone !== undefined)
             target.workDone = workDone.trim();
         if (workRemaining !== undefined)
@@ -560,7 +1010,7 @@ server.registerTool("planner-feature-discuss", {
         return doc;
     });
     const result = updated.features.find((entry) => entry.id === feature.id);
-    return writeAndSummarize(st, `✅ Feature discussed/updated: ${formatFeatureRef(result.number)} — ${result.name}${result.shortId ? ` · ${result.shortId}` : ""}`);
+    return writeAndSummarize(st, `✅ Feature discussed/updated: ${formatFeatureRef(result.number)} — ${result.name}${result.shortId ? ` · ${result.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`, { feature: result, discussed: true, updatedFields: receivedFields });
 });
 server.registerTool("planner-feature-update", {
     description: "Update a feature.",
@@ -568,6 +1018,7 @@ server.registerTool("planner-feature-update", {
         feature: z.string().min(1).describe("Feature ref. Accepts F00x/P00x/T00x composite, bare P00x/T00x (global), 5-char shortId, UUID, or title."),
         name: z.string().optional(),
         description: z.string().optional(),
+        descriptionRef: z.string().optional().describe("Optional markdown reference under .planner/docs/ for the full feature description."),
         status: z.enum(STATUS_VALUES).optional(),
         workDone: z.string().optional(),
         workRemaining: z.string().optional(),
@@ -585,6 +1036,24 @@ server.registerTool("planner-feature-update", {
     if (updates.status !== undefined) {
         return derivedStatusReadOnlyResult("feature", formatFeatureRef(feature.number), updates.status, feature.status);
     }
+    const mutableFields = ["name", "description", "descriptionRef", "workDone", "workRemaining", "startDate", "endDate", "priority"];
+    const receivedFields = mutableFields.filter((field) => updates[field] !== undefined);
+    if (receivedFields.length === 0) {
+        return mutationNoFieldsFailure({
+            entity: "feature",
+            ref: formatFeatureRef(feature.number),
+            operation: "update",
+            mutableFields,
+            retryCommand: `planner-feature-update ${formatFeatureRef(feature.number)}`,
+            readBackCommand: `planner-feature-show ${formatFeatureRef(feature.number)} with full=true`,
+            descriptionFallback: {
+                entityId: feature.id,
+                inputField: "description",
+                storedField: "feature description",
+                descriptionRefField: "descriptionRef",
+            },
+        });
+    }
     const updated = await st.updateFeatures((doc) => {
         const target = doc.features.find((entry) => entry.id === feature.id);
         if (!target)
@@ -593,6 +1062,13 @@ server.registerTool("planner-feature-update", {
             target.name = updates.name.trim();
         if (updates.description !== undefined)
             target.description = updates.description.trim();
+        if (updates.descriptionRef !== undefined) {
+            const descriptionRef = normalizeDescriptionRef(updates.descriptionRef);
+            if (descriptionRef)
+                target.descriptionRef = descriptionRef;
+            else
+                delete target.descriptionRef;
+        }
         if (updates.workDone !== undefined)
             target.workDone = updates.workDone.trim();
         if (updates.workRemaining !== undefined)
@@ -607,7 +1083,7 @@ server.registerTool("planner-feature-update", {
         return doc;
     });
     const result = updated.features.find((entry) => entry.id === feature.id);
-    return writeAndSummarize(st, `✅ Feature updated: ${formatFeatureRef(result.number)} — ${result.name}${result.shortId ? ` · ${result.shortId}` : ""}`);
+    return writeAndSummarize(st, `✅ Feature updated: ${formatFeatureRef(result.number)} — ${result.name}${result.shortId ? ` · ${result.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.`, { feature: result, updated: true, updatedFields: receivedFields });
 });
 server.registerTool("planner-feature-delete", {
     description: "Delete a feature. By default, phases are unlinked rather than deleted.",
@@ -623,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", {
@@ -663,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();
@@ -701,6 +1177,7 @@ server.registerTool("planner-phase-add", {
             updatedAt: timestamp,
             handoff: "",
             handoffUpdatedAt: "",
+            handoffAudit: null,
             handoffReadAt: "",
             handoffHistory: [],
             statusLog: [],
@@ -716,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);
@@ -731,15 +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 || ""}${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,
@@ -747,21 +1236,28 @@ server.registerTool("planner-phase-show", {
             summary: phase.summary,
             status: phase.status,
             taskCount: phase.tasks.length,
-            ...(full ? { description: phase.description } : {}),
+            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 }) => {
@@ -770,39 +1266,76 @@ server.registerTool("planner-phase-discuss", {
     const found = findPhaseByRef(await st.loadAllPhases(), features, ref);
     if (!found)
         return text(`Phase not found: ${ref}`);
+    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({
+            entity: "phase",
+            ref: formatPhaseRef(found.number, featureNumberOfPhase(found, features)),
+            operation: "discuss",
+            mutableFields,
+            retryCommand: `planner-phase-discuss ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))}`,
+            readBackCommand: `planner-phase-show ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} with full=true`,
+            descriptionFallback: {
+                entityId: found.id,
+                inputField: "scope",
+                storedField: "phase description",
+                descriptionRefField: "descriptionRef",
+            },
+        });
+    }
     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();
         if (updates.scope !== undefined)
             entry.description = updates.scope.trim();
+        if (updates.descriptionRef !== undefined) {
+            const descriptionRef = normalizeDescriptionRef(updates.descriptionRef);
+            if (descriptionRef)
+                entry.descriptionRef = descriptionRef;
+            else
+                delete entry.descriptionRef;
+        }
         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.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}` : ""}`);
+    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(),
         status: z.enum(PHASE_STATUS_VALUES).optional(),
         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();
@@ -813,19 +1346,101 @@ server.registerTool("planner-phase-update", {
     if (updates.status !== undefined) {
         return derivedStatusReadOnlyResult("phase", formatPhaseRef(found.number, featureNumberOfPhase(found, features)), updates.status, found.status);
     }
-    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.priority !== undefined)
-            entry.priority = updates.priority;
-        entry.updatedAt = nowISO();
-        return entry;
+    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({
+            entity: "phase",
+            ref: formatPhaseRef(found.number, featureNumberOfPhase(found, features)),
+            operation: "update",
+            mutableFields,
+            retryCommand: `planner-phase-update ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))}`,
+            readBackCommand: `planner-phase-show ${formatPhaseRef(found.number, featureNumberOfPhase(found, features))} with full=true`,
+            descriptionFallback: {
+                entityId: found.id,
+                inputField: "description",
+                storedField: "phase description",
+                descriptionRefField: "descriptionRef",
+            },
+        });
+    }
+    const previousFeatureId = found.featureId;
+    let nextFeatureId = previousFeatureId;
+    if (updates.featureId !== undefined) {
+        if (updates.featureId.trim() === "") {
+            nextFeatureId = undefined;
+        }
+        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}` : ""}`);
+    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.",
@@ -835,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 });
@@ -855,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);
@@ -926,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)
@@ -944,6 +1562,8 @@ server.registerTool("planner-task-show", {
     const sections = [summary];
     if (found.task.description?.trim())
         sections.push(found.task.description.trim());
+    if (found.task.descriptionRef)
+        sections.push(`Description reference:\n- ${found.task.descriptionRef}`);
     if (snapshot || pendingDeviation) {
         sections.push([
             pendingDeviation
@@ -957,20 +1577,50 @@ server.registerTool("planner-task-show", {
     }
     if (log)
         sections.push(`Status log:\n${log}`);
-    return text(sections.join("\n\n"));
+    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.",
     inputSchema: {
         task: z.string().min(1),
         description: z.string().optional(),
+        descriptionRef: z.string().optional().describe("Optional markdown reference under .planner/docs/ for the full task description."),
         checklist: z.array(z.string()).optional(),
     },
-}, async ({ task: ref, description, checklist }) => {
+}, async ({ task: ref, description, descriptionRef: rawDescriptionRef, checklist }) => {
     const st = await requireStore();
     const found = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, ref);
     if (!found)
         return text(`Task not found: ${ref}`);
+    const mutableFields = ["description", "descriptionRef", "checklist"];
+    const discussInputs = { description, descriptionRef: rawDescriptionRef, checklist };
+    const receivedFields = mutableFields.filter((field) => discussInputs[field] !== undefined);
+    if (receivedFields.length === 0) {
+        return mutationNoFieldsFailure({
+            entity: "task",
+            ref: taskCompositeRef(found.task, found.phase, (await st.loadFeatures()).features),
+            operation: "discuss",
+            mutableFields,
+            retryCommand: `planner-task-discuss ${taskCompositeRef(found.task, found.phase, (await st.loadFeatures()).features)}`,
+            readBackCommand: `planner-task-show ${taskCompositeRef(found.task, found.phase, (await st.loadFeatures()).features)} with full=true`,
+            descriptionFallback: {
+                entityId: found.task.id,
+                inputField: "description",
+                storedField: "task description",
+                descriptionRefField: "descriptionRef",
+            },
+        });
+    }
     let updatedTask;
     await st.updatePhase(found.phase.id, (phase) => {
         const task = phase.tasks.find((entry) => entry.id === found.task.id);
@@ -978,8 +1628,13 @@ server.registerTool("planner-task-discuss", {
             return phase;
         if (description !== undefined)
             task.description = description.trim();
-        if (checklist !== undefined)
-            task.checklist = checklist.map((item, index) => ({ id: createChecklistItemId(task.id, index + 1, item), number: index + 1, title: item, checked: false }));
+        if (rawDescriptionRef !== undefined) {
+            const descriptionRef = normalizeDescriptionRef(rawDescriptionRef);
+            if (descriptionRef)
+                task.descriptionRef = descriptionRef;
+            else
+                delete task.descriptionRef;
+        }
         if (checklist !== undefined)
             task.checklist = checklist.map((item, index) => ({ id: createChecklistItemId(task.id, index + 1, item), number: index + 1, title: item, checked: false }));
         task.updatedAt = nowISO();
@@ -989,7 +1644,49 @@ server.registerTool("planner-task-discuss", {
     });
     const features = (await st.loadFeatures()).features;
     const t = updatedTask ?? found.task;
-    return writeAndSummarize(st, `✅ Task discussed/updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}`);
+    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.",
@@ -998,11 +1695,15 @@ server.registerTool("planner-task-update", {
         title: z.string().optional(),
         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, 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)
@@ -1020,6 +1721,31 @@ 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", "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({
+            entity: "task",
+            ref: taskCompositeRef(found.task, found.phase, (await st.loadFeatures()).features),
+            operation: "update",
+            mutableFields,
+            retryCommand: `planner-task-update ${taskCompositeRef(found.task, found.phase, (await st.loadFeatures()).features)}`,
+            readBackCommand: `planner-task-show ${taskCompositeRef(found.task, found.phase, (await st.loadFeatures()).features)} with full=true`,
+            descriptionFallback: {
+                entityId: found.task.id,
+                inputField: "description",
+                storedField: "task description",
+                descriptionRefField: "descriptionRef",
+            },
+        });
+    }
+    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) => {
@@ -1032,6 +1758,32 @@ server.registerTool("planner-task-update", {
             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 = {
@@ -1068,7 +1820,20 @@ server.registerTool("planner-task-update", {
             }
         }
     }
-    return writeAndSummarize(st, `✅ Task updated: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (${t.status})${t.shortId ? ` · ${t.shortId}` : ""}${resumeNotice}`, resumeRequired ? { resumeRequired } : undefined);
+    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.",
@@ -1190,18 +1955,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", {
@@ -1279,7 +2081,7 @@ server.registerTool("planner-task-pause", {
     ].join("\n"), { task: checkpointed, snapshot, ...(resume ? { resumeRequired: { taskId: resume.task.id } } : {}) });
 });
 server.registerTool("planner-task-switch", {
-    description: "Atomically switch from active work to a temporary task, even outside normal priority order. Call this tool first so valid sessionInfo context can be reused; on denial, perform only the missing/stale reads listed in nextActions and retry. Pause the source with a mandatory snapshot, start the target, and push a durable LIFO return target.",
+    description: "Atomically switch from active work to a temporary task, even outside normal priority order. Call this tool first so valid sessionInfo context can be reused; on denial, perform only the missing/stale reads listed in nextActions and retry. If nextActions includes planner-project-guidelines-show, read that section and keep it in working memory while doing task work. Pause the source with a mandatory snapshot, start the target, and push a durable LIFO return target.",
     inputSchema: {
         from_task: z.string().min(1),
         to_task: z.string().min(1),
@@ -1305,6 +2107,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)),
@@ -1323,16 +2128,23 @@ 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);
     const targetPhaseRef = formatPhaseRef(target.phase.number, featureNumberOfPhase(target.phase, features));
     const targetFeatureRef = targetFeature ? formatFeatureRef(targetFeature.number) : "";
+    if (!projectGuidelinesReady) {
+        const nextActions = mcpContextReadActions(contextEligibility, { task: targetTaskRef, phase: targetPhaseRef, ...(targetFeatureRef ? { feature: targetFeatureRef } : {}) }, true, !requirementsReady, `Retry planner-task-switch to ${targetTaskRef}`);
+        return text(`Task switch denied: read Project Guidelines before switching task work. Current state: ${projectGuidelinesReadState}.`, { projectGuidelinesReadState, contextEligibility, nextActions });
+    }
     if (!contextEligibility.eligible) {
-        const nextActions = mcpContextReadActions(contextEligibility, { task: targetTaskRef, phase: targetPhaseRef, ...(targetFeatureRef ? { feature: targetFeatureRef } : {}) }, !requirementsReady, `Retry planner-task-switch to ${targetTaskRef}`);
+        const nextActions = mcpContextReadActions(contextEligibility, { task: targetTaskRef, phase: targetPhaseRef, ...(targetFeatureRef ? { feature: targetFeatureRef } : {}) }, false, !requirementsReady, `Retry planner-task-switch to ${targetTaskRef}`);
         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 });
@@ -1346,7 +2158,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,
@@ -1357,74 +2169,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)}`,
@@ -1433,8 +2248,28 @@ 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, in order, and retry. 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.",
+    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) },
 }, async ({ task: ref }, extra) => {
     const plannerSessionId = plannerSessionIdFor(extra);
@@ -1445,144 +2280,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}.`, `Repeat the required full context reads, then retry planner-task-start ${taskRef}.`], { taskId: found.task.id }));
-    const linkedRequirements = [
-        ...(await st.linkedRequirementsForPhase(found.phase.id)),
-        ...(found.phase.featureId ? await st.linkedRequirementsForFeature(found.phase.featureId) : []),
-    ].filter((requirement, index, all) => all.findIndex((candidate) => candidate.id === requirement.id) === index);
-    const linkedRequirementIds = linkedRequirements.map((requirement) => requirement.id);
-    const contextInput = {
-        sessionId: plannerSessionId,
-        taskId: found.task.id,
-        phaseId: found.phase.id,
-        ...(found.phase.featureId ? { featureId: found.phase.featureId } : {}),
-        task: found.task,
-        phase: found.phase,
-        ...(parentFeature ? { feature: parentFeature } : {}),
-        requirements: linkedRequirements,
-        requirementIds: linkedRequirementIds,
-    };
-    const contextEligibility = contextReadEligibilityForSession(contextInput);
-    const requirementsReady = hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
-    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 } : {}) }, !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 [project, phases, focus] = await Promise.all([st.loadProject(), st.loadAllPhases(), st.loadResume()]);
-    const eligibility = checkExplicitTaskStart(features, phases, found.task.id, project.workDeviations);
-    if (!eligibility.eligible)
-        return 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", {
@@ -1658,47 +2502,415 @@ server.registerTool("planner-task-complete", {
     return writeAndSummarize(st, `✅ Task completed: ${taskCompositeRef(t, found.phase, features)} — ${t.title} (done)${t.shortId ? ` · ${t.shortId}` : ""}${clearedRef ? ` — phase handoff auto-cleared (${clearedRef})` : ""}${resumeNotice}`, resumeRequired ? { resumeRequired } : undefined);
 });
 server.registerTool("planner-handoff-list", {
-    description: "List all phases with a non-empty entity-scoped handoff (phase.handoff field). Returns composite refs (P00x / P00x(F00x)) with the first line and last-updated time.",
-}, async () => {
+    description: "List active handoffs as compact summary-only pages. Full bodies are never embedded; call planner-handoff-show for one exact phase.",
+    inputSchema: {
+        page: z.number().int().min(1).default(1).describe("1-based page number."),
+        pageSize: z.number().int().min(1).max(25).default(10).describe("Summaries per page; maximum 25."),
+    },
+}, async ({ page, pageSize }) => {
     const st = await requireStore();
     const list = await st.listHandoffs();
     if (list.length === 0)
-        return text("No phase handoffs set.");
-    const lines = list.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`);
-    return text(`Phase handoffs (${list.length}):\n${lines.join("\n")}`, { count: list.length, handoffs: 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; ${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();
     const r = await resolvePhaseForHandoff(st, phaseRef);
     if (!r.ok)
         return text(`❌ ${r.error}`);
-    const content = await st.getPhaseHandoff(r.phase.id);
-    if (!content.trim())
-        return text(`No handoff set on ${r.compositeRef}.`, { phaseRef: r.compositeRef, empty: true });
-    return text(`Handoff for ${r.compositeRef}:\n\n${content}`, { phaseRef: r.compositeRef, phaseId: r.phase.id });
+    const phase = await st.loadPhase(r.phase.id);
+    const bounded = boundedHandoffForTransport(phase.handoff);
+    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 read-back and source reconciliation completed."
+        : "NOT resume-ready: after reading this entire persisted body, call planner-handoff-verify with its contentHash and a fresh comparison against every required source. If any gap exists, rewrite instead of verifying.";
+    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 only after planner-handoff-show has displayed the entire body and the agent has compared it again with conversation corrections, planner entities, working tree/diff, verification/runtime evidence, and peer output. Any discovered omission blocks verification and requires prepare+rewrite.",
+    inputSchema: {
+        phaseRef: z.string().min(1),
+        expectedContentHash: z.string().regex(/^[a-f0-9]{64}$/),
+        sourceReviews: z.array(z.object({
+            source: z.enum(["conversation", "planner-entities", "working-tree", "verification-runtime", "peer-agent-output"]),
+            detail: z.string().min(12),
+        })),
+        omissionsFound: z.array(z.string().min(1)),
+    },
+}, 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, 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 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(),
+        linkedPhaseIds: z.array(z.string().min(1)),
+        macroTasks: z.array(z.object({
+            title: z.string().min(1),
+            description: z.string().optional(),
+            status: z.enum(STATUS_VALUES).optional(),
+        })).optional(),
+    },
+}, async ({ title, description, linkedPhaseIds, macroTasks }) => {
+    const st = await requireStore();
+    const links = await resolveRequirementPhaseRefs(st, linkedPhaseIds);
+    if (!links.ok)
+        return text(`❌ ${links.error}`, { created: false, errorCode: "REQUIREMENT_PHASE_LINK_INVALID" });
+    const now = nowISO();
+    let normalizedMacroTasks;
+    try {
+        normalizedMacroTasks = reconcileRequirementMacroTasks([], (macroTasks ?? []).map((task) => ({
+            title: task.title,
+            ...(task.description !== undefined ? { description: task.description } : {}),
+            status: task.status ?? "planned",
+        })), now);
+    }
+    catch (error) {
+        const message = error instanceof RequirementMacroTaskError ? error.message : "Invalid macro tasks.";
+        return text(`❌ ${message}`, { created: false, errorCode: "REQUIREMENT_MACRO_TASK_INVALID" });
+    }
+    const requirement = {
+        id: createRequirementId(),
+        title: title.trim(),
+        description: description?.trim() ?? "",
+        macroTasks: normalizedMacroTasks,
+        linkedPhaseIds: links.linkedPhaseIds,
+        createdAt: now,
+        updatedAt: now,
+        sessionInfo: [],
+    };
+    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 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(),
+        linkedPhaseIds: z.array(z.string().min(1)).optional(),
+        macroTasks: z.array(z.object({
+            id: z.string().min(1).optional(),
+            title: z.string().min(1),
+            description: z.string().optional(),
+            status: z.enum(STATUS_VALUES),
+        })).optional(),
+    },
+}, 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 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" });
+    }
+    await st.writeGenerated();
+    return writeAndSummarize(st, `Requirement updated: ${next.id}.`, { requirement: next, updated: true });
+});
+server.registerTool("planner-requirement-delete", {
+    description: "Permanently delete a top-level requirement. Confirm the intended requirement first.",
+    inputSchema: { requirementId: z.string().min(1) },
+}, async ({ requirementId }) => {
+    const st = await requireStore();
+    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.writeGenerated();
+    return writeAndSummarize(st, `Requirement deleted: ${requirementId}.`, { deleted: true, requirementId });
+});
+function ideaPromotionTarget(st, type, ref) {
+    return Promise.all([st.loadFeatures(), st.loadAllPhases()]).then(([featuresDoc, phases]) => {
+        const features = featuresDoc.features;
+        if (type === "feature") {
+            const feature = findFeatureByRef(features, ref);
+            return feature ? { id: feature.id, ref: formatFeatureRef(feature.number) } : undefined;
+        }
+        if (type === "phase") {
+            const phase = findPhaseByRef(phases, features, ref);
+            return phase ? { id: phase.id, ref: formatPhaseRef(phase.number, features.find((item) => item.id === phase.featureId)?.number) } : undefined;
+        }
+        const found = findTaskByRef(phases, features, ref);
+        return found ? { id: found.task.id, ref: `${formatPhaseRef(found.phase.number, features.find((item) => item.id === found.phase.featureId)?.number)}/T${String(found.task.number).padStart(3, "0")}` } : undefined;
+    });
+}
+server.registerTool("planner-idea-list", {
+    description: "List top-level Ideas Inbox entries. Ideas never affect feature, phase, or task rollups.",
+    inputSchema: {},
+}, async () => {
+    const ideas = (await requireStore().then((st) => st.loadIdeas())).ideas;
+    return text(ideas.map((idea) => `- ${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}${idea.promotion ? ` → ${idea.promotion.targetRef}` : ""}`).join("\n") || "No ideas", { ideas });
+});
+server.registerTool("planner-idea-show", {
+    description: "Show one Idea Inbox entry by I-number, short ID, UUID, or title.",
+    inputSchema: { idea: z.string().min(1) },
+}, async ({ idea: ref }) => {
+    const st = await requireStore();
+    const idea = findIdeaByRef((await st.loadIdeas()).ideas, ref);
+    return idea ? text(`${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}\n\n${idea.description || "(no description)"}`, { idea }) : text(`Idea not found: ${ref}`, { errorCode: "NOT_FOUND" });
+});
+server.registerTool("planner-idea-create", {
+    description: "Create a rollup-independent Ideas Inbox entry.",
+    inputSchema: { title: z.string().min(1), description: z.string().optional() },
+}, async ({ title, description }) => {
+    const st = await requireStore();
+    const idea = await st.createIdea({ title, ...(description !== undefined ? { description } : {}) });
+    await st.writeGenerated();
+    return text(`Idea created: ${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}`, { idea, created: true });
+});
+server.registerTool("planner-idea-update", {
+    description: "Update an unpromoted or promoted Idea Inbox entry title or description.",
+    inputSchema: { idea: z.string().min(1), title: z.string().min(1).optional(), description: z.string().optional() },
+}, async ({ idea: ref, title, description }) => {
+    const st = await requireStore();
+    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 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 });
+});
+server.registerTool("planner-idea-delete", {
+    description: "Delete an Idea Inbox entry. Confirm the exact idea with the user before calling.",
+    inputSchema: { idea: z.string().min(1), confirmed: z.boolean() },
+}, async ({ idea: ref, confirmed }) => {
+    if (!confirmed)
+        return text("Idea deletion requires confirmed=true after explicit user confirmation.", { errorCode: "CONFIRMATION_REQUIRED", deleted: false });
+    const st = await requireStore();
+    const current = findIdeaByRef((await st.loadIdeas()).ideas, ref);
+    if (!current)
+        return text(`Idea not found: ${ref}`, { errorCode: "NOT_FOUND", deleted: false });
+    await st.deleteIdea(current.id);
+    await st.writeGenerated();
+    return text(`Idea deleted: ${formatIdeaRef(current.number)}.`, { deleted: true, ideaRef: formatIdeaRef(current.number) });
+});
+server.registerTool("planner-idea-promotion-begin", {
+    description: "Begin an Idea promotion discussion without persisting a target or promotion. Returns the project-local grill-me instructions; follow them one question at a time, then use planner-idea-promotion-finalize only after target confirmation.",
+    inputSchema: { idea: z.string().min(1), targetType: z.enum(["feature", "phase", "task"]) },
+}, async ({ idea: ref, targetType }) => {
+    const st = await requireStore();
+    const idea = findIdeaByRef((await st.loadIdeas()).ideas, ref);
+    if (!idea)
+        return text(`Idea not found: ${ref}`, { errorCode: "NOT_FOUND" });
+    if (idea.promotion)
+        return text(`${formatIdeaRef(idea.number)} is already promoted to ${idea.promotion.targetRef}.`, { errorCode: "ALREADY_PROMOTED", idea });
+    const features = (await st.loadFeatures()).features;
+    const phases = await st.loadAllPhases();
+    const recommendedFeature = features[0];
+    const recommendedPhase = recommendedFeature ? phases.find((phase) => phase.featureId === recommendedFeature.id) : phases[0];
+    const recommendation = targetType === "feature"
+        ? "Create a new feature after the discussion."
+        : targetType === "phase"
+            ? recommendedFeature ? `Recommended parent feature: ${formatFeatureRef(recommendedFeature.number)} — ${recommendedFeature.name}. Confirm or choose another feature before creating the phase.` : "Create and confirm a parent feature before promoting to a phase."
+            : recommendedPhase
+                ? `Recommended destination: ${formatPhaseRef(recommendedPhase.number, features.find((feature) => feature.id === recommendedPhase.featureId)?.number)} — ${recommendedPhase.title}. Confirm its feature and phase before creating the task.`
+                : "Create and confirm a parent feature and phase before promoting to a task.";
+    return text(`Promotion discussion started for ${formatIdeaRef(idea.number)}. ${recommendation}`, { idea, targetType, recommendation, grillMeSkill: await st.ideaDiscussionSkill(), persisted: false, nextActions: ["Follow grill-me one question at a time.", "Obtain explicit parent and target confirmation.", "Create the agreed target through the normal feature/phase/task creation tool.", "Call planner-idea-promotion-finalize with discussionCompleted=true and confirmed=true."] });
+});
+server.registerTool("planner-idea-promotion-finalize", {
+    description: "Record a promotion only after grill-me discussion, explicit target confirmation, and successful target creation. targetRef must be the already-created agreed target; no raw UUID is returned.",
+    inputSchema: { idea: z.string().min(1), targetType: z.enum(["feature", "phase", "task"]), targetRef: z.string().min(1), discussionCompleted: z.boolean(), confirmed: z.boolean() },
+}, async ({ idea: ref, targetType, targetRef, discussionCompleted, confirmed }) => {
+    if (!discussionCompleted || !confirmed)
+        return text("Promotion requires discussionCompleted=true and confirmed=true; no target or promotion was persisted.", { errorCode: "IDEA_PROMOTION_CONFIRMATION_REQUIRED", promoted: false });
+    const st = await requireStore();
+    const idea = findIdeaByRef((await st.loadIdeas()).ideas, ref);
+    if (!idea)
+        return text(`Idea not found: ${ref}`, { errorCode: "NOT_FOUND", promoted: false });
+    const target = await ideaPromotionTarget(st, targetType, targetRef);
+    if (!target)
+        return text(`Confirmed ${targetType} target not found: ${targetRef}; no promotion was persisted.`, { errorCode: "TARGET_NOT_FOUND", promoted: false });
+    const promoted = await st.promoteIdea(idea.id, { targetType, targetId: target.id });
+    await st.writeGenerated();
+    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 and refresh the single active phase handoff while synchronizing durable task, phase, and feature context. Run planner-handoff-prepare with the confirmed phaseRef first and pass its exact handoffUpdatedAt token.",
+    description: "Persist a reconciled handoff candidate with durable context synchronization and mandatory audits. The result always has resumeReady=false until a separate planner-handoff-show read-back and planner-handoff-verify source reconciliation succeeds. Run planner-handoff-prepare first; link extended detail from committed .planner/docs/ Markdown.",
     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."),
         reconciledExistingHandoff: z.boolean().optional().describe("Confirm that still-relevant existing handoff information was retained."),
+        completenessAudit: z.object({
+            version: z.literal(HANDOFF_COMPLETENESS_AUDIT_VERSION),
+            entries: z.array(z.object({
+                category: z.string().min(1).describe(`One required category id: ${HANDOFF_COMPLETENESS_CATEGORIES.map((entry) => entry.id).join(", ")}`),
+                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."),
+        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("Mandatory for confirmed writes. Every concrete item must appear verbatim in the handoff or a validated supporting document."),
+        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."),
+        })).optional(),
         taskUpdates: z.array(z.object({
             taskRef: z.string().min(1),
             completionSummary: z.string().min(1),
@@ -1716,7 +2928,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, 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) ?? "";
@@ -1740,7 +2952,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 = [];
@@ -1759,9 +2973,13 @@ 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,
                 ...(phaseUpdate ? { phaseUpdate: {
@@ -1775,15 +2993,31 @@ server.registerTool("planner-handoff-write", {
             },
         });
         await st.writeGenerated();
-        return text(`✅ Reconciled handoff and durable context on ${r.compositeRef}; updated ${result.updatedTaskIds.length} task(s).`, { phaseRef: r.compositeRef, phaseId: r.phase.id, ...result });
+        return text(`⚠️ Handoff candidate persisted on ${r.compositeRef}, but it is NOT resume-ready yet. Required next action: call planner-handoff-show ${r.compositeRef}, read the entire persisted body, compare it again with every required source, then call planner-handoff-verify with the returned contentHash. If that review finds any gap, run prepare+write again instead of verifying.`, {
+            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.`,
+                "Compare the persisted body against conversation corrections, planner entities, working tree/diff, verification/runtime evidence, and peer-agent output.",
+                "If any omission exists, run planner-handoff-prepare and planner-handoff-write again; otherwise call planner-handoff-verify with the shown contentHash.",
+            ],
+        });
     }
     catch (error) {
+        if (error instanceof HandoffContractError)
+            return handoffContractFailure(error);
         const message = error instanceof Error ? error.message : String(error);
         return text(`❌ Handoff refresh denied: ${message}`, { error: message });
     }
 });
 server.registerTool("planner-handoff-prepare", {
-    description: "Identify or audit the exact handoff target. Without phaseRef, returns the confirmation workflow. With a confirmed phaseRef, returns the current handoff/version and done tasks missing durable completion evidence.",
+    description: "Identify or audit the exact handoff target. With a confirmed phaseRef, returns the canonical scaffold, a bounded priority-ordered phase work map with sibling goals/dependencies/capability ownership, the current token, missing task evidence, mandatory audits, and the 24,000-character inline budget. Reread the canonical phase and relevant sibling tasks before proposing work.",
     inputSchema: { phaseRef: z.string().min(1).optional() },
 }, async ({ phaseRef }) => {
     if (!phaseRef)
@@ -1802,9 +3036,24 @@ server.registerTool("planner-handoff-prepare", {
         return text([
             `Handoff preparation audit 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}`),
+            "",
+            `Required cold-start source review v${audit.coldStartInventoryVersion} — inspect and substantively summarize every source before drafting:`,
+            ...audit.coldStartSourceReviews.map((entry) => `- ${entry.id} — ${entry.label}`),
+            "Required cold-start inventory — every category needs a concrete item (use an explicit verified-negative statement when nothing exists), and every item must appear verbatim in the handoff or a validated supporting document:",
+            ...audit.coldStartInventoryCategories.map((entry) => `- ${entry.id} — ${entry.label}`),
+            `Maximum canonical inline content: ${audit.maxContentChars} characters. Link extended material from .planner/docs/.`,
+            "",
             "Existing active handoff (reconcile all still-relevant content):",
             audit.handoff.trim() || "(none)",
         ].join("\n"), { phaseRef: r.compositeRef, ...audit });
@@ -1833,47 +3082,93 @@ 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).",
-}, async () => {
+    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()))
         return text("No .planner/ found at " + planRoot() + ". Run planner-init first.");
+    const plannerSessionId = plannerSessionIdFor(extra);
+    let preparation;
+    try {
+        preparation = await st.preparePlannerSession();
+    }
+    catch (error) {
+        return text(`Planner load aborted: ${error instanceof Error ? error.message : String(error)}`, { errorCode: "PLANNER_SESSION_PREPARATION_FAILED", loaded: false });
+    }
+    const project = preparation.project;
+    if (project.projectGuidelines.content.trim()) {
+        await st.recordProjectGuidelinesRead({ sessionId: plannerSessionId });
+    }
+    const plannerSkill = await st.syncPlannerSkill();
+    await st.syncGrillMeSkill();
     const web = await ensureWebStarted();
     const recap = await buildRecap(st, web, { harness: "mcp" });
-    return text(recap);
+    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",
+                content: plannerSkill.content,
+                status: plannerSkill.status,
+                customized: plannerSkill.customized,
+                message: plannerSkill.message,
+                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,
+            },
+        },
+    };
 });
 server.registerTool("planner-disable", {
     description: "MCP no-op equivalent of Pi /planner disable. Stop the MCP process from the host to disable it.",