@agent-plan/core 0.2.26 → 0.2.28

package/dist/write-coordination.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRY_MS = 20;
+export class PlanWriterBusyError extends Error {
+    details;
+    code = "PLAN_WRITER_BUSY";
+    constructor(details) {
+        const owner = details.owner
+            ? ` Active writer: pid ${details.owner.pid} on ${details.owner.hostname}, acquired ${details.owner.acquiredAt}.`
+            : "";
+        super(`PLAN_WRITER_BUSY: another process is mutating ${details.planRoot}; waited ${details.waitedMs}ms.${owner} Read-only operations remain available; retry the write after the active mutation finishes.`);
+        this.details = details;
+        this.name = "PlanWriterBusyError";
+    }
+}
+const heldRoots = new AsyncLocalStorage();
+function positiveEnvMs(name, fallback) {
+    const raw = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+async function readOwner(lockPath) {
+    try {
+        const parsed = JSON.parse(await readFile(join(lockPath, "owner.json"), "utf8"));
+        if (typeof parsed.token !== "string"
+            || typeof parsed.pid !== "number"
+            || typeof parsed.hostname !== "string"
+            || typeof parsed.cwd !== "string"
+            || typeof parsed.acquiredAt !== "string")
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ownerIsActive(owner, heartbeatStale) {
+    if (owner.hostname !== hostname())
+        return !heartbeatStale;
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function acquirePlanRootLock(planRoot) {
+    const locksRoot = join(planRoot, ".local", "locks");
+    const lockPath = join(locksRoot, "writer.lock");
+    const recoveryPath = join(locksRoot, "writer-recovery.lock");
+    const startedAt = Date.now();
+    const timeoutMs = positiveEnvMs("AGENT_PLAN_WRITE_LOCK_TIMEOUT_MS", DEFAULT_TIMEOUT_MS);
+    const staleMs = positiveEnvMs("AGENT_PLAN_WRITE_LOCK_STALE_MS", DEFAULT_STALE_MS);
+    const retryMs = positiveEnvMs("AGENT_PLAN_WRITE_LOCK_RETRY_MS", DEFAULT_RETRY_MS);
+    const owner = {
+        token: randomUUID(),
+        pid: process.pid,
+        hostname: hostname(),
+        cwd: process.cwd(),
+        acquiredAt: new Date().toISOString(),
+    };
+    for (;;) {
+        try {
+            await mkdir(locksRoot, { recursive: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+            continue;
+        }
+        if (await pathExists(recoveryPath)) {
+            try {
+                const recovery = await stat(recoveryPath);
+                if (Date.now() - recovery.mtimeMs > staleMs) {
+                    await rm(recoveryPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            const waitedMs = Date.now() - startedAt;
+            if (waitedMs >= timeoutMs) {
+                const currentOwner = await readOwner(lockPath);
+                throw new PlanWriterBusyError({
+                    errorCode: "PLAN_WRITER_BUSY",
+                    planRoot,
+                    lockPath,
+                    waitedMs,
+                    ...(currentOwner ? { owner: currentOwner } : {}),
+                });
+            }
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+            continue;
+        }
+        try {
+            await mkdir(lockPath);
+            try {
+                await writeFile(join(lockPath, "owner.json"), JSON.stringify(owner, null, 2), "utf8");
+                // A stale-owner recovery may have started after our initial check. Its
+                // sentinel wins: withdraw this new lock and retry after recovery ends.
+                if (await pathExists(recoveryPath)) {
+                    const persistedOwner = await readOwner(lockPath);
+                    if (persistedOwner?.token === owner.token) {
+                        await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                    }
+                    await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+                    continue;
+                }
+            }
+            catch (error) {
+                const persistedOwner = await readOwner(lockPath);
+                if (!persistedOwner || persistedOwner.token === owner.token) {
+                    await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                }
+                throw error;
+            }
+            const heartbeat = setInterval(() => {
+                const now = new Date();
+                void utimes(lockPath, now, now).catch(() => { });
+            }, Math.max(250, Math.floor(staleMs / 3)));
+            heartbeat.unref();
+            return async () => {
+                clearInterval(heartbeat);
+                const persistedOwner = await readOwner(lockPath);
+                if (persistedOwner?.token === owner.token) {
+                    await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                }
+            };
+        }
+        catch (error) {
+            const fsError = error;
+            if (fsError.code === "ENOENT") {
+                await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+                continue;
+            }
+            if (fsError.code !== "EEXIST")
+                throw error;
+            const currentOwner = await readOwner(lockPath);
+            let stale = false;
+            try {
+                const info = await stat(lockPath);
+                stale = Date.now() - info.mtimeMs > staleMs;
+            }
+            catch {
+                continue;
+            }
+            if (currentOwner ? !ownerIsActive(currentOwner, stale) : stale) {
+                try {
+                    await mkdir(recoveryPath);
+                    try {
+                        const confirmedOwner = await readOwner(lockPath);
+                        let confirmedStale = false;
+                        try {
+                            const info = await stat(lockPath);
+                            confirmedStale = Date.now() - info.mtimeMs > staleMs;
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (confirmedOwner ? !ownerIsActive(confirmedOwner, confirmedStale) : confirmedStale) {
+                            await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                        }
+                    }
+                    finally {
+                        await rm(recoveryPath, { recursive: true, force: true }).catch(() => { });
+                    }
+                }
+                catch (recoveryError) {
+                    if (recoveryError.code !== "EEXIST")
+                        throw recoveryError;
+                }
+                continue;
+            }
+            const waitedMs = Date.now() - startedAt;
+            if (waitedMs >= timeoutMs) {
+                throw new PlanWriterBusyError({
+                    errorCode: "PLAN_WRITER_BUSY",
+                    planRoot,
+                    lockPath,
+                    waitedMs,
+                    ...(currentOwner ? { owner: currentOwner } : {}),
+                });
+            }
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, retryMs));
+        }
+    }
+}
+/**
+ * Serialize one logical planner mutation across processes for a planner root.
+ * Nested writes in the same async transaction are re-entrant. Reads never take
+ * this lock, so secondary processes remain available for inspection.
+ */
+export async function withPlanRootWriteLock(root, fn) {
+    const planRoot = resolve(root);
+    const active = heldRoots.getStore();
+    if (active?.has(planRoot))
+        return fn();
+    const release = await acquirePlanRootLock(planRoot);
+    const next = new Set(active ?? []);
+    next.add(planRoot);
+    try {
+        return await heldRoots.run(next, fn);
+    }
+    finally {
+        await release();
+    }
+}

package/package.json

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

package/planner-skill.md

@@ -30,9 +30,10 @@ Discover before mutating:
 
 1. List features, phases, or tasks using compact list tools.
 2. Follow the lowest visible ready priority unless the automatic recommendation or an approved deviation says otherwise.
-3. Use `task_recommend` / `planner-task-recommend` when choosing the next task.
+3. Use `task_recommend` / `planner-task-recommend` when choosing the next task. Treat its `claims` as bounded evidence: priority is a policy signal, a handoff is actionable only when persisted `resumeReady=true`, and Markdown prose or terminal archives never create an action claim.
 4. Read the exact entity with its full-detail show/get surface when full context is needed.
 5. Never infer an ambiguous bare reference. Ask for the exact composite reference.
+6. Never claim that no task is active from counts, feature summaries, or omitted task detail. Use an explicit `activeTaskState`/`activeTasks` result from `plan_get`, `planner-show`, or the lifecycle recommendation. Only `activeTaskState: none` (verified from all persisted task statuses) proves absence; `conflict` means multiple active tasks must be reconciled.
 
 Feature and phase statuses are derived from their children. Do not write their status directly; update the relevant child tasks. A `DERIVED_STATUS_READ_ONLY` result is a non-success result.
 
@@ -45,8 +46,9 @@ When denied:
 1. Confirm `started` is `false` and read `errorCode` plus `nextActions`.
 2. Perform only the missing or stale reads listed in `nextActions`. Reads may be completed in any order within the current session.
 3. If Project Guidelines are listed, call `project_guidelines_show` or `planner-project-guidelines-show` and retain the content while working.
-4. Read each task on every start or resume. Fresh unchanged feature, phase, and linked-requirement reads may be reused across sibling tasks in the same session.
-5. Retry the lifecycle operation. Only `started: true` proves work is active.
+4. Read each task on every start or resume. Fresh unchanged feature, phase, and linked-requirement reads may be reused across sibling tasks in the same session. When linked requirements are requested, call `requirement_list` or `planner-requirement-list` with the exact `phaseRef` from `nextActions`; a broad unscoped inventory does not attest that every requirement was read. A full feature/phase/task read is complete only when it delivers all canonical Accepted Decision fields (`id`, `title`, `decision`, `rationale`, `implementationNotes`, `acceptedAt`); title-only summaries never satisfy the read gate.
+5. Use the returned priority-ordered phase work map to review sibling task refs, goals, dependencies, statuses, and remaining capability ownership. Before proposing or creating work, reread the canonical phase and the relevant sibling task full view; never duplicate a capability already owned by another task.
+6. Retry the lifecycle operation. Only `started: true` proves work is active.
 
 Do not convert a denial into a planner status change merely to bypass the gate. Common typed denials include `PROJECT_GUIDELINES_READ_REQUIRED`, `CONTEXT_READ_REQUIRED`, `REQUIREMENTS_READ_REQUIRED`, `START_NOT_ALLOWED`, `ACTIVE_TASK_CONFLICT`, `TASK_DONE`, and persistence verification failures.
 
@@ -54,7 +56,9 @@ Do not convert a denial into a planner status change merely to bypass the gate.
 
 `Project Guidelines` is the canonical project section for coding standards, formatting, styling, verification conventions, and other implementation rules.
 
-- Read it on planner load when present and whenever lifecycle `nextActions` says it is missing or stale.
+`Requirements` are separate declarative product outcomes: user, business, or system capabilities that phases deliver. They have no lifecycle status. Never store coding standards, best practices, formatting rules, verification process, or agent behavior in Requirements; store those only in Project Guidelines. Nested Requirement macro-tasks retain their own implementation status.
+
+- Read Project Guidelines on planner load when present and whenever lifecycle `nextActions` says it is missing or stale.
 - Update it only through `project_guidelines_update`, `planner-project-guidelines-update`, or Pi `/planner project guidelines`.
 - Explicit planner load automatically and atomically deduplicates legacy `globalRules`, textual `workflowRules`, and project `decisions` into canonical Project Guidelines and Accepted Decisions before recap/context delivery. Ordinary entity reads remain non-mutating. `project_context_migrate` and `planner-project-context-migrate` remain manual preview/recovery diagnostics; repeated applications are idempotent.
 - The Web UI may display the section for the human supervisor, but guideline-read enforcement applies to agents.
@@ -82,20 +86,30 @@ Every mutation is success-sensitive:
 
 ## Handoff protocol
 
-Handoffs are phase-scoped resume documents, not locks. They must be operationally exhaustive, not merely structurally valid.
+Handoffs are phase-scoped resume capsules, not locks. They transfer only the context a cold agent needs to continue safely. Every canonical terminal phase outcome archives its active handoff automatically; terminal phases cannot receive a new handoff.
 
 Before writing:
 
 1. Resolve one exact phase reference and obtain user confirmation when required.
-2. Run `handoff_prepare` / `planner-handoff-prepare` for that exact phase.
-3. Reconcile every still-relevant detail from an existing handoff; do not append a competing handoff.
-4. Build the versioned `completenessAudit` returned by prepare. Every required category must appear exactly once as `captured` or `not-applicable`, with concrete detail or a substantive reason. Generic values such as `N/A`, `none`, `unknown`, or `see above` are rejected with `HANDOFF_COMPLETENESS_AUDIT_REQUIRED`.
+2. Run `handoff_prepare` / `planner-handoff-prepare` for that exact phase. Review its bounded, priority-ordered `phaseWorkMap`, then reread the canonical phase and every relevant sibling task full view before describing remaining work; preserve existing capability ownership rather than proposing duplicates.
+3. **Before generating prose**, read the returned `requiredHumanInputs` and supply them structurally (including `reason`). The returned `draftTemplate` is guidance, not a form: headings are optional and concise free-form resume prose is accepted. Never write `Created at`, `Updated at`, or `Reason` into Markdown: the planner generates those fields before persistence.
+4. Reconcile every still-relevant detail from an existing handoff; do not append a competing handoff.
+5. Do not build or copy a completeness audit into the Markdown. Legacy `completenessAudit` input is optional; the planner records derived evidence as structured metadata.
+6. Do not build or copy a cold-start inventory or five source reviews into the Markdown. Legacy `coldStartInventory`, `sourceReviews`, and `omissionsFound` inputs are optional; the planner derives omitted evidence from persisted state. Include concrete files/symbols, verification, constraints, blockers, and next steps only when they are needed to resume.
+
+The resume-critical content is: exact focus and resume point; current/partial state; decisions and constraints; relevant files/symbols; verification and pending checks; blockers; and ordered next actions. Omit categories that have no resume impact.
+
+Write the canonical handoff as a compact resume capsule targeting at most 8,000 inline characters (24,000 remains only as an absolute compatibility ceiling). Keep inline only the exact focus, current/partial state, decisions or constraints, relevant verification, blockers, and ordered resume steps. Put extended detail in `.planner/docs/` only when the next agent genuinely needs it; externalization is automatic and does not require a manual inventory.
 
-The mandatory categories are: exact focus and resume point; first resume action; completed work; partial work; remaining work; decisions and rationale; rejected alternatives; files and symbols; branch and worktree; commands and tools; completed verification; pending verification; runtime limitations and workarounds; blockers and risks; user-visible behavior; operator actions; project-specific operating notes; and conversation-only facts.
+Then call `handoff_write` / `planner-handoff-write` once with the preparation token, structured `reason`, compact capsule, optional supporting-document manifest, and reconciled task/phase/feature context. Missing preflight/reason, unresolved placeholders, invalid documents, or failed persistence read-back are typed failures and must never be reported as success.
 
-Keep the canonical handoff within the tool-reported budget (currently 24,000 characters). Essential focus, resume point, first action, risks, and verification status must remain inline. Put extended logs, large mappings, command transcripts, and deep design detail in committed Markdown files under `.planner/docs/`; pass each through `supportingDocuments` with a substantive description of what it contains and why the next agent needs it. Links supplement rather than replace the inline resume contract.
+A successful write persists only a **handoff candidate** and returns `resumeReady: false`. Immediately call `handoff_show` / `planner-handoff-show` with the exact phase reference and read the persisted capsule. If the capsule omits resume-critical context, rewrite it; otherwise call `handoff_verify` / `planner-handoff-verify` with the content hash. Source reviews and omission lists are optional legacy evidence; the planner derives them when omitted. Only a successful verification result with `resumeReady: true` authorizes telling the user that the handoff is resume-ready.
 
-Then call `handoff_write` / `planner-handoff-write` with the preparation token, completeness audit, optional supporting-document manifest, and reconciled task/phase/feature context. Missing categories, oversized bodies, invalid documents, or failed persistence read-back are typed failures and must never be reported as success. Read the persisted handoff back with the exact phase reference and verify its body, content hash, audit metadata, branch, file, command, expected behavior, and next action before stopping. `handoff_list` is a compact paginated summary-only index; use `handoff_show` for one bounded body and its metadata. Clear/archive only after explicit intent or when phase completion makes it obsolete.
+`handoff_list` is a compact paginated index of active handoffs and exposes whether each is resume-ready. Use `handoff_show` for one bounded active body and its metadata; after phase completion/rejection/cancellation, the same exact phase-scoped show call returns the latest terminal archive so its closeout and `.planner/docs/` references remain discoverable. Clear/archive only after explicit intent or when phase completion makes the handoff non-operational.
+
+## Hierarchical description freshness
+
+Task description or descriptionRef changes can make the owning phase and feature prose stale; phase description changes can make the owning feature stale. Use `description_freshness` / `planner-description-freshness` to read the deterministic, non-mutating leaf-to-root reconciliation preview. Read the cited child and parent full views, then explicitly update only parent prose that is actually obsolete. Never silently copy child text into a parent or claim the hierarchy is fresh from a generic entity timestamp alone; the preview uses description-specific revisions and returns exact stale parent refs.
 
 ## Ideas Inbox and promotion
 
@@ -162,6 +176,8 @@ Supported interactive command paths:
 - `/planner handoff write <P00x(F00x)>`
 - `/planner handoff clear <P00x(F00x)>`
 
+`handoff_verify` is an agent tool rather than an interactive command; call it only after `handoff_show` completes the separate persisted read-back.
+
 Pause, switch, deviation, recommendation, requirement, and decision operations are available through the registered Pi tools below rather than every interactive `/planner` path.
 
 ### Dashboard, export, and guard
@@ -178,25 +194,25 @@ Pause, switch, deviation, recommendation, requirement, and decision operations a
 
 The MCP adapter publishes these tools:
 
-- Core: `planner-version`, `planner-init`, `planner-show`, `planner-repair`, `planner-cleanup-orphan-phases`, `planner-export`, `planner-authorize-bypass`, `planner-clear-bypass`, `planner-load`, `planner-disable`, `planner-web`.
+- Core: `planner-version`, `planner-init`, `planner-show`, `planner-description-freshness`, `planner-repair`, `planner-cleanup-orphan-phases`, `planner-export`, `planner-authorize-bypass`, `planner-clear-bypass`, `planner-load`, `planner-disable`, `planner-web`.
 - Ideas: `planner-idea-list`, `planner-idea-show`, `planner-idea-create`, `planner-idea-update`, `planner-idea-delete`, `planner-idea-promotion-begin`, `planner-idea-promotion-finalize`.
-- Project: `planner-project-language`, `planner-project-discuss`, `planner-project-guidelines-show`, `planner-project-guidelines-update`, `planner-project-context-migrate`, `planner-requirement-list`, `planner-requirement-create`, `planner-requirement-update`, `planner-requirement-delete`.
+- 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-delete`, `planner-task-recommend`, `planner-task-deviation`, `planner-task-pause`, `planner-task-switch`, `planner-task-start`, `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-clear`.
+- 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`.
+- Handoffs: `planner-handoff-list`, `planner-handoff-show`, `planner-handoff-prepare`, `planner-handoff-write`, `planner-handoff-verify`, `planner-handoff-clear`.
 
 ## Pi tool inventory
 
 The Pi adapter registers these tools:
 
 - Ideas: `idea_list`, `idea_show`, `idea_create`, `idea_update`, `idea_delete`, `idea_promotion_begin`, `idea_promotion_finalize`.
-- Project and requirements: `project_set_language_preferences`, `project_update`, `project_guidelines_show`, `project_guidelines_update`, `project_context_migrate`, `requirement_list`, `requirement_create`, `requirement_update`, `requirement_delete`.
-- Plan: `plan_init`, `plan_get`, `plan_render`, `plan_repair`, `plan_cleanup_orphan_phases`, `plan_authorize_bypass`, `plan_clear_bypass`.
+- Project and requirements: `project_set_language_preferences`, `project_update`, `project_guidelines_show`, `project_guidelines_update`, `project_context_migrate`, `accepted_decision_create`, `accepted_decision_update`, `accepted_decision_delete`, `requirement_list`, `requirement_create`, `requirement_update`, `requirement_delete`.
+- 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 and decisions: `phase_list`, `phase_get`, `phase_create`, `phase_update`, `phase_delete`, `decision_record`.
-- Tasks: `task_list`, `task_get`, `task_create`, `task_update`, `task_delete`, `task_recommend`, `task_deviation`, `task_pause`, `task_switch`, `task_start`, `task_complete`, `task_checklist_toggle`, `task_checklist_add`, `task_checklist_remove`.
-- Handoffs: `handoff_list`, `handoff_show`, `handoff_prepare`, `handoff_write`, `handoff_clear`.
+- Phases and decisions: `phase_list`, `phase_get`, `phase_create`, `phase_discuss`, `phase_update`, `phase_delete`, `decision_record`.
+- 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`.
+- 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.