@agent-plan/core 0.2.28 → 0.3.0

package/dist/handoff-context.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { buildPhaseWorkMap } from "./task-context.js";
+import { truncateAtSafeBoundary } from "./text-bounds.js";
 export const COMPLETION_SUMMARY_HEADING = "**Completion summary:**";
 export const HANDOFF_COMPLETENESS_AUDIT_VERSION = 1;
 export const HANDOFF_COLD_START_INVENTORY_VERSION = 1;
@@ -68,6 +69,121 @@ export class HandoffContractError extends Error {
         this.details = details;
     }
 }
+/** Single source of truth for the supportingDocuments recovery statement.
+ * Rendered in prepare output (before drafting) and attached to every
+ * agent-supplied-manifest failure of HANDOFF_SUPPORTING_DOCUMENT_INVALID
+ * (as details.recovery) so both adapters can render it without duplicating
+ * the wording. */
+export const HANDOFF_SUPPORTING_DOCUMENTS_GUIDANCE = "supportingDocuments is optional and usually unnecessary: content above the target length is externalized automatically into .planner/docs/. Drop the field and retry unless you are linking a document you created yourself.";
+/** Build a HANDOFF_SUPPORTING_DOCUMENT_INVALID error for a defect in an
+ * agent-supplied manifest entry, always carrying the droppable-field
+ * recovery statement. Do not use this for planner-owned failures (e.g. the
+ * auto-externalized document's own path) — those are not something dropping
+ * the agent's field would fix. */
+export function supportingDocumentInvalidError(message, details = {}) {
+    return new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", message, { ...details, recovery: HANDOFF_SUPPORTING_DOCUMENTS_GUIDANCE });
+}
+/** Build a HANDOFF_SUPPORTING_DOCUMENT_INVALID error for a PlanStore-internal
+ * invariant (the count of requested vs. PlanStore-verified documents must
+ * always match; PlanStore either throws for a defective entry or returns one
+ * verified entry per requested document, in lockstep). This is unreachable
+ * through the documented tool flow, so unlike supportingDocumentInvalidError
+ * it must not carry the droppable-field recovery statement: dropping the
+ * field would not be the fix for an invariant violation, and advertising it
+ * would mislead the agent. */
+function supportingDocumentInvariantError(message, details = {}) {
+    return new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", message, details);
+}
+/** Build a HANDOFF_RETAINED_CONTENT_NOT_FOUND error: `content` was omitted
+ * from a handoff_write call and PlanStore has no body retained for this
+ * phase + expectedHandoffUpdatedAt token (see PlanStore.retainHandoffDraft /
+ * getRetainedHandoffDraft). Reasons: no write against this token has ever
+ * failed, the retained draft aged out, the phase went terminal and its
+ * drafts were discarded, or the token itself is wrong/stale. Content is
+ * always required on the first write attempt for a token; it becomes
+ * optional only on a retry that reuses a retained one. */
+export function retainedHandoffContentNotFoundError(phaseId, expectedHandoffUpdatedAt) {
+    return new HandoffContractError("HANDOFF_RETAINED_CONTENT_NOT_FOUND", "content was omitted but no retained draft was found for this phase and expectedHandoffUpdatedAt token.", {
+        phaseId,
+        expectedHandoffUpdatedAt,
+        recovery: "Provide content once. After a write fails, a retry against the exact same expectedHandoffUpdatedAt may omit content to reuse the body just submitted; a fresh token (from a new handoff_prepare) or a phase that has since gone terminal has nothing retained.",
+    });
+}
+/** The exact description externalizeOversizedHandoffContent stamps on the
+ * supporting-document entry it generates for an auto-externalized document.
+ * The single source of truth for recognizing one later: handoff_prepare
+ * matches on this instead of the timestamped file-naming convention, so
+ * detection and generation cannot drift apart. A document a human or agent
+ * linked deliberately (a different description) is already named in the
+ * persisted capsule's own "Supporting documents" bullet and is out of scope
+ * here — only content the tooling itself moved out without being asked. */
+export const HANDOFF_AUTO_EXTERNALIZED_DOCUMENT_DESCRIPTION = "Full submitted handoff detail externalized automatically; required for cold resume and reconciliation.";
+export function isAutoExternalizedHandoffDocument(document) {
+    return document.description === HANDOFF_AUTO_EXTERNALIZED_DOCUMENT_DESCRIPTION;
+}
+/** Level-2 (`##`) headings of a handoff document, in order. Used to name
+ * what an externalized document contains when its content cannot be
+ * inlined (budget, or the file is missing) and as a table of contents
+ * alongside content that is inlined. */
+export function extractHandoffSectionHeadings(content) {
+    const headings = [];
+    for (const line of content.split(/\r?\n/)) {
+        const match = line.match(/^##\s+(.+?)\s*$/);
+        if (match)
+            headings.push(match[1]);
+    }
+    return headings;
+}
+/** Prior `##` headings with no counterpart heading in `newContent`. A
+ * section counts as carried forward only if its exact heading text
+ * (case-insensitive) still appears as a `##` heading somewhere in the new
+ * content — matching by heading, not by scanning prose for the words, keeps
+ * this a narrow structural check rather than a fuzzy content audit. Callers
+ * needing "did the author account for this" evidence use
+ * validateHandoffSectionReconciliation below, which turns this list into a
+ * typed refusal unless every entry has a disposition. */
+function unaccountedHandoffSections(priorSectionHeadings, newContent) {
+    const newHeadings = new Set(extractHandoffSectionHeadings(newContent).map((heading) => heading.trim().toLowerCase()));
+    return priorSectionHeadings.filter((heading) => !newHeadings.has(heading.trim().toLowerCase()));
+}
+/**
+ * Make reconciliation evidenced rather than asserted (P104(F005)/T416).
+ *
+ * Narrow by design: this compares `##` heading text only, never section
+ * content or a fixed category list — it is not a return to the 16-section
+ * scaffold and 14-category cold-start inventory P100(F021)/T396 removed for
+ * making authoring verbose and failing late. A prior capsule with no
+ * headings (or a new submission with none) simply has nothing to name here;
+ * the check degrades to a no-op rather than blocking the write.
+ *
+ * A prior section vanishes from the new content in three ways an author
+ * might legitimately intend: dropped because it no longer matters,
+ * superseded by newer content, or folded into a different section (a rename
+ * reads the same way — the old heading is gone, the content lives under a
+ * new one). This function does not try to tell those apart; it only
+ * requires the author to say which happened, per named section, before the
+ * write proceeds. A deliberate full rewrite where every prior section is
+ * obsolete is handled the same way: every heading is named, and the author
+ * writes one disposition per heading.
+ */
+export function validateHandoffSectionReconciliation(priorSectionHeadings, newContent, dispositions) {
+    const unaccounted = unaccountedHandoffSections(priorSectionHeadings, newContent);
+    if (unaccounted.length === 0)
+        return;
+    const bySection = new Map();
+    for (const entry of dispositions ?? []) {
+        const section = entry.section?.trim();
+        if (section)
+            bySection.set(section.toLowerCase(), entry.disposition ?? "");
+    }
+    const stillUnaccounted = unaccounted.filter((section) => !isSubstantive(bySection.get(section.trim().toLowerCase()) ?? ""));
+    if (stillUnaccounted.length > 0) {
+        throw new HandoffContractError("HANDOFF_SECTION_RECONCILIATION_REQUIRED", "Prior handoff sections have no counterpart in the new content. Supply sectionDispositions with one substantive entry per named section (dropped, superseded, or folded into another section) before writing.", {
+            unaccountedSections: stillUnaccounted,
+            recovery: "Retry against the same phaseRef and expectedHandoffUpdatedAt with sectionDispositions only; content may be omitted to reuse the body just submitted.",
+        });
+    }
+}
 export function hasTaskCompletionEvidence(task) {
     if (task.status !== "done")
         return true;
@@ -132,6 +248,13 @@ export function auditPhaseHandoff(phase, feature) {
         coldStartInventoryCategories: HANDOFF_COLD_START_INVENTORY_CATEGORIES,
         existingCompletenessAudit: phase.handoffAudit,
         phaseWorkMap: buildPhaseWorkMap(phase, feature.number),
+        supportingDocumentsGuidance: HANDOFF_SUPPORTING_DOCUMENTS_GUIDANCE,
+        // Filled in by PlanStore.preparePhaseHandoff, which alone can read
+        // .planner/docs/; this pure function has no filesystem access.
+        externalizedHandoffDocuments: [],
+        // Compact-capsule headings only; PlanStore.preparePhaseHandoff overlays
+        // headings from auto-externalized documents once it has read them back.
+        priorSectionHeadings: phase.handoff.trim() ? extractHandoffSectionHeadings(phase.handoff) : [],
     };
 }
 function nonEmpty(value, field) {
@@ -339,11 +462,16 @@ function sectionBody(content, headings) {
     }
     return body.join("\n").trim();
 }
+// truncateAtSafeBoundary / boundedContentForTransport moved to text-bounds.ts
+// (P104(F005)/T419) so task-context.ts can share them without creating a
+// cycle: this module already imports buildPhaseWorkMap from task-context.ts.
+// Both are exported directly from text-bounds.js at the package root now.
 function boundedSection(value, fallback, maxChars) {
     const normalized = value.trim() || fallback;
     if (normalized.length <= maxChars)
         return normalized;
-    return `${normalized.slice(0, Math.max(0, maxChars - 86)).trimEnd()}\n\n[Extended detail continues in the linked planner document.]`;
+    const safe = truncateAtSafeBoundary(normalized, Math.max(0, maxChars - 86));
+    return `${safe}\n\n[Extended detail continues in the linked planner document.]`;
 }
 /**
  * Mechanically compact oversized legacy or verbose handoffs while retaining the
@@ -390,7 +518,7 @@ export function externalizeOversizedHandoffContent(content, supportingDocumentPa
         extendedContent: `${firstHeading} — extended detail\n\n${base}\n`,
         supportingDocument: {
             path: supportingDocumentPath,
-            description: "Full submitted handoff detail externalized automatically; required for cold resume and reconciliation.",
+            description: HANDOFF_AUTO_EXTERNALIZED_DOCUMENT_DESCRIPTION,
         },
     };
 }
@@ -456,20 +584,32 @@ export function validateHandoffContextSync(phase, feature, input) {
     const requestedDocuments = input.supportingDocuments ?? [];
     const verifiedDocuments = input.verifiedSupportingDocuments ?? [];
     if (requestedDocuments.length !== verifiedDocuments.length) {
-        throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", "Every supporting document must be validated by PlanStore before the handoff is written.", { requestedCount: requestedDocuments.length, verifiedCount: verifiedDocuments.length });
+        throw supportingDocumentInvariantError("Every supporting document must be validated by PlanStore before the handoff is written.", { requestedCount: requestedDocuments.length, verifiedCount: verifiedDocuments.length });
     }
     const verifiedContents = input.verifiedSupportingDocumentContents ?? [];
     if (verifiedContents.length !== verifiedDocuments.length) {
-        throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", "Validated supporting-document content is required for cold-start inventory coverage checks.", { verifiedDocumentCount: verifiedDocuments.length, verifiedContentCount: verifiedContents.length });
+        throw supportingDocumentInvariantError("Validated supporting-document content is required for cold-start inventory coverage checks.", { verifiedDocumentCount: verifiedDocuments.length, verifiedContentCount: verifiedContents.length });
     }
     for (let index = 0; index < requestedDocuments.length; index += 1) {
         const requested = requestedDocuments[index];
         const verified = verifiedDocuments[index];
         if (requested.path !== verified.path || !isSubstantive(requested.description) || requested.description.trim() !== verified.description) {
-            throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document ${requested.path || `(index ${index})`} is not valid or lacks a substantive description.`, { index, path: requested.path });
+            throw supportingDocumentInvalidError(`Supporting document ${requested.path || `(index ${index})`} is not valid or lacks a substantive description.`, { index, path: requested.path });
         }
-        if (!input.content.includes(requested.path)) {
-            throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Canonical handoff content must link supporting document ${requested.path}.`, { index, path: requested.path });
+        // Body-dependent: the manifest is valid on its own, but the drafted content
+        // never linked it. This is the one check that cannot move to prepare, since
+        // prepare runs before the body exists.
+        //
+        // Check the submitted body as well as the persisted one. Auto-externalization
+        // rewrites `content` after the agent submitted it, moving whole sections into
+        // a .planner/docs/ file; a path the author linked inside one of those sections
+        // is no longer in `content` through no fault of theirs. The planner's own
+        // auto-externalized document is the mirror case — its path is generated during
+        // the rewrite, so it appears only in `content`. Accepting either body covers
+        // both without letting through a path the agent never linked anywhere.
+        const linkedBodies = [input.content, ...(input.submittedContent ? [input.submittedContent] : [])];
+        if (!linkedBodies.some((body) => body.includes(requested.path))) {
+            throw supportingDocumentInvalidError(`Canonical handoff content must link supporting document ${requested.path}. Checked the ${input.submittedContent ? "submitted body and the auto-externalized body" : "submitted body"}.`, { index, path: requested.path });
         }
     }
     renderVerifiedHandoffContent(input.content, input.completenessAudit, input.coldStartInventory, verifiedContents);
@@ -482,6 +622,15 @@ export function validateHandoffContextSync(phase, feature, input) {
     if (phase.handoff.trim() && !input.reconciledExistingHandoff) {
         throw new Error("An active handoff already exists. Reconcile its still-relevant content and set reconciledExistingHandoff=true.");
     }
+    if (phase.handoff.trim()) {
+        // Judge against the body the author actually wrote, not the planner's
+        // own auto-externalized compaction (mirrors the supporting-document link
+        // check above): when this write itself got compacted, submittedContent
+        // is the full pre-compaction text and is what a prior section's heading
+        // would still appear in.
+        const newContentForHeadings = input.submittedContent ?? input.content;
+        validateHandoffSectionReconciliation(input.priorSectionHeadings ?? [], newContentForHeadings, input.sectionDispositions);
+    }
     const sync = input.contextSync;
     const taskIds = sync.taskUpdates.map((update) => nonEmpty(update.taskId, "Task update taskId"));
     if (new Set(taskIds).size !== taskIds.length)
@@ -528,6 +677,14 @@ export function applyHandoffContextSync(phase, feature, input, timestamp) {
     for (const update of input.contextSync.taskUpdates) {
         const task = nextPhase.tasks.find((candidate) => candidate.id === update.taskId);
         const files = uniqueStrings(update.filesTouched ?? []);
+        // Decisions mentioned in a completion summary are prose, not decision
+        // authority (a completion summary is explicitly one of the places a new
+        // durable decision must not live only in). Render them into the section
+        // text with that caveat instead of appending to the legacy task.decisions
+        // array, which nothing treats as authoritative and which is otherwise
+        // read-only going forward (see accepted-decision-guard.ts). A decision
+        // worth keeping needs its own accepted_decision_create call on the right
+        // owner; this list is not a substitute for that.
         const decisions = uniqueStrings(update.decisions ?? []);
         const section = [
             COMPLETION_SUMMARY_HEADING,
@@ -539,24 +696,25 @@ export function applyHandoffContextSync(phase, feature, input, timestamp) {
             "**Remaining or unverified:**",
             update.remainingWork.trim(),
             ...(files.length > 0 ? ["", "**Files touched:**", ...files.map((file) => `- ${file}`)] : []),
+            ...(decisions.length > 0 ? ["", "**Decisions mentioned (not decision authority; record any durable decision with accepted_decision_create on its actual owner):**", ...decisions.map((decision) => `- ${decision}`)] : []),
         ].join("\n");
         task.description = appendSection(task.description, section);
         task.descriptionUpdatedAt = timestamp;
-        task.decisions = uniqueStrings([...(task.decisions ?? []), ...decisions]);
         task.updatedAt = timestamp;
         updatedTaskIds.push(task.id);
     }
     const phaseUpdate = input.contextSync.phaseUpdate;
     if (phaseUpdate) {
+        const phaseDecisions = uniqueStrings(phaseUpdate.decisions ?? []);
         const section = [
             "**Handoff context update:**",
             phaseUpdate.progressSummary.trim(),
             "",
             "**Remaining work:**",
             phaseUpdate.remainingWork.trim(),
+            ...(phaseDecisions.length > 0 ? ["", "**Decisions mentioned (not decision authority; record any durable decision with accepted_decision_create on its actual owner):**", ...phaseDecisions.map((decision) => `- ${decision}`)] : []),
         ].join("\n");
         nextPhase.notes = appendSection(nextPhase.notes, section);
-        nextPhase.decisions = uniqueStrings([...(nextPhase.decisions ?? []), ...(phaseUpdate.decisions ?? [])]);
     }
     const featureUpdate = input.contextSync.featureUpdate;
     if (featureUpdate) {

package/dist/handoff-reply.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared reply shaping for the handoff show/prepare tools.
+ *
+ * Every adapter (MCP, Pi, and any future harness) calls the same builders
+ * here instead of assembling its own text/structuredContent pair. Each
+ * builder returns exactly one copy of every piece of information: the
+ * human-readable channel (`text`) and the machine-readable channel
+ * (`structured`) never both carry the same field. Which channel is
+ * canonical for a given piece of content is decided per field below, based
+ * on what a structuredContent-only host needs in order to act (see the
+ * per-field comments) rather than by a single blanket rule — see AGENTS.md
+ * rule 4: this placement decision belongs in the core exactly once, not
+ * once per adapter.
+ */
+import type { HandoffCompletenessAudit, Phase } from "./schema.js";
+import type { PhaseWorkMap } from "./task-context.js";
+import { type HandoffContractError, type PhaseHandoffAudit } from "./handoff-context.js";
+import type { MutationReply } from "./mutation-reply.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 declare function handoffContractFailureReply(error: HandoffContractError, action?: "refresh" | "preparation"): MutationReply;
+export interface BoundedHandoffContent {
+    content: string;
+    fullLength: number;
+    truncated: boolean;
+}
+/** 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 declare function boundedHandoffForTransport(content: string): BoundedHandoffContent;
+/** A tool reply as one result: the human-readable body and the structured
+ * payload, with no field present in both. */
+export interface HandoffReply {
+    text: string;
+    structured: Record<string, unknown>;
+}
+export type HandoffShowReplyInput = {
+    kind: "empty";
+    phaseRef: string;
+    phaseId: string;
+    handoffAudit: HandoffCompletenessAudit | null;
+} | {
+    kind: "archived";
+    phaseRef: string;
+    phaseId: string;
+    /** Raw archived content; the builder bounds it for transport. */
+    content: string;
+    archiveReason: string;
+    archivedAt: string;
+    archiveFile: string;
+    handoffAudit: HandoffCompletenessAudit | null;
+} | {
+    kind: "active";
+    phaseRef: string;
+    phase: Phase;
+    phaseWorkMap: PhaseWorkMap;
+};
+/**
+ * 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 declare function buildHandoffShowReply(input: HandoffShowReplyInput): HandoffReply;
+/** Single source of truth for the prepare-reply evidence-contract sentence,
+ * previously hardcoded identically in both adapters. */
+export declare 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.";
+export interface HandoffPrepareReplyInput {
+    phaseRef: string;
+    audit: PhaseHandoffAudit;
+}
+/**
+ * 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 declare function buildHandoffPrepareReply(input: HandoffPrepareReplyInput): HandoffReply;
+//# sourceMappingURL=handoff-reply.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-reply.d.ts","sourceRoot":"","sources":["../src/handoff-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAA6B,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,GAAE,SAAS,GAAG,aAAyB,GAAG,aAAa,CAMrI;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;oBAMoB;AACpB,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAKjF;AA8CD;6CAC6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAmCD,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEN;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAsEhF;AAED;wDACwD;AACxD,eAAO,MAAM,iCAAiC,0IAC2F,CAAC;AAE1I,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,YAAY,CAkFtF"}

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,
+        },
+    };
+}