ai-foreman 1.7.6 → 1.7.7

package/dist/tickets/groupReset.js

@@ -0,0 +1,279 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stringify } from "yaml";
+import { recoverableBuildRuns } from "../buildRuns.js";
+import { WorkflowDb } from "../workflowDb.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
+import { renderProgressDoc, writeProgressDoc } from "./renderMarkdown.js";
+import { StateDb, pristineTicketState } from "./stateDb.js";
+import { loadTickets, validateTicketDefs } from "./ticketLoader.js";
+export class TicketResetDependencyConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        super(`cannot restore deleted ticket definitions atomically: ${conflicts.map((conflict) => `${conflict.ticketId} depends on missing ${conflict.dependencyId}`).join("; ")}`);
+        this.conflicts = conflicts;
+    }
+}
+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"],
+};
+/** Resolve a requested target exactly once into immutable groups, rows, and restorations. */
+export function resolveTicketResetSelection(projectDir, requested, options = {}, now = new Date()) {
+    const opened = open(projectDir);
+    const { definitions, db } = opened;
+    try {
+        db.ensureSyntheticLegacyGroup(definitions, now);
+        const groupCatalog = db.listTicketGroups();
+        const groups = selectGroups(groupCatalog, requested);
+        const current = new Map(definitions.map((definition) => [definition.id, definition]));
+        const snapshots = new Map(groupCatalog.flatMap((group) => group.members.map((member) => [member.ticketId, member.snapshot])));
+        const states = db.getAllStates();
+        const targetIds = selectTicketIds(requested, groups, definitions, states);
+        const selectedGroupIds = new Set(groups.map((group) => group.id));
+        const restoreDependencies = new Set(options.restoreDependencies ?? []);
+        const definitionRestorations = [];
+        const previewRows = [];
+        for (const ticketId of targetIds) {
+            const definition = current.get(ticketId);
+            const snapshot = snapshots.get(ticketId);
+            if (!definition && !snapshot)
+                throw new Error(`ticket ${ticketId} is missing and has no valid Rafi definition snapshot`);
+            const policy = options.perTicket?.[ticketId] ?? options.deletedTickets ?? "ignore";
+            const restore = !definition && policy === "restore";
+            if (restore && snapshot)
+                definitionRestorations.push({ ticketId, digest: snapshot.digest, restore: true });
+            const display = definition ?? snapshot?.definition;
+            previewRows.push({
+                ticketId,
+                title: display?.title ?? "(definition unavailable)",
+                status: states.get(ticketId)?.status ?? "planned",
+                definitionMissing: !definition,
+                restoreDefinition: restore,
+            });
+        }
+        for (const dependencyId of restoreDependencies) {
+            if (current.has(dependencyId))
+                continue;
+            const snapshot = snapshots.get(dependencyId);
+            if (!snapshot)
+                throw new Error(`deleted dependency ${dependencyId} has no valid Rafi definition snapshot`);
+            if (!definitionRestorations.some((item) => item.ticketId === dependencyId))
+                definitionRestorations.push({ ticketId: dependencyId, digest: snapshot.digest, restore: true, dependencyOnly: !targetIds.includes(dependencyId) });
+        }
+        const restoredIds = new Set(definitionRestorations.filter((item) => item.restore).map((item) => item.ticketId));
+        const conflicts = [];
+        for (const restoration of definitionRestorations.filter((item) => item.restore && !item.dependencyOnly)) {
+            const restored = snapshots.get(restoration.ticketId)?.definition;
+            for (const dependencyId of restored.depends_on ?? []) {
+                if (!current.has(dependencyId) && !restoredIds.has(dependencyId))
+                    conflicts.push({ ticketId: restoration.ticketId, dependencyId });
+            }
+        }
+        if (conflicts.length)
+            throw new TicketResetDependencyConflictError(conflicts);
+        const selectedIds = new Set(targetIds);
+        const relatedRuns = recoverableBuildRuns(projectDir, now)
+            .filter((run) => run.tickets.some((ticketId) => selectedIds.has(ticketId)))
+            .map((run) => ({ runId: run.runId, status: run.status, tickets: [...run.tickets] }));
+        const base = {
+            version: 1, requested, resolvedAt: now.toISOString(),
+            groups: groups.map((group) => ({ id: group.id, sequence: group.sequence, memberTicketIds: group.members.map((member) => member.ticketId) })),
+            ticketIds: targetIds,
+            previewRows,
+            definitionRestorations,
+            relatedRuns,
+        };
+        return { ...base, inputFingerprint: selectionFingerprint(base, current, states, snapshots, groupCatalog) };
+    }
+    finally {
+        db.close();
+    }
+}
+export function applyResolvedTicketReset(projectDir, selection, actor = "user", now = new Date(), hooks = {}) {
+    const opened = open(projectDir);
+    const { config, paths, definitions, db } = opened;
+    const workflow = new WorkflowDb(projectDir);
+    const resetId = hooks.resetId ?? randomUUID();
+    const current = new Map(definitions.map((definition) => [definition.id, definition]));
+    const groupCatalog = db.listTicketGroups();
+    const snapshots = new Map(groupCatalog.flatMap((group) => group.members.map((member) => [member.ticketId, member.snapshot])));
+    const states = db.getAllStates();
+    const selectedIds = new Set(selection.ticketIds);
+    const currentRelatedRuns = recoverableBuildRuns(projectDir, now)
+        .filter((run) => run.tickets.some((ticketId) => selectedIds.has(ticketId)))
+        .map((run) => ({ runId: run.runId, status: run.status, tickets: [...run.tickets] }));
+    const comparable = { ...selection, relatedRuns: currentRelatedRuns };
+    delete comparable.inputFingerprint;
+    const actualFingerprint = selectionFingerprint(comparable, current, states, snapshots, groupCatalog);
+    if (actualFingerprint !== selection.inputFingerprint) {
+        db.close();
+        workflow.close();
+        throw new Error("ticket/group/reset inputs changed after preview; no reset was applied—preview the exact selection again");
+    }
+    const restore = selection.definitionRestorations.filter((item) => item.restore);
+    const restored = restore.map((item) => item.ticketId);
+    const restoredSet = new Set(restored);
+    const restoredDefinitions = restore.map((item) => snapshots.get(item.ticketId)?.definition);
+    if (restoredDefinitions.some((item) => !item)) {
+        db.close();
+        workflow.close();
+        throw new Error("a selected definition snapshot became unavailable");
+    }
+    const nextDefinitions = [...definitions, ...restoredDefinitions.filter((definition) => !current.has(definition.id))].sort((a, b) => a.order - b.order);
+    const definitionIssues = validateTicketDefs(nextDefinitions);
+    if (definitionIssues.length) {
+        db.close();
+        workflow.close();
+        throw new Error(`restored ticket definitions are invalid: ${definitionIssues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+    }
+    const resettable = selection.ticketIds.filter((ticketId) => current.has(ticketId) || restoredSet.has(ticketId));
+    const ignoredMissing = selection.ticketIds.filter((ticketId) => !current.has(ticketId) && !restoredSet.has(ticketId));
+    if (resettable.length === 0 && restored.length === 0) {
+        db.close();
+        workflow.close();
+        return { resetId, tickets: [], restored: [], ignoredMissing };
+    }
+    const stageDir = join(projectDir, ".rafi", "reset-stage", resetId);
+    const stagedDefinitions = join(stageDir, "tickets.yaml");
+    const stagedProgress = join(stageDir, "progress.md");
+    const definitionsBefore = existsSync(paths.tickets) ? readFileSync(paths.tickets) : undefined;
+    const progressBefore = existsSync(paths.progressDoc) ? readFileSync(paths.progressDoc) : undefined;
+    const oldStates = new Map([...new Set([...resettable, ...restored])].map((ticketId) => [ticketId, db.getState(ticketId)]));
+    const oldRecent = db.getRecentCompleted().filter((row) => resettable.includes(row.ticket_id));
+    const eventIds = [];
+    const run = workflow.createRun({ kind: "recovery", checkpoint: "group-reset-intent", originalWork: selection, remainingWork: { tickets: resettable }, state: { resetId } }, now);
+    const publication = workflow.beginPublication(run.runId, { operation: "group-ticket-reset", resetId, selection, stagedDefinitions, stagedProgress, definitionsTarget: paths.tickets, progressTarget: paths.progressDoc }, { definitions: digest(definitionsBefore), progress: digest(progressBefore) }, now);
+    try {
+        const stamp = now.toISOString();
+        db.transaction(() => {
+            for (const definition of restoredDefinitions)
+                if (!db.getState(definition.id))
+                    db.upsertState(definition.id, pristineTicketState(definition.id, stamp, actor), stamp);
+            for (const row of selection.previewRows) {
+                if (!resettable.includes(row.ticketId)) {
+                    eventIds.push(db.insertEvent({ timestamp: stamp, actor, ticket_id: row.ticketId, event_type: "ticket_reset_skipped_missing", old_status: row.status, new_status: row.status, summary: `Skipped missing definition ${row.ticketId}`, validation: null, evidence: null, payload_json: JSON.stringify({ reset_id: resetId, input_fingerprint: selection.inputFingerprint }) }));
+                    continue;
+                }
+                const old = db.getState(row.ticketId)?.status ?? row.status;
+                db.upsertState(row.ticketId, pristineTicketState(row.ticketId, stamp, actor), stamp);
+                db.deleteRecentCompleted(row.ticketId);
+                eventIds.push(db.insertEvent({ timestamp: stamp, actor, ticket_id: row.ticketId, event_type: "ticket_reset", old_status: old, new_status: "planned", summary: `Reset ${row.ticketId} from approved immutable selection`, validation: null, evidence: null, payload_json: JSON.stringify({ reset_id: resetId, groups: selection.groups.map((group) => group.id), restored_definition: restoredSet.has(row.ticketId), input_fingerprint: selection.inputFingerprint }) }));
+            }
+        });
+        mkdirSync(stageDir, { recursive: true });
+        writeFileSync(stagedDefinitions, stringify({ tickets: nextDefinitions }, { lineWidth: 120 }), "utf8");
+        writeFileSync(stagedProgress, renderProgressDoc({ config, projectDir, ticketDefs: nextDefinitions, states: db.getAllStates(), db, now: stamp }), "utf8");
+        workflow.updatePublication(publication.transactionId, "staged", now);
+        workflow.updatePublication(publication.transactionId, "tracker_committed", now);
+        hooks.beforePublish?.();
+        atomicCopy(stagedDefinitions, paths.tickets);
+        writeProgressDoc(paths.progressDoc, readFileSync(stagedProgress, "utf8"), true);
+        workflow.updatePublication(publication.transactionId, "published", now);
+        workflow.updatePublication(publication.transactionId, "committed", now);
+        workflow.transition(run.runId, { status: "completed", checkpoint: "group-reset-committed", remainingWork: {}, state: { resetId, tickets: resettable, restored, ignoredMissing } }, now);
+        rmSync(stageDir, { recursive: true, force: true });
+        return { resetId, tickets: resettable, restored, ignoredMissing };
+    }
+    catch (error) {
+        db.transaction(() => {
+            db.deleteEvents(eventIds);
+            for (const [ticketId, state] of oldStates)
+                state ? db.upsertState(ticketId, state, state.updated_at) : db.deleteState(ticketId);
+            for (const row of oldRecent)
+                db.upsertRecentCompleted(row);
+        });
+        restoreFile(paths.tickets, definitionsBefore);
+        restoreFile(paths.progressDoc, progressBefore);
+        workflow.updatePublication(publication.transactionId, "rolled_back", now);
+        workflow.transition(run.runId, { status: "failed", checkpoint: "group-reset-rolled-back", state: { resetId, error: error instanceof Error ? error.message : String(error) } }, now);
+        rmSync(stageDir, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        db.close();
+        workflow.close();
+    }
+}
+function selectGroups(groups, requested) {
+    if (requested.kind === "all-groups")
+        return groups;
+    if (requested.kind === "recent-groups") {
+        if (!Number.isInteger(requested.count) || requested.count < 1)
+            throw new Error("recent group count must be a positive integer");
+        return groups.slice(0, requested.count);
+    }
+    if (requested.kind === "group") {
+        const group = groups.find((candidate) => candidate.id === requested.groupId);
+        if (!group)
+            throw new Error(`ticket group ${requested.groupId} not found`);
+        return [group];
+    }
+    if (requested.kind === "group-index") {
+        if (!Number.isInteger(requested.position) || requested.position < 1)
+            throw new Error("group index must be a positive 1-based position");
+        const group = groups[requested.position - 1];
+        if (!group)
+            throw new Error(`ticket group index ${requested.position} not found`);
+        return [group];
+    }
+    return [];
+}
+function selectTicketIds(requested, groups, definitions, states) {
+    if (["all-groups", "recent-groups", "group", "group-index"].includes(requested.kind))
+        return [...new Set(groups.flatMap((group) => group.members.map((member) => member.ticketId)))];
+    if (requested.kind === "ticket") {
+        if (!definitions.some((definition) => definition.id === requested.ticketId))
+            throw new Error(`Ticket ${requested.ticketId} not found. Run \`rafi tickets queue\` to list tickets.`);
+        return [requested.ticketId];
+    }
+    if (requested.kind === "run") {
+        const known = new Set(definitions.map((definition) => definition.id));
+        const missing = requested.ticketIds.filter((ticketId) => !known.has(ticketId));
+        if (missing.length)
+            throw new Error(`Tickets not found: ${missing.join(", ")}`);
+        return [...new Set(requested.ticketIds)];
+    }
+    if (requested.kind !== "scope")
+        throw new Error(`unsupported reset target: ${requested.kind}`);
+    const statuses = new Set(SCOPE_STATUSES[requested.scope]);
+    return definitions.filter((definition) => statuses.has(states.get(definition.id)?.status ?? "planned")).map((definition) => definition.id);
+}
+function selectionFingerprint(base, definitions, states, snapshots, groups) {
+    const relevant = [...new Set([...base.ticketIds, ...base.definitionRestorations.map((item) => item.ticketId)])].sort();
+    return hash({
+        requested: base.requested,
+        groups: base.groups,
+        groupCatalog: groups.map((group) => ({
+            id: group.id, sequence: group.sequence, origin: group.origin, createdAt: group.createdAt, legacy: group.legacy, operationId: group.operationId,
+            members: group.members.map((member) => ({ ticketId: member.ticketId, position: member.position, snapshotDigest: member.snapshot.digest })),
+        })),
+        definitionCatalog: [...definitions.entries()].sort(([a], [b]) => a.localeCompare(b)),
+        tickets: relevant.map((ticketId) => ({ ticketId, definition: definitions.get(ticketId) ?? null, state: states.get(ticketId) ?? null, snapshotDigest: snapshots.get(ticketId)?.digest ?? null })),
+        relatedRuns: base.relatedRuns,
+        restorations: base.definitionRestorations,
+    });
+}
+function open(projectDir) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    return { config, paths, definitions: loadTickets(paths.tickets), db: new StateDb(paths.stateDb) };
+}
+function hash(value) { return createHash("sha256").update(stableJson(value)).digest("hex"); }
+function digest(value) { return value ? createHash("sha256").update(value).digest("hex") : null; }
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+function atomicCopy(source, target) { mkdirSync(dirname(target), { recursive: true }); const temp = `${target}.${process.pid}.${randomUUID()}.tmp`; writeFileSync(temp, readFileSync(source)); renameSync(temp, target); }
+function restoreFile(path, value) { if (value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, value);
+}
+else
+    rmSync(path, { force: true }); }

