ai-foreman 1.7.1 → 1.7.3

package/dist/agentRun.d.ts

@@ -4,6 +4,7 @@ import { type StepStatus } from "./foreman.js";
 import type { BuilderAdapter, BuilderAdapterOptions, EffortLevel, TurnResult } from "./adapters/types.js";
 import { type RoleBundle } from "./roles.js";
 import type { AgentRuntime } from "./runtimeAuth.js";
+import type { AgentRoleDefaultsV1 } from "rafi-spec";
 export type { EffortLevel } from "./adapters/types.js";
 export declare const VALID_EFFORT: readonly EffortLevel[];
 export interface RoleBuilderOptions {
@@ -54,4 +55,5 @@ export declare function makeLogPath(projectDir: string, label: string): string;
 export declare function mergeSkills(roleSkills: readonly string[], extraSkills?: readonly string[]): string[];
 export declare function readOnlyPermissionConfig(): PermissionConfig;
 export declare function createRoleBuilder(opts: RoleBuilderOptions): Promise<RoleBuilder>;
+export declare function readRoleDefaultsForExecution(projectDir: string, role: string): AgentRoleDefaultsV1 | undefined;
 export declare function runRoleInstruction(opts: RoleInstructionRunOptions): Promise<RoleInstructionRunResult>;

package/dist/agentRun.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, DEFAULT_CONFIG } from "./config.js";
 import { Log } from "./log.js";
