@agent-plan/core 0.2.25 → 0.2.26

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,79 @@
-import type { Feature, Phase, Task } from "./schema.js";
+import type { Feature, HandoffCompletenessAudit, HandoffCompletenessEntry, HandoffSupportingDocument, Phase, Task } from "./schema.js";
 export declare const COMPLETION_SUMMARY_HEADING = "**Completion summary:**";
+export declare const HANDOFF_COMPLETENESS_AUDIT_VERSION = 1;
+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 type HandoffCompletenessCategory = typeof HANDOFF_COMPLETENESS_CATEGORIES[number]["id"];
+export type HandoffContractErrorCode = "HANDOFF_COMPLETENESS_AUDIT_REQUIRED" | "HANDOFF_CONTENT_LIMIT_EXCEEDED" | "HANDOFF_SUPPORTING_DOCUMENT_INVALID" | "HANDOFF_PERSISTENCE_VERIFICATION_FAILED";
+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 HandoffSupportingDocumentInput {
+    path: string;
+    description: string;
+}
 export interface HandoffTaskContextUpdate {
     taskId: string;
     completionSummary: string;
@@ -35,11 +109,22 @@ export interface PhaseHandoffAudit {
         number: number;
         title: string;
     }>;
+    completenessVersion: number;
+    maxContentChars: number;
+    completenessCategories: ReadonlyArray<{
+        id: HandoffCompletenessCategory;
+        label: string;
+    }>;
+    existingCompletenessAudit: HandoffCompletenessAudit | null;
 }
 export interface RefreshPhaseHandoffInput {
     content: string;
     expectedHandoffUpdatedAt: string;
     reconciledExistingHandoff: boolean;
+    completenessAudit?: HandoffCompletenessAuditInput;
+    supportingDocuments?: HandoffSupportingDocumentInput[];
+    /** Populated and verified by PlanStore before pure domain application. */
+    verifiedSupportingDocuments?: HandoffSupportingDocument[];
     contextSync: PhaseHandoffContextSync;
 }
 export interface RefreshPhaseHandoffResult {
@@ -47,9 +132,14 @@ export interface RefreshPhaseHandoffResult {
     feature: Feature;
     updatedTaskIds: string[];
     handoffUpdatedAt: string;
+    handoffAudit: HandoffCompletenessAudit;
 }
 export declare function hasTaskCompletionEvidence(task: Task): boolean;
 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 renderHandoffCompletenessAudit(audit: HandoffCompletenessAuditInput): string;
+export declare function renderVerifiedHandoffContent(content: string, audit?: HandoffCompletenessAuditInput): 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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"}

package/dist/handoff-context.js

@@ -1,4 +1,39 @@
+import { createHash } from "node:crypto";
 export const COMPLETION_SUMMARY_HEADING = "**Completion summary:**";
+export const HANDOFF_COMPLETENESS_AUDIT_VERSION = 1;
+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 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;
@@ -17,6 +52,10 @@ export function auditPhaseHandoff(phase, feature) {
         handoffUpdatedAt: phase.handoffUpdatedAt,
         missingCompletionTaskIds: missingCompletionTasks.map((task) => task.id),
         missingCompletionTasks,
+        completenessVersion: HANDOFF_COMPLETENESS_AUDIT_VERSION,
+        maxContentChars: MAX_HANDOFF_CONTENT_CHARS,
+        completenessCategories: HANDOFF_COMPLETENESS_CATEGORIES,
+        existingCompletenessAudit: phase.handoffAudit,
     };
 }
 function nonEmpty(value, field) {
@@ -34,6 +73,74 @@ 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 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) {
+    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 });
+    }
+    return rendered;
+}
 export function validateCanonicalHandoffContent(content) {
     const body = nonEmpty(content, "Handoff content");
     const required = [
@@ -53,7 +160,22 @@ export function validateCanonicalHandoffContent(content) {
         throw new Error(`Canonical handoff is missing required sections: ${missing.join(", ")}.`);
 }
 export function validateHandoffContextSync(phase, feature, input) {
-    validateCanonicalHandoffContent(input.content);
+    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 });
+    }
+    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 });
+        }
+    }
     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.`);
     }
@@ -100,6 +222,8 @@ 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 auditEntries = validateHandoffCompletenessAudit(input.completenessAudit);
     const nextPhase = structuredClone(phase);
     const nextFeature = structuredClone(feature);
     const updatedTaskIds = [];
@@ -141,8 +265,16 @@ 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,
+        supportingDocuments: input.verifiedSupportingDocuments ?? [],
+        contentHash: handoffContentHash(handoffContent),
+        contentLength: handoffContent.length,
+        verifiedAt: timestamp,
+    };
     nextPhase.handoffReadAt = "";
     nextPhase.updatedAt = timestamp;
     nextFeature.updatedAt = timestamp;

package/dist/index.d.ts

@@ -4,14 +4,18 @@ 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 "./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 { PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, type IdeaCreateInput, type IdeaUpdateInput, type IdeaPromotionTargetInput, 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,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"}

package/dist/index.js

@@ -4,12 +4,16 @@ 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 "./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 { PlanRenderer } from "./renderer.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/payload-fallback.d.ts

@@ -0,0 +1,38 @@
+export type PlannerPayloadEntity = "project" | "feature" | "phase" | "task";
+export type PlannerPayloadOperation = "update" | "discuss";
+export type PlannerPayloadFailureCode = "NO_MUTABLE_FIELDS_RECEIVED" | "DESCRIPTION_MARKDOWN_FALLBACK_REQUIRED";
+export interface DescriptionFallbackInput {
+    entityId?: string;
+    inputField: string;
+    storedField: string;
+    descriptionRefField: string;
+}
+export interface NoMutableFieldsReceivedInput {
+    entity: PlannerPayloadEntity;
+    ref: string;
+    operation: PlannerPayloadOperation;
+    mutableFields: readonly string[];
+    retryCommand: string;
+    readBackCommand?: string;
+    descriptionFallback?: DescriptionFallbackInput;
+}
+export interface NoMutableFieldsReceivedResult {
+    updated: false;
+    discussed?: false;
+    reason: "no-mutable-fields";
+    errorCode: PlannerPayloadFailureCode;
+    suspectedLongTextPayloadLoss: boolean;
+    entity: PlannerPayloadEntity;
+    ref: string;
+    operation: PlannerPayloadOperation;
+    mutableFields: string[];
+    fallbackDocPath?: string;
+    fallbackDescriptionTemplate?: string;
+    nextActions: string[];
+    message: string;
+}
+export declare function normalizeDescriptionRef(value: string | undefined): string | undefined;
+export declare function isPlannerDescriptionRef(value: string): boolean;
+export declare function suggestedDescriptionRefPath(entity: PlannerPayloadEntity, entityId?: string): string;
+export declare function noMutableFieldsReceived(input: NoMutableFieldsReceivedInput): NoMutableFieldsReceivedResult;
+//# sourceMappingURL=payload-fallback.d.ts.map

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

@@ -0,0 +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"}

package/dist/payload-fallback.js

@@ -0,0 +1,73 @@
+export function normalizeDescriptionRef(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function isPlannerDescriptionRef(value) {
+    if (!value.startsWith(".planner/docs/"))
+        return false;
+    if (value.includes("\\") || value.includes("\0"))
+        return false;
+    const parts = value.split("/");
+    if (parts.length < 4)
+        return false;
+    if (parts[0] !== ".planner" || parts[1] !== "docs")
+        return false;
+    return parts.slice(2).every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+export function suggestedDescriptionRefPath(entity, entityId) {
+    switch (entity) {
+        case "project":
+            return ".planner/docs/project/description.md";
+        case "feature":
+            return `.planner/docs/features/${entityId ?? "feature"}.md`;
+        case "phase":
+            return `.planner/docs/phases/${entityId ?? "phase"}.md`;
+        case "task":
+            return `.planner/docs/tasks/${entityId ?? "task"}.md`;
+    }
+}
+export function noMutableFieldsReceived(input) {
+    const mutableFields = [...input.mutableFields];
+    const fallbackDocPath = input.descriptionFallback
+        ? suggestedDescriptionRefPath(input.entity, input.descriptionFallback.entityId)
+        : undefined;
+    const nextActions = input.descriptionFallback && fallbackDocPath
+        ? [
+            `Create a committed markdown file at ${fallbackDocPath} containing the full intended ${input.descriptionFallback.storedField}.`,
+            `Retry ${input.retryCommand} with a concise ${input.descriptionFallback.inputField} summary and ${input.descriptionFallback.descriptionRefField} set to ${fallbackDocPath}.`,
+            ...(input.readBackCommand
+                ? [`Read back ${input.readBackCommand} and confirm the summary plus ${input.descriptionFallback.descriptionRefField} survived.`]
+                : []),
+            "Continue only after the read-back confirms the markdown reference persisted.",
+        ]
+        : [
+            `Retry ${input.retryCommand} with at least one mutable field: ${mutableFields.join(", ")}.`,
+        ];
+    const fallbackDescriptionTemplate = fallbackDocPath
+        ? `Concise summary here. Full description is stored in ${fallbackDocPath}.`
+        : undefined;
+    const message = [
+        "Not updated — no mutable fields were received.",
+        "No planner data was changed.",
+        input.descriptionFallback
+            ? `If you attempted to send a long ${input.descriptionFallback.inputField}, it may have exceeded the tool payload limit before reaching the planner.`
+            : `Provide at least one mutable field for this ${input.operation} operation.`,
+        "Next required actions:",
+        ...nextActions.map((action, index) => `${index + 1}. ${action}`),
+    ].join("\n");
+    return {
+        updated: false,
+        ...(input.operation === "discuss" ? { discussed: false } : {}),
+        reason: "no-mutable-fields",
+        errorCode: input.descriptionFallback ? "DESCRIPTION_MARKDOWN_FALLBACK_REQUIRED" : "NO_MUTABLE_FIELDS_RECEIVED",
+        suspectedLongTextPayloadLoss: Boolean(input.descriptionFallback),
+        entity: input.entity,
+        ref: input.ref,
+        operation: input.operation,
+        mutableFields,
+        ...(fallbackDocPath ? { fallbackDocPath } : {}),
+        ...(fallbackDescriptionTemplate ? { fallbackDescriptionTemplate } : {}),
+        nextActions,
+        message,
+    };
+}