@agent-plan/core 0.2.25 → 0.2.27

package/dist/description-freshness.d.ts

@@ -0,0 +1,37 @@
+import type { Feature, Phase } from "./schema.js";
+export type DescriptionFreshnessOwnerKind = "feature" | "phase";
+export type DescriptionFreshnessChildKind = "phase" | "task";
+export interface DescriptionFreshnessDiagnostic {
+    ownerKind: DescriptionFreshnessOwnerKind;
+    ownerId: string;
+    ownerRef: string;
+    state: "fresh" | "stale";
+    ownerDescriptionUpdatedAt: string;
+    newestChildKind: DescriptionFreshnessChildKind | null;
+    newestChildId: string;
+    newestChildRef: string;
+    newestChildDescriptionUpdatedAt: string;
+    reason: string;
+}
+export interface DescriptionReconciliationStep {
+    ownerKind: DescriptionFreshnessOwnerKind;
+    ownerId: string;
+    ownerRef: string;
+    causedByRef: string;
+    reason: string;
+    action: string;
+}
+export interface HierarchicalDescriptionFreshness {
+    diagnostics: DescriptionFreshnessDiagnostic[];
+    staleParentRefs: string[];
+    reconciliationRequired: boolean;
+    reconciliationPreview: DescriptionReconciliationStep[];
+}
+/**
+ * Compute child-to-parent description freshness without mutating user-authored
+ * prose. Reconciliation is intentionally leaf-to-root: stale phases first,
+ * then their owning features.
+ */
+export declare function buildHierarchicalDescriptionFreshness(features: Feature[], phases: Phase[]): HierarchicalDescriptionFreshness;
+export declare function freshnessForOwner(freshness: HierarchicalDescriptionFreshness, ownerKind: DescriptionFreshnessOwnerKind, ownerId: string): DescriptionFreshnessDiagnostic | undefined;
+//# sourceMappingURL=description-freshness.d.ts.map

package/dist/description-freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"description-freshness.d.ts","sourceRoot":"","sources":["../src/description-freshness.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAQ,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,6BAA6B,GAAG,SAAS,GAAG,OAAO,CAAC;AAChE,MAAM,MAAM,6BAA6B,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,6BAA6B,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,yBAAyB,EAAE,MAAM,CAAC;IAClC,eAAe,EAAE,6BAA6B,GAAG,IAAI,CAAC;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B,EAAE,MAAM,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,6BAA6B,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gCAAgC;IAC/C,WAAW,EAAE,8BAA8B,EAAE,CAAC;IAC9C,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,sBAAsB,EAAE,OAAO,CAAC;IAChC,qBAAqB,EAAE,6BAA6B,EAAE,CAAC;CACxD;AA2DD;;;;GAIG;AACH,wBAAgB,qCAAqC,CACnD,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,GACd,gCAAgC,CA0ClC;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,gCAAgC,EAC3C,SAAS,EAAE,6BAA6B,EACxC,OAAO,EAAE,MAAM,GACd,8BAA8B,GAAG,SAAS,CAE5C"}

package/dist/description-freshness.js

