@agent-plan/pi-adapter 0.2.25 → 0.2.27

package/dist/index.js

@@ -10,12 +10,13 @@
  */
 import { Type } from "typebox";
 import { paginatedSelect, paginatedNotify } from "./ui/paginate.js";
-import { ExportService, PlanStore, setWriteBusyHook, setWriteNotifyHook, 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 { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
+import { ExportService, PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, 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_SOURCE_REVIEWS, HANDOFF_COLD_START_INVENTORY_CATEGORIES, MAX_HANDOFF_CONTENT_CHARS, handoffContentHash, HandoffContractError } from "@agent-plan/core";
+import { createChecklistItemId, createFeatureId, createPhaseId, createTaskId, clampSlug, normalizeSlug, formatPhaseRef, formatFeatureRef, formatIdeaRef, featureNumberOfPhase, validateResolvedTarget } from "@agent-plan/core/naming";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { writeFile, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { createServer } from "node:net";
 import { fileURLToPath } from "node:url";
 import { serve } from "@agent-plan/server/serve";
@@ -85,16 +86,74 @@ function derivedStatusReadOnlyResult(entity, ref, attemptedStatus, effectiveStat
         },
     };
 }
-function piContextReadActions(eligibility, refs, requirementReadRequired, retryAction) {
-    const actions = (eligibility.requiredReads ?? []).flatMap((read) => {
+function mutationNoFieldsFailure(input) {
+    const outcome = noMutableFieldsReceived(input);
+    return {
+        isError: true,
+        content: [{ type: "text", text: outcome.message }],
+        details: 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}` }],
+        details: { [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 handoffContractFailure(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: `❌ Handoff refresh denied [${error.code}]: ${error.message}` }],
+        details: { errorCode: error.code, ...error.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 piContextReadActions(eligibility, refs, projectGuidelinesReadRequired, requirementReadRequired, retryAction) {
+    const actions = projectGuidelinesReadRequired ? ["project_guidelines_show"] : [];
+    actions.push(...(eligibility.requiredReads ?? []).flatMap((read) => {
         if (read.kind === "task")
             return [`task_get ${refs.task} with full=true`];
         if (read.kind === "phase")
             return [`phase_get ${refs.phase} with full=true`];
-        return refs.feature ? [`feature_get ${refs.feature} with full=true`] : [];
-    });
+        if (read.kind === "feature")
+            return refs.feature ? [`feature_get ${refs.feature} with full=true`] : [];
+        return [];
+    }));
     if (requirementReadRequired)
-        actions.push("requirement_list");
+        actions.push(`requirement_list with phaseRef=${refs.phase}`);
     actions.push(retryAction);
     return actions;
 }
@@ -172,6 +231,14 @@ const PLANNER_COMMAND_COMPLETIONS = [
     { value: "cleanup-orphans", label: "cleanup-orphans", description: "List and remove orphan phase files" },
     { value: "project discuss", label: "project discuss", description: "Run project discovery" },
     { value: "project language", label: "project language", description: "Set persistent language preferences" },
+    { value: "project guidelines", label: "project guidelines", description: "Edit the canonical Project Guidelines section" },
+    { value: "project migrate-context", label: "project migrate-context", description: "Preview and explicitly migrate legacy project rules and decisions" },
+    { value: "idea list", label: "idea list", description: "List Ideas Inbox entries" },
+    { value: "idea add", label: "idea add", description: "Create an Ideas Inbox entry" },
+    { value: "idea show", label: "idea show", description: "Show an idea" },
+    { value: "idea update", label: "idea update", description: "Update an idea" },
+    { value: "idea delete", label: "idea delete", description: "Delete an idea after confirmation" },
+    { value: "idea promote", label: "idea promote", description: "Begin guided idea promotion" },
     { value: "feature list", label: "feature list", description: "List features" },
     { value: "feature add", label: "feature add", description: "Create a feature" },
     { value: "feature show", label: "feature show", description: "Show a feature" },
@@ -280,7 +347,7 @@ async function ensureProjectLanguagePreferences(st, persist = true) {
             project.contentLanguage = contentLanguage;
             project.chatLanguage = chatLanguage;
             if (persist)
-                await st.saveProject(project);
+                await st.updateProject((current) => ({ ...current, contentLanguage, chatLanguage }));
         }
         return project;
     }
@@ -289,7 +356,11 @@ async function ensureProjectLanguagePreferences(st, persist = true) {
         project.contentLanguage = contentLanguage || fallback;
         project.chatLanguage = chatLanguage || fallback;
         if (persist)
-            await st.saveProject(project);
+            await st.updateProject((current) => ({
+                ...current,
+                contentLanguage: project.contentLanguage,
+                chatLanguage: project.chatLanguage,
+            }));
         return project;
     }
     return project;
@@ -624,6 +695,33 @@ function statusIcon(status) {
 function pad(n) {
     return String(n).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: `${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}` };
+}
 function applyTaskLifecycleDates(task, nextStatus, now) {
     const previousStatus = task.status;
     if (nextStatus === "in-progress" && !task.startedAt) {
@@ -656,8 +754,7 @@ async function pickProjectPort(ctx, explicitPort) {
         if (!(await isPortAvailable(explicitPort)) && project.webPort !== explicitPort) {
             throw new Error(`Port ${explicitPort} is already in use`);
         }
-        project.webPort = explicitPort;
-        await st.saveProject(project);
+        await st.updateProject((current) => ({ ...current, webPort: explicitPort }));
         return explicitPort;
     }
     // Reuse the persisted port if it's still free (stable port across restarts,
@@ -674,8 +771,7 @@ async function pickProjectPort(ctx, explicitPort) {
             continue;
         if (await isPortAvailable(port)) {
             if (project.webPort <= 0) {
-                project.webPort = port;
-                await st.saveProject(project);
+                await st.updateProject((current) => ({ ...current, webPort: port }));
             }
             return port;
         }
@@ -807,8 +903,7 @@ async function startServer(ctx, requestedPort, visibility = "lan") {
                 // existing canonical). Never persist a transient fallback port — that
                 // hijacks the primary session's port when two instances share a .planner.
                 if (project.webPort <= 0 || project.webPort === realPort) {
-                    project.webPort = realPort;
-                    await st.saveProject(project);
+                    await st.updateProject((current) => ({ ...current, webPort: realPort }));
                 }
             }
         }
@@ -1139,6 +1234,13 @@ export default function planPiExtension(pi) {
             "cleanup-orphans",
             "project discuss",
             "project language",
+            "project guidelines",
+            "idea list",
+            "idea add",
+            "idea show",
+            "idea update",
+            "idea delete",
+            "idea promote",
             "feature list",
             "feature add",
             "feature show",
@@ -1170,7 +1272,7 @@ export default function planPiExtension(pi) {
             "load",
             "stop",
         ];
-        const SUB_HELP = "Available: init, show, version, repair, cleanup-orphans, project, feature, phase, task, discuss, handoff, web, export, export-full, bypass, clear-bypass, load, stop\n" +
+        const SUB_HELP = "Available: init, show, version, repair, cleanup-orphans, project, idea, feature, phase, task, discuss, handoff, web, export, export-full, bypass, clear-bypass, load, stop\n" +
             "Try: /planner <TAB>  |  /planner feature list  |  /planner task start  |  /planner cleanup-orphans\n" +
             "Handoff actions: /planner handoff list | show P00x | write P00x | clear P00x | prepare (prepare proposes a target and asks for confirmation)";
         if (!a) {
@@ -1183,11 +1285,16 @@ export default function planPiExtension(pi) {
             return;
         }
         if (a === "version") {
+            const packages = runtimePackagesDiagnostic([PI_ADAPTER_PACKAGE, CORE_PACKAGE, SERVER_PACKAGE]);
+            const capabilities = runtimeCapabilities();
             ctx.ui.notify([
-                "Agent Plan runtime versions",
-                `${PI_ADAPTER_PACKAGE.name}: ${PI_ADAPTER_PACKAGE.version}`,
-                `${CORE_PACKAGE.name}: ${CORE_PACKAGE.version}`,
-                `${SERVER_PACKAGE.name}: ${SERVER_PACKAGE.version}`,
+                "Agent Plan runtime diagnostics",
+                "Runtime packages (loaded package manifests):",
+                `- ${PI_ADAPTER_PACKAGE.name}: loaded ${packages[PI_ADAPTER_PACKAGE.name]?.loadedVersion ?? PI_ADAPTER_PACKAGE.version}`,
+                `- ${CORE_PACKAGE.name}: loaded ${packages[CORE_PACKAGE.name]?.loadedVersion ?? CORE_PACKAGE.version}`,
+                `- ${SERVER_PACKAGE.name}: loaded ${packages[SERVER_PACKAGE.name]?.loadedVersion ?? SERVER_PACKAGE.version}`,
+                `Plan schema: manifest schemaVersion ${capabilities.planSchema.manifestSchemaVersion}`,
+                `Allocation registry: v${capabilities.allocationRegistry.version}; supported kinds: ${capabilities.allocationRegistry.supportedKinds.join(", ")}`,
             ].join("\n"), "info");
             return;
         }
@@ -1254,12 +1361,18 @@ export default function planPiExtension(pi) {
         // ── show ──
         if (a === "show") {
             const plan = await st.loadAll();
+            const activeTasks = plan.phases.flatMap((phase) => phase.tasks
+                .filter((task) => task.status === "in-progress")
+                .map((task) => `${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}/T${pad(task.number)} — ${task.title} (in-progress)`));
             ctx.ui.notify([
                 `📋 **${plan.project.name}**`,
                 `   Description: ${plan.project.description || "*not set*"}`,
                 `   Goal: ${plan.project.goal || "*not set*"}`,
                 `   Phases: ${plan.phases.length}`,
                 `   Requirements: ${plan.requirements.requirements.length}`,
+                ...(activeTasks.length === 0
+                    ? ["   Active tasks: none (verified from all persisted phase task statuses)"]
+                    : [`   Active tasks (${activeTasks.length})${activeTasks.length > 1 ? " — CONFLICT: multiple tasks are in progress" : ""}:`, ...activeTasks.map((task) => `   - ${task}`)]),
                 `   Updated: ${plan.manifest.updatedAt}`,
             ].join("\n"), "info");
             return;
@@ -1472,7 +1585,7 @@ export default function planPiExtension(pi) {
         // ═══════════════════════════════════════════════════════════════
         if (a === "project") {
             if (!b) {
-                ctx.ui.notify("project actions: discuss | language", "info");
+                ctx.ui.notify("project actions: discuss | language | guidelines | migrate-context", "info");
                 return;
             }
             if (b === "discuss") {
@@ -1503,7 +1616,17 @@ export default function planPiExtension(pi) {
                         }))
                         : project.acceptedDecisions,
                 };
-                await st.saveProject(draftProject);
+                await st.updateProject((current) => ({
+                    ...current,
+                    goal: draftProject.goal,
+                    technologies: draftProject.technologies,
+                    tools: draftProject.tools,
+                    globalRules: draftProject.globalRules,
+                    decisions: draftProject.decisions,
+                    acceptedDecisions: draftProject.acceptedDecisions,
+                    contentLanguage: draftProject.contentLanguage,
+                    chatLanguage: draftProject.chatLanguage,
+                }));
                 await st.saveCodebaseProfile(profile);
                 await st.writeGenerated();
                 ctx.ui.notify("Initial profile saved. The agent will now take over as Lead Architect to conduct discovery.", "info");
@@ -1529,12 +1652,124 @@ export default function planPiExtension(pi) {
                 const chatLanguage = await ctx.ui.input(`Chat language [${project.chatLanguage || contentLanguage?.trim() || project.contentLanguage || "English"}]`);
                 project.contentLanguage = contentLanguage?.trim() || project.contentLanguage || "English";
                 project.chatLanguage = chatLanguage?.trim() || project.chatLanguage || project.contentLanguage || "English";
-                await st.saveProject(project);
+                await st.updateProject((current) => ({
+                    ...current,
+                    contentLanguage: project.contentLanguage,
+                    chatLanguage: project.chatLanguage,
+                }));
                 await st.writeGenerated();
                 ctx.ui.notify(`Saved language preferences: content=${project.contentLanguage}, chat=${project.chatLanguage}`, "info");
                 return;
             }
-            ctx.ui.notify(`Unknown project action "${b}". Try: discuss, language`, "warning");
+            if (b === "guidelines") {
+                const project = await st.loadProject();
+                const nextContent = await ctx.ui.editor("Project Guidelines / Coding Standard (Markdown or plain text). Agents must read this before task work.", project.projectGuidelines.content || "");
+                const guidelinesContent = nextContent?.trim() || "";
+                project.projectGuidelines = { ...project.projectGuidelines, content: guidelinesContent };
+                await st.updateProject((current) => ({
+                    ...current,
+                    projectGuidelines: { ...current.projectGuidelines, content: guidelinesContent },
+                }), { expectedGuidelinesUpdatedAt: project.projectGuidelines.updatedAt });
+                await st.writeGenerated();
+                ctx.ui.notify(project.projectGuidelines.content ? "Project Guidelines updated." : "Project Guidelines cleared.", "info");
+                return;
+            }
+            if (b === "migrate-context") {
+                const preview = await st.previewLegacyProjectContextMigration();
+                const summary = legacyContextMigrationSummary(preview);
+                if (!preview.hasLegacyContext) {
+                    ctx.ui.notify(`Project context migration preview:\n${summary}\nNo migration is needed.`, "info");
+                    return;
+                }
+                const choice = await ctx.ui.select("Apply the previewed migration? This clears only migrated legacy fields.", ["apply", "cancel"]);
+                if (choice !== "apply") {
+                    ctx.ui.notify(`Project context migration preview (no changes applied):\n${summary}`, "info");
+                    return;
+                }
+                const result = await st.migrateLegacyProjectContext();
+                await st.writeGenerated();
+                ctx.ui.notify(`${result.applied ? "Legacy project context migration applied and verified." : "No legacy project context required migration."}\n${legacyContextMigrationSummary(result.preview)}`, "info");
+                return;
+            }
+            ctx.ui.notify(`Unknown project action "${b}". Try: discuss, language, guidelines, migrate-context`, "warning");
+            return;
+        }
+        // ═══════════════════════════════════════════════════════════════
+        //  idea <sub>
+        // ═══════════════════════════════════════════════════════════════
+        if (a === "idea") {
+            if (!b) {
+                ctx.ui.notify("idea actions: list | add [title] | show [ref] | update [ref] | delete [ref] | promote [ref]", "info");
+                return;
+            }
+            const ideas = (await st.loadIdeas()).ideas;
+            if (b === "list") {
+                await paginatedNotify(ctx, {
+                    title: "ideas",
+                    lines: ideas.map((idea) => `${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}${idea.promotion ? ` → ${idea.promotion.targetRef}` : ""}`),
+                    pageSize: 10,
+                });
+                return;
+            }
+            if (b === "add") {
+                const title = subArgs.trim() || await ctx.ui.input("Idea title");
+                if (!title?.trim()) {
+                    ctx.ui.notify("Aborted", "warning");
+                    return;
+                }
+                const description = await ctx.ui.editor("Idea description", "");
+                const idea = await st.createIdea({ title: title.trim(), ...(description?.trim() ? { description: description.trim() } : {}) });
+                await st.writeGenerated();
+                ctx.ui.notify(`Idea created: ${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}`, "info");
+                return;
+            }
+            const ref = subArgs.trim() || await ctx.ui.input("Idea ref (I00x, short ID, or title)");
+            const idea = ref ? findIdeaByRef(ideas, ref) : undefined;
+            if (!idea) {
+                ctx.ui.notify(`Idea not found: ${ref || "(empty)"}`, "error");
+                return;
+            }
+            if (b === "show") {
+                ctx.ui.notify(`${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}\n\n${idea.description || "(no description)"}${idea.promotion ? `\n\nPromoted to: ${idea.promotion.targetRef}` : ""}`, "info");
+                return;
+            }
+            if (b === "update") {
+                const title = await ctx.ui.input(`Title [${idea.title}]`);
+                const description = await ctx.ui.editor("Description", idea.description);
+                const updated = await st.updateIdea(idea.id, { ...(title?.trim() ? { title: title.trim() } : {}), ...(description !== undefined ? { description: description.trim() } : {}) });
+                await st.writeGenerated();
+                ctx.ui.notify(`Idea updated: ${formatIdeaRef(updated.number)} — ${updated.title}`, "info");
+                return;
+            }
+            if (b === "delete") {
+                const answer = await ctx.ui.select(`Delete ${formatIdeaRef(idea.number)} — ${idea.title}?`, ["cancel", "delete"]);
+                if (answer !== "delete") {
+                    ctx.ui.notify("Cancelled — no changes saved.", "info");
+                    return;
+                }
+                await st.deleteIdea(idea.id);
+                await st.writeGenerated();
+                ctx.ui.notify(`Idea deleted: ${formatIdeaRef(idea.number)}.`, "info");
+                return;
+            }
+            if (b === "promote") {
+                if (idea.promotion) {
+                    ctx.ui.notify(`Already promoted to ${idea.promotion.targetRef}.`, "warning");
+                    return;
+                }
+                const targetType = await ctx.ui.select("Promotion target", ["feature", "phase", "task"]);
+                if (!targetType)
+                    return;
+                const skill = await st.ideaDiscussionSkill();
+                if (capturedPi) {
+                    await capturedPi.sendUserMessage(`Discuss promotion of ${formatIdeaRef(idea.number)} — ${idea.title} to a ${targetType}.\n\n${skill}\n\nDo not create or persist a target until the discussion is complete and I explicitly confirm the exact destination. For a phase, recommend and confirm its feature. For a task, recommend and confirm its feature and phase. After creating the confirmed target with the normal planner tool, record the promotion with idea_promotion_finalize.`);
+                }
+                else {
+                    ctx.ui.notify("Promotion discussion instructions loaded. Use the idea_promotion_begin tool in an agent session.", "info");
+                }
+                return;
+            }
+            ctx.ui.notify(`Unknown idea action "${b}". Try: list, add, show, update, delete, promote`, "warning");
             return;
         }
         // ═══════════════════════════════════════════════════════════════
@@ -1762,9 +1997,7 @@ export default function planPiExtension(pi) {
                 }
                 else {
                     for (const phase of phases) {
-                        phase.featureId = undefined;
-                        phase.updatedAt = nowISO();
-                        await st.savePhase(phase);
+                        await st.updatePhase(phase.id, (current) => ({ ...current, featureId: undefined, updatedAt: nowISO() }));
                         affectedPhases += 1;
                     }
                 }
@@ -1804,7 +2037,7 @@ export default function planPiExtension(pi) {
                 // and only then abandoning the follow-up question.
                 const startDiscuss = await ctx.ui.input("Start phase discuss now? Type yes to continue");
                 let phase;
-                await withFeatureLock(feature.id, async () => {
+                await st.runBatch(() => withFeatureLock(feature.id, async () => {
                     const phases = await st.loadAllPhases();
                     const featurePhases = phases.filter((p) => p.featureId === feature.id);
                     const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
@@ -1816,7 +2049,7 @@ export default function planPiExtension(pi) {
                         goals: [], nonGoals: [], dependencies: [], dependsOn: [], risks: [],
                         openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                         createdAt: nowISO(), updatedAt: nowISO(),
-                        handoff: "", handoffUpdatedAt: "",
+                        handoff: "", handoffUpdatedAt: "", handoffAudit: null,
                         handoffReadAt: "",
                         handoffHistory: [],
                         statusLog: [],
@@ -1832,7 +2065,7 @@ export default function planPiExtension(pi) {
                         return doc;
                     });
                     await st.writeGenerated();
-                });
+                }));
                 if (!phase)
                     return;
                 ctx.ui.notify(`Phase created: ${formatPhaseRef(phase.number, feature.number)} — ${title}${phase.shortId ? ` · ${phase.shortId}` : ""} (feature ${feature.name})`, "info");
@@ -1880,8 +2113,12 @@ export default function planPiExtension(pi) {
                 ctx.ui.notify(recapLines.join("\n"), "info");
                 const changeNote = await ctx.ui.input("Anything changed? (free text, or leave empty to keep current plan)");
                 if (changeNote?.trim()) {
-                    phase.notes = `${phase.notes ? phase.notes + "\n" : ""}[discuss ${nowISO()}] ${changeNote.trim()}`;
-                    await st.savePhase(phase);
+                    const note = changeNote.trim();
+                    phase = await st.updatePhase(phase.id, (current) => ({
+                        ...current,
+                        notes: `${current.notes ? current.notes + "\n" : ""}[discuss ${nowISO()}] ${note}`,
+                        updatedAt: nowISO(),
+                    }));
                     if (capturedPi) {
                         await capturedPi.sendUserMessage(`Before planning tasks for phase ${phase.id} (${phase.title}), the user reported a change: ${changeNote.trim()}. ` +
                             "Discuss this change with the user, update the phase scope/dependencies/risks if needed, then propose the task breakdown. " +
@@ -1903,25 +2140,22 @@ export default function planPiExtension(pi) {
                     if (ans?.trim())
                         answers[q.key] = ans.trim();
                 }
-                if (answers.goal)
-                    phase.goals = [answers.goal];
-                if (answers.summary)
-                    phase.summary = answers.summary;
-                if (answers.scope)
-                    phase.description = answers.scope;
-                if (answers.non_scope)
-                    phase.nonGoals = [answers.non_scope];
-                if (answers.deps)
-                    phase.dependencies = splitCsv(answers.deps);
-                if (answers.risks)
-                    phase.risks = splitCsv(answers.risks);
-                if (answers.completion)
-                    phase.completionCriteria = splitCsv(answers.completion);
-                phase.status = "planned";
-                phase.updatedAt = nowISO();
-                await st.savePhase(phase);
+                phase = await st.updatePhase(phase.id, (current) => ({
+                    ...current,
+                    ...(answers.goal ? { goals: [answers.goal] } : {}),
+                    ...(answers.summary ? { summary: answers.summary } : {}),
+                    ...(answers.scope ? { description: answers.scope } : {}),
+                    ...(answers.non_scope ? { nonGoals: [answers.non_scope] } : {}),
+                    ...(answers.deps ? { dependencies: splitCsv(answers.deps) } : {}),
+                    ...(answers.risks ? { risks: splitCsv(answers.risks) } : {}),
+                    ...(answers.completion ? { completionCriteria: splitCsv(answers.completion) } : {}),
+                    discussedAt: nowISO(),
+                    contextReady: true,
+                    contextReadyReason: "Updated through /planner phase discuss.",
+                    updatedAt: nowISO(),
+                }));
                 await st.writeGenerated();
-                ctx.ui.notify(`Phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))} is now **planned**.${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
+                ctx.ui.notify(`Phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))} is now **context ready**; derived status remains ${phase.status}.${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "show") {
@@ -1993,33 +2227,25 @@ export default function planPiExtension(pi) {
                 const deps = await ctx.ui.input(`Dependencies (comma-separated) [${phase.dependencies.join(", ") || ""}]`);
                 const risks = await ctx.ui.input(`Risks (comma-separated) [${phase.risks.join(", ") || ""}]`);
                 const completion = await ctx.ui.input(`Completion criteria (comma-separated) [${phase.completionCriteria.join(", ") || ""}]`);
-                // Update only changed fields
-                if (title?.trim())
-                    phase.title = title.trim();
                 if (statusInput?.trim()) {
                     const valid = ["draft", "discovery", "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
                     if (!valid.includes(statusInput.trim())) {
                         ctx.ui.notify(`Invalid status. Use: ${valid.join(", ")}`, "error");
                         return;
                     }
-                    phase.status = statusInput.trim();
                 }
-                if (summary !== undefined)
-                    phase.summary = summary;
-                if (desc?.trim())
-                    phase.description = desc.trim();
-                if (goals?.trim())
-                    phase.goals = goals.split(",").map((g) => g.trim()).filter(Boolean);
-                if (nonGoals?.trim())
-                    phase.nonGoals = nonGoals.split(",").map((g) => g.trim()).filter(Boolean);
-                if (deps?.trim())
-                    phase.dependencies = deps.split(",").map((g) => g.trim()).filter(Boolean);
-                if (risks?.trim())
-                    phase.risks = risks.split(",").map((g) => g.trim()).filter(Boolean);
-                if (completion?.trim())
-                    phase.completionCriteria = completion.split(",").map((g) => g.trim()).filter(Boolean);
-                phase.updatedAt = nowISO();
-                await st.savePhase(phase);
+                phase = await st.updatePhase(phase.id, (current) => ({
+                    ...current,
+                    ...(title?.trim() ? { title: title.trim(), slug: normalizeSlug(title) } : {}),
+                    ...(summary !== undefined ? { summary } : {}),
+                    ...(desc?.trim() ? { description: desc.trim() } : {}),
+                    ...(goals?.trim() ? { goals: splitCsv(goals) } : {}),
+                    ...(nonGoals?.trim() ? { nonGoals: splitCsv(nonGoals) } : {}),
+                    ...(deps?.trim() ? { dependencies: splitCsv(deps) } : {}),
+                    ...(risks?.trim() ? { risks: splitCsv(risks) } : {}),
+                    ...(completion?.trim() ? { completionCriteria: splitCsv(completion) } : {}),
+                    updatedAt: nowISO(),
+                }));
                 await st.writeGenerated();
                 ctx.ui.notify(`Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))} — ${phase.title} (${phase.status})${phase.shortId ? ` · ${phase.shortId}` : ""}`, "info");
                 return;
@@ -2068,12 +2294,15 @@ export default function planPiExtension(pi) {
                     dependsOn: [],
                     pauseSnapshot: null, pauseHistory: [],
                     startedAt: "", completedAt: "",
+                    activeOwnerSession: "",
                     createdAt: now, updatedAt: now,
                 };
-                phase.tasks.push(task);
-                phase.taskIds.push(taskId);
-                phase.updatedAt = nowISO();
-                await st.savePhase(phase);
+                await st.updatePhase(phase.id, (current) => ({
+                    ...current,
+                    tasks: [...current.tasks, task],
+                    taskIds: [...current.taskIds, taskId],
+                    updatedAt: nowISO(),
+                }));
                 await st.writeGenerated();
                 ctx.ui.notify(`Task created: ${taskId} — ${title}`, "info");
                 if (isYes(startDiscuss)) {
@@ -2104,18 +2333,20 @@ export default function planPiExtension(pi) {
                 const { phase, task } = resolved;
                 const description = await ctx.ui.input(`Execution notes / description [${task.description || ""}]`);
                 const checklistSeed = await ctx.ui.input("Checklist items (comma-separated, blank to keep current)");
-                if (description?.trim())
-                    task.description = description.trim();
-                if (checklistSeed?.trim()) {
-                    task.checklist = splitCsv(checklistSeed).map((itemTitle, index) => ({ number: index + 1,
+                const checklist = checklistSeed?.trim()
+                    ? splitCsv(checklistSeed).map((itemTitle, index) => ({
+                        number: index + 1,
                         id: createChecklistItemId(task.id, index + 1, itemTitle),
                         title: itemTitle,
                         checked: false,
-                    }));
-                }
-                task.updatedAt = nowISO();
-                phase.updatedAt = nowISO();
-                await st.savePhase(phase);
+                    }))
+                    : undefined;
+                await st.updateTask(phase.id, task.id, (current) => ({
+                    ...current,
+                    ...(description?.trim() ? { description: description.trim() } : {}),
+                    ...(checklist ? { checklist } : {}),
+                    updatedAt: nowISO(),
+                }));
                 await st.writeGenerated();
                 ctx.ui.notify(`Task ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} discussed and updated.`, "info");
                 return;
@@ -2181,10 +2412,12 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify("Aborted", "warning");
                     return;
                 }
-                phase.tasks = phase.tasks.filter((t) => t.id !== task.id);
-                phase.taskIds = phase.taskIds.filter((id) => id !== task.id);
-                phase.updatedAt = nowISO();
-                await st.savePhase(phase);
+                await st.updatePhase(phase.id, (current) => ({
+                    ...current,
+                    tasks: current.tasks.filter((candidate) => candidate.id !== task.id),
+                    taskIds: current.taskIds.filter((id) => id !== task.id),
+                    updatedAt: nowISO(),
+                }));
                 await st.writeGenerated();
                 ctx.ui.notify(`Task deleted: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")}${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
                 return;