package/dist/tickets/groups.d.ts

@@ -0,0 +1,36 @@
+import type { TicketGroup, TicketGroupId } from "rafi-spec";
+import { type TicketStatus } from "./stateDb.js";
+export interface TicketGroupListMember {
+    ticketId: string;
+    position: number;
+    definitionMissing: boolean;
+    snapshotDigest: string;
+    status: TicketStatus;
+}
+export interface TicketGroupListRow {
+    id: TicketGroupId;
+    recencyPosition: number;
+    origin: TicketGroup["origin"];
+    createdAt: string;
+    legacy: boolean;
+    members: TicketGroupListMember[];
+    statusTotals: Partial<Record<TicketStatus, number>>;
+    recoverableRuns: Array<{
+        runId: string;
+        status: string;
+        tickets: string[];
+    }>;
+}
+export interface TicketGroupListEnvelope {
+    version: 1;
+    generatedAt: string;
+    groups: TicketGroupListRow[];
+}
+export declare function listTicketGroups(projectDir: string, now?: Date): TicketGroupListEnvelope;
+export interface TicketGroupRepairPreview {
+    version: 1;
+    ticketIds: string[];
+    inputFingerprint: string;
+}
+export declare function previewTicketGroupRepair(projectDir: string): TicketGroupRepairPreview;
+export declare function repairTicketGroups(projectDir: string, expectedFingerprint: string, now?: Date): TicketGroup | undefined;

