@agent-plan/core 0.2.29 → 0.3.1

package/dist/handoff-reply.js

@@ -0,0 +1,279 @@
+import { MAX_HANDOFF_CONTENT_CHARS, handoffContentHash, } from "./handoff-context.js";
+import { boundedContentForTransport } from "./text-bounds.js";
+/**
+ * Render a HandoffContractError (handoff refresh/prepare denial) as a
+ * text/structured pair. Both adapters carried an identical copy; kept here
+ * so the message and the `errorCode`/details shape can never drift between
+ * MCP and Pi. Each adapter still owns its own envelope (`isError` +
+ * `structuredContent` for MCP, `details` for Pi) — see AGENTS.md rule 4.
+ */
+export function handoffContractFailureReply(error, action = "refresh") {
+    const recovery = typeof error.details.recovery === "string" ? ` Recovery: ${error.details.recovery}` : "";
+    return {
+        text: `❌ Handoff ${action} denied [${error.code}]: ${error.message}${recovery}`,
+        structured: { errorCode: error.code, ...error.details },
+    };
+}
+/** Bound raw handoff content to the absolute compatibility ceiling for
+ * transport. Legacy or externally-written content can exceed the ceiling;
+ * everything produced through the normal write path already respects it.
+ * Cuts at a safe boundary (paragraph, then line, then word — see
+ * boundedContentForTransport / truncateAtSafeBoundary in handoff-context.ts)
+ * rather than an arbitrary character offset, so the visible remainder never
+ * ends mid-word. */
+export function boundedHandoffForTransport(content) {
+    const suffix = "\n\n[Legacy handoff truncated for transport safety. Move extended detail to a linked file under .planner/docs/ and refresh the handoff.]";
+    if (content.length <= MAX_HANDOFF_CONTENT_CHARS)
+        return { content, fullLength: content.length, truncated: false };
+    const bounded = boundedContentForTransport(content, Math.max(0, MAX_HANDOFF_CONTENT_CHARS - suffix.length));
+    return { content: `${bounded.content}${suffix}`, fullLength: content.length, truncated: true };
+}
+/**
+ * Render the existing handoff's auto-externalized documents (see
+ * HandoffExternalizedDocumentAudit) for the prepare text channel. Shares one
+ * budget across every document rather than bounding each independently to
+ * MAX_HANDOFF_CONTENT_CHARS, so several documents from successive rewrites
+ * cannot each spend the full ceiling — the reporting phase's own P082 capsule
+ * carried two linked documents at once, and a prior capsule's externalized
+ * document can by itself already be as large as the ceiling (a large draft
+ * is exactly what got externalized). Every document is still named — path,
+ * description, and heading table of contents — even when its content does
+ * not fit, so "elided" never again means "invisible": inlining degrades to
+ * naming, it never degrades to silence.
+ */
+function renderExternalizedHandoffDocuments(documents) {
+    let remaining = MAX_HANDOFF_CONTENT_CHARS;
+    const blocks = [];
+    const structured = [];
+    for (const document of documents) {
+        const headingsNote = document.headings.length > 0 ? ` (sections: ${document.headings.join(", ")})` : "";
+        const header = `- ${document.path} — ${document.description}${headingsNote}`;
+        if (document.missing) {
+            blocks.push(`${header}\n  [Not found on disk; its content is unavailable. Treat any facts it carried as unverified until confirmed another way.]`);
+            structured.push({ path: document.path, headings: document.headings, contentLength: document.contentLength, missing: true, inlined: false, truncated: false });
+            continue;
+        }
+        if (remaining <= 0) {
+            blocks.push(`${header}\n  [Not inlined: the reconciliation budget for externalized detail is exhausted. Read this document directly before drafting.]`);
+            structured.push({ path: document.path, headings: document.headings, contentLength: document.contentLength, missing: false, inlined: false, truncated: false });
+            continue;
+        }
+        const bounded = boundedContentForTransport(document.content ?? "", remaining);
+        remaining -= bounded.content.length;
+        const continuation = bounded.truncated
+            ? "\n\n[Not fully inlined: remaining detail exceeds the reconciliation budget. Read this document directly for the rest.]"
+            : "";
+        blocks.push(`${header}\n${bounded.content}${continuation}`);
+        structured.push({ path: document.path, headings: document.headings, contentLength: document.contentLength, missing: false, inlined: true, truncated: bounded.truncated });
+    }
+    return { text: blocks.join("\n\n"), structured };
+}
+/**
+ * Transport shape of the phase work map. `entries` is the machine-readable
+ * twin of the rendered `content` — the same siblings spelled as JSON — and
+ * no caller reads it off a reply, so only the counts travel. Pass
+ * `includeContent` for the reply that renders the map in no other channel.
+ */
+function workMapForTransport(map, includeContent) {
+    return {
+        ...(includeContent ? { content: map.content } : {}),
+        total: map.total,
+        truncated: map.truncated,
+        maxChars: map.maxChars,
+    };
+}
+/**
+ * Transport shape of the persisted audit. `entries`, `coldStartInventory`
+ * and `readBackSourceReviews` are planner-owned legacy evidence that agents
+ * are told not to reproduce (P100(F021)/T396) and that nothing reads back
+ * off a reply; only the verification facts travel.
+ */
+function handoffAuditForTransport(audit) {
+    if (!audit)
+        return null;
+    return {
+        version: audit.version,
+        contentHash: audit.contentHash,
+        contentLength: audit.contentLength,
+        verifiedAt: audit.verifiedAt,
+        resumeReadyAt: audit.resumeReadyAt,
+        supportingDocuments: audit.supportingDocuments,
+    };
+}
+/**
+ * Build the reply for `planner-handoff-show` / `handoff_show`, covering the
+ * empty, archived, and active branches through one shared shape so no
+ * surface keeps its own construction.
+ *
+ * Placement: the resume capsule body is prose meant to be read, and every
+ * existing consumer reads it from `text` (never from `structured`), so
+ * `text` is its one home; `structured` carries only `fullLength`/
+ * `truncated` flags plus the identifiers, hash, and verification flags a
+ * structuredContent-only host needs to drive the candidate-then-verify
+ * contract (call verify with the right hash) without needing the prose
+ * itself.
+ */
+export function buildHandoffShowReply(input) {
+    if (input.kind === "empty") {
+        return {
+            text: `No handoff set on ${input.phaseRef}.`,
+            structured: {
+                phaseRef: input.phaseRef,
+                phaseId: input.phaseId,
+                content: "",
+                empty: true,
+                resumeReady: false,
+                handoffAudit: handoffAuditForTransport(input.handoffAudit),
+            },
+        };
+    }
+    if (input.kind === "archived") {
+        const bounded = boundedHandoffForTransport(input.content);
+        const supportingDocuments = input.handoffAudit?.supportingDocuments ?? [];
+        const documentLines = supportingDocuments.map((document) => `- ${document.path} — ${document.description}`);
+        return {
+            text: [
+                `Archived terminal-phase handoff for ${input.phaseRef} (${input.archiveReason}; archived ${input.archivedAt})`,
+                ...(documentLines.length ? ["Supporting documents:", ...documentLines] : []),
+                "",
+                bounded.content,
+            ].join("\n"),
+            structured: {
+                phaseRef: input.phaseRef,
+                phaseId: input.phaseId,
+                active: false,
+                archived: true,
+                archiveReason: input.archiveReason,
+                archivedAt: input.archivedAt,
+                archiveFile: input.archiveFile,
+                fullLength: bounded.fullLength,
+                truncated: bounded.truncated,
+                supportingDocuments,
+                empty: false,
+                resumeReady: false,
+                handoffAudit: handoffAuditForTransport(input.handoffAudit),
+            },
+        };
+    }
+    const { phase, phaseRef, phaseWorkMap } = input;
+    const bounded = boundedHandoffForTransport(phase.handoff);
+    const contentHash = handoffContentHash(phase.handoff);
+    const persistenceVerified = Boolean(phase.handoffAudit
+        && phase.handoffAudit.contentHash === contentHash
+        && phase.handoffAudit.contentLength === phase.handoff.length);
+    const resumeReady = persistenceVerified && Boolean(phase.handoffAudit?.resumeReadyAt);
+    const status = resumeReady
+        ? "Resume-ready: persisted compact capsule read-back completed."
+        : "NOT resume-ready: after reading this persisted capsule, call planner-handoff-verify with its contentHash. The planner derives legacy evidence from persisted state; rewrite only if the capsule itself omits resume-critical context.";
+    return {
+        text: `Handoff for ${phaseRef}\n${status}\nContent hash: ${contentHash}\n\n${phaseWorkMap.content}\n\nBefore proposing new work, reread the canonical phase and relevant sibling task full view; do not duplicate an already-owned capability.\n\n${bounded.content}`,
+        structured: {
+            phaseRef,
+            phaseId: phase.id,
+            // The rendered map is already in `text`, so only the counts travel.
+            phaseWorkMap: workMapForTransport(phaseWorkMap, false),
+            fullLength: bounded.fullLength,
+            truncated: bounded.truncated,
+            contentHash,
+            persistenceVerified,
+            resumeReady,
+            verificationRequired: !resumeReady,
+            handoffAudit: handoffAuditForTransport(phase.handoffAudit),
+        },
+    };
+}
+/** Single source of truth for the prepare-reply evidence-contract sentence,
+ * previously hardcoded identically in both adapters. */
+export const HANDOFF_PREPARE_EVIDENCE_CONTRACT = "Planner-owned completeness and cold-start evidence is derived from persisted state; no category inventory is required from the agent.";
+/**
+ * Build the reply for `planner-handoff-prepare` / `handoff_prepare`.
+ *
+ * Placement: `draftTemplate` has no consumer in `text` (only the intro line
+ * pointing at it is read there) and every existing consumer reads it from
+ * `structured`, so `structured` is its one home; `text` gets a pointer
+ * instead of a second copy. The existing active handoff being reconciled is
+ * the opposite: nothing reads it from `structured`, so it stays prose in
+ * `text` only, bounded for transport, with `structured` carrying just its
+ * length/truncated flags. `missingCompletionTasks` duplicates the same
+ * titles already rendered into `text`; `structured` keeps only the task ids
+ * needed to address `taskUpdates`. The existing handoff's auto-externalized
+ * documents follow the same rule as the existing handoff itself: their
+ * bodies are prose for `text` (see renderExternalizedHandoffDocuments),
+ * `structured` keeps only path/headings/size/inlined/truncated per document
+ * (existingHandoffExternalizedDocuments) — see P104(F005)/T415's accepted
+ * decision for why inlining (budget permitting) was chosen over a
+ * separate-field or names-only reply.
+ */
+export function buildHandoffPrepareReply(input) {
+    const { phaseRef, audit } = input;
+    const { completenessCategories: _completenessCategories, coldStartSourceReviews: _coldStartSourceReviews, coldStartInventoryCategories: _coldStartInventoryCategories, handoff, missingCompletionTasks, 
+    // Guidance is instruction the agent reads; the text channel renders it,
+    // so it must not travel again in the structured payload.
+    supportingDocumentsGuidance: _supportingDocumentsGuidance, 
+    // Raw document bodies; never spread as-is into structured (see below —
+    // content stays text-only, structured keeps only the small facts).
+    externalizedHandoffDocuments, ...structuredAudit } = audit;
+    const missingLines = missingCompletionTasks
+        .map((task) => `- T${String(task.number).padStart(3, "0")} — ${task.title}`)
+        .join("\n") || "- None";
+    const existingBounded = boundedHandoffForTransport(handoff);
+    const existingText = existingBounded.content.trim() || "(none)";
+    const externalized = renderExternalizedHandoffDocuments(externalizedHandoffDocuments);
+    const text = [
+        `Handoff preparation for ${phaseRef}`,
+        `Base handoffUpdatedAt: ${audit.handoffUpdatedAt || "(empty)"}`,
+        "Required human inputs before drafting:",
+        ...audit.requiredHumanInputs.map((requiredInput) => `- ${requiredInput.id} — ${requiredInput.description}`),
+        "Planner-generated metadata (do not add these to Markdown): Created at, Updated at, Reason.",
+        "The exact drafting scaffold is provided in the structured result's draftTemplate field; replace every angle-bracket placeholder and retain every heading.",
+        "",
+        "Done tasks missing durable completion/verification evidence:",
+        missingLines,
+        "",
+        "Compact handoff contract: include only the exact focus/resume point, current or partial state, constraints, blockers, decisions, verification, and ordered next actions needed by the next agent.",
+        "No Markdown heading is mandatory: concise free-form resume prose is accepted. Use headings only when they make the capsule clearer.",
+        "Completeness audit and cold-start evidence are planner-owned metadata; do not copy their categories or source reviews into Markdown.",
+        `Inline target: ${audit.targetContentChars} characters; absolute compatibility ceiling: ${audit.maxContentChars}. Extended detail is externalized automatically when needed.`,
+        `Supporting documents: ${audit.supportingDocumentsGuidance}`,
+        "",
+        "Existing active handoff (reconcile all still-relevant content):",
+        existingText,
+        // Content this same active handoff previously moved out automatically.
+        // Reconciling "the existing handoff" means reconciling this too — it is
+        // not optional background reading, it is the part most likely to hold a
+        // fact no task holds (see AGENTS.md rule 4: this belongs here once, not
+        // rediscovered per adapter).
+        ...(externalizedHandoffDocuments.length > 0
+            ? [
+                "",
+                "Externalized detail from the existing handoff (auto-moved out when the capsule exceeded the inline target; reconcile before drafting — this is part of \"the existing handoff\", not optional background):",
+                externalized.text,
+            ]
+            : []),
+        ...(audit.priorSectionHeadings.length > 0
+            ? [
+                "",
+                `Prior sections to account for: ${audit.priorSectionHeadings.join(", ")}. Any of these missing as a "##" heading from the written content will be refused (HANDOFF_SECTION_RECONCILIATION_REQUIRED) unless you also submit sectionDispositions naming what happened to it (dropped, superseded, or folded into another section).`,
+            ]
+            : []),
+    ].join("\n");
+    return {
+        text,
+        structured: {
+            phaseRef,
+            ...structuredAudit,
+            // Prepare renders the map in no text channel, so it keeps `content`
+            // here — but not the JSON twin of the same siblings.
+            phaseWorkMap: workMapForTransport(structuredAudit.phaseWorkMap, true),
+            existingCompletenessAudit: handoffAuditForTransport(structuredAudit.existingCompletenessAudit),
+            existingHandoffLength: existingBounded.fullLength,
+            existingHandoffTruncated: existingBounded.truncated,
+            // Bodies are text-only (see externalized.text above); structured keeps
+            // only the facts a structuredContent-only host needs to know more
+            // exists than it can see: path, headings, size, and whether this call
+            // inlined it.
+            existingHandoffExternalizedDocuments: externalized.structured,
+            evidenceContract: HANDOFF_PREPARE_EVIDENCE_CONTRACT,
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./naming.js";
 export * from "./refs.js";
+export * from "./render-utils.js";
+export * from "./pagination.js";
+export * from "./task-lifecycle.js";
 export * from "./schema.js";
 export * from "./checklist.js";
 export * from "./recap.js";
@@ -7,18 +10,32 @@ export * from "./planner-rules.js";
 export * from "./planner-skill.js";
 export * from "./display-status.js";
 export * from "./description-freshness.js";
+export * from "./text-bounds.js";
 export * from "./task-context.js";
 export * from "./task-selection.js";
 export * from "./task-start-outcome.js";
+export * from "./task-order-context.js";
+export * from "./task-completion-gate.js";
+export * from "./stranded-phase.js";
 export * from "./read-tracking.js";
 export * from "./payload-fallback.js";
 export * from "./handoff-context.js";
+export * from "./handoff-reply.js";
+export * from "./mutation-reply.js";
+export * from "./recommend-reply.js";
+export * from "./feature-delete.js";
+export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
+export * from "./project-context.js";
+export * from "./load-reply.js";
+export * from "./on-hold.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
 export * from "./runtime-diagnostics.js";
 export * from "./write-coordination.js";
-export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, type IdeaCreateInput, type IdeaUpdateInput, type IdeaPromotionTargetInput, type AcceptedDecisionOwner, type AcceptedDecisionCreateInput, type AcceptedDecisionUpdateInput, type PhaseHandoffSummary, type OrphanPhaseSummary } from "./plan-store.js";
+export * from "./guard-decision.js";
+export * from "./guard-state.js";
+export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, nowISO, type IdeaCreateInput, type IdeaUpdateInput, type IdeaPromotionTargetInput, type AcceptedDecisionOwner, type AcceptedDecisionCreateInput, type AcceptedDecisionUpdateInput, type RecordProjectContextReadInput, type RecordProjectContextReadResult, type PhaseHandoffSummary, type OrphanPhaseSummary } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";
 export type { CodebaseProfile, ResumeFocus, ActivityEntry, ActivityLog, AmbientFacts } from "./schema.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,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,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1c,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,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

@@ -1,5 +1,8 @@
 export * from "./naming.js";
 export * from "./refs.js";
+export * from "./render-utils.js";
+export * from "./pagination.js";
+export * from "./task-lifecycle.js";
 export * from "./schema.js";
 export * from "./checklist.js";
 export * from "./recap.js";
@@ -7,17 +10,31 @@ export * from "./planner-rules.js";
 export * from "./planner-skill.js";
 export * from "./display-status.js";
 export * from "./description-freshness.js";
+export * from "./text-bounds.js";
 export * from "./task-context.js";
 export * from "./task-selection.js";
 export * from "./task-start-outcome.js";
+export * from "./task-order-context.js";
+export * from "./task-completion-gate.js";
+export * from "./stranded-phase.js";
 export * from "./read-tracking.js";
 export * from "./payload-fallback.js";
 export * from "./handoff-context.js";
+export * from "./handoff-reply.js";
+export * from "./mutation-reply.js";
+export * from "./recommend-reply.js";
+export * from "./feature-delete.js";
+export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
+export * from "./project-context.js";
+export * from "./load-reply.js";
+export * from "./on-hold.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
 export * from "./runtime-diagnostics.js";
 export * from "./write-coordination.js";
-export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock } from "./plan-store.js";
+export * from "./guard-decision.js";
+export * from "./guard-state.js";
+export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, nowISO } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";

