@agent-plan/core 0.2.18 → 0.2.19-next.1

package/dist/plan-store.js

@@ -1,7 +1,7 @@
-import { access, copyFile, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CodebaseProfileSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, PlanWorkspaceSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, } from "./schema.js";
-import { createFeatureId, createPhaseId, createRequirementId, createTaskId, isLegacyPhaseId } from "./naming.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();
 }
@@ -108,6 +108,12 @@ async function atomicUpdateJson(path, schema, updater) {
         return parsed;
     });
 }
+/** Extract the first meaningful line of a handoff: skip blank lines, strip a
+ *  leading markdown header (#), trim, and truncate to ~80 chars. */
+function handoffFirstLine(text) {
+    const line = text.trim().split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
+    return line.replace(/^#+\s*/, "").trim().slice(0, 80);
+}
 export async function migrateToUuids(store) {
     // Run as a batch so internal saveFeatures/savePhase calls do not
     // re-trigger syncStatuses (O(N^2) on large planners). Idempotent: if there
@@ -187,7 +193,6 @@ async function readJson(path, schema) {
         throw new PlanStoreError(`read failed: ${path}`, cause);
     }
 }
-// ─── PlanStore ──────────────────────────────────────────────────────────
 export class PlanStore {
     root;
     autoSync = false;
@@ -224,16 +229,15 @@ 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;
@@ -335,7 +339,7 @@ export class PlanStore {
     }
     async ensureStructureOrdering() {
         return this.runAsBatch(async () => {
-            const featuresDoc = await readJson(this.featuresPath(), FeaturesDocumentSchema).catch(() => ({ features: [] }));
+            const featuresDoc = await this.loadFeatures();
             const phases = await this.loadAllPhases();
             const normalized = this.normalizeStructureSnapshot(featuresDoc, phases);
             if (!normalized.changed)
@@ -360,6 +364,35 @@ export class PlanStore {
     featuresPath() {
         return join(this.root, "features.json");
     }
+    featuresDir() {
+        return join(this.root, "features");
+    }
+    featurePath(featureId) {
+        return join(this.featuresDir(), `${featureId}.json`);
+    }
+    withFeaturesLock(fn) {
+        // Sentinel-keyed mutex (the features dir path) serializing all feature
+        // mutations so read-modify-write via updateFeatures is race-free and the
+        // one-time legacy→per-file migration never interleaves with a writer.
+        return withWriteLock(this.featuresDir(), fn);
+    }
+    /** Idempotent one-time migration: if a legacy features.json exists, split it
+     *  into features/<id>.json (one per feature) and remove the legacy file.
+     *  Must be called under withFeaturesLock. Crash-safe: re-run overwrites. */
+    async migrateLegacy() {
+        let legacy;
+        try {
+            legacy = await readJson(this.featuresPath(), FeaturesDocumentSchema);
+        }
+        catch {
+            return; // no legacy features.json (already migrated or fresh project)
+        }
+        await mkdir(this.featuresDir(), { recursive: true });
+        for (const feat of legacy.features) {
+            await atomicWriteJson(this.featurePath(feat.id), feat);
+        }
+        await unlink(this.featuresPath()).catch(() => { });
+    }
     phasesDir() {
         return join(this.root, "phases");
     }
@@ -388,6 +421,7 @@ export class PlanStore {
         }
         await mkdir(this.root, { recursive: true });
         await mkdir(this.phasesDir(), { recursive: true });
+        await mkdir(this.featuresDir(), { recursive: true });
         await mkdir(join(this.generatedDir(), "phases"), { recursive: true });
         await mkdir(join(this.root, "schema"), { recursive: true });
         await mkdir(join(this.root, "adapters"), { recursive: true });
@@ -474,18 +508,58 @@ export class PlanStore {
         return readJson(this.projectPath(), ProjectSchema);
     }
     async loadPhase(phaseId) {
-        const phase = await readJson(this.phasePath(phaseId), PhaseSchema);
-        return this.normalizePhaseDocument(phase).phase;
-    }
-    async loadFeatures() {
+        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 features = await readJson(this.featuresPath(), FeaturesDocumentSchema);
-            return this.normalizeFeaturesDocument(features).doc;
+            const all = await readdir(this.featuresDir());
+            jsonFiles = all.filter((f) => f.endsWith(".json"));
         }
         catch {
-            return { features: [] };
+            // features/ absent → fall through to legacy single-file layout
+        }
+        if (jsonFiles.length > 0) {
+            const out = [];
+            for (const f of jsonFiles) {
+                const id = f.replace(/\.json$/, "");
+                try {
+                    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);
+                }
+            }
+            // 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);
+            const legacyFeatures = legacy.features;
+            legacyFeatures.sort((a, b) => (a.number - b.number) || a.id.localeCompare(b.id));
+            return legacyFeatures;
+        }
+        catch {
+            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);
@@ -671,14 +745,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. */
@@ -795,13 +870,156 @@ export class PlanStore {
         catch { /* best-effort */ }
         return { removed };
     }
+    /** All non-empty shortIds currently assigned in the project (features + phases + tasks).
+     *  Read-only; used by createShortId collision guard during entity creation. */
+    async assignedShortIds() {
+        const features = await this.loadFeatures();
+        const phases = await this.loadAllPhases();
+        const ids = new Set();
+        for (const f of features.features)
+            if (f.shortId)
+                ids.add(f.shortId);
+        for (const p of phases) {
+            if (p.shortId)
+                ids.add(p.shortId);
+            for (const t of p.tasks)
+                if (t.shortId)
+                    ids.add(t.shortId);
+        }
+        return ids;
+    }
+    /** Next priority (>=1) for a new entity within its scope.
+     *  - feature: max priority among features + 1
+     *  - phase: max priority among phases of parentId (featureId) + 1
+     *  - task: max priority among tasks of parentId (phaseId) + 1 */
+    async nextPriority(kind, parentId) {
+        if (kind === "feature") {
+            const features = await this.loadFeatures();
+            const max = features.features.reduce((m, f) => Math.max(m, f.priority ?? 0), 0);
+            return max + 1;
+        }
+        if (kind === "phase") {
+            const phases = await this.loadAllPhases();
+            const siblings = phases.filter((p) => p.featureId === parentId);
+            const max = siblings.reduce((m, p) => Math.max(m, p.priority ?? 0), 0);
+            return max + 1;
+        }
+        // task
+        const phase = parentId ? await this.loadPhase(parentId).catch(() => undefined) : undefined;
+        const tasks = phase?.tasks ?? [];
+        const max = tasks.reduce((m, t) => Math.max(m, t.priority ?? 0), 0);
+        return max + 1;
+    }
+    /** Idempotent backfill of shortId (globally-unique 5-char Crockford) and priority
+     *  (per-scope display order). Assigns missing shortIds and priorities; never overwrites
+     *  existing non-empty shortIds or non-zero priorities. Safe to run at startup. */
+    async ensureShortIdsAndPriority() {
+        return this.runAsBatch(async () => {
+            const featuresDoc = await this.loadFeatures();
+            const phases = await this.loadAllPhases();
+            const existing = new Set();
+            for (const f of featuresDoc.features)
+                if (f.shortId)
+                    existing.add(f.shortId);
+            for (const p of phases) {
+                if (p.shortId)
+                    existing.add(p.shortId);
+                for (const t of p.tasks)
+                    if (t.shortId)
+                        existing.add(t.shortId);
+            }
+            let shortIdsAssigned = 0;
+            let prioritiesAssigned = 0;
+            let featuresDirty = false;
+            const assignPriority = (current, index) => {
+                if (current === 0) {
+                    prioritiesAssigned += 1;
+                    return index + 1;
+                }
+                return current;
+            };
+            // Features: shortId + priority (project scope)
+            const sortedFeatures = [...featuresDoc.features].sort((a, b) => a.number - b.number || a.createdAt.localeCompare(b.createdAt));
+            sortedFeatures.forEach((f, index) => {
+                if (!f.shortId) {
+                    f.shortId = createShortId(existing);
+                    existing.add(f.shortId);
+                    shortIdsAssigned += 1;
+                    featuresDirty = true;
+                }
+                const nextP = assignPriority(f.priority ?? 0, index);
+                if (nextP !== f.priority) {
+                    f.priority = nextP;
+                    featuresDirty = true;
+                }
+            });
+            if (featuresDirty) {
+                featuresDoc.features.sort((a, b) => a.priority - b.priority || a.number - b.number);
+                await this.saveFeatures(featuresDoc);
+            }
+            // Phases + tasks
+            for (const phase of phases) {
+                let phaseDirty = false;
+                if (!phase.shortId) {
+                    phase.shortId = createShortId(existing);
+                    existing.add(phase.shortId);
+                    shortIdsAssigned += 1;
+                    phaseDirty = true;
+                }
+                const phaseIndex = phase.number - 1; // stable pre-migration order
+                const nextPP = assignPriority(phase.priority ?? 0, phaseIndex < 0 ? 0 : phaseIndex);
+                if (nextPP !== phase.priority) {
+                    phase.priority = nextPP;
+                    phaseDirty = true;
+                }
+                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);
+                        existing.add(t.shortId);
+                        shortIdsAssigned += 1;
+                        phaseDirty = true;
+                    }
+                    const nextTP = assignPriority(t.priority ?? 0, index);
+                    if (nextTP !== t.priority) {
+                        t.priority = nextTP;
+                        phaseDirty = true;
+                    }
+                });
+                if (phaseDirty) {
+                    phase.tasks.sort((a, b) => a.priority - b.priority || a.number - b.number);
+                    phase.taskIds = phase.tasks.map((t) => t.id);
+                    phase.updatedAt = nowISO();
+                    await this.savePhase(phase);
+                }
+            }
+            // Duplicate shortId report (across all entities)
+            const allShortIds = [];
+            for (const f of featuresDoc.features)
+                if (f.shortId)
+                    allShortIds.push(f.shortId);
+            for (const ph of phases) {
+                if (ph.shortId)
+                    allShortIds.push(ph.shortId);
+                for (const t of ph.tasks)
+                    if (t.shortId)
+                        allShortIds.push(t.shortId);
+            }
+            const counts = new Map();
+            for (const id of allShortIds)
+                counts.set(id, (counts.get(id) ?? 0) + 1);
+            const duplicateShortIds = [...counts.entries()].filter(([, c]) => c > 1).map(([id]) => id);
+            return { shortIdsAssigned, prioritiesAssigned, duplicateShortIds };
+        });
+    }
     /** Repair dangling references and report integrity. One-shot maintenance op. */
     async repair() {
         return this.runAsBatch(async () => {
             const migrated = await this.migratePhaseIds();
+            const backfill = await this.ensureShortIdsAndPriority();
             const integrity = await this.validateIntegrity();
             await this.writeGenerated();
-            return { migrated, integrity };
+            return { migrated, backfill, integrity };
         });
     }
     /** Validate plan integrity: globally unique phase ids and resolvable feature.phaseIds. */
@@ -821,104 +1039,95 @@ export class PlanStore {
                     danglingPhaseIds.push(`${feature.id} -> ${ref}`);
             }
         }
