ai-foreman 1.3.0 → 1.4.0

package/README.md

@@ -123,9 +123,13 @@ Branch-mode examples:
 ```bash
 ai-foreman start ./my-project --steps 3 --branch-per-ticket --agent codex
 ai-foreman start ./my-project --steps 3 --create-pr --pr-ready --agent codex
+ai-foreman start ./my-project --steps 3 --completion auto-merge --provider gitlab
+ai-foreman start ./my-project --steps 3 --completion direct-merge
 ai-foreman start ./my-project --steps 1 --branch-per-ticket --continue --ticket T001
 ```
 
+Saved `tickets.build` defaults in `rafi-config.yaml` can enable branch-per-ticket and completion behavior automatically. Use `--completion pr|auto-merge|direct-merge|none`, `--no-branch-per-ticket`, `--no-create-pr`, or `--auto-merge-wait` / `--no-auto-merge-wait` to override saved defaults for one run.
+
 ### GitHub PR Failure Recovery
 
 When `--create-pr` cannot prepare GitHub, push a branch, or create a PR, Foreman records a structured failure and blocks the affected ticket cleanly. Blocked worktrees are retained automatically so you can repair the environment and retry without losing the ticket session.
@@ -164,6 +168,10 @@ gh repo view <host>/<owner>/<repo>
 | `--fast` | flag | off | Lower latency. |
 | `-y, --yes` | flag | off | Skips confirmation before builder edits ticket files. |
 
+Use `ai-foreman tickets setup:init` or `setup:update` to save local, Linear, or Jira Cloud ticket sources in `rafi-config.yaml`. Linear imports use `LINEAR_API_KEY`; Jira Cloud imports use `JIRA_EMAIL` and `JIRA_API_TOKEN`. Imported provider payloads are snapshotted under ignored `.tickets/imports/`, and mirrored tickets carry `external_refs`.
+
+Use `ai-foreman tickets review` to accept, defer, or dismiss pending split/combine/duplicate recommendations rendered in the progress doc.
+
 ## What Foreman Does
 
 During a run, Foreman:
@@ -258,11 +266,15 @@ Init options:
 | `-p, --project <dir>` | `./my-project` / `../repo` | current directory | Project to initialize. |
 | `--app-name <name>` | `"My App"` | none | Application name stored in tracker config. |
 | `--timezone <tz>` | `America/Chicago` / `UTC` | `UTC` | IANA timezone. |
-| `--queue-limit <n>` | `25` / `50` / `100` | `50` | Next-queue window size. |
+| `--implementation-limit <n>` | `250` / `500` / `1000` | `500` | Implementation queue window for generated docs and Foreman selection. |
+| `--view-limit <n>` | `1000` / `20000` | `20000` | Default row limit for the display queue command. |
+| `--queue-limit <n>` | `250` / `500` / `1000` | none | Deprecated alias for `--implementation-limit`. |
 | `--docs-root <dir>` | `docs` / `docs-rafi` | `rafi-config.yaml` docs.root, then `docs` | Root for generated progress/archive docs. |
 
 `tickets init` reads `docs.root` from `rafi-config.yaml` when present. `--docs-root` overrides that value. The selected root must be a safe repo-relative directory, and init refuses to overwrite an existing selected `ticket-progress.md`.
 
