ai-foreman 1.7.4 → 1.7.6

package/dist/tickets/details.js

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
+import { loadDeliveryConfig } from "./delivery.js";
+import { resolveBlockers } from "./blockers.js";
+import { StateDb, pristineTicketState } from "./stateDb.js";
+import { loadTickets } from "./ticketLoader.js";
+export function getTicketDetails(projectDir, ticketId, now = new Date()) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    if (!existsSync(paths.tickets))
+        throw new Error("ticket tracker is not initialized; run `rafi tickets init`");
+    const tickets = loadTickets(paths.tickets);
+    const definition = tickets.find((ticket) => ticket.id === ticketId);
+    if (!definition)
+        throw new Error(`Ticket ${ticketId} not found. Run \`rafi tickets queue\` to list tickets.`);
+    const db = new StateDb(paths.stateDb);
+    try {
+        const states = db.getAllStates();
+        const state = states.get(ticketId) ?? pristineTicketState(ticketId, now.toISOString());
+        const delivery = loadDeliveryConfig(projectDir);
+        const units = delivery?.units.filter((unit) => unit.tickets.includes(ticketId)) ?? [];
+        const unitIds = new Set(units.map((unit) => unit.id));
+        const stacks = delivery?.stacks?.filter((stack) => stack.units.some((unit) => unitIds.has(unit))) ?? [];
+        return {
+            definition,
+            state,
+            effective_blockers: resolveBlockers(definition, states),
+            validation_history: db.getValidationSnapshots(ticketId),
+            events: db.getTicketEvents(ticketId),
+            delivery: { units, stacks },
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function formatTicketDetails(details) {
+    const lines = [`${details.definition.id}: ${details.definition.title}`, "", "Canonical ticket"];
+    const preferred = [
+        "id", "order", "title", "area", "priority", "size", "risk", "summary", "depends_on",
+        "acceptance", "required_tests", "likely_files", "rollback", "notes", "external_refs",
+        "source_refs", "plan_ref", "supersedes", "superseded_by",
+    ];
+    const keys = [...preferred.filter((key) => key in details.definition), ...Object.keys(details.definition).filter((key) => !preferred.includes(key)).sort()];
+    for (const key of keys)
+        lines.push(...formatField(key, details.definition[key]));
+    lines.push("", "Active state");
+    for (const [key, value] of Object.entries(details.state))
+        lines.push(...formatField(key, parseJsonField(key, value)));
+    lines.push(...formatField("effective_blockers", details.effective_blockers));
+    lines.push("", "Active validation and evidence");
+    lines.push(...formatField("validation_result", details.state.validation_result));
+    lines.push(...formatField("validation_commands", details.state.validation_commands));
+    lines.push(...formatField("validation_notes", details.state.validation_notes));
+    lines.push(...formatField("evidence", details.state.evidence));
+    lines.push("", "Historical validation");
+    lines.push(...formatRecords(details.validation_history));
+    lines.push("", "Delivery");
+    lines.push(...formatField("units", details.delivery.units));
+    lines.push(...formatField("stacks", details.delivery.stacks));
+    lines.push("", "History");
+    lines.push(...formatRecords(details.events));
+    return lines;
+}
+function formatField(label, value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return [`${label}: (none)`];
+        if (value.every((item) => typeof item !== "object" || item === null)) {
+            return [`${label}:`, ...value.map((item) => `  - ${String(item)}`)];
+        }
+        return [`${label}:`, ...JSON.stringify(value, null, 2).split("\n").map((line) => `  ${line}`)];
+    }
+    if (value && typeof value === "object") {
+        return [`${label}:`, ...JSON.stringify(value, null, 2).split("\n").map((line) => `  ${line}`)];
+    }
+    const rendered = value === undefined || value === null || value === "" ? "(none)" : String(value);
+    if (!rendered.includes("\n"))
+        return [`${label}: ${rendered}`];
+    return [`${label}:`, ...rendered.split("\n").map((line) => `  ${line}`)];
+}
+function formatRecords(records) {
+    return records.length ? JSON.stringify(records, null, 2).split("\n").map((line) => `  ${line}`) : ["  (none)"];
+}
+function parseJsonField(key, value) {
+    if (key !== "blocked_by_json" || typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}

package/dist/tickets/eligibility.d.ts

@@ -0,0 +1,28 @@
+import type { DeliveryConfig } from "./delivery.js";
+import type { TicketDef } from "./ticketSchema.js";
+import type { TicketState } from "./stateDb.js";
+export type TicketIneligibilityCode = "missing" | "terminal" | "outside-window" | "dependencies" | "explicit-blocker" | "delivery-constraint" | "active-lease" | "resumable-owner";
+export interface TicketEligibility {
+    ticket?: TicketDef;
+    eligible: boolean;
+    recommended: boolean;
+    blockers: Array<{
+        code: TicketIneligibilityCode;
+        detail: string;
+        tickets?: string[];
+    }>;
+    eligibleDependencies: TicketDef[];
+}
+export interface EligibilityContext {
+    tickets: TicketDef[];
+    states: Map<string, TicketState>;
+    implementationLimit: number;
+    delivery?: DeliveryConfig;
+    activeLease?: {
+        runId: string;
+    };
+    allowOwnedResume?: boolean;
+}
+export declare function evaluateTicketEligibility(context: EligibilityContext, ticketId: string): TicketEligibility;
+export declare function eligibleTickets(context: EligibilityContext): TicketDef[];
+export declare function implementationWindow(tickets: TicketDef[], states: Map<string, TicketState>, limit: number): TicketDef[];

package/dist/tickets/eligibility.js

@@ -0,0 +1,71 @@
+import { resolveBlockers } from "./blockers.js";
+export function evaluateTicketEligibility(context, ticketId) {
+    const ticket = context.tickets.find((candidate) => candidate.id === ticketId);
+    if (!ticket)
+        return { eligible: false, recommended: false, blockers: [{ code: "missing", detail: `ticket ${ticketId} does not exist` }], eligibleDependencies: [] };
+    const state = context.states.get(ticket.id);
+    const blockers = [];
+    if (["done", "canceled", "obsolete"].includes(state?.status ?? "planned"))
+        blockers.push({ code: "terminal", detail: `ticket is ${state?.status}` });
+    const window = implementationWindow(context.tickets, context.states, context.implementationLimit);
+    if (!window.some((candidate) => candidate.id === ticket.id))
+        blockers.push({ code: "outside-window", detail: `ticket is outside the ${context.implementationLimit}-ticket implementation window` });
+    const unfinishedDependencies = ticket.depends_on.filter((id) => context.states.get(id)?.status !== "done");
+    if (unfinishedDependencies.length)
+        blockers.push({ code: "dependencies", detail: `unfinished dependencies: ${unfinishedDependencies.join(", ")}`, tickets: unfinishedDependencies });
+    const explicit = resolveBlockers(ticket, context.states).filter((id) => !unfinishedDependencies.includes(id));
+    if (explicit.length)
+        blockers.push({ code: "explicit-blocker", detail: `explicit blockers: ${explicit.join(", ")}`, tickets: explicit });
+    const deliveryReason = deliveryConstraint(ticket.id, context.delivery, context.states);
+    if (deliveryReason)
+        blockers.push({ code: "delivery-constraint", detail: deliveryReason });
+    if (context.activeLease)
+        blockers.push({ code: "active-lease", detail: `project has an active workflow lease for run ${context.activeLease.runId}` });
+    if (!context.allowOwnedResume && (state?.status === "in_progress" || state?.owner))
+        blockers.push({ code: "resumable-owner", detail: `ticket has resumable ownership${state.owner ? ` by ${state.owner}` : ""}` });
+    const eligibleDependencies = unfinishedDependencies
+        .map((id) => context.tickets.find((candidate) => candidate.id === id))
+        .filter((candidate) => Boolean(candidate))
+        .filter((candidate) => evaluateTicketEligibility({ ...context, activeLease: undefined }, candidate.id).eligible)
+        .sort(ticketOrder);
+    const ranked = eligibleTickets({ ...context, activeLease: undefined });
+    return { ticket, eligible: blockers.length === 0, recommended: ranked[0]?.id === ticket.id, blockers, eligibleDependencies };
+}
+export function eligibleTickets(context) {
+    return implementationWindow(context.tickets, context.states, context.implementationLimit)
+        .filter((ticket) => {
+        const state = context.states.get(ticket.id);
+        if (["done", "canceled", "obsolete", "in_progress"].includes(state?.status ?? "planned") || state?.owner)
+            return false;
+        if (resolveBlockers(ticket, context.states).length)
+            return false;
+        return !deliveryConstraint(ticket.id, context.delivery, context.states);
+    })
+        .sort(ticketOrder);
+}
+export function implementationWindow(tickets, states, limit) {
+    return tickets.filter((ticket) => !["done", "canceled", "obsolete"].includes(states.get(ticket.id)?.status ?? "planned")).sort(ticketOrder).slice(0, limit);
+}
+function ticketOrder(a, b) {
+    return a.order - b.order || a.id.localeCompare(b.id);
+}
+function deliveryConstraint(ticketId, delivery, states) {
+    if (!delivery)
+        return undefined;
+    const unit = delivery.units.find((candidate) => candidate.tickets.includes(ticketId));
+    if (!unit)
+        return undefined;
+    const stack = delivery.stacks?.find((candidate) => candidate.units.includes(unit.id));
+    if (!stack)
+        return undefined;
+    const firstUnfinishedUnit = stack.units.find((unitId) => {
+        const candidate = delivery.units.find((item) => item.id === unitId);
+        return candidate?.tickets.some((id) => !["done", "canceled", "obsolete"].includes(states.get(id)?.status ?? "planned"));
+    });
+    if (firstUnfinishedUnit && firstUnfinishedUnit !== unit.id)
+        return `delivery stack ${stack.id} must continue with unit ${firstUnfinishedUnit}`;
+    const firstUnfinishedTicket = unit.tickets.find((id) => !["done", "canceled", "obsolete"].includes(states.get(id)?.status ?? "planned"));
+    if (firstUnfinishedTicket && firstUnfinishedTicket !== ticketId && unit.dependency_mode === "stack")
+        return `delivery unit ${unit.id} must continue with ${firstUnfinishedTicket}`;
+    return undefined;
+}

package/dist/tickets/importer.js

@@ -5,6 +5,7 @@ import { StateDb } from "./stateDb.js";
 import { nowTimestamp } from "./events.js";
 import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
 import { insertXlSplitRecommendations } from "./recommendations.js";
+import { currentActivity, withActivityPhase } from "../activity.js";
 export function importFromMarkdown(_progressDocPath) {
     throw new Error("foreman tickets import is not yet implemented.\n\n" +
         "To start fresh:\n" +
@@ -19,9 +20,9 @@ export function importFromMarkdown(_progressDocPath) {
 export async function importExternalSources(projectDir, sources, opts) {
     const results = [];
     for (const source of sources) {
-        const items = source.type === "linear"
-            ? await fetchLinearIssues(source, opts)
-            : await fetchJiraIssues(source, opts);
+        const items = await withActivityPhase(`importing ${source.type} tickets`, () => source.type === "linear"
+            ? fetchLinearIssues(source, opts)
+            : fetchJiraIssues(source, opts));
         const snapshotPath = writeImportSnapshot(projectDir, source.type, {
             source: redactSource(source),
             fetched_at: new Date().toISOString(),
@@ -42,11 +43,13 @@ export async function importExternalSources(projectDir, sources, opts) {
     return results;
 }
 export async function validateExternalSourceAccess(source) {
-    if (source.type === "linear") {
-        await fetchLinearIssues(source, { importCap: 1, commentLimit: 0 });
-        return;
-    }
-    await fetchJiraIssues(source, { importCap: 1, commentLimit: 0 });
+    await withActivityPhase(`checking ${source.type} access`, async () => {
+        if (source.type === "linear") {
+            await fetchLinearIssues(source, { importCap: 1, commentLimit: 0 });
+            return;
+        }
+        await fetchJiraIssues(source, { importCap: 1, commentLimit: 0 });
+    });
 }
 export async function fetchLinearIssues(source, opts) {
     const apiKey = process.env[source.api_key_env];
@@ -84,6 +87,7 @@ export async function fetchLinearIssues(source, opts) {
             if (items.length >= opts.importCap)
                 break;
         }
+        currentActivity()?.update("importing Linear tickets", `fetched ${items.length}`);
         if (!issues?.pageInfo?.hasNextPage || !issues.pageInfo.endCursor || nodes.length === 0)
             break;
         after = issues.pageInfo.endCursor;
@@ -137,6 +141,7 @@ export async function fetchJiraIssues(source, opts) {
             if (items.length >= opts.importCap)
                 break;
         }
+        currentActivity()?.update("importing Jira tickets", `fetched ${items.length}`);
         nextPageToken = typeof json.nextPageToken === "string" ? json.nextPageToken : undefined;
         if (!nextPageToken || issues.length === 0 || json.isLast === true)
             break;

package/dist/tickets/reset.d.ts

@@ -0,0 +1,27 @@
+import { type TicketStatus } from "./stateDb.js";
+export type TicketResetScope = "all" | "completed-and-unfinished" | "unfinished";
+export interface TicketResetPreviewRow {
+    id: string;
+    title: string;
+    status: TicketStatus;
+    cleared: string[];
+}
+export interface TicketResetPreview {
+    scope: TicketResetScope | "single" | "run";
+    tickets: TicketResetPreviewRow[];
+    relatedRuns: Array<{
+        runId: string;
+        status: string;
+        tickets: string[];
+    }>;
+}
+export declare function previewTicketReset(projectDir: string, target: string | TicketResetScope | string[]): TicketResetPreview;
+export declare function resetTickets(projectDir: string, target: string | TicketResetScope | string[], actor?: string, now?: Date, hooks?: {
+    beforePublish?: () => void;
+    resetId?: string;
+}): {
+    resetId: string;
+    tickets: string[];
+};
+/** Finish or roll back a reset publication left incomplete by process interruption. */
+export declare function recoverTicketResetPublications(projectDir: string): string[];

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;