@agent-plan/core 0.3.1 → 0.3.2

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export * from "./handoff-reply.js";
 export * from "./mutation-reply.js";
 export * from "./recommend-reply.js";
 export * from "./feature-delete.js";
+export * from "./task-move.js";
 export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
 export * from "./project-context.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,6BAA6B,EAAE,KAAK,8BAA8B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3hB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,6BAA6B,EAAE,KAAK,8BAA8B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3hB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -24,6 +24,7 @@ export * from "./handoff-reply.js";
 export * from "./mutation-reply.js";
 export * from "./recommend-reply.js";
 export * from "./feature-delete.js";
+export * from "./task-move.js";
 export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
 export * from "./project-context.js";

package/dist/on-hold.d.ts

@@ -29,9 +29,13 @@ export interface OnHoldTask {
     /** Why it was put on hold: the motivation of the status change that parked it. */
     reason: string;
     heldSince: string;
-    /** Planner refs named in the reason, each checked against the plan. */
+    /** Planner refs the task is actually waiting on: refs named in the hold
+     *  reason, plus its own dependsOn edges (by composite ref) — deduplicated,
+     *  so a dependency already spelled out in the reason is not double-listed.
+     *  Each is checked against the plan. */
     namedRefs: OnHoldRef[];
-    /** True when the reason names at least one ref and every named ref is finished. */
+    /** True when there is at least one ref to wait on (named in the reason or
+     *  a dependsOn edge) and every one of them is finished. */
     readyToResume: boolean;
 }
 /** Resolve every planner ref named in `text`, by number only (never by title). */

package/dist/on-hold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"on-hold.d.ts","sourceRoot":"","sources":["../src/on-hold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAQ,MAAM,aAAa,CAAC;AAGxD;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB,aAA8C,CAAC;AAG5E,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,mFAAmF;IACnF,aAAa,EAAE,OAAO,CAAC;CACxB;AAgBD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,SAAK,GAAG,SAAS,EAAE,CA8B5G;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,UAAU,EAAE,CAwBzG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAKhE;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,SAAI,GAAG,MAAM,CAiBvE"}
+{"version":3,"file":"on-hold.d.ts","sourceRoot":"","sources":["../src/on-hold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAQ,MAAM,aAAa,CAAC;AAGxD;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB,aAA8C,CAAC;AAG5E,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB;;;4CAGwC;IACxC,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB;+DAC2D;IAC3D,aAAa,EAAE,OAAO,CAAC;CACxB;AAgBD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,SAAK,GAAG,SAAS,EAAE,CA8B5G;AAoBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,UAAU,EAAE,CAiCzG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAKhE;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,SAAI,GAAG,MAAM,CAiBvE"}

package/dist/on-hold.js

@@ -55,6 +55,23 @@ export function refsNamedIn(text, phases, features, selfTaskId = "") {
     }
     return [...seen.values()];
 }
