@agent-plan/core 0.2.25 → 0.2.27

package/dist/plan-store.js

@@ -1,5 +1,5 @@
-import { access, copyFile, mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { access, copyFile, lstat, mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { z, ZodError } from "zod";
 /** Canonical `.planner/.gitignore` content (P042 spec): ignore the `.local/`
@@ -14,15 +14,83 @@ const PLANNER_GITIGNORE = [
     "generated/",
     "",
 ].join("\n");
-import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, TaskPauseSnapshotSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, WorkDeviationSchema, } from "./schema.js";
-import { createFeatureId, createPhaseId, createRequirementId, createShortId, createStatusLogEntryId, createTaskId, formatPhaseRef, isLegacyPhaseId } from "./naming.js";
+import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, TaskSchema, TaskPauseSnapshotSchema, ProjectSchema, AcceptedDecisionSchema, RequirementSchema, RequirementsDocumentSchema, IdeaSchema, IdeasDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, WorkDeviationSchema, } from "./schema.js";
+import { createFeatureId, createIdeaId, createPhaseId, createRequirementId, createShortId, createStatusLogEntryId, createTaskId, formatFeatureRef, formatIdeaRef, formatPhaseRef, formatThreeDigitNumber, isLegacyPhaseId } from "./naming.js";
 import { deriveParentDisplay, fromCanonicalStatus } from "./display-status.js";
+import { buildHierarchicalDescriptionFreshness } from "./description-freshness.js";
 import { loadExtensionRules, PLANNER_EXTENSION_RULES } from "./planner-rules.js";
-import { applyHandoffContextSync, auditPhaseHandoff, } from "./handoff-context.js";
+import { loadProjectGrillMeSkill, syncProjectGrillMeSkill, syncProjectPlannerSkill } from "./planner-skill.js";
+import { applyLegacyProjectContextMigration, plannerSessionPreparationResult, previewLegacyProjectContextMigration, } from "./project-context-migration.js";
+import { applyHandoffContextSync, auditPhaseHandoff, externalizeOversizedHandoffContent, handoffContentHash, materializeHandoffMetadata, HandoffContractError, TARGET_HANDOFF_CONTENT_CHARS, validateHandoffReadBackVerification, } from "./handoff-context.js";
+import { withPlanRootWriteLock } from "./write-coordination.js";
+import { ALLOCATION_REGISTRY_VERSION, PLAN_SCHEMA_VERSION, SUPPORTED_ALLOCATION_KINDS, isSupportedAllocationKind, unsupportedAllocationKindDetails, } from "./runtime-diagnostics.js";
 function nowISO() {
     return new Date().toISOString();
 }
 const MAX_SESSION_INFO_ENTRIES = 16;
+function normalizeAcceptedDecisionCreate(input, acceptedAt) {
+    const title = input.title.trim();
+    if (!title) {
+        throw new PlanStoreError("Accepted decision title is required.", undefined, {
+            errorCode: "ACCEPTED_DECISION_TITLE_REQUIRED",
+            entity: "acceptedDecision",
+            operation: "create",
+        });
+    }
+    return AcceptedDecisionSchema.parse({
+        id: randomUUID(),
+        title,
+        decision: input.decision?.trim() ?? "",
+        rationale: input.rationale?.trim() ?? "",
+        implementationNotes: input.implementationNotes?.trim() ?? "",
+        acceptedAt,
+    });
+}
+function updateAcceptedDecisionList(decisions, decisionId, input) {
+    const mutableFields = ["title", "decision", "rationale", "implementationNotes"];
+    const receivedFields = mutableFields.filter((field) => input[field] !== undefined);
+    if (receivedFields.length === 0) {
+        throw new PlanStoreError("No mutable accepted decision fields were received.", undefined, {
+            errorCode: "NO_MUTABLE_FIELDS_RECEIVED",
+            entity: "acceptedDecision",
+            operation: "update",
+            mutableFields,
+        });
+    }
+    const index = decisions.findIndex((decision) => decision.id === decisionId);
+    if (index < 0) {
+        throw new PlanStoreError(`Accepted decision ${decisionId} not found.`, undefined, {
+            errorCode: "ACCEPTED_DECISION_NOT_FOUND",
+            entity: "acceptedDecision",
+            operation: "update",
+            decisionId,
+        });
+    }
+    const current = decisions[index];
+    const next = AcceptedDecisionSchema.parse({
+        ...current,
+        ...(input.title !== undefined ? { title: input.title.trim() } : {}),
+        ...(input.decision !== undefined ? { decision: input.decision.trim() } : {}),
+        ...(input.rationale !== undefined ? { rationale: input.rationale.trim() } : {}),
+        ...(input.implementationNotes !== undefined ? { implementationNotes: input.implementationNotes.trim() } : {}),
+    });
+    return {
+        decisions: decisions.map((decision) => decision.id === decisionId ? next : decision),
+        decision: next,
+    };
+}
+function deleteAcceptedDecisionFromList(decisions, decisionId) {
+    const decision = decisions.find((entry) => entry.id === decisionId);
+    if (!decision) {
+        throw new PlanStoreError(`Accepted decision ${decisionId} not found.`, undefined, {
+            errorCode: "ACCEPTED_DECISION_NOT_FOUND",
+            entity: "acceptedDecision",
+            operation: "delete",
+            decisionId,
+        });
+    }
+    return { decisions: decisions.filter((entry) => entry.id !== decisionId), decision };
+}
 function upsertSessionInfo(entity, sessionId, createdAt) {
     const nextInfo = [
         ...entity.sessionInfo.filter((entry) => entry.sessionId !== sessionId),
@@ -34,6 +102,29 @@ function upsertSessionInfo(entity, sessionId, createdAt) {
         || nextInfo.some((entry, index) => entry.sessionId !== entity.sessionInfo[index]?.sessionId || entry.createdAt !== entity.sessionInfo[index]?.createdAt);
     return changed ? { entity: { ...entity, sessionInfo: nextInfo }, changed: true } : { entity, changed: false };
 }
+function mergeSessionInfo(current, incoming) {
+    const newestBySession = new Map();
+    for (const entry of [...(current ?? []), ...(incoming ?? [])]) {
+        const prior = newestBySession.get(entry.sessionId);
+        if (!prior || entry.createdAt > prior)
+            newestBySession.set(entry.sessionId, entry.createdAt);
+    }
+    return [...newestBySession.entries()]
+        .map(([sessionId, createdAt]) => ({ sessionId, createdAt }))
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
+        .slice(0, MAX_SESSION_INFO_ENTRIES);
+}
+function assertSnapshotNotOlder(entity, entityId, incomingUpdatedAt, currentUpdatedAt) {
+    if (incomingUpdatedAt < currentUpdatedAt) {
+        throw new PlanStaleWriteError({
+            errorCode: "PLAN_STALE_WRITE",
+            entity,
+            entityId,
+            expectedUpdatedAt: incomingUpdatedAt,
+            actualUpdatedAt: currentUpdatedAt,
+        });
+    }
+}
 function resolveStoredFeatureId(features, ref) {
     const raw = ref?.trim();
     if (!raw)
@@ -65,6 +156,36 @@ export class PlanStoreError extends Error {
         this.name = "PlanStoreError";
     }
 }
+/** Optimistic-concurrency failure for a mutation based on an obsolete entity
+ * snapshot. Callers must reload, reapply only the intended fields, and retry. */
+export class PlanStaleWriteError extends PlanStoreError {
+    details;
+    code = "PLAN_STALE_WRITE";
+    constructor(details) {
+        super(`PLAN_STALE_WRITE: ${details.entity} ${details.entityId} changed after it was read (expected ${details.expectedUpdatedAt || "an unversioned snapshot"}, found ${details.actualUpdatedAt || "an unversioned current value"}). Reload the entity, reapply only the intended fields, and retry.`, undefined, details);
+        this.details = details;
+        this.name = "PlanStaleWriteError";
+    }
+}
+export function assertPlannerRevision(entity, entityId, expectedUpdatedAt, actualUpdatedAt) {
+    if (expectedUpdatedAt !== undefined && expectedUpdatedAt !== actualUpdatedAt) {
+        throw new PlanStaleWriteError({
+            errorCode: "PLAN_STALE_WRITE",
+            entity,
+            entityId,
+            expectedUpdatedAt,
+            actualUpdatedAt,
+        });
+    }
+}
+export class PlanUnsupportedAllocationKindError extends PlanStoreError {
+    code = "PLAN_UNSUPPORTED_ALLOCATION_KIND";
+    constructor(kind) {
+        const details = unsupportedAllocationKindDetails(kind);
+        super(`PLAN_UNSUPPORTED_ALLOCATION_KIND: allocation kind "${kind}" is not supported by the loaded Agent Plan runtime. Supported kinds: ${details.supportedKinds.join(", ")}. ${details.action}`, undefined, details);
+        this.name = "PlanUnsupportedAllocationKindError";
+    }
+}
 // ── Atomic file helpers ────────────────────────────────────────────────
 // Per-path write mutex: serializes concurrent writes to the SAME file so that
 // parallel tool calls (feature_create/phase_create/...) don't truncate JSON.
@@ -89,9 +210,9 @@ const CROSS_PROCESS_LOCK_RETRY_MS = 10;
 /** Allocation registry is deliberately outside the versioned plan. Git worktrees
  * share their common git dir, so reservations are serialized across branches
  * without rewriting project.json or unrelated planner entities. */
-const AllocationKindSchema = z.enum(["feature", "phase", "task"]);
+const AllocationKindSchema = z.enum(SUPPORTED_ALLOCATION_KINDS);
 const AllocationRegistrySchema = z.object({
-    version: z.literal(1),
+    version: z.literal(ALLOCATION_REGISTRY_VERSION),
     projectId: z.string().min(1),
     allocations: z.array(z.object({
         kind: AllocationKindSchema,
@@ -124,6 +245,34 @@ async function gitCommonDirFor(planRoot) {
         }
     }
 }
+async function readAllocationRegistry(path, projectId) {
+    const fallback = { version: ALLOCATION_REGISTRY_VERSION, projectId, allocations: [] };
+    const raw = await readFile(path, "utf8")
+        .then((content) => JSON.parse(content))
+        .catch(() => fallback);
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const allocations = raw.allocations;
+        if (Array.isArray(allocations)) {
+            const unsupported = allocations
+                .map((entry) => entry && typeof entry === "object" && !Array.isArray(entry) ? String(entry.kind ?? "") : "")
+                .filter((kind) => kind && !isSupportedAllocationKind(kind));
+            if (unsupported.length > 0)
+                throw new PlanUnsupportedAllocationKindError(unsupported[0]);
+        }
+    }
+    const parsed = AllocationRegistrySchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new PlanStoreError(`PLAN_RUNTIME_SCHEMA_INCOMPATIBLE: allocation registry ${path} is not compatible with the loaded Agent Plan runtime. Upgrade all Agent Plan packages and reload the harness before retrying the mutation.`, undefined, {
+            errorCode: "PLAN_RUNTIME_SCHEMA_INCOMPATIBLE",
+            schema: "allocationRegistry",
+            expectedVersion: ALLOCATION_REGISTRY_VERSION,
+            supportedKinds: SUPPORTED_ALLOCATION_KINDS,
+            path,
+            validationErrors: parsed.error.issues.map((issue) => ({ path: issue.path.join("."), message: issue.message })),
+        });
+    }
+    return parsed.data;
+}
 async function writeRegistry(path, registry) {
     await mkdir(dirname(path), { recursive: true });
     const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
@@ -191,7 +340,7 @@ export function withFeatureLock(featureId, fn) {
     });
 }
 async function atomicWriteText(path, raw, root) {
-    return withWriteLock(path, async () => {
+    const write = () => withWriteLock(path, async () => {
         writeBusyHook?.(true);
         const localRoot = root ? join(root, ".local") : undefined;
         const tmpDir = localRoot ? join(localRoot, "tmp") : dirname(path);
@@ -224,6 +373,7 @@ async function atomicWriteText(path, raw, root) {
             writeBusyHook?.(false);
         }
     });
+    return root ? withPlanRootWriteLock(root, write) : write();
 }
 async function atomicWriteJson(path, data, root) {
     return atomicWriteText(path, JSON.stringify(data, null, 2), root);
@@ -232,7 +382,7 @@ async function atomicUpdateJson(path, schema, updater, root) {
     // NOTE: write the file INLINE here, do NOT call atomicWriteJson/atomicWriteText,
     // because those re-acquire withWriteLock(path) — and we already hold it (below).
     // Re-entrant locking is not supported, so calling them would deadlock.
-    return withWriteLock(path, async () => {
+    const write = () => withWriteLock(path, async () => {
         const current = await readJson(path, schema);
         const updated = updater(current);
         const parsed = schema.parse(updated);
@@ -268,6 +418,7 @@ async function atomicUpdateJson(path, schema, updater, root) {
         }
         return parsed;
     });
+    return root ? withPlanRootWriteLock(root, write) : write();
 }
 /** Extract the first meaningful line of a handoff: skip blank lines, strip a
  *  leading markdown header (#), trim, and truncate to ~80 chars. */
@@ -557,22 +708,24 @@ export class PlanStore {
      *  planners). The caller is responsible for triggering any needed final
      *  sync explicitly. */
     async runAsBatch(fn) {
-        const prev = this.batchInProgress;
-        this.batchInProgress = true;
-        try {
-            return await fn();
-        }
-        finally {
-            this.batchInProgress = prev;
-        }
+        return withPlanRootWriteLock(this.root, async () => {
+            const prev = this.batchInProgress;
+            this.batchInProgress = true;
+            try {
+                return await fn();
+            }
+            finally {
+                this.batchInProgress = prev;
+            }
+        });
     }
     /** Public batch wrapper used by the module-level migrateToUuids helper. */
     async runBatchForMigration(fn) {
         return this.runAsBatch(fn);
     }
-    /** Public batch wrapper: suspend autoSync (status rollup) for a sequence of
-     *  writes. Use for priority-only reorders so they don't recompute phase/feature
-     *  status (a reorder must not flip a partially-done feature to in-progress). */
+    /** Public root-scoped write transaction. It serializes the whole sequence
+     *  across processes and suspends autoSync for nested writes. Use for composite
+     *  mutations and priority reorders that must not be interleaved. */
     async runBatch(fn) {
         return this.runAsBatch(fn);
     }
@@ -584,7 +737,7 @@ export class PlanStore {
         // Numbers are a STABLE global sequence (assigned once at create from project.nextTaskNumber).
         // Do NOT renumber here — renumbering would break references after deletions.
         const normalized = tasks.map((task) => {
-            const descriptionUpdatedAt = task.description && !task.descriptionUpdatedAt
+            const descriptionUpdatedAt = (task.description || task.descriptionRef) && !task.descriptionUpdatedAt
                 ? task.createdAt
                 : task.descriptionUpdatedAt;
             const normalizedStatus = task.status === "paused" ? "planned" : task.status;
@@ -594,11 +747,13 @@ export class PlanStore {
                 fromStatus: entry.fromStatus === "paused" ? "planned" : entry.fromStatus,
                 toStatus: entry.toStatus === "paused" ? "planned" : entry.toStatus,
             }));
+            const activeOwnerSession = normalizedStatus === "in-progress" ? task.activeOwnerSession?.trim() ?? "" : "";
             if (descriptionUpdatedAt !== task.descriptionUpdatedAt
                 || normalizedStatus !== task.status
                 || pauseSnapshot !== task.pauseSnapshot
+                || activeOwnerSession !== task.activeOwnerSession
                 || statusLog.some((entry, index) => entry !== task.statusLog[index])) {
-                return { ...task, descriptionUpdatedAt, status: normalizedStatus, pauseSnapshot, statusLog };
+                return { ...task, descriptionUpdatedAt, status: normalizedStatus, pauseSnapshot, statusLog, activeOwnerSession };
             }
             return task;
         });
@@ -623,17 +778,56 @@ export class PlanStore {
     /** Stamp description edits independently from generic entity mutations.
      * Legacy entities cannot reveal their historical description-edit time, so
      * their creation time is the earliest truthful fallback. */
-    stampDescriptionUpdatedAt(entity, previousDescription, timestamp) {
-        if (!entity.description)
+    stampDescriptionUpdatedAt(entity, previousDescription, previousDescriptionRef, timestamp) {
+        if (!entity.description && !entity.descriptionRef)
             return { ...entity, descriptionUpdatedAt: "" };
-        if (previousDescription === undefined || previousDescription !== entity.description) {
+        if (previousDescription === undefined
+            || previousDescription !== entity.description
+            || previousDescriptionRef !== entity.descriptionRef) {
             return { ...entity, descriptionUpdatedAt: timestamp };
         }
         return entity.descriptionUpdatedAt ? entity : { ...entity, descriptionUpdatedAt: entity.createdAt };
     }
+    stampProjectGuidelinesUpdatedAt(project, previousContent, timestamp) {
+        const nextContent = project.projectGuidelines.content.trim();
+        const nextGuidelines = {
+            content: nextContent,
+            updatedAt: project.projectGuidelines.updatedAt,
+            sessionInfo: project.projectGuidelines.sessionInfo,
+        };
+        if (!nextContent) {
+            return {
+                ...project,
+                projectGuidelines: {
+                    ...nextGuidelines,
+                    updatedAt: "",
+                    sessionInfo: [],
+                },
+            };
+        }
+        if (previousContent === undefined || previousContent !== nextContent) {
+            return {
+                ...project,
+                projectGuidelines: {
+                    ...nextGuidelines,
+                    updatedAt: timestamp,
+                },
+            };
+        }
+        if (nextGuidelines.updatedAt) {
+            return { ...project, projectGuidelines: nextGuidelines };
+        }
+        return {
+            ...project,
+            projectGuidelines: {
+                ...nextGuidelines,
+                updatedAt: timestamp,
+            },
+        };
+    }
     normalizeFeaturesDocument(doc) {
         // Numbers are a STABLE global sequence (assigned once at create from project.nextFeatureNumber).
-        const features = doc.features.map((feature) => feature.description && !feature.descriptionUpdatedAt
+        const features = doc.features.map((feature) => (feature.description || feature.descriptionRef) && !feature.descriptionUpdatedAt
             ? { ...feature, descriptionUpdatedAt: feature.createdAt }
             : feature);
         return { doc: { ...doc, features }, changed: features.some((feature, index) => feature !== doc.features[index]) };
@@ -642,7 +836,7 @@ export class PlanStore {
         const { tasks, changed } = this.normalizeTasks(phase.tasks);
         const nextTaskIds = tasks.map((task) => task.id);
         const taskIdsChanged = nextTaskIds.length !== phase.taskIds.length || nextTaskIds.some((id, index) => id !== phase.taskIds[index]);
-        const descriptionUpdatedAt = phase.description && !phase.descriptionUpdatedAt ? phase.createdAt : phase.descriptionUpdatedAt;
+        const descriptionUpdatedAt = (phase.description || phase.descriptionRef) && !phase.descriptionUpdatedAt ? phase.createdAt : phase.descriptionUpdatedAt;
         const descriptionTimestampChanged = descriptionUpdatedAt !== phase.descriptionUpdatedAt;
         return {
             phase: {
@@ -780,6 +974,9 @@ export class PlanStore {
     requirementsPath() {
         return join(this.root, "requirements.json");
     }
+    ideasPath() {
+        return join(this.root, "ideas.json");
+    }
     featuresPath() {
         return join(this.root, "features.json");
     }
@@ -790,10 +987,11 @@ export class PlanStore {
         return join(this.featuresDir(), `${featureId}.json`);
     }
     withFeaturesLock(fn) {
-        // Sentinel-keyed mutex (the features dir path) serializing all feature
-        // mutations so read-modify-write via updateFeatures is race-free and the
-        // one-time legacy→per-file migration never interleaves with a writer.
-        return withWriteLock(this.featuresDir(), fn);
+        // Root-scoped coordination prevents another process from interleaving a
+        // feature collection transaction. The sentinel lock retains per-collection
+        // serialization within this process; nested file writes are re-entrant at
+        // the planner-root layer.
+        return withPlanRootWriteLock(this.root, () => withWriteLock(this.featuresDir(), fn));
     }
     /** Idempotent one-time migration: if a legacy features.json exists, split it
      *  into features/<id>.json (one per feature) and remove the legacy file.
@@ -946,6 +1144,11 @@ export class PlanStore {
             name: projectName,
             goal: "",
             description: "",
+            projectGuidelines: {
+                content: "",
+                updatedAt: "",
+                sessionInfo: [],
+            },
             webPort: 0,
             scope: [],
             outOfScope: [],
@@ -967,6 +1170,7 @@ export class PlanStore {
             workDeviations: [],
         });
         await this.saveRequirements({ requirements: [] });
+        await this.saveIdeas({ nextIdeaNumber: 1, ideas: [] });
         await this.saveFeatures({ features: [] });
         await this.saveResume({
             updatedAt: nowISO(),
@@ -985,6 +1189,8 @@ export class PlanStore {
         // never causes git conflicts. The canonical source is plan-core; this file
         // is the per-project copy / override point, loaded at planner startup.
         await writeFile(join(this.root, "rules.json"), JSON.stringify({ extensionRules: PLANNER_EXTENSION_RULES }, null, 2), "utf-8");
+        await this.syncPlannerSkill();
+        await this.syncGrillMeSkill();
         // Write a README stub
         const readme = [
             "# Project Plan",
@@ -994,8 +1200,11 @@ export class PlanStore {
             "## Structure",
             "",
             "- `manifest.json` — metadata",
+            "- `SKILL.md` — managed cross-harness planner operating guide",
+            "- `skills/grill-me/SKILL.md` — managed idea-discussion interview skill",
             "- `project.json` — scope, rules, stack, tools",
             "- `requirements.json` — requirements and macro-tasks",
+            "- `ideas.json` — top-level Ideas Inbox (excluded from work status derivation)",
             "- `phases/` — one JSON file per phase",
             "- `generated/` — auto-generated markdown views (under `.local/`)",
             "- `schema/plan.schema.json` — JSON Schema for tooling",
@@ -1018,6 +1227,22 @@ export class PlanStore {
     async extensionRules() {
         return loadExtensionRules(this.root);
     }
+    /**
+     * Create or safely refresh the project-local planner usage skill. Explicit
+     * planner-load surfaces call this so unmodified managed copies follow the
+     * installed Agent Plan version while project customizations are preserved.
+     */
+    async syncPlannerSkill() {
+        return syncProjectPlannerSkill(this.root);
+    }
+    /** Safely create or refresh the project-local grill-me skill for Ideas. */
+    async syncGrillMeSkill() {
+        return syncProjectGrillMeSkill(this.root);
+    }
+    /** Load grill-me instructions only when an Ideas discussion requests them. */
+    async ideaDiscussionSkill() {
+        return loadProjectGrillMeSkill(this.root);
+    }
     /** Idempotently ensure `.planner/.gitignore` ignores `.local/` (and the
      *  canonical transient/derived patterns). Projects initialized before the
      *  `.local/` move either have no `.planner/.gitignore` or one with stale
@@ -1053,7 +1278,21 @@ export class PlanStore {
     /** Read-only manifest load. Upgrading legacy `.local` state is explicit
      * maintenance (`repair`), never an incidental side effect of opening a plan. */
     async loadManifest() {
-        const manifest = await readJson(this.manifestPath(), ManifestSchema);
+        let manifest;
+        try {
+            manifest = await readJson(this.manifestPath(), ManifestSchema);
+        }
+        catch (error) {
+            if (error instanceof PlanStoreError && error.details?.validationErrors) {
+                throw new PlanStoreError(`PLAN_RUNTIME_SCHEMA_INCOMPATIBLE: manifest ${this.manifestPath()} is not compatible with the loaded Agent Plan runtime. Expected manifest schemaVersion ${PLAN_SCHEMA_VERSION}. Upgrade all Agent Plan packages and reload the harness before retrying the operation.`, error, {
+                    ...error.details,
+                    errorCode: "PLAN_RUNTIME_SCHEMA_INCOMPATIBLE",
+                    schema: "manifest",
+                    expectedVersion: PLAN_SCHEMA_VERSION,
+                });
+            }
+            throw error;
+        }
         const timestamp = await readJson(this.timestampPath(), z.object({ updatedAt: TimestampSchema })).catch(() => undefined);
         return timestamp ? { ...manifest, updatedAt: timestamp.updatedAt } : manifest;
     }
@@ -1077,10 +1316,13 @@ export class PlanStore {
      * Worktrees in the same clone share `.git/agent-plan/allocations`, guarded by
      * the same cross-process lock used for atomic writes. The registry reserves
      * numbers/short IDs before an entity file is written, so parallel branches
-     * cannot allocate the same F/P/T or shortId. Existing entities are never
+     * cannot allocate the same F/P/T/I or shortId. Existing entities are never
      * rewritten; cross-clone coordination requires a shared allocator service.
      */
     async allocateEntityIdentity(kind, entityId) {
+        if (!isSupportedAllocationKind(String(kind)))
+            throw new PlanUnsupportedAllocationKindError(String(kind));
+        const supportedKind = kind;
         const project = await this.loadProject();
         const manifest = await this.loadManifest();
         const commonGitDir = await gitCommonDirFor(this.root);
@@ -1088,32 +1330,41 @@ export class PlanStore {
             ? join(commonGitDir, "agent-plan", "allocations", `${manifest.projectId}.json`)
             : join(this.localRoot(), "allocations", `${manifest.projectId}.json`);
         return withWriteLock(registryPath, async () => {
-            const registry = AllocationRegistrySchema.parse(await readFile(registryPath, "utf8")
-                .then(JSON.parse)
-                .catch(() => ({ version: 1, projectId: manifest.projectId, allocations: [] })));
+            const registry = await readAllocationRegistry(registryPath, manifest.projectId);
             if (registry.projectId !== manifest.projectId)
                 throw new PlanStoreError(`allocation registry project mismatch: ${registryPath}`);
-            const prior = registry.allocations.find((entry) => entry.kind === kind && entry.entityId === entityId);
+            const prior = registry.allocations.find((entry) => entry.kind === supportedKind && entry.entityId === entityId);
             if (prior)
                 return { number: prior.number, shortId: prior.shortId };
             const phases = await this.loadAllPhases();
             const features = (await this.loadFeatures()).features;
-            const canonical = kind === "feature"
+            const ideasDocument = await this.loadIdeas();
+            const ideas = ideasDocument.ideas;
+            const canonical = supportedKind === "feature"
                 ? features.map((feature) => ({ number: feature.number, shortId: feature.shortId }))
-                : kind === "phase"
+                : supportedKind === "phase"
                     ? phases.map((phase) => ({ number: phase.number, shortId: phase.shortId }))
-                    : phases.flatMap((phase) => phase.tasks.map((task) => ({ number: task.number, shortId: task.shortId })));
-            const usedNumbers = new Set([...canonical.map((entry) => entry.number), ...registry.allocations.filter((entry) => entry.kind === kind).map((entry) => entry.number)]);
-            const counter = kind === "feature" ? project.nextFeatureNumber : kind === "phase" ? project.nextPhaseNumber : project.nextTaskNumber;
+                    : supportedKind === "task"
+                        ? phases.flatMap((phase) => phase.tasks.map((task) => ({ number: task.number, shortId: task.shortId })))
+                        : ideas.map((idea) => ({ number: idea.number, shortId: idea.shortId }));
+            const usedNumbers = new Set([...canonical.map((entry) => entry.number), ...registry.allocations.filter((entry) => entry.kind === supportedKind).map((entry) => entry.number)]);
+            const counter = supportedKind === "feature"
+                ? project.nextFeatureNumber
+                : supportedKind === "phase"
+                    ? project.nextPhaseNumber
+                    : supportedKind === "task"
+                        ? project.nextTaskNumber
+                        : ideasDocument.nextIdeaNumber;
             let number = Math.max(1, counter);
             while (usedNumbers.has(number))
                 number += 1;
             const allShortIds = new Set([
                 ...features.map((feature) => feature.shortId),
                 ...phases.flatMap((phase) => [phase.shortId, ...phase.tasks.map((task) => task.shortId)]),
+                ...ideas.map((idea) => idea.shortId),
                 ...registry.allocations.map((entry) => entry.shortId),
             ].filter(Boolean));
-            const allocation = { kind, entityId, number, shortId: createShortId(allShortIds, `${kind}:${entityId}`) };
+            const allocation = { kind: supportedKind, entityId, number, shortId: createShortId(allShortIds, `${supportedKind}:${entityId}`) };
             registry.allocations.push(allocation);
             await writeRegistry(registryPath, registry);
             return { number: allocation.number, shortId: allocation.shortId };
@@ -1124,6 +1375,7 @@ export class PlanStore {
     async allocFeatureNumber() { return this.allocateLegacyNumber("feature"); }
     async allocPhaseNumber() { return this.allocateLegacyNumber("phase"); }
     async allocTaskNumber() { return this.allocateLegacyNumber("task"); }
+    async allocIdeaNumber() { return this.allocateLegacyNumber("idea"); }
     async allocateLegacyNumber(kind) {
         const id = `legacy-${kind}-${randomUUID()}`;
         return (await this.allocateEntityIdentity(kind, id)).number;
@@ -1316,6 +1568,18 @@ export class PlanStore {
             return { requirements: [] };
         }
     }
+    async loadIdeas() {
+        try {
+            const document = await readJson(this.ideasPath(), IdeasDocumentSchema);
+            return {
+                ...document,
+                ideas: [...document.ideas].sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
+            };
+        }
+        catch {
+            return { nextIdeaNumber: 1, ideas: [] };
+        }
+    }
     async linkedRequirementsForPhase(phaseId) {
         const requirements = await this.loadRequirements();
         return requirements.requirements.filter((requirement) => requirement.linkedPhaseIds.includes(phaseId));
@@ -1390,16 +1654,25 @@ export class PlanStore {
         return deriveParentDisplay(childStatuses);
     }
     async loadAll() {
-        const [manifest, project, requirements, phases] = await Promise.all([
+        const [manifest, project, requirements, ideas, phases] = await Promise.all([
             this.loadManifest(),
             this.loadProject(),
             this.loadRequirements(),
+            this.loadIdeas(),
             this.loadAllPhases(),
         ]);
         const rawFeatures = await this.loadRawFeatures();
         const features = rawFeatures.map((f) => ({ ...f, status: this.deriveFeatureStatus(f.id, phases) }));
         const normalized = this.normalizeStructureSnapshot({ features }, phases);
-        return { manifest, project, requirements, phases: normalized.phases, features: normalized.features };
+        return { manifest, project, requirements, ideas, phases: normalized.phases, features: normalized.features };
+    }
+    /**
+     * Preview child-to-parent description drift without rewriting user-authored
+     * feature or phase prose. Callers decide whether to reconcile each parent.
+     */
+    async previewDescriptionReconciliation() {
+        const workspace = await this.loadAll();
+        return buildHierarchicalDescriptionFreshness(workspace.features.features, workspace.phases);
     }
     /** Migrate legacy non-feature-scoped phase ids to feature-scoped ids and repair
      *  dangling feature.phaseIds references. Idempotent. */
@@ -1760,11 +2033,17 @@ export class PlanStore {
         const duplicateShortIds = [...sidCounts.entries()].filter(([, c]) => c > 1).map(([id]) => id);
         return { duplicatePhaseIds, danglingPhaseIds, duplicateShortIds };
     }
-    /** A handoff remains active while any task needs work. Its automatic end-of-
-     * phase lifecycle is deliberately narrower than canonical display status:
-     * every task must be done or canceled (not merely derived "rejected"). */
-    hasCompletedHandoffLifecycle(tasks) {
-        return tasks.length > 0 && tasks.every((task) => task.status === "done" || task.status === "canceled");
+    /** Return the archive reason for a canonical terminal phase outcome. Handoff
+     * lifecycle follows the derived phase status, so rejected tasks cannot leave
+     * an operational handoff active or merely hidden from the active list. */
+    terminalHandoffReason(phase) {
+        if (phase.status === "done")
+            return "phase-done";
+        if (phase.status === "rejected")
+            return "phase-rejected";
+        if (phase.status === "canceled")
+            return "phase-canceled";
+        return null;
     }
     derivePhaseStatus(tasks) {
         if (tasks.length === 0)
@@ -1837,14 +2116,14 @@ export class PlanStore {
         // (serve.ts, adapters) that invoke it after mutations.
         return [];
     }
-    /** Auto-clear a phase's handoff only when every task is terminal as done or
-     *  canceled. This covers an all-canceled phase too, whose legacy canonical
-     *  derived status is "rejected". Returns the composite ref when cleared. */
+    /** Auto-clear a phase's handoff for every canonical terminal derived status.
+     * Returns the composite ref when an active handoff was archived. */
     async syncTaskStatusRollup(phaseId) {
         const phase = await this.loadPhase(phaseId);
         let cleared = null;
-        if (this.hasCompletedHandoffLifecycle(phase.tasks) && phase.handoff !== "") {
-            await this.clearPhaseHandoff(phaseId, "phase-done");
+        const terminalReason = this.terminalHandoffReason(phase);
+        if (terminalReason && phase.handoff !== "") {
+            await this.clearPhaseHandoff(phaseId, terminalReason);
             const features = await this.loadFeatures();
             const feature = features.features.find((f) => f.id === phase.featureId);
             cleared = formatPhaseRef(phase.number, feature?.number);
@@ -1906,11 +2185,52 @@ export class PlanStore {
         }
     }
     // ── Savers ───────────────────────────────────────────────────────────
-    async updateProject(updater) {
-        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, updater, this.root);
+    async updateProject(updater, options = {}) {
+        const timestamp = nowISO();
+        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, (current) => {
+            assertPlannerRevision("project", "project-guidelines", options.expectedGuidelinesUpdatedAt, current.projectGuidelines.updatedAt);
+            const previousGuidelines = current.projectGuidelines.content;
+            const candidate = updater(current);
+            return this.stampProjectGuidelinesUpdatedAt(candidate, previousGuidelines, timestamp);
+        }, this.root);
         await this.maybeAutoSync();
         return updated;
     }
+    /** Preview the explicit, lossless migration from legacy project rule and
+     * decision fields into Project Guidelines and structured accepted decisions. */
+    async previewLegacyProjectContextMigration() {
+        return previewLegacyProjectContextMigration(await readJson(this.projectPath(), ProjectSchema));
+    }
+    /** Prepare an explicit planner session before recap/context delivery.
+     * Ordinary entity reads remain non-mutating. */
+    async preparePlannerSession() {
+        return plannerSessionPreparationResult(await this.migrateLegacyProjectContext());
+    }
+    /** Apply and verify the legacy project-context migration. Callers must invoke
+     * this only from an explicit preparation or compatibility-recovery flow. */
+    async migrateLegacyProjectContext() {
+        const original = await readJson(this.projectPath(), ProjectSchema);
+        const acceptedAt = nowISO();
+        const expected = applyLegacyProjectContextMigration(original, acceptedAt);
+        if (!expected.applied)
+            return expected;
+        await this.updateProject(() => expected.project);
+        const persisted = await readJson(this.projectPath(), ProjectSchema);
+        const migratedDecisionIds = new Set(expected.preview.acceptedDecisionAdditions.map((decision) => decision.id));
+        const persistedDecisionIds = new Set(persisted.acceptedDecisions.map((decision) => decision.id));
+        const verified = persisted.projectGuidelines.content === expected.preview.resultingGuidelinesContent
+            && persisted.globalRules.length === 0
+            && persisted.workflowRules.beforePhaseStart.length === 0
+            && persisted.workflowRules.beforeTaskStart.length === 0
+            && persisted.workflowRules.afterPhaseComplete.length === 0
+            && persisted.decisions.length === 0
+            && [...migratedDecisionIds].every((id) => persistedDecisionIds.has(id));
+        if (!verified) {
+            await atomicWriteJson(this.projectPath(), ProjectSchema.parse(original), this.root);
+            throw new PlanStoreError("Legacy project-context migration failed persisted read-back verification; the original project was restored.");
+        }
+        return { applied: true, preview: expected.preview, project: persisted };
+    }
     /** Persist an explicitly approved work deviation without coupling it to a harness. */
     async addWorkDeviation(deviation) {
         const deviations = [...(await this.loadWorkDeviations()), deviation];
@@ -1938,10 +2258,11 @@ export class PlanStore {
             // Updaters commonly mutate `current` in place, so snapshot descriptions
             // before invoking them rather than comparing object references afterward.
             const previousDescriptions = new Map(current.features.map((feature) => [feature.id, feature.description]));
+            const previousDescriptionRefs = new Map(current.features.map((feature) => [feature.id, feature.descriptionRef]));
             const timestamp = nowISO();
             const candidate = updater(current);
             const stamped = {
-                features: candidate.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), timestamp)),
+                features: candidate.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), previousDescriptionRefs.get(feature.id), timestamp)),
             };
             const upd = this.normalizeFeaturesDocument(stamped).doc;
             await this.saveFeaturesRaw(upd);
@@ -1950,11 +2271,176 @@ export class PlanStore {
         await this.maybeAutoSync();
         return updated;
     }
+    /** Field-scoped feature mutation against the lock-reloaded canonical document. */
+    async updateFeature(featureId, updater, options = {}) {
+        let persisted;
+        await this.updateFeatures((document) => {
+            const index = document.features.findIndex((feature) => feature.id === featureId);
+            if (index < 0)
+                throw new PlanStoreError(`Feature ${featureId} not found.`);
+            const current = document.features[index];
+            assertPlannerRevision("feature", featureId, options.expectedUpdatedAt, current.updatedAt);
+            const next = updater(structuredClone(current));
+            if (next.id !== current.id)
+                throw new PlanStoreError("Feature identity cannot be changed by updateFeature.");
+            document.features[index] = next;
+            persisted = next;
+            return document;
+        });
+        return persisted;
+    }
     async updateRequirements(updater) {
         const updated = await atomicUpdateJson(this.requirementsPath(), RequirementsDocumentSchema, updater, this.root);
         await this.maybeAutoSync();
         return updated;
     }
+    /** Field-scoped requirement mutation against the lock-reloaded canonical document. */
+    async updateRequirement(requirementId, updater, options = {}) {
+        let persisted;
+        await this.updateRequirements((document) => {
+            const index = document.requirements.findIndex((requirement) => requirement.id === requirementId);
+            if (index < 0)
+                throw new PlanStoreError(`Requirement ${requirementId} not found.`);
+            const current = document.requirements[index];
+            assertPlannerRevision("requirement", requirementId, options.expectedUpdatedAt, current.updatedAt);
+            const next = RequirementSchema.parse(updater(structuredClone(current)));
+            if (next.id !== current.id)
+                throw new PlanStoreError("Requirement identity cannot be changed by updateRequirement.");
+            document.requirements[index] = next;
+            persisted = next;
+            return document;
+        });
+        return persisted;
+    }
+    async ensureIdeasFileForWrite() {
+        try {
+            await access(this.ideasPath());
+        }
+        catch {
+            await atomicWriteJson(this.ideasPath(), IdeasDocumentSchema.parse({ nextIdeaNumber: 1, ideas: [] }), this.root);
+        }
+    }
+    async updateIdeas(updater) {
+        await this.ensureIdeasFileForWrite();
+        const updated = await atomicUpdateJson(this.ideasPath(), IdeasDocumentSchema, (current) => {
+            const candidate = IdeasDocumentSchema.parse(updater(current));
+            const maxNumber = candidate.ideas.reduce((max, idea) => Math.max(max, idea.number), 0);
+            return {
+                ...candidate,
+                nextIdeaNumber: Math.max(candidate.nextIdeaNumber, maxNumber + 1),
+                ideas: [...candidate.ideas].sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
+            };
+        }, this.root);
+        await this.touchTimestamp();
+        await this.maybeAutoSync();
+        return updated;
+    }
+    async createIdea(input, timestamp = nowISO()) {
+        const id = createIdeaId();
+        const { number, shortId } = await this.allocateEntityIdentity("idea", id);
+        const idea = IdeaSchema.parse({
+            id,
+            number,
+            shortId,
+            title: input.title.trim(),
+            description: input.description?.trim() ?? "",
+            promotion: null,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        });
+        await this.updateIdeas((document) => ({
+            nextIdeaNumber: Math.max(document.nextIdeaNumber, number + 1),
+            ideas: [...document.ideas, idea],
+        }));
+        return idea;
+    }
+    async updateIdea(ideaId, input, timestamp = nowISO()) {
+        let updated;
+        await this.updateIdeas((document) => {
+            const existing = document.ideas.find((idea) => idea.id === ideaId);
+            if (!existing)
+                throw new PlanStoreError(`Idea ${ideaId} not found.`);
+            updated = IdeaSchema.parse({
+                ...existing,
+                ...(input.title !== undefined ? { title: input.title.trim() } : {}),
+                ...(input.description !== undefined ? { description: input.description.trim() } : {}),
+                updatedAt: timestamp,
+            });
+            return {
+                ...document,
+                ideas: document.ideas.map((idea) => idea.id === ideaId ? updated : idea),
+            };
+        });
+        return updated;
+    }
+    async deleteIdea(ideaId) {
+        let deleted = false;
+        await this.updateIdeas((document) => {
+            deleted = document.ideas.some((idea) => idea.id === ideaId);
+            return deleted
+                ? { ...document, ideas: document.ideas.filter((idea) => idea.id !== ideaId) }
+                : document;
+        });
+        return deleted;
+    }
+    async resolveIdeaPromotionTarget(targetType, targetId) {
+        const phases = await this.loadAllPhases();
+        const features = (await this.loadFeatures()).features;
+        if (targetType === "feature") {
+            const feature = features.find((candidate) => candidate.id === targetId);
+            if (!feature)
+                throw new PlanStoreError(`Idea promotion target feature ${targetId} not found.`);
+            return formatFeatureRef(feature.number);
+        }
+        if (targetType === "phase") {
+            const phase = phases.find((candidate) => candidate.id === targetId);
+            if (!phase)
+                throw new PlanStoreError(`Idea promotion target phase ${targetId} not found.`);
+            const feature = features.find((candidate) => candidate.id === phase.featureId);
+            return formatPhaseRef(phase.number, feature?.number);
+        }
+        for (const phase of phases) {
+            const task = phase.tasks.find((candidate) => candidate.id === targetId);
+            if (!task)
+                continue;
+            const feature = features.find((candidate) => candidate.id === phase.featureId);
+            return `${formatPhaseRef(phase.number, feature?.number)}/T${formatThreeDigitNumber(task.number)}`;
+        }
+        throw new PlanStoreError(`Idea promotion target task ${targetId} not found.`);
+    }
+    async promoteIdea(ideaId, input) {
+        const targetRef = await this.resolveIdeaPromotionTarget(input.targetType, input.targetId);
+        const promotedAt = input.promotedAt ?? nowISO();
+        let promoted;
+        await this.updateIdeas((document) => {
+            const existing = document.ideas.find((idea) => idea.id === ideaId);
+            if (!existing)
+                throw new PlanStoreError(`Idea ${ideaId} not found.`);
+            if (existing.promotion) {
+                if (existing.promotion.targetType === input.targetType && existing.promotion.targetId === input.targetId) {
+                    promoted = existing;
+                    return document;
+                }
+                throw new PlanStoreError(`Idea ${formatIdeaRef(existing.number)} is already promoted to ${existing.promotion.targetRef}.`);
+            }
+            const promotion = {
+                targetType: input.targetType,
+                targetId: input.targetId,
+                targetRef,
+                promotedAt,
+            };
+            promoted = IdeaSchema.parse({
+                ...existing,
+                promotion,
+                updatedAt: promotedAt,
+            });
+            return {
+                ...document,
+                ideas: document.ideas.map((idea) => idea.id === ideaId ? promoted : idea),
+            };
+        });
+        return promoted;
+    }
     /**
      * Persist completion of one full task → phase → feature → requirements read
      * sequence. Session metadata is deliberately the only changed entity field:
@@ -2023,12 +2509,18 @@ export class PlanStore {
             }
             catch (error) {
                 const rollbackErrors = [];
-                if (featureChanged && nextFeature)
-                    await this.saveFeature(originalFeatures.features[featureIndex]).catch((rollbackError) => rollbackErrors.push(rollbackError));
-                if (phaseChanged)
-                    await this.savePhase(originalPhase).catch((rollbackError) => rollbackErrors.push(rollbackError));
-                if (requirementsChanged)
-                    await this.saveRequirements(originalRequirements).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                if (featureChanged && nextFeature) {
+                    await atomicWriteJson(this.featurePath(nextFeature.id), originalFeatures.features[featureIndex], this.root)
+                        .catch((rollbackError) => rollbackErrors.push(rollbackError));
+                }
+                if (phaseChanged) {
+                    await atomicWriteJson(this.phasePath(originalPhase.id), PhaseSchema.parse(originalPhase), this.root)
+                        .catch((rollbackError) => rollbackErrors.push(rollbackError));
+                }
+                if (requirementsChanged) {
+                    await atomicWriteJson(this.requirementsPath(), originalRequirements, this.root)
+                        .catch((rollbackError) => rollbackErrors.push(rollbackError));
+                }
                 if (rollbackErrors.length > 0)
                     throw new AggregateError([error, ...rollbackErrors], "Context-read attestation failed and rollback was incomplete.");
                 throw error;
@@ -2039,21 +2531,57 @@ export class PlanStore {
             return { phase, ...(feature ? { feature } : {}), requirements, createdAt };
         });
     }
+    async recordProjectGuidelinesRead(input) {
+        const sessionId = input.sessionId.trim();
+        if (!sessionId)
+            throw new PlanStoreError("Project-guidelines attestation requires a non-empty sessionId.");
+        const createdAt = TimestampSchema.parse(input.createdAt ?? nowISO());
+        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, (project) => {
+            if (!project.projectGuidelines.content.trim())
+                return project;
+            const result = upsertSessionInfo(project.projectGuidelines, sessionId, createdAt);
+            return result.changed ? { ...project, projectGuidelines: result.entity } : project;
+        }, this.root);
+        await this.maybeAutoSync();
+        return updated;
+    }
     async saveProject(project) {
         // Runtime workDeviations live in .local/deviations.json (T299); never
         // persist them here so shared project.json stays stable across worktrees.
-        const parsed = ProjectSchema.parse({ ...project, workDeviations: [] });
-        await atomicWriteJson(this.projectPath(), parsed, this.root);
+        await withPlanRootWriteLock(this.root, async () => {
+            const previous = await readJson(this.projectPath(), ProjectSchema).catch(() => null);
+            const withMergedGuidelineReads = previous
+                ? {
+                    ...project,
+                    projectGuidelines: {
+                        ...project.projectGuidelines,
+                        sessionInfo: mergeSessionInfo(previous.projectGuidelines.sessionInfo, project.projectGuidelines.sessionInfo),
+                    },
+                }
+                : project;
+            const stamped = this.stampProjectGuidelinesUpdatedAt(withMergedGuidelineReads, previous?.projectGuidelines.content, nowISO());
+            const parsed = ProjectSchema.parse({ ...stamped, workDeviations: [] });
+            await atomicWriteJson(this.projectPath(), parsed, this.root);
+        });
         await this.touchTimestamp();
         await this.maybeAutoSync();
     }
     async saveFeatures(features) {
         await this.withFeaturesLock(async () => {
             await this.migrateLegacy();
-            const previousDescriptions = new Map((await this.loadRawFeatures()).map((feature) => [feature.id, feature.description]));
+            const currentFeatures = await this.loadRawFeatures();
+            const currentById = new Map(currentFeatures.map((feature) => [feature.id, feature]));
             const timestamp = nowISO();
             await this.saveFeaturesRaw({
-                features: features.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), timestamp)),
+                features: features.features.map((feature) => {
+                    const current = currentById.get(feature.id);
+                    if (current)
+                        assertSnapshotNotOlder("feature", feature.id, feature.updatedAt, current.updatedAt);
+                    const merged = current
+                        ? { ...feature, sessionInfo: mergeSessionInfo(current.sessionInfo, feature.sessionInfo) }
+                        : feature;
+                    return this.stampDescriptionUpdatedAt(merged, current?.description, current?.descriptionRef, timestamp);
+                }),
             });
         });
         await this.touchTimestamp();
@@ -2088,63 +2616,115 @@ export class PlanStore {
         await this.withFeaturesLock(async () => {
             await this.migrateLegacy();
             const previous = await readJson(this.featurePath(feature.id), FeatureSchema).catch(() => null);
+            if (previous)
+                assertSnapshotNotOlder("feature", feature.id, feature.updatedAt, previous.updatedAt);
             await mkdir(this.featuresDir(), { recursive: true });
-            const parsed = FeatureSchema.parse(this.stampDescriptionUpdatedAt(feature, previous?.description, nowISO()));
+            const merged = previous
+                ? { ...feature, sessionInfo: mergeSessionInfo(previous.sessionInfo, feature.sessionInfo) }
+                : feature;
+            const parsed = FeatureSchema.parse(this.stampDescriptionUpdatedAt(merged, previous?.description, previous?.descriptionRef, nowISO()));
             await atomicWriteJson(this.featurePath(parsed.id), parsed, this.root);
         });
         await this.touchTimestamp();
         await this.maybeAutoSync();
     }
     async saveRequirements(reqs) {
-        const parsed = RequirementsDocumentSchema.parse(reqs);
-        await atomicWriteJson(this.requirementsPath(), parsed, this.root);
+        await withPlanRootWriteLock(this.root, async () => {
+            const current = await readJson(this.requirementsPath(), RequirementsDocumentSchema).catch(() => null);
+            const currentById = new Map((current?.requirements ?? []).map((requirement) => [requirement.id, requirement]));
+            const parsed = RequirementsDocumentSchema.parse({
+                requirements: reqs.requirements.map((requirement) => {
+                    const previous = currentById.get(requirement.id);
+                    if (previous)
+                        assertSnapshotNotOlder("requirement", requirement.id, requirement.updatedAt, previous.updatedAt);
+                    return previous
+                        ? { ...requirement, sessionInfo: mergeSessionInfo(previous.sessionInfo, requirement.sessionInfo) }
+                        : requirement;
+                }),
+            });
+            await atomicWriteJson(this.requirementsPath(), parsed, this.root);
+        });
         await this.touchTimestamp();
     }
-    async savePhase(phase) {
-        const previous = await this.loadPhase(phase.id).catch(() => null);
-        const timestamp = nowISO();
-        const features = await this.loadRawFeatures();
-        const resolvedFeatureId = resolveStoredFeatureId(features, phase.featureId);
-        // Referential integrity: if a featureId is present but cannot be resolved
-        // to a known feature, REJECT — never persist an orphan featureId.
-        // NOTE: a missing/empty featureId is intentionally ALLOWED here so that
-        // legacy migrations, repair, and feature-delete (unlink) can persist phases
-        // without a feature yet. The hard "featureId required" gate lives at the
-        // adapter boundary (Pi phase_create/task_create and MCP planner-phase-add/
-        // planner-task-add), which is where user-facing creation happens.
-        if (phase.featureId && phase.featureId.trim() && !resolvedFeatureId) {
-            throw new PlanStoreError(`Cannot save phase "${phase.title}": featureId "${phase.featureId}" does not match any existing feature. Use a valid feature UUID, F00x ref, or shortId.`);
-        }
-        const normalizedInput = resolvedFeatureId && resolvedFeatureId !== phase.featureId
-            ? { ...phase, featureId: resolvedFeatureId }
-            : phase;
-        const previousTaskDescriptions = new Map((previous?.tasks ?? []).map((task) => [task.id, task.description]));
-        const timestamped = this.stampDescriptionUpdatedAt(normalizedInput, previous?.description, timestamp);
-        timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), timestamp));
-        const parsed = PhaseSchema.parse(this.normalizePhaseDocument(timestamped).phase);
-        await mkdir(this.phasesDir(), { recursive: true });
-        await atomicWriteJson(this.phasePath(parsed.id), parsed, this.root);
+    async saveIdeas(ideas) {
+        await withPlanRootWriteLock(this.root, async () => {
+            const parsed = IdeasDocumentSchema.parse(ideas);
+            const maxNumber = parsed.ideas.reduce((max, idea) => Math.max(max, idea.number), 0);
+            await atomicWriteJson(this.ideasPath(), {
+                ...parsed,
+                nextIdeaNumber: Math.max(parsed.nextIdeaNumber, maxNumber + 1),
+                ideas: [...parsed.ideas].sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
+            }, this.root);
+        });
+        await this.touchTimestamp();
+    }
+    async savePhase(phase, options = {}) {
+        await withPlanRootWriteLock(this.root, async () => {
+            const previous = await this.loadPhase(phase.id).catch(() => null);
+            if (previous) {
+                assertPlannerRevision("phase", phase.id, options.expectedUpdatedAt, previous.updatedAt);
+                if (options.expectedUpdatedAt === undefined) {
+                    assertSnapshotNotOlder("phase", phase.id, phase.updatedAt, previous.updatedAt);
+                }
+            }
+            const timestamp = nowISO();
+            const features = await this.loadRawFeatures();
+            const resolvedFeatureId = resolveStoredFeatureId(features, phase.featureId);
+            // Referential integrity: if a featureId is present but cannot be resolved
+            // to a known feature, REJECT — never persist an orphan featureId.
+            // NOTE: a missing/empty featureId is intentionally ALLOWED here so that
+            // legacy migrations, repair, and feature-delete (unlink) can persist phases
+            // without a feature yet. The hard "featureId required" gate lives at the
+            // adapter boundary (Pi phase_create/task_create and MCP planner-phase-add/
+            // planner-task-add), which is where user-facing creation happens.
+            if (phase.featureId && phase.featureId.trim() && !resolvedFeatureId) {
+                throw new PlanStoreError(`Cannot save phase "${phase.title}": featureId "${phase.featureId}" does not match any existing feature. Use a valid feature UUID, F00x ref, or shortId.`);
+            }
+            const normalizedInput = resolvedFeatureId && resolvedFeatureId !== phase.featureId
+                ? { ...phase, featureId: resolvedFeatureId }
+                : phase;
+            const previousTaskDescriptions = new Map((previous?.tasks ?? []).map((task) => [task.id, task.description]));
+            const previousTaskDescriptionRefs = new Map((previous?.tasks ?? []).map((task) => [task.id, task.descriptionRef]));
+            const mergedPhase = previous
+                ? { ...normalizedInput, sessionInfo: mergeSessionInfo(previous.sessionInfo, normalizedInput.sessionInfo) }
+                : normalizedInput;
+            const previousTasksById = new Map((previous?.tasks ?? []).map((task) => [task.id, task]));
+            const timestamped = this.stampDescriptionUpdatedAt(mergedPhase, previous?.description, previous?.descriptionRef, timestamp);
+            timestamped.tasks = timestamped.tasks.map((task) => {
+                const previousTask = previousTasksById.get(task.id);
+                const mergedTask = previousTask
+                    ? { ...task, sessionInfo: mergeSessionInfo(previousTask.sessionInfo, task.sessionInfo) }
+                    : task;
+                return this.stampDescriptionUpdatedAt(mergedTask, previousTaskDescriptions.get(task.id), previousTaskDescriptionRefs.get(task.id), timestamp);
+            });
+            const parsed = PhaseSchema.parse(this.normalizePhaseDocument(timestamped).phase);
+            await mkdir(this.phasesDir(), { recursive: true });
+            await atomicWriteJson(this.phasePath(parsed.id), parsed, this.root);
+        });
         await this.touchTimestamp();
         await this.maybeAutoSync();
     }
     /** Atomic read-modify-write on a single phase file. Serializes concurrent
      *  task_create / phase_update calls on the SAME phaseId so batch operations
      *  don't lose tasks (last-write-wins race condition). */
-    async updatePhase(phaseId, updater) {
+    async updatePhase(phaseId, updater, options = {}) {
         const features = await this.loadRawFeatures();
         // Augment the raw (on-disk) phase with its DERIVED status before handing it
         // to the updater, so updaters that read 'phase.status' see the truth. The
         // returned object's 'status' is stripped by PhaseSchema.parse (status is
         // not persisted); the return value is re-derived for the caller.
         const raw = await atomicUpdateJson(this.phasePath(phaseId), PhaseSchema, (rawPhase) => {
+            assertPlannerRevision("phase", phaseId, options.expectedUpdatedAt, rawPhase.updatedAt);
             const current = { ...rawPhase, status: this.derivePhaseStatus(rawPhase.tasks) };
             // The updater may mutate `current`, therefore snapshot descriptions first.
             const previousDescription = current.description;
+            const previousDescriptionRef = current.descriptionRef;
             const previousTaskDescriptions = new Map(current.tasks.map((task) => [task.id, task.description]));
+            const previousTaskDescriptionRefs = new Map(current.tasks.map((task) => [task.id, task.descriptionRef]));
             const timestamp = nowISO();
             const next = updater(current);
-            const timestamped = this.stampDescriptionUpdatedAt(next, previousDescription, timestamp);
-            timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), timestamp));
+            const timestamped = this.stampDescriptionUpdatedAt(next, previousDescription, previousDescriptionRef, timestamp);
+            timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), previousTaskDescriptionRefs.get(task.id), timestamp));
             const resolvedFeatureId = resolveStoredFeatureId(features, timestamped.featureId);
             // Referential integrity: reject orphan featureId.
             if (timestamped.featureId && timestamped.featureId.trim() && !resolvedFeatureId) {
@@ -2159,6 +2739,109 @@ export class PlanStore {
         await this.maybeAutoSync();
         return { ...raw, status: this.derivePhaseStatus(raw.tasks) };
     }
+    /** Field-scoped task mutation against the lock-reloaded canonical phase. */
+    async updateTask(phaseId, taskId, updater, options = {}) {
+        let persisted;
+        const phase = await this.updatePhase(phaseId, (currentPhase) => {
+            const index = currentPhase.tasks.findIndex((task) => task.id === taskId);
+            if (index < 0)
+                throw new PlanStoreError(`Task ${taskId} does not belong to phase ${phaseId}.`);
+            const current = currentPhase.tasks[index];
+            assertPlannerRevision("task", taskId, options.expectedUpdatedAt, current.updatedAt);
+            const next = TaskSchema.parse(updater(structuredClone(current)));
+            if (next.id !== current.id || next.phaseId !== current.phaseId) {
+                throw new PlanStoreError("Task identity and parent phase cannot be changed by updateTask.");
+            }
+            currentPhase.tasks[index] = next;
+            currentPhase.updatedAt = next.updatedAt;
+            persisted = next;
+            return currentPhase;
+        });
+        return { phase, task: persisted };
+    }
+    async createAcceptedDecision(owner, input, acceptedAt = nowISO()) {
+        const decision = normalizeAcceptedDecisionCreate(input, acceptedAt);
+        if (owner.kind === "project") {
+            await this.updateProject((project) => ({ ...project, acceptedDecisions: [...project.acceptedDecisions, decision] }));
+            return decision;
+        }
+        if (owner.kind === "feature") {
+            await this.updateFeature(owner.featureId, (feature) => ({ ...feature, acceptedDecisions: [...feature.acceptedDecisions, decision], updatedAt: acceptedAt }));
+            return decision;
+        }
+        if (owner.kind === "phase") {
+            await this.updatePhase(owner.phaseId, (phase) => ({ ...phase, acceptedDecisions: [...phase.acceptedDecisions, decision], updatedAt: acceptedAt }));
+            return decision;
+        }
+        await this.updateTask(owner.phaseId, owner.taskId, (task) => ({ ...task, acceptedDecisions: [...task.acceptedDecisions, decision], updatedAt: acceptedAt }));
+        return decision;
+    }
+    async updateAcceptedDecision(owner, decisionId, input) {
+        let updated;
+        if (owner.kind === "project") {
+            await this.updateProject((project) => {
+                const result = updateAcceptedDecisionList(project.acceptedDecisions, decisionId, input);
+                updated = result.decision;
+                return { ...project, acceptedDecisions: result.decisions };
+            });
+            return updated;
+        }
+        if (owner.kind === "feature") {
+            await this.updateFeature(owner.featureId, (feature) => {
+                const result = updateAcceptedDecisionList(feature.acceptedDecisions, decisionId, input);
+                updated = result.decision;
+                return { ...feature, acceptedDecisions: result.decisions, updatedAt: nowISO() };
+            });
+            return updated;
+        }
+        if (owner.kind === "phase") {
+            await this.updatePhase(owner.phaseId, (phase) => {
+                const result = updateAcceptedDecisionList(phase.acceptedDecisions, decisionId, input);
+                updated = result.decision;
+                return { ...phase, acceptedDecisions: result.decisions, updatedAt: nowISO() };
+            });
+            return updated;
+        }
+        await this.updateTask(owner.phaseId, owner.taskId, (task) => {
+            const result = updateAcceptedDecisionList(task.acceptedDecisions, decisionId, input);
+            updated = result.decision;
+            return { ...task, acceptedDecisions: result.decisions, updatedAt: nowISO() };
+        });
+        return updated;
+    }
+    async deleteAcceptedDecision(owner, decisionId) {
+        let deleted;
+        if (owner.kind === "project") {
+            await this.updateProject((project) => {
+                const result = deleteAcceptedDecisionFromList(project.acceptedDecisions, decisionId);
+                deleted = result.decision;
+                return { ...project, acceptedDecisions: result.decisions };
+            });
+            return deleted;
+        }
+        if (owner.kind === "feature") {
+            await this.updateFeature(owner.featureId, (feature) => {
+                const result = deleteAcceptedDecisionFromList(feature.acceptedDecisions, decisionId);
+                deleted = result.decision;
+                return { ...feature, acceptedDecisions: result.decisions, updatedAt: nowISO() };
+            });
+            return deleted;
+        }
+        if (owner.kind === "phase") {
+            await this.updatePhase(owner.phaseId, (phase) => {
+                const result = deleteAcceptedDecisionFromList(phase.acceptedDecisions, decisionId);
+                deleted = result.decision;
+                return { ...phase, acceptedDecisions: result.decisions, updatedAt: nowISO() };
+            });
+            return deleted;
+        }
+        await this.updateTask(owner.phaseId, owner.taskId, (task) => {
+            const result = deleteAcceptedDecisionFromList(task.acceptedDecisions, decisionId);
+            deleted = result.decision;
+            return { ...task, acceptedDecisions: result.decisions, updatedAt: nowISO() };
+        });
+        return deleted;
+    }
     /** Save a durable resume checkpoint without introducing a separate canonical task status. */
     async pauseTask(phaseId, taskId, input) {
         const snapshot = TaskPauseSnapshotSchema.parse(input);
@@ -2181,6 +2864,7 @@ export class PlanStore {
                 status: "planned",
                 pauseSnapshot: snapshot,
                 pauseHistory: [...task.pauseHistory, snapshot],
+                activeOwnerSession: "",
                 statusLog: [...task.statusLog, {
                         id: createStatusLogEntryId(),
                         date: snapshot.pausedAt,
@@ -2197,7 +2881,7 @@ export class PlanStore {
         return paused;
     }
     /** Resume a checkpointed task without resetting its original startedAt. */
-    async resumeTask(phaseId, taskId, timestamp = nowISO()) {
+    async resumeTask(phaseId, taskId, timestamp = nowISO(), ownerSessionId = "") {
         let resumed;
         await this.updatePhase(phaseId, (phase) => {
             const task = phase.tasks.find((candidate) => candidate.id === taskId);
@@ -2214,6 +2898,7 @@ export class PlanStore {
                 ...task,
                 status: "in-progress",
                 pauseSnapshot: null,
+                activeOwnerSession: ownerSessionId.trim() || task.activeOwnerSession,
                 startedAt: task.startedAt || timestamp,
                 statusLog: [...task.statusLog, {
                         id: createStatusLogEntryId(),
@@ -2230,11 +2915,164 @@ export class PlanStore {
         });
         return resumed;
     }
+    /** Reopen a completed task atomically without changing any other task.
+     * Completion evidence remains in the description and status log; completedAt is
+     * cleared because the task is once again active work. */
+    async reopenTask(phaseId, taskId, options) {
+        if (!options.confirmed) {
+            throw new PlanStoreError("Task reopening requires explicit confirmation.", undefined, { errorCode: "TASK_REOPEN_CONFIRMATION_REQUIRED", taskId });
+        }
+        const timestamp = options.timestamp ?? nowISO();
+        let reopened;
+        await this.updatePhase(phaseId, (phase) => {
+            const task = phase.tasks.find((candidate) => candidate.id === taskId);
+            if (!task)
+                throw new PlanStoreError(`Task ${taskId} does not belong to phase ${phaseId}.`, undefined, { errorCode: "TASK_NOT_FOUND", taskId });
+            if (task.status !== "done")
+                throw new PlanStoreError(`Task ${taskId} is not completed.`, undefined, { errorCode: "TASK_REOPEN_NOT_DONE", taskId });
+            reopened = {
+                ...task,
+                status: "in-progress",
+                completedAt: "",
+                pauseSnapshot: null,
+                activeOwnerSession: options.ownerSessionId?.trim() ?? "",
+                statusLog: [...task.statusLog, {
+                        id: createStatusLogEntryId(),
+                        date: timestamp,
+                        fromStatus: "done",
+                        toStatus: "in-progress",
+                        title: "done → in-progress (reopened)",
+                        description: "Reopened through the confirmed lifecycle operation; prior completion evidence is retained.",
+                    }],
+                updatedAt: timestamp,
+            };
+            phase.tasks = phase.tasks.map((candidate) => candidate.id === taskId ? reopened : candidate);
+            return phase;
+        });
+        return reopened;
+    }
+    /** Add a validated dependency edge from one task to another. */
+    async addTaskDependency(phaseId, taskId, dependencyId, timestamp = nowISO()) {
+        const phases = await this.loadAllPhases();
+        const tasks = phases.flatMap((phase) => phase.tasks.map((task) => ({ phase, task })));
+        const source = tasks.find((entry) => entry.phase.id === phaseId && entry.task.id === taskId);
+        const dependency = tasks.find((entry) => entry.task.id === dependencyId);
+        if (!source)
+            throw new PlanStoreError("Task not found.", undefined, { errorCode: "TASK_NOT_FOUND" });
+        if (!dependency)
+            throw new PlanStoreError("Dependency task not found.", undefined, { errorCode: "DEPENDENCY_TASK_NOT_FOUND" });
+        if (taskId === dependencyId)
+            throw new PlanStoreError("A task cannot depend on itself.", undefined, { errorCode: "DEPENDENCY_SELF" });
+        if (source.task.dependsOn.includes(dependencyId))
+            return source.task;
+        const graph = new Map(tasks.map(({ task }) => [task.id, [...task.dependsOn]]));
+        graph.set(taskId, [...(graph.get(taskId) ?? []), dependencyId]);
+        const visit = (id, path = new Set()) => { if (path.has(id))
+            return true; const next = new Set(path); next.add(id); return (graph.get(id) ?? []).some((child) => visit(child, next)); };
+        if (visit(taskId))
+            throw new PlanStoreError("Dependency would create a cycle.", undefined, { errorCode: "DEPENDENCY_CYCLE" });
+        return (await this.updateTask(phaseId, taskId, (task) => ({ ...task, dependsOn: [...task.dependsOn, dependencyId], updatedAt: timestamp }))).task;
+    }
+    /** Remove a dependency edge without affecting either task. */
+    async deleteTaskDependency(phaseId, taskId, dependencyId) {
+        return (await this.updateTask(phaseId, taskId, (task) => {
+            if (!task.dependsOn.includes(dependencyId))
+                throw new PlanStoreError("Dependency not found.", undefined, { errorCode: "DEPENDENCY_NOT_FOUND" });
+            return { ...task, dependsOn: task.dependsOn.filter((id) => id !== dependencyId), updatedAt: nowISO() };
+        })).task;
+    }
+    /** Create a planner-owned subtask with a stable ID under a task. */
+    async createSubtask(phaseId, taskId, input, timestamp = nowISO()) {
+        const title = input.title.trim();
+        if (!title)
+            throw new PlanStoreError("Subtask title is required.", undefined, { errorCode: "SUBTASK_TITLE_REQUIRED" });
+        let created;
+        await this.updateTask(phaseId, taskId, (task) => {
+            created = { id: randomUUID(), title, status: input.status ?? "planned", description: input.description?.trim() ?? "", createdAt: timestamp, updatedAt: timestamp };
+            task.subtasks = [...(task.subtasks ?? []), created];
+            return task;
+        });
+        return created;
+    }
+    /** Update a subtask by its parent task and planner-owned ID. */
+    async updateSubtask(phaseId, taskId, subtaskId, input, timestamp = nowISO()) {
+        let updated;
+        await this.updateTask(phaseId, taskId, (task) => {
+            const index = (task.subtasks ?? []).findIndex((subtask) => subtask.id === subtaskId);
+            if (index < 0)
+                throw new PlanStoreError(`Subtask ${subtaskId} was not found.`, undefined, { errorCode: "SUBTASK_NOT_FOUND" });
+            const current = task.subtasks[index];
+            if (input.title !== undefined && !input.title.trim())
+                throw new PlanStoreError("Subtask title is required.", undefined, { errorCode: "SUBTASK_TITLE_REQUIRED" });
+            updated = { ...current, ...(input.title !== undefined ? { title: input.title.trim() } : {}), ...(input.description !== undefined ? { description: input.description.trim() } : {}), ...(input.status !== undefined ? { status: input.status } : {}), updatedAt: timestamp };
+            task.subtasks = task.subtasks.map((candidate, candidateIndex) => candidateIndex === index ? updated : candidate);
+            return task;
+        });
+        return updated;
+    }
+    /** Delete a subtask by its planner-owned ID. */
+    async deleteSubtask(phaseId, taskId, subtaskId) {
+        await this.updateTask(phaseId, taskId, (task) => {
+            if (!(task.subtasks ?? []).some((subtask) => subtask.id === subtaskId))
+                throw new PlanStoreError(`Subtask ${subtaskId} was not found.`, undefined, { errorCode: "SUBTASK_NOT_FOUND" });
+            task.subtasks = task.subtasks.filter((subtask) => subtask.id !== subtaskId);
+            return task;
+        });
+    }
+    /** Reorder subtasks without changing their stable identities. */
+    async reorderSubtasks(phaseId, taskId, orderedIds) {
+        let ordered = [];
+        await this.updateTask(phaseId, taskId, (task) => {
+            const current = task.subtasks ?? [];
+            if (orderedIds.length !== current.length || new Set(orderedIds).size !== current.length || orderedIds.some((id) => !current.some((subtask) => subtask.id === id)))
+                throw new PlanStoreError("Subtask order must contain every existing subtask exactly once.", undefined, { errorCode: "SUBTASK_ORDER_INVALID" });
+            ordered = orderedIds.map((id) => current.find((subtask) => subtask.id === id));
+            task.subtasks = ordered;
+            return task;
+        });
+        return ordered;
+    }
     // ── Phase-scoped handoff (entity field, harness-agnostic) ────────────
     /** Get the handoff text for a phase ("" if none). Throws if phase missing. */
     async getPhaseHandoff(phaseId) {
         return (await this.loadPhase(phaseId)).handoff;
     }
+    async validateHandoffSupportingDocuments(documents) {
+        const docsRoot = resolve(this.root, "docs");
+        const metadata = [];
+        const contents = [];
+        const seen = new Set();
+        for (const document of documents) {
+            const normalizedPath = document.path.trim().replace(/\\/g, "/");
+            if (!/^\.planner\/docs\/.+\.md$/i.test(normalizedPath) || normalizedPath.includes("/../")) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document path must be a Markdown file under .planner/docs/: ${document.path}`, { path: document.path });
+            }
+            if (seen.has(normalizedPath)) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document appears more than once: ${normalizedPath}`, { path: normalizedPath });
+            }
+            seen.add(normalizedPath);
+            const target = resolve(this.root, normalizedPath.slice(".planner/".length));
+            if (!target.startsWith(`${docsRoot}${sep}`)) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document escapes .planner/docs/: ${normalizedPath}`, { path: normalizedPath });
+            }
+            const fileStat = await lstat(target).catch(() => null);
+            if (!fileStat || fileStat.isSymbolicLink() || !fileStat.isFile()) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document must be a regular file under .planner/docs/ (symlinks rejected): ${normalizedPath}`, { path: normalizedPath });
+            }
+            const content = await readFile(target, "utf8").catch(() => null);
+            if (content === null || !content.trim()) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document is missing or empty: ${normalizedPath}`, { path: normalizedPath });
+            }
+            metadata.push({
+                path: normalizedPath,
+                description: document.description.trim(),
+                contentHash: handoffContentHash(content),
+                contentLength: content.length,
+            });
+            contents.push(content);
+        }
+        return { metadata, contents };
+    }
     /** Audit one exact phase before preparing a handoff refresh. */
     async preparePhaseHandoff(phaseId) {
         const phase = await this.loadPhase(phaseId);
@@ -2252,6 +3090,9 @@ export class PlanStore {
     async refreshPhaseHandoff(phaseId, input) {
         return this.runAsBatch(async () => {
             const originalPhase = await this.loadPhase(phaseId);
+            if (this.terminalHandoffReason(originalPhase)) {
+                throw new PlanStoreError(`Cannot write a handoff on ${originalPhase.status} phase ${phaseId}; terminal phases have no pending handoff.`);
+            }
             if (!originalPhase.featureId)
                 throw new PlanStoreError(`Phase ${phaseId} has no parent feature; durable handoff context cannot be synchronized.`);
             const originalFeatures = await this.loadFeatures();
@@ -2259,41 +3100,113 @@ export class PlanStore {
             if (featureIndex < 0)
                 throw new PlanStoreError(`Parent feature ${originalPhase.featureId} not found for phase ${phaseId}.`);
             const timestamp = nowISO();
-            const applied = applyHandoffContextSync(originalPhase, originalFeatures.features[featureIndex], input, timestamp);
-            const nextFeatures = structuredClone(originalFeatures);
-            nextFeatures.features[featureIndex] = applied.feature;
+            const existingCreatedAt = originalPhase.handoff.match(/^Created at:\s*(\S+)\s*$/im)?.[1] ?? timestamp;
+            const materializedContent = materializeHandoffMetadata(input.content, input.reason, existingCreatedAt, timestamp);
+            let effectiveInput = { ...input, content: materializedContent };
+            if (materializedContent.length > TARGET_HANDOFF_CONTENT_CHARS) {
+                const stamp = timestamp.replace(/[:.]/g, "-");
+                const autoPath = `.planner/docs/handoff-p${String(originalPhase.number).padStart(3, "0")}-${stamp}.md`;
+                const externalized = externalizeOversizedHandoffContent(materializedContent, autoPath);
+                if (externalized.externalized) {
+                    const docsDir = resolve(this.root, "docs");
+                    await mkdir(docsDir, { recursive: true });
+                    const target = resolve(this.root, autoPath.slice(".planner/".length));
+                    if (!target.startsWith(`${docsDir}${sep}`)) {
+                        throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Auto-externalized supporting document escapes .planner/docs/: ${autoPath}`, { path: autoPath });
+                    }
+                    await writeFile(target, externalized.extendedContent, "utf8");
+                    const autoDoc = externalized.supportingDocument;
+                    effectiveInput = {
+                        ...input,
+                        content: externalized.content,
+                        supportingDocuments: [...(input.supportingDocuments ?? []), autoDoc],
+                    };
+                }
+            }
+            const verifiedSupportingDocuments = await this.validateHandoffSupportingDocuments(effectiveInput.supportingDocuments ?? []);
+            const verifiedInput = {
+                ...effectiveInput,
+                verifiedSupportingDocuments: verifiedSupportingDocuments.metadata,
+                verifiedSupportingDocumentContents: verifiedSupportingDocuments.contents,
+            };
+            const originalFeature = originalFeatures.features[featureIndex];
+            const applied = applyHandoffContextSync(originalPhase, originalFeature, verifiedInput, timestamp);
             try {
-                await this.saveFeatures(nextFeatures);
+                // Keep the transaction granular: only the parent feature and target phase
+                // belong to this handoff refresh. Rewriting the whole feature document can
+                // disturb unrelated feature containment metadata.
+                await this.saveFeature(applied.feature);
                 await this.savePhase(applied.phase);
+                const phase = await this.loadPhase(phaseId);
+                const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === originalPhase.featureId);
+                const persistedHash = handoffContentHash(phase.handoff);
+                if (phase.handoff !== applied.phase.handoff
+                    || !phase.handoffAudit
+                    || phase.handoffAudit.contentHash !== persistedHash
+                    || phase.handoffAudit.contentLength !== phase.handoff.length) {
+                    throw new HandoffContractError("HANDOFF_PERSISTENCE_VERIFICATION_FAILED", "The persisted handoff did not match the verified content. The write was rolled back.", { expectedHash: applied.phase.handoffAudit?.contentHash ?? "", actualHash: persistedHash });
+                }
+                return {
+                    phase,
+                    feature,
+                    updatedTaskIds: applied.updatedTaskIds,
+                    handoffUpdatedAt: phase.handoffUpdatedAt,
+                    handoffAudit: phase.handoffAudit,
+                };
             }
             catch (error) {
                 const rollbackErrors = [];
-                await this.saveFeatures(originalFeatures).catch((rollbackError) => rollbackErrors.push(rollbackError));
-                await this.savePhase(originalPhase).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                // Restore the exact parsed snapshots directly. Going through saveFeature /
+                // savePhase would restamp description freshness against the failed write.
+                await atomicWriteJson(this.featurePath(originalFeature.id), FeatureSchema.parse(originalFeature), this.root)
+                    .catch((rollbackError) => rollbackErrors.push(rollbackError));
+                await atomicWriteJson(this.phasePath(originalPhase.id), PhaseSchema.parse(originalPhase), this.root)
+                    .catch((rollbackError) => rollbackErrors.push(rollbackError));
                 if (rollbackErrors.length > 0) {
                     throw new AggregateError([error, ...rollbackErrors], "Handoff refresh failed and rollback was incomplete.");
                 }
                 throw error;
             }
-            const phase = await this.loadPhase(phaseId);
-            const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === originalPhase.featureId);
-            return { phase, feature, updatedTaskIds: applied.updatedTaskIds, handoffUpdatedAt: phase.handoffUpdatedAt };
         });
     }
-    /** Set the handoff text for a phase + stamp handoffUpdatedAt. A completed or
-     * canceled phase cannot receive a new operational handoff. Replacing an
-     * existing handoff archives the previous content as `superseded` first. */
+    /** Mark a persisted handoff resume-ready only after a separate full read-back
+     * has reconciled every required source and found no omissions. */
+    async verifyPhaseHandoffReadBack(phaseId, input) {
+        const timestamp = nowISO();
+        const phase = await this.updatePhase(phaseId, (current) => {
+            const sourceReviews = validateHandoffReadBackVerification(current, input);
+            return {
+                ...current,
+                handoffReadAt: timestamp,
+                handoffAudit: {
+                    ...current.handoffAudit,
+                    resumeReadyAt: timestamp,
+                    readBackSourceReviews: sourceReviews,
+                },
+            };
+        });
+        return {
+            phaseId: phase.id,
+            handoffUpdatedAt: phase.handoffUpdatedAt,
+            contentHash: phase.handoffAudit.contentHash,
+            resumeReadyAt: phase.handoffAudit.resumeReadyAt,
+            sourceReviews: phase.handoffAudit.readBackSourceReviews,
+        };
+    }
+    /** Set the handoff text for a phase + stamp handoffUpdatedAt. A terminal
+     * phase cannot receive a new operational handoff. Replacing an existing
+     * handoff archives the previous content as `superseded` first. */
     async setPhaseHandoff(phaseId, text) {
         const phase = await this.loadPhase(phaseId);
         const normalized = text.trim();
-        if (phase.status === "done" || phase.status === "canceled") {
-            throw new PlanStoreError(`Cannot write a handoff on ${phase.status} phase ${phaseId}; completed phases have no pending handoff.`);
+        if (this.terminalHandoffReason(phase)) {
+            throw new PlanStoreError(`Cannot write a handoff on ${phase.status} phase ${phaseId}; terminal phases have no pending handoff.`);
         }
         if (phase.handoff && normalized && phase.handoff !== normalized) {
             await this.clearPhaseHandoff(phaseId, "superseded");
         }
         const now = new Date().toISOString();
-        await this.updatePhase(phaseId, (current) => ({ ...current, handoff: normalized, handoffUpdatedAt: now }));
+        await this.updatePhase(phaseId, (current) => ({ ...current, handoff: normalized, handoffUpdatedAt: now, handoffAudit: null }));
     }
     /** Mark the phase handoff as read/acknowledged on recap (sets handoffReadAt).
      *  Does NOT clear it: read/load/show are non-mutating resume operations. */
@@ -2318,7 +3231,7 @@ export class PlanStore {
         }
         const phases = await this.loadAllPhases();
         const target = phases.find((p) => p.status === "in-progress")
-            ?? phases.find((p) => p.status !== "done" && p.status !== "canceled")
+            ?? phases.find((p) => !this.terminalHandoffReason(p))
             ?? null;
         if (!target)
             return { imported: false }; // no non-completed phase — leave file for a later run
@@ -2339,7 +3252,8 @@ export class PlanStore {
      *  metadata entry { file, clearedAt, reason } is prepended to handoffHistory
      *  (capped at 5; oldest file is deleted when trimmed). handoffUpdatedAt is
      *  left unchanged as an audit trail. If the handoff is empty, this is a no-op.
-     *  reason: "phase-done" | "manual" | "superseded" | "imported". */
+     *  reason: "phase-done" | "phase-rejected" | "phase-canceled" |
+     *  "manual" | "superseded" | "imported". */
     async clearPhaseHandoff(phaseId, reason = "manual") {
         await this.migrateLegacyHandoffArchive();
         const phase = await this.loadPhase(phaseId).catch(() => null);
@@ -2365,14 +3279,15 @@ export class PlanStore {
         }
         await this.updatePhase(phaseId, (p) => ({ ...p, handoff: "", handoffHistory: trimmed }));
     }
-    /** Archive stale handoffs only after every task in their phase is done or
-     * canceled. Idempotent: only non-empty phase.handoff values are moved. */
+    /** Archive stale handoffs for every canonical terminal phase outcome.
+     * Idempotent: only non-empty phase.handoff values are moved. */
     async archiveStaleHandoffs() {
         const phases = await this.loadAllPhases();
         let archived = 0;
         for (const phase of phases) {
-            if (this.hasCompletedHandoffLifecycle(phase.tasks) && phase.handoff) {
-                await this.clearPhaseHandoff(phase.id, "phase-done");
+            const reason = this.terminalHandoffReason(phase);
+            if (reason && phase.handoff) {
+                await this.clearPhaseHandoff(phase.id, reason);
                 archived += 1;
             }
         }
@@ -2383,8 +3298,8 @@ export class PlanStore {
         return this.runAsBatch(() => this.archiveStaleHandoffs());
     }
     /** List only active/pending phase handoffs, newest first. Handoffs from
-     * phases where every task is done/canceled are archived before returning. */
-    async listHandoffs() {
+     * canonically terminal phases are archived before returning. */
+    async listHandoffs(options = {}) {
         await this.archiveStaleHandoffs();
         const phases = await this.loadAllPhases();
         const features = await this.loadFeatures();
@@ -2394,7 +3309,7 @@ export class PlanStore {
             featureNumber.set(f.id, f.number);
         const out = [];
         for (const p of phases) {
-            if (!p.handoff || p.status === "done" || p.status === "canceled")
+            if (!p.handoff || this.terminalHandoffReason(p))
                 continue;
             if (p.featureId && !featureIds.has(p.featureId))
                 continue;
@@ -2405,7 +3320,13 @@ export class PlanStore {
                 compositeRef: formatPhaseRef(p.number, fnum),
                 updatedAt: p.handoffUpdatedAt || p.updatedAt,
                 firstLine: handoffFirstLine(p.handoff),
-                content: p.handoff,
+                ...(options.includeContent ? { content: p.handoff } : {}),
+                auditVersion: p.handoffAudit?.version ?? null,
+                contentLength: p.handoff.length,
+                contentHash: p.handoffAudit?.contentHash ?? handoffContentHash(p.handoff),
+                verifiedAt: p.handoffAudit?.verifiedAt ?? "",
+                resumeReady: Boolean(p.handoffAudit?.resumeReadyAt),
+                resumeReadyAt: p.handoffAudit?.resumeReadyAt ?? "",
             });
         }
         out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
@@ -2503,14 +3424,15 @@ export class PlanStore {
         await unlink(join(this.root, ".local", "backups", "phases", `${phaseId}.json.bak`)).catch(() => { });
     }
     // ── Workspace-level operations ─────────────────────────────────────
-    /** Load the full workspace (manifest + phases + project + requirements + features) */
+    /** Load the full workspace, including the rollup-independent Ideas Inbox. */
     async loadWorkspace() {
         const manifest = await this.loadManifest();
         const phases = await this.loadAllPhases();
         const project = await this.loadProject();
         const features = await this.loadFeatures();
         const requirements = await this.loadRequirements();
-        return { manifest, phases, project, features, requirements };
+        const ideas = await this.loadIdeas();
+        return { manifest, phases, project, features, requirements, ideas };
     }
     // ── Markdown generation ────────────────────────────────────────────
     /** Load all data, render markdown, and write into generated/. Skips files