package/dist/load-reply.d.ts

@@ -0,0 +1,63 @@
+import type { ProjectContextReply } from "./project-context.js";
+import type { PlanWorkspace } from "./schema.js";
+/**
+ * Reply shaping for an explicit planner load, shared by every adapter
+ * (MCP planner-load, Pi's planner-load tool and /planner load command).
+ *
+ * Every piece is sent once, in one text the agent reads top to bottom: the
+ * recap to show the user, then the agent-only context. `structured` carries
+ * only status fields; hosts that show the agent only structured content
+ * still get the text because the MCP server folds it in.
+ */
+/** How the planner operating guide reaches the agent on this load. */
+export type PlannerGuideDelivery = 
+/** The guide body is included (a host with no other way to deliver it). */
+{
+    mode: "include";
+    content: string;
+    customized: boolean;
+    message: string;
+}
+/** The host already delivers the guide (e.g. Claude Code's /planner
+ * command); send only where it lives, never the body again. */
+ | {
+    mode: "pointer";
+    path: string;
+    customized: boolean;
+    message: string;
+};
+export interface PlannerLoadReplyInput {
+    recap: string;
+    projectContext: ProjectContextReply;
+    /** Accepted Decisions below project scope (feature/phase/task). Project
+     * decisions are already inside the project context. */
+    scopedDecisions?: {
+        content: string;
+        total: number;
+        truncated: boolean;
+    };
+    plannerGuide: PlannerGuideDelivery;
+}
+export interface PlannerLoadReply {
+    text: string;
+    structured: Record<string, unknown>;
+}
+export declare const PLANNER_LOAD_RECAP_HEADING = "## Recap \u2014 show this to the user verbatim";
+export declare const PLANNER_LOAD_AGENT_HEADING = "## Agent-only context \u2014 read and keep it; never quote it in the recap";
+/** Split a load reply's text back into the recap the user sees and the
+ * agent-only context. Any client (or test) that must show only the recap
+ * uses this instead of guessing at the layout. */
+export declare function splitPlannerLoadText(text: string): {
+    recap: string;
+    agentContext: string;
+};
+export declare function buildPlannerLoadReply(input: PlannerLoadReplyInput): PlannerLoadReply;
+/** Accepted Decisions owned by features, phases and tasks, bounded for a
+ * load reply. Project decisions are left out: the project context already
+ * carries them. */
+export declare function buildScopedDecisionContext(plan: PlanWorkspace): {
+    content: string;
+    total: number;
+    truncated: boolean;
+};
+//# sourceMappingURL=load-reply.d.ts.map

