ai-foreman 1.7.26 → 1.7.28

package/dist/ticketPlanning.d.ts

@@ -2,6 +2,7 @@ import type { TicketDef } from "./tickets/ticketSchema.js";
 import { type TicketStatus } from "./tickets/stateDb.js";
 import { type DeliveryConfig } from "./tickets/delivery.js";
 import { type TicketBuildSetupConfig } from "./tickets/setupConfig.js";
+import { z } from "zod";
 export declare const PROPOSAL_START = "RAFI_PROPOSAL_START";
 export declare const PROPOSAL_END = "RAFI_PROPOSAL_END";
 export interface TicketEdit {
@@ -68,6 +69,378 @@ export interface TicketPlanningContext {
 export interface TicketPlanValidationContext {
     futureWorkIds?: Iterable<number>;
 }
+export declare const ticketPlanProposalV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    title: z.ZodString;
+    markdown: z.ZodString;
+    additions: z.ZodArray<z.ZodObject<{
+        qa_preparation: z.ZodOptional<z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            decisionId: z.ZodString;
+            level: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+            rationale: z.ZodString;
+            riskFactors: z.ZodArray<z.ZodObject<{
+                category: z.ZodEnum<{
+                    interaction: "interaction";
+                    compatibility: "compatibility";
+                    "state-transition": "state-transition";
+                    "external-dependency": "external-dependency";
+                    authorization: "authorization";
+                    security: "security";
+                    "data-integrity": "data-integrity";
+                    migration: "migration";
+                    concurrency: "concurrency";
+                    recovery: "recovery";
+                    deployment: "deployment";
+                    "architecture-uncertainty": "architecture-uncertainty";
+                }>;
+                rationale: z.ZodString;
+                references: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            lowRisk: z.ZodOptional<z.ZodObject<{
+                narrowBehavior: z.ZodString;
+                understoodDependencies: z.ZodString;
+                adequateVerification: z.ZodString;
+            }, z.core.$strict>>;
+            policyVersion: z.ZodLiteral<"qa-preparation-v1">;
+            plannerOperationId: z.ZodString;
+            plannerIdentity: z.ZodString;
+            timestamp: z.ZodString;
+            minimumLevel: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+            minimumReasons: z.ZodArray<z.ZodString>;
+            predecessorDecisionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        id: z.ZodString;
+        order: z.ZodNumber;
+        documentation: z.ZodOptional<z.ZodObject<{
+            required: z.ZodBoolean;
+            targets: z.ZodArray<z.ZodString>;
+            criteria: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        title: z.ZodString;
+        area: z.ZodString;
+        priority: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>;
+        size: z.ZodEnum<{
+            XS: "XS";
+            S: "S";
+            M: "M";
+            L: "L";
+            XL: "XL";
+        }>;
+        risk: z.ZodEnum<{
+            Low: "Low";
+            Medium: "Medium";
+            High: "High";
+        }>;
+        depends_on: z.ZodArray<z.ZodString>;
+        summary: z.ZodString;
+        acceptance: z.ZodArray<z.ZodString>;
+        required_tests: z.ZodArray<z.ZodString>;
+        likely_files: z.ZodArray<z.ZodString>;
+        rollback: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        external_refs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            provider: z.ZodString;
+            id: z.ZodString;
+            key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>>>;
+        source_refs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            item: z.ZodString;
+            source_id: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            fingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>>>;
+        superseded_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        plan_ref: z.ZodOptional<z.ZodObject<{
+            plan_id: z.ZodString;
+            revision: z.ZodNumber;
+            slice_ref: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    edits: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        patch: z.ZodObject<{
+            qa_preparation: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+                version: z.ZodLiteral<1>;
+                decisionId: z.ZodString;
+                level: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+                rationale: z.ZodString;
+                riskFactors: z.ZodArray<z.ZodObject<{
+                    category: z.ZodEnum<{
+                        interaction: "interaction";
+                        compatibility: "compatibility";
+                        "state-transition": "state-transition";
+                        "external-dependency": "external-dependency";
+                        authorization: "authorization";
+                        security: "security";
+                        "data-integrity": "data-integrity";
+                        migration: "migration";
+                        concurrency: "concurrency";
+                        recovery: "recovery";
+                        deployment: "deployment";
+                        "architecture-uncertainty": "architecture-uncertainty";
+                    }>;
+                    rationale: z.ZodString;
+                    references: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>>;
+                lowRisk: z.ZodOptional<z.ZodObject<{
+                    narrowBehavior: z.ZodString;
+                    understoodDependencies: z.ZodString;
+                    adequateVerification: z.ZodString;
+                }, z.core.$strict>>;
+                policyVersion: z.ZodLiteral<"qa-preparation-v1">;
+                plannerOperationId: z.ZodString;
+                plannerIdentity: z.ZodString;
+                timestamp: z.ZodString;
+                minimumLevel: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+                minimumReasons: z.ZodArray<z.ZodString>;
+                predecessorDecisionId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            id: z.ZodOptional<z.ZodString>;
+            order: z.ZodOptional<z.ZodNumber>;
+            documentation: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+                required: z.ZodBoolean;
+                targets: z.ZodArray<z.ZodString>;
+                criteria: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>>;
+            title: z.ZodOptional<z.ZodString>;
+            area: z.ZodOptional<z.ZodString>;
+            priority: z.ZodOptional<z.ZodEnum<{
+                P0: "P0";
+                P1: "P1";
+                P2: "P2";
+                P3: "P3";
+            }>>;
+            size: z.ZodOptional<z.ZodEnum<{
+                XS: "XS";
+                S: "S";
+                M: "M";
+                L: "L";
+                XL: "XL";
+            }>>;
+            risk: z.ZodOptional<z.ZodEnum<{
+                Low: "Low";
+                Medium: "Medium";
+                High: "High";
+            }>>;
+            depends_on: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            summary: z.ZodOptional<z.ZodString>;
+            acceptance: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            required_tests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            likely_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            rollback: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+            notes: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+            external_refs: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+                provider: z.ZodString;
+                id: z.ZodString;
+                key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strict>>>>;
+            source_refs: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+                source: z.ZodString;
+                item: z.ZodString;
+                source_id: z.ZodOptional<z.ZodString>;
+                url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                fingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strict>>>>;
+            superseded_by: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+            supersedes: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+            plan_ref: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+                plan_id: z.ZodString;
+                revision: z.ZodNumber;
+                slice_ref: z.ZodString;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    supersessions: z.ZodArray<z.ZodObject<{
+        replaced: z.ZodArray<z.ZodString>;
+        replacements: z.ZodArray<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    state_changes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            blocked: "blocked";
+            in_progress: "in_progress";
+            done: "done";
+            planned: "planned";
+            next: "next";
+            canceled: "canceled";
+            obsolete: "obsolete";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    source_reconciliation: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        item: z.ZodString;
+        disposition: z.ZodEnum<{
+            split: "split";
+            deferred: "deferred";
+            combined: "combined";
+            mapped: "mapped";
+            excluded: "excluded";
+        }>;
+        ticket_ids: z.ZodArray<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    delivery: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        plan: z.ZodOptional<z.ZodObject<{
+            plan_id: z.ZodString;
+            revision: z.ZodNumber;
+        }, z.core.$strict>>;
+        units: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            tickets: z.ZodArray<z.ZodString>;
+            branch_mode: z.ZodEnum<{
+                current: "current";
+                "per-ticket": "per-ticket";
+                shared: "shared";
+            }>;
+            completion: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                pr: "pr";
+                "auto-merge": "auto-merge";
+                "direct-merge": "direct-merge";
+            }>>;
+            provider: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                local: "local";
+                github: "github";
+                gitlab: "gitlab";
+            }>>;
+            pr_ready: z.ZodOptional<z.ZodBoolean>;
+            merge_method: z.ZodOptional<z.ZodEnum<{
+                squash: "squash";
+                merge: "merge";
+                rebase: "rebase";
+            }>>;
+            cleanup: z.ZodOptional<z.ZodBoolean>;
+            depends_on: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            dependency_mode: z.ZodOptional<z.ZodEnum<{
+                combine: "combine";
+                wait: "wait";
+                stack: "stack";
+            }>>;
+        }, z.core.$strict>>;
+        stacks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            units: z.ZodArray<z.ZodString>;
+            status: z.ZodOptional<z.ZodEnum<{
+                partial: "partial";
+                blocked: "blocked";
+                in_progress: "in_progress";
+                planned: "planned";
+                merged: "merged";
+                awaiting_review: "awaiting_review";
+            }>>;
+            completed_prefix: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            next_ticket: z.ZodOptional<z.ZodString>;
+            review_links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            remote_checked_at: z.ZodOptional<z.ZodString>;
+            remote_stale: z.ZodOptional<z.ZodBoolean>;
+            published_branches: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+    build_defaults: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        branch_strategy: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+            current: "current";
+            batch: "batch";
+            "branch-per-ticket": "branch-per-ticket";
+        }>>>;
+        completion: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            pr: "pr";
+            "auto-merge": "auto-merge";
+            "direct-merge": "direct-merge";
+        }>>>;
+        provider: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            local: "local";
+            github: "github";
+            gitlab: "gitlab";
+        }>>>;
+        pr_ready: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+        merge_method: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+            squash: "squash";
+            merge: "merge";
+            rebase: "rebase";
+        }>>>;
+        cleanup: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+        auto_merge_wait: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+        auto_merge_timeout_minutes: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+        base_branch: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        branch_prefix: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        branch_policy: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                size: "size";
+                global: "global";
+            }>;
+            global_strategy: z.ZodEnum<{
+                current: "current";
+                batch: "batch";
+                "branch-per-ticket": "branch-per-ticket";
+            }>;
+            by_size: z.ZodObject<{
+                XS: z.ZodEnum<{
+                    "per-ticket": "per-ticket";
+                    shared: "shared";
+                }>;
+                S: z.ZodEnum<{
+                    "per-ticket": "per-ticket";
+                    shared: "shared";
+                }>;
+                M: z.ZodEnum<{
+                    "per-ticket": "per-ticket";
+                    shared: "shared";
+                }>;
+                L: z.ZodEnum<{
+                    "per-ticket": "per-ticket";
+                    shared: "shared";
+                }>;
+                XL: z.ZodEnum<{
+                    "per-ticket": "per-ticket";
+                    shared: "shared";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>>;
+        review: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+            title_style: z.ZodEnum<{
+                none: "none";
+                custom: "custom";
+                "ticket-title": "ticket-title";
+                conventional: "conventional";
+            }>;
+            title_template: z.ZodNullable<z.ZodString>;
+            description_sections: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+        validation_checklist: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>>;
+    future_work: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        disposition: z.ZodEnum<{
+            rejected: "rejected";
+            accepted: "accepted";
+            merged: "merged";
+            queued: "queued";
+        }>;
+    }, z.core.$strict>>;
+    next: z.ZodObject<{
+        ticket_ids: z.ZodArray<z.ZodString>;
+        replace_existing: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare function readTicketPlanningContext(projectDir: string): TicketPlanningContext;
 export declare function ticketPlanningFingerprint(projectDir: string): PlanningFingerprint[];
 export declare function planningFingerprintChanges(projectDir: string, expected: PlanningFingerprint[]): string[];

package/dist/ticketPlanning.js

@@ -10,8 +10,34 @@ import { renderAndWrite } from "./tickets/renderMarkdown.js";
 import { runAllValidation } from "./tickets/validate.js";
 import { normalizeDeliveryConfig, validateDeliveryConfig } from "./tickets/delivery.js";
 import { loadTicketSetupConfig, mergeTicketSetup, saveTicketSetupConfig } from "./tickets/setupConfig.js";
+import { z } from "zod";
+import { documentationPolicyV1ZodSchema as documentationPolicyZodSchema, qaPreparationDepthDecisionZodSchema, zodIssues } from "rafi-spec";
 export const PROPOSAL_START = "RAFI_PROPOSAL_START";
 export const PROPOSAL_END = "RAFI_PROPOSAL_END";
+const providerText = (max = 20_000) => z.string().trim().min(1).max(max);
+const identifier = z.string().regex(/^[A-Za-z][A-Za-z0-9-_]{0,127}$/);
+const ticketSourceRef = z.strictObject({ source: providerText(500), item: providerText(2_000), source_id: identifier.optional(), url: z.string().url().nullable().optional(), fingerprint: z.string().regex(/^[a-f0-9]{64}$/).nullable().optional(), note: providerText(2_000).nullable().optional() });
+const ticketDefinitionProposal = z.strictObject({
+    qa_preparation: qaPreparationDepthDecisionZodSchema.optional(), id: identifier, order: z.number().int().min(0),
+    documentation: documentationPolicyZodSchema.optional(),
+    title: providerText(500), area: providerText(500), priority: z.enum(["P0", "P1", "P2", "P3"]), size: z.enum(["XS", "S", "M", "L", "XL"]), risk: z.enum(["Low", "Medium", "High"]),
+    depends_on: z.array(identifier).max(200), summary: providerText(), acceptance: z.array(providerText()).min(1).max(200), required_tests: z.array(providerText()).min(1).max(200), likely_files: z.array(providerText(1_000)).max(200),
+    rollback: z.string().max(20_000).nullable().optional(), notes: z.string().max(20_000).nullable().optional(),
+    external_refs: z.array(z.strictObject({ provider: providerText(100), id: providerText(500), key: providerText(500).nullable().optional(), url: z.string().url().nullable().optional() })).max(100).optional(),
+    source_refs: z.array(ticketSourceRef).max(100).optional(), superseded_by: z.array(identifier).max(200).optional(), supersedes: z.array(identifier).max(200).optional(),
+    plan_ref: z.strictObject({ plan_id: identifier, revision: z.number().int().min(1), slice_ref: identifier }).optional(),
+});
+const deliveryConfigProposal = z.strictObject({
+    version: z.literal(1), plan: z.strictObject({ plan_id: identifier, revision: z.number().int().min(1) }).optional(),
+    units: z.array(z.strictObject({ id: identifier, tickets: z.array(identifier).min(1).max(200), branch_mode: z.enum(["current", "per-ticket", "shared"]), completion: z.enum(["pr", "auto-merge", "direct-merge", "none"]).optional(), provider: z.enum(["auto", "github", "gitlab", "local"]).optional(), pr_ready: z.boolean().optional(), merge_method: z.enum(["squash", "merge", "rebase"]).optional(), cleanup: z.boolean().optional(), depends_on: z.array(identifier).max(200).optional(), dependency_mode: z.enum(["combine", "wait", "stack"]).optional() })).max(200),
+    stacks: z.array(z.strictObject({ id: identifier, name: providerText(500), units: z.array(identifier).min(1).max(5), status: z.enum(["planned", "in_progress", "partial", "blocked", "awaiting_review", "merged"]).optional(), completed_prefix: z.array(identifier).max(5).optional(), next_ticket: identifier.optional(), review_links: z.array(z.string().url()).max(20).optional(), remote_checked_at: z.string().datetime().optional(), remote_stale: z.boolean().optional(), published_branches: z.record(identifier, providerText(500)).optional() })).max(200).optional(),
+});
+const buildDefaultsProposal = z.strictObject({
+    branch_strategy: z.enum(["current", "batch", "branch-per-ticket"]).optional(), completion: z.enum(["pr", "auto-merge", "direct-merge", "none"]).optional(), provider: z.enum(["auto", "github", "gitlab", "local"]).optional(), pr_ready: z.boolean().optional(), merge_method: z.enum(["squash", "merge", "rebase"]).optional(), cleanup: z.boolean().optional(), auto_merge_wait: z.boolean().optional(), auto_merge_timeout_minutes: z.number().int().min(0).nullable().optional(), base_branch: providerText(500).optional(), branch_prefix: providerText(500).optional(), branch_policy: z.strictObject({ mode: z.enum(["global", "size"]), global_strategy: z.enum(["current", "batch", "branch-per-ticket"]), by_size: z.strictObject({ XS: z.enum(["shared", "per-ticket"]), S: z.enum(["shared", "per-ticket"]), M: z.enum(["shared", "per-ticket"]), L: z.enum(["shared", "per-ticket"]), XL: z.enum(["shared", "per-ticket"]) }) }).optional(), review: z.strictObject({ title_style: z.enum(["ticket-title", "conventional", "none", "custom"]), title_template: z.string().max(500).nullable(), description_sections: z.array(providerText(500)).max(50) }).optional(), validation_checklist: z.array(providerText(500)).max(100).optional(),
+});
+export const ticketPlanProposalV1Schema = z.strictObject({
+    version: z.literal(1), title: providerText(500), markdown: providerText(100_000), additions: z.array(ticketDefinitionProposal).max(200), edits: z.array(z.strictObject({ id: identifier, patch: ticketDefinitionProposal.partial() })).max(200), supersessions: z.array(z.strictObject({ replaced: z.array(identifier).min(1).max(200), replacements: z.array(identifier).min(1).max(200), reason: providerText() })).max(200), state_changes: z.array(z.strictObject({ id: identifier, status: z.enum(["planned", "next", "in_progress", "blocked", "done", "canceled", "obsolete"]), reason: providerText() })).max(200), source_reconciliation: z.array(z.strictObject({ source: providerText(500), item: providerText(2_000), disposition: z.enum(["mapped", "split", "combined", "deferred", "excluded"]), ticket_ids: z.array(identifier).max(200), reason: providerText().optional() })).max(500), delivery: deliveryConfigProposal.nullable().optional(), build_defaults: buildDefaultsProposal.partial().nullable().optional(), future_work: z.array(z.strictObject({ id: z.number().int().min(0), disposition: z.enum(["accepted", "rejected", "merged", "queued"]) })).max(500), next: z.strictObject({ ticket_ids: z.array(identifier).max(200), replace_existing: z.boolean() }),
+});
 const TICKET_STATUSES = new Set([
     "planned", "next", "in_progress", "blocked", "done", "canceled", "obsolete",
 ]);
@@ -57,13 +83,18 @@ export function extractTicketPlanProposal(output, existingTickets = [], context
     catch (err) {
         throw new Error(`planner proposal is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
     }
-    const issues = validateTicketPlanProposal(parsed, existingTickets, context);
+    const contract = ticketPlanProposalV1Schema.safeParse(parsed);
+    if (!contract.success)
+        throw new Error(`planner proposal contract validation failed:\n${zodIssues(contract.error).map((issue) => `- ${issue}`).join("\n")}`);
+    const issues = validateTicketPlanProposal(contract.data, existingTickets, context);
     if (issues.length)
         throw new Error(`invalid planner proposal:\n${issues.map((issue) => `- ${issue}`).join("\n")}`);
-    return parsed;
+    return contract.data;
 }
 export function validateTicketPlanProposal(value, existingTickets = [], context = {}) {
     const issues = [];
+    const contract = ticketPlanProposalV1Schema.safeParse(value);
+    const contractIssues = contract.success ? [] : zodIssues(contract.error);
     if (!value || typeof value !== "object" || Array.isArray(value))
         return ["proposal must be an object"];
     const proposal = value;
@@ -159,7 +190,7 @@ export function validateTicketPlanProposal(value, existingTickets = [], context
     issues.push(...detectCycles(staged).map((cycle) => `dependency cycle: ${cycle}`));
     if (p.delivery)
         issues.push(...validateDeliveryConfig(p.delivery, staged).map((issue) => `delivery ${issue.path}: ${issue.message}`));
-    return [...new Set(issues)];
+    return [...new Set([...contractIssues, ...issues])];
 }
 export function applyApprovedTicketPlan(projectDir, proposal, opts) {
     const root = resolve(projectDir);

package/dist/ticketPopulation.d.ts

@@ -1,8 +1,9 @@
-import type { StructuredPlanV1 } from "rafi-spec";
+import { type StructuredPlanV1 } from "rafi-spec";
 import type { TicketDef } from "./tickets/ticketSchema.js";
 import { type DeliveryConfig } from "./tickets/delivery.js";
 export interface TicketSliceProposal {
     qa_preparation?: TicketDef["qa_preparation"];
+    documentation?: TicketDef["documentation"];
     slice_ref: string;
     title: string;
     area: string;
@@ -33,15 +34,39 @@ export interface TicketPopulationProposalV1 {
 }
 export declare const TICKET_POPULATION_PROPOSAL_START = "RAFI_TICKET_POPULATION_PROPOSAL_START";
 export declare const TICKET_POPULATION_PROPOSAL_END = "RAFI_TICKET_POPULATION_PROPOSAL_END";
+export interface PopulationRiskWaiver {
+    ticketId: string;
+    reason: string;
+    actor: string;
+}
 export interface MaterializedTicketPopulation {
     tickets: TicketDef[];
     delivery: DeliveryConfig;
     retirements: string[];
     sliceToTicket: Map<string, string>;
+    riskWaivers?: PopulationRiskWaiver[];
+}
+export type PopulationBranchStrategy = "current" | "batch" | "branch-per-ticket";
+/** A recoverable, proposal-local validation failure. Callers can ask Ticket Maker
+ * to repair only the listed tickets instead of discarding the whole interview. */
+export declare class TicketPopulationValidationError extends Error {
+    readonly repairableRiskTicketIds: string[];
+    readonly repairableRiskSliceRefs: string[];
+    readonly onlyRepairableRiskFailures: boolean;
+    constructor(message: string, repairableRiskTicketIds: string[], repairableRiskSliceRefs: string[], onlyRepairableRiskFailures: boolean);
 }
+/** Reject a correction that attempts to turn a risk-note repair into a new plan. */
+export declare function assertRiskPlanOnlyCorrection(previous: TicketPopulationProposalV1, corrected: TicketPopulationProposalV1, permittedSliceRefs: string[]): void;
 export declare function extractTicketPopulationProposal(output: string): TicketPopulationProposalV1;
-export declare function validateTicketPopulationProposal(proposal: TicketPopulationProposalV1, plan: StructuredPlanV1, existing: TicketDef[]): string[];
-export declare function materializeTicketPopulation(proposal: TicketPopulationProposalV1, plan: StructuredPlanV1, existing: TicketDef[]): MaterializedTicketPopulation;
+export declare function validateTicketPopulationProposal(proposal: TicketPopulationProposalV1, plan: StructuredPlanV1, existing: TicketDef[], options?: {
+    branchStrategy?: PopulationBranchStrategy;
+}): string[];
+export declare function materializeTicketPopulation(proposal: TicketPopulationProposalV1, plan: StructuredPlanV1, existing: TicketDef[], options?: {
+    waiveRiskTicketIds?: string[];
+    waiverReason?: string;
+    waiverActor?: string;
+    branchStrategy?: PopulationBranchStrategy;
+}): MaterializedTicketPopulation;
 export declare function authorizeTicketRetirements(retirements: string[], input: {
     interactiveConfirmed?: boolean;
     authorizedIds?: string[];