+Init writes `implementation_limit` and `view_limit` to `.tickets/config.yaml`. Existing configs with `queue_limit` still load as an implementation limit, with the old default value `50` upgraded to `500`.
+
 This creates:
 
 ```txt

package/dist/branch/git.d.ts

@@ -24,3 +24,5 @@ export declare function hasWorktreeChanges(worktreePath: string): boolean;
 export declare function commitAll(worktreePath: string, message: string): string | undefined;
 export declare function headCommitIfAhead(worktreePath: string, base: string): string | undefined;
 export declare function pushBranch(worktreePath: string, branch: string): void;
+export declare function squashMergeBranchToLocalBase(projectDir: string, branch: string, baseBranch: string, message: string): string;
+export declare function deleteLocalBranch(projectDir: string, branch: string): void;

package/dist/branch/git.js

@@ -26,7 +26,7 @@ export function generatedTrackerDirtyPaths(paths) {
     return out;
 }
 export function ensureCleanBaseWorktree(cwd, opts = {}) {
-    const allowedDirtyPaths = new Set((opts.allowedDirtyPaths ?? []).map(normalizeRepoPath));
+    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) => {
         const path = normalizeRepoPath(line.slice(3));
@@ -101,6 +101,23 @@ export function headCommitIfAhead(worktreePath, base) {
 export function pushBranch(worktreePath, branch) {
     runGit(worktreePath, ["push", "-u", "origin", branch]);
 }
+export function squashMergeBranchToLocalBase(projectDir, branch, baseBranch, message) {
+    const current = currentGitRef(projectDir);
+    if (current !== baseBranch) {
+        runGit(projectDir, ["checkout", baseBranch]);
+    }
+    runGit(projectDir, ["merge", "--squash", branch]);
+    runGit(projectDir, ["commit", "-m", message]);
+    return runGit(projectDir, ["rev-parse", "--short", "HEAD"]).stdout;
+}
+export function deleteLocalBranch(projectDir, branch) {
+    try {
+        runGit(projectDir, ["branch", "-D", branch]);
+    }
+    catch {
+        // Branch cleanup is best-effort; worktree removal already frees the checkout.
+    }
+}
 function normalizeRepoPath(path) {
     return path
         .replace(/\\/g, "/")

package/dist/branch/github.d.ts

@@ -1,4 +1,4 @@
-import type { BranchPlanNode, GitHubFailure, GitHubOperationResult, GitHubReadinessResult, GitHubRemote, GitHubRemoteResult, PrResult } from "./types.js";
+import type { BranchPlanNode, GitHubFailure, GitHubOperationResult, GitHubReadinessResult, GitHubRemote, GitHubRemoteResult, PrResult, ReviewMergeStatus } from "./types.js";
 export declare function inspectGitHubRemote(cwd: string): GitHubRemoteResult;
 export declare function originLooksLikeGitHub(cwd: string): boolean;
 export declare function checkGitHubReadiness(cwd: string): GitHubReadinessResult;
@@ -17,5 +17,7 @@ export interface CreatePrOptions {
     commit?: string;
 }
 export declare function createOrReusePr(cwd: string, opts: CreatePrOptions): PrResult;
+export declare function enableGitHubAutoMerge(cwd: string, branch: string, cleanup: boolean): PrResult;
+export declare function checkGitHubPrMerged(cwd: string, branch: string): ReviewMergeStatus;
 export declare function formatGitHubFailure(failure: GitHubFailure): string;
 export {};

package/dist/branch/github.js

@@ -157,6 +157,38 @@ export function createOrReusePr(cwd, opts) {
         return { status: "created", url: created.stdout };
     return prFailure(classifyPrFailure(created, opts.node.branch, "Failed to create GitHub PR.", remoteForRepair));
 }
+export function enableGitHubAutoMerge(cwd, branch, cleanup) {
+    const args = ["pr", "merge", branch, "--auto", "--squash"];
+    if (cleanup)
+        args.push("--delete-branch");
+    const result = runCommand(cwd, "gh", args, 30_000);
+    if (result.ok)
+        return { status: "auto_merge_enabled", url: result.stdout };
+    return prFailure(classifyPrFailure(result, branch, "Failed to enable GitHub PR auto-merge."));
+}
+export function checkGitHubPrMerged(cwd, branch) {
+    const remote = inspectGitHubRemote(cwd);
+    const remoteForRepair = remote.ok ? remote.remote : undefined;
+    const result = runCommand(cwd, "gh", [
+        "pr",
+        "view",
+        branch,
+        "--json",
+        "state,url",
+        "--jq",
+        "[.state, .url] | @tsv",
+    ]);
+    if (!result.ok) {
+        return classifyPrFailure(result, branch, "Failed to check GitHub PR merge state.", remoteForRepair);
+    }
+    const [state, url] = result.stdout.split(/\t/);
+    return {
+        ok: true,
+        merged: state === "MERGED",
+        state,
+        url: url || undefined,
+    };
+}
 export function formatGitHubFailure(failure) {
     const lines = [
         `${failure.code}: ${failure.message}`,

package/dist/branch/gitlab.d.ts

@@ -0,0 +1,15 @@
+import type { BranchPlanNode, GitHubOperationResult, PrResult, ReviewMergeStatus } from "./types.js";
+export declare function preflightGlab(cwd: string): GitHubOperationResult;
+export declare function pushBranchForMr(cwd: string, branch: string): GitHubOperationResult;
+export interface CreateMrOptions {
+    node: BranchPlanNode;
+    ready: boolean;
+    runId: string;
+    qaEvidence?: string;
+    commit?: string;
+    autoMerge?: boolean;
+    cleanup?: boolean;
+}
+export declare function createOrReuseMr(cwd: string, opts: CreateMrOptions): PrResult;
+export declare function enableGitLabAutoMerge(cwd: string, branch: string, cleanup: boolean): PrResult;
+export declare function checkGitLabMrMerged(cwd: string, branch: string): ReviewMergeStatus;

package/dist/branch/gitlab.js

@@ -0,0 +1,290 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
+const OUTPUT_LIMIT = 2_000;
+export function preflightGlab(cwd) {
+    const version = runCommand(cwd, "glab", ["--version"], 5_000);
+    if (!version.ok) {
+        return failure("glab_missing", "GitLab CLI is not installed or is not on PATH.", [
+            "Install GitLab CLI: https://gitlab.com/gitlab-org/cli",
+            "glab --version",
+        ], version);
+    }
+    const remote = runCommand(cwd, "git", ["remote", "get-url", "origin"]);
+    if (!remote.ok) {
+        return failure("remote_missing", "git remote origin is not configured.", [
+            "git remote add origin <gitlab repo url>",
+            "git remote get-url origin",
+        ], remote);
+    }
+    if (!looksGitLab(remote.stdout)) {
+        return failure("remote_not_gitlab", `origin does not look like a GitLab remote: ${remote.stdout}`, [
+            "git remote set-url origin <gitlab repo url>",
+            "git remote get-url origin",
+        ], remote);
+    }
+    const auth = runCommand(cwd, "glab", ["auth", "status"], 10_000);
+    if (!auth.ok) {
+        return classifyCommandFailure(auth, "glab_not_authenticated", "GitLab CLI is not authenticated.", [
+            "glab auth login",
+            "glab auth status",
+        ]);
+    }
+    return { ok: true, output: version.stdout };
+}
+export function pushBranchForMr(cwd, branch) {
+    const result = runCommand(cwd, "git", ["push", "-u", "origin", branch], 30_000);
+    if (result.ok)
+        return { ok: true, output: result.stdout };
+    return classifyCommandFailure(result, "push_failed", [
+        `Failed to push branch ${branch} to origin.`,
+        "Branch push requires write access and working Git credentials for the remote.",
+    ].join(" "), [
+        `git push -u origin ${branch}`,
+        "git ls-remote origin",
+    ]);
+}
+export function createOrReuseMr(cwd, opts) {
+    const existing = findExistingMr(cwd, opts.node.branch);
+    if (!existing.ok)
+        return prFailure(existing);
+    if (existing.url)
+        return { status: "existing", url: existing.url };
+    const bodyPath = join(cwd, ".foreman", "mr-bodies", opts.runId, `${opts.node.ticket.id}.md`);
+    try {
+        mkdirSync(join(cwd, ".foreman", "mr-bodies", opts.runId), { recursive: true });
+        writeFileSync(bodyPath, buildMrBody(opts), "utf8");
+    }
+    catch (err) {
+        return prFailure(failure("mr_create_failed", `Failed to write GitLab MR body file at ${bodyPath}.`, [
+            `mkdir -p ${shellQuote(join(".foreman", "mr-bodies", opts.runId))}`,
+        ], undefined, err instanceof Error ? err.message : String(err)));
+    }
+    const args = [
+        "mr",
+        "create",
+        "--source-branch",
+        opts.node.branch,
+        "--target-branch",
+        opts.node.baseBranch,
+        "--title",
+        `${opts.node.ticket.id}: ${opts.node.ticket.title}`,
+        "--description",
+        readBodyArg(bodyPath),
+        "--yes",
+    ];
+    if (!opts.ready)
+        args.push("--draft");
+    if (opts.autoMerge)
+        args.push("--auto-merge", "--squash-before-merge");
+    if (opts.cleanup)
+        args.push("--remove-source-branch");
+    const created = runCommand(cwd, "glab", args);
+    if (created.ok)
+        return { status: "created", url: created.stdout };
+    return prFailure(classifyCommandFailure(created, "mr_create_failed", `Failed to create GitLab MR. Branch: ${opts.node.branch}`, [
+        `glab mr create --source-branch ${opts.node.branch} --target-branch ${opts.node.baseBranch}`,
+        "glab auth status",
+    ]));
+}
+export function enableGitLabAutoMerge(cwd, branch, cleanup) {
+    const args = ["mr", "merge", branch, "--auto-merge", "--squash", "--yes"];
+    if (cleanup)
+        args.push("--remove-source-branch");
+    const result = runCommand(cwd, "glab", args, 30_000);
+    if (result.ok)
+        return { status: "auto_merge_enabled", url: result.stdout };
+    return prFailure(classifyCommandFailure(result, "mr_create_failed", `Failed to enable GitLab MR auto-merge. Branch: ${branch}`, [
+        `glab mr merge ${branch} --auto-merge --squash --yes`,
+        "glab auth status",
+    ]));
+}
+export function checkGitLabMrMerged(cwd, branch) {
+    const result = runCommand(cwd, "glab", [
+        "mr",
+        "view",
+        branch,
+        "--output",
+        "json",
+    ]);
+    if (!result.ok) {
+        return classifyCommandFailure(result, "mr_create_failed", `Failed to check GitLab MR merge state. Branch: ${branch}`, [
+            `glab mr view ${branch} --output json`,
+            "glab auth status",
+        ]);
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const state = parsed.state;
+        return {
+            ok: true,
+            merged: state === "merged" || state === "merged_results" || Boolean(parsed.merged_at ?? parsed.mergedAt),
+            state,
+            url: parsed.web_url ?? parsed.webUrl,
+        };
+    }
+    catch {
+        return {
+            ok: true,
+            merged: /merged/i.test(result.stdout),
+            state: result.stdout.slice(0, 120),
+        };
+    }
+}
+function findExistingMr(cwd, branch) {
+    const result = runCommand(cwd, "glab", [
+        "mr",
+        "list",
+        "--source-branch",
+        branch,
+        "--output",
+        "json",
+    ]);
+    if (!result.ok) {
+        return classifyCommandFailure(result, "mr_create_failed", "Failed to check for an existing GitLab MR.", [
+            `glab mr list --source-branch ${branch}`,
+            "glab auth status",
+        ]);
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const first = Array.isArray(parsed) ? parsed[0] : undefined;
+        return { ok: true, url: first?.web_url ?? first?.webUrl };
+    }
+    catch {
+        return { ok: true, url: undefined };
+    }
+}
+function runCommand(cwd, bin, args, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+    const result = spawnSync(bin, args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: commandTimeoutMs(timeoutMs),
+    });
+    const stdout = outputToString(result.stdout).trim();
+    const stderr = outputToString(result.stderr).trim();
+    const output = truncateOutput([stderr, stdout].filter(Boolean).join("\n").trim());
+    const error = result.error;
+    return {
+        ok: !error && result.status === 0,
+        command: commandDisplay(bin, args),
+        stdout,
+        stderr,
+        output,
+        status: result.status,
+        signal: result.signal,
+        errorCode: error?.code,
+        errorMessage: error?.message,
+        timedOut: error?.code === "ETIMEDOUT" || result.signal === "SIGTERM",
+    };
+}
+function commandTimeoutMs(defaultMs) {
+    const raw = process.env.RAFI_GITLAB_COMMAND_TIMEOUT_MS;
+    if (!raw)
+        return defaultMs;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : defaultMs;
+}
+function classifyCommandFailure(result, fallbackCode, fallbackMessage, repairCommands) {
+    if (result.errorCode === "ENOENT") {
+        return failure("glab_missing", "GitLab CLI is not installed or is not on PATH.", [
+            "Install GitLab CLI: https://gitlab.com/gitlab-org/cli",
+            "glab --version",
+        ], result);
+    }
+    if (result.timedOut || looksNetworkLike(result.output) || looksNetworkLike(result.errorMessage ?? "")) {
+        return failure("network_or_timeout", `${fallbackMessage} The command timed out or hit a network error.`, repairCommands, result);
+    }
+    if (looksUnauthenticated(result.output)) {
+        return failure("glab_not_authenticated", fallbackMessage, repairCommands, result);
+    }
+    return failure(fallbackCode, fallbackMessage, repairCommands, result);
+}
+function failure(code, message, repairCommands, result, outputOverride) {
+    return {
+        ok: false,
+        code,
+        message,
+        repairCommands,
+        command: result?.command,
+        output: outputOverride ?? (result?.output || result?.errorMessage ? truncateOutput([result?.output, result?.errorMessage].filter(Boolean).join("\n")) : undefined),
+    };
+}
+function prFailure(failure) {
+    return {
+        status: "failed",
+        error: failure.message,
+        code: failure.code,
+        message: failure.message,
+        repairCommands: failure.repairCommands,
+        command: failure.command,
+        output: failure.output,
+    };
+}
+function looksGitLab(remote) {
+    return /gitlab\./i.test(remote) || /gitlab\.com/i.test(remote);
+}
+function looksUnauthenticated(output) {
+    return [
+        /not logged in/i,
+        /authentication required/i,
+        /could not authenticate/i,
+        /unauthorized/i,
+        /\b401\b/,
+    ].some((pattern) => pattern.test(output));
+}
+function looksNetworkLike(output) {
+    return [
+        /timed? out/i,
+        /could not resolve host/i,
+        /failed to connect/i,
+        /connection (?:reset|refused|closed)/i,
+        /\b(?:ENOTFOUND|ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN)\b/i,
+    ].some((pattern) => pattern.test(output));
+}
+function readBodyArg(bodyPath) {
+    return readFileSync(bodyPath, "utf8");
+}
+function buildMrBody(opts) {
+    const ticket = opts.node.ticket;
+    return [
+        `## ${ticket.id}: ${ticket.title}`,
+        "",
+        ticket.summary,
+        "",
+        "## Acceptance Criteria",
+        ...ticket.acceptance.map((item) => `- ${item}`),
+        "",
+        "## Validation",
+        opts.qaEvidence ?? "Foreman QA emitted qa_pass.",
+        "",
+        "## Branch Metadata",
+        `- Base: ${opts.node.baseBranch}`,
+        `- Head: ${opts.node.branch}`,
+        `- Dependencies: ${opts.node.dependencies.length ? opts.node.dependencies.join(", ") : "None"}`,
+        `- Commit: ${opts.commit ?? "N/A"}`,
+        "",
+        "Generated by Rafi ai-foreman branch-per-ticket mode.",
+        "",
+    ].join("\n");
+}
+function commandDisplay(bin, args) {
+    return [bin, ...args.map(shellQuote)].join(" ");
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
+function outputToString(value) {
+    if (!value)
+        return "";
+    return Buffer.isBuffer(value) ? value.toString("utf8") : value;
+}
+function truncateOutput(output) {
+    if (output.length <= OUTPUT_LIMIT)
+        return output;
+    return `${output.slice(0, OUTPUT_LIMIT).trimEnd()}\n... truncated ...`;
+}

package/dist/branch/planner.d.ts

@@ -12,6 +12,7 @@ export interface BuildBranchPlanOptions {
     branchPrefix: string;
     maxBranchDepth: number;
     auditDependencies?: AuditDependency[];
+    rootBaseBranches?: boolean;
 }
 export declare function buildBranchPlan(tickets: TicketDef[], states: Map<string, TicketState>, opts: BuildBranchPlanOptions): BranchPlan;
 export declare function selectTicketsForBranchRun(tickets: TicketDef[], states: Map<string, TicketState>, steps: number): TicketDef[];

package/dist/branch/planner.js

@@ -60,7 +60,9 @@ export function buildBranchPlan(tickets, states, opts) {
         const dependencies = dependencyMap.get(ticket.id) ?? [];
         const branch = branchById.get(ticket.id);
         const baseTicket = chooseBaseDependency(dependencies, dependencyMap);
-        const baseBranch = baseTicket ? (branchById.get(baseTicket) ?? opts.baseRef) : opts.baseRef;
+        const baseBranch = opts.rootBaseBranches
+            ? opts.baseRef
+            : baseTicket ? (branchById.get(baseTicket) ?? opts.baseRef) : opts.baseRef;
         const node = {
             ticket,
             branch,

package/dist/branch/resume.d.ts

@@ -12,6 +12,8 @@ export interface BranchResumeSession {
     fast?: boolean;
     qaEnabled?: boolean;
     createPr?: boolean;
+    completionMode?: string;
+    reviewProvider?: string;
     prReady?: boolean;
     keepWorktrees?: boolean;
     ts?: string;

package/dist/branch/resume.js

@@ -39,6 +39,8 @@ export function findResumableBranchSessions(foremanDir) {
                     fast: booleanField(record.fast),
                     qaEnabled: booleanField(record.qaEnabled),
                     createPr: booleanField(record.createPr),
+                    completionMode: stringField(record.completionMode),
+                    reviewProvider: stringField(record.reviewProvider),
                     prReady: booleanField(record.prReady),
                     keepWorktrees: booleanField(record.keepWorktrees),
                     ts: stringField(record.ts),
@@ -63,7 +65,9 @@ export function formatBranchContinueCommand(projectDir, session) {
         shellQuote(projectDir),
         "--steps",
         "1",
-        session.createPr ? "--create-pr" : "--branch-per-ticket",
+        ...(session.completionMode && session.completionMode !== "none"
+            ? ["--completion", shellQuote(session.completionMode)]
+            : [session.createPr ? "--create-pr" : "--branch-per-ticket"]),
         "--continue",
         "--ticket",
         shellQuote(session.ticket),
@@ -74,6 +78,8 @@ export function formatBranchContinueCommand(projectDir, session) {
         args.push("--model", shellQuote(session.model));
     if (session.effort)
         args.push("--effort", shellQuote(session.effort));
+    if (session.reviewProvider)
+        args.push("--provider", shellQuote(session.reviewProvider));
     if (session.fast)
         args.push("--fast");
     if (session.qaEnabled === false)

package/dist/branch/runner.d.ts

@@ -1,6 +1,6 @@
 import type { BuilderAdapter, EffortLevel } from "../adapters/types.js";
 import type { Log } from "../log.js";
-import type { BranchPlan, BranchPlanNode, BranchRunSummary } from "./types.js";
+import type { BranchPlan, BranchPlanNode, BranchRunSummary, CompletionMode, ReviewProvider } from "./types.js";
 export interface BranchRunnerOptions {
     projectDir: string;
     runId: string;
@@ -13,8 +13,13 @@ export interface BranchRunnerOptions {
     notificationsEnabled: boolean;
     qaEnabled: boolean;
     createPr: boolean;
+    completionMode?: CompletionMode;
+    reviewProvider?: ReviewProvider;
     prReady: boolean;
     keepWorktrees: boolean;
+    cleanupBranches?: boolean;
+    autoMergeWait?: boolean;
+    autoMergeTimeoutMinutes?: number | null;
     allowedBaseDirtyPaths?: string[];
     trackerPaths?: {
         progressDoc: string;