@agent-plan/core 0.2.25 → 0.2.27

package/dist/handoff-context.js

@@ -1,4 +1,79 @@
+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 -->";
+export const HANDOFF_COMPLETENESS_CATEGORIES = [
+    { id: "exact-focus-resume-point", label: "Exact focus and resume point" },
+    { id: "first-resume-action", label: "First resume action" },
+    { id: "completed-work", label: "Completed work" },
+    { id: "partial-work", label: "Partial work" },
+    { id: "remaining-work", label: "Remaining work" },
+    { id: "decisions-rationale", label: "Decisions and rationale" },
+    { id: "rejected-alternatives", label: "Rejected alternatives" },
+    { id: "files-symbols", label: "Files and symbols" },
+    { id: "branch-worktree", label: "Branch and worktree" },
+    { id: "commands-tools", label: "Commands and tools" },
+    { id: "completed-verification", label: "Completed verification" },
+    { id: "pending-verification", label: "Pending verification" },
+    { id: "runtime-limitations-workarounds", label: "Runtime limitations and workarounds" },
+    { id: "blockers-risks", label: "Blockers and risks" },
+    { id: "user-visible-behavior", label: "User-visible behavior" },
+    { id: "operator-actions", label: "Operator actions" },
+    { 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",
+];
+const LEGACY_HANDOFF_CANONICAL_SECTIONS = [
+    "Created at", "Updated at", "Reason", "Current focus", "What was being done",
+    "Working tree and ownership", "Work not started or intentionally untouched", "Runtime wiring",
+    "Preservation constraints", "Verification evidence", "Related planned work", "How to resume",
+    "Files touched", "Blockers", "Next steps", "Recent decisions",
+];
+export class HandoffContractError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "HandoffContractError";
+        this.code = code;
+        this.details = details;
+    }
+}
 export function hasTaskCompletionEvidence(task) {
     if (task.status !== "done")
         return true;
@@ -6,6 +81,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))
@@ -17,6 +123,21 @@ export function auditPhaseHandoff(phase, feature) {
         handoffUpdatedAt: phase.handoffUpdatedAt,
         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) {
@@ -34,6 +155,279 @@ function appendSection(existing, section) {
         return existing;
     return existing.trim() ? `${existing.trim()}\n\n---\n${normalized}` : normalized;
 }
+function isSubstantive(value) {
+    const normalized = value.trim();
+    if (normalized.length < 12)
+        return false;
+    return !/^(?:n\/?a|none|nothing|unknown|same as above|see (?:above|handoff|document)|not applicable|tbd)[.!]?$/i.test(normalized);
+}
+function stripRenderedCompletenessAudit(content) {
+    const start = content.indexOf(HANDOFF_AUDIT_START_MARKER);
+    if (start < 0)
+        return content.trim();
+    const end = content.indexOf(HANDOFF_AUDIT_END_MARKER, start);
+    if (end < 0)
+        return content.slice(0, start).trim();
+    return `${content.slice(0, start)}${content.slice(end + HANDOFF_AUDIT_END_MARKER.length)}`.trim();
+}
+export function handoffContentHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function validateHandoffCompletenessAudit(audit) {
+    const expectedIds = HANDOFF_COMPLETENESS_CATEGORIES.map((entry) => entry.id);
+    if (!audit || 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();
+    const duplicates = [];
+    for (const entry of audit.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 = expectedIds.filter((id) => {
+        const entry = byCategory.get(id);
+        return entry ? !isSubstantive(entry.detail) : false;
+    });
+    if (missingCategories.length > 0 || unknownCategories.length > 0 || duplicates.length > 0 || invalidCategories.length > 0) {
+        throw new HandoffContractError("HANDOFF_COMPLETENESS_AUDIT_REQUIRED", "The handoff completeness audit is missing required categories or contains non-substantive entries.", { missingCategories, invalidCategories, unknownCategories, duplicateCategories: [...new Set(duplicates)] });
+    }
+    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 || 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 before handoff persistence. Populate it from the scaffold returned by handoff_prepare.`, { 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 bySource = new Map();
+    const duplicateSources = [];
+    for (const review of input.sourceReviews) {
+        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", "Read-back verification must re-check every required source against the persisted handoff with substantive findings.", { 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]));
+    return [
+        HANDOFF_AUDIT_START_MARKER,
+        `## Operational completeness audit (v${HANDOFF_COMPLETENESS_AUDIT_VERSION})`,
+        "",
+        ...entries.flatMap((entry) => [
+            `### ${labels.get(entry.category) ?? entry.category}`,
+            `**Status:** ${entry.status}`,
+            entry.detail.trim(),
+            "",
+        ]),
+        HANDOFF_AUDIT_END_MARKER,
+    ].join("\n").trim();
+}
+export function renderVerifiedHandoffContent(content, audit, coldStartInventory, supportingDocumentContents = []) {
+    const base = stripRenderedCompletenessAudit(content);
+    validateCanonicalHandoffContent(base);
+    validateHandoffCompletenessAudit(audit);
+    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 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) {
     const body = nonEmpty(content, "Handoff content");
     const required = [
@@ -41,21 +435,56 @@ export function validateCanonicalHandoffContent(content) {
         { 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: "Current and partial state", pattern: /^##\s+Current and partial state\s*$/im },
+        { label: "Preservation constraints", pattern: /^##\s+Preservation constraints\s*$/im },
+        { label: "Supporting documents", pattern: /^##\s+Supporting documents\s*$/im },
+        { label: "Blockers and risks", pattern: /^##\s+Blockers and risks\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(", ")}.`);
+    if (missing.length === 0) {
+        const unresolvedPlaceholders = [...body.matchAll(/\{\{REQUIRED:[^}]+\}\}/g)].map((match) => match[0]);
+        if (unresolvedPlaceholders.length > 0) {
+            throw new HandoffContractError("HANDOFF_CANONICAL_SECTIONS_REQUIRED", "The canonical handoff still contains unresolved placeholders. Replace every placeholder before writing.", { missingSections: [], unresolvedPlaceholders: [...new Set(unresolvedPlaceholders)] });
+        }
+        return;
+    }
+    const legacyMissing = LEGACY_HANDOFF_CANONICAL_SECTIONS.filter((label) => {
+        if (label === "Created at")
+            return !/^Created at:\s*\S+/im.test(body);
+        if (label === "Updated at")
+            return !/^Updated at:\s*\S+/im.test(body);
+        if (label === "Reason")
+            return !/^Reason:\s*\S+/im.test(body);
+        return !new RegExp(`^##\\s+${label.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")}\\s*$`, "im").test(body);
+    });
+    if (legacyMissing.length > 0) {
+        throw new HandoffContractError("HANDOFF_CANONICAL_SECTIONS_REQUIRED", "The canonical handoff does not match the prepared scaffold. Fill every required heading and replace every placeholder before writing.", { missingSections: missing, legacyMissingSections: legacyMissing, unresolvedPlaceholders: [...new Set([...body.matchAll(/\{\{REQUIRED:[^}]+\}\}/g)].map((m) => m[0]))] });
+    }
 }
 export function validateHandoffContextSync(phase, feature, input) {
-    validateCanonicalHandoffContent(input.content);
-    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.`);
+    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];
+        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 });
+        }
+        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 });
+        }
+    }
+    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.");
@@ -100,6 +529,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, 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 = [];
@@ -141,8 +573,26 @@ export function applyHandoffContextSync(phase, feature, input, timestamp) {
         nextFeature.workDone = appendSection(nextFeature.workDone, featureUpdate.workDone);
         nextFeature.workRemaining = appendSection(nextFeature.workRemaining, featureUpdate.workRemaining);
     }
-    nextPhase.handoff = input.content.trim();
+    nextPhase.handoff = handoffContent;
     nextPhase.handoffUpdatedAt = 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() };
+            }),
+            entries: coldStartInventoryEntries,
+        },
+        supportingDocuments: input.verifiedSupportingDocuments ?? [],
+        contentHash: handoffContentHash(handoffContent),
+        contentLength: handoffContent.length,
+        verifiedAt: timestamp,
+        resumeReadyAt: "",
+        readBackSourceReviews: [],
+    };
     nextPhase.handoffReadAt = "";
     nextPhase.updatedAt = timestamp;
     nextFeature.updatedAt = timestamp;

package/dist/index.d.ts

@@ -4,14 +4,21 @@ export * from "./schema.js";
 export * from "./checklist.js";
 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";
 export * from "./read-tracking.js";
+export * from "./payload-fallback.js";
 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 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,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC/M,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

@@ -4,13 +4,20 @@ export * from "./schema.js";
 export * from "./checklist.js";
 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";
 export * from "./read-tracking.js";
+export * from "./payload-fallback.js";
 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/naming.d.ts

@@ -39,6 +39,8 @@ export declare function formatThreeDigitNumber(value: number): string;
 export declare function formatPhaseRef(phaseNumber: number, featureNumber?: number): string;
 /** Human-readable feature ref: `F00x`. Harness-agnostic. */
 export declare function formatFeatureRef(featureNumber: number): string;
+/** Human-readable idea ref: `I00x`. Ideas use an independent global sequence. */
+export declare function formatIdeaRef(ideaNumber: number): string;
 /** Find the parent feature's number for a phase (for P00x(F00x) composite refs). */
 export declare function featureNumberOfPhase(phase: {
     featureId?: string | null | undefined;
@@ -53,6 +55,7 @@ export declare function isLegacyPhaseId(phaseId: string): boolean;
 export declare function migratePhaseId(featureId: string, number: number, slug: string): string;
 export declare function createTaskId(): string;
 export declare function createRequirementId(): string;
+export declare function createIdeaId(): string;
 export declare function createMacroTaskId(): string;
 export declare function createFeatureId(): string;
 export declare function createChecklistItemId(taskId: string, number: number, title: string): string;

package/dist/naming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAKA;iFACiF;AACjF,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAErE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,YAAY,QAAoE,CAAC;AAE9F,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEtD;AAED;;gEAEgE;AAChE,wBAAsB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACnE,IAAI,EAAE,SAAS,GAAG,OAAO,EACzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACnC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAStD;AAGD;;;;;qCAKqC;AACrC,wBAAgB,aAAa,CAAC,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BtF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;8BAI8B;AAC9B,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAK,EAAE,QAAQ,SAAa,GAAG,MAAM,CAGnF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iBAEiB;AACjB,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,EAChD,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GACzC,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAKA;iFACiF;AACjF,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAErE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,YAAY,QAAoE,CAAC;AAE9F,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEtD;AAED;;gEAEgE;AAChE,wBAAsB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACnE,IAAI,EAAE,SAAS,GAAG,OAAO,EACzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACnC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAStD;AAGD;;;;;qCAKqC;AACrC,wBAAgB,aAAa,CAAC,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BtF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;8BAI8B;AAC9B,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAK,EAAE,QAAQ,SAAa,GAAG,MAAM,CAGnF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iBAEiB;AACjB,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,EAChD,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GACzC,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}

package/dist/naming.js

@@ -94,6 +94,10 @@ export function formatPhaseRef(phaseNumber, featureNumber) {
 export function formatFeatureRef(featureNumber) {
     return `F${formatThreeDigitNumber(featureNumber)}`;
 }
+/** Human-readable idea ref: `I00x`. Ideas use an independent global sequence. */
+export function formatIdeaRef(ideaNumber) {
+    return `I${formatThreeDigitNumber(ideaNumber)}`;
+}
 /** Find the parent feature's number for a phase (for P00x(F00x) composite refs). */
 export function featureNumberOfPhase(phase, features) {
     return phase.featureId ? features.find((f) => f.id === phase.featureId)?.number : undefined;
@@ -116,6 +120,9 @@ export function createTaskId() {
 export function createRequirementId() {
     return randomUUID();
 }
+export function createIdeaId() {
+    return randomUUID();
+}
 export function createMacroTaskId() {
     return randomUUID();
 }

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"}