@agent-plan/core 0.2.19-next.9 → 0.2.20

package/dist/plan-store.js

@@ -1,15 +1,53 @@
-import { access, copyFile, mkdir, readdir, readFile, rename, 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, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+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 +70,97 @@ let writeNotifyHook;
 export function setWriteNotifyHook(hook) {
     writeNotifyHook = hook;
 }
+const CROSS_PROCESS_LOCK_STALE_MS = 30_000;
+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 AllocationRegistrySchema = z.object({
+    version: z.literal(1),
+    projectId: z.string().min(1),
+    allocations: z.array(z.object({
+        kind: AllocationKindSchema,
+        entityId: z.string().min(1),
+        number: z.number().int().positive(),
+        shortId: z.string().regex(/^[A-Z2-9]{5}$/),
+    })).default([]),
+});
+async function gitCommonDirFor(planRoot) {
+    let current = resolve(planRoot);
+    for (;;) {
+        const dotGit = join(current, ".git");
+        try {
+            const info = await stat(dotGit);
+            if (info.isDirectory())
+                return dotGit;
+            const pointer = await readFile(dotGit, "utf8");
+            const match = pointer.match(/^gitdir:\s*(.+)\s*$/m);
+            if (!match?.[1])
+                return undefined;
+            const worktreeGitDir = resolve(current, match[1]);
+            const commonDirRef = await readFile(join(worktreeGitDir, "commondir"), "utf8").catch(() => "");
+            return commonDirRef.trim() ? resolve(worktreeGitDir, commonDirRef.trim()) : worktreeGitDir;
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return undefined;
+            current = parent;
+        }
+    }
+}
+async function writeRegistry(path, registry) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    await writeFile(tmp, JSON.stringify(registry, null, 2), "utf8");
+    await rename(tmp, path);
+}
+async function acquireCrossProcessLock(path) {
+    const lockPath = `${path}.lock`;
+    await mkdir(dirname(lockPath), { recursive: true });
+    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 +168,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 +211,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 +223,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);
@@ -271,20 +418,55 @@ export async function migrateToGlobalSequence(store) {
     });
 }
 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 {
@@ -336,23 +518,43 @@ export class PlanStore {
     normalizeTasks(tasks) {
         // 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 };
+        const normalized = tasks.map((task) => task.description && !task.descriptionUpdatedAt
+            ? { ...task, descriptionUpdatedAt: task.createdAt }
+            : task);
+        return { tasks: normalized, changed: normalized.some((task, index) => task !== tasks[index]) };
+    }
+    /** 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)
+            return { ...entity, descriptionUpdatedAt: "" };
+        if (previousDescription === undefined || previousDescription !== entity.description) {
+            return { ...entity, descriptionUpdatedAt: timestamp };
+        }
+        return entity.descriptionUpdatedAt ? entity : { ...entity, descriptionUpdatedAt: entity.createdAt };
     }
     normalizeFeaturesDocument(doc) {
         // Numbers are a STABLE global sequence (assigned once at create from project.nextFeatureNumber).
-        return { doc, changed: false };
+        const features = doc.features.map((feature) => feature.description && !feature.descriptionUpdatedAt
+            ? { ...feature, descriptionUpdatedAt: feature.createdAt }
+            : feature);
+        return { doc: { ...doc, features }, changed: features.some((feature, index) => feature !== doc.features[index]) };
     }
     normalizePhaseDocument(phase) {
         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 descriptionTimestampChanged = descriptionUpdatedAt !== phase.descriptionUpdatedAt;
         return {
             phase: {
                 ...phase,
+                descriptionUpdatedAt,
                 tasks,
                 taskIds: nextTaskIds,
             },
-            changed: changed || taskIdsChanged,
+            changed: changed || taskIdsChanged || descriptionTimestampChanged,
         };
     }
     normalizeStructureSnapshot(featuresDoc, phases) {
@@ -361,7 +563,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);
@@ -504,7 +711,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(() => { });
     }
@@ -515,16 +722,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);
+    }
+    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) {
@@ -534,7 +806,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 = {
@@ -544,7 +820,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: "",
@@ -567,6 +844,7 @@ export class PlanStore {
             nextFeatureNumber: 1,
             nextPhaseNumber: 1,
             nextTaskNumber: 1,
+            workDeviations: [],
         });
         await this.saveRequirements({ requirements: [] });
         await this.saveFeatures({ features: [] });
@@ -594,7 +872,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");
@@ -604,16 +882,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/",
-            "handoff-archive/",
-            "",
-        ].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 {
@@ -625,29 +916,71 @@ export class PlanStore {
         }
     }
     // ── Loaders ──────────────────────────────────────────────────────────
+    /** Read-only manifest load. Upgrading legacy `.local` state is explicit
+     * maintenance (`repair`), never an incidental side effect of opening a plan. */
     async loadManifest() {
-        return readJson(this.manifestPath(), ManifestSchema);
+        const manifest = await readJson(this.manifestPath(), ManifestSchema);
+        const timestamp = await readJson(this.timestampPath(), z.object({ updatedAt: TimestampSchema })).catch(() => undefined);
+        return timestamp ? { ...manifest, updatedAt: timestamp.updatedAt } : 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).
+     * Reserve immutable human identifiers without touching tracked `project.json`.
+     * 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
+     * rewritten; cross-clone coordination requires a shared allocator service.
      */
-    async allocFeatureNumber() { return this.allocSeqNumber("nextFeatureNumber"); }
-    async allocPhaseNumber() { return this.allocSeqNumber("nextPhaseNumber"); }
-    async allocTaskNumber() { return this.allocSeqNumber("nextTaskNumber"); }
-    async allocSeqNumber(key) {
+    async allocateEntityIdentity(kind, entityId) {
         const project = await this.loadProject();
-        const n = project[key];
-        project[key] = n + 1;
-        await this.saveProject(project);
-        return n;
+        const manifest = await this.loadManifest();
+        const commonGitDir = await gitCommonDirFor(this.root);
+        const registryPath = commonGitDir
+            ? 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: [] })));
+            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);
+            if (prior)
+                return { number: prior.number, shortId: prior.shortId };
+            const phases = await this.loadAllPhases();
+            const features = (await this.loadFeatures()).features;
+            const canonical = kind === "feature"
+                ? features.map((feature) => ({ number: feature.number, shortId: feature.shortId }))
+                : kind === "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;
+            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)]),
+                ...registry.allocations.map((entry) => entry.shortId),
+            ].filter(Boolean));
+            const allocation = { kind, entityId, number, shortId: createShortId(allShortIds, `${kind}:${entityId}`) };
+            registry.allocations.push(allocation);
+            await writeRegistry(registryPath, registry);
+            return { number: allocation.number, shortId: allocation.shortId };
+        });
+    }
+    /** Compatibility helpers. New callers should allocate the number and shortId
+     * together with allocateEntityIdentity so reservation cannot be split. */
+    async allocFeatureNumber() { return this.allocateLegacyNumber("feature"); }
+    async allocPhaseNumber() { return this.allocateLegacyNumber("phase"); }
+    async allocTaskNumber() { return this.allocateLegacyNumber("task"); }
+    async allocateLegacyNumber(kind) {
+        const id = `legacy-${kind}-${randomUUID()}`;
+        return (await this.allocateEntityIdentity(kind, id)).number;
     }
     async loadPhase(phaseId) {
         const raw = await readJson(this.phasePath(phaseId), PhaseSchema);
@@ -700,7 +1033,10 @@ 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;
+        // Keep legacy feature descriptions displayable without rewriting on read.
+        // Phase/task reads already apply the equivalent creation-date fallback.
+        const normalizedFeatures = this.normalizeFeaturesDocument({ features }).doc.features;
+        return this.normalizeStructureSnapshot({ features: normalizedFeatures }, phases).features;
     }
     async loadCodebaseProfile() {
         try {
@@ -712,10 +1048,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);
         }
