@agent-plan/core 0.2.19-next.2 → 0.2.19-next.20

package/dist/plan-store.js

@@ -1,15 +1,52 @@
-import { access, copyFile, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, } from "./schema.js";
-import { createFeatureId, createPhaseId, createRequirementId, createShortId, createTaskId, formatPhaseRef, isLegacyPhaseId } from "./naming.js";
+import { access, copyFile, mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { z, ZodError } from "zod";
+/** Canonical `.planner/.gitignore` content (P042 spec): ignore the `.local/`
+ *  transient root, legacy `*.bak` crash backups, `*.tmp.*` atomic-write temp
+ *  files, and the legacy root-level `generated/` dir (now under `.local/`).
+ *  Shared by `init()` and `ensureGitignore()` so the two never drift. */
+const PLANNER_GITIGNORE = [
+    "# Agent Plan transient/derived/session-local files — do not track",
+    ".local/",
+    "*.bak",
+    "*.tmp.*",
+    "generated/",
+    "",
+].join("\n");
+import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, } from "./schema.js";
+import { createFeatureId, createPhaseId, createRequirementId, createShortId, createStatusLogEntryId, createTaskId, formatPhaseRef, isLegacyPhaseId } from "./naming.js";
+import { deriveParentDisplay, fromCanonicalStatus } from "./display-status.js";
 function nowISO() {
     return new Date().toISOString();
 }
