@agent-plan/core 0.2.19-next.0 → 0.2.19-next.10

package/dist/plan-store.js

@@ -1,6 +1,6 @@
-import { access, copyFile, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, PlanWorkspaceSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, } from "./schema.js";
+import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, } from "./schema.js";
 import { createFeatureId, createPhaseId, createRequirementId, createShortId, createTaskId, formatPhaseRef, isLegacyPhaseId } from "./naming.js";
 function nowISO() {
     return new Date().toISOString();
@@ -176,6 +176,100 @@ 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) {
     try {
         const raw = await readFile(path, "utf-8");
@@ -193,7 +287,6 @@ async function readJson(path, schema) {
         throw new PlanStoreError(`read failed: ${path}`, cause);
     }
 }
-// ─── PlanStore ──────────────────────────────────────────────────────────
 export class PlanStore {
     root;
     autoSync = false;
@@ -230,36 +323,24 @@ export class PlanStore {
     async runBatchForMigration(fn) {
         return this.runAsBatch(fn);
     }
+    /** Public batch wrapper: suspend autoSync (status rollup) for a sequence of
+     *  writes. Use for priority-only reorders so they don't recompute phase/feature
+     *  status (a reorder must not flip a partially-done feature to in-progress). */
+    async runBatch(fn) {
+        return this.runAsBatch(fn);
+    }
     async maybeAutoSync() {
-        if (!this.autoSync || this.syncGuard || this.batchInProgress)
-            return;
-        try {
-            this.syncGuard = true;
-            await this.syncStatuses();
-        }
-        finally {
-            this.syncGuard = false;
-        }
+        // No-op: status is derived on read, so there is nothing to sync after a
+        // 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);
@@ -289,10 +370,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));
@@ -301,12 +379,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;
@@ -316,16 +389,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;
@@ -340,7 +407,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);
@@ -352,6 +419,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() {
@@ -413,9 +526,6 @@ export class PlanStore {
     activityPath() {
         return join(this.root, "activity.json");
     }
-    handoffPath() {
-        return join(this.root, "HANDOFF.md");
-    }
     // ── Init ─────────────────────────────────────────────────────────────
     async init(projectName) {
         if (await this.exists()) {
@@ -454,6 +564,9 @@ export class PlanStore {
                 beforeTaskStart: [],
                 afterPhaseComplete: [],
             },
+            nextFeatureNumber: 1,
+            nextPhaseNumber: 1,
+            nextTaskNumber: 1,
         });
         await this.saveRequirements({ requirements: [] });
         await this.saveFeatures({ features: [] });
@@ -462,6 +575,7 @@ export class PlanStore {
             currentPhaseId: "",
             inProgressTaskIds: [],
             nextSteps: ["Run /planner project discuss to bootstrap discovery"],
+            nextStepsUpdatedAt: nowISO(),
             blockers: [],
             notes: "Project initialized. Awaiting discovery.",
             lastSessionSummary: "",
@@ -484,12 +598,20 @@ export class PlanStore {
             "- `schema/plan.schema.json` — JSON Schema for tooling",
         ].join("\n");
         await writeFile(join(this.root, "README.md"), readme, "utf-8");
-        // Write a .gitignore inside .planner/ so transient backup/tmp files are
+        // Write a .gitignore inside .planner/ so transient/derived files are
         // not tracked by the host project's git. Git respects nested .gitignore.
+        // - *.bak/*.tmp.*: crash backups from atomic writes
+        // - 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 files — do not track",
+            "# Agent Plan transient/derived files — do not track",
             "*.bak",
             "*.tmp.*",
+            "resume.json",
+            "resume.*.json",
+            "generated/",
+            "handoff-archive/",
             "",
         ].join("\n"), "utf-8");
     }
@@ -509,12 +631,33 @@ export class PlanStore {
     async loadProject() {
         return readJson(this.projectPath(), ProjectSchema);
     }
-    async loadPhase(phaseId) {
-        const phase = await readJson(this.phasePath(phaseId), PhaseSchema);
-        return this.normalizePhaseDocument(phase).phase;
+    /**
+     * 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"); }
+    async allocPhaseNumber() { return this.allocSeqNumber("nextPhaseNumber"); }
+    async allocTaskNumber() { return this.allocSeqNumber("nextTaskNumber"); }
+    async allocSeqNumber(key) {
+        const project = await this.loadProject();
+        const n = project[key];
+        project[key] = n + 1;
+        await this.saveProject(project);
+        return n;
     }
-    async loadFeatures() {
-        // Per-file layout: read features/<id>.json (one file per feature).
+    async loadPhase(phaseId) {
+        const raw = await readJson(this.phasePath(phaseId), PhaseSchema);
+        const normalized = this.normalizePhaseDocument(raw).phase;
+        return { ...normalized, status: this.derivePhaseStatus(normalized.tasks) };
+    }
+    /** Read raw feature files WITHOUT the derived `status` field. Used
+     *  internally so loadFeatures/loadAll can derive status from phases without
+     *  double-loading. */
+    async loadRawFeatures() {
         let jsonFiles = [];
         try {
             const all = await readdir(this.featuresDir());
@@ -524,28 +667,41 @@ export class PlanStore {
             // features/ absent → fall through to legacy single-file layout
         }
         if (jsonFiles.length > 0) {
-            const features = [];
+            const out = [];
             for (const f of jsonFiles) {
                 const id = f.replace(/\.json$/, "");
                 try {
-                    features.push(await readJson(this.featurePath(id), FeatureSchema));
+                    out.push(await readJson(this.featurePath(id), FeatureSchema));
                 }
                 catch (err) {
                     // Skip an invalid feature file rather than failing the whole load.
                     console.warn(`[plan-store] skipping invalid feature file ${f}:`, err);
                 }
             }
-            return this.normalizeFeaturesDocument({ features }).doc;
+            // Deterministic order: sort by the persisted `number` (creation order)
+            // so callers that renumber by index (normalizeFeaturesDocument) and
+            // callers that keep persisted numbers (loadAll) agree, regardless of the
+            // filesystem readdir order. Tiebreak by id for full determinism.
+            out.sort((a, b) => (a.number - b.number) || a.id.localeCompare(b.id));
+            return out;
         }
         // Legacy: single features.json (pre-migration read; migration writes on first write op).
         try {
             const legacy = await readJson(this.featuresPath(), FeaturesDocumentSchema);
-            return this.normalizeFeaturesDocument(legacy).doc;
+            const legacyFeatures = legacy.features;
+            legacyFeatures.sort((a, b) => (a.number - b.number) || a.id.localeCompare(b.id));
+            return legacyFeatures;
         }
         catch {
-            return { features: [] };
+            return [];
         }
     }
+    async loadFeatures() {
+        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;
+    }
     async loadCodebaseProfile() {
         try {
             return await readJson(this.codebasePath(), CodebaseProfileSchema);
@@ -568,7 +724,18 @@ export class PlanStore {
         }
     }
     async saveResume(resume) {
-        const parsed = ResumeFocusSchema.parse(resume);
+        // 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);
         await this.touchManifest();
     }
@@ -584,6 +751,7 @@ export class PlanStore {
             currentPhaseId: "",
             inProgressTaskIds: [],
             nextSteps: [],
+            nextStepsUpdatedAt: "",
             blockers: [],
             notes: "",
             lastSessionSummary: "",
@@ -622,44 +790,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}`;
@@ -684,6 +814,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 ?? "",
@@ -731,14 +862,15 @@ export class PlanStore {
         });
     }
     async loadAll() {
-        const [manifest, project, features, requirements, phases] = await Promise.all([
+        const [manifest, project, requirements, phases] = await Promise.all([
             this.loadManifest(),
             this.loadProject(),
-            this.loadFeatures(),
             this.loadRequirements(),
             this.loadAllPhases(),
         ]);
-        return PlanWorkspaceSchema.parse({ manifest, project, features, requirements, phases });
+        const rawFeatures = await this.loadRawFeatures();
+        const features = rawFeatures.map((f) => ({ ...f, status: this.deriveFeatureStatus(f.id, phases) }));
+        return { manifest, project, requirements, phases, features: { features } };
     }
     /** Migrate legacy non-feature-scoped phase ids to feature-scoped ids and repair
      *  dangling feature.phaseIds references. Idempotent. */
@@ -916,13 +1048,9 @@ 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) => {
@@ -1002,9 +1130,13 @@ export class PlanStore {
         return this.runAsBatch(async () => {
             const migrated = await this.migratePhaseIds();
             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 };
         });
     }
     /** Validate plan integrity: globally unique phase ids and resolvable feature.phaseIds. */
@@ -1042,123 +1174,77 @@ export class PlanStore {
         const duplicateShortIds = [...sidCounts.entries()].filter(([, c]) => c > 1).map(([id]) => id);
         return { duplicatePhaseIds, danglingPhaseIds, duplicateShortIds };
     }
-    derivePhaseStatus(phase) {
-        if (phase.tasks.length === 0)
-            return phase.status;
-        const taskStatuses = phase.tasks.map((task) => task.status);
-        const allRejectedOrCanceled = taskStatuses.every((status) => status === "rejected" || status === "canceled");
-        const anyBlocked = taskStatuses.some((status) => status === "blocked");
-        const anyInProgress = taskStatuses.some((status) => status === "in-progress");
-        const anyWaiting = taskStatuses.some((status) => status === "waiting");
-        const anyDeferred = taskStatuses.some((status) => status === "deferred");
-        const anyPlanned = taskStatuses.some((status) => status === "planned");
-        const anyDone = taskStatuses.some((status) => status === "done");
-        if (allRejectedOrCanceled)
+    derivePhaseStatus(tasks) {
+        if (tasks.length === 0)
+            return "draft";
+        const taskStatuses = tasks.map((task) => task.status);
+        // Ignore rejected/canceled tasks (void) when deriving progress.
+        const meaningful = taskStatuses.filter((s) => s !== "rejected" && s !== "canceled");
+        if (meaningful.length === 0)
             return "rejected";
-        if (anyBlocked)
-            return "blocked";
-        if (anyInProgress)
+        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"))
             return "in-progress";
-        if (anyWaiting)
+        // No progress at all ⇒ surface the stall / not-started state (blocked > waiting > deferred > planned).
+        if (meaningful.some((s) => s === "blocked"))
+            return "blocked";
+        if (meaningful.some((s) => s === "waiting"))
             return "waiting";
-        if (anyDeferred)
+        if (meaningful.some((s) => s === "deferred"))
             return "deferred";
-        if (anyPlanned)
-            return "planned";
-        if (anyDone)
-            return "done";
         return "planned";
     }
-    deriveFeatureStatus(featureId, currentStatus, phases) {
+    deriveFeatureStatus(featureId, phases) {
         const featurePhases = phases.filter((phase) => phase.featureId === featureId);
         if (featurePhases.length === 0)
-            return currentStatus;
+            return "planned";
         const phaseStatuses = featurePhases.map((phase) => phase.status);
-        const allRejectedOrCanceled = phaseStatuses.every((status) => status === "rejected" || status === "canceled");
-        const anyBlocked = phaseStatuses.some((status) => status === "blocked");
-        const anyActive = phaseStatuses.some((status) => status === "discovery" || status === "in-progress");
-        const anyWaiting = phaseStatuses.some((status) => status === "waiting");
-        const anyDeferred = phaseStatuses.some((status) => status === "deferred");
-        const anyPlannedLike = phaseStatuses.some((status) => status === "draft" || status === "planned");
-        const anyDone = phaseStatuses.every((status) => status === "done");
-        if (allRejectedOrCanceled)
+        // Ignore rejected/canceled phases when deriving progress.
+        const meaningful = phaseStatuses.filter((s) => s !== "rejected" && s !== "canceled");
+        if (meaningful.length === 0)
             return "rejected";
-        if (anyBlocked)
-            return "blocked";
-        if (anyActive)
+        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"))
             return "in-progress";
-        if (anyWaiting)
+        // No progress at all ⇒ surface the stall / not-started state.
+        if (meaningful.some((s) => s === "blocked"))
+            return "blocked";
+        if (meaningful.some((s) => s === "waiting"))
             return "waiting";
-        if (anyDeferred)
+        if (meaningful.some((s) => s === "deferred"))
             return "deferred";
-        if (anyPlannedLike)
-            return "planned";
-        if (anyDone)
-            return "done";
         return "planned";
     }
     async syncStatuses() {
-        // Run as a batch so the internal saveFeatures + N savePhase calls do not
-        // re-trigger syncStatuses on every write (O(N^2) on large planners).
-        // Returns the composite refs of phases whose handoff was auto-cleared
-        // (phase transitioned to done).
-        const cleared = [];
-        await this.runAsBatch(async () => {
-            await this.migratePhaseIds();
-            const workspace = await this.loadAll();
-            const { phases, features } = workspace;
-            const featNum = new Map(features.features.map((f) => [f.id, f.number]));
-            // 1. Update Phase statuses based on tasks; auto-clear handoff when a
-            //    phase transitions to done (completed phases don't keep stale
-            //    handoffs). handoffUpdatedAt is kept as an audit trail.
-            for (const phase of phases) {
-                const was = phase.status;
-                phase.status = this.derivePhaseStatus(phase);
-                if (phase.status === "done" && was !== "done" && phase.handoff) {
-                    phase.handoff = "";
-                    cleared.push(formatPhaseRef(phase.number, featNum.get(phase.featureId ?? "")));
-                }
-            }
-            // 2. Update Feature statuses based on phases
-            for (const feature of features.features) {
-                feature.status = this.deriveFeatureStatus(feature.id, feature.status, phases);
-            }
-            // 3. Save everything
-            await this.saveFeatures(features);
-            for (const phase of phases) {
-                await this.savePhase(phase);
-            }
-            // 4. Refresh resume focus so a subentrating agent sees current state
-            await this.refreshResume();
-        });
-        return cleared;
-    }
-    /** Optimized rollup: syncs only the affected phase and its parent feature.
-     *  Drastically reduces write operations and 'busy' window for task updates.
-     *  Returns the composite ref of the phase if its handoff was auto-cleared
-     *  (phase transitioned to done), else null. */
+        // No-op: phase/feature status is now DERIVED at read time (never persisted),
+        // so there is nothing to sync. Kept for backward compatibility with callers
+        // (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. */
     async syncTaskStatusRollup(phaseId) {
         const phase = await this.loadPhase(phaseId);
-        const was = phase.status;
-        phase.status = this.derivePhaseStatus(phase);
-        // Auto-clear handoff when the phase transitions to done.
-        const cleared = phase.status === "done" && was !== "done" && phase.handoff !== "";
-        if (cleared)
-            phase.handoff = "";
-        await this.savePhase(phase);
-        let feature;
-        if (phase.featureId) {
-            const featuresDoc = await this.loadFeatures();
-            feature = featuresDoc.features.find((f) => f.id === phase.featureId);
-            if (feature) {
-                // To derive feature status, we still need the statuses of all its phases
-                const allPhases = await this.loadAllPhases();
-                feature.status = this.deriveFeatureStatus(feature.id, feature.status, allPhases);
-                await this.saveFeatures(featuresDoc);
-            }
+        let cleared = null;
+        if (phase.status === "done" && 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);
         }
         await this.refreshResume();
-        return cleared ? formatPhaseRef(phase.number, feature?.number) : null;
+        return cleared;
     }
     // ── Savers ───────────────────────────────────────────────────────────
     async updateProject(updater) {
@@ -1247,9 +1333,17 @@ export class PlanStore {
      *  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 updated = await atomicUpdateJson(this.phasePath(phaseId), PhaseSchema, (phase) => this.normalizePhaseDocument(updater(phase)).phase);
+        // 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) };
+            const next = updater(current);
+            return this.normalizePhaseDocument(next).phase;
+        });
         await this.maybeAutoSync();
-        return updated;
+        return { ...raw, status: this.derivePhaseStatus(raw.tasks) };
     }
     // ── Phase-scoped handoff (entity field, harness-agnostic) ────────────
     /** Get the handoff text for a phase ("" if none). Throws if phase missing. */
@@ -1262,10 +1356,76 @@ 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: "" }));
+    /** 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");
+    }
+    /** 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") {
+        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);
+        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(() => { });
+        }
+        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. */
@@ -1282,9 +1442,11 @@ 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));