package/dist/load-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-reply.d.ts","sourceRoot":"","sources":["../src/load-reply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,MAAM,oBAAoB;AAC9B,2EAA2E;AACzE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC5E;+DAC+D;GAC7D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,mBAAmB,CAAC;IACpC;2DACuD;IACvD,eAAe,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE,YAAY,EAAE,oBAAoB,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,eAAO,MAAM,0BAA0B,mDAA8C,CAAC;AACtF,eAAO,MAAM,0BAA0B,+EAA0E,CAAC;AAElH;;kDAEkD;AAClD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAK1F;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,CAmCpF;AAED;;mBAEmB;AACnB,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAYtH"}

package/dist/load-reply.js

@@ -0,0 +1,64 @@
+import { featureNumberOfPhase, formatFeatureRef, formatPhaseRef } from "./naming.js";
+import { buildBoundedAcceptedDecisionContext } from "./task-context.js";
+export const PLANNER_LOAD_RECAP_HEADING = "## Recap — show this to the user verbatim";
+export const PLANNER_LOAD_AGENT_HEADING = "## Agent-only context — read and keep it; never quote it in the recap";
+/** Split a load reply's text back into the recap the user sees and the
+ * agent-only context. Any client (or test) that must show only the recap
+ * uses this instead of guessing at the layout. */
+export function splitPlannerLoadText(text) {
+    const agentAt = text.indexOf(PLANNER_LOAD_AGENT_HEADING);
+    const recapStart = text.startsWith(PLANNER_LOAD_RECAP_HEADING) ? PLANNER_LOAD_RECAP_HEADING.length : 0;
+    if (agentAt < 0)
+        return { recap: text.slice(recapStart).trim(), agentContext: "" };
+    return { recap: text.slice(recapStart, agentAt).trim(), agentContext: text.slice(agentAt + PLANNER_LOAD_AGENT_HEADING.length).trim() };
+}
+export function buildPlannerLoadReply(input) {
+    const guide = input.plannerGuide;
+    const guideBlock = guide.mode === "include"
+        ? ["### Agent Plan operating guide", guide.customized ? guide.message : "", guide.content].filter(Boolean).join("\n\n")
+        : [
+            "### Agent Plan operating guide",
+            `Follow the Agent Plan operating guide. If it is not already in this conversation (the /planner command includes it), read ${guide.path}.`,
+            guide.customized ? guide.message : "",
+        ].filter(Boolean).join("\n");
+    const blocks = [
+        PLANNER_LOAD_RECAP_HEADING,
+        input.recap,
+        PLANNER_LOAD_AGENT_HEADING,
+        "### Project context",
+        input.projectContext.text,
+    ];
+    if (input.scopedDecisions && input.scopedDecisions.total > 0) {
+        blocks.push("### Accepted decisions for features, phases and tasks", input.scopedDecisions.content);
+    }
+    blocks.push(guideBlock);
+    return {
+        text: blocks.join("\n\n"),
+        structured: {
+            loaded: true,
+            projectContext: input.projectContext.structured,
+            plannerGuide: guide.mode === "include"
+                ? { mode: "include", customized: guide.customized }
+                : { mode: "pointer", path: guide.path, customized: guide.customized },
+            scopedDecisions: input.scopedDecisions
+                ? { total: input.scopedDecisions.total, truncated: input.scopedDecisions.truncated }
+                : { total: 0, truncated: false },
+        },
+    };
+}
+/** Accepted Decisions owned by features, phases and tasks, bounded for a
+ * load reply. Project decisions are left out: the project context already
+ * carries them. */
+export function buildScopedDecisionContext(plan) {
+    const features = plan.features.features;
+    const phaseRef = (phase) => formatPhaseRef(phase.number, featureNumberOfPhase(phase, features));
+    const { content, total, truncated } = buildBoundedAcceptedDecisionContext([
+        ...features.map((feature) => ({ scope: `feature ${formatFeatureRef(feature.number)}`, decisions: feature.acceptedDecisions })),
+        ...plan.phases.map((phase) => ({ scope: `phase ${phaseRef(phase)}`, decisions: phase.acceptedDecisions })),
+        ...plan.phases.flatMap((phase) => phase.tasks.map((task) => ({
+            scope: `task ${phaseRef(phase)}/T${String(task.number).padStart(3, "0")}`,
+            decisions: task.acceptedDecisions,
+        }))),
+    ]);
+    return { content, total, truncated };
+}

