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

package/dist/plan-store.js

@@ -1,4 +1,4 @@
-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, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, } from "./schema.js";
 import { createFeatureId, createPhaseId, createRequirementId, createShortId, createTaskId, formatPhaseRef, isLegacyPhaseId } from "./naming.js";
@@ -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");
@@ -240,24 +334,13 @@ export class PlanStore {
         // save. Kept so existing save* call sites compile unchanged.
     }
     normalizeTasks(tasks) {
-        let changed = false;
-        const normalized = tasks.map((task, index) => {
-            const nextNumber = index + 1;
-            if (task.number !== nextNumber)
-                changed = true;
-            return { ...task, number: nextNumber };
-        });
-        return { tasks: normalized, changed };
+        // Numbers are a STABLE global sequence (assigned once at create from project.nextTaskNumber).
+        // Do NOT renumber here — renumbering would break references after deletions.
+        return { tasks, changed: false };
     }
     normalizeFeaturesDocument(doc) {
-        let changed = false;
-        const normalized = doc.features.map((feature, index) => {
-            const nextNumber = index + 1;
-            if (feature.number !== nextNumber)
-                changed = true;
-            return { ...feature, number: nextNumber };
-        });
-        return { doc: { features: normalized }, changed };
+        // Numbers are a STABLE global sequence (assigned once at create from project.nextFeatureNumber).
+        return { doc, changed: false };
     }
     normalizePhaseDocument(phase) {
         const { tasks, changed } = this.normalizeTasks(phase.tasks);
@@ -287,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));
@@ -299,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;
@@ -314,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;
@@ -338,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);
@@ -350,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() {
@@ -411,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()) {
@@ -452,6 +564,9 @@ export class PlanStore {
                 beforeTaskStart: [],
                 afterPhaseComplete: [],
             },
+            nextFeatureNumber: 1,
+            nextPhaseNumber: 1,
+            nextTaskNumber: 1,
         });
         await this.saveRequirements({ requirements: [] });
         await this.saveFeatures({ features: [] });
@@ -460,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: "",
@@ -482,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");
     }
@@ -507,6 +631,24 @@ export class PlanStore {
     async loadProject() {
         return readJson(this.projectPath(), ProjectSchema);
     }
+    /**
+     * Allocate the next global sequence number for a feature/phase/task.
+     * Reads the monotonic counter from project.json, increments it, persists,
+     * and returns the allocated number. MUST be called within withFeatureLock
+     * (adapters create entities inside a lock) so the counter is race-free.
+     * The counter never reuses a number — deletions leave gaps (by design:
+     * stable references survive deletion).
+     */
+    async allocFeatureNumber() { return this.allocSeqNumber("nextFeatureNumber"); }
+    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 loadPhase(phaseId) {
         const raw = await readJson(this.phasePath(phaseId), PhaseSchema);
         const normalized = this.normalizePhaseDocument(raw).phase;
@@ -582,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();
     }
@@ -598,6 +751,7 @@ export class PlanStore {
             currentPhaseId: "",
             inProgressTaskIds: [],
             nextSteps: [],
+            nextStepsUpdatedAt: "",
             blockers: [],
             notes: "",
             lastSessionSummary: "",
@@ -636,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}`;
@@ -698,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 ?? "",
@@ -931,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) => {
@@ -1017,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. */
@@ -1121,7 +1238,7 @@ export class PlanStore {
         const phase = await this.loadPhase(phaseId);
         let cleared = null;
         if (phase.status === "done" && phase.handoff !== "") {
-            await this.updatePhase(phaseId, (p) => ({ ...p, handoff: "", handoffUpdatedAt: nowISO() }));
+            await this.clearPhaseHandoff(phaseId, "phase-done");
             const features = await this.loadFeatures();
             const feature = features.features.find((f) => f.id === phase.featureId);
             cleared = formatPhaseRef(phase.number, feature?.number);
@@ -1239,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. */
@@ -1259,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));

package/dist/recap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,GAAE,YAAiB,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+GhH"}
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,GAAE,YAAiB,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HhH"}

package/dist/recap.js

@@ -49,7 +49,6 @@ export async function buildRecap(st, web = {}, opts = {}) {
     const featureAddCmd = cmd("/planner feature add", "planner-feature-add");
     const phaseAddCmd = cmd("/planner phase add", "planner-phase-add");
     const handoffShowCmd = cmd("/planner handoff show", "planner-handoff-show");
-    const handoffClearCmd = cmd("/planner handoff clear", "planner-handoff-clear");
     const lines = [];
     lines.push(italian ? "## Ripresa planner" : "## Planner recap");
     const name = plan.project.name || "(unnamed project)";
@@ -71,18 +70,33 @@ export async function buildRecap(st, web = {}, opts = {}) {
     else {
         lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "nessun task attivo — rivedi il piano e scegli il prossimo task concreto" : "no active task — review the plan and pick the next concrete task"}`);
     }
