ai-foreman 1.0.10 → 1.0.12

package/README.md

@@ -94,6 +94,14 @@ What each part does:
 | `--no-qa` | flag | QA on | Disables per-ticket QA review. |
 | `--continue` | flag | off | Resumes the most recent logged session. |
 | `-r, --resume <sessionId>` | session ID from `.foreman/` logs | none | Resumes a specific Claude/Codex session. |
+| `--branch-per-ticket` | flag | off | Runs each selected structured ticket in its own git worktree and branch. Requires initialized `.tickets/`. |
+| `--create-pr` | flag | off | Pushes each successful ticket branch and creates a GitHub PR. Implies `--branch-per-ticket`. |
+| `--pr-ready` | flag | draft PRs | Creates ready-for-review PRs instead of draft PRs when used with `--create-pr`. |
+| `--keep-worktrees` | flag | remove successful worktrees | Keeps successful ticket worktrees for inspection. Blocked worktrees are kept automatically. |
+| `--ticket <id>` | `T001` | none | Selects a branch-mode ticket to continue. Repeatable with `--continue`. |
+| `--base <ref>` | `main` / `origin/main` / `HEAD` | current branch or `HEAD` | Base ref for root ticket branches. |
+| `--branch-prefix <prefix>` | `rafi` / `feature` | `rafi` | Prefix for generated ticket branches. |
+| `--max-branch-depth <n>` | `1` / `2` / `3` | `2` | Maximum selected branch stack depth. |
 
 Auto-detected tracker files:
 
@@ -104,6 +112,43 @@ Resume rule:
 
 - Use either `--continue` or `--resume`.
 - Do not use both in the same command.