+function resolveStoredFeatureId(features, ref) {
+    const raw = ref?.trim();
+    if (!raw)
+        return undefined;
+    const normalized = raw.toLowerCase();
+    const byId = features.find((feature) => feature.id.toLowerCase() === normalized);
+    if (byId)
+        return byId.id;
+    const byNumber = normalized.match(/^f(\d+)$/)
+        ? features.find((feature) => feature.number === parseInt(normalized.slice(1), 10))
+        : undefined;
+    if (byNumber)
+        return byNumber.id;
+    const byShortId = features.find((feature) => feature.shortId?.toLowerCase() === normalized);
+    if (byShortId)
+        return byShortId.id;
+    const byExactName = features.find((feature) => feature.name.toLowerCase() === normalized);
+    if (byExactName)
+        return byExactName.id;
+    return undefined;
+}
 export class PlanStoreError extends Error {
     cause;
-    constructor(message, cause) {
+    details;
+    constructor(message, cause, details) {
         super(message);
         this.cause = cause;
+        this.details = details;
         this.name = "PlanStoreError";
     }
 }
@@ -32,14 +69,52 @@ let writeNotifyHook;
 export function setWriteNotifyHook(hook) {
     writeNotifyHook = hook;
 }
+const CROSS_PROCESS_LOCK_STALE_MS = 30_000;
+const CROSS_PROCESS_LOCK_RETRY_MS = 10;
+async function acquireCrossProcessLock(path) {
+    const lockPath = `${path}.lock`;
+    for (;;) {
+        try {
+            await mkdir(lockPath);
+            return async () => {
+                await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err?.code !== "EEXIST")
+                throw err;
+            try {
+                const info = await stat(lockPath);
+                if (Date.now() - info.mtimeMs > CROSS_PROCESS_LOCK_STALE_MS) {
+                    await rm(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, CROSS_PROCESS_LOCK_RETRY_MS));
+        }
+    }
+}
 function withWriteLock(path, fn) {
     const prev = writeLocks.get(path) ?? Promise.resolve();
     let release;
     const next = new Promise((resolve) => { release = resolve; });
-    writeLocks.set(path, prev.then(() => next));
-    return prev.then(fn).finally(() => {
+    const tail = prev.then(() => next);
+    writeLocks.set(path, tail);
+    return prev.then(async () => {
+        const releaseCrossProcess = await acquireCrossProcessLock(path);
+        try {
+            return await fn();
+        }
+        finally {
+            await releaseCrossProcess();
+        }
+    }).finally(() => {
         release();
-        if (writeLocks.get(path) === prev.then(() => next))
+        if (writeLocks.get(path) === tail)
             writeLocks.delete(path);
     });
 }
@@ -47,21 +122,35 @@ export function withFeatureLock(featureId, fn) {
     const prev = featureLocks.get(featureId) ?? Promise.resolve();
     let release;
     const next = new Promise((resolve) => { release = resolve; });
-    featureLocks.set(featureId, prev.then(() => next));
+    const tail = prev.then(() => next);
+    featureLocks.set(featureId, tail);
     return prev.then(fn).finally(() => {
         release();
-        if (featureLocks.get(featureId) === prev.then(() => next))
+        if (featureLocks.get(featureId) === tail)
             featureLocks.delete(featureId);
     });
 }
-async function atomicWriteText(path, raw) {
+async function atomicWriteText(path, raw, root) {
     return withWriteLock(path, async () => {
         writeBusyHook?.(true);
-        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+        const localRoot = root ? join(root, ".local") : undefined;
+        const tmpDir = localRoot ? join(localRoot, "tmp") : dirname(path);
+        const backupsRoot = localRoot ? join(localRoot, "backups") : dirname(path);
+        const rel = localRoot && path.startsWith(localRoot)
+            ? path.slice(localRoot.length).replace(/^\//, "")
+            : root && path.startsWith(root)
+                ? path.slice(root.length).replace(/^\//, "")
+                : basename(path);
+        const backupRel = rel ? rel + ".bak" : basename(path) + ".bak";
+        const backupPath = join(backupsRoot, backupRel);
+        const tmpName = rel ? rel.replace(/[/\\]/g, "--") + `.tmp.${process.pid}.${Date.now()}` : `${basename(path)}.tmp.${process.pid}.${Date.now()}`;
+        const tmp = join(tmpDir, tmpName);
         try {
+            await mkdir(tmpDir, { recursive: true });
             await writeFile(tmp, raw, "utf-8");
             try {
-                await copyFile(path, `${path}.bak`);
+                await mkdir(dirname(backupPath), { recursive: true });
+                await copyFile(path, backupPath);
             }
             catch { }
             await rename(tmp, path);
@@ -76,10 +165,10 @@ async function atomicWriteText(path, raw) {
         }
     });
 }
-async function atomicWriteJson(path, data) {
-    return atomicWriteText(path, JSON.stringify(data, null, 2));
+async function atomicWriteJson(path, data, root) {
+    return atomicWriteText(path, JSON.stringify(data, null, 2), root);
 }
-async function atomicUpdateJson(path, schema, updater) {
+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.
@@ -88,11 +177,23 @@ async function atomicUpdateJson(path, schema, updater) {
         const updated = updater(current);
         const parsed = schema.parse(updated);
         writeBusyHook?.(true);
-        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+        const localRoot = root ? join(root, ".local") : undefined;
+        const tmpDir = localRoot ? join(localRoot, "tmp") : dirname(path);
+        const backupsRoot = localRoot ? join(localRoot, "backups") : dirname(path);
+        const rel = localRoot && path.startsWith(localRoot)
+            ? path.slice(localRoot.length).replace(/^\//, "")
+            : root && path.startsWith(root)
+                ? path.slice(root.length).replace(/^\//, "")
+                : basename(path);
+        const backupPath = join(backupsRoot, rel + ".bak");
+        const tmpName = rel ? rel.replace(/[/\\]/g, "--") + `.tmp.${process.pid}.${Date.now()}` : `${basename(path)}.tmp.${process.pid}.${Date.now()}`;
+        const tmp = join(tmpDir, tmpName);
         try {
+            await mkdir(tmpDir, { recursive: true });
             await writeFile(tmp, JSON.stringify(parsed, null, 2), "utf-8");
             try {
-                await copyFile(path, `${path}.bak`);
+                await mkdir(dirname(backupPath), { recursive: true });
+                await copyFile(path, backupPath);
             }
             catch { }
             await rename(tmp, path);
@@ -176,21 +277,150 @@ export async function migrateToUuids(store) {
         await store.writeGenerated();
     });
 }
+/**
+ * One-time idempotent migration to GLOBAL F/P/T numbering.
+ *
+ * Legacy plans assign Phase.number per-feature and Task.number per-phase, so
+ * every feature has a P001 and every phase has a T001 (ambiguous in chat/handoffs).
+ * This renumbers ALL features/phases/tasks by `createdAt` asc (stable tiebreak by
+ * id) into a single project-wide 1..N sequence and sets the monotonic project
+ * counters (nextFeatureNumber/nextPhaseNumber/nextTaskNumber).
+ *
+ * Idempotent: if no duplicate phase/task/feature numbers exist across the
+ * project, the plan is already global → no renumber writes happen (only the
+ * counters are ensured, in case project.json predates them). MUST run before
+ * ensureStructureOrdering (which no longer renumbers — numbers are stable).
+ */
+export async function migrateToGlobalSequence(store) {
+    return store.runBatchForMigration(async () => {
+        const ws = await store.loadAll();
+        const phases = ws.phases;
+        const features = ws.features.features;
+        const project = ws.project;
+        const allTasks = [];
+        for (const phase of phases)
+            for (const task of phase.tasks)
+                allTasks.push({ phase, task });
+        const hasDupes = (nums) => new Set(nums).size !== nums.length;
+        const phaseDupes = hasDupes(phases.map((p) => p.number));
+        const taskDupes = hasDupes(allTasks.map((x) => x.task.number));
+        const featureDupes = hasDupes(features.map((f) => f.number));
+        const maxP = phases.reduce((m, p) => Math.max(m, p.number), 0);
+        const maxT = allTasks.reduce((m, x) => Math.max(m, x.task.number), 0);
+        const maxF = features.reduce((m, f) => Math.max(m, f.number), 0);
+        if (!phaseDupes && !taskDupes && !featureDupes) {
+            // Already global. Ensure counters are set (project.json may predate them).
+            let changed = false;
+            if (project.nextPhaseNumber <= maxP) {
+                project.nextPhaseNumber = maxP + 1;
+                changed = true;
+            }
+            if (project.nextTaskNumber <= maxT) {
+                project.nextTaskNumber = maxT + 1;
+                changed = true;
+            }
+            if (project.nextFeatureNumber <= maxF) {
+                project.nextFeatureNumber = maxF + 1;
+                changed = true;
+            }
+            if (changed)
+                await store.saveProject(project);
+            return { migrated: false, phases: phases.length, tasks: allTasks.length, features: features.length };
+        }
+        const renumber = (arr) => arr
+            .slice()
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+            .map((x, i) => ({ ...x, number: i + 1 }));
+        const newFeatures = renumber(features);
+        const newPhases = renumber(phases);
+        const numberedTasks = renumber(allTasks.map((x) => x.task));
+        // Reassemble renumbered tasks into their phases, keyed by the task's OWN
+        // phaseId (source of truth). NOTE: do NOT pair `numberedTasks[i]` with
+        // `allTasks[i]!.phase.id` — the two arrays are in DIFFERENT orders
+        // (numberedTasks is sorted by createdAt, allTasks is in phase-iteration
+        // order), so a positional index would file each task under the wrong phase.
+        const phaseIdByTaskId = new Map(allTasks.map((x) => [x.task.id, x.phase.id]));
+        const newPhaseIds = new Set(newPhases.map((p) => p.id));
+        const tasksByPhase = new Map();
+        for (const t of numberedTasks) {
+            // Prefer the task's own phaseId when it points to a real phase; otherwise
+            // fall back to the phase the task was loaded from (handles legacy tasks
+            // with empty/stale phaseId without losing them).
+            const pid = (t.phaseId && newPhaseIds.has(t.phaseId)) ? t.phaseId : (phaseIdByTaskId.get(t.id) ?? "");
+            const bucket = tasksByPhase.get(pid) ?? [];
+            bucket.push(t);
+            tasksByPhase.set(pid, bucket);
+        }
+        const finalPhases = newPhases.map((p) => {
+            const tasks = tasksByPhase.get(p.id) ?? [];
+            const order = new Map(tasks.map((t) => [t.id, t]));
+            const ordered = p.taskIds.map((id) => order.get(id)).filter((t) => Boolean(t));
+            for (const t of tasks.sort((a, b) => a.number - b.number))
+                if (!ordered.includes(t))
+                    ordered.push(t);
+            return { ...p, tasks: ordered, taskIds: ordered.map((t) => t.id) };
+        });
+        await store.saveFeatures({ features: newFeatures });
+        for (const p of finalPhases)
+            await store.savePhase(p);
+        project.nextFeatureNumber = newFeatures.length + 1;
+        project.nextPhaseNumber = newPhases.length + 1;
+        project.nextTaskNumber = numberedTasks.length + 1;
+        await store.saveProject(project);
+        await store.writeGenerated();
+        return { migrated: true, phases: newPhases.length, tasks: numberedTasks.length, features: newFeatures.length };
+    });
+}
 async function readJson(path, schema) {
+    let backupTried = false;
+    let backupFailed = false;
+    let rawPreview;
     try {
         const raw = await readFile(path, "utf-8");
+        rawPreview = raw.slice(0, 240);
         return schema.parse(JSON.parse(raw));
     }
     catch (cause) {
         // Try the .bak backup before giving up (recover from external-write corruption).
+        backupTried = true;
         try {
             const bak = await readFile(`${path}.bak`, "utf-8");
+            rawPreview = bak.slice(0, 240);
             return schema.parse(JSON.parse(bak));
         }
         catch {
+            backupFailed = true;
             // fall through to original error
         }
-        throw new PlanStoreError(`read failed: ${path}`, cause);
+        const details = {
+            path,
+            operation: "readJson",
+            backupTried,
+            backupFailed,
+        };
+        if (rawPreview != null)
+            details.rawPreview = rawPreview;
+        if (cause instanceof SyntaxError) {
+            const match = cause.message.match(/position\s+(\d+)/i);
+            const position = match && match[1] ? Number.parseInt(match[1], 10) : undefined;
+            if (rawPreview != null && position != null && position >= 0) {
+                const upTo = rawPreview.slice(0, position);
+                const line = upTo.split("\n").length;
+                const lastNL = upTo.lastIndexOf("\n");
+                const column = position - (lastNL >= 0 ? lastNL : 0);
+                details.jsonParseError = { message: cause.message, line, column };
+            }
+            else {
+                details.jsonParseError = { message: cause.message };
+            }
+        }
+        else if (cause instanceof ZodError) {
+            details.validationErrors = cause.issues.slice(0, 8).map((issue) => ({
+                path: issue.path.map((p) => (typeof p === "number" ? `[${p}]` : String(p))).join("."),
+                message: issue.message,
+            }));
+        }
+        throw new PlanStoreError(`read failed: ${path}`, cause, details);
     }
 }
 export class PlanStore {
@@ -240,24 +470,13 @@ export class PlanStore {
         // save. Kept so existing save* call sites compile unchanged.
     }
     normalizeTasks(tasks) {
-        let changed = false;
-        const normalized = tasks.map((task, index) => {
-            const nextNumber = index + 1;
-            if (task.number !== nextNumber)
-                changed = true;
-            return { ...task, number: nextNumber };
-        });
-        return { tasks: normalized, changed };
+        // Numbers are a STABLE global sequence (assigned once at create from project.nextTaskNumber).
+        // Do NOT renumber here — renumbering would break references after deletions.
+        return { tasks, changed: false };
     }
     normalizeFeaturesDocument(doc) {
-        let changed = false;
-        const normalized = doc.features.map((feature, index) => {
-            const nextNumber = index + 1;
-            if (feature.number !== nextNumber)
-                changed = true;
-            return { ...feature, number: nextNumber };
-        });
-        return { doc: { features: normalized }, changed };
+        // Numbers are a STABLE global sequence (assigned once at create from project.nextFeatureNumber).
+        return { doc, changed: false };
     }
     normalizePhaseDocument(phase) {
         const { tasks, changed } = this.normalizeTasks(phase.tasks);
@@ -278,7 +497,12 @@ export class PlanStore {
         const phasesByFeature = new Map();
         const orphanPhases = [];
         for (const phase of phases) {
-            if (phase.featureId) {
+            const resolvedFeatureId = resolveStoredFeatureId(featuresDoc.features, phase.featureId);
+            if (resolvedFeatureId && resolvedFeatureId !== phase.featureId) {
+                phase.featureId = resolvedFeatureId;
+                changed = true;
+            }
+            if (phase.featureId && featuresDoc.features.some((feature) => feature.id === phase.featureId)) {
                 const bucket = phasesByFeature.get(phase.featureId) ?? [];
                 bucket.push(phase);
                 phasesByFeature.set(phase.featureId, bucket);
@@ -287,10 +511,7 @@ export class PlanStore {
                 orphanPhases.push(phase);
             }
         }
-        const normalizedFeatures = featuresDoc.features.map((feature, featureIndex) => {
-            const nextFeatureNumber = featureIndex + 1;
-            if (feature.number !== nextFeatureNumber)
-                changed = true;
+        const normalizedFeatures = featuresDoc.features.map((feature) => {
             const linked = feature.phaseIds.map((id) => phaseById.get(id)).filter((phase) => Boolean(phase));
             const linkedIds = new Set(linked.map((phase) => phase.id));
             const inferred = (phasesByFeature.get(feature.id) ?? []).filter((phase) => !linkedIds.has(phase.id));
@@ -299,12 +520,7 @@ export class PlanStore {
             if (normalizedPhaseIds.length !== feature.phaseIds.length || normalizedPhaseIds.some((id, index) => id !== feature.phaseIds[index])) {
                 changed = true;
             }
-            orderedPhases.forEach((phase, index) => {
-                const nextPhaseNumber = index + 1;
-                if (phase.number !== nextPhaseNumber) {
-                    phase.number = nextPhaseNumber;
-                    changed = true;
-                }
+            orderedPhases.forEach((phase) => {
                 const normalizedPhase = this.normalizePhaseDocument(phase);
                 if (normalizedPhase.changed) {
                     phase.tasks = normalizedPhase.phase.tasks;
@@ -314,16 +530,10 @@ export class PlanStore {
             });
             return {
                 ...feature,
-                number: nextFeatureNumber,
                 phaseIds: normalizedPhaseIds,
             };
         });
-        orphanPhases.forEach((phase, index) => {
-            const nextPhaseNumber = index + 1;
-            if (phase.number !== nextPhaseNumber) {
-                phase.number = nextPhaseNumber;
-                changed = true;
-            }
+        orphanPhases.forEach((phase) => {
             const normalizedPhase = this.normalizePhaseDocument(phase);
             if (normalizedPhase.changed) {
                 phase.tasks = normalizedPhase.phase.tasks;
@@ -338,7 +548,7 @@ export class PlanStore {
         };
     }
     async ensureStructureOrdering() {
-        return this.runAsBatch(async () => {
+        const result = await this.runAsBatch(async () => {
             const featuresDoc = await this.loadFeatures();
             const phases = await this.loadAllPhases();
             const normalized = this.normalizeStructureSnapshot(featuresDoc, phases);
@@ -350,6 +560,52 @@ export class PlanStore {
             }
             return { changed: true };
         });
+        // One-time import of a legacy file-based HANDOFF.md (pre-F004) into the
+        // entity-scoped phase.handoff. Idempotent — renames the file to .bak.
+        await this.importLegacyHandoffFile().catch(() => { });
+        return result;
+    }
+    /** Rebuild each phase's `tasks` + `taskIds` from the task's OWN `phaseId`
+     *  (source of truth). Heals plans where tasks got filed into the wrong phase
+     *  file (e.g. the migrateToGlobalSequence index-mismatch bug, @agent-plan/core
+     *  <0.2.19-next.7). Deterministic, lossless, idempotent: groups every task by
+     *  its phaseId, preserves each phase's existing taskIds order, appends orphan
+     *  tasks (whose phaseId dangles or is empty) by number. Writes a phase file
+     *  only when its task set actually changed. */
+    async rebuildContainment() {
+        return this.runAsBatch(async () => {
+            const phases = await this.loadAllPhases();
+            const phaseById = new Map(phases.map((p) => [p.id, p]));
+            const allTasks = [];
+            for (const p of phases)
+                for (const t of p.tasks)
+                    allTasks.push({ task: t, fromPhaseId: p.id });
+            const grouped = new Map();
+            let orphan = 0;
+            for (const { task, fromPhaseId } of allTasks) {
+                const pid = (task.phaseId && phaseById.has(task.phaseId)) ? task.phaseId : fromPhaseId;
+                if (!phaseById.has(pid))
+                    orphan++;
+                const bucket = grouped.get(pid) ?? [];
+                bucket.push(task);
+                grouped.set(pid, bucket);
+            }
+            let changed = 0;
+            for (const p of phases) {
+                const tasks = grouped.get(p.id) ?? [];
+                const byId = new Map(tasks.map((t) => [t.id, t]));
+                const ordered = p.taskIds.map((id) => byId.get(id)).filter((t) => Boolean(t));
+                for (const t of tasks.slice().sort((a, b) => a.number - b.number))
+                    if (!ordered.some((o) => o.id === t.id))
+                        ordered.push(t);
+                const same = ordered.length === p.tasks.length && ordered.every((t, i) => t.id === p.tasks[i]?.id);
+                if (same)
+                    continue;
+                await this.savePhase({ ...p, tasks: ordered, taskIds: ordered.map((t) => t.id) });
+                changed++;
+            }
+            return { changed, tasks: allTasks.length, orphan };
+        });
     }
     // ── Path helpers ─────────────────────────────────────────────────────
     manifestPath() {
@@ -389,7 +645,7 @@ export class PlanStore {
         }
         await mkdir(this.featuresDir(), { recursive: true });
         for (const feat of legacy.features) {
-            await atomicWriteJson(this.featurePath(feat.id), feat);
+            await atomicWriteJson(this.featurePath(feat.id), feat, this.root);
         }
         await unlink(this.featuresPath()).catch(() => { });
     }
@@ -400,19 +656,81 @@ export class PlanStore {
         return join(this.phasesDir(), `${phaseId}.json`);
     }
     generatedDir() {
-        return join(this.root, "generated");
+        return join(this.localRoot(), "generated");
     }
     codebasePath() {
         return join(this.root, "codebase.json");
     }
     resumePath() {
-        return join(this.root, "resume.json");
+        return join(this.localRoot(), "resume.json");
     }
     activityPath() {
-        return join(this.root, "activity.json");
+        return join(this.localRoot(), "activity.json");
+    }
+    localRoot() {
+        return join(this.root, ".local");
+    }
+    timestampPath() {
+        return join(this.localRoot(), "timestamp.json");
+    }
+    backupsDir() {
+        return join(this.localRoot(), "backups");
+    }
+    tmpDir() {
+        return join(this.localRoot(), "tmp");
+    }
+    handoffArchiveDir() {
+        return join(this.localRoot(), "handoff-archive");
+    }
+    /** One-time migration for plans created before .planner/.local/ existed.
+     *  Moves a legacy root-level file into .local/ if the legacy file exists and
+     *  the .local/ counterpart does not. Safe to call on every load. */
+    async migrateLegacyLocalFile(oldPath, newPath) {
+        try {
+            await access(oldPath);
+        }
+        catch {
+            return;
+        }
+        try {
+            await access(newPath);
+            return;
+        }
+        catch { }
+        await mkdir(dirname(newPath), { recursive: true });
+        await rename(oldPath, newPath);
+    }
+    async migrateLegacyGeneratedDir() {
+        const oldDir = join(this.root, "generated");
+        const newDir = this.generatedDir();
+        try {
+            await access(oldDir);
+        }
+        catch {
+            return;
+        }
+        try {
+            await access(newDir);
+            return;
+        }
+        catch { }
+        await rename(oldDir, newDir);
     }
-    handoffPath() {
-        return join(this.root, "HANDOFF.md");
+    async migrateLegacyHandoffArchive() {
+        const oldDir = join(this.root, "handoff-archive");
+        const newDir = this.handoffArchiveDir();
+        try {
+            await access(oldDir);
+        }
+        catch {
+            return;
+        }
+        try {
+            await access(newDir);
+            return;
+        }
+        catch { }
+        await rename(oldDir, newDir);
     }
     // ── Init ─────────────────────────────────────────────────────────────
     async init(projectName) {
@@ -422,7 +740,11 @@ export class PlanStore {
         await mkdir(this.root, { recursive: true });
         await mkdir(this.phasesDir(), { recursive: true });
         await mkdir(this.featuresDir(), { recursive: true });
+        await mkdir(this.localRoot(), { recursive: true });
+        await mkdir(this.backupsDir(), { recursive: true });
+        await mkdir(this.tmpDir(), { recursive: true });
         await mkdir(join(this.generatedDir(), "phases"), { recursive: true });
+        await mkdir(this.handoffArchiveDir(), { recursive: true });
         await mkdir(join(this.root, "schema"), { recursive: true });
         await mkdir(join(this.root, "adapters"), { recursive: true });
         const manifest = {
@@ -432,7 +754,8 @@ export class PlanStore {
             createdAt: nowISO(),
             updatedAt: nowISO(),
         };
-        await atomicWriteJson(this.manifestPath(), manifest);
+        await atomicWriteJson(this.manifestPath(), manifest, this.root);
+        await atomicWriteJson(this.timestampPath(), { updatedAt: manifest.updatedAt }, this.root);
         await this.saveProject({
             name: projectName,
             goal: "",
@@ -452,6 +775,9 @@ export class PlanStore {
                 beforeTaskStart: [],
                 afterPhaseComplete: [],
             },
+            nextFeatureNumber: 1,
+            nextPhaseNumber: 1,
+            nextTaskNumber: 1,
         });
         await this.saveRequirements({ requirements: [] });
         await this.saveFeatures({ features: [] });
@@ -460,6 +786,7 @@ export class PlanStore {
             currentPhaseId: "",
             inProgressTaskIds: [],
             nextSteps: ["Run /planner project discuss to bootstrap discovery"],
+            nextStepsUpdatedAt: nowISO(),
             blockers: [],
             notes: "Project initialized. Awaiting discovery.",
             lastSessionSummary: "",
@@ -478,7 +805,7 @@ export class PlanStore {
             "- `project.json` — scope, rules, stack, tools",
             "- `requirements.json` — requirements and macro-tasks",
             "- `phases/` — one JSON file per phase",
-            "- `generated/` — auto-generated markdown views",
+            "- `generated/` — auto-generated markdown views (under `.local/`)",
             "- `schema/plan.schema.json` — JSON Schema for tooling",
         ].join("\n");
         await writeFile(join(this.root, "README.md"), readme, "utf-8");
@@ -488,15 +815,29 @@ export class PlanStore {
         // - resume.json: per-session resume focus + the machine-local guard-bypass
         //   timestamp (guardBypassUntil must NOT leak into git/other clones)
         // - generated/: auto-regenerated markdown views (derived from JSON; churn)
-        await writeFile(join(this.root, ".gitignore"), [
-            "# Agent Plan transient/derived files — do not track",
-            "*.bak",
-            "*.tmp.*",
-            "resume.json",
-            "resume.*.json",
-            "generated/",
-            "",
-        ].join("\n"), "utf-8");
+        await writeFile(join(this.root, ".gitignore"), PLANNER_GITIGNORE, "utf-8");
+    }
+    /** 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
+     *  root-level patterns. This upgrades them safely on load and on repair.
+     *  Returns true if the file was (re)written. Safe to call on every load. */
+    async ensureGitignore() {
+        const gi = join(this.root, ".gitignore");
+        try {
+            const existing = await readFile(gi, "utf8").catch(() => null);
+            // Up to date iff it contains all canonical patterns (P042 spec):
+            // .local/ (transients), *.bak (crash backups), *.tmp.* (atomic-write
+            // temp files), generated/ (legacy dir).
+            if (existing != null && existing.includes(".local/") && existing.includes("*.bak") && existing.includes("*.tmp.*") && existing.includes("generated/")) {
+                return false;
+            }
+            await writeFile(gi, PLANNER_GITIGNORE, "utf-8");
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     async exists() {
         try {
@@ -509,11 +850,79 @@ export class PlanStore {
     }
     // ── Loaders ──────────────────────────────────────────────────────────
     async loadManifest() {
-        return readJson(this.manifestPath(), ManifestSchema);
+        // Ensure the .planner/.gitignore ignores transients (P042). Idempotent;
+        // upgrades plans initialized before the .local/ move. Runs on every load.
+        await this.ensureGitignore().catch(() => { });
+        const manifest = await readJson(this.manifestPath(), ManifestSchema);
+        try {
+            const timestamp = await readJson(this.timestampPath(), z.object({ updatedAt: TimestampSchema }));
+            manifest.updatedAt = timestamp.updatedAt;
+        }
+        catch {
+            // Legacy plan without .local/timestamp.json: bootstrap from manifest.updatedAt
+            // and create the timestamp file so subsequent writes stay in .local/.
+            try {
+                await mkdir(this.localRoot(), { recursive: true });
+                await atomicWriteJson(this.timestampPath(), { updatedAt: manifest.updatedAt }, this.root);
+            }
+            catch {
+                // ignore bootstrap failure
+            }
+        }
+        return manifest;
     }
     async loadProject() {
         return readJson(this.projectPath(), ProjectSchema);
     }
+    /**
+     * Allocate the next global sequence number for a feature/phase/task.
+     * Reads the monotonic counter from project.json, increments it, persists,
+     * and returns the allocated number. MUST be called within withFeatureLock
+     * (adapters create entities inside a lock) so the counter is race-free.
+     * The counter never reuses a number — deletions leave gaps (by design:
+     * stable references survive deletion).
+     */
+    async allocFeatureNumber() { return this.allocSeqNumber("nextFeatureNumber", "feature"); }
+    async allocPhaseNumber() { return this.allocSeqNumber("nextPhaseNumber", "phase"); }
+    async allocTaskNumber() { return this.allocSeqNumber("nextTaskNumber", "task"); }
+    /** Allocate a globally-unique sequence number. `atomicUpdateJson` already
+     *  serializes concurrent calls via `withWriteLock` on the project file, so
+     *  the read-modify-write is race-free in-process. The collision guard
+     *  additionally skips any candidate that already exists in the data (safety
+     *  net for cross-process races or manual edits) and persists the corrected
+     *  counter. */
+    async allocSeqNumber(key, kind) {
+        // Load already-used numbers for this kind (best-effort read; the
+        // atomicUpdateJson below is the authoritative write).
+        const used = new Set();
+        if (kind === "task") {
+            const phases = await this.loadAllPhases();
+            for (const p of phases)
+                for (const t of p.tasks)
+                    used.add(t.number);
+        }
+        else if (kind === "phase") {
+            const phases = await this.loadAllPhases();
+            for (const p of phases)
+                used.add(p.number);
+        }
+        else {
+            const feats = await this.loadRawFeatures();
+            for (const f of feats)
+                used.add(f.number);
+        }
+        let allocated = 0;
+        await this.updateProject((project) => {
+            let candidate = project[key];
+            // Collision guard: skip any candidate that already exists.
+            while (used.has(candidate))
+                candidate++;
+            allocated = candidate;
+            project[key] = candidate + 1;
+            return project;
+        });
+        return allocated;
+    }
     async loadPhase(phaseId) {
         const raw = await readJson(this.phasePath(phaseId), PhaseSchema);
         const normalized = this.normalizePhaseDocument(raw).phase;
@@ -565,7 +974,7 @@ export class PlanStore {
         const raws = await this.loadRawFeatures();
         const phases = await this.loadAllPhases();
         const features = raws.map((f) => ({ ...f, status: this.deriveFeatureStatus(f.id, phases) }));
-        return this.normalizeFeaturesDocument({ features }).doc;
+        return this.normalizeStructureSnapshot({ features }, phases).features;
     }
     async loadCodebaseProfile() {
         try {
@@ -577,10 +986,11 @@ export class PlanStore {
     }
     async saveCodebaseProfile(profile) {
         const parsed = CodebaseProfileSchema.parse(profile);
-        await atomicWriteJson(this.codebasePath(), parsed);
-        await this.touchManifest();
+        await atomicWriteJson(this.codebasePath(), parsed, this.root);
+        await this.touchTimestamp();
     }
     async loadResume() {
+        await this.migrateLegacyLocalFile(join(this.root, "resume.json"), this.resumePath());
         try {
             return await readJson(this.resumePath(), ResumeFocusSchema);
         }
@@ -589,9 +999,20 @@ export class PlanStore {
         }
     }
     async saveResume(resume) {
-        const parsed = ResumeFocusSchema.parse(resume);
-        await atomicWriteJson(this.resumePath(), parsed);
-        await this.touchManifest();
+        // Track when `nextSteps` actually change (free-text can go stale; the recap
+        // surfaces nextStepsUpdatedAt so staleness is visible). Preserved when
+        // refreshResume keeps existing nextSteps; bumped only on a real change.
+        const existing = await this.loadResume().catch(() => null);
+        const nextStepsChanged = JSON.stringify(existing?.nextSteps ?? []) !== JSON.stringify(resume.nextSteps ?? []);
+        const withTs = {
+            ...resume,
+            nextStepsUpdatedAt: nextStepsChanged
+                ? nowISO()
+                : (resume.nextStepsUpdatedAt || existing?.nextStepsUpdatedAt || nowISO()),
+        };
+        const parsed = ResumeFocusSchema.parse(withTs);
+        await atomicWriteJson(this.resumePath(), parsed, this.root);
+        await this.touchTimestamp();
     }
     /**
      * Authorize a temporary guard bypass so edit/write tools may proceed even
@@ -605,6 +1026,7 @@ export class PlanStore {
             currentPhaseId: "",
             inProgressTaskIds: [],
             nextSteps: [],
+            nextStepsUpdatedAt: "",
             blockers: [],
             notes: "",
             lastSessionSummary: "",
@@ -636,6 +1058,7 @@ export class PlanStore {
         return until > Date.now();
     }
     async loadActivityLog() {
+        await this.migrateLegacyLocalFile(join(this.root, "activity.json"), this.activityPath());
         try {
             return await readJson(this.activityPath(), ActivityLogSchema);
         }
@@ -643,44 +1066,6 @@ export class PlanStore {
             return { entries: [] };
         }
     }
-    async handoffExists() {
-        try {
-            await access(this.handoffPath());
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    async loadHandoff() {
-        try {
-            const [content, info] = await Promise.all([
-                readFile(this.handoffPath(), "utf-8"),
-                stat(this.handoffPath()),
-            ]);
-            const createdAt = content.match(/^Created at:\s*(.+)$/m)?.[1]?.trim() ?? info.birthtime.toISOString();
-            const updatedAt = content.match(/^Updated at:\s*(.+)$/m)?.[1]?.trim() ?? info.mtime.toISOString();
-            return {
-                content,
-                createdAt,
-                updatedAt,
-            };
-        }
-        catch {
-            return null;
-        }
-    }
-    async saveHandoff(content) {
-        await atomicWriteText(this.handoffPath(), content);
-        await this.touchManifest();
-    }
-    async deleteHandoff() {
-        try {
-            await unlink(this.handoffPath());
-        }
-        catch { }
-        await this.touchManifest();
-    }
     async appendActivity(type, ref, summary) {
         const log = await this.loadActivityLog();
         const id = `act-${log.entries.length + 1}-${type}`;
@@ -689,8 +1074,8 @@ export class PlanStore {
         // Cap to last 200 entries
         if (log.entries.length > 200)
             log.entries = log.entries.slice(-200);
-        await atomicWriteJson(this.activityPath(), { entries: log.entries });
-        await this.touchManifest();
+        await atomicWriteJson(this.activityPath(), { entries: log.entries }, this.root);
+        await this.touchTimestamp();
         return entry;
     }
     /** Derive an up-to-date resume focus from the current workspace state. */
@@ -705,6 +1090,7 @@ export class PlanStore {
             currentPhaseId: inProgressPhases[0]?.id ?? existing?.currentPhaseId ?? "",
             inProgressTaskIds: inProgressTasks.map((t) => t.id),
             nextSteps: existing?.nextSteps ?? [],
+            nextStepsUpdatedAt: existing?.nextStepsUpdatedAt ?? "",
             blockers: blockedTasks.map((t) => `${t.id}: ${t.title}`),
             notes: notes ?? existing?.notes ?? "",
             lastSessionSummary: lastSessionSummary ?? existing?.lastSessionSummary ?? "",
@@ -721,6 +1107,27 @@ export class PlanStore {
             return { requirements: [] };
         }
     }
+    async linkedRequirementsForPhase(phaseId) {
+        const requirements = await this.loadRequirements();
+        return requirements.requirements.filter((requirement) => requirement.linkedPhaseIds.includes(phaseId));
+    }
+    async loadPhaseWithRequirements(phaseId) {
+        const [phase, linkedRequirements] = await Promise.all([
+            this.loadPhase(phaseId),
+            this.linkedRequirementsForPhase(phaseId),
+        ]);
+        return { ...phase, linkedRequirements };
+    }
+    async loadAllPhasesWithRequirements() {
+        const [phases, requirements] = await Promise.all([
+            this.loadAllPhases(),
+            this.loadRequirements(),
+        ]);
+        return phases.map((phase) => ({
+            ...phase,
+            linkedRequirements: requirements.requirements.filter((requirement) => requirement.linkedPhaseIds.includes(phase.id)),
+        }));
+    }
     async loadAllPhases() {
         const { readdir } = await import("node:fs/promises");
         let files;
@@ -751,6 +1158,22 @@ export class PlanStore {
             return left.createdAt.localeCompare(right.createdAt);
         });
     }
+    /** Derive the parent display snapshot for a phase from its tasks' canonical
+     *  statuses. Pure, non-persisting. */
+    async loadPhaseDisplay(phaseId) {
+        const phase = await this.loadPhase(phaseId);
+        const childStatuses = phase.tasks.map((t) => fromCanonicalStatus(t.status));
+        return deriveParentDisplay(childStatuses);
+    }
+    /** Derive the parent display snapshot for a feature from its phases' DERIVED
+     *  canonical statuses (each phase status is derived from its tasks at read
+     *  time, then mapped via fromCanonicalStatus). Pure, non-persisting. */
+    async loadFeatureDisplay(featureId) {
+        const phases = await this.loadAllPhases();
+        const featurePhases = phases.filter((p) => p.featureId === featureId);
+        const childStatuses = featurePhases.map((p) => fromCanonicalStatus(p.status));
+        return deriveParentDisplay(childStatuses);
+    }
     async loadAll() {
         const [manifest, project, requirements, phases] = await Promise.all([
             this.loadManifest(),
@@ -760,7 +1183,8 @@ export class PlanStore {
         ]);
         const rawFeatures = await this.loadRawFeatures();
         const features = rawFeatures.map((f) => ({ ...f, status: this.deriveFeatureStatus(f.id, phases) }));
-        return { manifest, project, requirements, phases, features: { features } };
+        const normalized = this.normalizeStructureSnapshot({ features }, phases);
+        return { manifest, project, requirements, phases: normalized.phases, features: normalized.features };
     }
     /** Migrate legacy non-feature-scoped phase ids to feature-scoped ids and repair
      *  dangling feature.phaseIds references. Idempotent. */
@@ -938,18 +1362,14 @@ export class PlanStore {
             let shortIdsAssigned = 0;
             let prioritiesAssigned = 0;
             let featuresDirty = false;
-            const assignPriority = (current, index) => {
-                if (current === 0) {
-                    prioritiesAssigned += 1;
-                    return index + 1;
-                }
-                return current;
-            };
+            // Priority is left to reorder (midpoint-insert); ensureShortIds only
+            // backfills shortIds. New items keep priority 0 until first drag reindex.
+            const assignPriority = (current, _index) => current;
             // Features: shortId + priority (project scope)
             const sortedFeatures = [...featuresDoc.features].sort((a, b) => a.number - b.number || a.createdAt.localeCompare(b.createdAt));
             sortedFeatures.forEach((f, index) => {
                 if (!f.shortId) {
-                    f.shortId = createShortId(existing);
+                    f.shortId = createShortId(existing, `feature:${f.number}:${f.id}`);
                     existing.add(f.shortId);
                     shortIdsAssigned += 1;
                     featuresDirty = true;
@@ -968,7 +1388,7 @@ export class PlanStore {
             for (const phase of phases) {
                 let phaseDirty = false;
                 if (!phase.shortId) {
-                    phase.shortId = createShortId(existing);
+                    phase.shortId = createShortId(existing, `phase:${phase.number}:${phase.id}`);
                     existing.add(phase.shortId);
                     shortIdsAssigned += 1;
                     phaseDirty = true;
@@ -982,7 +1402,7 @@ export class PlanStore {
                 const sortedTasks = [...phase.tasks].sort((a, b) => a.number - b.number || a.createdAt.localeCompare(b.createdAt));
                 sortedTasks.forEach((t, index) => {
                     if (!t.shortId) {
-                        t.shortId = createShortId(existing);
+                        t.shortId = createShortId(existing, `task:${t.number}:${t.id}`);
                         existing.add(t.shortId);
                         shortIdsAssigned += 1;
                         phaseDirty = true;
@@ -1022,13 +1442,37 @@ export class PlanStore {
     /** Repair dangling references and report integrity. One-shot maintenance op. */
     async repair() {
         return this.runAsBatch(async () => {
+            // Ensure the .planner/.gitignore ignores transients (P042). Idempotent;
+            // upgrades plans initialized before the .local/ move.
+            await this.ensureGitignore().catch(() => { });
             const migrated = await this.migratePhaseIds();
+            await this.repairPhaseFeatureRefs();
             const backfill = await this.ensureShortIdsAndPriority();
+            // Rebuild phase containment from each task's own phaseId. Heals plans
+            // corrupted by the migrateToGlobalSequence index-mismatch bug (core
+            // <0.2.19-next.7). Lossless + idempotent — safe to run every repair.
+            const containment = await this.rebuildContainment();
             const integrity = await this.validateIntegrity();
             await this.writeGenerated();
-            return { migrated, backfill, integrity };
+            return { migrated, backfill, containment, integrity };
         });
     }
+    async repairPhaseFeatureRefs() {
+        const features = await this.loadRawFeatures();
+        const phases = await this.loadAllPhases();
+        let changed = 0;
+        for (const phase of phases) {
+            const resolvedFeatureId = resolveStoredFeatureId(features, phase.featureId);
+            if (resolvedFeatureId && resolvedFeatureId !== phase.featureId) {
+                await this.savePhase({ ...phase, featureId: resolvedFeatureId });
+                changed += 1;
+            }
+        }
+        if (changed > 0) {
+            await this.updateFeatures((doc) => doc);
+        }
+        return changed;
+    }
     /** Validate plan integrity: globally unique phase ids and resolvable feature.phaseIds. */
     async validateIntegrity() {
         const phases = await this.loadAllPhases();
@@ -1074,18 +1518,28 @@ export class PlanStore {
             return "rejected";
         if (meaningful.every((s) => s === "done"))
             return "done";
-        // Lifecycle truth: any progress (active work OR partial completion) ⇒
-        // in-progress, until fully done. This is what prevents a single
-        // blocked/waiting/deferred task from poisoning the parent when there is
-        // substantial done or in-progress work (the long-standing rollup bug).
-        if (meaningful.some((s) => s === "in-progress") || meaningful.some((s) => s === "done"))
+        const hasDone = meaningful.some((s) => s === "done");
+        const hasActive = meaningful.some((s) => s === "in-progress");
+        const hasPlanned = meaningful.some((s) => s === "planned");
+        const hasBlocked = meaningful.some((s) => s === "blocked");
+        const hasWaiting = meaningful.some((s) => s === "waiting");
+        const hasDeferred = meaningful.some((s) => s === "deferred");
+        if (hasActive)
+            return "in-progress";
+        // If completed work exists and the ONLY remaining meaningful work is deferred,
+        // surface deferred instead of implying active execution.
+        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && hasDeferred)
+            return "deferred";
+        // Partial completion with remaining planned/blocked/waiting work still means
+        // the phase has genuinely started and is not terminal yet.
+        if (hasDone)
             return "in-progress";
         // No progress at all ⇒ surface the stall / not-started state (blocked > waiting > deferred > planned).
-        if (meaningful.some((s) => s === "blocked"))
+        if (hasBlocked)
             return "blocked";
-        if (meaningful.some((s) => s === "waiting"))
+        if (hasWaiting)
             return "waiting";
-        if (meaningful.some((s) => s === "deferred"))
+        if (hasDeferred)
             return "deferred";
         return "planned";
     }
@@ -1100,17 +1554,25 @@ export class PlanStore {
             return "rejected";
         if (meaningful.every((s) => s === "done"))
             return "done";
-        // Any progress (an active phase, or a partially-complete done phase) ⇒
-        // in-progress. Prevents a single stalled phase from poisoning the feature
-        // when other phases have done/in-progress work.
-        if (meaningful.some((s) => s === "discovery" || s === "in-progress") || meaningful.some((s) => s === "done"))
+        const hasDone = meaningful.some((s) => s === "done");
+        const hasActive = meaningful.some((s) => s === "discovery" || s === "in-progress");
+        const hasPlanned = meaningful.some((s) => s === "planned");
+        const hasBlocked = meaningful.some((s) => s === "blocked");
+        const hasWaiting = meaningful.some((s) => s === "waiting");
+        const hasDeferred = meaningful.some((s) => s === "deferred");
+        if (hasActive)
+            return "in-progress";
+        // Same rule as phases: done + deferred-only remainder is deferred, not active.
+        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && hasDeferred)
+            return "deferred";
+        if (hasDone)
             return "in-progress";
         // No progress at all ⇒ surface the stall / not-started state.
-        if (meaningful.some((s) => s === "blocked"))
+        if (hasBlocked)
             return "blocked";
-        if (meaningful.some((s) => s === "waiting"))
+        if (hasWaiting)
             return "waiting";
-        if (meaningful.some((s) => s === "deferred"))
+        if (hasDeferred)
             return "deferred";
         return "planned";
     }
@@ -1128,17 +1590,70 @@ export class PlanStore {
         const phase = await this.loadPhase(phaseId);
         let cleared = null;
         if (phase.status === "done" && phase.handoff !== "") {
-            await this.updatePhase(phaseId, (p) => ({ ...p, handoff: "", handoffUpdatedAt: nowISO() }));
+            await this.clearPhaseHandoff(phaseId, "phase-done");
             const features = await this.loadFeatures();
             const feature = features.features.find((f) => f.id === phase.featureId);
             cleared = formatPhaseRef(phase.number, feature?.number);
         }
+        // Append a statusLog entry to the phase when its DERIVED status changed
+        // (audit trail; status itself is NOT persisted). Idempotent: only appends
+        // when the new derived status differs from the last recorded toStatus.
+        await this.#appendPhaseStatusLog(phaseId);
+        // Roll up to the parent feature's statusLog too.
+        if (phase.featureId)
+            await this.#appendFeatureStatusLog(phase.featureId);
         await this.refreshResume();
         return cleared;
     }
+    /** Append a PhaseStatusLogEntry to the phase when its derived status changed
+     *  vs. the last recorded toStatus (baseline "draft" when empty, matching the
+     *  phase-creation literal). Idempotent across repeated reads of the same state. */
+    async #appendPhaseStatusLog(phaseId) {
+        await this.updatePhase(phaseId, (p) => {
+            const last = p.statusLog.at(-1)?.toStatus ?? "draft";
+            if (p.status !== last) {
+                p.statusLog = [...p.statusLog, {
+                        id: createStatusLogEntryId(),
+                        date: nowISO(),
+                        fromStatus: last,
+                        toStatus: p.status,
+                        title: `${last} → ${p.status}`,
+                        description: "",
+                    }];
+            }
+            return p;
+        });
+    }
+    /** Append a StatusLogEntry to the feature when its derived status changed
+     *  vs. the last recorded toStatus (baseline "planned" when empty, matching
+     *  the feature-creation/empty-phases derivation). Idempotent. */
+    async #appendFeatureStatusLog(featureId) {
+        const features = await this.loadFeatures();
+        const feature = features.features.find((f) => f.id === featureId);
+        if (!feature)
+            return;
+        const last = feature.statusLog.at(-1)?.toStatus ?? "planned";
+        if (feature.status !== last) {
+            await this.updateFeatures((doc) => {
+                const target = doc.features.find((f) => f.id === featureId);
+                if (target && target.statusLog.at(-1)?.toStatus !== feature.status) {
+                    const baseline = target.statusLog.at(-1)?.toStatus ?? "planned";
+                    target.statusLog = [...target.statusLog, {
+                            id: createStatusLogEntryId(),
+                            date: nowISO(),
+                            fromStatus: baseline,
+                            toStatus: feature.status,
+                            title: `${baseline} → ${feature.status}`,
+                            description: "",
+                        }];
+                }
+                return doc;
+            });
+        }
+    }
     // ── Savers ───────────────────────────────────────────────────────────
     async updateProject(updater) {
-        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, updater);
+        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, updater, this.root);
         await this.maybeAutoSync();
         return updated;
     }
@@ -1154,14 +1669,14 @@ export class PlanStore {
         return updated;
     }
     async updateRequirements(updater) {
-        const updated = await atomicUpdateJson(this.requirementsPath(), RequirementsDocumentSchema, updater);
+        const updated = await atomicUpdateJson(this.requirementsPath(), RequirementsDocumentSchema, updater, this.root);
         await this.maybeAutoSync();
         return updated;
     }
     async saveProject(project) {
         const parsed = ProjectSchema.parse(project);
-        await atomicWriteJson(this.projectPath(), parsed);
-        await this.touchManifest();
+        await atomicWriteJson(this.projectPath(), parsed, this.root);
+        await this.touchTimestamp();
         await this.maybeAutoSync();
     }
     async saveFeatures(features) {
@@ -1169,7 +1684,7 @@ export class PlanStore {
             await this.migrateLegacy();
             await this.saveFeaturesRaw(features);
         });
-        await this.touchManifest();
+        await this.touchTimestamp();
         await this.maybeAutoSync();
     }
     /** Per-file write of all features + orphan reconcile. No lock (caller holds withFeaturesLock). */
@@ -1178,7 +1693,7 @@ export class PlanStore {
         await mkdir(this.featuresDir(), { recursive: true });
         const wantIds = new Set(parsed.features.map((f) => f.id));
         for (const feat of parsed.features) {
-            await atomicWriteJson(this.featurePath(feat.id), feat);
+            await atomicWriteJson(this.featurePath(feat.id), feat, this.root);
         }
         // Orphan reconcile: remove feature files no longer in the document.
         try {
@@ -1202,27 +1717,43 @@ export class PlanStore {
             await this.migrateLegacy();
             await mkdir(this.featuresDir(), { recursive: true });
             const parsed = FeatureSchema.parse(feature);
-            await atomicWriteJson(this.featurePath(parsed.id), parsed);
+            await atomicWriteJson(this.featurePath(parsed.id), parsed, this.root);
         });
-        await this.touchManifest();
+        await this.touchTimestamp();
         await this.maybeAutoSync();
     }
     async saveRequirements(reqs) {
         const parsed = RequirementsDocumentSchema.parse(reqs);
-        await atomicWriteJson(this.requirementsPath(), parsed);
-        await this.touchManifest();
+        await atomicWriteJson(this.requirementsPath(), parsed, this.root);
+        await this.touchTimestamp();
     }
     async savePhase(phase) {
-        const parsed = PhaseSchema.parse(this.normalizePhaseDocument(phase).phase);
+        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 parsed = PhaseSchema.parse(this.normalizePhaseDocument(normalizedInput).phase);
         await mkdir(this.phasesDir(), { recursive: true });
-        await atomicWriteJson(this.phasePath(parsed.id), parsed);
-        await this.touchManifest();
+        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) {
+        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
@@ -1230,7 +1761,15 @@ export class PlanStore {
         const raw = await atomicUpdateJson(this.phasePath(phaseId), PhaseSchema, (rawPhase) => {
             const current = { ...rawPhase, status: this.derivePhaseStatus(rawPhase.tasks) };
             const next = updater(current);
-            return this.normalizePhaseDocument(next).phase;
+            const resolvedFeatureId = resolveStoredFeatureId(features, next.featureId);
+            // Referential integrity: reject orphan featureId.
+            if (next.featureId && next.featureId.trim() && !resolvedFeatureId) {
+                throw new PlanStoreError(`Cannot update phase: featureId "${next.featureId}" does not match any existing feature.`);
+            }
+            const normalizedInput = resolvedFeatureId && resolvedFeatureId !== next.featureId
+                ? { ...next, featureId: resolvedFeatureId }
+                : next;
+            return this.normalizePhaseDocument(normalizedInput).phase;
         });
         await this.maybeAutoSync();
         return { ...raw, status: this.derivePhaseStatus(raw.tasks) };
@@ -1246,10 +1785,74 @@ export class PlanStore {
         const now = new Date().toISOString();
         await this.updatePhase(phaseId, (phase) => ({ ...phase, handoff: text, handoffUpdatedAt: now }));
     }
-    /** Clear the handoff text for a phase (handoff=""). handoffUpdatedAt is left
-     *  unchanged as an audit trail (when a handoff last existed). */
-    async clearPhaseHandoff(phaseId) {
-        await this.updatePhase(phaseId, (phase) => ({ ...phase, handoff: "" }));
+    /** Mark the phase handoff as read/acknowledged on recap (sets handoffReadAt).
+     *  Does NOT clear the handoff — content is kept until a task starts or the
+     *  phase completes, so a restart between read and resume does not lose it. */
+    async markHandoffRead(phaseId) {
+        await this.updatePhase(phaseId, (phase) => ({ ...phase, handoffReadAt: nowISO() }));
+    }
+    /** One-time import of a legacy .planner/HANDOFF.md file (file-based handoff
+     *  from before F004) into the entity-scoped phase.handoff. Idempotent: if the
+     *  file is absent or empty, no-op. If it exists + non-empty + the target phase
+     *  has no handoff, writes the content onto the current in-progress phase (or
+     *  the first phase if none in-progress) with an "imported" handoffHistory entry,
+     *  then renames the file to HANDOFF.md.bak so it won't re-import. If the target
+     *  already has a handoff, the entity-scoped one wins and the file is just .bak'd. */
+    async importLegacyHandoffFile() {
+        const filePath = join(this.root, "HANDOFF.md");
+        const content = await readFile(filePath, "utf-8").catch(() => null);
+        if (content === null)
+            return { imported: false };
+        if (content.trim() === "") {
+            await rename(filePath, filePath + ".bak").catch(() => { });
+            return { imported: false };
+        }
+        const phases = await this.loadAllPhases();
+        const target = phases.find((p) => p.status === "in-progress") ?? phases[0] ?? null;
+        if (!target)
+            return { imported: false }; // no phases yet — leave file for a later run
+        if ((target.handoff ?? "") === "") {
+            await this.setPhaseHandoff(target.id, content + "\n\n<!-- imported from legacy .planner/HANDOFF.md -->\n");
+            await this.updatePhase(target.id, (p) => ({
+                ...p,
+                handoffHistory: [{ file: "(legacy HANDOFF.md)", clearedAt: nowISO(), reason: "imported" }, ...(p.handoffHistory ?? [])].slice(0, 5),
+            }));
+        }
+        await rename(filePath, filePath + ".bak").catch(() => { });
+        const features = await this.loadFeatures();
+        const feat = features.features.find((f) => f.id === target.featureId);
+        return { imported: true, phaseRef: formatPhaseRef(target.number, feat?.number) };
+    }
+    /** Clear the handoff for a phase, archiving its content first. The handoff
+     *  markdown is written to .planner/handoff-archive/<phaseId>-<ISO>.md and a
+     *  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: "task-started" | "phase-done" | "manual" | "superseded" | "imported". */
+    async clearPhaseHandoff(phaseId, reason = "manual") {
+        await this.migrateLegacyHandoffArchive();
+        const phase = await this.loadPhase(phaseId).catch(() => null);
+        if (!phase || phase.handoff === "")
+            return; // nothing to archive
+        const clearedAt = nowISO();
+        const safeTs = clearedAt.replace(/[:.]/g, "-");
+        const archiveDir = this.handoffArchiveDir();
+        await mkdir(archiveDir, { recursive: true }).catch(() => { });
+        const fileName = `${phaseId}-${safeTs}.md`;
+        const filePath = join(archiveDir, fileName);
+        await atomicWriteText(filePath, phase.handoff, this.root);
+        const entry = { file: `handoff-archive/${fileName}`, clearedAt, reason };
+        // Cap history at 5: prepend new entry, drop oldest (and delete its file).
+        const trimmed = [entry, ...(phase.handoffHistory ?? [])].slice(0, 5);
+        const dropped = (phase.handoffHistory ?? []).slice(4); // entries beyond index 4 after prepend
+        for (const d of dropped) {
+            if (!d?.file)
+                continue;
+            // Legacy entries used `.planner/handoff-archive/...`; new entries use `.planner/.local/handoff-archive/...`.
+            await unlink(join(this.handoffArchiveDir(), basename(d.file))).catch(() => { });
+            await unlink(join(this.root, d.file)).catch(() => { });
+        }
+        await this.updatePhase(phaseId, (p) => ({ ...p, handoff: "", handoffHistory: trimmed }));
     }
     /** List all phases that have a non-empty handoff, newest first, with a
      *  human-readable composite ref (P00x or P00x(F00x)) and a first-line excerpt. */
@@ -1266,14 +1869,64 @@ export class PlanStore {
             const fnum = p.featureId ? featureNumber.get(p.featureId) : undefined;
             out.push({
                 phaseId: p.id,
+                featureId: p.featureId,
                 compositeRef: formatPhaseRef(p.number, fnum),
                 updatedAt: p.handoffUpdatedAt || p.updatedAt,
                 firstLine: handoffFirstLine(p.handoff),
+                content: p.handoff,
             });
         }
         out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
         return out;
     }
+    async listOrphanPhases() {
+        const phases = await this.loadAllPhases();
+        const featuresDoc = await this.loadFeatures();
+        const out = [];
+        for (const phase of phases) {
+            const resolvedFeatureId = resolveStoredFeatureId(featuresDoc.features, phase.featureId);
+            if (resolvedFeatureId)
+                continue;
+            const reason = phase.featureId?.trim()
+                ? `feature not found: ${phase.featureId}`
+                : "missing featureId";
+            out.push({
+                phaseId: phase.id,
+                featureId: phase.featureId,
+                shortId: phase.shortId,
+                compositeRef: formatPhaseRef(phase.number),
+                title: phase.title,
+                reason,
+            });
+        }
+        out.sort((a, b) => a.compositeRef.localeCompare(b.compositeRef));
+        return out;
+    }
+    async cleanupOrphanPhases() {
+        return this.runAsBatch(async () => {
+            const found = await this.listOrphanPhases();
+            if (found.length === 0)
+                return { found, removed: [] };
+            const orphanIds = new Set(found.map((phase) => phase.phaseId));
+            for (const orphan of found) {
+                try {
+                    await unlink(this.phasePath(orphan.phaseId));
+                }
+                catch {
+                    // already gone
+                }
+            }
+            await this.updateFeatures((doc) => {
+                for (const feature of doc.features) {
+                    feature.phaseIds = feature.phaseIds.filter((id) => !orphanIds.has(id));
+                }
+                return doc;
+            });
+            await this.touchTimestamp();
+            await this.writeGenerated();
+            return { found, removed: found };
+        });
+    }
     async deletePhase(phaseId) {
         try {
             await unlink(this.phasePath(phaseId));
@@ -1281,7 +1934,7 @@ export class PlanStore {
         catch {
             // already gone
         }
-        await this.touchManifest();
+        await this.touchTimestamp();
     }
     // ── Workspace-level operations ─────────────────────────────────────
     /** Load the full workspace (manifest + phases + project + requirements + features) */
@@ -1294,8 +1947,10 @@ export class PlanStore {
         return { manifest, phases, project, features, requirements };
     }
     // ── Markdown generation ────────────────────────────────────────────
-    /** Load all data, render markdown, and write into generated/. */
+    /** Load all data, render markdown, and write into generated/. Skips files
+     *  whose content is unchanged to avoid unnecessary backup churn. */
     async writeGenerated() {
+        await this.migrateLegacyGeneratedDir();
         const { PlanRenderer } = await import("./renderer.js");
         const plan = await this.loadAll();
         const renderer = new PlanRenderer();
@@ -1311,21 +1966,27 @@ export class PlanStore {
             if (dir !== genDir) {
                 await mkdir(dir, { recursive: true });
             }
+            try {
+                const existing = await readFile(fullPath, "utf-8");
+                if (existing === content)
+                    continue;
+            }
+            catch {
+                // file does not exist yet — write it
+            }
             await writeFile(fullPath, content, "utf-8");
             written.push(relPath);
         }
         return written;
     }
     // ── Touch ────────────────────────────────────────────────────────────
-    /** Update manifest.updatedAt to reflect a change. */
-    async touchManifest() {
+    /** Update .local/timestamp.json to reflect a change. */
+    async touchTimestamp() {
         try {
-            const m = await this.loadManifest();
-            m.updatedAt = nowISO();
-            await atomicWriteJson(this.manifestPath(), m);
+            await atomicWriteJson(this.timestampPath(), { updatedAt: nowISO() }, this.root);
         }
         catch {
-            // if manifest doesn't exist yet, skip
+            // if .local/ doesn't exist yet, skip
         }
     }
 }