-    // Next step: only surface resume.nextSteps when the plan is NOT complete —
-    // otherwise stale init-time steps (e.g. "bootstrap discovery") leak through
-    // and contradict an all-done plan.
-    if (!planComplete && resume?.nextSteps?.length) {
+    // Next step: the phase handoff (phase.handoff) is the authoritative,
+    // actively-managed resume context. When a handoff is pending, point to it
+    // instead of surfacing potentially-stale resume.json nextSteps. When no
+    // handoff exists, fall back to resume.nextSteps but mark them as possibly
+    // stale (free-text that refreshResume never touches, so they can drift).
+    if (handoffs.length > 0) {
+        lines.push(italian
+            ? `Prossimo step: leggi l'handoff di fase pendente sotto (fonte autorevole, gestita attivamente). I nextSteps legacy di resume.json sono soppressi perché possono essere stale.`
+            : `Next step: read the pending phase handoff below (authoritative, actively maintained). Legacy resume.json nextSteps are suppressed because they may be stale.`);
+    }
+    else if (!planComplete && resume?.nextSteps?.length) {
         lines.push(`${italian ? "Prossimo step" : "Next step"}: ${resume.nextSteps[0]}`);
+        const staleNote = resume.nextStepsUpdatedAt
+            ? (italian
+                ? `⚠️ nextSteps free-text da resume.json, ultimo aggiornamento ${resume.nextStepsUpdatedAt} — può essere stale; verifica contro lo stato attuale prima di agire.`
+                : `⚠️ nextSteps are free-text from resume.json, last updated ${resume.nextStepsUpdatedAt} — may be stale; verify against current state before acting.`)
+            : (italian
+                ? `⚠️ nextSteps free-text da resume.json — può essere stale; verifica contro lo stato attuale prima di agire.`
+                : `⚠️ nextSteps are free-text from resume.json — may be stale; verify against current state before acting.`);
+        lines.push(staleNote);
     }
     if (handoffs.length > 0) {
         lines.push("", italian ? `## Handoff di fase pendenti (${handoffs.length})` : `## Pending phase handoffs (${handoffs.length})`);
         handoffs.forEach((h, i) => lines.push(`[${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`));
         lines.push("", italian
-            ? `→ Leggi quello pertinente con ${handoffShowCmd} <ref> (valida contro lo stato attuale), poi ${handoffClearCmd} <ref> una volta consumato.`
-            : `→ Read the relevant one with ${handoffShowCmd} <ref> (validate against current state), then call ${handoffClearCmd} <ref> once consumed (delete-on-resume).`);
+            ? `→ Leggi quello pertinente con ${handoffShowCmd} <ref> (valida contro lo stato attuale). L'handoff è MANTENUTO finché un task della fase non parte (auto-archiviato) o la fase non si conclude — non serve cancellarlo a mano.`
+            : `→ Read the relevant one with ${handoffShowCmd} <ref> (validate against current state). It is KEPT until a task in that phase starts (then auto-archived) or the phase completes — no need to clear it manually.`);
     }
     else if (planComplete) {
         lines.push("", italian

package/dist/refs.d.ts

@@ -21,4 +21,27 @@ import type { Phase, Feature } from "./schema.js";
  * @param ref     the human-facing ref (P00x / P00x(F00x) / UUID / title)
  */
 export declare function findPhaseByRef(phases: Phase[], features: Feature[], ref: string): Phase | undefined;
+/**
+ * Resolve a task reference to { phase, task }. Harness-agnostic, shared by all
+ * adapters so resolution semantics are identical everywhere.
+ *
+ * Supported task refs (case-insensitive):
+ *   - UUID:     "bd6ed366-..."            -> task.id
+ *   - Short:    "T003" | "t3"             -> task.number (GLOBALLY unique under the
+ *                                           new global-sequence numbering; bare T00x
+ *                                           is unambiguous across all phases)
+ *   - Compos:   "F001/P002/T003"          -> feature/phase/task numbers with parent
+ *                "P002(F001)/T003"          validation (feature + phase must match)
+ *                "P002/T003"
+ *   - ShortId:  "UUXD1"                   -> task.shortId (5-char, globally unique)
+ *   - Title:    exact match, then includes (backward-compat fallback)
+ *
+ * Returns `undefined` when not found, or when a composite parent (phase/feature)
+ * does not match the resolved task's parent.
+ */
+import type { Task } from "./schema.js";
+export declare function findTaskByRef(phases: Phase[], features: Feature[], ref: string): {
+    phase: Phase;
+    task: Task;
+} | undefined;
 //# sourceMappingURL=refs.d.ts.map

package/dist/refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAgCnB"}
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAgCnB;AACD;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAexC,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CAiD1C"}