-        return { duplicatePhaseIds, danglingPhaseIds };
-    }
-    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)
+        // Duplicate shortIds across all entities
+        const allShortIds = [];
+        for (const f of features.features)
+            if (f.shortId)
+                allShortIds.push(f.shortId);
+        for (const ph of phases) {
+            if (ph.shortId)
+                allShortIds.push(ph.shortId);
+            for (const t of ph.tasks)
+                if (t.shortId)
+                    allShortIds.push(t.shortId);
+        }
+        const sidCounts = new Map();
+        for (const id of allShortIds)
+            sidCounts.set(id, (sidCounts.get(id) ?? 0) + 1);
+        const duplicateShortIds = [...sidCounts.entries()].filter(([, c]) => c > 1).map(([id]) => id);
+        return { duplicatePhaseIds, danglingPhaseIds, duplicateShortIds };
+    }
+    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).
-        await this.runAsBatch(async () => {
-            await this.migratePhaseIds();
-            const workspace = await this.loadAll();
-            const { phases, features } = workspace;
-            // 1. Update Phase statuses based on tasks
-            for (const phase of phases) {
-                phase.status = this.derivePhaseStatus(phase);
-            }
-            // 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();
-        });
-    }
-    /** Optimized rollup: syncs only the affected phase and its parent feature.
-     *  Drastically reduces write operations and 'busy' window for task updates. */
+        // 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);
-        phase.status = this.derivePhaseStatus(phase);
-        await this.savePhase(phase);
-        if (phase.featureId) {
-            const featuresDoc = await this.loadFeatures();
-            const 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.updatePhase(phaseId, (p) => ({ ...p, handoff: "", handoffUpdatedAt: nowISO() }));
+            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;
     }
     // ── Savers ───────────────────────────────────────────────────────────
     async updateProject(updater) {
@@ -927,7 +1136,13 @@ export class PlanStore {
         return updated;
     }
     async updateFeatures(updater) {
-        const updated = await atomicUpdateJson(this.featuresPath(), FeaturesDocumentSchema, (current) => this.normalizeFeaturesDocument(updater(current)).doc);
+        const updated = await this.withFeaturesLock(async () => {
+            await this.migrateLegacy();
+            const current = await this.loadFeatures();
+            const upd = this.normalizeFeaturesDocument(updater(current)).doc;
+            await this.saveFeaturesRaw(upd);
+            return upd;
+        });
         await this.maybeAutoSync();
         return updated;
     }
@@ -943,8 +1158,45 @@ export class PlanStore {
         await this.maybeAutoSync();
     }
     async saveFeatures(features) {
+        await this.withFeaturesLock(async () => {
+            await this.migrateLegacy();
+            await this.saveFeaturesRaw(features);
+        });
+        await this.touchManifest();
+        await this.maybeAutoSync();
+    }
+    /** Per-file write of all features + orphan reconcile. No lock (caller holds withFeaturesLock). */
+    async saveFeaturesRaw(features) {
         const parsed = FeaturesDocumentSchema.parse(this.normalizeFeaturesDocument(features).doc);
-        await atomicWriteJson(this.featuresPath(), parsed);
+        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);
+        }
+        // Orphan reconcile: remove feature files no longer in the document.
+        try {
+            const files = await readdir(this.featuresDir());
+            for (const f of files) {
+                if (!f.endsWith(".json"))
+                    continue;
+                const id = f.replace(/\.json$/, "");
+                if (!wantIds.has(id)) {
+                    await unlink(this.featurePath(id)).catch(() => { });
+                }
+            }
+        }
+        catch {
+            // dir absent — nothing to reconcile
+        }
+    }
+    /** Granular single-feature write (per-file lock; parallel-safe across features). */
+    async saveFeature(feature) {
+        await this.withFeaturesLock(async () => {
+            await this.migrateLegacy();
+            await mkdir(this.featuresDir(), { recursive: true });
+            const parsed = FeatureSchema.parse(feature);
+            await atomicWriteJson(this.featurePath(parsed.id), parsed);
+        });
         await this.touchManifest();
         await this.maybeAutoSync();
     }
@@ -964,9 +1216,56 @@ 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. */
+    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). */
+    async setPhaseHandoff(phaseId, text) {
+        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: "" }));
+    }
+    /** 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. */
+    async listHandoffs() {
+        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 p of phases) {
+            if (!p.handoff)
+                continue;
+            const fnum = p.featureId ? featureNumber.get(p.featureId) : undefined;
+            out.push({
+                phaseId: p.id,
+                compositeRef: formatPhaseRef(p.number, fnum),
+                updatedAt: p.handoffUpdatedAt || p.updatedAt,
+                firstLine: handoffFirstLine(p.handoff),
+            });
+        }
+        out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return out;
     }
     async deletePhase(phaseId) {
         try {