+/** Resolve a task's dependsOn edges to composite refs, checked against the
+ *  plan the same way refsNamedIn checks a ref found in text. A dependsOn id
+ *  always resolves (dependencies are validated at creation — see
+ *  PlanStore.addTaskDependency), but a defensive `found: false` covers a
+ *  dangling edge from an older plan rather than throwing. */
+function dependencyRefsFor(task, phases, features) {
+    return (task.dependsOn ?? []).map((dependencyId) => {
+        for (const phase of phases) {
+            const dependency = phase.tasks.find((candidate) => candidate.id === dependencyId);
+            if (dependency) {
+                const ref = `${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${pad(dependency.number)}`;
+                return { ref, found: true, finished: FINISHED.has(dependency.status) };
+            }
+        }
+        return { ref: dependencyId, found: false, finished: false };
+    });
+}
 /**
  * Every on-hold task, ready-to-resume ones first. Pass `phaseIds` to limit
  * the list to the phases a caller is about to act on.
@@ -69,7 +86,17 @@ export function listOnHoldWork(features, phases, phaseIds) {
             if (!ON_HOLD_STATUSES.has(task.status))
                 continue;
             const { reason, at } = holdEntry(task);
+            // A parked task waits on whatever its reason names AND whatever it
+            // depends on — merged by ref so a dependency already spelled out in
+            // the reason is not counted, or shown, twice.
             const namedRefs = refsNamedIn(reason, phases, features, task.id);
+            const seenRefs = new Set(namedRefs.map((named) => named.ref));
+            for (const dependencyRef of dependencyRefsFor(task, phases, features)) {
+                if (seenRefs.has(dependencyRef.ref))
+                    continue;
+                seenRefs.add(dependencyRef.ref);
+                namedRefs.push(dependencyRef);
+            }
             items.push({
                 taskId: task.id,
                 ref: `${phaseRef}/T${pad(task.number)}`,

package/dist/task-move.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Move one or more tasks to a different phase without recreating them.
+ *
+ * Before this, moving a task meant deleting it and creating a new one in
+ * the target phase — losing its id, statusLog, checklist ticks, accepted
+ * decisions, pause history, and every dependsOn edge pointing at it (see
+ * P108(F005): heca's P082(F003)/T468, T470, T471, T472, T513 are on hold
+ * until work in P094 lands, but belong in P094 as its closing steps, and
+ * recreating five ~4,000-character tasks loses all of that history). This
+ * module is the one place that moves a task: only `phaseId`, `statusLog`
+ * (one appended entry) and `updatedAt` change. Everything else — id,
+ * number, shortId, status, checklist, subtasks, acceptedDecisions,
+ * pauseSnapshot/pauseHistory, notes, description/descriptionRef and
+ * dependsOn — survives untouched because the task object is spread, never
+ * rebuilt field by field. Other tasks' dependsOn keep resolving because
+ * task ids never change; only the composite ref they'd print as changes.
+ *
+ * Reply size is deliberately independent of task size: a moved task's
+ * description can be tens of thousands of characters, and a caller moving
+ * five tasks already has that text — it must not pay to receive it again.
+ * buildTaskMoveReply (below) echoes only ref/id/shortId/title/status per
+ * task, never the task body.
+ *
+ * Both phase files change together or neither: this runs inside
+ * `store.runBatch` and mirrors the rollback-on-error shape the MCP/Pi
+ * `planner-task-switch` / `task_switch` tools already use for a two-phase
+ * write (pause a task in one phase, start one in another) — collect the
+ * exact task objects removed from each source phase, and if any later step
+ * throws, add them straight back rather than reconstructing the phase's
+ * task array (which could clobber a concurrent unrelated write to that
+ * file).
+ */
+import type { PlanStore } from "./plan-store.js";
+import type { MutationReply } from "./mutation-reply.js";
+export type MoveTasksErrorCode = "NO_TASKS_GIVEN" | "TARGET_PHASE_NOT_FOUND" | "TASK_NOT_FOUND" | "SOURCE_EQUALS_TARGET" | "TARGET_PHASE_TERMINAL";
+/** One moved task, named only by ref/identity — never its description,
+ *  checklist, statusLog or any other field a caller already has. */
+export interface TaskMoveSummary {
+    taskId: string;
+    shortId: string;
+    title: string;
+    status: string;
+    oldRef: string;
+    newRef: string;
+}
+export interface MoveTasksResult {
+    targetPhaseRef: string;
+    moves: TaskMoveSummary[];
+    /** Refs of source phases that had a pending handoff at the time of the
+     *  move. A handoff is free prose and may name the moved task by ref; it
+     *  is NOT rewritten here (see buildTaskMoveReply — the reply just flags
+     *  it so a caller knows to check). */
+    sourcePhaseRefsWithHandoff: string[];
+}
+export type MoveTasksOutcome = {
+    ok: true;
+    result: MoveTasksResult;
+} | {
+    ok: false;
+    errorCode: MoveTasksErrorCode;
+    error: string;
+};
+/**
+ * Move `taskIds` (task UUIDs, already resolved by the caller) into
+ * `targetPhaseId` (a phase UUID). Validates target-exists, source != target
+ * per task, and refuses a terminal target phase — a terminal phase is
+ * closed, and reopening it by dropping new work in is not this operation's
+ * job (accepted decision on P108(F005)/T443: no override flag; unlink or
+ * reopen the phase first). An in-progress task MAY move; the reply says so.
+ */
+export declare function moveTasks(store: PlanStore, taskIds: string[], targetPhaseId: string, timestamp?: string): Promise<MoveTasksOutcome>;
+/**
+ * The one reply planner-task-move / task_move return. Deliberately NOT
+ * built with buildMutationReply: that helper echoes one entity's changed
+ * field values, and the only value that changed here — phaseId — is not
+ * something a caller refers to directly. What a caller needs per task is
+ * its old ref, its new ref, and enough identity (id/shortId/title/status)
+ * to confirm it moved — never the description, checklist or statusLog it
+ * already has and did not ask to resend.
+ */
+export declare function buildTaskMoveReply(result: MoveTasksResult, readBackCommand: string): MutationReply;
+//# sourceMappingURL=task-move.d.ts.map