package/dist/tickets/groups.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { recoverableBuildRuns } from "../buildRuns.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
+import { StateDb, pristineTicketState } from "./stateDb.js";
+import { loadTickets } from "./ticketLoader.js";
+export function listTicketGroups(projectDir, now = new Date()) {
+    const { definitions, db } = open(projectDir);
+    try {
+        db.ensureSyntheticLegacyGroup(definitions, now);
+        const current = new Map(definitions.map((definition) => [definition.id, definition]));
+        const states = db.getAllStates();
+        const runs = recoverableBuildRuns(projectDir, now);
+        const groups = db.listTicketGroups().map((group, index) => {
+            const members = group.members.map((member) => ({
+                ticketId: member.ticketId,
+                position: member.position,
+                definitionMissing: !current.has(member.ticketId),
+                snapshotDigest: member.snapshot.digest,
+                status: states.get(member.ticketId)?.status ?? pristineTicketState(member.ticketId, now.toISOString()).status,
+            }));
+            const memberIds = new Set(members.map((member) => member.ticketId));
+            const statusTotals = {};
+            for (const member of members)
+                statusTotals[member.status] = (statusTotals[member.status] ?? 0) + 1;
+            return {
+                id: group.id, recencyPosition: index + 1, origin: group.origin, createdAt: group.createdAt, legacy: group.legacy,
+                members, statusTotals,
+                recoverableRuns: runs.filter((run) => run.tickets.some((ticket) => memberIds.has(ticket))).map((run) => ({ runId: run.runId, status: run.status, tickets: [...run.tickets] })),
+            };
+        });
+        return { version: 1, generatedAt: now.toISOString(), groups };
+    }
+    finally {
+        db.close();
+    }
+}
+export function previewTicketGroupRepair(projectDir) {
+    const { definitions, db } = open(projectDir);
+    try {
+        db.ensureSyntheticLegacyGroup(definitions);
+        const ticketIds = db.ungroupedTicketIds(definitions.map((definition) => definition.id));
+        return { version: 1, ticketIds, inputFingerprint: repairFingerprint(definitions.filter((definition) => ticketIds.includes(definition.id))) };
+    }
+    finally {
+        db.close();
+    }
+}
+export function repairTicketGroups(projectDir, expectedFingerprint, now = new Date()) {
+    const { definitions, db } = open(projectDir);
+    try {
+        const ticketIds = db.ungroupedTicketIds(definitions.map((definition) => definition.id));
+        const selected = definitions.filter((definition) => ticketIds.includes(definition.id));
+        const actual = repairFingerprint(selected);
+        if (actual !== expectedFingerprint)
+            throw new Error("ticket definitions changed after the repair preview; preview again before approving");
+        return db.repairTicketGroups(selected, `ticket-groups:repair:${actual}`, now);
+    }
+    finally {
+        db.close();
+    }
+}
+function repairFingerprint(definitions) {
+    return createHash("sha256").update(JSON.stringify(definitions.map((definition) => [definition.id, definition]).sort(([a], [b]) => String(a).localeCompare(String(b))))).digest("hex");
+}
+function open(projectDir) {
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    return { definitions: loadTickets(paths.tickets), db: new StateDb(paths.stateDb) };
+}

