@agent-plan/core 0.3.0 → 0.3.2

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/dist/task-selection.d.ts

@@ -1,6 +1,7 @@
 import type { Feature, Phase, Task, WorkDeviation } from "./schema.js";
+import { type OnHoldTask } from "./on-hold.js";
 export type RecommendationClaimKind = "recommendation" | "advisory" | "conflict" | "insufficient";
-export type RecommendationClaimSource = "priority" | "active-task" | "resume-deviation" | "dependency-ready" | "handoff" | "archived-handoff";
+export type RecommendationClaimSource = "priority" | "active-task" | "resume-deviation" | "dependency-ready" | "handoff" | "archived-handoff" | "on-hold";
 export interface RecommendationClaim {
     kind: RecommendationClaimKind;
     source: RecommendationClaimSource;
@@ -46,6 +47,8 @@ export interface NextWorkRecommendation {
     nextPhase: WorkSummary | null;
     nextTask: WorkSummary | null;
     claims: RecommendationClaim[];
+    /** On-hold tasks in started phases, ready-to-resume first (see on-hold.ts). */
+    onHold: OnHoldTask[];
 }
 export interface TaskRecommendation {
     kind: TaskRecommendationKind;

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

@@ -1 +1 @@
-{"version":3,"file":"task-selection.d.ts","sourceRoot":"","sources":["../src/task-selection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task-selection.d.ts","sourceRoot":"","sources":["../src/task-selection.ts"],"names":[],"mappings":"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"}

package/dist/task-selection.js

@@ -1,3 +1,4 @@
+import { listOnHoldWork, startedOpenPhaseIds } from "./on-hold.js";
 const hardUnavailable = new Set(["blocked", "deferred", "canceled", "rejected"]);
 const terminal = new Set(["done", "canceled", "rejected"]);
 const priority = (entity) => entity.priority != null ? entity.priority : Number.MAX_SAFE_INTEGER;
@@ -15,8 +16,19 @@ const selectionClaimKind = (selectionKind) => {
         return "insufficient";
     return "advisory";
 };
-const buildRecommendationClaims = (selection, evidence = {}, dependencyReadyCandidates = []) => {
+const buildRecommendationClaims = (selection, evidence = {}, dependencyReadyCandidates = [], onHold = []) => {
     const claims = [];
+    // Parked work whose every named blocker is finished competes with fresh
+    // work; listed before it so the claim limit never drops it.
+    const readyOnHold = onHold.filter((item) => item.readyToResume).map((item) => ({
+        kind: "advisory",
+        source: "on-hold",
+        ref: item.ref,
+        title: item.title,
+        reason: `On hold (${item.status}); everything its reason names is finished (${item.namedRefs.map((named) => named.ref).join(", ")}), so it may be ready. Re-check it and resume it if nothing else holds it.`,
+        taskId: item.taskId,
+        phaseId: item.phaseId,
+    }));
     if (selection.candidate) {
         claims.push({
             kind: selectionClaimKind(selection.kind),
@@ -29,6 +41,7 @@ const buildRecommendationClaims = (selection, evidence = {}, dependencyReadyCand
             ...(selection.candidate.feature?.id ? { featureId: selection.candidate.feature.id } : {}),
         });
     }
+    claims.push(...readyOnHold);
     for (const candidate of dependencyReadyCandidates) {
         claims.push({
             kind: "advisory",
@@ -251,6 +264,12 @@ export function recommendNextWork(features, phases, deviations = [], currentPhas
         && !(feature && hardUnavailable.has(feature.status))
         && task.dependsOn.every((id) => taskById.get(id)?.status === "done"))
         .sort((left, right) => compare(left.feature ?? { priority: 0, number: 0 }, right.feature ?? { priority: 0, number: 0 }) || compare(left.phase, right.phase) || compare(left.task, right.task));
+    // On-hold work in phases already under way, plus the phase the
+    // recommendation is about to send the agent into.
+    const onHoldPhaseIds = startedOpenPhaseIds(phases);
+    if (selection.candidate)
+        onHoldPhaseIds.add(selection.candidate.phase.id);
+    const onHold = listOnHoldWork(features, phases, onHoldPhaseIds);
     const activeTask = selection.kind === "active" && selection.candidate
         ? summarizeTask(selection.candidate.task)
         : null;
@@ -260,7 +279,8 @@ export function recommendNextWork(features, phases, deviations = [], currentPhas
         nextFeature: selection.candidate?.feature ? summarizeFeature(selection.candidate.feature) : null,
         nextPhase: selection.candidate ? summarizePhase(selection.candidate.phase) : null,
         nextTask: selection.candidate ? summarizeTask(selection.candidate.task) : null,
-        claims: buildRecommendationClaims(selection, evidence, dependencyReadyCandidates),
+        claims: buildRecommendationClaims(selection, evidence, dependencyReadyCandidates, onHold),
+        onHold,
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/core",
-  "version": "0.3.0",
+  "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.