package/dist/task-move.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-move.d.ts","sourceRoot":"","sources":["../src/task-move.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,wBAAwB,GACxB,gBAAgB,GAChB,sBAAsB,GACtB,uBAAuB,CAAC;AAM5B;oEACoE;AACpE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB;;;0CAGsC;IACtC,0BAA0B,EAAE,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACrC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAMhE;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,aAAa,EAAE,MAAM,EACrB,SAAS,SAA2B,GACnC,OAAO,CAAC,gBAAgB,CAAC,CA4H3B;AAOD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,GAAG,aAAa,CAuBlG"}

package/dist/task-move.js

@@ -0,0 +1,169 @@
+import { createStatusLogEntryId, featureNumberOfPhase, formatPhaseRef, formatThreeDigitNumber } from "./naming.js";
+/** Phase statuses a task cannot be moved into. Same terminal set as tasks
+ *  (done/canceled/rejected) — a terminal phase is meant to stay closed. */
+const TERMINAL_PHASE_STATUSES = new Set(["done", "canceled", "rejected"]);
+function taskRef(task, phase, features) {
+    return `${formatPhaseRef(phase.number, featureNumberOfPhase(phase, features))}/T${formatThreeDigitNumber(task.number)}`;
+}
+/**
+ * Move `taskIds` (task UUIDs, already resolved by the caller) into
+ * `targetPhaseId` (a phase UUID). Validates target-exists, source != target
+ * per task, and refuses a terminal target phase — a terminal phase is
+ * closed, and reopening it by dropping new work in is not this operation's
+ * job (accepted decision on P108(F005)/T443: no override flag; unlink or
+ * reopen the phase first). An in-progress task MAY move; the reply says so.
+ */
+export async function moveTasks(store, taskIds, targetPhaseId, timestamp = new Date().toISOString()) {
+    const uniqueTaskIds = [...new Set(taskIds)];
+    if (uniqueTaskIds.length === 0) {
+        return { ok: false, errorCode: "NO_TASKS_GIVEN", error: "No task ids given to move." };
+    }
+    return store.runBatch(async () => {
+        const [phases, featuresDoc] = await Promise.all([store.loadAllPhases(), store.loadFeatures()]);
+        const features = featuresDoc.features;
+        const targetPhase = phases.find((phase) => phase.id === targetPhaseId);
+        if (!targetPhase) {
+            return { ok: false, errorCode: "TARGET_PHASE_NOT_FOUND", error: `Target phase not found: ${targetPhaseId}` };
+        }
+        if (TERMINAL_PHASE_STATUSES.has(targetPhase.status)) {
+            const targetRef = formatPhaseRef(targetPhase.number, featureNumberOfPhase(targetPhase, features));
+            return {
+                ok: false,
+                errorCode: "TARGET_PHASE_TERMINAL",
+                error: `Target phase ${targetRef} is ${targetPhase.status}; cannot move tasks into a terminal phase.`,
+            };
+        }
+        const targetPhaseRef = formatPhaseRef(targetPhase.number, featureNumberOfPhase(targetPhase, features));
+        const allTasks = phases.flatMap((phase) => phase.tasks.map((task) => ({ phase, task })));
+        const located = [];
+        for (const taskId of uniqueTaskIds) {
+            const hit = allTasks.find((entry) => entry.task.id === taskId);
+            if (!hit)
+                return { ok: false, errorCode: "TASK_NOT_FOUND", error: `Task not found: ${taskId}` };
+            if (hit.phase.id === targetPhaseId) {
+                return {
+                    ok: false,
+                    errorCode: "SOURCE_EQUALS_TARGET",
+                    error: `Task ${taskRef(hit.task, hit.phase, features)} is already in ${targetPhaseRef}.`,
+                };
+            }
+            located.push(hit);
+        }
+        // Group by source phase so a multi-source move removes each phase's
+        // tasks in one write, and rollback restores exactly what was removed.
+        const bySourcePhase = new Map();
+        for (const entry of located) {
+            const bucket = bySourcePhase.get(entry.phase.id) ?? { phase: entry.phase, tasks: [] };
+            bucket.tasks.push(entry.task);
+            bySourcePhase.set(entry.phase.id, bucket);
+        }
+        const writtenSourcePhaseIds = [];
+        const summaries = [];
+        const sourcePhaseRefsWithHandoff = [...bySourcePhase.values()]
+            .filter((bucket) => bucket.phase.handoff !== "")
+            .map((bucket) => formatPhaseRef(bucket.phase.number, featureNumberOfPhase(bucket.phase, features)));
+        try {
+            for (const [sourcePhaseId, bucket] of bySourcePhase) {
+                const idsToRemove = new Set(bucket.tasks.map((task) => task.id));
+                await store.updatePhase(sourcePhaseId, (phase) => {
+                    phase.tasks = phase.tasks.filter((task) => !idsToRemove.has(task.id));
+                    return phase;
+                });
+                writtenSourcePhaseIds.push(sourcePhaseId);
+            }
+            const movedTasks = located.map(({ phase: sourcePhase, task }) => {
+                const oldRef = taskRef(task, sourcePhase, features);
+                const newRef = `${targetPhaseRef}/T${formatThreeDigitNumber(task.number)}`;
+                summaries.push({ taskId: task.id, shortId: task.shortId, title: task.title, status: task.status, oldRef, newRef });
+                return {
+                    ...task,
+                    phaseId: targetPhaseId,
+                    statusLog: [...task.statusLog, {
+                            id: createStatusLogEntryId(),
+                            date: timestamp,
+                            fromStatus: task.status,
+                            toStatus: task.status,
+                            title: `moved ${oldRef} → ${newRef}`,
+                            description: `Moved from ${oldRef} to ${newRef}; status unchanged.`,
+                        }],
+                    updatedAt: timestamp,
+                };
+            });
+            await store.updatePhase(targetPhaseId, (phase) => {
+                phase.tasks = [...phase.tasks, ...movedTasks];
+                return phase;
+            });
+        }
+        catch (error) {
+            // Roll back every source phase already written. Add the ORIGINAL task
+            // objects back rather than restoring a whole array snapshot, so a
+            // concurrent unrelated write to the same file (another task added or
+            // edited while this move was in flight) is not clobbered.
+            for (const sourcePhaseId of writtenSourcePhaseIds) {
+                const bucket = bySourcePhase.get(sourcePhaseId);
+                if (!bucket)
+                    continue;
+                await store.updatePhase(sourcePhaseId, (phase) => {
+                    phase.tasks = [...phase.tasks, ...bucket.tasks];
+                    return phase;
+                }).catch(() => { });
+            }
+            throw error;
+        }
+        // Roll up derived status the same way every other task mutation does:
+        // a phase whose task count just changed may have crossed into or out of
+        // a terminal status (handoff archiving, phase/feature statusLog, resume
+        // refresh all live in syncTaskStatusRollup — callers must not reimplement
+        // them). Every touched phase gets it, not just the target.
+        for (const sourcePhaseId of writtenSourcePhaseIds) {
+            await store.syncTaskStatusRollup(sourcePhaseId);
+        }
+        await store.syncTaskStatusRollup(targetPhaseId);
+        await store.writeGenerated();
+        // Prove it happened: re-read from disk rather than trusting the
+        // in-memory write — same discipline as deleteFeatureCascade.
+        const persistedTarget = await store.loadPhase(targetPhaseId);
+        const persistedIds = new Set(persistedTarget.tasks.map((task) => task.id));
+        if (summaries.some((move) => !persistedIds.has(move.taskId))) {
+            return { ok: false, errorCode: "TASK_NOT_FOUND", error: `Task move did not persist to ${targetPhaseRef}.` };
+        }
+        return { ok: true, result: { targetPhaseRef, moves: summaries, sourcePhaseRefsWithHandoff } };
+    });
+}
+/** Cap on how many moved tasks a reply names individually. Moving one task
+ *  or a handful (the documented case) always prints every ref; a very large
+ *  batch degrades to a count rather than growing the reply without bound. */
+const MAX_TASK_MOVE_REPLY_ITEMS = 20;
+/**
+ * The one reply planner-task-move / task_move return. Deliberately NOT
+ * built with buildMutationReply: that helper echoes one entity's changed
+ * field values, and the only value that changed here — phaseId — is not
+ * something a caller refers to directly. What a caller needs per task is
+ * its old ref, its new ref, and enough identity (id/shortId/title/status)
+ * to confirm it moved — never the description, checklist or statusLog it
+ * already has and did not ask to resend.
+ */
+export function buildTaskMoveReply(result, readBackCommand) {
+    const shown = result.moves.slice(0, MAX_TASK_MOVE_REPLY_ITEMS);
+    const omitted = result.moves.length - shown.length;
+    const lines = shown.map((move) => `${move.oldRef} → ${move.newRef} — ${move.title} [${move.status}]${move.shortId ? ` · ${move.shortId}` : ""}`);
+    const handoffNotice = result.sourcePhaseRefsWithHandoff.length > 0
+        ? [`⚠️ Pending handoff on ${result.sourcePhaseRefsWithHandoff.join(", ")} may reference the moved task(s) by ref; it is prose and was not rewritten — check it.`]
+        : [];
+    const text = [
+        `✅ Moved ${result.moves.length} task(s) to ${result.targetPhaseRef}:`,
+        ...lines,
+        ...(omitted > 0 ? [`(+${omitted} more)`] : []),
+        ...handoffNotice,
+        `Read back: ${readBackCommand}`,
+    ].join("\n");
+    const structured = {
+        moved: true,
+        targetPhaseRef: result.targetPhaseRef,
+        moves: shown.map((move) => ({ id: move.taskId, shortId: move.shortId, title: move.title, status: move.status, oldRef: move.oldRef, newRef: move.newRef })),
+        ...(omitted > 0 ? { omittedMoves: omitted } : {}),
+        ...(result.sourcePhaseRefsWithHandoff.length > 0 ? { sourcePhaseRefsWithHandoff: result.sourcePhaseRefsWithHandoff } : {}),
+        readBack: readBackCommand,
+    };
+    return { text, structured };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/core",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": false,
   "description": "Harness-agnostic core for Agent Plan: schemas, persistence, ordering, status rollups, and markdown rendering.",
   "license": "MIT",

package/planner-skill.md

@@ -86,6 +86,7 @@ A decision has exactly one owner: the project when it is project-wide, a feature
 - A temporary task completion can emit `RESUME REQUIRED`. Resume the preserved source or deliberately switch again; do not silently abandon it.
 - Complete a task only after implementation and verification. Supply durable completion evidence, files touched, decisions, remaining or unverified work, and updated code references.
 - Status changes to `blocked`, `canceled`, `rejected`, `deferred`, `waiting`, or back to `planned` require a substantive motivation on agent surfaces.
+- A task that belongs in a different phase is moved with `task_move` / `planner-task-move`, never recreated. Recreating loses the id, statusLog, checklist, accepted decisions, pause history, and every `dependsOn` edge pointing at it; moving keeps all of it and only the composite ref changes. Pass refs only — the move never needs the task's description.
 
 ## Mutation integrity and oversized descriptions
 
@@ -217,7 +218,7 @@ The MCP adapter publishes these tools:
 - Project: `planner-project-language`, `planner-project-discuss`, `planner-project-guidelines-show`, `planner-project-guidelines-update`, `planner-project-context-migrate`, `planner-accepted-decision-create`, `planner-accepted-decision-update`, `planner-accepted-decision-delete`, `planner-requirement-list`, `planner-requirement-create`, `planner-requirement-update`, `planner-requirement-delete`.
 - Features: `planner-feature-list`, `planner-feature-add`, `planner-feature-show`, `planner-feature-discuss`, `planner-feature-update`, `planner-feature-delete`.
 - Phases: `planner-phase-list`, `planner-phase-add`, `planner-phase-show`, `planner-phase-discuss`, `planner-phase-update`, `planner-phase-delete`.
-- Tasks: `planner-task-list`, `planner-task-add`, `planner-task-show`, `planner-task-discuss`, `planner-task-update`, `planner-task-dependency-add`, `planner-task-dependency-delete`, `planner-task-delete`, `planner-task-recommend`, `planner-task-deviation`, `planner-task-pause`, `planner-task-switch`, `planner-task-start`, `planner-task-reopen`, `planner-task-complete`, `planner-task-checklist-toggle`, `planner-task-checklist-add`, `planner-task-checklist-remove`.
+- Tasks: `planner-task-list`, `planner-task-add`, `planner-task-show`, `planner-task-discuss`, `planner-task-update`, `planner-task-move`, `planner-task-dependency-add`, `planner-task-dependency-delete`, `planner-task-delete`, `planner-task-recommend`, `planner-task-deviation`, `planner-task-pause`, `planner-task-switch`, `planner-task-start`, `planner-task-reopen`, `planner-task-complete`, `planner-task-checklist-toggle`, `planner-task-checklist-add`, `planner-task-checklist-remove`.
 - Handoffs: `planner-handoff-list`, `planner-handoff-show`, `planner-handoff-prepare`, `planner-handoff-write`, `planner-handoff-verify`, `planner-handoff-clear`.
 
 ## Pi tool inventory
@@ -229,7 +230,7 @@ The Pi adapter registers these tools:
 - Plan: `plan_init`, `plan_get`, `description_freshness`, `plan_render`, `plan_repair`, `plan_cleanup_orphan_phases`, `plan_authorize_bypass`, `plan_clear_bypass`.
 - Features: `feature_list`, `feature_get`, `feature_create`, `feature_discuss`, `feature_update`, `feature_delete`.
 - Phases: `phase_list`, `phase_get`, `phase_create`, `phase_discuss`, `phase_update`, `phase_delete`, `decision_record` (deprecated, write-disabled compatibility redirect — see Accepted Decision ownership).
-- Tasks: `task_list`, `task_get`, `task_create`, `task_update`, `task_dependency_add`, `task_dependency_delete`, `task_delete`, `task_recommend`, `task_deviation`, `task_pause`, `task_switch`, `task_start`, `task_reopen`, `task_complete`, `task_checklist_toggle`, `task_checklist_add`, `task_checklist_remove`.
+- Tasks: `task_list`, `task_get`, `task_create`, `task_update`, `task_move`, `task_dependency_add`, `task_dependency_delete`, `task_delete`, `task_recommend`, `task_deviation`, `task_pause`, `task_switch`, `task_start`, `task_reopen`, `task_complete`, `task_checklist_toggle`, `task_checklist_add`, `task_checklist_remove`.
 - Handoffs: `handoff_list`, `handoff_show`, `handoff_prepare`, `handoff_write`, `handoff_verify`, `handoff_clear`.
 - Dashboard and lifecycle: `planner-web`, `planner-load`, `planner-stop`.
 - Deprecated compatibility aliases: `plan_get_handoff`, `plan_write_handoff`, `plan_delete_handoff`. Prefer the entity-scoped handoff tools.