@@ -2213,125 +2446,137 @@ export default function planPiExtension(pi) {
                 const title = await ctx.ui.input(`Title [${task.title}]`);
                 const statusInput = await ctx.ui.input(`Status [${task.status}] (planned|in-progress|done|blocked|canceled)`);
                 const desc = await ctx.ui.input(`Description [leave empty to keep]`);
-                // Update only changed fields
-                if (title?.trim())
-                    task.title = title.trim();
                 const now = nowISO();
-                if (statusInput?.trim()) {
-                    const normalizedStatus = statusInput.trim();
+                const normalizedStatus = statusInput?.trim();
+                if (normalizedStatus) {
                     const valid = ["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"];
                     if (!valid.includes(normalizedStatus)) {
                         ctx.ui.notify(`Invalid status. Use: ${valid.join(", ")}`, "error");
                         return;
                     }
                     if (normalizedStatus === "in-progress" && normalizedStatus !== task.status) {
-                        ctx.ui.notify("Task start/resume transitions require /planner task start so ordered full context reads and lifecycle state remain consistent.", "warning");
+                        ctx.ui.notify("Task start/resume transitions require /planner task start so lifecycle state remains consistent.", "warning");
                         return;
                     }
                     if (normalizedStatus === "done" && normalizedStatus !== task.status) {
                         ctx.ui.notify("Task completion requires /planner task complete with durable completion and verification evidence.", "warning");
                         return;
                     }
-                    applyTaskLifecycleDates(task, normalizedStatus, now);
                 }
-                if (desc?.trim())
-                    task.description = desc.trim();
-                task.updatedAt = now;
-                phase.updatedAt = now;
-                await st.savePhase(phase);
+                const result = await st.updateTask(phase.id, task.id, (current) => {
+                    const next = {
+                        ...current,
+                        ...(title?.trim() ? { title: title.trim() } : {}),
+                        ...(normalizedStatus ? { status: normalizedStatus } : {}),
+                        ...(desc?.trim() ? { description: desc.trim() } : {}),
+                        updatedAt: now,
+                    };
+                    if (normalizedStatus)
+                        applyTaskLifecycleDates(next, normalizedStatus, now);
+                    return next;
+                });
                 await st.syncTaskStatusRollup(phase.id);
                 await st.writeGenerated();
-                ctx.ui.notify(`Task updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (${task.status})${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
+                ctx.ui.notify(`Task updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(result.task.number).padStart(3, "0")} — ${result.task.title} (${result.task.status})${result.task.shortId ? ` · ${result.task.shortId}` : ""}`, "info");
                 return;
             }
             if (b === "start") {
-                let phase = null;
-                let task = null;
-                if (subArgs.trim()) {
-                    const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
-                    phase = resolved?.phase ?? null;
-                    task = resolved?.task ?? null;
-                }
-                if (!task) {
-                    phase = await pickPhase();
-                    if (!phase) {
-                        ctx.ui.notify("No phases available", "warning");
-                        return;
-                    }
-                    if (phase.tasks.length === 0) {
-                        ctx.ui.notify(`No tasks in "${phase.title}"`, "info");
-                        return;
+                return st.runBatch(async () => {
+                    let phase = null;
+                    let task = null;
+                    if (subArgs.trim()) {
+                        const resolved = findTaskByRef(await st.loadAllPhases(), (await st.loadFeatures()).features, subArgs.trim());
+                        phase = resolved?.phase ?? null;
+                        task = resolved?.task ?? null;
                     }
-                    task = await pickTask(phase);
                     if (!task) {
-                        ctx.ui.notify("Aborted", "warning");
-                        return;
+                        phase = await pickPhase();
+                        if (!phase) {
+                            ctx.ui.notify("No phases available", "warning");
+                            return;
+                        }
+                        if (phase.tasks.length === 0) {
+                            ctx.ui.notify(`No tasks in "${phase.title}"`, "info");
+                            return;
+                        }
+                        task = await pickTask(phase);
+                        if (!task) {
+                            ctx.ui.notify("Aborted", "warning");
+                            return;
+                        }
                     }
-                }
-                if (phase) {
-                    const features = (await st.loadFeatures()).features;
-                    const feature = phase.featureId ? features.find((candidate) => candidate.id === phase.featureId) : undefined;
-                    const linkedRequirements = [
-                        ...(await st.linkedRequirementsForPhase(phase.id)),
-                        ...(phase.featureId ? await st.linkedRequirementsForFeature(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: task.id,
-                        phaseId: phase.id,
-                        ...(phase.featureId ? { featureId: phase.featureId } : {}),
-                        task,
-                        phase,
-                        ...(feature ? { feature } : {}),
-                        requirements: linkedRequirements,
-                        requirementIds: linkedRequirementIds,
-                    };
-                    const contextEligibility = contextReadEligibilityForSession(contextInput);
-                    const requirementsReady = hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
-                    const phaseRef = formatPhaseRef(phase.number, featureNumberOfPhase(phase, features));
-                    const taskRef = `${phaseRef}/T${String(task.number).padStart(3, "0")}`;
-                    const featureRef = feature ? formatFeatureRef(feature.number) : "";
-                    if (!contextEligibility.eligible) {
-                        const actions = piContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, !requirementsReady, `/planner task start ${taskRef}`);
-                        ctx.ui.notify(`❌ TASK START FAILED [CONTEXT_READ_REQUIRED]\nstarted: false\n${contextEligibility.reason}\nNext required actions:\n${actions.map((action, index) => `${index + 1}. ${action}`).join("\n")}`, "error");
-                        return;
+                    if (phase) {
+                        const features = (await st.loadFeatures()).features;
+                        const feature = phase.featureId ? features.find((candidate) => candidate.id === phase.featureId) : undefined;
+                        const linkedRequirements = [
+                            ...(await st.linkedRequirementsForPhase(phase.id)),
+                            ...(phase.featureId ? await st.linkedRequirementsForFeature(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: task.id,
+                            phaseId: phase.id,
+                            ...(phase.featureId ? { featureId: phase.featureId } : {}),
+                            task,
+                            phase,
+                            ...(feature ? { feature } : {}),
+                            requirements: linkedRequirements,
+                            requirementIds: linkedRequirementIds,
+                        };
+                        const contextEligibility = contextReadEligibilityForSession(contextInput);
+                        const requirementEligibility = requirementReadEligibilityForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
+                        const requirementsReady = requirementEligibility.eligible;
+                        const project = await st.loadProject();
+                        const projectGuidelinesReadState = projectGuidelinesReadStateForSession(project, plannerSessionId);
+                        const projectGuidelinesReady = projectGuidelinesReadState === "valid" || projectGuidelinesReadState === "not-required";
+                        const phaseRef = formatPhaseRef(phase.number, featureNumberOfPhase(phase, features));
+                        const taskRef = `${phaseRef}/T${String(task.number).padStart(3, "0")}`;
+                        const featureRef = feature ? formatFeatureRef(feature.number) : "";
+                        if (!projectGuidelinesReady) {
+                            const actions = piContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, true, !requirementsReady, `/planner task start ${taskRef}`);
+                            ctx.ui.notify(`❌ TASK START FAILED [PROJECT_GUIDELINES_READ_REQUIRED]\nstarted: false\nProject Guidelines must be read before task work. Current state: ${projectGuidelinesReadState}.\nNext required actions:\n${actions.map((action, index) => `${index + 1}. ${action}`).join("\n")}`, "error");
+                            return;
+                        }
+                        if (!contextEligibility.eligible) {
+                            const actions = piContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, false, !requirementsReady, `/planner task start ${taskRef}`);
+                            ctx.ui.notify(`❌ TASK START FAILED [CONTEXT_READ_REQUIRED]\nstarted: false\n${contextEligibility.reason}\nNext required actions:\n${actions.map((action, index) => `${index + 1}. ${action}`).join("\n")}`, "error");
+                            return;
+                        }
+                        if (!requirementsReady) {
+                            ctx.ui.notify(`❌ TASK START FAILED [REQUIREMENTS_READ_REQUIRED]\nstarted: false\n${requirementEligibility.reason}\nRun requirement_list with phaseRef=${phaseRef}, then retry /planner task start. The task remains unchanged.`, "error");
+                            return;
+                        }
+                        if (!hasValidSessionAttestation(contextInput)) {
+                            await st.recordContextRead({ sessionId: plannerSessionId, phaseId: phase.id, taskId: task.id, ...(phase.featureId ? { featureId: phase.featureId } : {}), requirementIds: linkedRequirementIds });
+                        }
                     }
-                    if (!requirementsReady) {
-                        ctx.ui.notify("❌ TASK START FAILED [REQUIREMENTS_READ_REQUIRED]\nstarted: false\nRun requirement_list, then retry /planner task start. The task remains unchanged.", "error");
+                    if (task.status === "in-progress") {
+                        ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
                         return;
                     }
-                    if (!hasValidSessionAttestation(contextInput)) {
-                        await st.recordContextRead({ sessionId: plannerSessionId, phaseId: phase.id, taskId: task.id, ...(phase.featureId ? { featureId: phase.featureId } : {}), requirementIds: linkedRequirementIds });
-                    }
-                }
-                if (task.status === "in-progress") {
-                    ctx.ui.notify(`Task "${task.title}" is already in-progress.`, "info");
+                    // 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 now = nowISO();
+                    const result = await st.updateTask(phase.id, task.id, (current) => {
+                        const entry = {
+                            id: createChecklistItemId(current.id, current.statusLog.length + 1, `${current.status}-in-progress`),
+                            date: now,
+                            fromStatus: current.status,
+                            toStatus: "in-progress",
+                            title: current.status === "done" ? "Reopened" : "→ in-progress",
+                            description: current.status === "done" ? "Task reopened from done status." : "",
+                        };
+                        const next = { ...current, status: "in-progress", statusLog: [...current.statusLog, entry], updatedAt: now };
+                        applyTaskLifecycleDates(next, "in-progress", now);
+                        return next;
+                    });
+                    await st.syncTaskStatusRollup(phase.id);
+                    await st.writeGenerated();
+                    ctx.ui.notify(`✅ Task started: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(result.task.number).padStart(3, "0")} — ${result.task.title} (in-progress)${result.task.shortId ? ` · ${result.task.shortId}` : ""}`, "info");
                     return;
-                }
-                // 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 now = nowISO();
-                // Record status change in the incremental statusLog.
-                const prevStatus = task.status;
-                const entry = {
-                    id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${task.status}-in-progress`),
-                    date: now,
-                    fromStatus: task.status,
-                    toStatus: "in-progress",
-                    title: task.status === "done" ? "Reopened" : `→ in-progress`,
-                    description: task.status === "done" ? "Task reopened from done status." : "",
-                };
-                task.statusLog = [...(task.statusLog ?? []), entry];
-                applyTaskLifecycleDates(task, "in-progress", now);
-                task.updatedAt = now;
-                phase.updatedAt = now;
-                await st.savePhase(phase);
-                await st.syncTaskStatusRollup(phase.id);
-                await st.writeGenerated();
-                ctx.ui.notify(`✅ Task started: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (in-progress)${task.shortId ? ` · ${task.shortId}` : ""}`, "info");
-                return;
+                });
             }
             if (b === "complete") {
                 let phase = null;
@@ -2375,26 +2620,30 @@ export default function planPiExtension(pi) {
                     return;
                 }
                 const now = nowISO();
-                // Record status change in the incremental statusLog.
-                const entry = {
-                    id: createChecklistItemId(task.id, (task.statusLog?.length ?? 0) + 1, `${task.status}-done`),
-                    date: now,
-                    fromStatus: task.status,
-                    toStatus: "done",
-                    title: `→ done`,
-                    description: completionSummary.trim(),
-                };
-                task.statusLog = [...(task.statusLog ?? []), entry];
-                applyTaskLifecycleDates(task, "done", now);
-                const separator = task.description ? "\n\n---\n**Completion summary:**\n" : "**Completion summary:**\n";
-                task.description = `${task.description}${separator}${completionSummary.trim()}`;
-                task.descriptionUpdatedAt = now;
-                task.updatedAt = now;
-                phase.updatedAt = now;
-                await st.savePhase(phase);
+                const result = await st.updateTask(phase.id, task.id, (current) => {
+                    const entry = {
+                        id: createChecklistItemId(current.id, current.statusLog.length + 1, `${current.status}-done`),
+                        date: now,
+                        fromStatus: current.status,
+                        toStatus: "done",
+                        title: "→ done",
+                        description: completionSummary.trim(),
+                    };
+                    const separator = current.description ? "\n\n---\n**Completion summary:**\n" : "**Completion summary:**\n";
+                    const next = {
+                        ...current,
+                        status: "done",
+                        statusLog: [...current.statusLog, entry],
+                        description: `${current.description}${separator}${completionSummary.trim()}`,
+                        descriptionUpdatedAt: now,
+                        updatedAt: now,
+                    };
+                    applyTaskLifecycleDates(next, "done", now);
+                    return next;
+                });
                 const clearedRef = await st.syncTaskStatusRollup(phase.id);
                 await st.writeGenerated();
-                ctx.ui.notify(`✅ Task completed: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(task.number).padStart(3, "0")} — ${task.title} (done)${task.shortId ? ` · ${task.shortId}` : ""}${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}`, "info");
+                ctx.ui.notify(`✅ Task completed: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, (await st.loadFeatures()).features))}/T${String(result.task.number).padStart(3, "0")} — ${result.task.title} (done)${result.task.shortId ? ` · ${result.task.shortId}` : ""}${clearedRef ? ` — phase handoff archived (${clearedRef})` : ""}`, "info");
                 return;
             }
             // checklist-add <T00x> <title>  /  checklist-remove <T00x> <C{n}|title>  /  checklist-toggle <T00x> <C{n}|title> [on|off]
@@ -2500,8 +2749,15 @@ export default function planPiExtension(pi) {
                     ctx.ui.notify(r.error, "warning");
                     return;
                 }