@@ -736,8 +1073,8 @@ export class PlanStore {
                 : (resume.nextStepsUpdatedAt || existing?.nextStepsUpdatedAt || nowISO()),
         };
         const parsed = ResumeFocusSchema.parse(withTs);
-        await atomicWriteJson(this.resumePath(), parsed);
-        await this.touchManifest();
+        await atomicWriteJson(this.resumePath(), parsed, this.root);
+        await this.touchTimestamp();
     }
     /**
      * Authorize a temporary guard bypass so edit/write tools may proceed even
@@ -783,6 +1120,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);
         }
@@ -798,8 +1136,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. */
@@ -831,6 +1169,33 @@ export class PlanStore {
             return { requirements: [] };
         }
     }
+    async linkedRequirementsForPhase(phaseId) {
+        const requirements = await this.loadRequirements();
+        return requirements.requirements.filter((requirement) => requirement.linkedPhaseIds.includes(phaseId));
+    }
+    /** Requirements linked to any phase belonging to a feature, deduplicated by ID. */
+    async linkedRequirementsForFeature(featureId) {
+        const [phases, requirements] = await Promise.all([this.loadAllPhases(), this.loadRequirements()]);
+        const phaseIds = new Set(phases.filter((phase) => phase.featureId === featureId).map((phase) => phase.id));
+        return requirements.requirements.filter((requirement) => requirement.linkedPhaseIds.some((phaseId) => phaseIds.has(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;
@@ -861,6 +1226,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(),
@@ -870,7 +1251,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. */
@@ -910,10 +1292,7 @@ export class PlanStore {
                 task.phaseId = newId;
             }
             await this.savePhase(phase);
-            try {
-                await unlink(this.phasePath(oldId));
-            }
-            catch { }
+            await this.unlinkPhaseFiles(oldId);
             renamed += 1;
         }
         // Repair feature.phaseIds: replace legacy refs with new ids, drop dangling ones.
@@ -1055,7 +1434,7 @@ export class PlanStore {
             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;
@@ -1074,7 +1453,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;
@@ -1088,7 +1467,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;
@@ -1128,17 +1507,38 @@ 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 handoffs = { archived: await this.archiveStaleHandoffs() };
             const integrity = await this.validateIntegrity();
             await this.writeGenerated();
-            return { migrated, backfill, containment, integrity };
+            return { migrated, backfill, containment, handoffs, 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();
@@ -1174,6 +1574,12 @@ 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");
+    }
     derivePhaseStatus(tasks) {
         if (tasks.length === 0)
             return "draft";
@@ -1184,18 +1590,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";
     }
@@ -1210,17 +1626,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";
     }
@@ -1230,33 +1654,112 @@ export class PlanStore {
         // (serve.ts, adapters) that invoke it after mutations.
         return [];
     }
-    /** Auto-clear a phase's handoff when its DERIVED status is done. Status itself
-     *  is no longer persisted (derived on read), so the only remaining side effect
-     *  of a task→done transition is clearing a stale handoff on a completed phase.
-     *  Returns the composite ref of the phase if its handoff was cleared, else null. */
+    /** 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. */
     async syncTaskStatusRollup(phaseId) {
         const phase = await this.loadPhase(phaseId);
         let cleared = null;
-        if (phase.status === "done" && phase.handoff !== "") {
+        if (this.hasCompletedHandoffLifecycle(phase.tasks) && phase.handoff !== "") {
             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;
     }
+    /** Persist an explicitly approved work deviation without coupling it to a harness. */
+    async addWorkDeviation(deviation) {
+        return this.updateProject((project) => ({
+            ...project,
+            workDeviations: [...project.workDeviations, deviation],
+        }));
+    }
+    /** Mark an approved/active deviation as resolved or canceled while retaining its audit record. */
+    async setWorkDeviationState(id, state, timestamp = nowISO()) {
+        return this.updateProject((project) => ({
+            ...project,
+            workDeviations: project.workDeviations.map((deviation) => deviation.id !== id ? deviation : {
+                ...deviation,
+                state,
+                activatedAt: state === "active" ? timestamp : deviation.activatedAt,
+                resolvedAt: state === "resolved" || state === "canceled" ? timestamp : deviation.resolvedAt,
+            }),
+        }));
+    }
     async updateFeatures(updater) {
         const updated = await this.withFeaturesLock(async () => {
             await this.migrateLegacy();
             const current = await this.loadFeatures();
-            const upd = this.normalizeFeaturesDocument(updater(current)).doc;
+            // 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 timestamp = nowISO();
+            const candidate = updater(current);
+            const stamped = {
+                features: candidate.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), timestamp)),
+            };
+            const upd = this.normalizeFeaturesDocument(stamped).doc;
             await this.saveFeaturesRaw(upd);
             return upd;
         });
@@ -1264,22 +1767,26 @@ 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) {
         await this.withFeaturesLock(async () => {
             await this.migrateLegacy();
-            await this.saveFeaturesRaw(features);
+            const previousDescriptions = new Map((await this.loadRawFeatures()).map((feature) => [feature.id, feature.description]));
+            const timestamp = nowISO();
+            await this.saveFeaturesRaw({
+                features: features.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), timestamp)),
+            });
         });