@@ -0,0 +1,84 @@
+import { formatFeatureRef, formatPhaseRef } from "./naming.js";
+function descriptionRevision(entity) {
+    if (!entity.description.trim() && !entity.descriptionRef?.trim())
+        return "";
+    return entity.descriptionUpdatedAt?.trim() || entity.createdAt;
+}
+function taskRef(task, phase, featureNumber) {
+    return `${formatPhaseRef(phase.number, featureNumber)}/T${String(task.number).padStart(3, "0")}`;
+}
+function newestChild(candidates) {
+    return candidates
+        .filter((candidate) => candidate.revision)
+        .sort((left, right) => right.revision.localeCompare(left.revision) || left.ref.localeCompare(right.ref))[0] ?? null;
+}
+function diagnostic(ownerKind, owner, ownerRef, child) {
+    const ownerRevision = descriptionRevision(owner);
+    const stale = child !== null && (!ownerRevision || child.revision > ownerRevision);
+    const reason = stale
+        ? `${ownerRef} description is older than ${child.ref}; review the child context and explicitly reconcile the parent description or descriptionRef.`
+        : child
+            ? `${ownerRef} description is at least as recent as its newest described child ${child.ref}.`
+            : `${ownerRef} has no described child context requiring reconciliation.`;
+    return {
+        ownerKind,
+        ownerId: owner.id,
+        ownerRef,
+        state: stale ? "stale" : "fresh",
+        ownerDescriptionUpdatedAt: ownerRevision,
+        newestChildKind: child?.kind ?? null,
+        newestChildId: child?.id ?? "",
+        newestChildRef: child?.ref ?? "",
+        newestChildDescriptionUpdatedAt: child?.revision ?? "",
+        reason,
+    };
+}
+/**
+ * Compute child-to-parent description freshness without mutating user-authored
+ * prose. Reconciliation is intentionally leaf-to-root: stale phases first,
+ * then their owning features.
+ */
+export function buildHierarchicalDescriptionFreshness(features, phases) {
+    const featureById = new Map(features.map((feature) => [feature.id, feature]));
+    const phaseDiagnostics = phases.map((phase) => {
+        const feature = phase.featureId ? featureById.get(phase.featureId) : undefined;
+        const ref = formatPhaseRef(phase.number, feature?.number);
+        const child = newestChild(phase.tasks.map((task) => ({
+            kind: "task",
+            id: task.id,
+            ref: taskRef(task, phase, feature?.number),
+            revision: descriptionRevision(task),
+        })));
+        return diagnostic("phase", phase, ref, child);
+    });
+    const featureDiagnostics = features.map((feature) => {
+        const ownedPhases = phases.filter((phase) => phase.featureId === feature.id);
+        const candidates = [];
+        for (const phase of ownedPhases) {
+            const phaseRef = formatPhaseRef(phase.number, feature.number);
+            candidates.push({ kind: "phase", id: phase.id, ref: phaseRef, revision: descriptionRevision(phase) });
+            for (const task of phase.tasks) {
+                candidates.push({ kind: "task", id: task.id, ref: taskRef(task, phase, feature.number), revision: descriptionRevision(task) });
+            }
+        }
+        return diagnostic("feature", feature, formatFeatureRef(feature.number), newestChild(candidates));
+    });
+    const diagnostics = [...phaseDiagnostics, ...featureDiagnostics];
+    const stale = diagnostics.filter((entry) => entry.state === "stale");
+    return {
+        diagnostics,
+        staleParentRefs: stale.map((entry) => entry.ownerRef),
+        reconciliationRequired: stale.length > 0,
+        reconciliationPreview: stale.map((entry) => ({
+            ownerKind: entry.ownerKind,
+            ownerId: entry.ownerId,
+            ownerRef: entry.ownerRef,
+            causedByRef: entry.newestChildRef,
+            reason: entry.reason,
+            action: `Read ${entry.newestChildRef}, review ${entry.ownerRef}, then explicitly update ${entry.ownerRef}'s description or descriptionRef if the parent prose is stale.`,
+        })),
+    };
+}
+export function freshnessForOwner(freshness, ownerKind, ownerId) {
+    return freshness.diagnostics.find((entry) => entry.ownerKind === ownerKind && entry.ownerId === ownerId);
+}

package/dist/display-status.d.ts

@@ -9,8 +9,8 @@
  * - `started`: the entity has clearly begun (historical progress exists) but
  *   no child is active now, and the unfinished remainder is mixed or cannot
  *   honestly collapse to one specific workflow label.
- * - `closed`: every child is terminal, but outcomes are mixed (e.g.
- *   `done + canceled`, `canceled + rejected`).
+ * - `closed`: every child is terminal, but outcomes are mixed without a
+ *   positive completion rollup (for example, `canceled + rejected`).
  *
  * These are NEVER persisted: they are computed on demand from children's
  * canonical workflow statuses. The canonical workflow model