-                const content = await st.getPhaseHandoff(r.phase.id);
-                ctx.ui.notify(content.trim() ? `Handoff ${r.compositeRef}:\n${content}` : `No handoff set on ${r.compositeRef}.`, "info");
+                const phase = await st.loadPhase(r.phase.id);
+                const content = phase.handoff;
+                const contentHash = content.trim() ? handoffContentHash(content) : "";
+                const resumeReady = Boolean(phase.handoffAudit?.resumeReadyAt)
+                    && phase.handoffAudit?.contentHash === contentHash
+                    && phase.handoffAudit?.contentLength === content.length;
+                ctx.ui.notify(content.trim()
+                    ? `Handoff ${r.compositeRef} (${resumeReady ? "resume-ready" : "verification required"}; contentHash ${contentHash}):\n${content}`
+                    : `No handoff set on ${r.compositeRef}.`, "info");
                 return;
             }
             if (action === "write") {
@@ -2516,14 +2772,16 @@ export default function planPiExtension(pi) {
                 await capturedPi.sendUserMessage("Prepare a canonical session handoff proposal. Do not write anything yet. First identify from this conversation and the latest planner lifecycle events the exact feature and phase where the decisions/work belong. Never use the first in-progress phase or a stale resume pointer as a target.\n\n" +
                     "If the last phase was just completed, do not create an operational handoff for it; its existing handoff must have been archived by the phase-done lifecycle. If another non-done phase is the real continuation, identify that phase explicitly.\n\n" +
                     "Before writing, tell the user exactly: `I propose writing this handoff on P00x(F00x) — <phase title>. Confirm?` Wait for an explicit confirmation. If the target is ambiguous, ask the user to identify the feature and phase instead of guessing.\n\n" +
-                    "After confirmation, call `handoff_prepare` with that exact phaseRef. Read the entire existing handoff and its handoffUpdatedAt token. Audit every listed done task that lacks durable completion/verification evidence. Then call `handoff_write` with the exact token, one reconciled handoff body, taskUpdates for every missing task, and either durable phase/feature updates or explicit no-update reasons. Never overwrite an existing handoff without retaining its still-relevant decisions, solved problems, architecture, files, and constraints. Replace stale focus, blockers, and next steps.\n\n" +
+                    "After confirmation, call `handoff_prepare` with that exact phaseRef. BEFORE drafting prose, use its exact returned scaffold and cold-start inventory categories. Read the entire existing handoff and its handoffUpdatedAt token. Complete every source review by checking the conversation and approvals, planner entities and sibling tasks, current diff/implementation, verification/runtime evidence, and peer-agent or network messages (or explicitly record that no peer output exists). Inventory every exact file, symbol, working-tree ownership/completion state, commit authorization, work or deletion not yet started, command/tool path, runtime call site, preservation constraint, proof observation, related planned capability, user-visible behavior, operator action, blocker/risk, remaining item, and ordered resume step known from this session. Then call `handoff_write` once with the exact token, the completed scaffold, the structured coldStartInventory, taskUpdates for every missing task, and either durable phase/feature updates or explicit no-update reasons. Every inventory item must appear verbatim in the inline handoff or a validated supporting document. Never overwrite an existing handoff without retaining its still-relevant decisions, solved problems, architecture, files, and constraints. Replace stale focus, blockers, and next steps. The write persists only a candidate and returns resumeReady=false. Immediately call `handoff_show`, read the entire persisted body, compare it again against all five sources, and either rewrite every discovered omission or call `handoff_verify` with the shown contentHash. Never tell the user the handoff is complete until verification returns resumeReady=true.\n\n" +
                     "The reconciled handoff MUST contain at minimum:\n" +
                     "- `Created at:` and `Updated at:` lines (ISO timestamps)\n" +
                     "- `Reason:` why this handoff is being written\n" +
                     "- `## Current focus`: feature, phase and task refs/titles/statuses derived from the confirmed target\n" +
-                    "- `## What was being done`: the concrete decisions/work from this session\n" +
+                    "- `## Current and partial state`: concise completed/current/partial state (extended detail goes in .planner/docs/)\n" +
+                    "- `## Preservation constraints`: minimal surviving behaviors and boundaries\n" +
+                    "- `## Supporting documents`: ordered .planner/docs/*.md links or an explicit verified none-needed statement\n" +
+                    "- `## Blockers and risks`: blockers/risks or an explicit verified none statement\n" +
                     "- `## How to resume`: explicit ordered steps\n" +
-                    "- `## Files touched`, `## Blockers`, `## Next steps`, and `## Recent decisions`\n" +
                     "Pass a meaningful title beginning with the confirmed phase ref. Generic titles are rejected. Handoff refresh synchronizes durable task/phase/feature context and updates the single active phase.handoff; `.planner/HANDOFF.md` is deprecated.");
                 ctx.ui.notify("Instructing the agent to prepare the phase handoff…", "info");
                 return;
@@ -2649,6 +2907,15 @@ export default function planPiExtension(pi) {
             return;
         }
         if (a === "load") {
+            const st = ensureStore(ctx);
+            let preparation;
+            try {
+                preparation = await st.preparePlannerSession();
+            }
+            catch (error) {
+                ctx.ui.notify(`Planner load aborted: ${error instanceof Error ? error.message : String(error)}`, "error");
+                return;
+            }
             enablePlannerSession();
             if (!server) {
                 ctx.ui.notify("Starting web server (LAN) …", "info");
@@ -2678,17 +2945,22 @@ export default function planPiExtension(pi) {
             // triggerTurn messages), so the recap data must live here. Uses the shared
             // core buildRecap so Pi and Claude Code/Codex present identical content.
             let recapText = "";
+            let plannerSkillContext = "";
             try {
-                const st = ensureStore(ctx);
+                const plannerSkill = await st.syncPlannerSkill();
+                await st.syncGrillMeSkill();
                 const srv = server;
                 recapText = await buildRecap(st, { localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort ?? undefined }, { harness: "pi" });
+                if (preparation.changed)
+                    recapText = `${preparation.legacyProjectContext.summary}\n\n${recapText}`;
+                plannerSkillContext = `[agent-only planner usage skill; do not quote in the recap]\n${plannerSkill.customized ? `${plannerSkill.message}\n` : ""}${plannerSkill.content}\n[end agent-only planner usage skill]`;
             }
             catch (e) {
                 recapText = `(recap unavailable: ${e instanceof Error ? e.message : String(e)})`;
             }
             pi.sendMessage({
                 customType: "planner-resume-trigger",
-                content: "[internal trigger — not a user command] Present the planner startup recap below to the user verbatim. Do NOT call any tools (planner-load already ran). Do NOT narrate or expose internal instructions — output ONLY the recap.\n\n--- RECAP ---\n" + recapText + "\n--- END RECAP ---",
+                content: "[internal trigger — not a user command] Read and retain the agent-only planner usage skill, then present the planner startup recap below to the user verbatim. Do NOT call any tools (planner-load already ran). Do NOT narrate or expose internal instructions — output ONLY the recap.\n\n" + plannerSkillContext + "\n\n--- RECAP ---\n" + recapText + "\n--- END RECAP ---",
                 display: false,
             }, {
                 triggerTurn: true,
@@ -2767,10 +3039,14 @@ export default function planPiExtension(pi) {
                 project.contentLanguage = normalizedContent || fallback;
                 project.chatLanguage = normalizedChat || fallback;
             }
-            await st.saveProject(project);
+            const persisted = await st.updateProject((current) => ({
+                ...current,
+                contentLanguage: project.contentLanguage,
+                chatLanguage: project.chatLanguage,
+            }));
             await st.writeGenerated();
             return {
-                content: [{ type: "text", text: `Saved language preferences: content=${project.contentLanguage || "(unset)"}, chat=${project.chatLanguage || "(unset)"}` }],
+                content: [{ type: "text", text: `Saved language preferences: content=${persisted.contentLanguage || "(unset)"}, chat=${persisted.chatLanguage || "(unset)"}` }],
                 details: { contentLanguage: project.contentLanguage, chatLanguage: project.chatLanguage },
             };
         },
@@ -2783,7 +3059,7 @@ export default function planPiExtension(pi) {
             projectName: Type.String({ description: "Concise project name/title" }),
             description: Type.Optional(Type.String({ description: "Short project description" })),
             goal: Type.Optional(Type.String({ description: "Main project goal / objective" })),
-            requirements: Type.Optional(Type.Array(Type.String(), { description: "Initial top-level requirements to seed requirements.json" })),
+            requirements: Type.Optional(Type.Array(Type.String(), { description: "Initial declarative product outcomes to seed as Requirements. Never include coding standards, best practices, formatting, verification process, or other Project Guidelines." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = loadStore(ctx);
@@ -2814,7 +3090,6 @@ export default function planPiExtension(pi) {
                         id: createRequirementId(),
                         title,
                         description: "",
-                        status: "planned",
                         macroTasks: [],
                         linkedPhaseIds: [],
                         sessionInfo: [],
@@ -2837,6 +3112,7 @@ export default function planPiExtension(pi) {
         parameters: Type.Object({
             name: Type.Optional(Type.String({ description: "Project title" })),
             description: Type.Optional(Type.String({ description: "Short project description" })),
+            descriptionRef: Type.Optional(Type.String({ description: "Optional markdown reference under .planner/docs/ for the full project description." })),
             goal: Type.Optional(Type.String({ description: "Main project goal / objective" })),
             scope: Type.Optional(Type.Array(Type.String(), { description: "Replace in-scope items" })),
             outOfScope: Type.Optional(Type.Array(Type.String(), { description: "Replace out-of-scope items" })),
@@ -2850,10 +3126,34 @@ export default function planPiExtension(pi) {
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found. Use plan_init first." }], details: {} };
             const project = await st.loadProject();
+            const mutableFields = ["name", "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: "update",
+                    mutableFields,
+                    retryCommand: "project_update with a concise description summary and the intended metadata",
+                    readBackCommand: "plan_get",
+                    descriptionFallback: {
+                        inputField: "description",
+                        storedField: "project description",
+                        descriptionRefField: "descriptionRef",
+                    },
+                });
+            }
             if (params.name !== undefined)
                 project.name = params.name.trim();
             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)
@@ -2868,37 +3168,178 @@ export default function planPiExtension(pi) {
                 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);
+            const persisted = await st.updateProject((current) => {
+                const next = {
+                    ...current,
+                    ...(params.name !== undefined ? { name: params.name.trim() } : {}),
+                    ...(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;
+            });
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Project updated: ${project.name}` }], details: project };
+            return { content: [{ type: "text", text: `Project updated: ${persisted.name}. Fields saved: ${receivedFields.join(", ")}.` }], details: { ...persisted, updated: true, updatedFields: receivedFields } };
         },
     });
     pi.registerTool({
-        name: "requirement_list",
-        label: "Requirement List",
-        description: "List all top-level requirements in requirements.json.",
+        name: "project_guidelines_show",
+        label: "Project Guidelines Show",
+        description: "Read the canonical Project Guidelines / Coding Standard section for this project. Call this when task_start or task_switch nextActions require it, and keep the guidance in working memory while doing task work.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            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 {
+                content: [{ type: "text", text: content
+                            ? [
+                                "## Project Guidelines",
+                                content,
+                            ].join("\n\n")
+                            : "No project guidelines set."
+                    }],
+                details: {
+                    projectGuidelines: refreshed.projectGuidelines,
+                    readRecorded: Boolean(content),
+                },
+            };
+        },
+    });
+    pi.registerTool({
+        name: "project_guidelines_update",
+        label: "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.",
+        parameters: Type.Object({
+            content: Type.String({ description: "Full Project Guidelines markdown/text. Pass an empty string to clear the section." }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found. Use plan_init first." }], details: {} };
+            const project = await st.loadProject();
+            await st.updateProject((current) => ({
+                ...current,
+                projectGuidelines: { ...current.projectGuidelines, content: params.content.trim() },
+            }), { expectedGuidelinesUpdatedAt: project.projectGuidelines.updatedAt });
+            await st.writeGenerated();
+            const refreshed = await st.loadProject();
+            return {
+                content: [{ type: "text", text: refreshed.projectGuidelines.content
+                            ? `Project Guidelines updated. Updated at ${refreshed.projectGuidelines.updatedAt}.`
+                            : "Project Guidelines cleared."
+                    }],
+                details: {
+                    updated: true,
+                    projectGuidelines: refreshed.projectGuidelines,
+                },
+            };
+        },
+    });
+    pi.registerTool({
+        name: "project_context_migrate",
+        label: "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.",
+        parameters: Type.Object({
+            apply: Type.Optional(Type.Boolean({ description: "False previews without mutation. True explicitly applies the previewed migration and clears only the migrated legacy fields." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found. Use plan_init first." }], details: {} };
+            const preview = await st.previewLegacyProjectContextMigration();
+            if (params.apply !== true) {
+                return {
+                    content: [{ type: "text", text: ["Project context migration preview (no changes applied).", legacyContextMigrationSummary(preview), preview.hasLegacyContext ? "Retry with apply=true to confirm." : "No migration is needed."].join("\n") }],
+                    details: { applied: false, preview },
+                };
+            }
+            const result = await st.migrateLegacyProjectContext();
+            await st.writeGenerated();
+            return {
+                content: [{ type: "text", text: [result.applied ? "Legacy project context migration applied and verified." : "No legacy project context required migration.", legacyContextMigrationSummary(result.preview)].join("\n") }],
+                details: result,
+            };
+        },
+    });
+    pi.registerTool({
+        name: "requirement_list",
+        label: "Requirement List",
+        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.",
+        parameters: Type.Object({
+            phaseRef: Type.Optional(Type.String({ description: "Optional target phase ref. When supplied, return full target-relevant requirements and record only those delivered requirements as read." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            const plannerSessionId = `pi:${ctx.sessionManager.getSessionId()}`;
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const requirements = await st.loadRequirements();
-            requirements.requirements.forEach((req) => markRequirementReadForSessionId(plannerSessionId, req.id));
+            if (!params.phaseRef?.trim()) {
+                return {
+                    content: [{ type: "text", text: requirements.requirements.map((req) => `- ${req.id} — ${req.title}`).join("\n") || "No requirements" }],
+                    details: { ...requirements, attestedRequirementIds: [], readScope: "inventory" },
+                };
+            }
+            const features = (await st.loadFeatures()).features;
+            const phase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseRef.trim());
+            if (!phase)
+                return { isError: true, content: [{ type: "text", text: `Phase not found: ${params.phaseRef}` }], details: { attestedRequirementIds: [] } };
+            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 {
-                content: [{ type: "text", text: requirements.requirements.map((req) => `- ${req.id} — ${req.title} (${req.status})`).join("\n") || "No requirements" }],
-                details: requirements,
+                content: [{ type: "text", text: body || `No requirements linked to ${targetRef}` }],
+                details: {
+                    ...requirements,
+                    requirements: delivered,
+                    attestedRequirementIds: delivered.map((requirement) => requirement.id),
+                    readScope: "target",
+                    target: { phaseId: phase.id, phaseRef: targetRef, featureId: phase.featureId },
+                },
             };
         },
     });
     pi.registerTool({
         name: "requirement_create",
         label: "Requirement Create",
-        description: "Create a new top-level requirement in requirements.json.",
+        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 project_guidelines_update instead. Requirements have no lifecycle status.",
         parameters: Type.Object({
             title: Type.String({ description: "Requirement title" }),
             description: Type.Optional(Type.String({ description: "Requirement description" })),
-            status: Type.Optional(Type.String({ description: "Initial status: planned|in-progress|done|blocked|canceled" })),
             linkedPhaseIds: Type.Optional(Type.Array(Type.String(), { description: "Optional linked phase IDs" })),
+            macroTasks: Type.Optional(Type.Array(Type.Object({
+                title: Type.String({ description: "Macro-task title" }),
+                description: Type.Optional(Type.String({ description: "Macro-task description" })),
+                status: Type.Optional(Type.String({ description: "Macro-task status" })),
+            }), { description: "Initial macro tasks. IDs and timestamps are planner-managed." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -2910,35 +3351,55 @@ export default function planPiExtension(pi) {
             const links = await resolveRequirementPhaseRefs(st, params.linkedPhaseIds);
             if (!links.ok)
                 return { content: [{ type: "text", text: links.error }], details: {} };
-            const requirements = await st.loadRequirements();
             const now = nowISO();
+            let macroTasks;
+            try {
+                macroTasks = reconcileRequirementMacroTasks([], (params.macroTasks ?? []).map((task) => ({
+                    title: task.title,
+                    ...(task.description !== undefined ? { description: task.description } : {}),
+                    status: task.status?.trim() ?? "planned",
+                })), now);
+            }
+            catch (error) {
+                const message = error instanceof RequirementMacroTaskError ? error.message : "Invalid macro tasks.";
+                return { content: [{ type: "text", text: message }], details: {} };
+            }
             const requirement = {
                 id: createRequirementId(),
                 title,
                 description: params.description?.trim() ?? "",
-                status: params.status?.trim() ?? "planned",
-                macroTasks: [],
+                macroTasks,
                 linkedPhaseIds: links.linkedPhaseIds,
                 sessionInfo: [],
                 createdAt: now,
                 updatedAt: now,
             };
-            requirements.requirements.push(requirement);
-            await st.saveRequirements(requirements);
+            try {
+                await st.updateRequirements((document) => ({ requirements: [...document.requirements, requirement] }));
+            }
+            catch (error) {
+                const message = error instanceof RequirementMacroTaskError ? error.message : error instanceof Error ? error.message : "Invalid requirement.";
+                return { content: [{ type: "text", text: message }], details: {} };
+            }
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Requirement created: ${requirement.id}` }], details: requirement };
+            return { content: [{ type: "text", text: `Requirement created: ${requirement.id}` }], details: { requirement, created: true } };
         },
     });
     pi.registerTool({
         name: "requirement_update",
         label: "Requirement Update",
-        description: "Update an existing top-level requirement.",
+        description: "Update a Requirement’s product outcome, linked phases, or ordered macro tasks. Never store coding standards, best practices, formatting, verification process, or other Project Guidelines here; use project_guidelines_update instead. Requirements have no lifecycle status.",
         parameters: Type.Object({
             requirementId: Type.String({ description: "Requirement ID" }),
             title: Type.Optional(Type.String({ description: "Requirement title" })),
             description: Type.Optional(Type.String({ description: "Requirement description" })),
-            status: Type.Optional(Type.String({ description: "Status: planned|in-progress|done|blocked|canceled" })),
             linkedPhaseIds: Type.Optional(Type.Array(Type.String(), { description: "Replace linked phase IDs" })),
+            macroTasks: Type.Optional(Type.Array(Type.Object({
+                id: Type.Optional(Type.String({ description: "Existing planner-assigned macro-task ID; omit for a new item." })),
+                title: Type.String({ description: "Macro-task title" }),
+                description: Type.Optional(Type.String({ description: "Macro-task description" })),
+                status: Type.String({ description: "Macro-task status" }),
+            }), { description: "Replace, add, remove, or reorder macro tasks. IDs/timestamps are preserved or assigned by the planner." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -2948,28 +3409,48 @@ export default function planPiExtension(pi) {
             const requirement = requirements.requirements.find((entry) => entry.id === params.requirementId);
             if (!requirement)
                 return { content: [{ type: "text", text: `Requirement not found: ${params.requirementId}` }], details: {} };
-            if (params.title !== undefined) {
-                const title = params.title.trim();
-                if (!title)
-                    return { content: [{ type: "text", text: "title required" }], details: {} };
-                requirement.title = title;
+            if (params.title !== undefined && !params.title.trim()) {
+                return { content: [{ type: "text", text: "title required" }], details: { errorCode: "TITLE_REQUIRED", updated: false } };
+            }
+            if (params.title === undefined && params.description === undefined && params.linkedPhaseIds === undefined && params.macroTasks === undefined) {
+                return mutationNoFieldsFailure({
+                    entity: "requirement",
+                    ref: params.requirementId,
+                    operation: "update",
+                    mutableFields: ["title", "description", "linkedPhaseIds", "macroTasks"],
+                    retryCommand: `requirement_update ${params.requirementId}`,
+                });
             }
-            if (params.description !== undefined)
-                requirement.description = params.description.trim();
-            if (params.status !== undefined)
-                requirement.status = params.status.trim();
-            if (params.linkedPhaseIds !== undefined) {
-                const links = await resolveRequirementPhaseRefs(st, params.linkedPhaseIds);
-                if (!links.ok)
-                    return { content: [{ type: "text", text: links.error }], details: {} };
-                requirement.linkedPhaseIds = links.linkedPhaseIds;
-            }
-            requirement.updatedAt = nowISO();
-            await st.saveRequirements(requirements);
-            await st.writeGenerated();
-            return { content: [{ type: "text", text: `Requirement updated: ${requirement.id}` }], details: requirement };
-        },
-    });
+            const links = params.linkedPhaseIds === undefined
+                ? undefined
+                : await resolveRequirementPhaseRefs(st, params.linkedPhaseIds);
+            if (links && !links.ok)
+                return { content: [{ type: "text", text: links.error }], details: { errorCode: "REQUIREMENT_PHASE_LINK_INVALID", updated: false } };
+            const now = nowISO();
+            let persisted;
+            try {
+                persisted = await st.updateRequirement(requirement.id, (canonical) => ({
+                    ...canonical,
+                    ...(params.title !== undefined ? { title: params.title.trim() } : {}),
+                    ...(params.description !== undefined ? { description: params.description.trim() } : {}),
+                    ...(links?.ok ? { linkedPhaseIds: links.linkedPhaseIds } : {}),
+                    ...(params.macroTasks !== undefined ? { macroTasks: reconcileRequirementMacroTasks(canonical.macroTasks, params.macroTasks.map((task) => ({
+                            ...(task.id ? { id: task.id } : {}),
+                            title: task.title,
+                            ...(task.description !== undefined ? { description: task.description } : {}),
+                            status: task.status.trim(),
+                        })), now) } : {}),
+                    updatedAt: now,
+                }));
+            }
+            catch (error) {
+                const message = error instanceof RequirementMacroTaskError ? error.message : "Invalid macro tasks.";
+                return { content: [{ type: "text", text: message }], details: {} };
+            }
+            await st.writeGenerated();
+            return { content: [{ type: "text", text: `Requirement updated: ${persisted.id}` }], details: { requirement: persisted, updated: true } };
+        },
+    });
     pi.registerTool({
         name: "requirement_delete",
         label: "Requirement Delete",
@@ -2981,32 +3462,134 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const requirements = await st.loadRequirements();
-            const next = requirements.requirements.filter((entry) => entry.id !== params.requirementId);
-            if (next.length === requirements.requirements.length) {
-                return { content: [{ type: "text", text: `Requirement not found: ${params.requirementId}` }], details: {} };
+            let deleted = false;
+            await st.updateRequirements((document) => {
+                const requirements = document.requirements.filter((entry) => entry.id !== params.requirementId);
+                deleted = requirements.length !== document.requirements.length;
+                return deleted ? { requirements } : document;
+            });
+            if (!deleted) {
+                return { content: [{ type: "text", text: `Requirement not found: ${params.requirementId}` }], details: { errorCode: "NOT_FOUND", deleted: false } };
             }
-            await st.saveRequirements({ requirements: next });
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Requirement deleted: ${params.requirementId}` }], details: { deleted: params.requirementId } };
+            return { content: [{ type: "text", text: `Requirement deleted: ${params.requirementId}` }], details: { deleted: true, requirementId: params.requirementId } };
+        },
+    });
+    pi.registerTool({
+        name: "idea_list", label: "Idea List", description: "List rollup-independent Ideas Inbox entries.", parameters: Type.Object({}),
+        async execute(_id, _params, _signal, _onUpdate, ctx) { const st = await requirePlan(ctx); if (!st)
+            return { content: [{ type: "text", text: "No .planner/ found." }], details: {} }; const ideas = (await st.loadIdeas()).ideas; return { content: [{ type: "text", text: ideas.map((idea) => `- ${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}${idea.promotion ? ` → ${idea.promotion.targetRef}` : ""}`).join("\n") || "No ideas" }], details: { ideas } }; },
+    });
+    pi.registerTool({
+        name: "idea_show", label: "Idea Show", description: "Show an idea by I-number, short ID, UUID, or title.", parameters: Type.Object({ idea: Type.String() }),
+        async execute(_id, params, _signal, _onUpdate, ctx) { const st = await requirePlan(ctx); if (!st)
+            return { content: [{ type: "text", text: "No .planner/ found." }], details: {} }; const idea = findIdeaByRef((await st.loadIdeas()).ideas, params.idea); return idea ? { content: [{ type: "text", text: `${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}\n\n${idea.description || "(no description)"}` }], details: { idea } } : { content: [{ type: "text", text: `Idea not found: ${params.idea}` }], details: { errorCode: "NOT_FOUND" } }; },
+    });
+    pi.registerTool({
+        name: "idea_create", label: "Idea Create", description: "Create an independent Ideas Inbox entry.", parameters: Type.Object({ title: Type.String(), description: Type.Optional(Type.String()) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) { const st = await requirePlan(ctx); if (!st)
+            return { content: [{ type: "text", text: "No .planner/ found." }], details: {} }; const idea = await st.createIdea({ title: params.title, ...(params.description !== undefined ? { description: params.description } : {}) }); await st.writeGenerated(); return { content: [{ type: "text", text: `Idea created: ${formatIdeaRef(idea.number)} · ${idea.shortId} — ${idea.title}` }], details: { idea, created: true } }; },
+    });
+    pi.registerTool({
+        name: "idea_update", label: "Idea Update", description: "Update an Ideas Inbox title or description.", parameters: Type.Object({ idea: Type.String(), title: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) { const st = await requirePlan(ctx); if (!st)
+            return { content: [{ type: "text", text: "No .planner/ found." }], details: {} }; const current = findIdeaByRef((await st.loadIdeas()).ideas, params.idea); if (!current)
+            return { content: [{ type: "text", text: `Idea not found: ${params.idea}` }], details: { errorCode: "NOT_FOUND", updated: false } }; if (params.title === undefined && params.description === undefined)
+            return mutationNoFieldsFailure({ entity: "idea", ref: params.idea, operation: "update", mutableFields: ["title", "description"], retryCommand: `idea_update ${params.idea}` }); const idea = await st.updateIdea(current.id, { ...(params.title !== undefined ? { title: params.title } : {}), ...(params.description !== undefined ? { description: params.description } : {}) }); await st.writeGenerated(); return { content: [{ type: "text", text: `Idea updated: ${formatIdeaRef(idea.number)} — ${idea.title}` }], details: { idea, updated: true } }; },
+    });
+    pi.registerTool({
+        name: "idea_delete", label: "Idea Delete", description: "Delete an Idea only after explicit user confirmation.", parameters: Type.Object({ idea: Type.String(), confirmed: Type.Boolean() }),
+        async execute(_id, params, _signal, _onUpdate, ctx) { if (!params.confirmed)
+            return { content: [{ type: "text", text: "Idea deletion requires confirmed=true after explicit user confirmation." }], details: { errorCode: "CONFIRMATION_REQUIRED", deleted: false } }; const st = await requirePlan(ctx); if (!st)
+            return { content: [{ type: "text", text: "No .planner/ found." }], details: {} }; const current = findIdeaByRef((await st.loadIdeas()).ideas, params.idea); if (!current)
+            return { content: [{ type: "text", text: `Idea not found: ${params.idea}` }], details: { errorCode: "NOT_FOUND", deleted: false } }; await st.deleteIdea(current.id); await st.writeGenerated(); return { content: [{ type: "text", text: `Idea deleted: ${formatIdeaRef(current.number)}.` }], details: { deleted: true, ideaRef: formatIdeaRef(current.number) } }; },
+    });
+    pi.registerTool({
+        name: "idea_promotion_begin", label: "Idea Promotion Begin", description: "Begin a grill-me idea promotion discussion without persisting a target or promotion.", parameters: Type.Object({ idea: Type.String(), targetType: Type.Union([Type.Literal("feature"), Type.Literal("phase"), Type.Literal("task")]) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const idea = findIdeaByRef((await st.loadIdeas()).ideas, params.idea);
+            if (!idea)
+                return { content: [{ type: "text", text: `Idea not found: ${params.idea}` }], details: { errorCode: "NOT_FOUND" } };
+            if (idea.promotion)
+                return { content: [{ type: "text", text: `${formatIdeaRef(idea.number)} is already promoted to ${idea.promotion.targetRef}.` }], details: { 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 = params.targetType === "feature"
+                ? "Create a new feature after the discussion."
+                : params.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 { content: [{ type: "text", text: `Promotion discussion started for ${formatIdeaRef(idea.number)}. ${recommendation}` }], details: { idea, targetType: params.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 using feature_create, phase_create, or task_create.", "Call idea_promotion_finalize with discussionCompleted=true and confirmed=true."] } };
         },
     });
+    pi.registerTool({
+        name: "idea_promotion_finalize", label: "Idea Promotion Finalize", description: "Record an idea promotion after grill-me discussion, explicit confirmation, and successful normal target creation.", parameters: Type.Object({ idea: Type.String(), targetType: Type.Union([Type.Literal("feature"), Type.Literal("phase"), Type.Literal("task")]), targetRef: Type.String(), discussionCompleted: Type.Boolean(), confirmed: Type.Boolean() }),
+        async execute(_id, params, _signal, _onUpdate, ctx) { if (!params.discussionCompleted || !params.confirmed)
+            return { content: [{ type: "text", text: "Promotion requires discussionCompleted=true and confirmed=true; no promotion was persisted." }], details: { errorCode: "IDEA_PROMOTION_CONFIRMATION_REQUIRED", promoted: false } }; const st = await requirePlan(ctx); if (!st)
+            return { content: [{ type: "text", text: "No .planner/ found." }], details: {} }; const idea = findIdeaByRef((await st.loadIdeas()).ideas, params.idea); if (!idea)
+            return { content: [{ type: "text", text: `Idea not found: ${params.idea}` }], details: { errorCode: "NOT_FOUND", promoted: false } }; const features = (await st.loadFeatures()).features; const phases = await st.loadAllPhases(); let target; if (params.targetType === "feature") {
+            const resolved = resolveFeatureRefStrict(features, params.targetRef);
+            target = resolved.ok ? { id: resolved.feature.id } : undefined;
+        }
+        else if (params.targetType === "phase") {
+            const phase = findPhaseByRef(phases, features, params.targetRef);
+            target = phase ? { id: phase.id } : undefined;
+        }
+        else {
+            const found = findTaskByRef(phases, features, params.targetRef);
+            target = found ? { id: found.task.id } : undefined;
+        } if (!target)
+            return { content: [{ type: "text", text: `Confirmed ${params.targetType} target not found: ${params.targetRef}; no promotion was persisted.` }], details: { errorCode: "TARGET_NOT_FOUND", promoted: false } }; const promoted = await st.promoteIdea(idea.id, { targetType: params.targetType, targetId: target.id }); await st.writeGenerated(); return { content: [{ type: "text", text: `Idea promoted: ${formatIdeaRef(promoted.number)} → ${promoted.promotion.targetRef}` }], details: { idea: promoted, promoted: true, targetRef: promoted.promotion.targetRef } }; },
+    });
     pi.registerTool({
         name: "plan_get",
         label: "Plan Get",
-        description: "Read the full plan: manifest, project, features, phases (with their tasks), and requirements. Call this first to understand current state before planning work.",
+        description: "Read the full plan plus explicit active-task evidence: manifest, project (including Accepted Decisions), features, phases (with their tasks), requirements, activeTaskState, and activeTasks. Never infer that no task is active from counts or omitted detail.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found. Use plan_init first." }], details: {} };
             const plan = await st.loadAll();
+            const activeTasks = plan.phases.flatMap((phase) => phase.tasks
+                .filter((task) => task.status === "in-progress")
+                .map((task) => ({
+                id: task.id,
+                ref: `${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}/T${pad(task.number)}`,
+                title: task.title,
+                status: task.status,
+            })));
+            const activeTaskEvidence = activeTasks.length === 0
+                ? "Active tasks: none (verified from all persisted phase task statuses)"
+                : `Active tasks (${activeTasks.length})${activeTasks.length > 1 ? " — CONFLICT" : ""}: ${activeTasks.map((task) => `${task.ref} — ${task.title}`).join("; ")}`;
+            const projectDecisionContext = buildBoundedAcceptedDecisionContext([{ scope: "project", decisions: plan.project.acceptedDecisions }]);
             return {
-                content: [{ type: "text", text: `Plan "${plan.project.name}": ${plan.features.features.length} features, ${plan.phases.length} phases, ${plan.requirements.requirements.length} requirements` }],
-                details: plan,
+                content: [{ type: "text", text: `Plan "${plan.project.name}": ${plan.features.features.length} features, ${plan.phases.length} phases, ${plan.requirements.requirements.length} requirements. ${activeTaskEvidence}\n${projectDecisionContext.content}` }],
+                details: { ...plan, activeTaskState: activeTasks.length === 0 ? "none" : activeTasks.length === 1 ? "single" : "conflict", activeTasks },
             };
         },
     });
+    pi.registerTool({
+        name: "description_freshness",
+        label: "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.",
+        parameters: Type.Object({}),
+        async execute(_id, _params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const freshness = await st.previewDescriptionReconciliation();
+            if (!freshness.reconciliationRequired)
+                return { content: [{ type: "text", text: "Description hierarchy is fresh; no parent reconciliation is required." }], details: freshness };
+            const lines = freshness.reconciliationPreview.map((step) => `- ${step.ownerRef} after ${step.causedByRef}: ${step.action}`);
+            return { content: [{ type: "text", text: `Parent description reconciliation required (${freshness.staleParentRefs.length}):\n${lines.join("\n")}` }], details: freshness };
+        },
+    });
     pi.registerTool({
         name: "plan_render",
         label: "Plan Render",
@@ -3089,9 +3672,11 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const list = await st.listHandoffs();
             if (list.length === 0)
-                return { content: [{ type: "text", text: "⚠️ plan_get_handoff is deprecated — no phase handoffs set. Use handoff_list / handoff_show (entity-scoped, phase.handoff field)." }], details: { deprecated: true, count: 0 } };
-            const lines = list.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`);
-            return { content: [{ type: "text", text: `⚠️ plan_get_handoff is deprecated — use handoff_list / handoff_show. Phase handoffs (${list.length}):\n${lines.join("\n")}` }], details: { deprecated: true, count: list.length, handoffs: list } };
+                return { content: [{ type: "text", text: "⚠️ plan_get_handoff is deprecated — no phase handoffs set. Use handoff_list / handoff_show (entity-scoped, phase.handoff field)." }], details: { deprecated: true, count: 0, total: 0, page: 1, totalPages: 1, handoffs: [] } };
+            const result = boundedPage(list, 1, 10);
+            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 { content: [{ type: "text", text: `⚠️ plan_get_handoff is deprecated — use handoff_list / handoff_show. Page 1/${pageInfo.totalPages} (${pageInfo.total} total):\n${lines.join("\n")}` }], details: { deprecated: true, count: items.length, ...pageInfo, handoffs: items } };
         },
     });
     pi.registerTool({
@@ -3182,23 +3767,28 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_list",
         label: "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.",
-        parameters: Type.Object({}),
-        async execute(_id, _params, _signal, _onUpdate, ctx) {
+        description: "List phases with active entity-scoped handoffs as compact summary-only pages. Full bodies are never embedded; call handoff_show for one exact phase.",
+        parameters: Type.Object({
+            page: Type.Optional(Type.Integer({ minimum: 1, description: "1-based page number (default 1)." })),
+            pageSize: Type.Optional(Type.Integer({ minimum: 1, maximum: 25, description: "Summaries per page (default 10, maximum 25)." })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const list = await st.listHandoffs();
             if (list.length === 0)
-                return { content: [{ type: "text", text: "No phase handoffs set." }], details: { count: 0 } };
-            const lines = list.map((e) => `- ${e.compositeRef} — ${e.firstLine} (updated ${e.updatedAt})`);
-            return { content: [{ type: "text", text: `Phase handoffs (${list.length}):\n${lines.join("\n")}` }], details: { count: list.length, handoffs: list } };
+                return { content: [{ type: "text", text: "No phase handoffs set." }], details: { count: 0, total: 0, page: 1, totalPages: 1, handoffs: [] } };
+            const result = boundedPage(list, params.page ?? 1, params.pageSize ?? 10);
+            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 { content: [{ type: "text", text: `Phase handoffs — page ${pageInfo.page}/${pageInfo.totalPages} (${pageInfo.total} total):\n${lines.join("\n")}` }], details: { count: items.length, ...pageInfo, handoffs: items } };
         },
     });
     pi.registerTool({
         name: "handoff_show",
         label: "Handoff Show",
-        description: "Read the entity-scoped handoff of a phase. phaseRef is required and accepts P00x, P00x(F00x), UUID, or title. Never infer a phase automatically.",
+        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 and accepts P00x, P00x(F00x), UUID, or title. Never infer a phase automatically.",
         parameters: Type.Object({ phaseRef: Type.String({ description: "Exact phase ref: P00x | P00x(F00x) | UUID | title. Ask the user when the target is ambiguous." }) }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3207,16 +3797,100 @@ export default function planPiExtension(pi) {
             const r = await resolvePhaseForHandoff(st, params.phaseRef);
             if (!r.ok)
                 return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
-            const content = await st.getPhaseHandoff(r.phase.id);
-            if (!content.trim())
-                return { content: [{ type: "text", text: `No handoff set on ${r.compositeRef}.` }], details: { phaseRef: r.compositeRef, empty: true } };
-            return { content: [{ type: "text", text: `Handoff for ${r.compositeRef}:\n\n${content}` }], details: { 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 {
+                        content: [{ type: "text", text: [
+                                    `Archived terminal-phase handoff for ${r.compositeRef} (${archived.reason}; archived ${archived.archivedAt})`,
+                                    ...(documentLines.length ? ["Supporting documents:", ...documentLines] : []),
+                                    "",
+                                    archivedContent.content,
+                                ].join("\n") }],
+                        details: {
+                            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 { content: [{ type: "text", text: `No handoff set on ${r.compositeRef}.` }], details: { 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 handoff_verify with its contentHash and a fresh comparison against every required source. If any gap exists, rewrite instead of verifying.";
+            return {
+                content: [{ type: "text", 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}` }],
+                details: { phaseRef: r.compositeRef, phaseId: r.phase.id, phaseWorkMap, ...bounded, contentHash, persistenceVerified, resumeReady, verificationRequired: !resumeReady, handoffAudit: phase.handoffAudit },
+            };
+        },
+    });
+    pi.registerTool({
+        name: "handoff_verify",
+        label: "Handoff Verify",
+        description: "Finalize one persisted handoff as resume-ready only after 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.",
+        parameters: Type.Object({
+            phaseRef: Type.String(),
+            expectedContentHash: Type.String({ pattern: "^[a-f0-9]{64}$" }),
+            sourceReviews: Type.Array(Type.Object({
+                source: Type.Union([Type.Literal("conversation"), Type.Literal("planner-entities"), Type.Literal("working-tree"), Type.Literal("verification-runtime"), Type.Literal("peer-agent-output")]),
+                detail: Type.String({ minLength: 12 }),
+            })),
+            omissionsFound: Type.Array(Type.String({ minLength: 1 })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const r = await resolvePhaseForHandoff(st, params.phaseRef);
+            if (!r.ok)
+                return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { resumeReady: false, error: r.error } };
+            try {
+                const result = await st.verifyPhaseHandoffReadBack(r.phase.id, {
+                    expectedContentHash: params.expectedContentHash,
+                    sourceReviews: params.sourceReviews,
+                    omissionsFound: params.omissionsFound,
+                });
+                await st.writeGenerated();
+                return {
+                    content: [{ type: "text", text: `✅ Handoff on ${r.compositeRef} is resume-ready after persisted read-back and source reconciliation.` }],
+                    details: { 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 { isError: true, content: [{ type: "text", text: `❌ Handoff read-back verification denied: ${message}` }], details: { resumeReady: false, error: message } };
+            }
         },
     });
     pi.registerTool({
         name: "handoff_prepare",
         label: "Handoff Prepare",
-        description: "Audit one exact phase before writing a handoff. Returns the current handoff/version and every done task missing durable completion or verification evidence. Call after the user confirms the target, then reconcile the returned context through handoff_write.",
+        description: "Audit one exact phase before writing a handoff. Returns the canonical scaffold, a bounded priority-ordered phase work map with sibling goals/dependencies/capability ownership, the current token, missing task evidence, required audits, and the 24,000-character inline budget. Reread the canonical phase and relevant sibling tasks before proposing work; reconcile everything through handoff_write.",
         parameters: Type.Object({ phaseRef: Type.String({ description: "Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title." }) }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3227,19 +3901,36 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: `❌ ${r.error}` }], details: { error: r.error } };
             try {
                 const audit = await st.preparePhaseHandoff(r.phase.id);
+                const { handoff, ...auditDetails } = audit;
+                const boundedExisting = boundedHandoffForTransport(handoff);
                 const missing = audit.missingCompletionTasks.map((task) => `- T${String(task.number).padStart(3, "0")} — ${task.title}`).join("\n") || "- None";
-                const existing = audit.handoff.trim() || "(none)";
+                const existing = boundedExisting.content.trim() || "(none)";
                 return {
                     content: [{ type: "text", 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):",
                                 existing,
                             ].join("\n") }],
-                    details: { phaseRef: r.compositeRef, ...audit },
+                    details: { phaseRef: r.compositeRef, ...auditDetails, existingHandoffLength: boundedExisting.fullLength, existingHandoffTruncated: boundedExisting.truncated },
                 };
             }
             catch (error) {
@@ -3251,15 +3942,40 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "handoff_write",
         label: "Handoff Write",
-        description: "Reconcile and refresh the single active phase handoff while synchronizing durable task, phase, and feature context. Run handoff_prepare first and pass its exact handoffUpdatedAt token. Existing context must be reconciled; refreshes do not create superseded archives.",
+        description: "Persist a reconciled handoff candidate with durable context synchronization and mandatory audits. The result always has resumeReady=false until a separate handoff_show read-back and handoff_verify source reconciliation succeeds. Run handoff_prepare first; extended detail belongs in linked .planner/docs/ Markdown.",
         parameters: Type.Object({
             phaseRef: Type.String({ description: "Exact confirmed phase ref: P00x | P00x(F00x) | UUID | title." }),
             title: Type.Optional(Type.String({ description: "Meaningful handoff title summarizing the work (becomes the H1 / first line in lists)." })),
+            reason: Type.Optional(Type.String({ description: "Why work is stopping and why a cold agent needs this handoff. Required for confirmed writes; rendered by the planner, not in Markdown." })),
             confirmed: Type.Boolean({ description: "Set true only after the user explicitly confirms the proposed feature+phase target." }),
             content: Type.Optional(Type.String({ description: "Handoff text (plain)." })),
             markdown_content: Type.Optional(Type.String({ description: "Handoff text (markdown). Preferred over content." })),
             expectedHandoffUpdatedAt: Type.Optional(Type.String({ description: "Exact handoffUpdatedAt returned by handoff_prepare; use an empty string when no handoff exists." })),
             reconciledExistingHandoff: Type.Optional(Type.Boolean({ description: "Confirm that all still-relevant information from the existing handoff was retained in this single refreshed body." })),
+            completenessAudit: Type.Optional(Type.Object({
+                version: Type.Literal(HANDOFF_COMPLETENESS_AUDIT_VERSION),
+                entries: Type.Array(Type.Object({
+                    category: Type.String({ description: `One required category id from handoff_prepare: ${HANDOFF_COMPLETENESS_CATEGORIES.map((entry) => entry.id).join(", ")}` }),
+                    status: Type.Union([Type.Literal("captured"), Type.Literal("not-applicable")]),
+                    detail: Type.String({ description: "Substantive captured detail or a substantive reason why the category is not applicable." }),
+                })),
+            })),
+            coldStartInventory: Type.Optional(Type.Object({
+                version: Type.Literal(HANDOFF_COLD_START_INVENTORY_VERSION),
+                sourceReviews: Type.Array(Type.Object({
+                    source: Type.String({ description: `One required source review id: ${HANDOFF_COLD_START_SOURCE_REVIEWS.map((entry) => entry.id).join(", ")}` }),
+                    detail: Type.String({ description: "Substantive summary of what was reviewed and which facts were extracted before drafting." }),
+                })),
+                entries: Type.Array(Type.Object({
+                    category: Type.String({ description: `One required cold-start category id from handoff_prepare: ${HANDOFF_COLD_START_INVENTORY_CATEGORIES.map((entry) => entry.id).join(", ")}` }),
+                    items: Type.Array(Type.String({ description: "Exact resume-critical item; it must appear verbatim in the handoff or a validated supporting document." })),
+                    notApplicableReason: Type.Optional(Type.String({ description: "Optional explanation only; every category still requires a concrete item, using an explicit verified-negative statement when nothing exists." })),
+                })),
+            })),
+            supportingDocuments: Type.Optional(Type.Array(Type.Object({
+                path: Type.String({ description: "Committed Markdown path under .planner/docs/." }),
+                description: Type.String({ description: "What the document contains and why the next agent needs it." }),
+            }))),
             taskUpdates: Type.Optional(Type.Array(Type.Object({
                 taskRef: Type.String(),
                 completionSummary: Type.String(),
@@ -3306,7 +4022,9 @@ export default function planPiExtension(pi) {
             if (!params.confirmed)
                 return { content: [{ type: "text", text: `Proposal only: I would refresh this handoff on ${r.compositeRef}. Ask the user to confirm, then run handoff_prepare and retry with confirmed=true.` }], details: { phaseRef: r.compositeRef, confirmationRequired: true } };
             if (params.expectedHandoffUpdatedAt === undefined)
-                return { content: [{ type: "text", text: "❌ Run handoff_prepare first and pass expectedHandoffUpdatedAt." }], details: { error: "preparation required" } };
+                return { isError: true, content: [{ type: "text", text: "❌ Handoff refresh denied [HANDOFF_PREFLIGHT_REQUIRED]: Run handoff_prepare first and pass expectedHandoffUpdatedAt." }], details: { errorCode: "HANDOFF_PREFLIGHT_REQUIRED", persisted: false } };
+            if (!params.reason?.trim())
+                return { isError: true, content: [{ type: "text", text: "❌ Handoff refresh denied [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." }], details: { errorCode: "HANDOFF_REASON_REQUIRED", persisted: false, requiredInputs: ["title", "reason"], generatedMetadata: ["Created at", "Updated at"] } };
             const phases = await st.loadAllPhases();
             const features = (await st.loadFeatures()).features;
             const taskUpdates = [];
@@ -3325,9 +4043,13 @@ export default function planPiExtension(pi) {
             }
             try {
                 const result = await st.refreshPhaseHandoff(r.phase.id, {
+                    reason: params.reason.trim(),
                     content: body,
                     expectedHandoffUpdatedAt: params.expectedHandoffUpdatedAt,
                     reconciledExistingHandoff: params.reconciledExistingHandoff === true,
+                    ...(params.completenessAudit ? { completenessAudit: params.completenessAudit } : {}),
+                    ...(params.coldStartInventory ? { coldStartInventory: params.coldStartInventory } : {}),
+                    ...(params.supportingDocuments ? { supportingDocuments: params.supportingDocuments } : {}),
                     contextSync: {
                         taskUpdates,
                         ...(params.phaseUpdate ? { phaseUpdate: {
@@ -3341,9 +4063,28 @@ export default function planPiExtension(pi) {
                     },
                 });
                 await st.writeGenerated();
-                return { content: [{ type: "text", text: `✅ Reconciled handoff and durable context on ${r.compositeRef}; updated ${result.updatedTaskIds.length} task(s).` }], details: { phaseRef: r.compositeRef, phaseId: r.phase.id, ...result } };
+                return {
+                    content: [{ type: "text", text: `⚠️ Handoff candidate persisted on ${r.compositeRef}, but it is NOT resume-ready yet. Required next action: call handoff_show ${r.compositeRef}, read the entire persisted body, compare it again with every required source, then call handoff_verify with the returned contentHash. If that review finds any gap, run prepare+write again instead of verifying.` }],
+                    details: {
+                        phaseRef: r.compositeRef,
+                        phaseId: r.phase.id,
+                        updatedTaskIds: result.updatedTaskIds,
+                        handoffUpdatedAt: result.handoffUpdatedAt,
+                        handoffAudit: result.handoffAudit,
+                        persisted: true,
+                        resumeReady: false,
+                        verificationRequired: true,
+                        nextActions: [
+                            `Call 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 handoff_prepare and handoff_write again; otherwise call 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 { content: [{ type: "text", text: `❌ Handoff refresh denied: ${message}` }], details: { error: message } };
             }
@@ -3398,7 +4139,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "feature_list",
         label: "Feature List",
-        description: "List features (compact: F00x · shortId — name (status; N phases, M tasks)). Use this to discover refs cheaply — do NOT read .planner/ files or plan_get full=true to find entities.",
+        description: "List features (compact: F00x · shortId — name (status; priority N; N phases, M tasks)). Use this to discover refs cheaply — do NOT read .planner/ files or plan_get full=true to find entities.",
         parameters: Type.Object({ featureRef: Type.Optional(Type.String({ description: "Optional: filter to one feature (F00x/shortId/UUID/name)" })) }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3411,7 +4152,7 @@ export default function planPiExtension(pi) {
             const phases = await st.loadAllPhases();
             const summary = features.map((f) => {
                 const fp = phases.filter((p) => p.featureId === f.id);
-                return `- ${formatFeatureRef(f.number)}${f.shortId ? ` · ${f.shortId}` : ""} — ${f.name} (${f.status}; ${fp.length} phases, ${fp.reduce((t, p) => t + p.tasks.length, 0)} tasks)`;
+                return `- ${formatFeatureRef(f.number)}${f.shortId ? ` · ${f.shortId}` : ""} — ${f.name} (${f.status}${f.priority > 0 ? `; priority ${f.priority}` : ""}; ${fp.length} phases, ${fp.reduce((t, p) => t + p.tasks.length, 0)} tasks)`;
             }).join("\n");
             return { content: [{ type: "text", text: summary || "No features" }], details: {} };
         },
@@ -3419,13 +4160,14 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "feature_get",
         label: "Feature Get",
-        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description and derived linked requirements.",
+        description: "Show a feature. Compact identity by default (saves tokens); pass full=true to include the description, every canonical Accepted Decision field, and derived linked requirements.",
         parameters: Type.Object({
             featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
             full: Type.Optional(Type.Boolean({ description: "If true, include the feature description. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
+            const plannerSessionId = `pi:${ctx.sessionManager.getSessionId()}`;
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const features = (await st.loadFeatures()).features;
@@ -3434,15 +4176,30 @@ export default function planPiExtension(pi) {
             if (!resolvedFeature.ok)
                 return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
             const feature = resolvedFeature.feature;
-            if (params.full)
-                markFeatureReadForSessionId(plannerSessionId, feature.id);
             const phases = (await st.loadAllPhases()).filter((p) => p.featureId === feature.id);
             const linkedRequirements = await st.linkedRequirementsForFeature(feature.id);
             const summary = `${feature.name} — ${formatFeatureRef(feature.number)}${feature.shortId ? ` · ${feature.shortId}` : ""} (${feature.status}; ${phases.length} phases${linkedRequirements.length ? `; ${linkedRequirements.length} linked requirement${linkedRequirements.length === 1 ? "" : "s"}` : ""})`;
+            const descriptionRefBlock = feature.descriptionRef ? `\n\nDescription reference:\n- ${feature.descriptionRef}` : "";
             const requirementsBlock = linkedRequirements.length > 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")}`
                 : "\n\nLinked requirements:\n- None linked to this feature.";
-            return { content: [{ type: "text", text: params.full ? `${summary}\n\n${feature.description || ""}${requirementsBlock}` : summary }], details: { linkedRequirements } };
+            if (!params.full)
+                return { content: [{ type: "text", text: summary }], details: { linkedRequirements } };
+            const decisionBlock = renderAcceptedDecisionsSection("Accepted Decisions", feature.acceptedDecisions);
+            const result = {
+                content: [{ type: "text", text: `${summary}\n\n${feature.description || ""}${descriptionRefBlock}${requirementsBlock}\n\n${decisionBlock}` }],
+                details: {
+                    feature: {
+                        ref: formatFeatureRef(feature.number),
+                        description: feature.description,
+                        descriptionRef: feature.descriptionRef ?? "",
+                        acceptedDecisions: feature.acceptedDecisions,
+                    },
+                    linkedRequirements,
+                },
+            };
+            markCanonicalFullReadForSessionId(plannerSessionId, "feature", feature, result.content[0].text);
+            return result;
         },
     });
     pi.registerTool({
@@ -3458,44 +4215,46 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            const now = nowISO();
-            const status = params.status ?? "planned";
-            const currentFeatures = (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: params.name,
-                description: params.description ?? "",
-                descriptionUpdatedAt: now,
-                status,
-                discussedAt: "",
-                contextReady: false,
-                contextReadyReason: "",
-                startDate: status === "in-progress" ? new Date().toISOString().slice(0, 10) : "",
-                endDate: "",
-                workDone: "",
-                workRemaining: "",
-                acceptedDecisions: [],
-                phaseIds: [],
-                dependsOn: [],
-                statusLog: [],
-                sessionInfo: [],
-                createdAt: now,
-                updatedAt: now,
-            };
-            // Atomic read-modify-write: serializes concurrent feature_create calls
-            // (batch) so they don't overwrite each other (last-write-wins race).
-            await st.updateFeatures((doc) => {
-                doc.features.push(feature);
-                return doc;
+            return st.runBatch(async () => {
+                const now = nowISO();
+                const status = params.status ?? "planned";
+                const currentFeatures = (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: params.name,
+                    description: params.description ?? "",
+                    descriptionUpdatedAt: now,
+                    status,
+                    discussedAt: "",
+                    contextReady: false,
+                    contextReadyReason: "",
+                    startDate: status === "in-progress" ? new Date().toISOString().slice(0, 10) : "",
+                    endDate: "",
+                    workDone: "",
+                    workRemaining: "",
+                    acceptedDecisions: [],
+                    phaseIds: [],
+                    dependsOn: [],
+                    statusLog: [],
+                    sessionInfo: [],
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                // Atomic read-modify-write: serializes concurrent feature_create calls
+                // (batch) so they don't overwrite each other (last-write-wins race).
+                await st.updateFeatures((doc) => {
+                    doc.features.push(feature);
+                    return doc;
+                });
+                await st.writeGenerated();
+                return { content: [{ type: "text", text: `✅ Feature created: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
             });
-            await st.writeGenerated();
-            return { content: [{ type: "text", text: `✅ Feature created: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
         },
     });
     pi.registerTool({
@@ -3505,6 +4264,7 @@ export default function planPiExtension(pi) {
         parameters: Type.Object({
             featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
             description: Type.Optional(Type.String({ description: "Current implementation state, scope, and goals for this feature" })),
+            descriptionRef: Type.Optional(Type.String({ description: "Optional markdown reference under .planner/docs/ for the full feature description." })),
             workDone: Type.Optional(Type.String({ description: "What is already implemented / decided" })),
             workRemaining: Type.Optional(Type.String({ description: "What still needs to be done" })),
             dependencies: Type.Optional(Type.Array(Type.String(), { description: "Cross-feature or external dependencies" })),
@@ -3518,16 +4278,41 @@ export default function planPiExtension(pi) {
             if (!resolvedFeature.ok)
                 return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
             const featureId = resolvedFeature.feature.id;
+            const mutableFields = ["description", "descriptionRef", "workDone", "workRemaining", "dependencies"];
+            const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+            if (receivedFields.length === 0) {
+                return mutationNoFieldsFailure({
+                    entity: "feature",
+                    ref: formatFeatureRef(resolvedFeature.feature.number),
+                    operation: "discuss",
+                    mutableFields,
+                    retryCommand: `feature_discuss ${formatFeatureRef(resolvedFeature.feature.number)}`,
+                    readBackCommand: `feature_get ${formatFeatureRef(resolvedFeature.feature.number)} with full=true`,
+                    descriptionFallback: {
+                        entityId: featureId,
+                        inputField: "description",
+                        storedField: "feature description",
+                        descriptionRefField: "descriptionRef",
+                    },
+                });
+            }
             const updatedDoc = await st.updateFeatures((doc) => {
                 const feature = doc.features.find((f) => f.id === featureId);
                 if (!feature)
                     return doc;
                 if (params.description !== undefined)
-                    feature.description = params.description;
+                    feature.description = params.description.trim();
+                if (params.descriptionRef !== undefined) {
+                    const descriptionRef = normalizeDescriptionRef(params.descriptionRef);
+                    if (descriptionRef)
+                        feature.descriptionRef = descriptionRef;
+                    else
+                        delete feature.descriptionRef;
+                }
                 if (params.workDone !== undefined)
-                    feature.workDone = params.workDone;
+                    feature.workDone = params.workDone.trim();
                 if (params.workRemaining !== undefined)
-                    feature.workRemaining = params.workRemaining;
+                    feature.workRemaining = params.workRemaining.trim();
                 if (params.dependencies !== undefined)
                     feature.dependsOn = params.dependencies.map((item) => item.trim()).filter(Boolean);
                 feature.discussedAt = nowISO();
@@ -3540,18 +4325,19 @@ export default function planPiExtension(pi) {
             if (!feature)
                 return { content: [{ type: "text", text: `Feature not found: ${params.featureId}` }], details: {} };
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `✅ Feature discussed/updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}` }], details: feature };
+            return { content: [{ type: "text", text: `✅ Feature discussed/updated: ${formatFeatureRef(feature.number)} — ${feature.name}${feature.shortId ? ` · ${feature.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.` }], details: { ...feature, discussed: true, updatedFields: receivedFields } };
         },
     });
     pi.registerTool({
         name: "feature_update",
         label: "Feature Update",
-        description: "Update one or more fields of a feature. Only provided fields are changed. IMPORTANT: feature status is derived from child phases/tasks, so do not update feature.status directly unless truly necessary.",
+        description: "Update one or more canonical feature fields. Feature status is derived from child phases/tasks and cannot be changed directly.",
         parameters: Type.Object({
             featureId: Type.String({ description: "Feature ref: F00x, shortId, UUID, or name" }),
             name: Type.Optional(Type.String({ description: "New name" })),
             description: Type.Optional(Type.String({ description: "New description" })),
-            status: Type.Optional(Type.String({ description: "New status: planned|in-progress|done|blocked|canceled. Avoid setting this directly unless you truly need an override: feature status is derived from child phases/tasks." })),
+            descriptionRef: Type.Optional(Type.String({ description: "Optional markdown reference under .planner/docs/ for the full feature description." })),
+            status: Type.Optional(Type.String({ description: "Deprecated compatibility field. Feature status is derived from child phases/tasks; supplying this field returns DERIVED_STATUS_READ_ONLY." })),
             startDate: Type.Optional(Type.String({ description: "Start date (YYYY-MM-DD)" })),
             endDate: Type.Optional(Type.String({ description: "End date (YYYY-MM-DD)" })),
             workDone: Type.Optional(Type.String({ description: "Notes on work done" })),
@@ -3564,7 +4350,7 @@ export default function planPiExtension(pi) {
                 rationale: Type.String(),
                 implementationNotes: Type.String(),
                 acceptedAt: Type.String(),
-            }), { description: "Replace accepted decisions list" })),
+            }), { description: "Deprecated compatibility field. Raw replacement is rejected; use accepted_decision_create, accepted_decision_update, or accepted_decision_delete." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -3578,25 +4364,39 @@ export default function planPiExtension(pi) {
             if (params.status !== undefined) {
                 return derivedStatusReadOnlyResult("feature", formatFeatureRef(resolvedFeature.feature.number), String(params.status), resolvedFeature.feature.status);
             }
+            if (params.acceptedDecisions !== undefined) {
+                return {
+                    content: [{ type: "text", text: "Raw acceptedDecisions replacement is disabled. Use accepted_decision_create, accepted_decision_update, or accepted_decision_delete so IDs and acceptedAt are preserved." }],
+                    details: { updated: false, errorCode: "ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED", targetType: "feature", targetRef: formatFeatureRef(resolvedFeature.feature.number) },
+                    isError: true,
+                };
+            }
             const mutableFields = [
                 "name",
                 "description",
+                "descriptionRef",
                 "startDate",
                 "endDate",
                 "workDone",
                 "workRemaining",
                 "priority",
-                "acceptedDecisions",
             ];
             const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
             if (receivedFields.length === 0) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: "Not updated — no mutable fields were received. No planner data was changed. If you attempted a large description, it may have exceeded the tool payload limit.",
-                        }],
-                    details: { updated: false, reason: "no-mutable-fields" },
-                };
+                return mutationNoFieldsFailure({
+                    entity: "feature",
+                    ref: formatFeatureRef(resolvedFeature.feature.number),
+                    operation: "update",
+                    mutableFields,
+                    retryCommand: `feature_update ${formatFeatureRef(resolvedFeature.feature.number)}`,
+                    readBackCommand: `feature_get ${formatFeatureRef(resolvedFeature.feature.number)} with full=true`,
+                    descriptionFallback: {
+                        entityId: featureId,
+                        inputField: "description",
+                        storedField: "feature description",
+                        descriptionRefField: "descriptionRef",
+                    },
+                });
             }
             let foundDoc;
             try {
@@ -3605,21 +4405,26 @@ export default function planPiExtension(pi) {
                     if (!feature)
                         return doc; // not found: no-op, handled below
                     if (params.name !== undefined)
-                        feature.name = params.name;
+                        feature.name = params.name.trim();
                     if (params.description !== undefined)
-                        feature.description = params.description;
+                        feature.description = params.description.trim();
+                    if (params.descriptionRef !== undefined) {
+                        const descriptionRef = normalizeDescriptionRef(params.descriptionRef);
+                        if (descriptionRef)
+                            feature.descriptionRef = descriptionRef;
+                        else
+                            delete feature.descriptionRef;
+                    }
                     if (params.workDone !== undefined)
-                        feature.workDone = params.workDone;
+                        feature.workDone = params.workDone.trim();
                     if (params.workRemaining !== undefined)
-                        feature.workRemaining = params.workRemaining;
+                        feature.workRemaining = params.workRemaining.trim();
                     if (params.startDate !== undefined)
-                        feature.startDate = params.startDate;
+                        feature.startDate = params.startDate.trim();
                     if (params.endDate !== undefined)
-                        feature.endDate = params.endDate;
+                        feature.endDate = params.endDate.trim();
                     if (params.priority !== undefined)
                         feature.priority = params.priority;
-                    if (params.acceptedDecisions !== undefined)
-                        feature.acceptedDecisions = params.acceptedDecisions;
                     feature.updatedAt = nowISO();
                     return doc;
                 });
@@ -3658,22 +4463,24 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
             const featureId = resolvedFeature.feature.id;
             let deleted = false;
-            await st.updateFeatures((doc) => {
-                const before = doc.features.length;
-                doc.features = doc.features.filter((f) => f.id !== featureId);
-                if (doc.features.length !== before)
-                    deleted = true;
-                return doc;
-            });
             let cascadeCount = 0;
-            if (params.cascade) {
-                const phases = await st.loadAllPhases();
-                for (const phase of phases.filter((p) => p.featureId === featureId)) {
-                    await st.deletePhase(phase.id);
-                    cascadeCount += 1;
+            await st.runBatch(async () => {
+                await st.updateFeatures((doc) => {
+                    const before = doc.features.length;
+                    doc.features = doc.features.filter((f) => f.id !== featureId);
+                    if (doc.features.length !== before)
+                        deleted = true;
+                    return doc;
+                });
+                if (params.cascade) {
+                    const phases = await st.loadAllPhases();
+                    for (const phase of phases.filter((p) => p.featureId === featureId)) {
+                        await st.deletePhase(phase.id);
+                        cascadeCount += 1;
+                    }
                 }
-            }
-            await st.writeGenerated();
+                await st.writeGenerated();
+            });
             return { content: [{ type: "text", text: `Feature deleted: ${params.featureId}${params.cascade ? ` (cascade: ${cascadeCount} phases)` : ""}` }], details: { deleted: params.featureId, cascadedPhases: cascadeCount } };
         },
     });
@@ -3681,7 +4488,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "phase_list",
         label: "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 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 plan_get full=true.",
         parameters: Type.Object({
             featureRef: Type.Optional(Type.String({ description: "Optional: filter to one feature (F00x/shortId/UUID/name)" })),
             status: Type.Optional(Type.String({ description: "Optional: filter by status name" })),
@@ -3704,7 +4511,7 @@ export default function planPiExtension(pi) {
             const summary = phases.map((p) => {
                 const fNum = featureNumberOfPhase(p, features);
                 const fTag = fNum !== undefined ? ` [F${pad(fNum)}]` : "";
-                return `- ${formatPhaseRef(p.number, fNum)}${p.shortId ? ` · ${p.shortId}` : ""} — ${p.title} (${p.status}; ${p.tasks.length} tasks)${fTag}`;
+                return `- ${formatPhaseRef(p.number, fNum)}${p.shortId ? ` · ${p.shortId}` : ""} — ${p.title} (${p.status}${p.priority > 0 ? `; priority ${p.priority}` : ""}; ${p.tasks.length} tasks)${fTag}`;
             }).join("\n");
             return { content: [{ type: "text", text: summary || "No phases" }], details: {} };
         },
@@ -3712,28 +4519,44 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "phase_get",
         label: "Phase Get",
-        description: "Show a phase. Compact identity by default (saves tokens); pass full=true to include the description and derived linked requirements.",
+        description: "Show a phase. Compact identity by default (saves tokens); pass full=true to include the description, every canonical Accepted Decision field, and derived linked requirements.",
         parameters: Type.Object({
             phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title" }),
             full: Type.Optional(Type.Boolean({ description: "If true, include the phase description. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
+            const plannerSessionId = `pi:${ctx.sessionManager.getSessionId()}`;
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const features = (await st.loadFeatures()).features;
             const phase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
             if (!phase)
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
-            if (params.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 { content: [{ type: "text", text: params.full ? `${summary}\n\n${phase.description || ""}${requirementsBlock}` : summary }], details: { linkedRequirements } };
+            if (!params.full)
+                return { content: [{ type: "text", text: summary }], details: { linkedRequirements } };
+            const decisionBlock = renderAcceptedDecisionsSection("Accepted Decisions", phase.acceptedDecisions);
+            const result = {
+                content: [{ type: "text", text: `${summary}\n\n${phase.description || ""}${descriptionRefBlock}${requirementsBlock}\n\n${decisionBlock}` }],
+                details: {
+                    phase: {
+                        ref: formatPhaseRef(phase.number, featureNumberOfPhase(phase, features)),
+                        description: phase.description,
+                        descriptionRef: phase.descriptionRef ?? "",
+                        acceptedDecisions: phase.acceptedDecisions,
+                    },
+                    linkedRequirements,
+                },
+            };
+            markCanonicalFullReadForSessionId(plannerSessionId, "phase", phase, result.content[0].text);
+            return result;
         },
     });
     pi.registerTool({
@@ -3768,7 +4591,7 @@ export default function planPiExtension(pi) {
             if (!existingFeature)
                 return { content: [{ type: "text", text: `Resolved feature ${featureId} no longer exists. Refusing to create phase.` }], details: {} };
             let phase;
-            await withFeatureLock(featureId, async () => {
+            await st.runBatch(() => withFeatureLock(featureId, async () => {
                 const id = createPhaseId();
                 const identity = await st.allocateEntityIdentity("phase", id);
                 const priority = await st.nextPriority("phase", featureId);
@@ -3784,7 +4607,7 @@ export default function planPiExtension(pi) {
                     goals: [], nonGoals: [], dependencies: [], dependsOn: [], risks: [],
                     openQuestions: [], decisions: [], acceptedDecisions: [], completionCriteria: [], taskIds: [], tasks: [],
                     createdAt: now, updatedAt: now,
-                    handoff: "", handoffUpdatedAt: "",
+                    handoff: "", handoffUpdatedAt: "", handoffAudit: null,
                     handoffReadAt: "",
                     handoffHistory: [],
                     statusLog: [],
@@ -3801,23 +4624,104 @@ export default function planPiExtension(pi) {
                     return doc;
                 });
                 await st.writeGenerated();
-            });
+            }));
             if (!phase)
                 return { content: [{ type: "text", text: "Phase creation failed." }], details: {} };
             const phaseCreateFeatures = (await st.loadFeatures()).features;
             return { content: [{ type: "text", text: `✅ Phase created: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseCreateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
         },
     });
+    pi.registerTool({
+        name: "phase_discuss",
+        label: "Phase Discuss",
+        description: "Persist phase discovery fields and mark governance context ready without overriding derived status.",
+        parameters: Type.Object({
+            phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title" }),
+            goal: Type.Optional(Type.String({ description: "Backward-compatible single main goal" })),
+            goals: Type.Optional(Type.Array(Type.String(), { description: "Replace the phase goals list" })),
+            summary: Type.Optional(Type.String()),
+            scope: Type.Optional(Type.String({ description: "Current phase scope; stored as the phase description" })),
+            descriptionRef: Type.Optional(Type.String({ description: "Optional markdown reference under .planner/docs/ for the full phase description." })),
+            nonGoals: Type.Optional(Type.Array(Type.String())),
+            dependencies: Type.Optional(Type.Array(Type.String())),
+            risks: Type.Optional(Type.Array(Type.String())),
+            openQuestions: Type.Optional(Type.Array(Type.String())),
+            completionCriteria: Type.Optional(Type.Array(Type.String())),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const resolvedPhase = findPhaseByRef(await st.loadAllPhases(), features, params.phaseId.trim());
+            if (!resolvedPhase)
+                return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: { discussed: false, errorCode: "PHASE_NOT_FOUND" }, isError: true };
+            const mutableFields = ["goal", "goals", "summary", "scope", "descriptionRef", "nonGoals", "dependencies", "risks", "openQuestions", "completionCriteria"];
+            const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+            if (receivedFields.length === 0) {
+                return mutationNoFieldsFailure({
+                    entity: "phase",
+                    ref: formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features)),
+                    operation: "discuss",
+                    mutableFields,
+                    retryCommand: `phase_discuss ${formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features))}`,
+                    readBackCommand: `phase_get ${formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features))} with full=true`,
+                    descriptionFallback: {
+                        entityId: resolvedPhase.id,
+                        inputField: "scope",
+                        storedField: "phase description",
+                        descriptionRefField: "descriptionRef",
+                    },
+                });
+            }
+            const phase = await st.updatePhase(resolvedPhase.id, (current) => {
+                if (params.goals !== undefined)
+                    current.goals = params.goals.map((item) => item.trim()).filter(Boolean);
+                else if (params.goal !== undefined)
+                    current.goals = [params.goal.trim()].filter(Boolean);
+                if (params.summary !== undefined)
+                    current.summary = params.summary.trim();
+                if (params.scope !== undefined)
+                    current.description = params.scope.trim();
+                if (params.descriptionRef !== undefined) {
+                    const descriptionRef = normalizeDescriptionRef(params.descriptionRef);
+                    if (descriptionRef)
+                        current.descriptionRef = descriptionRef;
+                    else
+                        delete current.descriptionRef;
+                }
+                if (params.nonGoals !== undefined)
+                    current.nonGoals = params.nonGoals.map((item) => item.trim()).filter(Boolean);
+                if (params.dependencies !== undefined)
+                    current.dependencies = params.dependencies.map((item) => item.trim()).filter(Boolean);
+                if (params.risks !== undefined)
+                    current.risks = params.risks.map((item) => item.trim()).filter(Boolean);
+                if (params.openQuestions !== undefined)
+                    current.openQuestions = params.openQuestions.map((item) => item.trim()).filter(Boolean);
+                if (params.completionCriteria !== undefined)
+                    current.completionCriteria = params.completionCriteria.map((item) => item.trim()).filter(Boolean);
+                current.discussedAt = nowISO();
+                current.contextReady = true;
+                current.contextReadyReason = "Updated through phase_discuss tool.";
+                current.updatedAt = nowISO();
+                return current;
+            });
+            await st.writeGenerated();
+            const phaseRef = formatPhaseRef(phase.number, featureNumberOfPhase(phase, features));
+            return { content: [{ type: "text", text: `✅ Phase discussed/context ready: ${phaseRef} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.` }], details: { ...phase, discussed: true, contextReady: true, updatedFields: receivedFields } };
+        },
+    });
     pi.registerTool({
         name: "phase_update",
         label: "Phase Update",
-        description: "Update one or more fields of a phase. Only provided fields are changed. Supports re-linking to a feature via featureId. IMPORTANT: phase status is derived from task statuses, so do not update phase.status directly unless truly necessary.",
+        description: "Update one or more canonical phase fields and optionally re-link the phase via featureId. Phase status is derived from task statuses and cannot be changed directly.",
         parameters: Type.Object({
             phaseId: Type.String({ description: "Phase ref: F00x/P00x, bare P00x (global), shortId, UUID, or title" }),
             title: Type.Optional(Type.String({ description: "New title" })),
-            status: Type.Optional(Type.String({ description: "New status: draft|discovery|planned|in-progress|done|blocked|canceled. Avoid setting this directly unless you truly need an override: phase status is derived from task statuses." })),
+            status: Type.Optional(Type.String({ description: "Deprecated compatibility field. Phase status is derived from task statuses; supplying this field returns DERIVED_STATUS_READ_ONLY." })),
             summary: Type.Optional(Type.String({ description: "New summary" })),
             description: Type.Optional(Type.String({ description: "New description" })),
+            descriptionRef: Type.Optional(Type.String({ description: "Optional markdown reference under .planner/docs/ for the full phase description." })),
             featureId: Type.Optional(Type.String({ description: "Link/unlink phase to a feature. Use empty string to unlink." })),
             priority: Type.Optional(Type.Number({ description: "Display order within the feature (lower = higher)" })),
             goals: Type.Optional(Type.Array(Type.String(), { description: "Replace goals list" })),
@@ -3833,7 +4737,7 @@ export default function planPiExtension(pi) {
                 rationale: Type.String(),
                 implementationNotes: Type.String(),
                 acceptedAt: Type.String(),
-            }), { description: "Replace accepted decisions list" })),
+            }), { description: "Deprecated compatibility field. Raw replacement is rejected; use accepted_decision_create, accepted_decision_update, or accepted_decision_delete." })),
             completionCriteria: Type.Optional(Type.Array(Type.String(), { description: "Replace completion criteria list" })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
@@ -3855,34 +4759,33 @@ export default function planPiExtension(pi) {
             if (params.status !== undefined) {
                 return derivedStatusReadOnlyResult("phase", formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features)), String(params.status), resolvedPhase.status);
             }
+            if (params.acceptedDecisions !== undefined) {
+                return {
+                    content: [{ type: "text", text: "Raw acceptedDecisions replacement is disabled. Use accepted_decision_create, accepted_decision_update, or accepted_decision_delete so IDs and acceptedAt are preserved." }],
+                    details: { updated: false, errorCode: "ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED", targetType: "phase", targetRef: formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features)) },
+                    isError: true,
+                };
+            }
+            const mutableFields = ["title", "summary", "description", "descriptionRef", "featureId", "priority", "goals", "nonGoals", "dependencies", "risks", "openQuestions", "decisions", "completionCriteria"];
+            const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+            if (receivedFields.length === 0) {
+                return mutationNoFieldsFailure({
+                    entity: "phase",
+                    ref: formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features)),
+                    operation: "update",
+                    mutableFields,
+                    retryCommand: `phase_update ${formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features))}`,
+                    readBackCommand: `phase_get ${formatPhaseRef(resolvedPhase.number, featureNumberOfPhase(resolvedPhase, features))} with full=true`,
+                    descriptionFallback: {
+                        entityId: phaseId,
+                        inputField: "description",
+                        storedField: "phase description",
+                        descriptionRefField: "descriptionRef",
+                    },
+                });
+            }
             const prevFeatureId = phase.featureId;
             let nextFeatureIdForUpdate = prevFeatureId;
-            if (params.title !== undefined) {
-                phase.title = params.title;
-                phase.slug = normalizeSlug(params.title);
-            }
-            if (params.summary !== undefined)
-                phase.summary = params.summary;
-            if (params.description !== undefined)
-                phase.description = params.description;
-            if (params.priority !== undefined)
-                phase.priority = params.priority;
-            if (params.goals !== undefined)
-                phase.goals = params.goals;
-            if (params.nonGoals !== undefined)
-                phase.nonGoals = params.nonGoals;
-            if (params.dependencies !== undefined)
-                phase.dependencies = params.dependencies;
-            if (params.risks !== undefined)
-                phase.risks = params.risks;
-            if (params.openQuestions !== undefined)
-                phase.openQuestions = params.openQuestions;
-            if (params.decisions !== undefined)
-                phase.decisions = params.decisions;
-            if (params.acceptedDecisions !== undefined)
-                phase.acceptedDecisions = params.acceptedDecisions;
-            if (params.completionCriteria !== undefined)
-                phase.completionCriteria = params.completionCriteria;
             if (params.featureId !== undefined) {
                 if (params.featureId === "") {
                     nextFeatureIdForUpdate = undefined;
@@ -3893,24 +4796,60 @@ export default function planPiExtension(pi) {
                         return { content: [{ type: "text", text: resolvedFeature.error }], details: {} };
                     nextFeatureIdForUpdate = resolvedFeature.feature.id;
                 }
-                phase.featureId = nextFeatureIdForUpdate;
-                if (nextFeatureIdForUpdate !== prevFeatureId) {
-                    await st.updateFeatures((doc) => {
-                        for (const f of doc.features) {
-                            if (f.id === prevFeatureId)
-                                f.phaseIds = f.phaseIds.filter((pid) => pid !== phase.id);
-                            if (f.id === nextFeatureIdForUpdate && !f.phaseIds.includes(phase.id))
-                                f.phaseIds.push(phase.id);
+            }
+            let persistedPhase;
+            await st.runBatch(async () => {
+                persistedPhase = await st.updatePhase(phaseId, (current) => {
+                    const next = {
+                        ...current,
+                        ...(params.title !== undefined ? { title: params.title.trim(), slug: normalizeSlug(params.title) } : {}),
+                        ...(params.summary !== undefined ? { summary: params.summary.trim() } : {}),
+                        ...(params.description !== undefined ? { description: params.description.trim() } : {}),
+                        ...(params.priority !== undefined ? { priority: params.priority } : {}),
+                        ...(params.goals !== undefined ? { goals: params.goals.map((item) => item.trim()).filter(Boolean) } : {}),
+                        ...(params.nonGoals !== undefined ? { nonGoals: params.nonGoals.map((item) => item.trim()).filter(Boolean) } : {}),
+                        ...(params.dependencies !== undefined ? { dependencies: params.dependencies.map((item) => item.trim()).filter(Boolean) } : {}),
+                        ...(params.risks !== undefined ? { risks: params.risks.map((item) => item.trim()).filter(Boolean) } : {}),
+                        ...(params.openQuestions !== undefined ? { openQuestions: params.openQuestions.map((item) => item.trim()).filter(Boolean) } : {}),
+                        ...(params.decisions !== undefined ? { decisions: params.decisions.map((item) => item.trim()).filter(Boolean) } : {}),
+                        ...(params.completionCriteria !== undefined ? { completionCriteria: params.completionCriteria.map((item) => item.trim()).filter(Boolean) } : {}),
+                        ...(params.featureId !== undefined ? { featureId: nextFeatureIdForUpdate } : {}),
+                        updatedAt: nowISO(),
+                    };
+                    if (params.descriptionRef !== undefined) {
+                        const descriptionRef = normalizeDescriptionRef(params.descriptionRef);
+                        if (descriptionRef)
+                            next.descriptionRef = descriptionRef;
+                        else
+                            delete next.descriptionRef;
+                    }
+                    return next;
+                });
+                if (params.featureId !== undefined && nextFeatureIdForUpdate !== prevFeatureId) {
+                    await st.updateFeatures((document) => {
+                        for (const feature of document.features) {
+                            if (feature.id === prevFeatureId)
+                                feature.phaseIds = feature.phaseIds.filter((id) => id !== phaseId);
+                            if (feature.id === nextFeatureIdForUpdate && !feature.phaseIds.includes(phaseId))
+                                feature.phaseIds.push(phaseId);
                         }
-                        return doc;
+                        return document;
                     });
                 }
-            }
-            phase.updatedAt = nowISO();
-            await st.savePhase(phase);
-            await st.writeGenerated();
+                await st.writeGenerated();
+            });
+            phase = persistedPhase;
             const phaseUpdateFeatures = (await st.loadFeatures()).features;
-            return { content: [{ type: "text", text: `✅ Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseUpdateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}` }], details: phase };
+            const descriptionFreshness = receivedFields.some((field) => field === "description" || field === "descriptionRef")
+                ? await st.previewDescriptionReconciliation()
+                : null;
+            const staleParentRefs = descriptionFreshness?.diagnostics
+                .filter((entry) => entry.state === "stale" && entry.ownerId === phase.featureId)
+                .map((entry) => entry.ownerRef) ?? [];
+            const freshnessNotice = staleParentRefs.length > 0
+                ? `\n⚠️ Parent description review required: ${staleParentRefs.join(", ")}. Run description_freshness for the non-mutating reconciliation preview.`
+                : "";
+            return { content: [{ type: "text", text: `✅ Phase updated: ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, phaseUpdateFeatures))} — ${phase.title}${phase.shortId ? ` · ${phase.shortId}` : ""}. Fields saved: ${receivedFields.join(", ")}.${freshnessNotice}` }], details: { ...phase, updated: true, updatedFields: receivedFields, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) } };
         },
     });
     pi.registerTool({
@@ -3948,7 +4887,7 @@ export default function planPiExtension(pi) {
                 implementationNotes: params.implementationNotes.trim(),
                 acceptedAt,
             };
-            await withFeatureLock(resolvedFeature.feature.id, async () => {
+            await st.runBatch(() => withFeatureLock(resolvedFeature.feature.id, async () => {
                 let featureWritten = false;
                 try {
                     await st.updateFeatures((doc) => {
@@ -3979,11 +4918,128 @@ export default function planPiExtension(pi) {
                     }
                     throw error;
                 }
-            });
+            }));
             await st.writeGenerated();
             return { content: [{ type: "text", text: `✅ Decision recorded on ${formatFeatureRef(resolvedFeature.feature.number)} and ${formatPhaseRef(resolvedPhase.number, resolvedFeature.feature.number)}: ${acceptedDecision.title}` }], details: acceptedDecision };
         },
     });
+    pi.registerTool({
+        name: "accepted_decision_create",
+        label: "Accepted Decision Create",
+        description: "Create an accepted decision on the project, feature, phase, or task without replacing the full acceptedDecisions array.",
+        parameters: Type.Object({
+            targetType: Type.Union([Type.Literal("project"), Type.Literal("feature"), Type.Literal("phase"), Type.Literal("task")]),
+            targetRef: Type.Optional(Type.String({ description: "Feature/phase/task ref. Omit for targetType=project." })),
+            title: Type.String({ minLength: 1 }),
+            decision: Type.Optional(Type.String()),
+            rationale: Type.Optional(Type.String()),
+            implementationNotes: Type.Optional(Type.String()),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const target = await resolveAcceptedDecisionTarget(st, params.targetType, params.targetRef);
+            if (!target.ok)
+                return { content: [{ type: "text", text: target.error }], details: { created: false, errorCode: "ACCEPTED_DECISION_TARGET_NOT_FOUND" }, isError: true };
+            const createInput = {
+                title: params.title,
+                ...(params.decision !== undefined ? { decision: params.decision } : {}),
+                ...(params.rationale !== undefined ? { rationale: params.rationale } : {}),
+                ...(params.implementationNotes !== undefined ? { implementationNotes: params.implementationNotes } : {}),
+            };
+            try {
+                const acceptedDecision = await st.createAcceptedDecision(target.owner, createInput);
+                await st.writeGenerated();
+                return { content: [{ type: "text", text: `✅ Accepted decision created on ${target.ref}: ${acceptedDecision.title}` }], details: { created: true, targetType: params.targetType, targetRef: target.ref, acceptedDecision } };
+            }
+            catch (error) {
+                return acceptedDecisionMutationFailure(error, "created");
+            }
+        },
+    });
+    pi.registerTool({
+        name: "accepted_decision_update",
+        label: "Accepted Decision Update",
+        description: "Update one accepted decision while preserving its id and acceptedAt timestamp.",
+        parameters: Type.Object({
+            targetType: Type.Union([Type.Literal("project"), Type.Literal("feature"), Type.Literal("phase"), Type.Literal("task")]),
+            targetRef: Type.Optional(Type.String({ description: "Feature/phase/task ref. Omit for targetType=project." })),
+            decisionId: Type.String({ minLength: 1 }),
+            title: Type.Optional(Type.String()),
+            decision: Type.Optional(Type.String()),
+            rationale: Type.Optional(Type.String()),
+            implementationNotes: Type.Optional(Type.String()),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const mutableFields = ["title", "decision", "rationale", "implementationNotes"];
+            const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+            if (receivedFields.length === 0) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "❌ ACCEPTED DECISION UPDATE FAILED [NO_MUTABLE_FIELDS_RECEIVED]\nNo accepted decision fields were supplied." }],
+                    details: noMutableFieldsReceived({
+                        entity: "acceptedDecision",
+                        ref: params.decisionId,
+                        operation: "update",
+                        mutableFields,
+                        retryCommand: "accepted_decision_update with title, decision, rationale, or implementationNotes",
+                        readBackCommand: "Read back the owning project, feature, phase, or task.",
+                    }),
+                };
+            }
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const target = await resolveAcceptedDecisionTarget(st, params.targetType, params.targetRef);
+            if (!target.ok)
+                return { content: [{ type: "text", text: target.error }], details: { updated: false, errorCode: "ACCEPTED_DECISION_TARGET_NOT_FOUND" }, isError: true };
+            const updateInput = {
+                ...(params.title !== undefined ? { title: params.title } : {}),
+                ...(params.decision !== undefined ? { decision: params.decision } : {}),
+                ...(params.rationale !== undefined ? { rationale: params.rationale } : {}),
+                ...(params.implementationNotes !== undefined ? { implementationNotes: params.implementationNotes } : {}),
+            };
+            try {
+                const acceptedDecision = await st.updateAcceptedDecision(target.owner, params.decisionId, updateInput);
+                await st.writeGenerated();
+                return { content: [{ type: "text", text: `✅ Accepted decision updated on ${target.ref}: ${acceptedDecision.title}` }], details: { updated: true, targetType: params.targetType, targetRef: target.ref, acceptedDecision, updatedFields: receivedFields } };
+            }
+            catch (error) {
+                return acceptedDecisionMutationFailure(error, "updated");
+            }
+        },
+    });
+    pi.registerTool({
+        name: "accepted_decision_delete",
+        label: "Accepted Decision Delete",
+        description: "Delete one accepted decision from the project, feature, phase, or task. Requires confirmed=true.",
+        parameters: Type.Object({
+            targetType: Type.Union([Type.Literal("project"), Type.Literal("feature"), Type.Literal("phase"), Type.Literal("task")]),
+            targetRef: Type.Optional(Type.String({ description: "Feature/phase/task ref. Omit for targetType=project." })),
+            decisionId: Type.String({ minLength: 1 }),
+            confirmed: Type.Boolean({ description: "Must be true to confirm deleting this accepted decision." }),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const target = await resolveAcceptedDecisionTarget(st, params.targetType, params.targetRef);
+            if (!target.ok)
+                return { content: [{ type: "text", text: target.error }], details: { deleted: false, errorCode: "ACCEPTED_DECISION_TARGET_NOT_FOUND" }, isError: true };
+            if (!params.confirmed) {
+                return { content: [{ type: "text", text: `Delete not confirmed for accepted decision ${params.decisionId} on ${target.ref}. Retry with confirmed=true.` }], details: { deleted: false, confirmRequired: true, targetType: params.targetType, targetRef: target.ref, decisionId: params.decisionId } };
+            }
+            try {
+                const acceptedDecision = await st.deleteAcceptedDecision(target.owner, params.decisionId);
+                await st.writeGenerated();
+                return { content: [{ type: "text", text: `✅ Accepted decision deleted from ${target.ref}: ${acceptedDecision.title}` }], details: { deleted: true, targetType: params.targetType, targetRef: target.ref, decisionId: params.decisionId, acceptedDecision } };
+            }
+            catch (error) {
+                return acceptedDecisionMutationFailure(error, "deleted");
+            }
+        },
+    });
     pi.registerTool({
         name: "phase_delete",
         label: "Phase Delete",
@@ -4007,18 +5063,20 @@ export default function planPiExtension(pi) {
             catch {
                 return { content: [{ type: "text", text: `Phase not found: ${params.phaseId}` }], details: {} };
             }
-            await st.deletePhase(phaseId);
-            if (phase.featureId) {
-                await st.updateFeatures((doc) => {
-                    const feature = doc.features.find((f) => f.id === phase.featureId);
-                    if (feature) {
-                        feature.phaseIds = feature.phaseIds.filter((pid) => pid !== phaseId);
-                        feature.updatedAt = nowISO();
-                    }
-                    return doc;
-                });
-            }
-            await st.writeGenerated();
+            await st.runBatch(async () => {
+                await st.deletePhase(phaseId);
+                if (phase.featureId) {
+                    await st.updateFeatures((doc) => {
+                        const feature = doc.features.find((f) => f.id === phase.featureId);
+                        if (feature) {
+                            feature.phaseIds = feature.phaseIds.filter((pid) => pid !== phaseId);
+                            feature.updatedAt = nowISO();
+                        }
+                        return doc;
+                    });
+                }
+                await st.writeGenerated();
+            });
             return { content: [{ type: "text", text: `Phase deleted: ${params.phaseId}` }], details: { deleted: params.phaseId } };
         },
     });
@@ -4026,7 +5084,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "task_list",
         label: "Task List",
-        description: "List tasks (compact: F00x/P00x/T00x · shortId — title (status)). Filters: featureRef, phaseRef, status. Omit all to list every task. Cheap discovery — do NOT read .planner/ files or plan_get full=true.",
+        description: "List tasks (compact: F00x/P00x/T00x · shortId — title (status; priority N)). Filters: featureRef, phaseRef, status. Omit all to list every task. Cheap discovery — do NOT read .planner/ files or plan_get full=true.",
         parameters: Type.Object({
             featureRef: Type.Optional(Type.String({})),
             phaseRef: Type.Optional(Type.String({})),
@@ -4057,7 +5115,7 @@ export default function planPiExtension(pi) {
                 for (const task of phase.tasks) {
                     if (params.status && task.status !== params.status)
                         continue;
-                    out.push(`- ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${pad(task.number)}${task.shortId ? ` · ${task.shortId}` : ""} — ${task.title} (${task.status})`);
+                    out.push(`- ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${pad(task.number)}${task.shortId ? ` · ${task.shortId}` : ""} — ${task.title} (${task.status}${task.priority > 0 ? `; priority ${task.priority}` : ""})`);
                 }
             }
             return { content: [{ type: "text", text: out.join("\n") || "No tasks" }], details: {} };
@@ -4066,21 +5124,20 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "task_get",
         label: "Task Get",
-        description: "Show a task. Compact identity by default (saves tokens); pass full=true to include the description, resume checkpoint/advisory, and statusLog.",
+        description: "Show a task. Compact identity by default (saves tokens); pass full=true to include the description, every canonical Accepted Decision field, resume checkpoint/advisory, and statusLog.",
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title" }),
             full: Type.Optional(Type.Boolean({ description: "If true, include the task description, resume checkpoint/advisory, and statusLog. Default: compact identity only." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
+            const plannerSessionId = `pi:${ctx.sessionManager.getSessionId()}`;
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const features = (await st.loadFeatures()).features;
             const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
             if (!found)
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
-            if (params.full)
-                markTaskReadForSessionId(plannerSessionId, found.task.id);
             const summary = `${found.task.title} — ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}${found.task.shortId ? ` · ${found.task.shortId}` : ""} (${found.task.status})`;
             if (!params.full)
                 return { content: [{ type: "text", text: summary }], details: {} };
@@ -4096,6 +5153,8 @@ export default function planPiExtension(pi) {
             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
@@ -4109,7 +5168,20 @@ export default function planPiExtension(pi) {
             }
             if (log)
                 sections.push(`Status log:\n${log}`);
-            return { content: [{ type: "text", text: sections.join("\n\n") }], details: {} };
+            sections.push(renderAcceptedDecisionsSection("Accepted Decisions", found.task.acceptedDecisions));
+            const result = {
+                content: [{ type: "text", text: sections.join("\n\n") }],
+                details: {
+                    task: {
+                        ref: `${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}`,
+                        description: found.task.description,
+                        descriptionRef: found.task.descriptionRef ?? "",
+                        acceptedDecisions: found.task.acceptedDecisions,
+                    },
+                },
+            };
+            markCanonicalFullReadForSessionId(plannerSessionId, "task", found.task, result.content[0].text);
+            return result;
         },
     });
     pi.registerTool({
@@ -4187,6 +5259,7 @@ export default function planPiExtension(pi) {
                 pauseHistory: [],
                 startedAt: "",
                 completedAt: "",
+                activeOwnerSession: "",
                 createdAt: now, updatedAt: now,
             };
             // Atomic read-modify-write on the phase file: serializes concurrent
@@ -4202,6 +5275,58 @@ export default function planPiExtension(pi) {
             return { content: [{ type: "text", text: `Task created: ${taskRef} — ${task.title}${task.shortId ? ` · ${task.shortId}` : ""}` }], details: task };
         },
     });
+    pi.registerTool({
+        name: "task_dependency_add",
+        label: "Task Dependency Add",
+        description: "Add a validated task dependency atomically; rejects self-dependencies, foreign tasks, and cycles.",
+        parameters: Type.Object({ taskId: Type.String(), dependsOn: Type.String() }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId);
+            const dependency = findTaskByRef(await st.loadAllPhases(), features, params.dependsOn);
+            if (!found || !dependency)
+                return { content: [{ type: "text", text: "Dependency target not found." }], details: { updated: false, errorCode: "DEPENDENCY_TASK_NOT_FOUND" }, isError: true };
+            try {
+                const task = await st.addTaskDependency(found.phase.id, found.task.id, dependency.task.id);
+                await st.writeGenerated();
+                return { content: [{ type: "text", text: "Dependency added." }], details: { updated: true, task } };
+            }
+            catch (error) {
+                const details = error instanceof PlanStoreError ? error.details : undefined;
+                return { content: [{ type: "text", text: error instanceof Error ? error.message : "Dependency update failed." }], details: { updated: false, errorCode: details?.errorCode ?? "DEPENDENCY_UPDATE_FAILED" }, isError: true };
+            }
+        },
+    });
+    pi.registerTool({
+        name: "task_dependency_delete",
+        label: "Task Dependency Delete",
+        description: "Remove a task dependency atomically after explicit confirmation.",
+        parameters: Type.Object({ taskId: Type.String(), dependsOn: Type.String(), confirmed: Type.Boolean() }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            if (!params.confirmed)
+                return { content: [{ type: "text", text: "Explicit confirmation is required." }], details: { updated: false, errorCode: "CONFIRMATION_REQUIRED" }, isError: true };
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId);
+            const dependency = findTaskByRef(await st.loadAllPhases(), features, params.dependsOn);
+            if (!found || !dependency)
+                return { content: [{ type: "text", text: "Dependency target not found." }], details: { updated: false, errorCode: "DEPENDENCY_TASK_NOT_FOUND" }, isError: true };
+            try {
+                const task = await st.deleteTaskDependency(found.phase.id, found.task.id, dependency.task.id);
+                await st.writeGenerated();
+                return { content: [{ type: "text", text: "Dependency removed." }], details: { updated: true, task } };
+            }
+            catch (error) {
+                const details = error instanceof PlanStoreError ? error.details : undefined;
+                return { content: [{ type: "text", text: error instanceof Error ? error.message : "Dependency deletion failed." }], details: { updated: false, errorCode: details?.errorCode ?? "DEPENDENCY_DELETE_FAILED" }, isError: true };
+            }
+        },
+    });
     pi.registerTool({
         name: "task_update",
         label: "Task Update",
@@ -4211,6 +5336,7 @@ export default function planPiExtension(pi) {
             title: Type.Optional(Type.String({ description: "New title" })),
             status: Type.Optional(Type.String({ description: "New status: planned|in-progress|done|blocked|canceled|rejected|deferred|waiting" })),
             description: Type.Optional(Type.String({ description: "New description" })),
+            descriptionRef: Type.Optional(Type.String({ description: "Optional markdown reference under .planner/docs/ for the full task description." })),
             notes: Type.Optional(Type.String({ description: "New implementation notes" })),
             motivation: Type.Optional(Type.String({ description: "Motivation for status change. REQUIRED when changing to blocked, canceled, rejected, deferred, waiting, or back to planned from another status." })),
             decisions: Type.Optional(Type.Array(Type.String(), { description: "Replace decisions list" })),
@@ -4221,9 +5347,10 @@ export default function planPiExtension(pi) {
                 rationale: Type.String(),
                 implementationNotes: Type.String(),
                 acceptedAt: Type.String(),
-            }), { description: "Replace accepted decisions list" })),
+            }), { description: "Deprecated compatibility field. Raw replacement is rejected; use accepted_decision_create, accepted_decision_update, or accepted_decision_delete." })),
             priority: Type.Optional(Type.Number({ description: "Display order within the phase (lower = higher)" })),
             checklist: Type.Optional(Type.Array(Type.String(), { description: "Replace checklist (plain strings). For interactive toggling use the web UI." })),
+            subtasks: Type.Optional(Type.Array(Type.Object({ id: Type.Optional(Type.String()), title: Type.String(), description: Type.Optional(Type.String()), status: Type.Optional(Type.String()) }), { description: "Replace subtasks; existing IDs must belong to this task and omitted IDs are planner-generated." })),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
@@ -4252,6 +5379,13 @@ export default function planPiExtension(pi) {
                     details: {},
                 };
             }
+            if (params.acceptedDecisions !== undefined) {
+                return {
+                    content: [{ type: "text", text: "Raw acceptedDecisions replacement is disabled. Use accepted_decision_create, accepted_decision_update, or accepted_decision_delete so IDs and acceptedAt are preserved." }],
+                    details: { updated: false, errorCode: "ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED", targetType: "task", targetRef: `${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}` },
+                    isError: true,
+                };
+            }
             if (params.status !== undefined &&
                 params.status !== found.task.status &&
                 needsMotivation(found.task.status, params.status)) {
@@ -4262,6 +5396,29 @@ export default function planPiExtension(pi) {
                     };
                 }
             }
+            if (params.subtasks !== undefined) {
+                const existingIds = new Set(found.task.subtasks.map((item) => item.id));
+                if (params.subtasks.some((item) => item.id !== undefined && !existingIds.has(item.id)))
+                    return { content: [{ type: "text", text: "Subtask IDs must belong to the target task." }], details: { updated: false, errorCode: "SUBTASK_ID_INVALID" }, isError: true };
+            }
+            const mutableFields = ["title", "status", "description", "descriptionRef", "notes", "motivation", "decisions", "priority", "checklist", "subtasks"];
+            const receivedFields = mutableFields.filter((field) => params[field] !== undefined);
+            if (receivedFields.length === 0) {
+                return mutationNoFieldsFailure({
+                    entity: "task",
+                    ref: `${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}`,
+                    operation: "update",
+                    mutableFields,
+                    retryCommand: `task_update ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)}`,
+                    readBackCommand: `task_get ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(found.task.number)} with full=true`,
+                    descriptionFallback: {
+                        entityId: found.task.id,
+                        inputField: "description",
+                        storedField: "task description",
+                        descriptionRefField: "descriptionRef",
+                    },
+                });
+            }
             try {
                 const updatedPhase = await st.updatePhase(hostPhase.id, (phase) => {
                     const task = phase.tasks.find((t) => t.id === found.task.id);
@@ -4272,13 +5429,18 @@ export default function planPiExtension(pi) {
                     if (params.priority !== undefined)
                         task.priority = params.priority;
                     if (params.description !== undefined)
-                        task.description = params.description;
+                        task.description = params.description.trim();
+                    if (params.descriptionRef !== undefined) {
+                        const descriptionRef = normalizeDescriptionRef(params.descriptionRef);
+                        if (descriptionRef)
+                            task.descriptionRef = descriptionRef;
+                        else
+                            delete task.descriptionRef;
+                    }
                     if (params.notes !== undefined)
-                        task.notes = params.notes;
+                        task.notes = params.notes.trim();
                     if (params.decisions !== undefined)
-                        task.decisions = params.decisions;
-                    if (params.acceptedDecisions !== undefined)
-                        task.acceptedDecisions = params.acceptedDecisions;
+                        task.decisions = params.decisions.map((item) => item.trim()).filter(Boolean);
                     if (params.checklist !== undefined) {
                         task.checklist = params.checklist.map((itemTitle, index) => ({ number: index + 1,
                             id: createChecklistItemId(task.id, index + 1, itemTitle),
@@ -4286,6 +5448,9 @@ export default function planPiExtension(pi) {
                             checked: false,
                         }));
                     }
+                    if (params.subtasks !== undefined) {
+                        task.subtasks = params.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 ?? now, updatedAt: now }));
+                    }
                     if (params.status !== undefined) {
                         if (params.status !== task.status) {
                             const entry = {
@@ -4314,7 +5479,17 @@ export default function planPiExtension(pi) {
                 return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: {} };
             await st.syncTaskStatusRollup(found.phase.id);
             await st.writeGenerated();
-            return { content: [{ type: "text", text: `Task updated: ${updatedTask.id} (${updatedTask.status})` }], details: updatedTask };
+            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 description_freshness for the non-mutating reconciliation preview.`
+                : "";
+            return { content: [{ type: "text", text: `Task updated: ${updatedTask.id} (${updatedTask.status}). Fields saved: ${receivedFields.join(", ")}.${freshnessNotice}` }], details: { ...updatedTask, updated: true, updatedFields: receivedFields, ...(descriptionFreshness ? { descriptionFreshness, staleParentRefs } : {}) } };
         },
     });
     pi.registerTool({
@@ -4346,21 +5521,38 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "task_recommend",
         label: "Task Recommend",
-        description: "Return the recommended next task without starting work: continue one active task or the current phase, otherwise choose ready work by feature → phase → task priority. Reports approved deviation/resume context and never blocks an explicit user choice.",
+        description: "Return the 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. Never blocks an explicit user choice.",
         parameters: Type.Object({}),
         async execute(_id, _params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
-            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 { content: [{ type: "text", text: `No task recommendation: ${result.reason}` }], details: result };
-            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 { content: [{ type: "text", 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")}` : ""}` }], details: { ...selection, activeTask: result.activeTask, nextFeature: result.nextFeature, nextPhase: result.nextPhase, nextTask: result.nextTask, claims: result.claims } };
+            const { candidate } = selection;
             const reference = `${formatPhaseRef(candidate.phase.number, featureNumberOfPhase(candidate.phase, features.features))}/T${String(candidate.task.number).padStart(3, "0")}`;
+            const activeLine = 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 {
-                content: [{ type: "text", text: `Recommended (${result.kind}): ${reference} — ${candidate.task.title}\n${result.reason}${result.deviation ? `\nDeviation: ${result.deviation.id}; resume target ${result.deviation.resumeTaskId}.` : ""}` }],
-                details: result,
+                content: [{ type: "text", text: `${activeLine}Next work (${selection.kind}): ${reference} — ${candidate.task.title}\n${selection.reason}${selection.deviation ? `\nDeviation: ${selection.deviation.id}; resume target ${selection.deviation.resumeTaskId}.` : ""}${claimsText}` }],
+                details: { ...selection, taskId: candidate.task.id, phaseId: candidate.phase.id, featureId: candidate.feature?.id, activeTask: result.activeTask, nextFeature: result.nextFeature, nextPhase: result.nextPhase, nextTask: result.nextTask, claims: result.claims },
             };
         },
     });
@@ -4463,7 +5655,7 @@ export default function planPiExtension(pi) {
     pi.registerTool({
         name: "task_switch",
         label: "Task Switch",
-        description: "Switch from active work to a temporary task, even outside 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. Atomically snapshot/pause the source, start the target, and push a durable LIFO return target.",
+        description: "Switch from active work to a temporary task, even outside 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 project_guidelines_show, read that section and keep it in working memory while doing task work. Atomically snapshot/pause the source, start the target, and push a durable LIFO return target.",
         parameters: Type.Object({
             from_task: Type.String({ description: "Currently in-progress task ref" }),
             to_task: Type.String({ description: "Temporary task ref to start" }),
@@ -4475,6 +5667,7 @@ export default function planPiExtension(pi) {
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
+            const plannerSessionId = `pi:${ctx.sessionManager.getSessionId()}`;
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found." }], details: {} };
             const [featuresDoc, phases, project, focus] = await Promise.all([st.loadFeatures(), st.loadAllPhases(), st.loadProject(), st.loadResume()]);
@@ -4490,6 +5683,9 @@ export default function planPiExtension(pi) {
             if (source.task.status !== "in-progress" && !source.task.pauseSnapshot) {
                 return { content: [{ type: "text", text: `Task switch denied: source is ${source.task.status}; only in-progress or checkpointed work can be switched.` }], details: {} };
             }
+            if (source.task.status === "in-progress" && source.task.activeOwnerSession && source.task.activeOwnerSession !== plannerSessionId) {
+                return { content: [{ type: "text", text: `Task switch denied: source task is owned by another session.` }], details: {} };
+            }
             const targetFeature = target.phase.featureId ? features.find((feature) => feature.id === target.phase.featureId) : undefined;
             const linkedRequirements = [
                 ...(await st.linkedRequirementsForPhase(target.phase.id)),
@@ -4508,16 +5704,26 @@ export default function planPiExtension(pi) {
                 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 targetPhaseRef = formatPhaseRef(target.phase.number, featureNumberOfPhase(target.phase, features));
             const targetTaskRef = `${targetPhaseRef}/T${String(target.task.number).padStart(3, "0")}`;
             const targetFeatureRef = targetFeature ? formatFeatureRef(targetFeature.number) : "";
+            if (!projectGuidelinesReady) {
+                const nextActions = piContextReadActions(contextEligibility, { task: targetTaskRef, phase: targetPhaseRef, ...(targetFeatureRef ? { feature: targetFeatureRef } : {}) }, true, !requirementsReady, `Retry task_switch to ${targetTaskRef}`);
+                return {
+                    content: [{ type: "text", text: `Task switch denied: read Project Guidelines before switching task work. Current state: ${projectGuidelinesReadState}.` }],
+                    details: { projectGuidelinesReadState, contextEligibility, nextActions },
+                };
+            }
             if (!contextEligibility.eligible) {
-                const nextActions = piContextReadActions(contextEligibility, { task: targetTaskRef, phase: targetPhaseRef, ...(targetFeatureRef ? { feature: targetFeatureRef } : {}) }, !requirementsReady, `Retry task_switch to ${targetTaskRef}`);
+                const nextActions = piContextReadActions(contextEligibility, { task: targetTaskRef, phase: targetPhaseRef, ...(targetFeatureRef ? { feature: targetFeatureRef } : {}) }, false, !requirementsReady, `Retry task_switch to ${targetTaskRef}`);
                 return { content: [{ type: "text", text: `Task switch denied: context reads required. ${contextEligibility.reason}` }], details: { ...contextEligibility, nextActions } };
             }
             if (!requirementsReady) {
-                return { content: [{ type: "text", text: "Task switch denied: read the requirements linked to the target phase and feature before switching." }], details: { requirementIds: linkedRequirementIds, nextActions: ["requirement_list", `Retry task_switch to ${targetTaskRef}`] } };
+                return { content: [{ type: "text", text: `Task switch denied: ${requirementEligibility.reason}` }], details: { requirementIds: linkedRequirementIds, requirementEligibility, nextActions: [`requirement_list with phaseRef=${targetPhaseRef}`, `Retry 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 });
@@ -4531,7 +5737,7 @@ export default function planPiExtension(pi) {
                 resumeLocation: params.resume_location.trim(), howToResume: params.how_to_resume.trim(),
                 relatedTaskId: target.task.id, pausedAt: timestamp, pausedBy: params.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.reason, snapshot,
@@ -4542,75 +5748,78 @@ export default function planPiExtension(pi) {
             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: ${params.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: ${params.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: ${params.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: ${params.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.writeGenerated();
+                await st.syncTaskStatusRollup(source.phase.id);
+                if (target.phase.id !== source.phase.id)
+                    await st.syncTaskStatusRollup(target.phase.id);
+                await st.writeGenerated();
+            });
             invalidateReads(plannerSessionId);
             const sourceRef = `${formatPhaseRef(source.phase.number, featureNumberOfPhase(source.phase, features))}/T${String(source.task.number).padStart(3, "0")}`;
             const targetRef = `${formatPhaseRef(target.phase.number, featureNumberOfPhase(target.phase, features))}/T${String(target.task.number).padStart(3, "0")}`;
@@ -4625,156 +5834,192 @@ export default function planPiExtension(pi) {
             };
         },
     });
+    pi.registerTool({
+        name: "task_reopen",
+        label: "Task Reopen",
+        description: "Atomically reopen a completed task. Requires confirmed=true, retains completion evidence, and never pauses another task.",
+        parameters: Type.Object({ taskId: Type.String({ description: "Task reference" }), confirmed: Type.Boolean({ description: "Must be true after explicit user confirmation." }) }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const st = await requirePlan(ctx);
+            if (!st)
+                return { content: [{ type: "text", text: "No .planner/ found." }], details: { reopened: false, errorCode: "PLAN_NOT_FOUND" }, isError: true };
+            const features = (await st.loadFeatures()).features;
+            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+            if (!found)
+                return { content: [{ type: "text", text: `Task not found: ${params.taskId}` }], details: { reopened: false, errorCode: "TASK_NOT_FOUND" }, isError: true };
+            try {
+                const reopened = await st.reopenTask(found.phase.id, found.task.id, { confirmed: params.confirmed, ownerSessionId: `pi:${ctx.sessionManager.getSessionId()}` });
+                await st.syncTaskStatusRollup(found.phase.id);
+                await st.writeGenerated();
+                return { content: [{ type: "text", text: `✅ Task reopened: ${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${pad(reopened.number)} — ${reopened.title} (in-progress)` }], details: { reopened: true, task: reopened } };
+            }
+            catch (error) {
+                const details = error instanceof PlanStoreError ? error.details : undefined;
+                return { content: [{ type: "text", text: `Task reopen denied: ${error instanceof Error ? error.message : "unknown error"}` }], details: { reopened: false, errorCode: details?.errorCode ?? "TASK_REOPEN_FAILED" }, isError: true };
+            }
+        },
+    });
     pi.registerTool({
         name: "task_start",
         label: "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. A denied start is an isError result with started=false; NEVER claim work started unless details.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 project_guidelines_show, read that section and keep it in working memory while doing task work. A denied start is an isError result with started=false; NEVER claim work started unless details.started is true. Success is returned only after persisted in-progress state is verified.",
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ref: F00x/P00x/T00x, bare T00x (global), 5-char shortId, UUID, or title to start" }),
         }),
         async execute(_id, params, _signal, _onUpdate, ctx) {
             const st = await requirePlan(ctx);
+            const plannerSessionId = `pi:${ctx.sessionManager.getSessionId()}`;
             if (!st)
                 return taskStartFailure(taskStartDenied("PLAN_NOT_FOUND", "No .planner/ found.", ["Initialize or load the planner, then retry task_start."]));
-            const features = (await st.loadFeatures()).features;
-            const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
-            if (!found)
-                return taskStartFailure(taskStartDenied("TASK_NOT_FOUND", `Task not found: ${params.taskId}`, ["Resolve the task with task_list or task_get, then retry task_start."]));
-            const task = found.task;
-            const phaseRef = formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features));
-            const taskRef = `${phaseRef}/T${String(task.number).padStart(3, "0")}`;
-            const feature = found.phase.featureId ? features.find((candidate) => candidate.id === found.phase.featureId) : undefined;
-            const featureRef = feature ? formatFeatureRef(feature.number) : "";
-            if (task.status === "done")
-                return taskStartFailure(taskStartDenied("TASK_DONE", `Task ${taskRef} is done and was not reopened.`, [`Use task_update with status=planned and a motivation to reopen ${taskRef}.`, `Repeat the required full context reads, then retry task_start ${taskRef}.`], { taskId: 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: task.id,
-                phaseId: found.phase.id,
-                ...(found.phase.featureId ? { featureId: found.phase.featureId } : {}),
-                task,
-                phase: found.phase,
-                ...(feature ? { feature } : {}),
-                requirements: linkedRequirements,
-                requirementIds: linkedRequirementIds,
-            };
-            const contextEligibility = contextReadEligibilityForSession(contextInput);
-            const requirementsReady = hasReadRequirementsForSession(plannerSessionId, linkedRequirementIds, linkedRequirements);
-            if (!contextEligibility.eligible) {
-                return taskStartFailure(taskStartDenied("CONTEXT_READ_REQUIRED", `Required context reads are incomplete or stale. ${contextEligibility.reason}`, piContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, !requirementsReady, `Retry task_start ${taskRef}`), { taskId: task.id }), { contextEligibility });
-            }
-            if (!requirementsReady) {
-                return taskStartFailure(taskStartDenied("REQUIREMENTS_READ_REQUIRED", "Linked requirements were not read; the task remains unchanged.", ["requirement_list", `Retry task_start ${taskRef}`], { taskId: task.id, requirementIds: linkedRequirementIds }));
-            }
-            if (!hasValidSessionAttestation(contextInput)) {
-                await st.recordContextRead({
+            return st.runBatch(async () => {
+                const features = (await st.loadFeatures()).features;
+                const found = findTaskByRef(await st.loadAllPhases(), features, params.taskId.trim());
+                if (!found)
+                    return taskStartFailure(taskStartDenied("TASK_NOT_FOUND", `Task not found: ${params.taskId}`, ["Resolve the task with task_list or task_get, then retry task_start."]));
+                const task = found.task;
+                const phaseRef = formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features));
+                const taskRef = `${phaseRef}/T${String(task.number).padStart(3, "0")}`;
+                const feature = found.phase.featureId ? features.find((candidate) => candidate.id === found.phase.featureId) : undefined;
+                const featureRef = feature ? formatFeatureRef(feature.number) : "";
+                if (task.status === "done")
+                    return taskStartFailure(taskStartDenied("TASK_DONE", `Task ${taskRef} is done and was not reopened.`, [`Use task_reopen with taskId=${taskRef} and confirmed=true after explicit user confirmation.`, `Retry task_start ${taskRef} only if reopening is not the intended operation.`], { taskId: 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,
-                    phaseId: found.phase.id,
                     taskId: task.id,
+                    phaseId: found.phase.id,
                     ...(found.phase.featureId ? { featureId: found.phase.featureId } : {}),
+                    task,
+                    phase: found.phase,
+                    ...(feature ? { feature } : {}),
+                    requirements: linkedRequirements,
                     requirementIds: linkedRequirementIds,
-                });
-            }
-            if (task.status === "in-progress") {
-                const outcome = taskStartSucceeded(task.id, true);
-                return { content: [{ type: "text", text: `✅ Task already started: ${taskRef} — ${task.title} (in-progress)\nstarted: true` }], details: { ...task, ...outcome, task } };
-            }
-            const [project, phases, focus] = await Promise.all([st.loadProject(), st.loadAllPhases(), st.loadResume()]);
-            const eligibility = checkExplicitTaskStart(features, phases, task.id, project.workDeviations);
-            if (!eligibility.eligible)
-                return taskStartFailure(taskStartDenied("START_NOT_ALLOWED", eligibility.reason, ["Resolve the reported task readiness condition, then retry task_start."], { taskId: task.id }), { eligibility });
-            const selection = recommendNextTask(features, phases, project.workDeviations, focus?.currentPhaseId);
-            if (selection.kind === "conflict") {
-                return taskStartFailure(taskStartDenied("ACTIVE_TASK_CONFLICT", selection.reason, ["Pause or reconcile the active tasks.", `Retry task_start ${taskRef}.`], { taskId: task.id }), { selection });
-            }
-            if (selection.kind === "active" && selection.candidate?.task.id !== task.id) {
-                const activeRef = `${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")}`;
-                return taskStartFailure(taskStartDenied("ACTIVE_TASK_CONFLICT", `${activeRef} is active; ${taskRef} was not started.`, [`Use task_switch to snapshot and pause ${activeRef}.`, `Retry task_start ${taskRef}.`], { taskId: task.id }), { selection });
-            }
-            let resumeProposal;
-            if (selection.kind === "resume" && selection.candidate && selection.candidate.task.id !== 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 resumeRef = `${formatPhaseRef(resumeTask.phase.number, featureNumberOfPhase(resumeTask.phase, features))}/T${String(resumeTask.task.number).padStart(3, "0")}`;
-                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: resumeRef,
-                    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.
-            // The output order is feature + its requirements, then phase + its requirements.
-            const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
-            const [phaseWithRequirements, featureRequirements] = await Promise.all([
-                st.loadPhaseWithRequirements(found.phase.id),
-                parentFeature ? st.linkedRequirementsForFeature(parentFeature.id) : Promise.resolve([]),
-            ]);
-            const phaseContext = buildPhaseContextBlock(phaseWithRequirements, parentFeature, phaseWithRequirements.linkedRequirements ?? [], featureRequirements);
-            const advisory = selection.candidate && selection.candidate.task.id !== task.id
-                ? selection.kind === "resume"
-                    ? `\n\n${resumeProposal ? resumeProposal.text : `⚠️ Resume advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} has a saved checkpoint. Evaluate its resume context before continuing with this explicit task request. Explicit task request honored.`}`
-                    : `\n\n⚠️ Priority advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} is the automatic recommendation. Explicit task request honored.`
-                : "";
-            const now = nowISO();
-            let startedTask;
-            if (task.pauseSnapshot) {
-                startedTask = await st.resumeTask(found.phase.id, found.task.id, now);
-            }
-            else {
-                await st.updatePhase(found.phase.id, (phase) => {
-                    const t = phase.tasks.find((x) => x.id === found.task.id);
-                    if (!t)
+                };
+                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 taskStartFailure(taskStartDenied("PROJECT_GUIDELINES_READ_REQUIRED", `Project Guidelines must be read before task work. Current state: ${projectGuidelinesReadState}.`, piContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, true, !requirementsReady, `Retry task_start ${taskRef}`), { taskId: task.id }), { projectGuidelinesReadState, contextEligibility });
+                }
+                if (!contextEligibility.eligible) {
+                    return taskStartFailure(taskStartDenied("CONTEXT_READ_REQUIRED", `Required context reads are incomplete or stale. ${contextEligibility.reason}`, piContextReadActions(contextEligibility, { task: taskRef, phase: phaseRef, ...(featureRef ? { feature: featureRef } : {}) }, false, !requirementsReady, `Retry task_start ${taskRef}`), { taskId: task.id }), { contextEligibility });
+                }
+                if (!requirementsReady) {
+                    return taskStartFailure(taskStartDenied("REQUIREMENTS_READ_REQUIRED", `Linked requirements were not read; the task remains unchanged. ${requirementEligibility.reason}`, [`requirement_list with phaseRef=${phaseRef}`, `Retry task_start ${taskRef}`], { taskId: task.id, requirementIds: linkedRequirementIds }), { requirementEligibility });
+                }
+                if (!hasValidSessionAttestation(contextInput)) {
+                    await st.recordContextRead({
+                        sessionId: plannerSessionId,
+                        phaseId: found.phase.id,
+                        taskId: task.id,
+                        ...(found.phase.featureId ? { featureId: found.phase.featureId } : {}),
+                        requirementIds: linkedRequirementIds,
+                    });
+                }
+                if (task.status === "in-progress") {
+                    const outcome = taskStartSucceeded(task.id, true);
+                    return { content: [{ type: "text", text: `✅ Task already started: ${taskRef} — ${task.title} (in-progress)\nstarted: true` }], details: { ...task, ...outcome, task } };
+                }
+                const [phases, focus] = await Promise.all([st.loadAllPhases(), st.loadResume()]);
+                const eligibility = checkExplicitTaskStart(features, phases, task.id, project.workDeviations);
+                if (!eligibility.eligible)
+                    return taskStartFailure(taskStartDenied("START_NOT_ALLOWED", eligibility.reason, ["Resolve the reported task readiness condition, then retry task_start."], { taskId: task.id }), { eligibility });
+                const selection = recommendNextTask(features, phases, project.workDeviations, focus?.currentPhaseId, plannerSessionId);
+                if (selection.kind === "conflict") {
+                    return taskStartFailure(taskStartDenied("ACTIVE_TASK_CONFLICT", selection.reason, ["Pause or reconcile the active tasks.", `Retry task_start ${taskRef}.`], { taskId: task.id }), { selection });
+                }
+                if (selection.kind === "active" && selection.candidate?.task.id !== task.id) {
+                    const activeRef = `${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")}`;
+                    return taskStartFailure(taskStartDenied("ACTIVE_TASK_CONFLICT", `${activeRef} is active; ${taskRef} was not started.`, [`Use task_switch to snapshot and pause ${activeRef}.`, `Retry task_start ${taskRef}.`], { taskId: task.id }), { selection });
+                }
+                let resumeProposal;
+                if (selection.kind === "resume" && selection.candidate && selection.candidate.task.id !== 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 resumeRef = `${formatPhaseRef(resumeTask.phase.number, featureNumberOfPhase(resumeTask.phase, features))}/T${String(resumeTask.task.number).padStart(3, "0")}`;
+                    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: resumeRef,
+                        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.
+                // The output order is feature + its requirements, then phase + its requirements.
+                const parentFeature = found.phase.featureId ? features.find((f) => f.id === found.phase.featureId) : undefined;
+                const [phaseWithRequirements, featureRequirements] = await Promise.all([
+                    st.loadPhaseWithRequirements(found.phase.id),
+                    parentFeature ? st.linkedRequirementsForFeature(parentFeature.id) : Promise.resolve([]),
+                ]);
+                const phaseContext = buildPhaseContextBlock(phaseWithRequirements, parentFeature, phaseWithRequirements.linkedRequirements ?? [], featureRequirements, found.task, project);
+                const advisory = selection.candidate && selection.candidate.task.id !== task.id
+                    ? selection.kind === "resume"
+                        ? `\n\n${resumeProposal ? resumeProposal.text : `⚠️ Resume advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} has a saved checkpoint. Evaluate its resume context before continuing with this explicit task request. Explicit task request honored.`}`
+                        : `\n\n⚠️ Priority advisory: ${formatPhaseRef(selection.candidate.phase.number, featureNumberOfPhase(selection.candidate.phase, features))}/T${String(selection.candidate.task.number).padStart(3, "0")} is the automatic recommendation. Explicit task request honored.`
+                    : "";
+                const now = nowISO();
+                let startedTask;
+                if (task.pauseSnapshot) {
+                    startedTask = await st.resumeTask(found.phase.id, found.task.id, now, plannerSessionId);
+                }
+                else {
+                    await st.updatePhase(found.phase.id, (phase) => {
+                        const t = phase.tasks.find((x) => x.id === found.task.id);
+                        if (!t)
+                            return phase;
+                        const previousStatus = t.status;
+                        applyTaskLifecycleDates(t, "in-progress", now);
+                        t.activeOwnerSession = plannerSessionId;
+                        t.statusLog = [...t.statusLog, {
+                                id: createChecklistItemId(t.id, t.statusLog.length + 1, `${previousStatus}-in-progress`),
+                                date: now, fromStatus: previousStatus, toStatus: "in-progress",
+                                title: `${previousStatus} → in-progress`, description: "",
+                            }];
+                        t.updatedAt = now;
+                        phase.updatedAt = now;
+                        startedTask = t;
                         return phase;
-                    const previousStatus = t.status;
-                    applyTaskLifecycleDates(t, "in-progress", now);
-                    t.statusLog = [...t.statusLog, {
-                            id: createChecklistItemId(t.id, t.statusLog.length + 1, `${previousStatus}-in-progress`),
-                            date: now, fromStatus: previousStatus, toStatus: "in-progress",
-                            title: `${previousStatus} → in-progress`, description: "",
-                        }];
-                    t.updatedAt = now;
-                    phase.updatedAt = now;
-                    startedTask = t;
-                    return phase;
-                });
-            }
-            await st.syncTaskStatusRollup(found.phase.id);
-            const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === task.id && deviation.state === "approved");
-            if (approvedDeviation)
-                await st.setWorkDeviationState(approvedDeviation.id, "active", now);
-            const resumedDeviation = project.workDeviations
-                .filter((deviation) => deviation.resumeTaskId === 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", now);
-            await st.writeGenerated();
-            const persistedTask = (await st.loadPhase(found.phase.id)).tasks.find((candidate) => candidate.id === task.id);
-            if (!startedTask || persistedTask?.status !== "in-progress") {
-                return taskStartFailure(taskStartDenied("PERSISTENCE_VERIFICATION_FAILED", `The lifecycle write could not be verified as in-progress for ${taskRef}.`, ["Inspect task_get for the persisted state and retry task_start only after resolving the persistence failure."], { taskId: task.id }));
-            }
-            const outcome = taskStartSucceeded(persistedTask.id);
-            return {
-                content: [{ type: "text", text: `✅ Task started: ${taskRef} — ${persistedTask.title} (in-progress)${persistedTask.shortId ? ` · ${persistedTask.shortId}` : ""}\nstarted: true${phaseContext}${advisory}` }],
-                details: { ...persistedTask, ...outcome, task: persistedTask },
-                ...(resumeProposal ? { resumeRequired: resumeProposal.structured } : {}),
-            };
+                    });
+                }
+                await st.syncTaskStatusRollup(found.phase.id);
+                const approvedDeviation = project.workDeviations.find((deviation) => deviation.temporaryTaskId === task.id && deviation.state === "approved");
+                if (approvedDeviation)
+                    await st.setWorkDeviationState(approvedDeviation.id, "active", now);
+                const resumedDeviation = project.workDeviations
+                    .filter((deviation) => deviation.resumeTaskId === 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", now);
+                await st.writeGenerated();
+                const persistedTask = (await st.loadPhase(found.phase.id)).tasks.find((candidate) => candidate.id === task.id);
+                if (!startedTask || persistedTask?.status !== "in-progress") {
+                    return taskStartFailure(taskStartDenied("PERSISTENCE_VERIFICATION_FAILED", `The lifecycle write could not be verified as in-progress for ${taskRef}.`, ["Inspect task_get for the persisted state and retry task_start only after resolving the persistence failure."], { taskId: task.id }));
+                }
+                const outcome = taskStartSucceeded(persistedTask.id);
+                return {
+                    content: [{ type: "text", text: `✅ Task started: ${taskRef} — ${persistedTask.title} (in-progress)${persistedTask.shortId ? ` · ${persistedTask.shortId}` : ""}\nstarted: true${phaseContext}${advisory}` }],
+                    details: { ...persistedTask, ...outcome, task: persistedTask },
+                    ...(resumeProposal ? { resumeRequired: resumeProposal.structured } : {}),
+                };
+            });
         },
     });
     pi.registerTool({
@@ -5036,10 +6281,24 @@ export default function planPiExtension(pi) {
             const st = await requirePlan(ctx);
             if (!st)
                 return { content: [{ type: "text", text: "No .planner/ found. Run plan_init first." }], details: { enabled: false, running: false } };
+            let preparation;
+            try {
+                preparation = await st.preparePlannerSession();
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: `Planner load aborted: ${error instanceof Error ? error.message : String(error)}` }], details: { errorCode: "PLANNER_SESSION_PREPARATION_FAILED", enabled: false, running: false } };
+            }
             enablePlannerSession();
             if (!server) {
                 await startServer(ctx, undefined, "lan").catch(() => { });
             }
+            const project = await st.loadProject();
+            if (project.projectGuidelines.content.trim()) {
+                await st.recordProjectGuidelinesRead({ sessionId: plannerSessionId });
+            }
+            const plannerSkill = await st.syncPlannerSkill();
+            await st.syncGrillMeSkill();
+            contextBlockDirty = true;
             const srv = server;
             let recap = "";
             try {
@@ -5048,7 +6307,9 @@ export default function planPiExtension(pi) {
             catch (e) {
                 recap = `(recap unavailable: ${e instanceof Error ? e.message : String(e)})`;
             }
-            return { content: [{ type: "text", text: recap }], details: { enabled: true, running: Boolean(srv), localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort } };
+            if (preparation.changed)
+                recap = `${preparation.legacyProjectContext.summary}\n\n${recap}`;
+            return { content: [{ type: "text", text: recap }], details: { enabled: true, running: Boolean(srv), localUrl: srv?.localUrl, lanUrl: srv?.lanUrl, port: lastKnownWebPort, preparation: preparation.legacyProjectContext, plannerSkill: { status: plannerSkill.status, customized: plannerSkill.customized, message: plannerSkill.message } } };
         },
     });
     pi.registerTool({
@@ -5109,6 +6370,7 @@ export default function planPiExtension(pi) {
             const recentActivity = activity.entries.slice(-3).reverse();
             const handoffs = await st.listHandoffs();
             const extensionRules = await st.extensionRules();
+            const plannerSkill = await st.syncPlannerSkill();
             const featureById = new Map(plan.features.features.map((feature) => [feature.id, feature]));
             const phaseById = new Map(plan.phases.map((phase) => [phase.id, phase]));
             const orderedPhases = [
@@ -5180,12 +6442,15 @@ export default function planPiExtension(pi) {
             const openQuestions = plan.phases
                 .flatMap((phase) => phase.openQuestions.map((question) => `[${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}] ${question}`))
                 .slice(0, 8);
-            const acceptedDecisions = [
-                ...project.acceptedDecisions.map((decision) => `[project] ${decision.title}`),
-                ...plan.features.features.flatMap((feature) => feature.acceptedDecisions.map((decision) => `[feature ${formatFeatureRef(feature.number)}] ${decision.title}`)),
-                ...plan.phases.flatMap((phase) => phase.acceptedDecisions.map((decision) => `[phase ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}] ${decision.title}`)),
-                ...plan.phases.flatMap((phase) => phase.tasks.flatMap((task) => task.acceptedDecisions.map((decision) => `[task ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}/T${pad(task.number)}] ${decision.title}`))),
-            ].slice(0, 20);
+            const acceptedDecisionContext = buildBoundedAcceptedDecisionContext([
+                { scope: "project", decisions: 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 ${formatPhaseRef(phase.number, featureNumberOfPhase(phase, plan.features.features))}/T${pad(task.number)}`,
+                    decisions: task.acceptedDecisions,
+                }))),
+            ]);
             const webServer = server;
             const webLocalUrl = webServer?.localUrl ?? webServer?.url ?? "";
             const webLanUrl = webServer?.lanUrl ?? "";
@@ -5223,11 +6488,11 @@ export default function planPiExtension(pi) {
                 "",
                 "Operational rules:",
                 "- Handoffs are context, not locks. Read the relevant handoff with handoff show <ref> before resuming.",
-                "- BEFORE work: call task_start or task_switch first so valid sessionInfo attestations are reused. If denied, perform only the missing/stale full reads listed in nextActions, in that order, then retry. A denial is an error with started=false; only details.started=true proves the task is in-progress. Only then touch code. AFTER finishing: task_complete with durable completion/verification evidence.",
+                "- BEFORE work: call task_start or task_switch first so valid sessionInfo attestations are reused. 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 project_guidelines_show, read that section and keep it in working memory while doing task work. A denial is an error with started=false; only details.started=true proves the task is in-progress. Only then touch code. AFTER finishing: task_complete with durable completion/verification evidence.",
                 "- Record every new decision or user-agreed modification in both the relevant feature and phase before treating the discussion as complete.",
                 "- Use task_update with motivation for blocked/canceled/rejected/deferred/waiting/planned(from non-planned).",
                 "- Planner ops (status/handoff/planner metadata) are NOT code edits; they are always allowed.",
-                "- Prioritize work: continue an in-progress task; otherwise choose ready work feature → phase → task by ascending priority, respecting dependencies and blocked/waiting states. Prefer shortId or F00x/P00x/T00x refs. Find via feature_list / phase_list / task_list; read one entity via *_get(full=true).",
+                "- Prioritize work: continue an in-progress task; otherwise choose ready work feature → phase → task by ascending priority, respecting dependencies and blocked/waiting states. Compact feature_list / phase_list / task_list surfaces expose priority markers; when browsing manually, follow the lowest visible priority first among ready siblings. Prefer shortId or F00x/P00x/T00x refs. Read one entity via *_get(full=true).",
                 "- If edit/write guard blocks you, start the right task or use an explicit bypass.",
                 ...(extensionRules.length > 0
                     ? [
@@ -5237,12 +6502,20 @@ export default function planPiExtension(pi) {
                     ]
                     : []),
                 "",
+                "Project-local planner usage skill (agent-only; keep in working context and do not quote in user recaps):",
+                plannerSkill.customized ? `Skill drift: ${plannerSkill.message}` : "",
+                plannerSkill.content,
+                "End project-local planner usage skill.",
+                "",
                 `Goal: ${project.goal || "(not set)"}`,
                 project.description ? `Description: ${project.description}` : "",
                 `Stack: ${[...project.technologies, ...project.tools].join(", ") || "(not set)"}`,
                 `Codebase: ${pkgSummary} | dirs=${profile?.directories.join(",") || "none"} | scanned=${profile?.scannedAt ?? "never"}`,
                 `Ambient: ${ambientSummary}`,
                 "",
+                "Project Guidelines (mandatory when present):",
+                project.projectGuidelines.content.trim() || "- (none)",
+                "",
                 "Global rules:",
                 project.globalRules.length ? project.globalRules.map((rule) => `- ${rule}`).join("\n") : "- (none)",
                 "",
@@ -5250,8 +6523,7 @@ export default function planPiExtension(pi) {
                 `Scope: ${project.scope.join(", ") || "(none)"}`,
                 `Out of scope: ${project.outOfScope.join(", ") || "(none)"}`,
                 "",
-                acceptedDecisions.length ? "Accepted decisions (do not re-litigate):" : "",
-                ...acceptedDecisions.map((decision) => `- ${decision}`),
+                acceptedDecisionContext.content,
                 openQuestions.length ? "" : "",
                 openQuestions.length ? "Open questions:" : "",
                 ...openQuestions.map((question) => `- ${question}`),