-        await this.touchManifest();
+        await this.touchTimestamp();
         await this.maybeAutoSync();
     }
     /** Per-file write of all features + orphan reconcile. No lock (caller holds withFeaturesLock). */
@@ -1288,7 +1795,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 {
@@ -1310,37 +1817,73 @@ export class PlanStore {
     async saveFeature(feature) {
         await this.withFeaturesLock(async () => {
             await this.migrateLegacy();
+            const previous = await readJson(this.featurePath(feature.id), FeatureSchema).catch(() => null);
             await mkdir(this.featuresDir(), { recursive: true });
-            const parsed = FeatureSchema.parse(feature);
-            await atomicWriteJson(this.featurePath(parsed.id), parsed);
+            const parsed = FeatureSchema.parse(this.stampDescriptionUpdatedAt(feature, previous?.description, nowISO()));
+            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 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);
-        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
         // not persisted); the return value is re-derived for the caller.
         const raw = await atomicUpdateJson(this.phasePath(phaseId), PhaseSchema, (rawPhase) => {
             const current = { ...rawPhase, status: this.derivePhaseStatus(rawPhase.tasks) };
+            // The updater may mutate `current`, therefore snapshot descriptions first.
+            const previousDescription = current.description;
+            const previousTaskDescriptions = new Map(current.tasks.map((task) => [task.id, task.description]));
+            const timestamp = nowISO();
             const next = updater(current);
-            return this.normalizePhaseDocument(next).phase;
+            const timestamped = this.stampDescriptionUpdatedAt(next, previousDescription, timestamp);
+            timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), timestamp));
+            const resolvedFeatureId = resolveStoredFeatureId(features, timestamped.featureId);
+            // Referential integrity: reject orphan featureId.
+            if (timestamped.featureId && timestamped.featureId.trim() && !resolvedFeatureId) {
+                throw new PlanStoreError(`Cannot update phase: featureId "${timestamped.featureId}" does not match any existing feature.`);
+            }
+            const normalizedInput = resolvedFeatureId && resolvedFeatureId !== timestamped.featureId
+                ? { ...timestamped, featureId: resolvedFeatureId }
+                : timestamped;
+            return this.normalizePhaseDocument(normalizedInput).phase;
         });
         await this.maybeAutoSync();
         return { ...raw, status: this.derivePhaseStatus(raw.tasks) };
@@ -1350,21 +1893,23 @@ export class PlanStore {
     async getPhaseHandoff(phaseId) {
         return (await this.loadPhase(phaseId)).handoff;
     }
-    /** Set the handoff text for a phase + stamp handoffUpdatedAt. Atomic per-file
-     *  update via updatePhase (so the web UI refreshes via maybeAutoSync). */
+    /** 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. */
     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 (phase.handoff && normalized && phase.handoff !== normalized) {
+            await this.clearPhaseHandoff(phaseId, "superseded");
+        }
         const now = new Date().toISOString();
-        await this.updatePhase(phaseId, (phase) => ({ ...phase, handoff: text, handoffUpdatedAt: now }));
-    }
-    /** Directory where cleared handoff content is archived as .md files
-     *  (gitignored). Keeps the phase JSON lean while making past handoffs
-     *  recoverable + human-readable. */
-    handoffArchiveDir() {
-        return join(this.root, "handoff-archive");
+        await this.updatePhase(phaseId, (current) => ({ ...current, handoff: normalized, handoffUpdatedAt: now }));
     }
     /** 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. */
+     *  Does NOT clear it: read/load/show are non-mutating resume operations. */
     async markHandoffRead(phaseId) {
         await this.updatePhase(phaseId, (phase) => ({ ...phase, handoffReadAt: nowISO() }));
     }
@@ -1385,9 +1930,11 @@ export class PlanStore {
             return { imported: false };
         }
         const phases = await this.loadAllPhases();
-        const target = phases.find((p) => p.status === "in-progress") ?? phases[0] ?? null;
+        const target = phases.find((p) => p.status === "in-progress")
+            ?? phases.find((p) => p.status !== "done" && p.status !== "canceled")
+            ?? null;
         if (!target)
-            return { imported: false }; // no phases yet — leave file for a later run
+            return { imported: false }; // no non-completed phase — 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) => ({
@@ -1405,8 +1952,9 @@ 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: "task-started" | "phase-done" | "manual" | "superseded" | "imported". */
+     *  reason: "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
@@ -1416,28 +1964,52 @@ export class PlanStore {
         await mkdir(archiveDir, { recursive: true }).catch(() => { });
         const fileName = `${phaseId}-${safeTs}.md`;
         const filePath = join(archiveDir, fileName);
-        await atomicWriteText(filePath, phase.handoff);
+        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)
-                await unlink(join(this.root, d.file)).catch(() => { });
+            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. */
+    /** Archive stale handoffs only after every task in their phase is done or
+     * canceled. 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");
+                archived += 1;
+            }
+        }
+        return archived;
+    }
+    /** Public maintenance operation for retroactively archiving stale handoffs. */
+    async cleanupStaleHandoffs() {
+        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() {
+        await this.archiveStaleHandoffs();
         const phases = await this.loadAllPhases();
         const features = await this.loadFeatures();
+        const featureIds = new Set(features.features.map((f) => f.id));
         const featureNumber = new Map();
         for (const f of features.features)
             featureNumber.set(f.id, f.number);
         const out = [];
         for (const p of phases) {
-            if (!p.handoff)
+            if (!p.handoff || p.status === "done" || p.status === "canceled")
+                continue;
+            if (p.featureId && !featureIds.has(p.featureId))
                 continue;
             const fnum = p.featureId ? featureNumber.get(p.featureId) : undefined;
             out.push({
@@ -1452,14 +2024,96 @@ export class PlanStore {
         out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
         return out;
     }
-    async deletePhase(phaseId) {
-        try {
-            await unlink(this.phasePath(phaseId));
+    /** List recoverable archived handoffs from phase.handoffHistory. Archived
+     * entries are never returned by listHandoffs() and are safe to show on a
+     * dedicated history page. */
+    async listArchivedHandoffs() {
+        const phases = await this.loadAllPhases();
+        const features = await this.loadFeatures();
+        const featureNumber = new Map();
+        for (const f of features.features)
+            featureNumber.set(f.id, f.number);
+        const out = [];
+        for (const phase of phases) {
+            const fnum = phase.featureId ? featureNumber.get(phase.featureId) : undefined;
+            for (const entry of phase.handoffHistory ?? []) {
+                if (!entry.file)
+                    continue;
+                const localPath = join(this.localRoot(), entry.file);
+                const legacyPath = join(this.root, entry.file);
+                const content = await readFile(localPath, "utf-8").catch(() => readFile(legacyPath, "utf-8").catch(() => ""));
+                out.push({
+                    phaseId: phase.id,
+                    featureId: phase.featureId,
+                    compositeRef: formatPhaseRef(phase.number, fnum),
+                    file: entry.file,
+                    archivedAt: entry.clearedAt,
+                    reason: entry.reason,
+                    firstLine: handoffFirstLine(content),
+                    content,
+                });
+            }
         }
-        catch {
-            // already gone
+        out.sort((a, b) => b.archivedAt.localeCompare(a.archivedAt));
+        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,
+            });
         }
-        await this.touchManifest();
+        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) {
+                await this.unlinkPhaseFiles(orphan.phaseId);
+            }
+            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) {
+        await this.unlinkPhaseFiles(phaseId);
+        await this.touchTimestamp();
+    }
+    /** Remove a phase file AND its inline .bak backup. atomicUpdateJson (used by
+     *  updatePhase without root) writes the backup inline at phases/<id>.json.bak,
+     *  and readJson falls back to `${path}.bak` on a missing main file — so a
+     *  delete that leaves the .bak behind would RESURRECT the deleted phase on
+     *  the next read. Feature backups (written with root) live under
+     *  .local/backups/ and are never read by readJson, so only the inline .bak
+     *  needs removing here. */
+    async unlinkPhaseFiles(phaseId) {
+        await unlink(this.phasePath(phaseId)).catch(() => { });
+        await unlink(`${this.phasePath(phaseId)}.bak`).catch(() => { });
     }
     // ── Workspace-level operations ─────────────────────────────────────
     /** Load the full workspace (manifest + phases + project + requirements + features) */
@@ -1472,8 +2126,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();
@@ -1489,21 +2145,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
         }
     }
 }