package/dist/tickets/importer.js

@@ -6,6 +6,7 @@ import { nowTimestamp } from "./events.js";
 import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
 import { insertXlSplitRecommendations } from "./recommendations.js";
 import { currentActivity, withActivityPhase } from "../activity.js";
+import { createHash } from "node:crypto";
 export function importFromMarkdown(_progressDocPath) {
     throw new Error("foreman tickets import is not yet implemented.\n\n" +
         "To start fresh:\n" +
@@ -157,6 +158,9 @@ export function applyImportedItems(projectDir, items) {
     const db = new StateDb(paths.stateDb);
     let created = 0;
     let updated = 0;
+    const createdTickets = [];
+    const statePatches = [];
+    let definitionsPublished = false;
     try {
         let nextNumber = nextTicketNumber(tickets);
         let nextOrder = nextTicketOrder(tickets);
@@ -171,7 +175,9 @@ export function applyImportedItems(projectDir, items) {
                 const id = `T${String(nextNumber++).padStart(3, "0")}`;
                 const order = nextOrder;
                 nextOrder += 1000;
-                tickets.push(importedItemToTicket(item, id, order));
+                const createdTicket = importedItemToTicket(item, id, order);
+                tickets.push(createdTicket);
+                createdTickets.push(createdTicket);
                 created++;
             }
             const ticket = matchIndex >= 0 ? tickets[matchIndex] : tickets[tickets.length - 1];
@@ -186,16 +192,34 @@ export function applyImportedItems(projectDir, items) {
                     patch.validation_result = "not_applicable";
                     patch.validation_notes = "External tracker marked this item complete before import.";
                 }
-                db.upsertState(ticket.id, patch, now);
+                statePatches.push({ ticketId: ticket.id, patch });
             }
         }
         const errors = validateTicketDefs(tickets).filter((issue) => issue.message);
         if (errors.length > 0) {
             throw new Error(`import produced invalid tickets:\n${errors.map((err) => `- ${err.path}: ${err.message}`).join("\n")}`);
         }
-        saveTickets(paths.tickets, tickets);
+        db.transaction(() => {
+            for (const { ticketId, patch } of statePatches)
+                db.upsertState(ticketId, patch, now);
+            db.ensureSyntheticLegacyGroup(existing);
+            if (createdTickets.length) {
+                const operationDigest = createHash("sha256").update(JSON.stringify(items.map((item) => [item.provider, item.providerId]))).digest("hex");
+                db.createTicketGroup({ origin: "import", operationId: `ticket-import:${operationDigest}`, createdAt: now, members: createdTickets.map((ticket) => ({ ticketId: ticket.id, definition: ticket, validatedAt: now })) });
+            }
+            saveTickets(paths.tickets, tickets);
+            definitionsPublished = true;
+            for (const ticket of tickets)
+                if (db.getTicketGroupForTicket(ticket.id))
+                    db.updateTicketDefinitionSnapshot(ticket.id, ticket, now);
+        });
         return { created, updated, tickets };
     }
+    catch (error) {
+        if (definitionsPublished)
+            saveTickets(paths.tickets, existing);
+        throw error;
+    }
     finally {
         db.close();
     }

package/dist/tickets/recommendations.js

@@ -3,6 +3,7 @@ import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
 import { StateDb } from "./stateDb.js";
 import { nowTimestamp } from "./events.js";
 import { renderAndWrite } from "./renderMarkdown.js";
+import { createHash } from "node:crypto";
 export function createReviewRecommendation(db, now, input) {
     return db.insertReviewRecommendation({
         created_at: now,
@@ -38,19 +39,42 @@ export function cmdReviewRecommendations(projectDir, opts = {}) {
             return { pending, changed: 0, action: opts.action };
         const now = nowTimestamp(config.timezone);
         if (opts.action === "accept") {
-            let tickets = loadTickets(paths.tickets);
+            const before = loadTickets(paths.tickets);
+            db.ensureSyntheticLegacyGroup(before);
+            let tickets = before;
+            const requestedAdditions = new Set();
             for (const rec of selected) {
-                tickets = applyRecommendationPatch(tickets, parseRecommendationPatch(rec));
+                const patch = parseRecommendationPatch(rec);
+                for (const ticket of patch.add ?? [])
+                    requestedAdditions.add(ticket.id);
+                tickets = applyRecommendationPatch(tickets, patch);
             }
             const issues = validateTicketDefs(tickets);
             if (issues.length > 0) {
                 throw new Error(`accepted recommendation produced invalid tickets:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`);
             }
-            saveTickets(paths.tickets, tickets);
-            db.transaction(() => {
-                for (const rec of selected)
-                    db.updateReviewRecommendationStatus(rec.id, "accepted", now);
-            });
+            let definitionsPublished = false;
+            try {
+                db.transaction(() => {
+                    const additions = tickets.filter((ticket) => requestedAdditions.has(ticket.id) && !db.getTicketGroupForTicket(ticket.id));
+                    if (additions.length) {
+                        const operationDigest = createHash("sha256").update(JSON.stringify(selected.map((rec) => rec.id).sort())).digest("hex");
+                        db.createTicketGroup({ origin: "production", operationId: `recommendations:${operationDigest}`, createdAt: now, members: additions.map((ticket) => ({ ticketId: ticket.id, definition: ticket, validatedAt: now })) });
+                    }
+                    saveTickets(paths.tickets, tickets);
+                    definitionsPublished = true;
+                    for (const ticket of tickets)
+                        if (db.getTicketGroupForTicket(ticket.id))
+                            db.updateTicketDefinitionSnapshot(ticket.id, ticket, now);
+                    for (const rec of selected)
+                        db.updateReviewRecommendationStatus(rec.id, "accepted", now);
+                });
+            }
+            catch (error) {
+                if (definitionsPublished)
+                    saveTickets(paths.tickets, before);
+                throw error;
+            }
             const states = db.getAllStates();
             renderAndWrite({ config, projectDir, ticketDefs: tickets, states, db });
         }

package/dist/tickets/reset.d.ts

@@ -25,3 +25,4 @@ export declare function resetTickets(projectDir: string, target: string | Ticket
 };
 /** Finish or roll back a reset publication left incomplete by process interruption. */
 export declare function recoverTicketResetPublications(projectDir: string): string[];
+export { applyResolvedTicketReset, resolveTicketResetSelection, TicketResetDependencyConflictError, type DeletedDependencyConflict, type ResolveGroupResetOptions, } from "./groupReset.js";

package/dist/tickets/reset.js

@@ -211,3 +211,4 @@ function activeFieldCategories(state) {
 function digest(value) {
     return value ? createHash("sha256").update(value).digest("hex") : null;
 }
+export { applyResolvedTicketReset, resolveTicketResetSelection, TicketResetDependencyConflictError, } from "./groupReset.js";

package/dist/tickets/setupConfig.d.ts

@@ -44,6 +44,7 @@ export interface TicketBuildSetupConfig {
     auto_merge_wait: boolean;
     auto_merge_timeout_minutes: number | null;
     base_branch: string;
+    branch_prefix: string;
     branch_policy: {
         mode: TicketBranchPolicyMode;
         global_strategy: TicketBuildBranchStrategy;

package/dist/tickets/setupConfig.js

@@ -1,14 +1,17 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { parse, stringify } from "yaml";
 import { loadDefaults } from "special-agents";
 import { appendLegacyTicketSources, loadSourceRegistry } from "../sources/sourceRegistry.js";
+import { BUILTIN_BRANCH_PREFIX, validateBranchPrefix } from "../branch/prefix.js";
 export const RAFI_CONFIG_FILE = "rafi-config.yaml";
 const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker", "uninstaller"];
 const SKILL_NAMES = [
     "better-sqlite3-rebuild",
     "grill-me",
+    "handoff",
     "improve-codebase-architecture",
     "prd-to-issues",
     "tdd",
@@ -35,6 +38,7 @@ export const DEFAULT_TICKET_SETUP = {
         auto_merge_wait: false,
         auto_merge_timeout_minutes: null,
         base_branch: "main",
+        branch_prefix: BUILTIN_BRANCH_PREFIX,
         branch_policy: {
             mode: "global",
             global_strategy: "branch-per-ticket",
@@ -95,7 +99,10 @@ export function saveTicketSetupConfig(projectDir, setup, opts = {}) {
             delete config.planning;
     }
     mkdirSync(projectDir, { recursive: true });
-    writeFileSync(join(projectDir, RAFI_CONFIG_FILE), stringify(config, { lineWidth: 100 }), "utf8");
+    const target = join(projectDir, RAFI_CONFIG_FILE);
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, stringify(config, { lineWidth: 100 }), "utf8");
+    renameSync(temporary, target);
 }
 /** Synchronize pending setup limits into the tracker, once the tracker exists. */
 export function syncTicketLimits(projectDir, limits) {
@@ -407,6 +414,7 @@ function normalizeBuild(value, label) {
         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_prefix: validateBranchPrefix(stringField(raw.branch_prefix, DEFAULT_TICKET_SETUP.build.branch_prefix)),
         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`),

package/dist/tickets/stateDb.d.ts

@@ -1,3 +1,4 @@
+import type { SavedTicketDefinitionSnapshot, TicketGroup, TicketGroupId, TicketGroupOrigin } from "rafi-spec";
 export type TicketStatus = "planned" | "next" | "in_progress" | "blocked" | "done" | "canceled" | "obsolete";
 export type ValidationResult = "passed" | "failed" | "not_run" | "not_applicable";
 export interface TicketState {
@@ -89,6 +90,12 @@ export interface OperationReceipt {
     completed_at: string;
     payload_json: string;
 }
+export interface TicketGroupValidationIssue {
+    code: "missing-membership" | "multiple-membership" | "unknown-member" | "empty-group" | "sequence-corruption" | "reused-id" | "snapshot-corruption" | "receipt-without-group";
+    message: string;
+    groupId?: TicketGroupId;
+    ticketId?: 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 {
@@ -121,5 +128,32 @@ export declare class StateDb {
     updateReviewRecommendationStatus(id: number, status: ReviewRecommendationStatus, updatedAt: string): void;
     getOperationReceipt(operationId: string): OperationReceipt | undefined;
     recordOperationReceipt(receipt: OperationReceipt): boolean;
+    createTicketGroup(input: {
+        origin: TicketGroupOrigin;
+        operationId: string;
+        members: Array<{
+            ticketId: string;
+            definition: unknown;
+            validatedAt?: string;
+        }>;
+        legacy?: boolean;
+        createdAt?: string;
+    }): TicketGroup;
+    /** Update only the recoverable definition; membership and order never change. */
+    updateTicketDefinitionSnapshot(ticketId: string, definition: unknown, validatedAt?: string): SavedTicketDefinitionSnapshot;
+    getTicketGroupByOperation(operationId: string): TicketGroup | undefined;
+    getTicketGroup(groupId: string): TicketGroup | undefined;
+    getTicketGroupForTicket(ticketId: string): TicketGroup | undefined;
+    listTicketGroups(): TicketGroup[];
+    /** One-time migration for repositories whose complete ticket set predates groups. */
+    ensureSyntheticLegacyGroup(definitions: Array<{
+        id: string;
+    } & Record<string, unknown>>, now?: Date): TicketGroup | undefined;
+    ungroupedTicketIds(ticketIds: readonly string[]): string[];
+    repairTicketGroups(definitions: Array<{
+        id: string;
+    } & Record<string, unknown>>, operationId: string, now?: Date): TicketGroup | undefined;
+    validateTicketGroups(knownTicketIds?: readonly string[]): TicketGroupValidationIssue[];
+    private getTicketGroupBySequence;
     transaction<T>(fn: () => T): T;
 }