package/dist/mutation-reply.d.ts

@@ -0,0 +1,105 @@
+import type { PlannerPayloadEntity, PlannerPayloadOperation } from "./payload-fallback.js";
+/**
+ * Per-field echo budget. A changed field is worth showing back so the caller
+ * can confirm what landed without a second call; a changed field the size of
+ * a task description is not. 2,000 characters is about three screens — long
+ * enough to read a title, a status, a checklist or a short note whole, short
+ * enough that echoing a full description is impossible.
+ */
+export declare const MUTATION_ECHO_MAX_FIELD_CHARS = 2000;
+/**
+ * Ceiling for the whole structured payload of a mutation reply. Chosen to
+ * match MAX_PHASE_WORK_MAP_CHARS and MAX_ACCEPTED_DECISION_CONTEXT_CHARS so
+ * an agent has one number in mind for planner payloads rather than four.
+ * When the assembled payload exceeds it, echoed values are dropped to names
+ * (see `boundMutationEcho`) — the caller still learns exactly which fields
+ * changed, which is the part it cannot get anywhere else.
+ */
+export declare const MUTATION_REPLY_MAX_CHARS = 8000;
+/**
+ * The long-text size a planner tool accepts in one call, stated up front so
+ * a caller does not discover it by being rejected. This is not a limit the
+ * planner imposes for its own sake: a long `description` can be dropped by
+ * the transport before it ever reaches the planner, which arrives here as
+ * "no mutable fields received" and is why DESCRIPTION_MARKDOWN_FALLBACK_REQUIRED
+ * exists. Measured: ~13,500 characters accepted, ~17,000 rejected. 12,000 is
+ * under the observed floor with room to spare.
+ *
+ * Above this, write the prose to a committed file under `.planner/docs/` and
+ * pass `descriptionRef` — see suggestedDescriptionRefPath in payload-fallback.ts.
+ */
+export declare const PLANNER_LONG_TEXT_FIELD_MAX_CHARS = 12000;
+/**
+ * One sentence for a tool description, so the limit is discoverable at the
+ * point of the call instead of after it fails. Every tool taking a long text
+ * field appends this to its own description.
+ */
+export declare function longTextFieldLimitNotice(field?: string): string;
+/** A tool reply as one result: the human-readable body and the structured
+ * payload, with no field present in both. */
+export interface MutationReply {
+    text: string;
+    structured: Record<string, unknown>;
+}
+/** Who was mutated, in the terms a caller refers to it by. The canonical
+ * `ref` is what travels — never the raw text the caller happened to type,
+ * which may be a short id, a title or a UUID. */
+export interface MutationIdentity {
+    entity: PlannerPayloadEntity;
+    ref: string;
+    id?: string;
+    shortId?: string;
+    title?: string;
+    status?: string;
+}
+export interface MutationReplyInput {
+    identity: MutationIdentity;
+    operation: PlannerPayloadOperation;
+    /** Fields the caller actually changed, in the order they were received. */
+    updatedFields: readonly string[];
+    /** The persisted values of those fields, to be echoed back within budget.
+     * Keys outside `updatedFields` are ignored: a mutation reply never carries
+     * a field the mutation did not touch. */
+    changedValues?: Record<string, unknown>;
+    /** Diagnostics that are not the entity — description freshness, stale
+     * parents, lost checklist ticks, resume-required notices. These are the
+     * reason to read a mutation result at all, so they are never trimmed. */
+    extras?: Record<string, unknown>;
+    /** Extra lines for the human channel, such as a lost-tick warning. */
+    notices?: readonly string[];
+    /** The command that returns the full entity, for a caller that wants what
+     * this reply deliberately leaves out. */
+    readBackCommand?: string;
+}
+/**
+ * Build the one reply every mutation tool returns.
+ *
+ * What a caller gets: that the write happened, which fields it touched, the
+ * canonical ref and identity of what it touched, the changed values within
+ * budget, and every diagnostic. What it does not get: the rest of the
+ * entity, which it can read with the command named in `readBack`.
+ *
+ * `updated` (or `discussed`), `updatedFields` and any `errorCode` keep their
+ * exact prior shape — mutation-integrity checking across the whole project
+ * reads those three and nothing else.
+ */
+export declare function buildMutationReply(input: MutationReplyInput): MutationReply;
+export interface DerivedStatusReadOnlyInput {
+    entity: "feature" | "phase";
+    ref: string;
+    attemptedStatus: string;
+    effectiveStatus: string;
+    /** Full "retry without the status field" instruction. Each adapter names
+     *  its own update tool (`planner-feature-update` vs `feature_update`), so
+     *  this one line stays adapter-supplied rather than templated here —
+     *  moving it into the core would restate a tool name the core doesn't own. */
+    retryAction: string;
+}
+/**
+ * A feature/phase `status` field cannot be set directly — it is derived
+ * from child phases/tasks. Both adapters carried an identical copy of this
+ * refusal for feature_update/phase_update; only the retry line's tool name
+ * differs, which is why it is the one caller-supplied piece.
+ */
+export declare function derivedStatusReadOnlyReply(input: DerivedStatusReadOnlyInput): MutationReply;
+//# sourceMappingURL=mutation-reply.d.ts.map

package/dist/mutation-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-reply.d.ts","sourceRoot":"","sources":["../src/mutation-reply.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,SAAgB,GAAG,MAAM,CAEtE;AAED;6CAC6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;iDAEiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,uBAAuB,CAAC;IACnC,2EAA2E;IAC3E,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;6CAEyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;6EAEyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sEAAsE;IACtE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;6CACyC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CA6C3E;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB;;;kFAG8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,aAAa,CA4B3F"}