@agent-plan/core 0.2.19-next.2 → 0.2.19-next.20

package/dist/schema.d.ts

@@ -133,6 +133,10 @@ export declare const ResumeFocusSchema: z.ZodObject<{
     currentPhaseId: z.ZodDefault<z.ZodString>;
     inProgressTaskIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     nextSteps: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** When `nextSteps` last changed (free-text can go stale; the recap surfaces
+     *  this so staleness is visible). Preserved across refreshResume (which keeps
+     *  existing nextSteps); bumped only when saveResume receives new nextSteps. */
+    nextStepsUpdatedAt: z.ZodDefault<z.ZodString>;
     blockers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     notes: z.ZodDefault<z.ZodString>;
     lastSessionSummary: z.ZodDefault<z.ZodString>;
@@ -142,6 +146,7 @@ export declare const ResumeFocusSchema: z.ZodObject<{
     currentPhaseId: string;
     inProgressTaskIds: string[];
     nextSteps: string[];
+    nextStepsUpdatedAt: string;
     blockers: string[];
     notes: string;
     lastSessionSummary: string;
@@ -151,6 +156,7 @@ export declare const ResumeFocusSchema: z.ZodObject<{
     currentPhaseId?: string | undefined;
     inProgressTaskIds?: string[] | undefined;
     nextSteps?: string[] | undefined;
+    nextStepsUpdatedAt?: string | undefined;
     blockers?: string[] | undefined;
     notes?: string | undefined;
     lastSessionSummary?: string | undefined;
@@ -314,6 +320,10 @@ export declare const ProjectSchema: z.ZodObject<{
         rationale?: string | undefined;
         implementationNotes?: string | undefined;
     }>, "many">>;
+    /** Monotonic global sequence counters — assigned at creation, never reused (gaps on delete). */
+    nextFeatureNumber: z.ZodDefault<z.ZodNumber>;
+    nextPhaseNumber: z.ZodDefault<z.ZodNumber>;
+    nextTaskNumber: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     goal: string;
@@ -340,6 +350,9 @@ export declare const ProjectSchema: z.ZodObject<{
         implementationNotes: string;
         acceptedAt: string;
     }[];
+    nextFeatureNumber: number;
+    nextPhaseNumber: number;
+    nextTaskNumber: number;
 }, {
     name: string;
     workflowRules: {
@@ -366,6 +379,9 @@ export declare const ProjectSchema: z.ZodObject<{
         rationale?: string | undefined;
         implementationNotes?: string | undefined;
     }[] | undefined;
+    nextFeatureNumber?: number | undefined;
+    nextPhaseNumber?: number | undefined;
+    nextTaskNumber?: number | undefined;
 }>;
 export declare const SubtaskStatusSchema: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
 export declare const TaskStatusSchema: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
@@ -396,15 +412,21 @@ export declare const SubtaskSchema: z.ZodObject<{
 }>;
 export declare const ChecklistItemSchema: z.ZodObject<{
     id: z.ZodString;
+    /** Per-task 1-based position, displayed as C{number} (C1, C2, ...). Default 0
+     *  so legacy on-disk items without a number still parse; the TaskSchema
+     *  transform overwrites it with the real index+1. */
+    number: z.ZodDefault<z.ZodNumber>;
     title: z.ZodString;
     checked: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
+    number: number;
     id: string;
     title: string;
     checked: boolean;
 }, {
     id: string;
     title: string;
+    number?: number | undefined;
     checked?: boolean | undefined;
 }>;
 /** Status transitions that require a motivation note from the agent. */
@@ -438,9 +460,36 @@ export declare const StatusLogEntrySchema: z.ZodObject<{
     toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
     description?: string | undefined;
 }>;
+/** Like StatusLogEntrySchema but for the DERIVED PHASE status, which includes
+ *  the "draft" and "discovery" lifecycle states absent from TaskStatus. */
+export declare const PhaseStatusLogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    date: z.ZodString;
+    fromStatus: z.ZodEnum<["draft", "discovery", "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+    toStatus: z.ZodEnum<["draft", "discovery", "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+    title: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    date: string;
+    title: string;
+    description: string;
+    fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+    toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+}, {
+    id: string;
+    date: string;
+    title: string;
+    fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+    toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+    description?: string | undefined;
+}>;
 export declare const TaskSchema: z.ZodEffects<z.ZodObject<{
     id: z.ZodString;
+    /** MUST be a phase UUID (not a ref like "P003"). Validated at the schema
+     *  layer so no adapter can persist an unresolved ref string. */
     phaseId: z.ZodString;
+    /** Global project-wide task sequence (assigned once at creation from project.nextTaskNumber; stable, gaps on delete). Bare T00x is unambiguous. */
     number: z.ZodDefault<z.ZodNumber>;
     shortId: z.ZodDefault<z.ZodString>;
     priority: z.ZodDefault<z.ZodNumber>;
@@ -496,15 +545,21 @@ export declare const TaskSchema: z.ZodEffects<z.ZodObject<{
     }>, "many">>;
     checklist: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
         id: z.ZodString;
+        /** Per-task 1-based position, displayed as C{number} (C1, C2, ...). Default 0
+         *  so legacy on-disk items without a number still parse; the TaskSchema
+         *  transform overwrites it with the real index+1. */
+        number: z.ZodDefault<z.ZodNumber>;
         title: z.ZodString;
         checked: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
+        number: number;
         id: string;
         title: string;
         checked: boolean;
     }, {
         id: string;
         title: string;
+        number?: number | undefined;
         checked?: boolean | undefined;
     }>]>, "many">>;
     subtasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -565,6 +620,7 @@ export declare const TaskSchema: z.ZodEffects<z.ZodObject<{
         toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
     }[];
     checklist: (string | {
+        number: number;
         id: string;
         title: string;
         checked: boolean;
@@ -613,6 +669,7 @@ export declare const TaskSchema: z.ZodEffects<z.ZodObject<{
     checklist?: (string | {
         id: string;
         title: string;
+        number?: number | undefined;
         checked?: boolean | undefined;
     })[] | undefined;
     subtasks?: {
@@ -629,6 +686,7 @@ export declare const TaskSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     checklist: {
         id: string;
+        number: number;
         title: string;
         checked: boolean;
     }[];
@@ -705,6 +763,7 @@ export declare const TaskSchema: z.ZodEffects<z.ZodObject<{
     checklist?: (string | {
         id: string;
         title: string;
+        number?: number | undefined;
         checked?: boolean | undefined;
     })[] | undefined;
     subtasks?: {
@@ -719,9 +778,28 @@ export declare const TaskSchema: z.ZodEffects<z.ZodObject<{
     startedAt?: string | undefined;
     completedAt?: string | undefined;
 }>;
+export declare const HandoffHistoryEntrySchema: z.ZodObject<{
+    /** Relative path under .planner/.local/handoff-archive/ (e.g. <phaseId>-<ISO>.md). */
+    file: z.ZodDefault<z.ZodString>;
+    clearedAt: z.ZodString;
+    /** Why the handoff was cleared: "task-started" | "phase-done" | "manual" | "superseded" | "imported". */
+    reason: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    clearedAt: string;
+    reason: string;
+}, {
+    clearedAt: string;
+    file?: string | undefined;
+    reason?: string | undefined;
+}>;
 export declare const PhaseSchema: z.ZodObject<{
     id: z.ZodString;
+    /** MUST be a feature UUID (not a ref like "F005"). Validated at the schema
+     *  layer so no adapter can persist an unresolved ref string. Optional only
+     *  for legacy pre-feature phases. */
     featureId: z.ZodOptional<z.ZodString>;
+    /** Global project-wide phase sequence (assigned once at creation from project.nextPhaseNumber; stable, gaps on delete). Bare P00x is unambiguous. */
     number: z.ZodNumber;
     shortId: z.ZodDefault<z.ZodString>;
     priority: z.ZodDefault<z.ZodNumber>;
@@ -766,7 +844,10 @@ export declare const PhaseSchema: z.ZodObject<{
     taskIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     tasks: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
         id: z.ZodString;
+        /** MUST be a phase UUID (not a ref like "P003"). Validated at the schema
+         *  layer so no adapter can persist an unresolved ref string. */
         phaseId: z.ZodString;
+        /** Global project-wide task sequence (assigned once at creation from project.nextTaskNumber; stable, gaps on delete). Bare T00x is unambiguous. */
         number: z.ZodDefault<z.ZodNumber>;
         shortId: z.ZodDefault<z.ZodString>;
         priority: z.ZodDefault<z.ZodNumber>;
@@ -822,15 +903,21 @@ export declare const PhaseSchema: z.ZodObject<{
         }>, "many">>;
         checklist: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
             id: z.ZodString;
+            /** Per-task 1-based position, displayed as C{number} (C1, C2, ...). Default 0
+             *  so legacy on-disk items without a number still parse; the TaskSchema
+             *  transform overwrites it with the real index+1. */
+            number: z.ZodDefault<z.ZodNumber>;
             title: z.ZodString;
             checked: z.ZodDefault<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
+            number: number;
             id: string;
             title: string;
             checked: boolean;
         }, {
             id: string;
             title: string;
+            number?: number | undefined;
             checked?: boolean | undefined;
         }>]>, "many">>;
         subtasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -891,6 +978,7 @@ export declare const PhaseSchema: z.ZodObject<{
             toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
         }[];
         checklist: (string | {
+            number: number;
             id: string;
             title: string;
             checked: boolean;
@@ -939,6 +1027,7 @@ export declare const PhaseSchema: z.ZodObject<{
         checklist?: (string | {
             id: string;
             title: string;
+            number?: number | undefined;
             checked?: boolean | undefined;
         })[] | undefined;
         subtasks?: {
@@ -955,6 +1044,7 @@ export declare const PhaseSchema: z.ZodObject<{
     }>, {
         checklist: {
             id: string;
+            number: number;
             title: string;
             checked: boolean;
         }[];
@@ -1031,6 +1121,7 @@ export declare const PhaseSchema: z.ZodObject<{
         checklist?: (string | {
             id: string;
             title: string;
+            number?: number | undefined;
             checked?: boolean | undefined;
         })[] | undefined;
         subtasks?: {
@@ -1049,6 +1140,53 @@ export declare const PhaseSchema: z.ZodObject<{
     updatedAt: z.ZodString;
     handoff: z.ZodDefault<z.ZodString>;
     handoffUpdatedAt: z.ZodDefault<z.ZodString>;
+    /** When the handoff was last read/acknowledged on recap (ISO). Non-empty means
+     *  the agent has seen it; the recap won't re-prompt every turn. The handoff
+     *  content is KEPT until a task in the phase starts (auto-clear) or the phase
+     *  completes — so a restart between read and resume does not lose context. */
+    handoffReadAt: z.ZodDefault<z.ZodString>;
+    /** Metadata for recently-cleared handoffs (newest-first, capped at 5). The
+     *  full content lives as .md files in .planner/.local/handoff-archive/ (gitignored);
+     *  this array only holds the pointer + clear reason + timestamp, so the phase
+     *  JSON stays lean and the archive is recoverable. */
+    handoffHistory: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Relative path under .planner/.local/handoff-archive/ (e.g. <phaseId>-<ISO>.md). */
+        file: z.ZodDefault<z.ZodString>;
+        clearedAt: z.ZodString;
+        /** Why the handoff was cleared: "task-started" | "phase-done" | "manual" | "superseded" | "imported". */
+        reason: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        clearedAt: string;
+        reason: string;
+    }, {
+        clearedAt: string;
+        file?: string | undefined;
+        reason?: string | undefined;
+    }>, "many">>;
+    /** Chronological audit trail of the DERIVED status (planned/in-progress/blocked/done/...). Appended ONLY when the derived status changes during a rollup; `status` itself is NOT persisted (still computed from child tasks at read time). Empty = no transition recorded yet (treated as "planned"). */
+    statusLog: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        date: z.ZodString;
+        fromStatus: z.ZodEnum<["draft", "discovery", "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+        toStatus: z.ZodEnum<["draft", "discovery", "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+        title: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        date: string;
+        title: string;
+        description: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+    }, {
+        id: string;
+        date: string;
+        title: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        description?: string | undefined;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     number: number;
     dependencies: string[];
@@ -1070,6 +1208,14 @@ export declare const PhaseSchema: z.ZodObject<{
     }[];
     shortId: string;
     priority: number;
+    statusLog: {
+        id: string;
+        date: string;
+        title: string;
+        description: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+    }[];
     dependsOn: string[];
     slug: string;
     discussedAt: string;
@@ -1084,6 +1230,7 @@ export declare const PhaseSchema: z.ZodObject<{
     tasks: {
         checklist: {
             id: string;
+            number: number;
             title: string;
             checked: boolean;
         }[];
@@ -1130,6 +1277,12 @@ export declare const PhaseSchema: z.ZodObject<{
     }[];
     handoff: string;
     handoffUpdatedAt: string;
+    handoffReadAt: string;
+    handoffHistory: {
+        file: string;
+        clearedAt: string;
+        reason: string;
+    }[];
     featureId?: string | undefined;
 }, {
     number: number;
@@ -1153,6 +1306,14 @@ export declare const PhaseSchema: z.ZodObject<{
     }[] | undefined;
     shortId?: string | undefined;
     priority?: number | undefined;
+    statusLog?: {
+        id: string;
+        date: string;
+        title: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        description?: string | undefined;
+    }[] | undefined;
     dependsOn?: string[] | undefined;
     featureId?: string | undefined;
     discussedAt?: string | undefined;
@@ -1197,6 +1358,7 @@ export declare const PhaseSchema: z.ZodObject<{
         checklist?: (string | {
             id: string;
             title: string;
+            number?: number | undefined;
             checked?: boolean | undefined;
         })[] | undefined;
         subtasks?: {
@@ -1213,9 +1375,16 @@ export declare const PhaseSchema: z.ZodObject<{
     }[] | undefined;
     handoff?: string | undefined;
     handoffUpdatedAt?: string | undefined;
+    handoffReadAt?: string | undefined;
+    handoffHistory?: {
+        clearedAt: string;
+        file?: string | undefined;
+        reason?: string | undefined;
+    }[] | undefined;
 }>;
 export declare const FeatureSchema: z.ZodObject<{
     id: z.ZodString;
+    /** Global project-wide feature sequence (assigned once at creation from project.nextFeatureNumber; stable, gaps on delete). */
     number: z.ZodDefault<z.ZodNumber>;
     shortId: z.ZodDefault<z.ZodString>;
     priority: z.ZodDefault<z.ZodNumber>;
@@ -1252,6 +1421,29 @@ export declare const FeatureSchema: z.ZodObject<{
     }>, "many">>;
     phaseIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Chronological audit trail of the DERIVED status (computed from child phases at read time). Appended ONLY when the derived status changes during a rollup; `status` itself is NOT persisted. Empty = no transition recorded yet (treated as "planned"). */
+    statusLog: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        date: z.ZodString;
+        fromStatus: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+        toStatus: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+        title: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        date: string;
+        title: string;
+        description: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+    }, {
+        id: string;
+        date: string;
+        title: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        description?: string | undefined;
+    }>, "many">>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -1271,6 +1463,14 @@ export declare const FeatureSchema: z.ZodObject<{
     }[];
     shortId: string;
     priority: number;
+    statusLog: {
+        id: string;
+        date: string;
+        title: string;
+        description: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+    }[];
     dependsOn: string[];
     discussedAt: string;
     contextReady: boolean;
@@ -1297,6 +1497,14 @@ export declare const FeatureSchema: z.ZodObject<{
     }[] | undefined;
     shortId?: string | undefined;
     priority?: number | undefined;
+    statusLog?: {
+        id: string;
+        date: string;
+        title: string;
+        fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        description?: string | undefined;
+    }[] | undefined;
     dependsOn?: string[] | undefined;
     discussedAt?: string | undefined;
     contextReady?: boolean | undefined;
@@ -1310,6 +1518,7 @@ export declare const FeatureSchema: z.ZodObject<{
 export declare const FeaturesDocumentSchema: z.ZodObject<{
     features: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        /** Global project-wide feature sequence (assigned once at creation from project.nextFeatureNumber; stable, gaps on delete). */
         number: z.ZodDefault<z.ZodNumber>;
         shortId: z.ZodDefault<z.ZodString>;
         priority: z.ZodDefault<z.ZodNumber>;
@@ -1346,6 +1555,29 @@ export declare const FeaturesDocumentSchema: z.ZodObject<{
         }>, "many">>;
         phaseIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Chronological audit trail of the DERIVED status (computed from child phases at read time). Appended ONLY when the derived status changes during a rollup; `status` itself is NOT persisted. Empty = no transition recorded yet (treated as "planned"). */
+        statusLog: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            date: z.ZodString;
+            fromStatus: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+            toStatus: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+            title: z.ZodString;
+            description: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            date: string;
+            title: string;
+            description: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        }, {
+            id: string;
+            date: string;
+            title: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            description?: string | undefined;
+        }>, "many">>;
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
@@ -1365,6 +1597,14 @@ export declare const FeaturesDocumentSchema: z.ZodObject<{
         }[];
         shortId: string;
         priority: number;
+        statusLog: {
+            id: string;
+            date: string;
+            title: string;
+            description: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        }[];
         dependsOn: string[];
         discussedAt: string;
         contextReady: boolean;
@@ -1391,6 +1631,14 @@ export declare const FeaturesDocumentSchema: z.ZodObject<{
         }[] | undefined;
         shortId?: string | undefined;
         priority?: number | undefined;
+        statusLog?: {
+            id: string;
+            date: string;
+            title: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            description?: string | undefined;
+        }[] | undefined;
         dependsOn?: string[] | undefined;
         discussedAt?: string | undefined;
         contextReady?: boolean | undefined;
@@ -1419,6 +1667,14 @@ export declare const FeaturesDocumentSchema: z.ZodObject<{
         }[];
         shortId: string;
         priority: number;
+        statusLog: {
+            id: string;
+            date: string;
+            title: string;
+            description: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+        }[];
         dependsOn: string[];
         discussedAt: string;
         contextReady: boolean;
@@ -1447,6 +1703,14 @@ export declare const FeaturesDocumentSchema: z.ZodObject<{
         }[] | undefined;
         shortId?: string | undefined;
         priority?: number | undefined;
+        statusLog?: {
+            id: string;
+            date: string;
+            title: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            description?: string | undefined;
+        }[] | undefined;
         dependsOn?: string[] | undefined;
         discussedAt?: string | undefined;
         contextReady?: boolean | undefined;
@@ -1712,6 +1976,10 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             rationale?: string | undefined;
             implementationNotes?: string | undefined;
         }>, "many">>;
+        /** Monotonic global sequence counters — assigned at creation, never reused (gaps on delete). */
+        nextFeatureNumber: z.ZodDefault<z.ZodNumber>;
+        nextPhaseNumber: z.ZodDefault<z.ZodNumber>;
+        nextTaskNumber: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         goal: string;
@@ -1738,6 +2006,9 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             implementationNotes: string;
             acceptedAt: string;
         }[];
+        nextFeatureNumber: number;
+        nextPhaseNumber: number;
+        nextTaskNumber: number;
     }, {
         name: string;
         workflowRules: {
@@ -1764,10 +2035,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             rationale?: string | undefined;
             implementationNotes?: string | undefined;
         }[] | undefined;
+        nextFeatureNumber?: number | undefined;
+        nextPhaseNumber?: number | undefined;
+        nextTaskNumber?: number | undefined;
     }>;
     features: z.ZodObject<{
         features: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
+            /** Global project-wide feature sequence (assigned once at creation from project.nextFeatureNumber; stable, gaps on delete). */
             number: z.ZodDefault<z.ZodNumber>;
             shortId: z.ZodDefault<z.ZodString>;
             priority: z.ZodDefault<z.ZodNumber>;
@@ -1804,6 +2079,29 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }>, "many">>;
             phaseIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
             dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            /** Chronological audit trail of the DERIVED status (computed from child phases at read time). Appended ONLY when the derived status changes during a rollup; `status` itself is NOT persisted. Empty = no transition recorded yet (treated as "planned"). */
+            statusLog: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                date: z.ZodString;
+                fromStatus: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+                toStatus: z.ZodEnum<["planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+                title: z.ZodString;
+                description: z.ZodDefault<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                id: string;
+                date: string;
+                title: string;
+                description: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            }, {
+                id: string;
+                date: string;
+                title: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                description?: string | undefined;
+            }>, "many">>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
         }, "strip", z.ZodTypeAny, {
@@ -1823,6 +2121,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }[];
             shortId: string;
             priority: number;
+            statusLog: {
+                id: string;
+                date: string;
+                title: string;
+                description: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            }[];
             dependsOn: string[];
             discussedAt: string;
             contextReady: boolean;
@@ -1849,6 +2155,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }[] | undefined;
             shortId?: string | undefined;
             priority?: number | undefined;
+            statusLog?: {
+                id: string;
+                date: string;
+                title: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                description?: string | undefined;
+            }[] | undefined;
             dependsOn?: string[] | undefined;
             discussedAt?: string | undefined;
             contextReady?: boolean | undefined;
@@ -1877,6 +2191,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }[];
             shortId: string;
             priority: number;
+            statusLog: {
+                id: string;
+                date: string;
+                title: string;
+                description: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            }[];
             dependsOn: string[];
             discussedAt: string;
             contextReady: boolean;
@@ -1905,6 +2227,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }[] | undefined;
             shortId?: string | undefined;
             priority?: number | undefined;
+            statusLog?: {
+                id: string;
+                date: string;
+                title: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                description?: string | undefined;
+            }[] | undefined;
             dependsOn?: string[] | undefined;
             discussedAt?: string | undefined;
             contextReady?: boolean | undefined;
@@ -2019,7 +2349,11 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
     }>;
     phases: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        /** MUST be a feature UUID (not a ref like "F005"). Validated at the schema
+         *  layer so no adapter can persist an unresolved ref string. Optional only
+         *  for legacy pre-feature phases. */
         featureId: z.ZodOptional<z.ZodString>;
+        /** Global project-wide phase sequence (assigned once at creation from project.nextPhaseNumber; stable, gaps on delete). Bare P00x is unambiguous. */
         number: z.ZodNumber;
         shortId: z.ZodDefault<z.ZodString>;
         priority: z.ZodDefault<z.ZodNumber>;
@@ -2064,7 +2398,10 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         taskIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         tasks: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
             id: z.ZodString;
+            /** MUST be a phase UUID (not a ref like "P003"). Validated at the schema
+             *  layer so no adapter can persist an unresolved ref string. */
             phaseId: z.ZodString;
+            /** Global project-wide task sequence (assigned once at creation from project.nextTaskNumber; stable, gaps on delete). Bare T00x is unambiguous. */
             number: z.ZodDefault<z.ZodNumber>;
             shortId: z.ZodDefault<z.ZodString>;
             priority: z.ZodDefault<z.ZodNumber>;
@@ -2120,15 +2457,21 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }>, "many">>;
             checklist: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
                 id: z.ZodString;
+                /** Per-task 1-based position, displayed as C{number} (C1, C2, ...). Default 0
+                 *  so legacy on-disk items without a number still parse; the TaskSchema
+                 *  transform overwrites it with the real index+1. */
+                number: z.ZodDefault<z.ZodNumber>;
                 title: z.ZodString;
                 checked: z.ZodDefault<z.ZodBoolean>;
             }, "strip", z.ZodTypeAny, {
+                number: number;
                 id: string;
                 title: string;
                 checked: boolean;
             }, {
                 id: string;
                 title: string;
+                number?: number | undefined;
                 checked?: boolean | undefined;
             }>]>, "many">>;
             subtasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -2189,6 +2532,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
                 toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
             }[];
             checklist: (string | {
+                number: number;
                 id: string;
                 title: string;
                 checked: boolean;
@@ -2237,6 +2581,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             checklist?: (string | {
                 id: string;
                 title: string;
+                number?: number | undefined;
                 checked?: boolean | undefined;
             })[] | undefined;
             subtasks?: {
@@ -2253,6 +2598,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }>, {
             checklist: {
                 id: string;
+                number: number;
                 title: string;
                 checked: boolean;
             }[];
@@ -2329,6 +2675,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             checklist?: (string | {
                 id: string;
                 title: string;
+                number?: number | undefined;
                 checked?: boolean | undefined;
             })[] | undefined;
             subtasks?: {
@@ -2347,6 +2694,53 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         updatedAt: z.ZodString;
         handoff: z.ZodDefault<z.ZodString>;
         handoffUpdatedAt: z.ZodDefault<z.ZodString>;
+        /** When the handoff was last read/acknowledged on recap (ISO). Non-empty means
+         *  the agent has seen it; the recap won't re-prompt every turn. The handoff
+         *  content is KEPT until a task in the phase starts (auto-clear) or the phase
+         *  completes — so a restart between read and resume does not lose context. */
+        handoffReadAt: z.ZodDefault<z.ZodString>;
+        /** Metadata for recently-cleared handoffs (newest-first, capped at 5). The
+         *  full content lives as .md files in .planner/.local/handoff-archive/ (gitignored);
+         *  this array only holds the pointer + clear reason + timestamp, so the phase
+         *  JSON stays lean and the archive is recoverable. */
+        handoffHistory: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Relative path under .planner/.local/handoff-archive/ (e.g. <phaseId>-<ISO>.md). */
+            file: z.ZodDefault<z.ZodString>;
+            clearedAt: z.ZodString;
+            /** Why the handoff was cleared: "task-started" | "phase-done" | "manual" | "superseded" | "imported". */
+            reason: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            file: string;
+            clearedAt: string;
+            reason: string;
+        }, {
+            clearedAt: string;
+            file?: string | undefined;
+            reason?: string | undefined;
+        }>, "many">>;
+        /** Chronological audit trail of the DERIVED status (planned/in-progress/blocked/done/...). Appended ONLY when the derived status changes during a rollup; `status` itself is NOT persisted (still computed from child tasks at read time). Empty = no transition recorded yet (treated as "planned"). */
+        statusLog: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            date: z.ZodString;
+            fromStatus: z.ZodEnum<["draft", "discovery", "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+            toStatus: z.ZodEnum<["draft", "discovery", "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting"]>;
+            title: z.ZodString;
+            description: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            date: string;
+            title: string;
+            description: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        }, {
+            id: string;
+            date: string;
+            title: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            description?: string | undefined;
+        }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         number: number;
         dependencies: string[];
@@ -2368,6 +2762,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[];
         shortId: string;
         priority: number;
+        statusLog: {
+            id: string;
+            date: string;
+            title: string;
+            description: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        }[];
         dependsOn: string[];
         slug: string;
         discussedAt: string;
@@ -2382,6 +2784,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         tasks: {
             checklist: {
                 id: string;
+                number: number;
                 title: string;
                 checked: boolean;
             }[];
@@ -2428,6 +2831,12 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[];
         handoff: string;
         handoffUpdatedAt: string;
+        handoffReadAt: string;
+        handoffHistory: {
+            file: string;
+            clearedAt: string;
+            reason: string;
+        }[];
         featureId?: string | undefined;
     }, {
         number: number;
@@ -2451,6 +2860,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[] | undefined;
         shortId?: string | undefined;
         priority?: number | undefined;
+        statusLog?: {
+            id: string;
+            date: string;
+            title: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            description?: string | undefined;
+        }[] | undefined;
         dependsOn?: string[] | undefined;
         featureId?: string | undefined;
         discussedAt?: string | undefined;
@@ -2495,6 +2912,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             checklist?: (string | {
                 id: string;
                 title: string;
+                number?: number | undefined;
                 checked?: boolean | undefined;
             })[] | undefined;
             subtasks?: {
@@ -2511,6 +2929,12 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[] | undefined;
         handoff?: string | undefined;
         handoffUpdatedAt?: string | undefined;
+        handoffReadAt?: string | undefined;
+        handoffHistory?: {
+            clearedAt: string;
+            file?: string | undefined;
+            reason?: string | undefined;
+        }[] | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     features: {
@@ -2531,6 +2955,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }[];
             shortId: string;
             priority: number;
+            statusLog: {
+                id: string;
+                date: string;
+                title: string;
+                description: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+            }[];
             dependsOn: string[];
             discussedAt: string;
             contextReady: boolean;
@@ -2594,6 +3026,9 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             implementationNotes: string;
             acceptedAt: string;
         }[];
+        nextFeatureNumber: number;
+        nextPhaseNumber: number;
+        nextTaskNumber: number;
     };
     phases: {
         number: number;
@@ -2616,6 +3051,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[];
         shortId: string;
         priority: number;
+        statusLog: {
+            id: string;
+            date: string;
+            title: string;
+            description: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+        }[];
         dependsOn: string[];
         slug: string;
         discussedAt: string;
@@ -2630,6 +3073,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         tasks: {
             checklist: {
                 id: string;
+                number: number;
                 title: string;
                 checked: boolean;
             }[];
@@ -2676,6 +3120,12 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[];
         handoff: string;
         handoffUpdatedAt: string;
+        handoffReadAt: string;
+        handoffHistory: {
+            file: string;
+            clearedAt: string;
+            reason: string;
+        }[];
         featureId?: string | undefined;
     }[];
 }, {
@@ -2697,6 +3147,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             }[] | undefined;
             shortId?: string | undefined;
             priority?: number | undefined;
+            statusLog?: {
+                id: string;
+                date: string;
+                title: string;
+                fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting";
+                description?: string | undefined;
+            }[] | undefined;
             dependsOn?: string[] | undefined;
             discussedAt?: string | undefined;
             contextReady?: boolean | undefined;
@@ -2760,6 +3218,9 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             rationale?: string | undefined;
             implementationNotes?: string | undefined;
         }[] | undefined;
+        nextFeatureNumber?: number | undefined;
+        nextPhaseNumber?: number | undefined;
+        nextTaskNumber?: number | undefined;
     };
     phases: {
         number: number;
@@ -2783,6 +3244,14 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[] | undefined;
         shortId?: string | undefined;
         priority?: number | undefined;
+        statusLog?: {
+            id: string;
+            date: string;
+            title: string;
+            fromStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            toStatus: "planned" | "in-progress" | "done" | "blocked" | "canceled" | "rejected" | "deferred" | "waiting" | "draft" | "discovery";
+            description?: string | undefined;
+        }[] | undefined;
         dependsOn?: string[] | undefined;
         featureId?: string | undefined;
         discussedAt?: string | undefined;
@@ -2827,6 +3296,7 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
             checklist?: (string | {
                 id: string;
                 title: string;
+                number?: number | undefined;
                 checked?: boolean | undefined;
             })[] | undefined;
             subtasks?: {
@@ -2843,6 +3313,12 @@ export declare const PlanWorkspaceSchema: z.ZodObject<{
         }[] | undefined;
         handoff?: string | undefined;
         handoffUpdatedAt?: string | undefined;
+        handoffReadAt?: string | undefined;
+        handoffHistory?: {
+            clearedAt: string;
+            file?: string | undefined;
+            reason?: string | undefined;
+        }[] | undefined;
     }[];
 }>;
 export type Timestamp = z.infer<typeof TimestampSchema>;
@@ -2870,6 +3346,7 @@ export type Project = z.infer<typeof ProjectSchema>;
 export type Subtask = z.infer<typeof SubtaskSchema>;
 export type ChecklistItem = z.infer<typeof ChecklistItemSchema>;
 export type StatusLogEntry = z.infer<typeof StatusLogEntrySchema>;
+export type PhaseStatusLogEntry = z.infer<typeof PhaseStatusLogEntrySchema>;
 export type Task = z.infer<typeof TaskSchema>;
 export type Phase = z.infer<typeof PhaseSchema> & {
     status: PhaseStatus;