ai-foreman 1.7.4 → 1.7.6

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/sourceFetch.js

@@ -5,12 +5,22 @@ import { isIP } from "node:net";
 import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { readdirSync } from "node:fs";
 import { parse as parseHtml } from "parse5";
+import { currentActivity, withActivityPhase } from "../activity.js";
 export const DEFAULT_SOURCE_FETCH_LIMITS = {
     timeoutMs: 15_000,
     maxBytes: 10 * 1024 * 1024,
     maxRedirects: 5,
 };
 export async function fetchAndSnapshotUrl(projectDir, input, limits = {}) {
+    const label = (() => { try {
+        return `fetching source ${new URL(input).hostname}`;
+    }
+    catch {
+        return "fetching URL source";
+    } })();
+    return withActivityPhase(label, () => fetchAndSnapshotUrlInternal(projectDir, input, limits));
+}
+async function fetchAndSnapshotUrlInternal(projectDir, input, limits) {
     const effective = { ...DEFAULT_SOURCE_FETCH_LIMITS, ...limits };
     const requested = normalizePublicHttpUrl(input);
     let current = requested;
@@ -126,6 +136,7 @@ async function readLimitedBody(response, maxBytes) {
         if (done)
             break;
         total += value.length;
+        currentActivity()?.pulse(`downloaded ${formatBytes(total)}`);
         if (total > maxBytes) {
             await reader.cancel();
             throw new Error(`URL content exceeds ${maxBytes} byte limit`);
@@ -174,6 +185,7 @@ async function extractSourceText(kind, bytes) {
         const document = await pdfjs.getDocument({ data: bytes, useWorkerFetch: false, isEvalSupported: false }).promise;
         const pages = [];
         for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+            currentActivity()?.update("extracting PDF source", `page ${pageNumber}/${document.numPages}`);
             const page = await document.getPage(pageNumber);
             const content = await page.getTextContent();
             pages.push(content.items.map((item) => "str" in item ? item.str : "").join(" "));
@@ -185,6 +197,13 @@ async function extractSourceText(kind, bytes) {
     const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     return kind === "html" ? htmlToText(decoded) : decoded;
 }
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
 export function htmlToText(html) {
     const doc = parseHtml(html);
     const blocks = new Set(["address", "article", "aside", "blockquote", "br", "div", "footer", "h1", "h2", "h3", "h4", "h5", "h6", "header", "li", "main", "p", "section", "table", "tr"]);

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

package/dist/workflowDb.d.ts

@@ -36,6 +36,8 @@ export interface ProjectLease {
     heartbeatAt: string;
     runId: string;
 }
+/** Read the current project lease without creating or migrating recovery state. */
+export declare function readCurrentWorkflowLease(projectDir: string): ProjectLease | undefined;
 export interface PublicationTransaction {
     transactionId: string;
     runId: string;
@@ -63,6 +65,7 @@ export declare class WorkflowDb {
     }, now?: Date): WorkflowRunSnapshot;
     getRun(runId: string): WorkflowRunSnapshot | undefined;
     activeRuns(): WorkflowRunSnapshot[];
+    resumableRuns(kind?: WorkflowKind): WorkflowRunSnapshot[];
     transition(runId: string, update: {
         status?: WorkflowRunStatus;
         checkpoint: string;

package/dist/workflowDb.js

@@ -4,6 +4,26 @@ import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import Database from "better-sqlite3";
 export const WORKFLOW_DB_FILE = ".rafi/recovery.sqlite3";
+/** Read the current project lease without creating or migrating recovery state. */
+export function readCurrentWorkflowLease(projectDir) {
+    const path = join(resolve(projectDir), WORKFLOW_DB_FILE);
+    if (!existsSync(path))
+        return undefined;
+    let db;
+    try {
+        db = new Database(path, { readonly: true, fileMustExist: true });
+        const row = db.prepare("SELECT * FROM project_lease WHERE singleton=1").get();
+        return row ? { owner: row.owner, generation: row.generation, pid: row.pid, host: row.host, processStart: row.process_start, heartbeatAt: row.heartbeat_at, runId: row.run_id } : undefined;
+    }
+    catch (error) {
+        if (String(error).includes("no such table"))
+            return undefined;
+        throw error;
+    }
+    finally {
+        db?.close();
+    }
+}
 /** Authoritative persistence for every resumable workflow in a project. */
 export class WorkflowDb {
     projectDir;
@@ -43,6 +63,12 @@ export class WorkflowDb {
     activeRuns() {
         return this.db.prepare("SELECT * FROM workflow_runs WHERE status IN ('running','paused','blocked') ORDER BY created_at").all().map(rowToRun);
     }
+    resumableRuns(kind) {
+        const rows = kind
+            ? this.db.prepare("SELECT * FROM workflow_runs WHERE kind=? AND status NOT IN ('completed','cancelled','superseded') ORDER BY created_at").all(kind)
+            : this.db.prepare("SELECT * FROM workflow_runs WHERE status NOT IN ('completed','cancelled','superseded') ORDER BY created_at").all();
+        return rows.map(rowToRun);
+    }
     transition(runId, update, now = new Date()) {
         const at = now.toISOString();
         return this.db.transaction(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,10 @@
     "ai-foreman": "dist/index.js"
   },
   "exports": {
+    "./activity.js": {
+      "types": "./dist/activity.d.ts",
+      "default": "./dist/activity.js"
+    },
     "./agent-run.js": {
       "types": "./dist/agentRun.d.ts",
       "default": "./dist/agentRun.js"
@@ -25,6 +29,10 @@
       "types": "./dist/interviews.d.ts",
       "default": "./dist/interviews.js"
     },
+    "./provider-questions.js": {
+      "types": "./dist/providerQuestions.d.ts",
+      "default": "./dist/providerQuestions.js"
+    },
     "./runtime-readiness.js": {
       "types": "./dist/runtimeReadiness.d.ts",
       "default": "./dist/runtimeReadiness.js"
@@ -65,6 +73,10 @@
       "types": "./dist/tickets/setupConfig.d.ts",
       "default": "./dist/tickets/setupConfig.js"
     },
+    "./ticket-reset.js": {
+      "types": "./dist/tickets/reset.d.ts",
+      "default": "./dist/tickets/reset.js"
+    },
     "./sources/source-registry.js": {
       "types": "./dist/sources/sourceRegistry.d.ts",
       "default": "./dist/sources/sourceRegistry.js"
@@ -118,8 +130,8 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.148"
   },
   "dependencies": {
-    "special-agents": "0.8.2",
-    "rafi-spec": "0.8.2",
+    "special-agents": "0.8.4",
+    "rafi-spec": "0.8.4",
     "@clack/prompts": "^1.4.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",