+- In branch mode, use `--continue --ticket <id>` to continue a ticket with its saved builder session.
+- For multiple branch tickets, repeat `--ticket` with `--continue`; do not reuse one explicit `--resume <sessionId>` across multiple tickets.
+- When a branch run ends blocked, Foreman prints paste-ready continue commands for resumable tickets.
+
+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 1 --branch-per-ticket --continue --ticket T001
+```
+
+### 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.
+
+`ai-foreman status ./my-project` shows the latest GitHub failure code, repair commands, last command output, and a retry command when a resumable ticket session exists.
+
+Common failure codes:
+
+| Code | Meaning |
+| --- | --- |
+| `gh_missing` | GitHub CLI is not installed or not on `PATH`. |
+| `gh_not_authenticated` | `gh` is installed but not authenticated for the remote host. |
+| `repo_unreachable` | `gh repo view` cannot access the target repository. |
+| `git_remote_unreachable` | `git ls-remote` cannot access the configured remote. |
+| `network_or_timeout` | A GitHub or git command timed out or hit a network error. |
+| `push_failed` | The ticket branch could not be pushed. |
+| `pr_create_failed` | The branch pushed, but PR creation or PR body writing failed. |
+
+For GitHub Enterprise remotes, repair commands include the remote host:
+
+```bash
+gh auth login --hostname <host>
+gh auth status --hostname <host>
+gh repo view <host>/<owner>/<repo>
+```
 
 ### `ai-foreman tickets populate`
 
@@ -522,5 +567,3 @@ Package output:
 - **`special-agents`** — library (rules + skills + agents + composition)
 - **`ai-foreman`** — this runtime
 - **`@rafi-ai/cli`** — CLI for `rafi create` and `rafi compile`
-
-

package/dist/adapters/codex.js

@@ -55,6 +55,7 @@ export class CodexAdapter {
     _activeProc;
     constructor(opts) {
         this.opts = opts;
+        this._sessionId = opts.resumeSessionId;
     }
     /**
      * Prepend role system text to a turn instruction when `systemPromptAppend` is

package/dist/branch/git.d.ts

@@ -0,0 +1,22 @@
+export interface GitCommandResult {
+    stdout: string;
+}
+export interface BaseWorktreeCleanOptions {
+    allowedDirtyPaths?: string[];
+}
+export declare function runGit(cwd: string, args: string[]): GitCommandResult;
+export declare function currentGitRef(cwd: string): string;
+export declare function generatedTrackerDirtyPaths(paths: {
+    stateDb: string;
+    progressDoc: string;
+}): 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;
+export declare function removeTicketWorktree(projectDir: string, worktreePath: string): void;
+export declare function currentWorktreeBranch(worktreePath: string): string;
+export declare function hasTrackerChanges(worktreePath: string): boolean;
+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;

package/dist/branch/git.js

@@ -0,0 +1,94 @@
+import { execFileSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function runGit(cwd, args) {
+    const stdout = execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return { stdout: stdout.trim() };
+}
+export function currentGitRef(cwd) {
+    const branch = runGit(cwd, ["branch", "--show-current"]).stdout;
+    return branch || "HEAD";
+}
+export function generatedTrackerDirtyPaths(paths) {
+    const stateDb = normalizeRepoPath(paths.stateDb);
+    const progressDoc = normalizeRepoPath(paths.progressDoc);
+    return [
+        stateDb,
+        `${stateDb}-wal`,
+        `${stateDb}-shm`,
+        progressDoc,
+        `${progressDoc}.tmp`,
+    ];
+}
+export function ensureCleanBaseWorktree(cwd, opts = {}) {
+    const allowedDirtyPaths = new Set((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));
+        return !path.startsWith(".foreman/") && !allowedDirtyPaths.has(path);
+    });
+    if (dirty.length > 0) {
+        throw new Error(`base worktree has uncommitted changes:\n${dirty.join("\n")}`);
+    }
+}
+export function ensureForemanExcluded(cwd) {
+    const excludePath = join(cwd, ".git", "info", "exclude");
+    if (!existsSync(excludePath))
+        return;
+    const line = ".foreman/";
+    if (readFileSync(excludePath, "utf8").split(/\r?\n/).includes(line))
+        return;
+    appendFileSync(excludePath, `\n${line}\n`, "utf8");
+}
+export function createTicketWorktree(projectDir, runId, branch, base) {
+    const worktreePath = join(projectDir, ".foreman", "worktrees", runId, branch.replace(/\//g, "__"));
+    mkdirSync(dirname(worktreePath), { recursive: true });
+    runGit(projectDir, ["worktree", "add", "-b", branch, worktreePath, base]);
+    return worktreePath;
+}
+export function removeTicketWorktree(projectDir, worktreePath) {
+    try {
+        runGit(projectDir, ["worktree", "remove", "--force", worktreePath]);
+    }
+    catch {
+        rmSync(worktreePath, { recursive: true, force: true });
+    }
+}
+export function currentWorktreeBranch(worktreePath) {
+    return runGit(worktreePath, ["branch", "--show-current"]).stdout;
+}
+export function hasTrackerChanges(worktreePath) {
+    const status = runGit(worktreePath, ["status", "--porcelain", "--", ".tickets", "docs/ticket-progress.md", "ticket-progress.md"]).stdout;
+    return status.trim().length > 0;
+}
+export function hasWorktreeChanges(worktreePath) {
+    return runGit(worktreePath, ["status", "--porcelain"]).stdout.trim().length > 0;
+}
+export function commitAll(worktreePath, message) {
+    if (!hasWorktreeChanges(worktreePath))
+        return undefined;
+    runGit(worktreePath, ["add", "-A"]);
+    runGit(worktreePath, ["commit", "-m", message]);
+    return runGit(worktreePath, ["rev-parse", "--short", "HEAD"]).stdout;
+}
+export function headCommitIfAhead(worktreePath, base) {
+    try {
+        const count = Number.parseInt(runGit(worktreePath, ["rev-list", "--count", `${base}..HEAD`]).stdout, 10);
+        if (!Number.isInteger(count) || count < 1)
+            return undefined;
+        return runGit(worktreePath, ["rev-parse", "--short", "HEAD"]).stdout;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function pushBranch(worktreePath, branch) {
+    runGit(worktreePath, ["push", "-u", "origin", branch]);
+}
+function normalizeRepoPath(path) {
+    return path
+        .replace(/\\/g, "/")
+        .replace(/^\.\/+/, "")
+        .replace(/\/+/g, "/")
+        .replace(/\/$/, "");
+}

package/dist/branch/github.d.ts

@@ -0,0 +1,21 @@
+import type { BranchPlanNode, GitHubFailure, GitHubOperationResult, GitHubReadinessResult, GitHubRemote, GitHubRemoteResult, PrResult } from "./types.js";
+export declare function inspectGitHubRemote(cwd: string): GitHubRemoteResult;
+export declare function originLooksLikeGitHub(cwd: string): boolean;
+export declare function checkGitHubReadiness(cwd: string): GitHubReadinessResult;
+export declare function preflightGh(cwd: string): GitHubReadinessResult;
+export declare function pushBranchForPr(cwd: string, branch: string): GitHubOperationResult;
+interface ExistingPrResult {
+    ok: true;
+    url?: string;
+}
+export declare function findExistingPr(cwd: string, branch: string, remote?: GitHubRemote): ExistingPrResult | GitHubFailure;
+export interface CreatePrOptions {
+    node: BranchPlanNode;
+    ready: boolean;
+    runId: string;
+    qaEvidence?: string;
+    commit?: string;
+}
+export declare function createOrReusePr(cwd: string, opts: CreatePrOptions): PrResult;
+export declare function formatGitHubFailure(failure: GitHubFailure): string;
+export {};

package/dist/branch/github.js

@@ -0,0 +1,414 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
+const OUTPUT_LIMIT = 2_000;
+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_GITHUB_COMMAND_TIMEOUT_MS;
+    if (!raw)
+        return defaultMs;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : defaultMs;
+}
+export function inspectGitHubRemote(cwd) {
+    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 <github repo url>",
+            "git remote get-url origin",
+        ], remote);
+    }
+    return parseGitHubRemote(remote.stdout);
+}
+export function originLooksLikeGitHub(cwd) {
+    const remote = inspectGitHubRemote(cwd);
+    return remote.ok && remote.remote.likelyGitHub;
+}
+export function checkGitHubReadiness(cwd) {
+    const ghVersion = runCommand(cwd, "gh", ["--version"], 5_000);
+    if (!ghVersion.ok) {
+        return failure("gh_missing", "GitHub CLI is not installed or is not on PATH.", [
+            "Install GitHub CLI: https://cli.github.com/",
+            "gh --version",
+        ], ghVersion);
+    }
+    const remote = inspectGitHubRemote(cwd);
+    if (!remote.ok)
+        return remote;
+    const auth = runCommand(cwd, "gh", ["auth", "status", "--hostname", remote.remote.host], 10_000);
+    if (!auth.ok) {
+        return classifyCommandFailure(auth, "gh_not_authenticated", authMessage(remote.remote), authRepair(remote.remote));
+    }
+    const repoView = runCommand(cwd, "gh", [
+        "repo",
+        "view",
+        remote.remote.repoArg,
+        "--json",
+        "nameWithOwner",
+        "--jq",
+        ".nameWithOwner",
+    ]);
+    if (!repoView.ok) {
+        return classifyCommandFailure(repoView, "repo_unreachable", repoMessage(remote.remote), [
+            `gh repo view ${remote.remote.repoArg}`,
+            ...authRepair(remote.remote),
+        ]);
+    }
+    const lsRemote = runCommand(cwd, "git", ["ls-remote", "origin"]);
+    if (!lsRemote.ok) {
+        return classifyCommandFailure(lsRemote, "git_remote_unreachable", [
+            "git cannot reach the origin remote. Check SSH/token credentials, VPN, network access, and repository permissions.",
+            `Origin: ${remote.remote.remoteUrl}`,
+        ].join(" "), [
+            "git ls-remote origin",
+            "git remote -v",
+        ]);
+    }
+    return { ok: true, remote: remote.remote };
+}
+export function preflightGh(cwd) {
+    return checkGitHubReadiness(cwd);
+}
+export function pushBranchForPr(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 findExistingPr(cwd, branch, remote) {
+    const result = runCommand(cwd, "gh", [
+        "pr",
+        "list",
+        "--head",
+        branch,
+        "--state",
+        "open",
+        "--json",
+        "url",
+        "--jq",
+        ".[0].url",
+    ]);
+    if (result.ok)
+        return { ok: true, url: result.stdout || undefined };
+    return classifyPrFailure(result, branch, "Failed to check for an existing GitHub PR.", remote);
+}
+export function createOrReusePr(cwd, opts) {
+    const remote = inspectGitHubRemote(cwd);
+    const remoteForRepair = remote.ok ? remote.remote : undefined;
+    const existing = findExistingPr(cwd, opts.node.branch, remoteForRepair);
+    if (!existing.ok)
+        return prFailure(existing);
+    if (existing.url)
+        return { status: "existing", url: existing.url };
+    const bodyPath = join(cwd, ".foreman", "pr-bodies", opts.runId, `${opts.node.ticket.id}.md`);
+    try {
+        mkdirSync(join(cwd, ".foreman", "pr-bodies", opts.runId), { recursive: true });
+        writeFileSync(bodyPath, buildPrBody(opts), "utf8");
+    }
+    catch (err) {
+        return prFailure(prBodyWriteFailure(opts.runId, bodyPath, err));
+    }
+    const args = [
+        "pr",
+        "create",
+        "--base",
+        opts.node.baseBranch,
+        "--head",
+        opts.node.branch,
+        "--title",
+        `${opts.node.ticket.id}: ${opts.node.ticket.title}`,
+        "--body-file",
+        bodyPath,
+    ];
+    if (!opts.ready)
+        args.push("--draft");
+    const created = runCommand(cwd, "gh", args);
+    if (created.ok)
+        return { status: "created", url: created.stdout };
+    return prFailure(classifyPrFailure(created, opts.node.branch, "Failed to create GitHub PR.", remoteForRepair));
+}
+export function formatGitHubFailure(failure) {
+    const lines = [
+        `${failure.code}: ${failure.message}`,
+        "Repair and verify:",
+        ...failure.repairCommands.map((command) => `  ${command}`),
+    ];
+    if (failure.output) {
+        lines.push("", "Command output:", indent(failure.output));
+    }
+    else if (failure.command) {
+        lines.push("", `Command: ${failure.command}`);
+    }
+    return lines.join("\n");
+}
+function parseGitHubRemote(remoteUrl) {
+    const parsed = parseRemoteParts(remoteUrl.trim());
+    if (!parsed) {
+        return failure("remote_not_github", `origin does not look like a GitHub remote: ${remoteUrl}`, [
+            "git remote set-url origin <github repo url>",
+            "git remote get-url origin",
+        ]);
+    }
+    const repo = parsed.repo.replace(/\.git$/i, "");
+    if (!parsed.owner || !repo || isKnownNonGitHubHost(parsed.host)) {
+        return failure("remote_not_github", `origin does not look like a GitHub remote: ${remoteUrl}`, [
+            "git remote set-url origin <github repo url>",
+            "git remote get-url origin",
+        ]);
+    }
+    const likelyGitHub = isLikelyGitHubHost(parsed.host);
+    const repoArg = parsed.host === "github.com"
+        ? `${parsed.owner}/${repo}`
+        : `${parsed.host}/${parsed.owner}/${repo}`;
+    return {
+        ok: true,
+        remote: {
+            remoteUrl,
+            host: parsed.host,
+            owner: parsed.owner,
+            repo,
+            repoArg,
+            likelyGitHub,
+        },
+    };
+}
+function parseRemoteParts(remoteUrl) {
+    const scpLike = /^(?:[^@/\s]+@)?([^:/\s]+):([^/\s]+)\/(.+)$/.exec(remoteUrl);
+    if (scpLike) {
+        return {
+            host: scpLike[1].toLowerCase(),
+            owner: scpLike[2],
+            repo: lastPathPart(scpLike[3]),
+        };
+    }
+    try {
+        const url = new URL(remoteUrl);
+        if (!url.hostname)
+            return undefined;
+        const parts = url.pathname.split("/").filter(Boolean);
+        if (parts.length < 2)
+            return undefined;
+        return {
+            host: url.hostname.toLowerCase(),
+            owner: parts[0],
+            repo: lastPathPart(parts.slice(1).join("/")),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function lastPathPart(path) {
+    const parts = path.split("/").filter(Boolean);
+    return parts[parts.length - 1] ?? "";
+}
+function classifyPrFailure(result, branch, message, remote) {
+    if (looksUnauthenticated(result.output)) {
+        return failure("gh_not_authenticated", "GitHub CLI is not authenticated for PR operations.", prRepair(branch, remote), result);
+    }
+    return classifyCommandFailure(result, "pr_create_failed", `${message} Branch: ${branch}`, prRepair(branch, remote));
+}
+function classifyCommandFailure(result, fallbackCode, fallbackMessage, repairCommands) {
+    if (result.errorCode === "ENOENT") {
+        const command = result.command.startsWith("gh ") ? "GitHub CLI" : result.command.split(" ")[0];
+        return failure(result.command.startsWith("gh ") ? "gh_missing" : "unknown", `${command} is not installed or is not on PATH.`, result.command.startsWith("gh ")
+            ? ["Install GitHub CLI: https://cli.github.com/", "gh --version"]
+            : repairCommands, result);
+    }
+    if (looksRemoteNotGitHub(result.output)) {
+        return failure("remote_not_github", `${fallbackMessage} The origin host is not a GitHub or GitHub Enterprise host.`, repairCommands, result);
+    }
+    if (looksGhRepoResolutionFailure(result.output)) {
+        return failure("repo_unreachable", fallbackMessage, repairCommands, 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 (fallbackCode === "gh_not_authenticated" || looksUnauthenticated(result.output)) {
+        return failure("gh_not_authenticated", fallbackMessage, repairCommands, result);
+    }
+    return failure(fallbackCode, fallbackMessage, repairCommands, result);
+}
+function prBodyWriteFailure(runId, bodyPath, err) {
+    const bodyDir = join(".foreman", "pr-bodies", runId);
+    return {
+        ok: false,
+        code: "pr_create_failed",
+        message: `Failed to write GitHub PR body file at ${bodyPath}.`,
+        repairCommands: [
+            `ls -la ${shellQuote(join(".foreman", "pr-bodies"))}`,
+            `mkdir -p ${shellQuote(bodyDir)}`,
+        ],
+        output: err instanceof Error ? err.message : String(err),
+    };
+}
+function failure(code, message, repairCommands, result) {
+    return {
+        ok: false,
+        code,
+        message,
+        repairCommands,
+        command: result?.command,
+        output: 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 authMessage(remote) {
+    return `GitHub CLI is not authenticated for ${remote.host}.`;
+}
+function repoMessage(remote) {
+    return `GitHub CLI cannot view ${remote.repoArg}. Check repository existence and read/write permissions.`;
+}
+function authRepair(remote) {
+    if (remote.host === "github.com") {
+        return ["gh auth login", "gh auth status"];
+    }
+    return [
+        `gh auth login --hostname ${remote.host}`,
+        `gh auth status --hostname ${remote.host}`,
+    ];
+}
+function authRepairForPr(remote) {
+    return remote ? authRepair(remote) : ["gh auth login", "gh auth status"];
+}
+function prRepair(branch, remote) {
+    return [
+        `gh pr list --head ${branch} --state open`,
+        ...authRepairForPr(remote),
+        remote ? `gh repo view ${remote.repoArg}` : "gh repo view",
+    ];
+}
+function isLikelyGitHubHost(host) {
+    return host === "github.com" || host.includes("github.");
+}
+function isKnownNonGitHubHost(host) {
+    return [
+        "gitlab.com",
+        "bitbucket.org",
+        "codeberg.org",
+        "sr.ht",
+        "sourcehut.org",
+        "dev.azure.com",
+        "ssh.dev.azure.com",
+    ].includes(host);
+}
+function looksUnauthenticated(output) {
+    return [
+        /not logged in/i,
+        /authentication required/i,
+        /could not authenticate/i,
+        /bad credentials/i,
+        /\b401\b/,
+        /unauthorized/i,
+    ].some((pattern) => pattern.test(output));
+}
+function looksNetworkLike(output) {
+    return [
+        /timed? out/i,
+        /could not resolve host/i,
+        /couldn't resolve host/i,
+        /failed to connect/i,
+        /connection (?:reset|refused|closed)/i,
+        /network is unreachable/i,
+        /no route to host/i,
+        /name or service not known/i,
+        /temporary failure/i,
+        /\b(?:ENOTFOUND|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ECONNABORTED|EAI_AGAIN|EHOSTUNREACH)\b/i,
+        /TLS handshake timeout/i,
+    ].some((pattern) => pattern.test(output));
+}
+function looksGhRepoResolutionFailure(output) {
+    return /could not resolve to a Repository/i.test(output);
+}
+function looksRemoteNotGitHub(output) {
+    return [
+        /not a GitHub(?: Enterprise Server)? host/i,
+        /not a GitHub or GitHub Enterprise host/i,
+        /not a GitHub Enterprise Server/i,
+        /hostname .*is not.*github/i,
+    ].some((pattern) => pattern.test(output));
+}
+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 ...`;
+}
+function indent(value) {
+    return value.split("\n").map((line) => `  ${line}`).join("\n");
+}
+function buildPrBody(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");
+}

package/dist/branch/planner.d.ts

@@ -0,0 +1,19 @@
+import type { TicketDef } from "../tickets/ticketSchema.js";
+import type { TicketState } from "../tickets/stateDb.js";
+import type { BranchPlan } from "./types.js";
+export interface AuditDependency {
+    ticket: string;
+    dependsOn: string;
+    reason?: string;
+}
+export interface BuildBranchPlanOptions {
+    steps: number;
+    baseRef: string;
+    branchPrefix: string;
+    maxBranchDepth: number;
+    auditDependencies?: AuditDependency[];
+}
+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[];
+export declare function parseAuditDependencies(text: string): AuditDependency[];
+export declare function buildBranchAuditInstruction(tickets: TicketDef[]): string;