@@ -86,7 +86,7 @@ export async function createRoleBuilder(opts) {
     if (!existsSync(opts.projectDir)) {
         throw new Error(`project directory not found: ${opts.projectDir}`);
     }
-    const saved = readRoleDefaults(opts.projectDir, opts.role);
+    const saved = readRoleDefaultsForExecution(opts.projectDir, opts.role);
     const configuredEffort = saved?.reasoning && saved.reasoning !== "default" ? saved.reasoning : undefined;
     const effectiveEffort = opts.effort ?? (VALID_EFFORT.includes(configuredEffort) ? configuredEffort : undefined);
     assertEffortLevel(effectiveEffort);
@@ -157,20 +157,47 @@ function phaseForRole(role) {
         return "uninstaller";
     return "builder";
 }
-function readRoleDefaults(projectDir, role) {
+export function readRoleDefaultsForExecution(projectDir, role) {
     const path = join(projectDir, "rafi-config.yaml");
     if (!existsSync(path))
         return undefined;
     try {
         const config = parseYaml(readFileSync(path, "utf8"));
-        return config?.agent_defaults?.version === 1
+        const saved = config?.agent_defaults?.version === 1
             ? config.agent_defaults.roles[role]
             : undefined;
+        if (!saved)
+            return undefined;
+        if (isFullyInitializedTracker(projectDir))
+            return saved;
+        const { make: _pendingMake, ...active } = saved;
+        return active;
     }
     catch {
         return undefined;
     }
 }
+function isFullyInitializedTracker(projectDir) {
+    try {
+        const trackerPath = join(projectDir, ".tickets", "config.yaml");
+        const ticketsPath = join(projectDir, ".tickets", "tickets.yaml");
+        const statePath = join(projectDir, ".tickets", "ticket-state.sqlite");
+        if (!existsSync(trackerPath) || !existsSync(ticketsPath) || !existsSync(statePath))
+            return false;
+        const tracker = parseYaml(readFileSync(trackerPath, "utf8"));
+        if (!tracker || typeof tracker !== "object" || Array.isArray(tracker))
+            return false;
+        const tickets = parseYaml(readFileSync(ticketsPath, "utf8"));
+        if (!tickets || !Array.isArray(tickets.tickets))
+            return false;
+        if (!statSync(statePath).isFile())
+            return false;
+        return readFileSync(statePath).subarray(0, 16).toString("utf8") === "SQLite format 3\u0000";
+    }
+    catch {
+        return false;
+    }
+}
 export async function runRoleInstruction(opts) {
     const logPath = opts.logPath ?? makeLogPath(opts.projectDir, opts.label.replace(/\s+/g, "-"));
     const log = new Log(logPath);

package/dist/branch/git.d.ts

@@ -11,6 +11,7 @@ export declare function generatedTrackerDirtyPaths(paths: {
     progressDoc: string;
     archiveDoc?: string;
 }): string[];
+export declare function collectBaseWorktreeDirtyPaths(cwd: string, opts?: BaseWorktreeCleanOptions): string[];
 export declare function ensureCleanBaseWorktree(cwd: string, opts?: BaseWorktreeCleanOptions): void;
 export declare function ensureForemanExcluded(cwd: string): void;
 export declare function createTicketWorktree(projectDir: string, runId: string, branch: string, base: string): string;

package/dist/branch/git.js

@@ -25,13 +25,16 @@ export function generatedTrackerDirtyPaths(paths) {
     }
     return out;
 }
-export function ensureCleanBaseWorktree(cwd, opts = {}) {
+export function collectBaseWorktreeDirtyPaths(cwd, opts = {}) {
     const allowedDirtyPaths = new Set([".tickets/.gitignore", ...(opts.allowedDirtyPaths ?? []).map(normalizeRepoPath)]);
     const status = runGit(cwd, ["status", "--porcelain", "--untracked-files=all"]).stdout;
-    const dirty = status.split("\n").filter(Boolean).filter((line) => {
+    return status.split("\n").filter(Boolean).filter((line) => {
         const path = normalizeRepoPath(line.slice(3));
         return !path.startsWith(".foreman/") && !allowedDirtyPaths.has(path);
     });
+}
+export function ensureCleanBaseWorktree(cwd, opts = {}) {
+    const dirty = collectBaseWorktreeDirtyPaths(cwd, opts);
     if (dirty.length > 0) {
         throw new Error(`base worktree has uncommitted changes:\n${dirty.join("\n")}`);
     }

package/dist/branch/runner.d.ts

@@ -10,6 +10,7 @@ export interface DeliveryUnitSession {
     sessionId: string;
     ticket: string;
 }
+export type BaseWorktreePolicy = "enforce" | "warn" | "skip";
 export declare function readDeliveryUnitSession(projectDir: string, unitId: string): DeliveryUnitSession | undefined;
 export interface BranchRunnerOptions {
     projectDir: string;
@@ -32,6 +33,7 @@ export interface BranchRunnerOptions {
     autoMergeTimeoutMinutes?: number | null;
     mergeMethod?: MergeMethod;
     allowedBaseDirtyPaths?: string[];
+    baseWorktreePolicy?: BaseWorktreePolicy;
     trackerPaths?: {
         progressDoc: string;
         archiveDoc: string;

package/dist/branch/runner.js

@@ -24,7 +24,20 @@ function deliverySessionPath(projectDir, unitId) {
     return join(projectDir, ".foreman", "delivery-sessions", `${unitId}.json`);
 }
 export async function runBranchPlan(opts) {
-    ensureCleanBaseWorktree(opts.projectDir, { allowedDirtyPaths: opts.allowedBaseDirtyPaths });
+    const baseWorktreePolicy = opts.baseWorktreePolicy ?? "enforce";
+    if (baseWorktreePolicy !== "skip") {
+        try {
+            ensureCleanBaseWorktree(opts.projectDir, { allowedDirtyPaths: opts.allowedBaseDirtyPaths });
+        }
+        catch (error) {
+            if (baseWorktreePolicy === "warn") {
+                console.warn(`foreman: warning: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
     ensureForemanExcluded(opts.projectDir);
     const completionMode = opts.completionMode ?? (opts.createPr ? "pr" : "none");
     const reviewProvider = opts.reviewProvider ?? "github";

package/dist/cli/start.js

@@ -18,7 +18,7 @@ import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
 import { applySharedDeliveryBranch, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
-import { currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
+import { collectBaseWorktreeDirtyPaths, currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
 import { formatGitHubFailure, preflightGh } from "../branch/github.js";
 import { preflightGlab } from "../branch/gitlab.js";
 import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
@@ -529,11 +529,20 @@ export function buildStartCommand() {
         if (branchMode) {
             const ticketsConfig = loadTicketsConfig(cwd);
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
-            try {
-                ensureCleanBaseWorktree(cwd, { allowedDirtyPaths: allowedBaseDirtyPaths });
+            const baseWorktreePolicy = recoveryRecord ? "skip" : "enforce";
+            if (baseWorktreePolicy === "skip") {
+                const dirty = collectBaseWorktreeDirtyPaths(cwd, { allowedDirtyPaths: allowedBaseDirtyPaths });
+                if (dirty.length > 0) {
+                    console.warn(`foreman: warning: base worktree has uncommitted changes; build recovery will continue.\n${dirty.join("\n")}`);
+                }
             }
-            catch (err) {
-                fail(err instanceof Error ? err.message : String(err));
+            else {
+                try {
+                    ensureCleanBaseWorktree(cwd, { allowedDirtyPaths: allowedBaseDirtyPaths });
+                }
+                catch (err) {
+                    fail(err instanceof Error ? err.message : String(err));
+                }
             }
             if (branchDefaults.createReview && branchDefaults.reviewProvider) {
                 await ensureReviewProviderReady(cwd, branchDefaults.reviewProvider, log, Boolean(opts.yes));
@@ -718,6 +727,7 @@ export function buildStartCommand() {
                 autoMergeTimeoutMinutes: branchDefaults.autoMergeTimeoutMinutes,
                 mergeMethod: branchDefaults.mergeMethod,
                 allowedBaseDirtyPaths,
+                baseWorktreePolicy,
                 trackerPaths: {
                     progressDoc: ticketsConfig.paths.progressDoc,
                     archiveDoc: ticketsConfig.paths.archiveDoc,

package/dist/cli/tickets.js

@@ -266,6 +266,8 @@ async function collectTicketSetupPatch(dir, opts, current) {
     const buildPatch = {};
     if (opts.agentPreference)
         populatePatch.agent_preference = parseAgentPreference(opts.agentPreference);
+    if (opts.branchStrategy)
+        buildPatch.branch_strategy = parseBranchStrategy(opts.branchStrategy);
     if (opts.completion)
         buildPatch.completion = parseCompletionMode(opts.completion);
     if (opts.provider)
@@ -275,6 +277,15 @@ async function collectTicketSetupPatch(dir, opts, current) {
     if (opts.autoMergeTimeoutMinutes !== undefined) {
         buildPatch.auto_merge_timeout_minutes = parseOptionalPositiveInteger(opts.autoMergeTimeoutMinutes, "--auto-merge-timeout-minutes");
     }
+    if (buildPatch.branch_strategy === "current") {
+        if (buildPatch.completion && buildPatch.completion !== "none")
+            fail("--branch-strategy current requires --completion none");
+        buildPatch.completion = "none";
+        buildPatch.provider = buildPatch.provider ?? "local";
+        buildPatch.pr_ready = false;
+        buildPatch.auto_merge_wait = false;
+        buildPatch.auto_merge_timeout_minutes = null;
+    }
     if (!shouldPrompt(opts)) {
         const prefill = current.sources.length === 0
             ? configuredPlanningSources(dir).map((path) => ({ type: "local", paths: [path] }))
@@ -321,6 +332,32 @@ async function collectTicketSetupPatch(dir, opts, current) {
     }
     if (section === "build" || section === "all") {
         const recommended = recommendedBuildDefaults(dir);
+        const strategy = await select({
+            message: "Default ticket work mode:",
+            initialValue: current.build.branch_strategy,
+            options: [
+                { value: "current", label: "One branch - work the queue on the current branch" },
+                { value: "batch", label: "Batch branch - use shared branches for explicit delivery batches" },
+                { value: "branch-per-ticket", label: "Branch per ticket - isolate each ticket on its own branch" },
+            ],
+        });
+        if (isCancel(strategy))
+            process.exit(0);
+        buildPatch.branch_strategy = strategy;
+        if (strategy === "current") {
+            buildPatch.completion = "none";
+            buildPatch.provider = "local";
+            buildPatch.pr_ready = false;
+            buildPatch.merge_method = "squash";
+            buildPatch.cleanup = true;
+            buildPatch.auto_merge_wait = false;
+            buildPatch.auto_merge_timeout_minutes = null;
+            return {
+                sources,
+                populate: populatePatch,
+                build: buildPatch,
+            };
+        }
         const completion = await select({
             message: "Default completion behavior for branch ticket runs:",
             initialValue: current.build.completion === "none" ? recommended.completion : current.build.completion,
@@ -333,7 +370,6 @@ async function collectTicketSetupPatch(dir, opts, current) {
         });
         if (isCancel(completion))
             process.exit(0);
-        buildPatch.branch_strategy = "branch-per-ticket";
         buildPatch.completion = completion;
         buildPatch.provider = recommended.provider;
         buildPatch.pr_ready = completion === "auto-merge";
@@ -517,6 +553,11 @@ function parseCompletionMode(value) {
         return value;
     fail("--completion must be one of: pr, auto-merge, direct-merge, none");
 }
+function parseBranchStrategy(value) {
+    if (["current", "batch", "branch-per-ticket"].includes(value))
+        return value;
+    fail("--branch-strategy must be one of: current, batch, branch-per-ticket");
+}
 function parseProvider(value) {
     if (["auto", "github", "gitlab", "local"].includes(value))
         return value;
@@ -853,6 +894,7 @@ export function buildTicketsCommand() {
         .option("--jira-jql <jql>", "Jira JQL query")
         .option("--url-source <urls...>", "add public HTTP(S) source URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
+        .option("--branch-strategy <strategy>", "build branch strategy default (current | batch | branch-per-ticket)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
@@ -883,6 +925,7 @@ export function buildTicketsCommand() {
         .option("--jira-jql <jql>", "Jira JQL query")
         .option("--url-source <urls...>", "replace saved sources with public HTTP(S) URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
+        .option("--branch-strategy <strategy>", "build branch strategy default (current | batch | branch-per-ticket)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
@@ -1261,7 +1304,7 @@ export function buildTicketsCommand() {
         .description("Print the ticket queue to stdout.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--limit <n>", "override view limit")
-        .option("--refresh", "query GitHub/GitLab and refresh cached stack review state")
+        .option("--refresh", "query GitHub/GitLab and refresh cached batch review state")
         .action((opts) => {
         try {
             const dir = cwd(opts);
@@ -1275,6 +1318,7 @@ export function buildTicketsCommand() {
                         console.log(line);
                 return;
             }
+            console.log("Batches: none configured. Queue is flat.");
             const rows = cmdQueue(dir, opts.limit !== undefined ? Number(opts.limit) : undefined);
             if (rows.length === 0) {
                 console.log("No remaining tickets.");

package/dist/tickets/queue.d.ts

@@ -35,5 +35,5 @@ export interface ActiveStatusRow {
 }
 export declare function buildNextQueue(ticketDefs: TicketDef[], states: Map<string, TicketState>, queueLimit: number): QueueRow[];
 export declare function buildActiveStatusRows(queueRows: QueueRow[], ticketDefs: TicketDef[], states: Map<string, TicketState>): ActiveStatusRow[];
-/** Human-readable queue blocks keep a whole unfinished stack and its resume point visible. */
+/** Human-readable queue blocks keep a whole unfinished batch and its resume point visible. */
 export declare function formatStackAwareQueue(ticketDefs: TicketDef[], states: Map<string, TicketState>, delivery?: DeliveryConfig): string[];

package/dist/tickets/queue.js

@@ -61,15 +61,16 @@ export function buildActiveStatusRows(queueRows, ticketDefs, states) {
         };
     });
 }
-/** Human-readable queue blocks keep a whole unfinished stack and its resume point visible. */
+/** Human-readable queue blocks keep a whole unfinished batch and its resume point visible. */
 export function formatStackAwareQueue(ticketDefs, states, delivery) {
     if (!delivery?.stacks?.length)
-        return buildNextQueue(ticketDefs, states, Number.MAX_SAFE_INTEGER).map((row) => `${row.ticket} ${row.status} ${row.title}`);
+        return ["Batches: none configured. Queue is flat.", ...buildNextQueue(ticketDefs, states, Number.MAX_SAFE_INTEGER).map((row) => `${row.ticket} ${row.status} ${row.title}`)];
     const defs = new Map(ticketDefs.map((ticket) => [ticket.id, ticket]));
     const unitById = new Map(delivery.units.map((unit) => [unit.id, unit]));
     const stackedTickets = new Set();
     const lines = [];
-    for (const stack of delivery.stacks) {
+    lines.push(`Batches: ${delivery.stacks.length} configured.`);
+    for (const [index, stack] of delivery.stacks.entries()) {
         const nodes = normalizeStackNodes(stack, delivery.units, ticketDefs);
         const ticketIds = stack.units.flatMap((id) => unitById.get(id)?.tickets ?? []);
         ticketIds.forEach((id) => stackedTickets.add(id));
@@ -79,16 +80,26 @@ export function formatStackAwareQueue(ticketDefs, states, delivery) {
         const next = ticketIds.find((id) => !terminal(states.get(id)?.status));
         const blockers = next && defs.get(next) ? resolveBlockers(defs.get(next), states) : [];
         const state = deriveStackState(stack, ticketIds, states, blockers);
-        lines.push(`=== STACK START: ${stack.name} (${stack.id}) ===`);
-        lines.push(`status=${state}; size=${ticketIds.length}; pr_depth=${nodes.length}; blockers=${blockers.join(",") || "none"}; completed_prefix=${completed.join(",") || "none"}; next=${next ?? "none"}`);
+        const units = stack.units.map((id) => unitById.get(id)).filter((unit) => Boolean(unit));
+        const branchModes = [...new Set(units.map((unit) => unit.branch_mode))].join(",") || "unknown";
+        const prChain = units.some((unit) => unit.dependency_mode === "stack") || nodes.length > 1;
+        lines.push(`=== Batch ${index + 1}: ${stack.name} (${stack.id}) ===`);
+        lines.push(`status=${state}; tickets=${ticketIds.length}; branch_mode=${branchModes}; blockers=${blockers.join(",") || "none"}; completed=${completed.join(",") || "none"}; next=${next ?? "none"}`);
+        if (prChain)
+            lines.push(`delivery=PR chain (${nodes.length} dependent branch${nodes.length === 1 ? "" : "es"})`);
         lines.push(`reviews=${stack.review_links?.join(",") || "none"}; remote_checked=${stack.remote_checked_at ?? "never"}${stack.remote_stale ? " (stale; run --refresh for a live check)" : ""}`);
         for (const id of ticketIds)
             lines.push(`${id} ${states.get(id)?.status ?? "planned"} ${defs.get(id)?.title ?? "unknown ticket"}`);
-        lines.push(`=== STACK END: ${stack.name} (${stack.id}) ===`);
+        lines.push(`=== End Batch ${index + 1}: ${stack.name} (${stack.id}) ===`);
     }
+    let unbatched = false;
     for (const ticket of ticketDefs.sort((a, b) => a.order - b.order)) {
         if (stackedTickets.has(ticket.id) || terminal(states.get(ticket.id)?.status))
             continue;
+        if (!unbatched) {
+            lines.push("Unbatched tickets:");
+            unbatched = true;
+        }
         const blockers = resolveBlockers(ticket, states);
         lines.push(`${ticket.id} ${computeDisplayStatus(states.get(ticket.id)?.status ?? "planned", blockers)} ${ticket.title}`);
     }

package/dist/tickets/setupConfig.d.ts

@@ -3,7 +3,7 @@ export type HarnessTarget = "claude" | "codex";
 export type TicketBuildCompletionMode = "pr" | "auto-merge" | "direct-merge" | "none";
 export type TicketBuildProvider = "auto" | "github" | "gitlab" | "local";
 export type TicketBuildMergeMethod = "squash" | "merge" | "rebase";
-export type TicketBuildBranchStrategy = "branch-per-ticket" | "batch";
+export type TicketBuildBranchStrategy = "current" | "batch" | "branch-per-ticket";
 export type TicketPopulateAgentPreference = "configured" | "claude" | "codex";
 export type TicketPopulateEnrichmentPolicy = "none" | "recommendations" | "agent";
 export type TicketSourceConfig = {

package/dist/tickets/setupConfig.js

@@ -346,7 +346,7 @@ function normalizePopulate(value, label) {
 function normalizeBuild(value, label) {
     const raw = objectOrEmpty(value, label);
     return {
-        branch_strategy: enumField(raw.branch_strategy, ["branch-per-ticket", "batch"], DEFAULT_TICKET_SETUP.build.branch_strategy, `${label}.branch_strategy`),
+        branch_strategy: enumField(raw.branch_strategy, ["current", "batch", "branch-per-ticket"], DEFAULT_TICKET_SETUP.build.branch_strategy, `${label}.branch_strategy`),
         completion: enumField(raw.completion, ["pr", "auto-merge", "direct-merge", "none"], DEFAULT_TICKET_SETUP.build.completion, `${label}.completion`),
         provider: enumField(raw.provider, ["auto", "github", "gitlab", "local"], DEFAULT_TICKET_SETUP.build.provider, `${label}.provider`),
         pr_ready: booleanField(raw.pr_ready, DEFAULT_TICKET_SETUP.build.pr_ready, `${label}.pr_ready`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "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",
@@ -118,8 +118,8 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.148"
   },
   "dependencies": {
-    "special-agents": "0.8.1",
-    "rafi-spec": "0.8.1",
+    "special-agents": "0.8.2",
+    "rafi-spec": "0.8.2",
     "@clack/prompts": "^1.4.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",