ai-foreman 1.7.5 → 1.7.6

package/dist/tickets/reset.js

@@ -0,0 +1,213 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { recoverableBuildRuns } from "../buildRuns.js";
+import { WorkflowDb, WORKFLOW_DB_FILE } from "../workflowDb.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
+import { renderProgressDoc, writeProgressDoc } from "./renderMarkdown.js";
+import { StateDb, pristineTicketState } from "./stateDb.js";
+import { loadTickets } from "./ticketLoader.js";
+const SCOPE_STATUSES = {
+    all: ["planned", "next", "in_progress", "blocked", "done", "canceled", "obsolete"],
+    "completed-and-unfinished": ["planned", "next", "in_progress", "blocked", "done"],
+    unfinished: ["planned", "next", "in_progress", "blocked"],
+};
+export function previewTicketReset(projectDir, target) {
+    const { tickets, db } = open(projectDir);
+    try {
+        const states = db.getAllStates();
+        let selected;
+        let scope;
+        if (Array.isArray(target)) {
+            scope = "run";
+            const wanted = new Set(target);
+            selected = tickets.filter((ticket) => wanted.has(ticket.id));
+            const missing = target.filter((id) => !selected.some((ticket) => ticket.id === id));
+            if (missing.length)
+                throw new Error(`Tickets not found: ${missing.join(", ")}`);
+        }
+        else if (target in SCOPE_STATUSES) {
+            scope = target;
+            const statuses = new Set(SCOPE_STATUSES[scope]);
+            selected = tickets.filter((ticket) => statuses.has(states.get(ticket.id)?.status ?? "planned"));
+        }
+        else {
+            scope = "single";
+            const ticket = tickets.find((candidate) => candidate.id === target);
+            if (!ticket)
+                throw new Error(`Ticket ${target} not found. Run \`rafi tickets queue\` to list tickets.`);
+            selected = [ticket];
+        }
+        const selectedIds = new Set(selected.map((ticket) => ticket.id));
+        const relatedRuns = recoverableBuildRuns(projectDir)
+            .filter((run) => run.tickets.some((id) => selectedIds.has(id)))
+            .map((run) => ({ runId: run.runId, status: run.status, tickets: run.tickets }));
+        return {
+            scope,
+            tickets: selected.map((ticket) => {
+                const state = states.get(ticket.id) ?? pristineTicketState(ticket.id, new Date(0).toISOString());
+                return { id: ticket.id, title: ticket.title, status: state.status, cleared: activeFieldCategories(state) };
+            }),
+            relatedRuns,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function resetTickets(projectDir, target, actor = "user", now = new Date(), hooks = {}) {
+    const preview = previewTicketReset(projectDir, target);
+    const ids = preview.tickets.map((ticket) => ticket.id);
+    if (ids.length === 0)
+        return { resetId: randomUUID(), tickets: [] };
+    const { config, paths, tickets, db } = open(projectDir);
+    const workflow = new WorkflowDb(projectDir);
+    const resetId = hooks.resetId ?? randomUUID();
+    if (ids.every((id) => db.getTicketEvents(id).some((event) => event.event_type === "ticket_reset" && event.payload_json?.includes(resetId)))) {
+        workflow.close();
+        db.close();
+        return { resetId, tickets: ids };
+    }
+    const stagePath = join(projectDir, ".rafi", "reset-stage", resetId, "progress.md");
+    const oldStates = new Map(ids.map((id) => [id, db.getState(id)]));
+    const oldRecentCompleted = db.getRecentCompleted().filter((row) => ids.includes(row.ticket_id));
+    const insertedEventIds = [];
+    const progressBefore = existsSync(paths.progressDoc) ? readFileSync(paths.progressDoc) : undefined;
+    const run = workflow.createRun({
+        kind: "recovery",
+        checkpoint: "ticket-reset-intent",
+        originalWork: { resetId, scope: preview.scope, tickets: ids, states: Object.fromEntries(oldStates) },
+        remainingWork: { tickets: ids },
+        state: { operation: "ticket-reset", progressDigest: digest(progressBefore) },
+    }, now);
+    const publication = workflow.beginPublication(run.runId, { operation: "ticket-reset", resetId, tickets: ids, stagePath, targetPath: paths.progressDoc }, { progressDigest: digest(progressBefore) }, now);
+    try {
+        const stamp = now.toISOString();
+        db.transaction(() => {
+            for (const row of preview.tickets) {
+                db.upsertState(row.id, pristineTicketState(row.id, stamp, actor), stamp);
+                db.deleteRecentCompleted(row.id);
+                insertedEventIds.push(db.insertEvent({
+                    timestamp: stamp,
+                    actor,
+                    ticket_id: row.id,
+                    event_type: "ticket_reset",
+                    old_status: row.status,
+                    new_status: "planned",
+                    summary: `Reset ${row.id} to pristine active state`,
+                    validation: null,
+                    evidence: null,
+                    payload_json: JSON.stringify({ reset_id: resetId, scope: preview.scope, cleared: row.cleared }),
+                }));
+            }
+        });
+        mkdirSync(dirname(stagePath), { recursive: true });
+        writeFileSync(stagePath, renderProgressDoc({ config, projectDir, ticketDefs: tickets, states: db.getAllStates(), db, now: stamp }), "utf8");
+        workflow.updatePublication(publication.transactionId, "staged", now);
+        workflow.updatePublication(publication.transactionId, "tracker_committed", now);
+        hooks.beforePublish?.();
+        writeProgressDoc(paths.progressDoc, readFileSync(stagePath, "utf8"), true);
+        workflow.updatePublication(publication.transactionId, "published", now);
+        workflow.updatePublication(publication.transactionId, "committed", now);
+        workflow.transition(run.runId, { status: "completed", checkpoint: "ticket-reset-committed", remainingWork: {}, state: { operation: "ticket-reset", resetId, tickets: ids } }, now);
+        rmSync(dirname(stagePath), { recursive: true, force: true });
+        return { resetId, tickets: ids };
+    }
+    catch (error) {
+        db.transaction(() => {
+            db.deleteEvents(insertedEventIds);
+            for (const [id, state] of oldStates) {
+                if (state)
+                    db.upsertState(id, state, state.updated_at);
+                else
+                    db.deleteState(id);
+            }
+            for (const row of oldRecentCompleted)
+                db.upsertRecentCompleted(row);
+        });
+        if (progressBefore)
+            writeProgressDoc(paths.progressDoc, progressBefore.toString("utf8"), true);
+        else
+            rmSync(paths.progressDoc, { force: true });
+        rmSync(dirname(stagePath), { recursive: true, force: true });
+        workflow.updatePublication(publication.transactionId, "rolled_back", now);
+        workflow.transition(run.runId, { status: "failed", checkpoint: "ticket-reset-rolled-back", state: { operation: "ticket-reset", resetId, error: error instanceof Error ? error.message : String(error) } }, now);
+        throw error;
+    }
+    finally {
+        workflow.close();
+        db.close();
+    }
+}
+/** Finish or roll back a reset publication left incomplete by process interruption. */
+export function recoverTicketResetPublications(projectDir) {
+    if (!existsSync(join(projectDir, WORKFLOW_DB_FILE)))
+        return [];
+    const workflow = new WorkflowDb(projectDir);
+    const recovered = [];
+    try {
+        for (const tx of workflow.incompletePublications()) {
+            const intent = tx.intent;
+            if (intent.operation !== "ticket-reset" || !intent.resetId || !intent.tickets || !intent.stagePath || !intent.targetPath)
+                continue;
+            const { config, tickets, db } = open(projectDir);
+            try {
+                const resetCommitted = intent.tickets.every((id) => db.getTicketEvents(id).some((event) => event.event_type === "ticket_reset" && event.payload_json?.includes(intent.resetId)));
+                if (resetCommitted || ["staged", "tracker_committed", "published"].includes(tx.status)) {
+                    if (!existsSync(intent.stagePath)) {
+                        mkdirSync(dirname(intent.stagePath), { recursive: true });
+                        writeFileSync(intent.stagePath, renderProgressDoc({ config, projectDir, ticketDefs: tickets, states: db.getAllStates(), db }), "utf8");
+                    }
+                    if (tx.status !== "published")
+                        writeProgressDoc(intent.targetPath, readFileSync(intent.stagePath, "utf8"), true);
+                    workflow.updatePublication(tx.transactionId, "committed");
+                    const run = workflow.getRun(tx.runId);
+                    if (run && run.status !== "completed")
+                        workflow.transition(run.runId, { status: "completed", checkpoint: "ticket-reset-recovered", remainingWork: {}, state: { ...run.state, recoveredPublication: tx.transactionId } });
+                }
+                else {
+                    workflow.updatePublication(tx.transactionId, "rolled_back");
+                }
+                rmSync(dirname(intent.stagePath), { recursive: true, force: true });
+                recovered.push(tx.transactionId);
+            }
+            finally {
+                db.close();
+            }
+        }
+        return recovered;
+    }
+    finally {
+        workflow.close();
+    }
+}
+function open(projectDir) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    const tickets = loadTickets(paths.tickets);
+    const db = new StateDb(paths.stateDb);
+    return { config, paths, tickets, db };
+}
+function activeFieldCategories(state) {
+    const out = [];
+    if (state.status !== "planned")
+        out.push("status");
+    if (state.owner)
+        out.push("owner");
+    if (state.current_step || state.next_action)
+        out.push("steps");
+    if (state.blocked_by_json !== "[]" || state.blocker_type || state.blocker_notes || state.first_blocked_at || state.last_checked_at)
+        out.push("temporary blockers");
+    if (state.last_worked_at || state.completed_at)
+        out.push("work timestamps");
+    if (state.attempt_count)
+        out.push("attempt count");
+    if (state.last_error)
+        out.push("last error");
+    if (state.evidence || state.validation_result || state.validation_commands || state.validation_notes)
+        out.push("active validation/evidence");
+    return out.length ? out : ["no active progress"];
+}
+function digest(value) {
+    return value ? createHash("sha256").update(value).digest("hex") : null;
+}

package/dist/tickets/reviewStandards.d.ts

@@ -0,0 +1,7 @@
+import type { BranchPlanNode } from "../branch/types.js";
+import { type TicketBuildSetupConfig } from "./setupConfig.js";
+import type { TicketDef } from "./ticketSchema.js";
+export declare function configuredReviewTitle(projectDir: string, ticket: TicketDef): string;
+export declare function renderReviewTitle(build: TicketBuildSetupConfig, ticket: TicketDef): string;
+export declare function configuredReviewBody(projectDir: string, node: BranchPlanNode, qaEvidence?: string, commit?: string): string;
+export declare function renderReviewBody(build: TicketBuildSetupConfig, node: BranchPlanNode, qaEvidence?: string, commit?: string): string;

package/dist/tickets/reviewStandards.js

@@ -0,0 +1,53 @@
+import { branchNodeFooter } from "../branch/presentation.js";
+import { loadTicketSetupConfigWithDefaults } from "./setupConfig.js";
+export function configuredReviewTitle(projectDir, ticket) {
+    const build = loadTicketSetupConfigWithDefaults(projectDir).build;
+    return renderReviewTitle(build, ticket);
+}
+export function renderReviewTitle(build, ticket) {
+    const standard = build.review;
+    if (standard.title_style === "ticket-title")
+        return `${ticket.id}: ${ticket.title}`;
+    if (standard.title_style === "conventional")
+        return `feat(${ticket.area.toLowerCase().replace(/[^a-z0-9]+/g, "-")}): ${ticket.title}`;
+    if (standard.title_style === "custom" && standard.title_template)
+        return interpolate(standard.title_template, ticket);
+    return ticket.title;
+}
+export function configuredReviewBody(projectDir, node, qaEvidence, commit) {
+    const build = loadTicketSetupConfigWithDefaults(projectDir).build;
+    return renderReviewBody(build, node, qaEvidence, commit);
+}
+export function renderReviewBody(build, node, qaEvidence, commit) {
+    const ticket = node.ticket;
+    const sections = build.review.description_sections.flatMap((section) => {
+        const key = section.toLowerCase();
+        let body;
+        if (key === "summary")
+            body = [ticket.summary];
+        else if (key === "linked ticket")
+            body = [`${ticket.id}: ${ticket.title}`];
+        else if (key === "changes made")
+            body = ticket.likely_files.length ? ticket.likely_files.map((path) => `- ${path}`) : ["- See branch diff."];
+        else if (key === "tests and validation performed")
+            body = [...ticket.required_tests.map((test) => `- ${test}`), `- Evidence: ${qaEvidence ?? "Foreman QA emitted qa_pass."}`];
+        else if (key === "risks or rollback notes")
+            body = [`- Risk: ${ticket.risk}`, `- Rollback: ${ticket.rollback ?? "Revert the review commit."}`];
+        else if (key === "checklist")
+            body = build.validation_checklist.map((item) => `- [ ] ${item}`);
+        else
+            body = ["_Complete before review._"];
+        return [`## ${section}`, "", ...body, ""];
+    });
+    return [
+        ...sections,
+        "## Branch Metadata", "",
+        `- Base: ${node.baseBranch}`, `- Head: ${node.branch}`,
+        `- Dependencies: ${node.dependencies.length ? node.dependencies.join(", ") : "None"}`,
+        `- Commit: ${commit ?? "N/A"}`, "",
+        branchNodeFooter(node), "",
+    ].join("\n");
+}
+function interpolate(template, ticket) {
+    return template.replaceAll("{id}", ticket.id).replaceAll("{title}", ticket.title).replaceAll("{area}", ticket.area);
+}

package/dist/tickets/setupConfig.d.ts

@@ -4,6 +4,8 @@ export type TicketBuildCompletionMode = "pr" | "auto-merge" | "direct-merge" | "
 export type TicketBuildProvider = "auto" | "github" | "gitlab" | "local";
 export type TicketBuildMergeMethod = "squash" | "merge" | "rebase";
 export type TicketBuildBranchStrategy = "current" | "batch" | "branch-per-ticket";
+export type TicketBranchPolicyMode = "global" | "size";
+export type TicketTitleStyle = "ticket-title" | "conventional" | "none" | "custom";
 export type TicketPopulateAgentPreference = "configured" | "claude" | "codex";
 export type TicketPopulateEnrichmentPolicy = "none" | "recommendations" | "agent";
 export type TicketSourceConfig = {
@@ -41,11 +43,27 @@ export interface TicketBuildSetupConfig {
     cleanup: boolean;
     auto_merge_wait: boolean;
     auto_merge_timeout_minutes: number | null;
+    base_branch: string;
+    branch_policy: {
+        mode: TicketBranchPolicyMode;
+        global_strategy: TicketBuildBranchStrategy;
+        by_size: Record<"XS" | "S" | "M" | "L" | "XL", "shared" | "per-ticket">;
+    };
+    review: {
+        title_style: TicketTitleStyle;
+        title_template: string | null;
+        description_sections: string[];
+    };
+    validation_checklist: string[];
 }
 export interface TicketsSetupConfig {
     sources: TicketSourceConfig[];
     populate: TicketPopulateSetupConfig;
     build: TicketBuildSetupConfig;
+    limits: {
+        implementation: number;
+        view: number;
+    };
 }
 export interface MinimalRafiConfigOptions {
     appName?: string;
@@ -59,11 +77,14 @@ export declare function loadTicketSetupConfig(projectDir: string): TicketsSetupC
 export declare function loadTicketSetupConfigWithDefaults(projectDir: string): TicketsSetupConfig;
 export declare function hasTicketSetupConfig(projectDir: string): boolean;
 export declare function saveTicketSetupConfig(projectDir: string, setup: TicketsSetupConfig, opts?: MinimalRafiConfigOptions): void;
+/** Synchronize pending setup limits into the tracker, once the tracker exists. */
+export declare function syncTicketLimits(projectDir: string, limits: TicketsSetupConfig["limits"]): void;
 export declare function ensureRafiConfigForTicketSetup(projectDir: string, opts?: MinimalRafiConfigOptions): Record<string, unknown>;
 export declare function normalizeTicketsSetupConfig(value: unknown, label?: string): TicketsSetupConfig;
 export declare function denormalizeTicketsSetupConfig(setup: TicketsSetupConfig): Record<string, unknown>;
 export declare function mergeTicketSetup(current: TicketsSetupConfig | undefined, patch: Partial<{
     sources: TicketSourceConfig[];
+    limits: TicketsSetupConfig["limits"];
     populate: Partial<TicketPopulateSetupConfig>;
     build: Partial<TicketBuildSetupConfig>;
 }>): TicketsSetupConfig;
@@ -88,4 +109,5 @@ export declare function configuredHarnessTargets(projectDir: string): HarnessTar
 export declare function detectPackageName(projectDir: string): string | undefined;
 export declare function defaultAppName(projectDir: string): string;
 export declare function detectGitProvider(projectDir: string): Exclude<TicketBuildProvider, "auto" | "local"> | undefined;
+export declare function detectDefaultBranch(projectDir: string): string;
 export declare function recommendedBuildDefaults(projectDir: string): TicketBuildSetupConfig;

package/dist/tickets/setupConfig.js

@@ -16,6 +16,7 @@ const SKILL_NAMES = [
 ];
 export const DEFAULT_TICKET_SETUP = {
     sources: [],
+    limits: { implementation: 500, view: 20_000 },
     populate: {
         source_handling: "saved",
         agent_preference: "configured",
@@ -33,6 +34,25 @@ export const DEFAULT_TICKET_SETUP = {
         cleanup: true,
         auto_merge_wait: false,
         auto_merge_timeout_minutes: null,
+        base_branch: "main",
+        branch_policy: {
+            mode: "global",
+            global_strategy: "branch-per-ticket",
+            by_size: { XS: "shared", S: "shared", M: "per-ticket", L: "per-ticket", XL: "per-ticket" },
+        },
+        review: {
+            title_style: "ticket-title",
+            title_template: null,
+            description_sections: ["Summary", "Linked ticket", "Changes made", "Tests and validation performed", "Risks or rollback notes", "Checklist"],
+        },
+        validation_checklist: [
+            "Acceptance criteria satisfied",
+            "Required tests pass",
+            "Configured project checks pass",
+            "Documentation updated when needed",
+            "Database and deployment changes reviewed when present",
+            "Validation evidence attached",
+        ],
     },
 };
 export function loadRafiConfigObject(projectDir) {
@@ -77,6 +97,18 @@ export function saveTicketSetupConfig(projectDir, setup, opts = {}) {
     mkdirSync(projectDir, { recursive: true });
     writeFileSync(join(projectDir, RAFI_CONFIG_FILE), stringify(config, { lineWidth: 100 }), "utf8");
 }
+/** Synchronize pending setup limits into the tracker, once the tracker exists. */
+export function syncTicketLimits(projectDir, limits) {
+    const path = join(projectDir, ".tickets", "config.yaml");
+    if (!existsSync(path))
+        return;
+    const raw = parse(readFileSync(path, "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`${path}: expected a YAML object`);
+    raw.implementation_limit = positiveInteger(limits.implementation, 500, "tickets.limits.implementation");
+    raw.view_limit = positiveInteger(limits.view, 20_000, "tickets.limits.view");
+    writeFileSync(path, stringify(raw, { lineWidth: 100 }), "utf8");
+}
 export function ensureRafiConfigForTicketSetup(projectDir, opts = {}) {
     const existing = loadRafiConfigObject(projectDir);
     if (existing)
@@ -95,6 +127,7 @@ export function normalizeTicketsSetupConfig(value, label = "tickets") {
     const raw = value;
     const setup = {
         sources: normalizeSources(raw.sources, `${label}.sources`),
+        limits: normalizeLimits(raw.limits, `${label}.limits`),
         populate: normalizePopulate(raw.populate, `${label}.populate`),
         build: normalizeBuild(raw.build, `${label}.build`),
     };
@@ -103,6 +136,7 @@ export function normalizeTicketsSetupConfig(value, label = "tickets") {
 export function denormalizeTicketsSetupConfig(setup) {
     return {
         sources: setup.sources.map((source) => ({ ...source })),
+        limits: { ...setup.limits },
         populate: { ...setup.populate },
         build: { ...setup.build },
     };
@@ -111,6 +145,7 @@ export function mergeTicketSetup(current, patch) {
     const base = current ? cloneTicketSetup(current) : cloneTicketSetup(DEFAULT_TICKET_SETUP);
     return normalizeTicketsSetupConfig({
         sources: patch.sources ?? base.sources,
+        limits: patch.limits ?? base.limits,
         populate: { ...base.populate, ...(patch.populate ?? {}) },
         build: { ...base.build, ...(patch.build ?? {}) },
     });
@@ -212,6 +247,22 @@ export function detectGitProvider(projectDir) {
     }
     return undefined;
 }
+export function detectDefaultBranch(projectDir) {
+    const attempts = [
+        ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"],
+        ["config", "--get", "init.defaultBranch"],
+        ["branch", "--show-current"],
+    ];
+    for (const args of attempts) {
+        try {
+            const value = execFileSync("git", args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+            if (value)
+                return value.replace(/^origin\//, "");
+        }
+        catch { /* try the next safe source */ }
+    }
+    return "main";
+}
 export function recommendedBuildDefaults(projectDir) {
     const provider = detectGitProvider(projectDir);
     return {
@@ -221,6 +272,7 @@ export function recommendedBuildDefaults(projectDir) {
         pr_ready: Boolean(provider),
         merge_method: "squash",
         cleanup: true,
+        base_branch: detectDefaultBranch(projectDir),
     };
 }
 function minimalRafiConfig(projectDir, opts) {
@@ -354,6 +406,45 @@ function normalizeBuild(value, label) {
         cleanup: booleanField(raw.cleanup, DEFAULT_TICKET_SETUP.build.cleanup, `${label}.cleanup`),
         auto_merge_wait: booleanField(raw.auto_merge_wait, DEFAULT_TICKET_SETUP.build.auto_merge_wait, `${label}.auto_merge_wait`),
         auto_merge_timeout_minutes: nullablePositiveInteger(raw.auto_merge_timeout_minutes, DEFAULT_TICKET_SETUP.build.auto_merge_timeout_minutes, `${label}.auto_merge_timeout_minutes`),
+        base_branch: stringField(raw.base_branch, DEFAULT_TICKET_SETUP.build.base_branch),
+        branch_policy: normalizeBranchPolicy(raw.branch_policy, raw.branch_strategy, `${label}.branch_policy`),
+        review: normalizeReview(raw.review, `${label}.review`),
+        validation_checklist: stringArray(raw.validation_checklist, DEFAULT_TICKET_SETUP.build.validation_checklist, `${label}.validation_checklist`),
+    };
+}
+function normalizeLimits(value, label) {
+    const raw = objectOrEmpty(value, label);
+    return {
+        implementation: positiveInteger(raw.implementation, DEFAULT_TICKET_SETUP.limits.implementation, `${label}.implementation`),
+        view: positiveInteger(raw.view, DEFAULT_TICKET_SETUP.limits.view, `${label}.view`),
+    };
+}
+function normalizeBranchPolicy(value, legacyStrategy, label) {
+    const raw = objectOrEmpty(value, label);
+    const sizes = objectOrEmpty(raw.by_size, `${label}.by_size`);
+    const globalStrategy = enumField(raw.global_strategy ?? legacyStrategy, ["current", "batch", "branch-per-ticket"], DEFAULT_TICKET_SETUP.build.branch_policy.global_strategy, `${label}.global_strategy`);
+    return {
+        mode: enumField(raw.mode, ["global", "size"], DEFAULT_TICKET_SETUP.build.branch_policy.mode, `${label}.mode`),
+        global_strategy: globalStrategy,
+        by_size: {
+            XS: enumField(sizes.XS, ["shared", "per-ticket"], "shared", `${label}.by_size.XS`),
+            S: enumField(sizes.S, ["shared", "per-ticket"], "shared", `${label}.by_size.S`),
+            M: enumField(sizes.M, ["shared", "per-ticket"], "per-ticket", `${label}.by_size.M`),
+            L: enumField(sizes.L, ["shared", "per-ticket"], "per-ticket", `${label}.by_size.L`),
+            XL: enumField(sizes.XL, ["shared", "per-ticket"], "per-ticket", `${label}.by_size.XL`),
+        },
+    };
+}
+function normalizeReview(value, label) {
+    const raw = objectOrEmpty(value, label);
+    const titleStyle = enumField(raw.title_style, ["ticket-title", "conventional", "none", "custom"], DEFAULT_TICKET_SETUP.build.review.title_style, `${label}.title_style`);
+    const titleTemplate = nullableString(raw.title_template);
+    if (titleStyle === "custom" && !titleTemplate)
+        throw new Error(`${label}.title_template: required for custom title style`);
+    return {
+        title_style: titleStyle,
+        title_template: titleTemplate,
+        description_sections: stringArray(raw.description_sections, DEFAULT_TICKET_SETUP.build.review.description_sections, `${label}.description_sections`),
     };
 }
 function objectOrEmpty(value, label) {
@@ -418,6 +509,13 @@ function nullablePositiveInteger(value, fallback, label) {
         return Number(value);
     throw new Error(`${label}: expected a positive integer or null`);
 }
+function stringArray(value, fallback, label) {
+    if (value === undefined)
+        return [...fallback];
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item.trim()))
+        throw new Error(`${label}: expected non-empty strings`);
+    return [...new Set(value.map((item) => String(item).trim()))];
+}
 function normalizeTargets(value) {
     if (!Array.isArray(value))
         return [];
@@ -431,8 +529,14 @@ function normalizeTargets(value) {
 function cloneTicketSetup(setup) {
     return {
         sources: setup.sources.map((source) => ({ ...source, ...(source.type === "local" ? { paths: [...source.paths] } : {}) })),
+        limits: { ...setup.limits },
         populate: { ...setup.populate },
-        build: { ...setup.build },
+        build: {
+            ...setup.build,
+            branch_policy: { ...setup.build.branch_policy, by_size: { ...setup.build.branch_policy.by_size } },
+            review: { ...setup.build.review, description_sections: [...setup.build.review.description_sections] },
+            validation_checklist: [...setup.build.validation_checklist],
+        },
     };
 }
 function unique(values) {

package/dist/tickets/stateDb.d.ts

@@ -89,6 +89,8 @@ export interface OperationReceipt {
     completed_at: string;
     payload_json: string;
 }
+/** The only valid initial/fully-reset active state for a ticket. */
+export declare function pristineTicketState(ticketId: string, now: string, actor?: string | null): TicketState;
 export declare class StateDb {
     private db;
     constructor(dbPath: string);
@@ -96,17 +98,22 @@ export declare class StateDb {
     close(): void;
     getState(ticketId: string): TicketState | undefined;
     getAllStates(): Map<string, TicketState>;
+    deleteState(ticketId: string): void;
     upsertState(ticketId: string, patch: Partial<Omit<TicketState, "ticket_id">>, now: string): void;
-    insertEvent(event: Omit<TicketEvent, "id">): void;
+    insertEvent(event: Omit<TicketEvent, "id">): number;
+    deleteEvents(ids: number[]): void;
     getRecentEvents(limit: number): TicketEvent[];
+    getTicketEvents(ticketId: string): TicketEvent[];
     insertValidationSnapshot(snap: Omit<ValidationSnapshot, "id">): void;
     getRecentValidationSnapshot(): ValidationSnapshot | undefined;
+    getValidationSnapshots(scope?: string): ValidationSnapshot[];
     insertFutureWork(item: Omit<FutureWorkItem, "id">): number;
     getFutureWork(): FutureWorkItem[];
     getFutureWorkById(id: number): FutureWorkItem | undefined;
     updateFutureWorkDisposition(id: number, disposition: string): void;
     getRecentCompleted(): RecentCompletedContext[];
     upsertRecentCompleted(row: RecentCompletedContext): void;
+    deleteRecentCompleted(ticketId: string): void;
     getArchiveIndex(): ArchiveIndexEntry[];
     insertReviewRecommendation(item: Omit<ReviewRecommendation, "id">): number;
     getReviewRecommendations(status?: ReviewRecommendationStatus): ReviewRecommendation[];

package/dist/tickets/stateDb.js

@@ -1,6 +1,31 @@
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
+/** The only valid initial/fully-reset active state for a ticket. */
+export function pristineTicketState(ticketId, now, actor = null) {
+    return {
+        ticket_id: ticketId,
+        status: "planned",
+        owner: null,
+        current_step: null,
+        next_action: null,
+        blocked_by_json: "[]",
+        blocker_type: null,
+        blocker_notes: null,
+        first_blocked_at: null,
+        last_checked_at: null,
+        last_worked_at: null,
+        completed_at: null,
+        attempt_count: 0,
+        last_error: null,
+        evidence: null,
+        validation_result: null,
+        validation_commands: null,
+        validation_notes: null,
+        updated_at: now,
+        updated_by: actor,
+    };
+}
 const INIT_SQL = `
 PRAGMA foreign_keys = ON;
 
@@ -160,30 +185,12 @@ export class StateDb {
             m.set(row.ticket_id, row);
         return m;
     }
+    deleteState(ticketId) {
+        this.db.prepare("DELETE FROM ticket_state WHERE ticket_id = ?").run(ticketId);
+    }
     upsertState(ticketId, patch, now) {
         const existing = this.getState(ticketId);
-        const base = existing ?? {
-            ticket_id: ticketId,
-            status: "planned",
-            owner: null,
-            current_step: null,
-            next_action: null,
-            blocked_by_json: "[]",
-            blocker_type: null,
-            blocker_notes: null,
-            first_blocked_at: null,
-            last_checked_at: null,
-            last_worked_at: null,
-            completed_at: null,
-            attempt_count: 0,
-            last_error: null,
-            evidence: null,
-            validation_result: null,
-            validation_commands: null,
-            validation_notes: null,
-            updated_at: now,
-            updated_by: null,
-        };
+        const base = existing ?? pristineTicketState(ticketId, now);
         const merged = { ...base, ...patch, ticket_id: ticketId, updated_at: now };
         if (existing) {
             this.db.prepare(`
@@ -218,7 +225,7 @@ export class StateDb {
     }
     // ── ticket_events ─────────────────────────────────────────────────────────
     insertEvent(event) {
-        this.db.prepare(`
+        const result = this.db.prepare(`
       INSERT INTO ticket_events (
         timestamp,actor,ticket_id,event_type,old_status,new_status,
         summary,validation,evidence,payload_json
@@ -227,12 +234,23 @@ export class StateDb {
         @summary,@validation,@evidence,@payload_json
       )
     `).run(event);
+        return Number(result.lastInsertRowid);
+    }
+    deleteEvents(ids) {
+        const remove = this.db.prepare("DELETE FROM ticket_events WHERE id = ?");
+        for (const id of ids)
+            remove.run(id);
     }
     getRecentEvents(limit) {
         return this.db
             .prepare("SELECT * FROM ticket_events ORDER BY timestamp DESC, id DESC LIMIT ?")
             .all(limit);
     }
+    getTicketEvents(ticketId) {
+        return this.db
+            .prepare("SELECT * FROM ticket_events WHERE ticket_id = ? ORDER BY timestamp, id")
+            .all(ticketId);
+    }
     // ── validation_snapshots ──────────────────────────────────────────────────
     insertValidationSnapshot(snap) {
         this.db.prepare(`
@@ -245,6 +263,16 @@ export class StateDb {
             .prepare("SELECT * FROM validation_snapshots ORDER BY timestamp DESC, id DESC LIMIT 1")
             .get();
     }
+    getValidationSnapshots(scope) {
+        if (scope !== undefined) {
+            return this.db
+                .prepare("SELECT * FROM validation_snapshots WHERE scope = ? ORDER BY timestamp, id")
+                .all(scope);
+        }
+        return this.db
+            .prepare("SELECT * FROM validation_snapshots ORDER BY timestamp, id")
+            .all();
+    }
     // ── future_work ───────────────────────────────────────────────────────────
     insertFutureWork(item) {
         const r = this.db.prepare(`
@@ -287,6 +315,9 @@ export class StateDb {
         updated_at=excluded.updated_at
     `).run(row);
     }
+    deleteRecentCompleted(ticketId) {
+        this.db.prepare("DELETE FROM recent_completed_context WHERE ticket_id = ?").run(ticketId);
+    }
     // ── archive_index ─────────────────────────────────────────────────────────
     getArchiveIndex() {
         return this.db