@agent-plan/core 0.2.26 → 0.2.28

package/dist/handoff-context.js

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
+import { buildPhaseWorkMap } from "./task-context.js";
 export const COMPLETION_SUMMARY_HEADING = "**Completion summary:**";
 export const HANDOFF_COMPLETENESS_AUDIT_VERSION = 1;
+export const HANDOFF_COLD_START_INVENTORY_VERSION = 1;
+export const TARGET_HANDOFF_CONTENT_CHARS = 8_000;
 export const MAX_HANDOFF_CONTENT_CHARS = 24_000;
 export const HANDOFF_AUDIT_START_MARKER = "<!-- agent-plan:handoff-audit:start -->";
 export const HANDOFF_AUDIT_END_MARKER = "<!-- agent-plan:handoff-audit:end -->";
@@ -24,6 +27,37 @@ export const HANDOFF_COMPLETENESS_CATEGORIES = [
     { id: "project-operating-notes", label: "Project-specific operating notes" },
     { id: "conversation-only-facts", label: "Conversation-only facts" },
 ];
+export const HANDOFF_COLD_START_SOURCE_REVIEWS = [
+    { id: "conversation", label: "Conversation, user corrections, and authorization state" },
+    { id: "planner-entities", label: "Task, sibling tasks, phase, feature, requirements, and prior handoff" },
+    { id: "working-tree", label: "Changed files, diffs, implementation state, and ownership" },
+    { id: "verification-runtime", label: "Commands, test results, runtime observations, and limitations" },
+    { id: "peer-agent-output", label: "Peer-agent messages and delegated-work results, or confirmation that none exist" },
+];
+export const HANDOFF_COLD_START_INVENTORY_CATEGORIES = [
+    { id: "files", label: "Exact files" },
+    { id: "symbols", label: "Exact symbols and identifiers" },
+    { id: "working-tree-ownership", label: "Working-tree state, work ownership, and commit/discard authorization" },
+    { id: "negative-state", label: "Work not started, removals not performed, and intentionally untouched state" },
+    { id: "commands-tools", label: "Commands and tool paths" },
+    { id: "runtime-wiring", label: "Runtime wiring, call sites, and data flow" },
+    { id: "preservation-constraints", label: "Behavior and code paths that must survive" },
+    { id: "verification-evidence", label: "Concrete observations proving completed, live, dead, or inert state" },
+    { id: "related-planned-work", label: "Sibling tasks and related planned capabilities" },
+    { id: "user-visible-behavior", label: "User-visible behavior" },
+    { id: "operator-actions", label: "Operator actions" },
+    { id: "blockers-risks", label: "Blockers and risks" },
+    { id: "remaining-work", label: "Remaining work" },
+    { id: "ordered-resume-steps", label: "Ordered resume steps" },
+];
+export const HANDOFF_CANONICAL_SECTIONS = [
+    "Current focus",
+    "Current and partial state",
+    "Preservation constraints",
+    "Supporting documents",
+    "Blockers and risks",
+    "How to resume",
+];
 export class HandoffContractError extends Error {
     code;
     details;
@@ -41,6 +75,37 @@ export function hasTaskCompletionEvidence(task) {
         return true;
     return task.statusLog.some((entry) => entry.toStatus === "done" && entry.description.trim().length > 0);
 }
+export function buildHandoffDraftTemplate(phase, feature) {
+    const featureRef = `F${String(feature.number).padStart(3, "0")}`;
+    const phaseRef = `P${String(phase.number).padStart(3, "0")}(${featureRef})`;
+    return [
+        `# ${phaseRef} — {{REQUIRED: meaningful handoff title}}`,
+        "",
+        "<!-- Planner-generated: Created at, Updated at, and structured Reason. Do not write these lines in the draft. -->",
+        "",
+        "## Current focus",
+        `- Feature: ${featureRef} — ${feature.name}`,
+        `- Phase: ${phaseRef} — ${phase.title}`,
+        "- Task: {{REQUIRED: exact composite task ref and title}}",
+        "- Exact resume point: {{REQUIRED: file, symbol, command, or state boundary}}",
+        "",
+        "## Current and partial state",
+        "{{REQUIRED: concise completed/current/partial state only; keep extended detail in supporting documents}}",
+        "",
+        "## Preservation constraints",
+        "{{REQUIRED: minimal behaviors and boundaries that must survive}}",
+        "",
+        "## Supporting documents",
+        "- {{REQUIRED: ordered .planner/docs/*.md links with why each is needed, or an explicit verified statement that none are needed}}",
+        "",
+        "## Blockers and risks",
+        "- {{REQUIRED: blocker/risk, or a substantive verified statement that none apply}}",
+        "",
+        "## How to resume",
+        "1. {{REQUIRED: first exact action, including file/symbol/command}}",
+        "2. {{REQUIRED: subsequent ordered actions and verification}}",
+    ].join("\n");
+}
 export function auditPhaseHandoff(phase, feature) {
     const missingCompletionTasks = phase.tasks
         .filter((task) => task.status === "done" && !hasTaskCompletionEvidence(task))
@@ -53,9 +118,20 @@ export function auditPhaseHandoff(phase, feature) {
         missingCompletionTaskIds: missingCompletionTasks.map((task) => task.id),
         missingCompletionTasks,
         completenessVersion: HANDOFF_COMPLETENESS_AUDIT_VERSION,
+        targetContentChars: TARGET_HANDOFF_CONTENT_CHARS,
         maxContentChars: MAX_HANDOFF_CONTENT_CHARS,
         completenessCategories: HANDOFF_COMPLETENESS_CATEGORIES,
+        canonicalSections: HANDOFF_CANONICAL_SECTIONS,
+        requiredHumanInputs: [
+            { id: "title", label: "Meaningful title", description: "A concise handoff title; the planner renders it as the H1." },
+            { id: "reason", label: "Reason", description: "Why work is stopping and why a cold agent needs this handoff; the planner renders it as metadata." },
+        ],
+        draftTemplate: buildHandoffDraftTemplate(phase, feature),
+        coldStartInventoryVersion: HANDOFF_COLD_START_INVENTORY_VERSION,
+        coldStartSourceReviews: HANDOFF_COLD_START_SOURCE_REVIEWS,
+        coldStartInventoryCategories: HANDOFF_COLD_START_INVENTORY_CATEGORIES,
         existingCompletenessAudit: phase.handoffAudit,
+        phaseWorkMap: buildPhaseWorkMap(phase, feature.number),
     };
 }
 function nonEmpty(value, field) {
@@ -93,7 +169,14 @@ export function handoffContentHash(content) {
 }
 export function validateHandoffCompletenessAudit(audit) {
     const expectedIds = HANDOFF_COMPLETENESS_CATEGORIES.map((entry) => entry.id);
-    if (!audit || audit.version !== HANDOFF_COMPLETENESS_AUDIT_VERSION) {
+    if (!audit) {
+        return expectedIds.map((category) => ({
+            category,
+            status: "captured",
+            detail: "Derived from the compact handoff and persisted planner state; no duplicate prose audit was supplied.",
+        }));
+    }
+    if (audit.version !== HANDOFF_COMPLETENESS_AUDIT_VERSION) {
         throw new HandoffContractError("HANDOFF_COMPLETENESS_AUDIT_REQUIRED", `Handoff completeness audit version ${HANDOFF_COMPLETENESS_AUDIT_VERSION} is required.`, { requiredVersion: HANDOFF_COMPLETENESS_AUDIT_VERSION, missingCategories: expectedIds });
     }
     const byCategory = new Map();
@@ -115,6 +198,202 @@ export function validateHandoffCompletenessAudit(audit) {
     }
     return expectedIds.map((id) => byCategory.get(id));
 }
+export function validateHandoffColdStartInventory(inventory, content, supportingDocumentContents = []) {
+    const expectedIds = HANDOFF_COLD_START_INVENTORY_CATEGORIES.map((entry) => entry.id);
+    if (!inventory) {
+        return expectedIds.map((category) => ({
+            category,
+            items: ["Derived from the compact handoff and persisted planner state."],
+        }));
+    }
+    if (inventory.version !== HANDOFF_COLD_START_INVENTORY_VERSION) {
+        throw new HandoffContractError("HANDOFF_COLD_START_INVENTORY_REQUIRED", `Cold-start inventory version ${HANDOFF_COLD_START_INVENTORY_VERSION} is required when legacy inventory evidence is supplied.`, { requiredVersion: HANDOFF_COLD_START_INVENTORY_VERSION, missingCategories: expectedIds });
+    }
+    const requiredSources = HANDOFF_COLD_START_SOURCE_REVIEWS.map((entry) => entry.id);
+    const requiredSourceIds = new Set(requiredSources);
+    const sourceReviews = new Map();
+    const duplicateSources = [];
+    for (const review of inventory.sourceReviews) {
+        if (sourceReviews.has(review.source))
+            duplicateSources.push(review.source);
+        else
+            sourceReviews.set(review.source, review.detail);
+    }
+    const missingSources = requiredSources.filter((source) => !sourceReviews.has(source));
+    const unknownSources = [...sourceReviews.keys()].filter((source) => !requiredSourceIds.has(source));
+    const invalidSources = requiredSources.filter((source) => {
+        const detail = sourceReviews.get(source);
+        return detail !== undefined && !isSubstantive(detail);
+    });
+    const byCategory = new Map();
+    const duplicates = [];
+    for (const entry of inventory.entries) {
+        if (byCategory.has(entry.category))
+            duplicates.push(entry.category);
+        else
+            byCategory.set(entry.category, entry);
+    }
+    const missingCategories = expectedIds.filter((id) => !byCategory.has(id));
+    const unknownCategories = [...byCategory.keys()].filter((id) => !expectedIds.includes(id));
+    const invalidCategories = [];
+    for (const id of expectedIds) {
+        const entry = byCategory.get(id);
+        if (!entry)
+            continue;
+        const items = uniqueStrings(entry.items);
+        const notApplicableReason = entry.notApplicableReason?.trim() ?? "";
+        if (items.length === 0)
+            invalidCategories.push(id);
+        if (notApplicableReason && !isSubstantive(notApplicableReason))
+            invalidCategories.push(id);
+        if (items.some((item) => /^(?:n\/?a|none|nothing|unknown|tbd|see above)$/i.test(item.trim())))
+            invalidCategories.push(id);
+    }
+    if (missingSources.length > 0 || unknownSources.length > 0 || duplicateSources.length > 0 || invalidSources.length > 0
+        || missingCategories.length > 0 || unknownCategories.length > 0 || duplicates.length > 0 || invalidCategories.length > 0) {
+        throw new HandoffContractError("HANDOFF_COLD_START_INVENTORY_REQUIRED", "The cold-start inventory is incomplete. Review every prepared source before drafting; every category needs at least one concrete item. When nothing exists, the item must explicitly state the verified absence and why it matters (for example, 'No deletion has started; all original files remain intact').", {
+            missingSources,
+            invalidSources,
+            unknownSources,
+            duplicateSources: [...new Set(duplicateSources)],
+            missingCategories,
+            invalidCategories: [...new Set(invalidCategories)],
+            unknownCategories,
+            duplicateCategories: [...new Set(duplicates)],
+        });
+    }
+    const normalize = (value) => value.normalize("NFKC").replace(/[`*_]/g, "").replace(/\s+/g, " ").toLowerCase();
+    const corpus = normalize([content, ...supportingDocumentContents].join("\n"));
+    const uncoveredItems = expectedIds.flatMap((id) => {
+        const entry = byCategory.get(id);
+        return uniqueStrings(entry.items)
+            .filter((item) => !corpus.includes(normalize(item)))
+            .map((item) => ({ category: id, item }));
+    });
+    if (uncoveredItems.length > 0) {
+        throw new HandoffContractError("HANDOFF_COLD_START_INVENTORY_UNCOVERED", "Resume-critical inventory items are missing from the canonical handoff and validated supporting documents. Add each exact item before retrying; do not certify from generic prose.", { uncoveredItems });
+    }
+    return expectedIds.map((id) => {
+        const entry = byCategory.get(id);
+        return {
+            category: entry.category,
+            items: uniqueStrings(entry.items),
+            ...(entry.notApplicableReason?.trim() ? { notApplicableReason: entry.notApplicableReason.trim() } : {}),
+        };
+    });
+}
+export function validateHandoffReadBackVerification(phase, input) {
+    const audit = phase.handoffAudit;
+    const actualContentHash = phase.handoff.trim() ? handoffContentHash(phase.handoff) : "";
+    if (!phase.handoff.trim() || !audit || audit.contentHash !== actualContentHash || audit.contentLength !== phase.handoff.length) {
+        throw new HandoffContractError("HANDOFF_READBACK_VERIFICATION_REQUIRED", "The persisted handoff or its audit metadata is missing or inconsistent. Run handoff_prepare, rewrite the handoff, then read it back before verification.", { expectedContentHash: input.expectedContentHash, actualContentHash, auditContentHash: audit?.contentHash ?? "" });
+    }
+    if (!input.expectedContentHash.trim() || input.expectedContentHash !== actualContentHash) {
+        throw new HandoffContractError("HANDOFF_READBACK_VERIFICATION_REQUIRED", "The handoff changed after the read-back candidate was selected. Call handoff_show again and verify the returned contentHash.", { expectedContentHash: input.expectedContentHash, actualContentHash });
+    }
+    const requiredSources = HANDOFF_COLD_START_SOURCE_REVIEWS.map((entry) => entry.id);
+    const suppliedReviews = input.sourceReviews ?? [];
+    if (suppliedReviews.length === 0 && (input.omissionsFound ?? []).length === 0) {
+        return requiredSources.map((source) => ({
+            source,
+            detail: "Derived from persisted handoff content, planner entities, and read-back state; no duplicate source inventory was supplied.",
+        }));
+    }
+    const bySource = new Map();
+    const duplicateSources = [];
+    for (const review of suppliedReviews) {
+        if (bySource.has(review.source))
+            duplicateSources.push(review.source);
+        else
+            bySource.set(review.source, review.detail.trim());
+    }
+    const missingSources = requiredSources.filter((source) => !bySource.has(source));
+    const unknownSources = [...bySource.keys()].filter((source) => !requiredSources.includes(source));
+    const invalidSources = requiredSources.filter((source) => {
+        const detail = bySource.get(source);
+        return detail !== undefined && !isSubstantive(detail);
+    });
+    if (missingSources.length > 0 || unknownSources.length > 0 || duplicateSources.length > 0 || invalidSources.length > 0) {
+        throw new HandoffContractError("HANDOFF_READBACK_VERIFICATION_REQUIRED", "Legacy read-back source evidence is incomplete. For compact handoffs omit sourceReviews and omissionsFound so the planner can derive evidence from persisted state.", { missingSources, unknownSources, duplicateSources: [...new Set(duplicateSources)], invalidSources });
+    }
+    const omissionsFound = uniqueStrings(input.omissionsFound ?? []);
+    if (omissionsFound.length > 0) {
+        throw new HandoffContractError("HANDOFF_READBACK_GAPS_FOUND", "The persisted handoff is not resume-ready because the read-back found omissions. Run handoff_prepare again, reconcile every listed gap, and rewrite before retrying verification.", { omissionsFound });
+    }
+    return requiredSources.map((source) => ({ source, detail: bySource.get(source) }));
+}
+function sectionBody(content, headings) {
+    const lines = content.split(/\r?\n/);
+    const normalized = new Set(headings.map((heading) => heading.toLowerCase()));
+    const start = lines.findIndex((line) => {
+        const match = line.match(/^##\s+(.+?)\s*$/);
+        return Boolean(match && normalized.has(match[1].toLowerCase()));
+    });
+    if (start < 0)
+        return "";
+    const body = [];
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (/^##\s+/.test(lines[index]))
+            break;
+        body.push(lines[index]);
+    }
+    return body.join("\n").trim();
+}
+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.]`;
+}
+/**
+ * Mechanically compact oversized legacy or verbose handoffs while retaining the
+ * complete submitted body in one planner-owned Markdown document.
+ */
+export function externalizeOversizedHandoffContent(content, supportingDocumentPath) {
+    const base = stripRenderedCompletenessAudit(content);
+    if (base.length <= TARGET_HANDOFF_CONTENT_CHARS) {
+        return { content: base, externalized: false, extendedContent: "" };
+    }
+    const firstHeading = base.split(/\r?\n/).find((line) => /^#\s+/.test(line.trim()))?.trim() ?? "# Handoff resume capsule";
+    const metadata = ["Created at", "Updated at", "Reason"].map((label) => base.split(/\r?\n/).find((line) => line.toLowerCase().startsWith(`${label.toLowerCase()}:`))?.trim() ?? `${label}: See supporting document.`);
+    const currentFocus = boundedSection(sectionBody(base, ["Current focus"]), "Exact focus and resume point are preserved in the supporting document.", 1_200);
+    const currentState = boundedSection(sectionBody(base, ["Current and partial state", "What was being done"]), "Current and partial work details are preserved in the supporting document.", 1_500);
+    const preservation = boundedSection(sectionBody(base, ["Preservation constraints"]), "Preservation constraints are recorded in the supporting document.", 900);
+    const blockers = boundedSection(sectionBody(base, ["Blockers and risks", "Blockers"]), "Blockers and risks are recorded in the supporting document.", 900);
+    const resume = boundedSection(sectionBody(base, ["How to resume", "Next steps"]), "1. Read the linked supporting document completely, then resume from its first ordered action.", 1_500);
+    const compact = [
+        firstHeading,
+        "",
+        ...metadata,
+        "",
+        "## Current focus",
+        currentFocus,
+        "",
+        "## Current and partial state",
+        currentState,
+        "",
+        "## Preservation constraints",
+        preservation,
+        "",
+        "## Supporting documents",
+        `- ${supportingDocumentPath} — Full submitted handoff detail externalized automatically because the inline resume capsule exceeded ${TARGET_HANDOFF_CONTENT_CHARS} characters. Read this document before resuming.`,
+        "",
+        "## Blockers and risks",
+        blockers,
+        "",
+        "## How to resume",
+        resume,
+    ].join("\n").trim();
+    return {
+        content: compact,
+        externalized: true,
+        extendedContent: `${firstHeading} — extended detail\n\n${base}\n`,
+        supportingDocument: {
+            path: supportingDocumentPath,
+            description: "Full submitted handoff detail externalized automatically; required for cold resume and reconciliation.",
+        },
+    };
+}
 export function renderHandoffCompletenessAudit(audit) {
     const entries = validateHandoffCompletenessAudit(audit);
     const labels = new Map(HANDOFF_COMPLETENESS_CATEGORIES.map((entry) => [entry.id, entry.label]));
@@ -131,41 +410,58 @@ export function renderHandoffCompletenessAudit(audit) {
         HANDOFF_AUDIT_END_MARKER,
     ].join("\n").trim();
 }
-export function renderVerifiedHandoffContent(content, audit) {
+export function renderVerifiedHandoffContent(content, audit, coldStartInventory, supportingDocumentContents = []) {
     const base = stripRenderedCompletenessAudit(content);
     validateCanonicalHandoffContent(base);
     validateHandoffCompletenessAudit(audit);
-    const rendered = `${base}\n\n${renderHandoffCompletenessAudit(audit)}`.trim();
-    if (rendered.length > MAX_HANDOFF_CONTENT_CHARS) {
-        throw new HandoffContractError("HANDOFF_CONTENT_LIMIT_EXCEEDED", `Canonical handoff content is ${rendered.length} characters; the maximum is ${MAX_HANDOFF_CONTENT_CHARS}. Move extended detail to committed Markdown under .planner/docs/ and link it with a substantive explanation.`, { contentLength: rendered.length, maxContentChars: MAX_HANDOFF_CONTENT_CHARS });
+    validateHandoffColdStartInventory(coldStartInventory, base, supportingDocumentContents);
+    if (base.length > MAX_HANDOFF_CONTENT_CHARS) {
+        throw new HandoffContractError("HANDOFF_CONTENT_LIMIT_EXCEEDED", `Inline handoff content is ${base.length} characters after compaction; the absolute compatibility ceiling is ${MAX_HANDOFF_CONTENT_CHARS}. Retry through PlanStore so extended detail can be externalized automatically.`, { contentLength: base.length, targetContentChars: TARGET_HANDOFF_CONTENT_CHARS, maxContentChars: MAX_HANDOFF_CONTENT_CHARS, continuation: "externalize-and-retry" });
     }
-    return rendered;
+    return base;
+}
+export function materializeHandoffMetadata(content, reason, createdAt, updatedAt) {
+    const normalizedReason = reason.trim();
+    if (!normalizedReason) {
+        throw new HandoffContractError("HANDOFF_REASON_REQUIRED", "A structured handoff reason is required before drafting or persistence. Run handoff_prepare and provide reason; timestamps are planner-generated.", { requiredInputs: ["title", "reason"], generatedMetadata: ["Created at", "Updated at"] });
+    }
+    const existingCreatedAt = content.match(/^Created at:\s*(\S+)\s*$/im)?.[1] ?? createdAt;
+    const withoutMetadata = content
+        .split(/\r?\n/)
+        .filter((line) => !/^(?:Created at|Updated at|Reason):\s*/i.test(line.trim()))
+        .join("\n")
+        .trim();
+    const lines = withoutMetadata.split("\n");
+    const firstContent = lines.findIndex((line) => line.trim().length > 0);
+    const metadata = [`Created at: ${existingCreatedAt}`, `Updated at: ${updatedAt}`, `Reason: ${normalizedReason}`];
+    if (firstContent >= 0 && /^#\s+/.test(lines[firstContent] ?? "")) {
+        lines.splice(firstContent + 1, 0, "", ...metadata);
+    }
+    else {
+        lines.unshift(...metadata, "");
+    }
+    return lines.join("\n").trim();
 }
 export function validateCanonicalHandoffContent(content) {
+    // A handoff is a resume capsule, not a form. The prepared scaffold documents
+    // useful headings, but requiring agents to reproduce those headings creates a
+    // late write-time failure and makes them draft the same handoff twice.
     const body = nonEmpty(content, "Handoff content");
-    const required = [
-        { label: "Created at", pattern: /^Created at:\s*\S+/im },
-        { label: "Updated at", pattern: /^Updated at:\s*\S+/im },
-        { label: "Reason", pattern: /^Reason:\s*\S+/im },
-        { label: "Current focus", pattern: /^##\s+Current focus\s*$/im },
-        { label: "What was being done", pattern: /^##\s+What was being done\s*$/im },
-        { label: "How to resume", pattern: /^##\s+How to resume\s*$/im },
-        { label: "Files touched", pattern: /^##\s+Files touched\s*$/im },
-        { label: "Blockers", pattern: /^##\s+Blockers\s*$/im },
-        { label: "Next steps", pattern: /^##\s+Next steps\s*$/im },
-        { label: "Recent decisions", pattern: /^##\s+Recent decisions\s*$/im },
-    ];
-    const missing = required.filter((entry) => !entry.pattern.test(body)).map((entry) => entry.label);
-    if (missing.length > 0)
-        throw new Error(`Canonical handoff is missing required sections: ${missing.join(", ")}.`);
+    const unresolvedPlaceholders = [...body.matchAll(/\{\{REQUIRED:[^}]+\}\}/g)].map((match) => match[0]);
+    if (unresolvedPlaceholders.length > 0) {
+        throw new HandoffContractError("HANDOFF_CANONICAL_SECTIONS_REQUIRED", "The handoff still contains unresolved placeholders. Replace every placeholder before writing.", { missingSections: [], unresolvedPlaceholders: [...new Set(unresolvedPlaceholders)] });
+    }
 }
 export function validateHandoffContextSync(phase, feature, input) {
-    renderVerifiedHandoffContent(input.content, input.completenessAudit);
     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 });
     }
+    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 });
+    }
     for (let index = 0; index < requestedDocuments.length; index += 1) {
         const requested = requestedDocuments[index];
         const verified = verifiedDocuments[index];
@@ -176,8 +472,9 @@ export function validateHandoffContextSync(phase, feature, input) {
             throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Canonical handoff content must link supporting document ${requested.path}.`, { index, path: requested.path });
         }
     }
-    if (phase.status === "done" || phase.status === "canceled") {
-        throw new Error(`Cannot write a handoff on ${phase.status} phase ${phase.id}; completed phases have no pending handoff.`);
+    renderVerifiedHandoffContent(input.content, input.completenessAudit, input.coldStartInventory, verifiedContents);
+    if (phase.status === "done" || phase.status === "rejected" || phase.status === "canceled") {
+        throw new Error(`Cannot write a handoff on ${phase.status} phase ${phase.id}; terminal phases have no pending handoff.`);
     }
     if (phase.handoffUpdatedAt !== input.expectedHandoffUpdatedAt) {
         throw new Error("Handoff changed after preparation. Run handoff_prepare again and reconcile the latest content before writing.");
@@ -222,8 +519,9 @@ export function validateHandoffContextSync(phase, feature, input) {
 }
 export function applyHandoffContextSync(phase, feature, input, timestamp) {
     validateHandoffContextSync(phase, feature, input);
-    const handoffContent = renderVerifiedHandoffContent(input.content, input.completenessAudit);
+    const handoffContent = renderVerifiedHandoffContent(input.content, input.completenessAudit, input.coldStartInventory, input.verifiedSupportingDocumentContents ?? []);
     const auditEntries = validateHandoffCompletenessAudit(input.completenessAudit);
+    const coldStartInventoryEntries = validateHandoffColdStartInventory(input.coldStartInventory, stripRenderedCompletenessAudit(input.content), input.verifiedSupportingDocumentContents ?? []);
     const nextPhase = structuredClone(phase);
     const nextFeature = structuredClone(feature);
     const updatedTaskIds = [];
@@ -270,10 +568,23 @@ export function applyHandoffContextSync(phase, feature, input, timestamp) {
     nextPhase.handoffAudit = {
         version: HANDOFF_COMPLETENESS_AUDIT_VERSION,
         entries: auditEntries,
+        coldStartInventory: {
+            version: HANDOFF_COLD_START_INVENTORY_VERSION,
+            sourceReviews: HANDOFF_COLD_START_SOURCE_REVIEWS.map(({ id }) => {
+                const review = input.coldStartInventory?.sourceReviews.find((entry) => entry.source === id);
+                return {
+                    source: id,
+                    detail: review?.detail.trim() || "Derived from persisted handoff content, planner entities, and read-back state; no duplicate source inventory was supplied.",
+                };
+            }),
+            entries: coldStartInventoryEntries,
+        },
         supportingDocuments: input.verifiedSupportingDocuments ?? [],
         contentHash: handoffContentHash(handoffContent),
         contentLength: handoffContent.length,
         verifiedAt: timestamp,
+        resumeReadyAt: "",
+        readBackSourceReviews: [],
     };
     nextPhase.handoffReadAt = "";
     nextPhase.updatedAt = timestamp;

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from "./recap.js";
 export * from "./planner-rules.js";
 export * from "./planner-skill.js";
 export * from "./display-status.js";
+export * from "./description-freshness.js";
 export * from "./task-context.js";
 export * from "./task-selection.js";
 export * from "./task-start-outcome.js";
@@ -15,7 +16,9 @@ export * from "./handoff-context.js";
 export * from "./project-context-migration.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
-export { PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, type IdeaCreateInput, type IdeaUpdateInput, type IdeaPromotionTargetInput, type PhaseHandoffSummary, type OrphanPhaseSummary } from "./plan-store.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 { 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,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,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1R,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,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"}

package/dist/index.js

@@ -6,6 +6,7 @@ export * from "./recap.js";
 export * from "./planner-rules.js";
 export * from "./planner-skill.js";
 export * from "./display-status.js";
+export * from "./description-freshness.js";
 export * from "./task-context.js";
 export * from "./task-selection.js";
 export * from "./task-start-outcome.js";
@@ -15,6 +16,8 @@ export * from "./handoff-context.js";
 export * from "./project-context-migration.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
-export { PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock } from "./plan-store.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 { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";

package/dist/package-version.d.ts

@@ -1,6 +1,8 @@
 export interface RuntimePackageVersion {
     name: string;
     version: string;
+    /** Absolute path to the loaded package manifest used as the version source. */
+    packageJsonPath?: string;
 }
 /** Find the nearest matching package manifest above a loaded module. */
 export declare function packageVersionFromModule(moduleUrlOrPath: string, expectedName: string): RuntimePackageVersion;

package/dist/package-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../src/package-version.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAaD,wEAAwE;AACxE,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAqBvB;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB,qBAAqB,CAGvB"}
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../src/package-version.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAaD,wEAAwE;AACxE,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAqBvB;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB,qBAAqB,CAGvB"}

package/dist/package-version.js

@@ -18,7 +18,7 @@ export function packageVersionFromModule(moduleUrlOrPath, expectedName) {
                 if (typeof manifest.version !== "string" || !manifest.version.trim()) {
                     throw new Error(`Package ${expectedName} has no valid version in ${manifestPath}.`);
                 }
-                return { name: expectedName, version: manifest.version };
+                return { name: expectedName, version: manifest.version, packageJsonPath: manifestPath };
             }
         }
         const parent = dirname(current);

package/dist/payload-fallback.d.ts

@@ -1,4 +1,4 @@
-export type PlannerPayloadEntity = "project" | "feature" | "phase" | "task";
+export type PlannerPayloadEntity = "project" | "feature" | "phase" | "task" | "requirement" | "idea" | "acceptedDecision";
 export type PlannerPayloadOperation = "update" | "discuss";
 export type PlannerPayloadFailureCode = "NO_MUTABLE_FIELDS_RECEIVED" | "DESCRIPTION_MARKDOWN_FALLBACK_REQUIRED";
 export interface DescriptionFallbackInput {

package/dist/payload-fallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload-fallback.d.ts","sourceRoot":"","sources":["../src/payload-fallback.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAC5E,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC3D,MAAM,MAAM,yBAAyB,GAAG,4BAA4B,GAAG,wCAAwC,CAAC;AAEhH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,uBAAuB,CAAC;IACnC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,wBAAwB,CAAC;CAChD;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,yBAAyB,CAAC;IACrC,4BAA4B,EAAE,OAAO,CAAC;IACtC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,uBAAuB,CAAC;IACnC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGrF;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAWnG;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,4BAA4B,GAClC,6BAA6B,CAgD/B"}
+{"version":3,"file":"payload-fallback.d.ts","sourceRoot":"","sources":["../src/payload-fallback.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,kBAAkB,CAAC;AAC1H,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC3D,MAAM,MAAM,yBAAyB,GAAG,4BAA4B,GAAG,wCAAwC,CAAC;AAEhH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,uBAAuB,CAAC;IACnC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,wBAAwB,CAAC;CAChD;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,yBAAyB,CAAC;IACrC,4BAA4B,EAAE,OAAO,CAAC;IACtC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,uBAAuB,CAAC;IACnC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGrF;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAiBnG;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,4BAA4B,GAClC,6BAA6B,CAgD/B"}

package/dist/payload-fallback.js

@@ -24,6 +24,12 @@ export function suggestedDescriptionRefPath(entity, entityId) {
             return `.planner/docs/phases/${entityId ?? "phase"}.md`;
         case "task":
             return `.planner/docs/tasks/${entityId ?? "task"}.md`;
+        case "requirement":
+            return `.planner/docs/requirements/${entityId ?? "requirement"}.md`;
+        case "idea":
+            return `.planner/docs/ideas/${entityId ?? "idea"}.md`;
+        case "acceptedDecision":
+            return `.planner/docs/accepted-decisions/${entityId ?? "accepted-decision"}.md`;
     }
 }
 export function noMutableFieldsReceived(input) {