@@ -62,7 +62,7 @@ export declare function countBreakdown(statuses: readonly WorkflowStatus[]): Sta
  * Algorithm (locked by P039 accepted decisions):
  *  1. If any meaningful child is active now → `in-progress`.
  *  2. If every child is terminal:
- *       - all `done` → `done`
+ *       - only `done` + `canceled`, with at least one `done` → `done`
  *       - all `canceled` → `canceled`
  *       - all `rejected` → `rejected`
  *       - otherwise → `closed` (mixed terminal outcomes)

package/dist/display-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"display-status.d.ts","sourceRoot":"","sources":["../src/display-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,aAAa,GACb,SAAS,GACT,SAAS,GACT,UAAU,GACV,MAAM,GACN,UAAU,GACV,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElE,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,aAAa,EAAE,aAAa,CAAC;IAC7B,wDAAwD;IACxD,SAAS,EAAE,eAAe,CAAC;IAC3B;+CAC2C;IAC3C,UAAU,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAMD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,eAAe,CAkBnF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,cAAc,EAAE,GAAG,aAAa,CAiE3F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAcrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CAIpF"}
+{"version":3,"file":"display-status.d.ts","sourceRoot":"","sources":["../src/display-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,aAAa,GACb,SAAS,GACT,SAAS,GACT,UAAU,GACV,MAAM,GACN,UAAU,GACV,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElE,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,aAAa,EAAE,aAAa,CAAC;IAC7B,wDAAwD;IACxD,SAAS,EAAE,eAAe,CAAC;IAC3B;+CAC2C;IAC3C,UAAU,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAMD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,eAAe,CAkBnF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,cAAc,EAAE,GAAG,aAAa,CAoE3F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAcrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CAIpF"}

package/dist/display-status.js

@@ -9,8 +9,8 @@
  * - `started`: the entity has clearly begun (historical progress exists) but
  *   no child is active now, and the unfinished remainder is mixed or cannot
  *   honestly collapse to one specific workflow label.
- * - `closed`: every child is terminal, but outcomes are mixed (e.g.
- *   `done + canceled`, `canceled + rejected`).
+ * - `closed`: every child is terminal, but outcomes are mixed without a
+ *   positive completion rollup (for example, `canceled + rejected`).
  *
  * These are NEVER persisted: they are computed on demand from children's
  * canonical workflow statuses. The canonical workflow model
@@ -65,7 +65,7 @@ function emptyBreakdown() {
  * Algorithm (locked by P039 accepted decisions):
  *  1. If any meaningful child is active now → `in-progress`.
  *  2. If every child is terminal:
- *       - all `done` → `done`
+ *       - only `done` + `canceled`, with at least one `done` → `done`
  *       - all `canceled` → `canceled`
  *       - all `rejected` → `rejected`
  *       - otherwise → `closed` (mixed terminal outcomes)
@@ -108,7 +108,8 @@ export function deriveParentDisplay(childStatuses) {
     }
     // 2. All children are terminal.
     if (statuses.every((s) => TERMINAL.has(s))) {
-        if (statuses.every((s) => s === "done")) {
+        if (statuses.some((s) => s === "done")
+            && statuses.every((s) => s === "done" || s === "canceled")) {
             return { displayStatus: "done", breakdown, hasStarted, totalChildren, meaningfulChildren };
         }
         if (statuses.every((s) => s === "canceled")) {

package/dist/handoff-context.d.ts

@@ -1,5 +1,157 @@
-import type { Feature, Phase, Task } from "./schema.js";
+import type { Feature, HandoffCompletenessAudit, HandoffCompletenessEntry, HandoffColdStartInventoryEntry, HandoffSupportingDocument, Phase, Task } from "./schema.js";
+import { type PhaseWorkMap } from "./task-context.js";
 export declare const COMPLETION_SUMMARY_HEADING = "**Completion summary:**";
+export declare const HANDOFF_COMPLETENESS_AUDIT_VERSION = 1;
+export declare const HANDOFF_COLD_START_INVENTORY_VERSION = 1;
+export declare const TARGET_HANDOFF_CONTENT_CHARS = 8000;
+export declare const MAX_HANDOFF_CONTENT_CHARS = 24000;
+export declare const HANDOFF_AUDIT_START_MARKER = "<!-- agent-plan:handoff-audit:start -->";
+export declare const HANDOFF_AUDIT_END_MARKER = "<!-- agent-plan:handoff-audit:end -->";
+export declare const HANDOFF_COMPLETENESS_CATEGORIES: readonly [{
+    readonly id: "exact-focus-resume-point";
+    readonly label: "Exact focus and resume point";
+}, {
+    readonly id: "first-resume-action";
+    readonly label: "First resume action";
+}, {
+    readonly id: "completed-work";
+    readonly label: "Completed work";
+}, {
+    readonly id: "partial-work";
+    readonly label: "Partial work";
+}, {
+    readonly id: "remaining-work";
+    readonly label: "Remaining work";
+}, {
+    readonly id: "decisions-rationale";
+    readonly label: "Decisions and rationale";
+}, {
+    readonly id: "rejected-alternatives";
+    readonly label: "Rejected alternatives";
+}, {
+    readonly id: "files-symbols";
+    readonly label: "Files and symbols";
+}, {
+    readonly id: "branch-worktree";
+    readonly label: "Branch and worktree";
+}, {
+    readonly id: "commands-tools";
+    readonly label: "Commands and tools";
+}, {
+    readonly id: "completed-verification";
+    readonly label: "Completed verification";
+}, {
+    readonly id: "pending-verification";
+    readonly label: "Pending verification";
+}, {
+    readonly id: "runtime-limitations-workarounds";
+    readonly label: "Runtime limitations and workarounds";
+}, {
+    readonly id: "blockers-risks";
+    readonly label: "Blockers and risks";
+}, {
+    readonly id: "user-visible-behavior";
+    readonly label: "User-visible behavior";
+}, {
+    readonly id: "operator-actions";
+    readonly label: "Operator actions";
+}, {
+    readonly id: "project-operating-notes";
+    readonly label: "Project-specific operating notes";
+}, {
+    readonly id: "conversation-only-facts";
+    readonly label: "Conversation-only facts";
+}];
+export declare const HANDOFF_COLD_START_SOURCE_REVIEWS: readonly [{
+    readonly id: "conversation";
+    readonly label: "Conversation, user corrections, and authorization state";
+}, {
+    readonly id: "planner-entities";
+    readonly label: "Task, sibling tasks, phase, feature, requirements, and prior handoff";
+}, {
+    readonly id: "working-tree";
+    readonly label: "Changed files, diffs, implementation state, and ownership";
+}, {
+    readonly id: "verification-runtime";
+    readonly label: "Commands, test results, runtime observations, and limitations";
+}, {
+    readonly id: "peer-agent-output";
+    readonly label: "Peer-agent messages and delegated-work results, or confirmation that none exist";
+}];
+export declare const HANDOFF_COLD_START_INVENTORY_CATEGORIES: readonly [{
+    readonly id: "files";
+    readonly label: "Exact files";
+}, {
+    readonly id: "symbols";
+    readonly label: "Exact symbols and identifiers";
+}, {
+    readonly id: "working-tree-ownership";
+    readonly label: "Working-tree state, work ownership, and commit/discard authorization";
+}, {
+    readonly id: "negative-state";
+    readonly label: "Work not started, removals not performed, and intentionally untouched state";
+}, {
+    readonly id: "commands-tools";
+    readonly label: "Commands and tool paths";
+}, {
+    readonly id: "runtime-wiring";
+    readonly label: "Runtime wiring, call sites, and data flow";
+}, {
+    readonly id: "preservation-constraints";
+    readonly label: "Behavior and code paths that must survive";
+}, {
+    readonly id: "verification-evidence";
+    readonly label: "Concrete observations proving completed, live, dead, or inert state";
+}, {
+    readonly id: "related-planned-work";
+    readonly label: "Sibling tasks and related planned capabilities";
+}, {
+    readonly id: "user-visible-behavior";
+    readonly label: "User-visible behavior";
+}, {
+    readonly id: "operator-actions";
+    readonly label: "Operator actions";
+}, {
+    readonly id: "blockers-risks";
+    readonly label: "Blockers and risks";
+}, {
+    readonly id: "remaining-work";
+    readonly label: "Remaining work";
+}, {
+    readonly id: "ordered-resume-steps";
+    readonly label: "Ordered resume steps";
+}];
+export declare const HANDOFF_CANONICAL_SECTIONS: readonly ["Current focus", "Current and partial state", "Preservation constraints", "Supporting documents", "Blockers and risks", "How to resume"];
+export type HandoffCompletenessCategory = typeof HANDOFF_COMPLETENESS_CATEGORIES[number]["id"];
+export type HandoffColdStartInventoryCategory = typeof HANDOFF_COLD_START_INVENTORY_CATEGORIES[number]["id"];
+export type HandoffContractErrorCode = "HANDOFF_PREFLIGHT_REQUIRED" | "HANDOFF_REASON_REQUIRED" | "HANDOFF_CANONICAL_SECTIONS_REQUIRED" | "HANDOFF_COMPLETENESS_AUDIT_REQUIRED" | "HANDOFF_COLD_START_INVENTORY_REQUIRED" | "HANDOFF_COLD_START_INVENTORY_UNCOVERED" | "HANDOFF_CONTENT_LIMIT_EXCEEDED" | "HANDOFF_SUPPORTING_DOCUMENT_INVALID" | "HANDOFF_PERSISTENCE_VERIFICATION_FAILED" | "HANDOFF_READBACK_VERIFICATION_REQUIRED" | "HANDOFF_READBACK_GAPS_FOUND";
+export declare class HandoffContractError extends Error {
+    readonly code: HandoffContractErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: HandoffContractErrorCode, message: string, details?: Record<string, unknown>);
+}
+export interface HandoffCompletenessAuditInput {
+    version: number;
+    entries: HandoffCompletenessEntry[];
+}
+export interface HandoffColdStartInventoryInput {
+    version: number;
+    sourceReviews: Array<{
+        source: string;
+        detail: string;
+    }>;
+    entries: HandoffColdStartInventoryEntry[];
+}
+export interface HandoffSupportingDocumentInput {
+    path: string;
+    description: string;
+}
+export interface HandoffContentExternalization {
+    content: string;
+    externalized: boolean;
+    extendedContent: string;
+    supportingDocument?: HandoffSupportingDocumentInput;
+}
 export interface HandoffTaskContextUpdate {
     taskId: string;
     completionSummary: string;
@@ -35,11 +187,45 @@ export interface PhaseHandoffAudit {
         number: number;
         title: string;
     }>;
+    completenessVersion: number;
+    targetContentChars: number;
+    maxContentChars: number;
+    completenessCategories: ReadonlyArray<{
+        id: HandoffCompletenessCategory;
+        label: string;
+    }>;
+    canonicalSections: ReadonlyArray<string>;
+    requiredHumanInputs: ReadonlyArray<{
+        id: "title" | "reason";
+        label: string;
+        description: string;
+    }>;
+    draftTemplate: string;
+    coldStartInventoryVersion: number;
+    coldStartSourceReviews: ReadonlyArray<{
+        id: string;
+        label: string;
+    }>;
+    coldStartInventoryCategories: ReadonlyArray<{
+        id: HandoffColdStartInventoryCategory;
+        label: string;
+    }>;
+    existingCompletenessAudit: HandoffCompletenessAudit | null;
+    phaseWorkMap: PhaseWorkMap;
 }
 export interface RefreshPhaseHandoffInput {
+    /** Structured, human-supplied explanation; rendered by the planner. */
+    reason: string;
     content: string;
     expectedHandoffUpdatedAt: string;
     reconciledExistingHandoff: boolean;
+    completenessAudit?: HandoffCompletenessAuditInput;
+    coldStartInventory?: HandoffColdStartInventoryInput;
+    supportingDocuments?: HandoffSupportingDocumentInput[];
+    /** Populated and verified by PlanStore before pure domain application. */
+    verifiedSupportingDocuments?: HandoffSupportingDocument[];
+    /** Content is kept in-memory only for cold-start coverage validation. */
+    verifiedSupportingDocumentContents?: string[];
     contextSync: PhaseHandoffContextSync;
 }
 export interface RefreshPhaseHandoffResult {
@@ -47,9 +233,44 @@ export interface RefreshPhaseHandoffResult {
     feature: Feature;
     updatedTaskIds: string[];
     handoffUpdatedAt: string;
+    handoffAudit: HandoffCompletenessAudit;
+}
+export interface VerifyPhaseHandoffReadBackInput {
+    expectedContentHash: string;
+    sourceReviews: Array<{
+        source: string;
+        detail: string;
+    }>;
+    omissionsFound: string[];
+}
+export interface VerifyPhaseHandoffReadBackResult {
+    phaseId: string;
+    handoffUpdatedAt: string;
+    contentHash: string;
+    resumeReadyAt: string;
+    sourceReviews: Array<{
+        source: string;
+        detail: string;
+    }>;
 }
 export declare function hasTaskCompletionEvidence(task: Task): boolean;
+export declare function buildHandoffDraftTemplate(phase: Phase, feature: Feature): string;
 export declare function auditPhaseHandoff(phase: Phase, feature: Feature): PhaseHandoffAudit;
+export declare function handoffContentHash(content: string): string;
+export declare function validateHandoffCompletenessAudit(audit: HandoffCompletenessAuditInput | undefined): HandoffCompletenessEntry[];
+export declare function validateHandoffColdStartInventory(inventory: HandoffColdStartInventoryInput | undefined, content: string, supportingDocumentContents?: string[]): HandoffColdStartInventoryEntry[];
+export declare function validateHandoffReadBackVerification(phase: Phase, input: VerifyPhaseHandoffReadBackInput): Array<{
+    source: string;
+    detail: string;
+}>;
+/**
+ * Mechanically compact oversized legacy or verbose handoffs while retaining the
+ * complete submitted body in one planner-owned Markdown document.
+ */
+export declare function externalizeOversizedHandoffContent(content: string, supportingDocumentPath: string): HandoffContentExternalization;
+export declare function renderHandoffCompletenessAudit(audit: HandoffCompletenessAuditInput): string;
+export declare function renderVerifiedHandoffContent(content: string, audit?: HandoffCompletenessAuditInput, coldStartInventory?: HandoffColdStartInventoryInput, supportingDocumentContents?: string[]): string;
+export declare function materializeHandoffMetadata(content: string, reason: string, createdAt: string, updatedAt: string): string;
 export declare function validateCanonicalHandoffContent(content: string): void;
 export declare function validateHandoffContextSync(phase: Phase, feature: Feature, input: RefreshPhaseHandoffInput): void;
 export declare function applyHandoffContextSync(phase: Phase, feature: Feature, input: RefreshPhaseHandoffInput, timestamp: string): {

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

@@ -1 +1 @@
-{"version":3,"file":"handoff-context.d.ts","sourceRoot":"","sources":["../src/handoff-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExD,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AAEpE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,2BAA2B,CAAC;IAC5C,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,sBAAsB,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB,EAAE,MAAM,CAAC;IACjC,yBAAyB,EAAE,OAAO,CAAC;IACnC,WAAW,EAAE,uBAAuB,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAI7D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAYnF;AAkBD,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAgBrE;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,wBAAwB,GAC9B,IAAI,CA4CN;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,wBAAwB,EAC/B,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,CAqD9D"}
+{"version":3,"file":"handoff-context.d.ts","sourceRoot":"","sources":["../src/handoff-context.ts"],"names":[],"mappings":"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"}