ai-foreman 1.0.12 → 1.2.0

package/README.md

@@ -85,7 +85,7 @@ What each part does:
 | --- | --- | --- | --- |
 | `<project>` | `./my-project` / `../repo` | required | Target repo the agent works in. |
 | `-s, --steps <n>` | `1` / `5` / `10` | required | Max tickets or implementation steps to drive. |
-| `-a, --agent <agent>` | `claude` / `codex` | `claude` | Builder agent. |
+| `-a, --agent <agent>` | `claude` / `codex` | single `rafi-config.yaml` target, otherwise `claude` | Builder agent. Explicit `--agent` always wins. |
 | `-m, --model <model>` | `gpt-5.5` / any supported agent model | agent default | Overrides the builder model. |
 | `--effort <level>` | Claude Code: `low` / `medium` / `high` / `xhigh`<br>Codex: `low` / `medium` / `high` / `xhigh` | agent default | Reasoning level. |
 | `--fast` | flag | off | Lower latency. For Codex, maps to `effort=low` when `--effort` is not set. |
@@ -105,6 +105,7 @@ What each part does:
 
 Auto-detected tracker files:
 
+- configured `paths.progress_doc` from `.tickets/config.yaml`
 - `docs/ticket-progress.md`
 - `ticket-progress.md`
 
@@ -155,7 +156,7 @@ gh repo view <host>/<owner>/<repo>
 | Option | Common values | Default | Notes |
 | --- | --- | --- | --- |
 | `-p, --project <dir>` | `./my-project` / `../repo` | current directory | Target repo with `.tickets/`. |
-| `-a, --agent <agent>` | `claude` / `codex` | `claude` | Builder agent. |
+| `-a, --agent <agent>` | `claude` / `codex` | single `rafi-config.yaml` target, otherwise `claude` | Builder agent. Explicit `--agent` always wins. |
 | `-m, --model <model>` | `gpt-5.5` / any supported agent model | agent default | Overrides the builder model. |
 | `--effort <level>` | Claude Code: `low` / `medium` / `high` / `xhigh`<br>Codex: `low` / `medium` / `high` / `xhigh` | agent default | Reasoning level. |
 | `--sources <paths...>` | `docs/tickets.md docs/plans/**` | scans relevant docs automatically | Optional files, folders, or globs for the agent to check first. Any reasonable planning format is OK. |
@@ -187,17 +188,25 @@ Without tickets, Foreman still works with:
 
 Claude Code:
 
-- Default agent.
+- Default agent when no single runtime target is configured.
 - Uses your existing Claude Code credentials.
 - Runs through the Claude Agent SDK.
-- `start` and `tickets populate` check Claude auth before launching the builder and prompt you to repair it if needed.
+- `start` and `tickets populate` check Claude auth before launching the builder and prompt you to repair it, switch to Codex for the current run, or cancel when interactive.
 
 Codex:
 
-- Use `--agent codex`.
+- Use `--agent codex`, or set `harness.targets: ["codex"]` in `rafi-config.yaml` and omit `--agent`.
 - Shells out to `codex exec`.
 - Requires the `codex` CLI on your `PATH`.
-- `start` and `tickets populate --agent codex` check Codex auth before launching the builder and prompt you to repair it if needed.
+- `start` and `tickets populate --agent codex` check Codex auth before launching the builder and prompt you to repair it, switch to Claude for the current run, or cancel when interactive.
+
+Runtime defaults and recovery:
+
+- If `--agent` is omitted, Foreman reads `rafi-config.yaml`. A single `harness.targets` value selects that runtime; missing config or both targets default to Claude.
+- Non-interactive and `--yes` runs fail clearly instead of switching runtimes automatically.
+- Resume and continue flows do not offer runtime switching because session IDs are runtime-specific.
+- If an interactive command switches providers, a provider-specific `--model` override is ignored for that run. `--effort` and `--fast` remain in effect.
+- Cancel stops the command and keeps project files, generated files, and installed packages in place.
 
 Task file:
 
@@ -249,6 +258,9 @@ Init options:
 | `--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. |
+| `--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`.
 
 This creates:
 
@@ -265,6 +277,8 @@ docs/
   ticket-progress.md
 ```
 
+With `--docs-root docs-rafi`, the generated tracker docs are written under `docs-rafi/` instead.
+
 ### 2. Add Tickets
 
 If the project already has planning material:
@@ -293,7 +307,7 @@ ai-foreman tickets populate --project ./my-project --agent codex --model gpt-5.5
 `populate` tells the builder to:
 
 - read `.tickets/*`
-- read `docs/ticket-progress.md`
+- read the configured progress doc
 - read existing planning files
 - fill `.tickets/tickets.yaml`
 - render the progress doc
@@ -401,7 +415,7 @@ ai-foreman tickets queue --project ./my-project
 
 Generated output:
 
-- `docs/ticket-progress.md` is generated from `.tickets/tickets.yaml`.
+- The configured progress doc is generated from `.tickets/tickets.yaml`.
 - It also includes state from `.tickets/ticket-state.sqlite`.
 - Builders should read it.
 - You should not manually edit generated sections.

package/dist/branch/git.d.ts

@@ -9,13 +9,17 @@ export declare function currentGitRef(cwd: string): string;
 export declare function generatedTrackerDirtyPaths(paths: {
     stateDb: string;
     progressDoc: string;
+    archiveDoc?: 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 hasTrackerChanges(worktreePath: string, paths?: {
+    progressDoc?: string;
+    archiveDoc?: 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;

package/dist/branch/git.js

@@ -12,13 +12,18 @@ export function currentGitRef(cwd) {
 export function generatedTrackerDirtyPaths(paths) {
     const stateDb = normalizeRepoPath(paths.stateDb);
     const progressDoc = normalizeRepoPath(paths.progressDoc);
-    return [
+    const out = [
         stateDb,
         `${stateDb}-wal`,
         `${stateDb}-shm`,
         progressDoc,
         `${progressDoc}.tmp`,
     ];
+    if (paths.archiveDoc) {
+        const archiveDoc = normalizeRepoPath(paths.archiveDoc);
+        out.push(archiveDoc, `${archiveDoc}.tmp`);
+    }
+    return out;
 }
 export function ensureCleanBaseWorktree(cwd, opts = {}) {
     const allowedDirtyPaths = new Set((opts.allowedDirtyPaths ?? []).map(normalizeRepoPath));
@@ -57,8 +62,19 @@ export function removeTicketWorktree(projectDir, worktreePath) {
 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;
+export function hasTrackerChanges(worktreePath, paths = {}) {
+    const progressDoc = normalizeRepoPath(paths.progressDoc ?? "docs/ticket-progress.md");
+    const archiveDoc = normalizeRepoPath(paths.archiveDoc ?? "docs/ticket-archive.md");
+    const pathspecs = [
+        ".tickets",
+        progressDoc,
+        `${progressDoc}.tmp`,
+        archiveDoc,
+        `${archiveDoc}.tmp`,
+        "docs/ticket-progress.md",
+        "ticket-progress.md",
+    ];
+    const status = runGit(worktreePath, ["status", "--porcelain", "--", ...unique(pathspecs)]).stdout;
     return status.trim().length > 0;
 }
 export function hasWorktreeChanges(worktreePath) {
@@ -92,3 +108,6 @@ function normalizeRepoPath(path) {
         .replace(/\/+/g, "/")
         .replace(/\/$/, "");
 }
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/branch/runner.d.ts

@@ -16,6 +16,10 @@ export interface BranchRunnerOptions {
     prReady: boolean;
     keepWorktrees: boolean;
     allowedBaseDirtyPaths?: string[];
+    trackerPaths?: {
+        progressDoc: string;
+        archiveDoc: string;
+    };
     resumeSessions?: Map<string, {
         worktreePath: string;
         sessionId: string;
@@ -24,5 +28,11 @@ export interface BranchRunnerOptions {
     observeBuilder?: (builder: BuilderAdapter) => Promise<void>;
 }
 export declare function runBranchPlan(opts: BranchRunnerOptions): Promise<BranchRunSummary[]>;
-export declare function buildBranchTicketInstruction(node: BranchPlanNode): string;
-export declare function buildBranchTicketResumeInstruction(node: BranchPlanNode): string;
+export declare function buildBranchTicketInstruction(node: BranchPlanNode, trackerPaths?: {
+    progressDoc?: string;
+    archiveDoc?: string;
+}): string;
+export declare function buildBranchTicketResumeInstruction(node: BranchPlanNode, trackerPaths?: {
+    progressDoc?: string;
+    archiveDoc?: string;
+}): string;

package/dist/branch/runner.js

@@ -86,7 +86,7 @@ export async function runBranchPlan(opts) {
             builder = await opts.createBuilder(worktreePath, resumeSession?.sessionId);
             viewer = opts.observeBuilder?.(builder);
             const foreman = new Foreman(builder, opts.log, opts.notificationsEnabled, opts.qaEnabled, 3, undefined);
-            const { result, status } = await foreman.runInstruction(resumeSession ? buildBranchTicketResumeInstruction(node) : buildBranchTicketInstruction(node));
+            const { result, status } = await foreman.runInstruction(resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths));
             const sessionId = builder.sessionId();
             if (sessionId) {
                 opts.log.write("branch-session", {
@@ -150,7 +150,7 @@ export async function runBranchPlan(opts) {
             if (currentBranch !== node.branch) {
                 throw new Error(`builder switched branch from ${node.branch} to ${currentBranch}`);
             }
-            if (hasTrackerChanges(worktreePath)) {
+            if (hasTrackerChanges(worktreePath, opts.trackerPaths)) {
                 throw new Error("builder modified tracker/control files in ticket worktree");
             }
             let commit;
@@ -286,7 +286,8 @@ function failureLogFields(node, pr) {
         output: pr.output,
     };
 }
-export function buildBranchTicketInstruction(node) {
+export function buildBranchTicketInstruction(node, trackerPaths = {}) {
+    const progressDoc = trackerPaths.progressDoc ?? "docs/ticket-progress.md";
     return `Implement exactly this ticket in the current branch/worktree:
 
 ${node.ticket.id}: ${node.ticket.title}
@@ -307,7 +308,7 @@ Branch-mode rules:
 - Implement only ${node.ticket.id}.
 - Do not switch branches.
 - Do not push, create PRs, or run git commit.
-- Do not edit .tickets/, docs/ticket-progress.md, or other tracker state.
+- Do not edit .tickets/, ${progressDoc}, or other tracker state.
 - If another selected ticket is required before this one can be completed, stop and end with STEP_STATUS: blocked | ticket="${node.ticket.id}" branch_dependency="<ticket-id>" reason="<why>".
 - End with STEP_STATUS: done | ticket="${node.ticket.id}" summary="<what changed>" when the ticket is implemented.
 
@@ -315,7 +316,8 @@ QA will happen in this same builder session after implementation.
 
 ${MARKER_SPEC}`;
 }
-export function buildBranchTicketResumeInstruction(node) {
+export function buildBranchTicketResumeInstruction(node, trackerPaths = {}) {
+    const progressDoc = trackerPaths.progressDoc ?? "docs/ticket-progress.md";
     return `Continue the existing builder session for this ticket in the current branch/worktree:
 
 ${node.ticket.id}: ${node.ticket.title}
@@ -326,7 +328,7 @@ Branch-mode rules:
 - Implement only ${node.ticket.id}.
 - Do not switch branches.
 - Do not push, create PRs, or run git commit.
-- Do not edit .tickets/, docs/ticket-progress.md, or other tracker state.
+- Do not edit .tickets/, ${progressDoc}, or other tracker state.
 - If another selected ticket is required before this one can be completed, stop and end with STEP_STATUS: blocked | ticket="${node.ticket.id}" branch_dependency="<ticket-id>" reason="<why>".
 - End with STEP_STATUS: done | ticket="${node.ticket.id}" summary="<what changed>" when the ticket is implemented.
 

package/dist/cli/runtimeAuthPrompt.d.ts

@@ -1,2 +1,21 @@
-import { type AgentRuntime } from "../runtimeAuth.js";
-export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, label: string): Promise<void>;
+import { RuntimeAuthError, type AgentRuntime } from "../runtimeAuth.js";
+export type RuntimeCommandRecoveryChoice = "retry" | "switch" | "cancel";
+export interface RuntimeCommandRecoveryContext {
+    otherRuntime: AgentRuntime;
+    allowSwitch: boolean;
+}
+export interface RuntimeReadyForCommandOptions {
+    label: string;
+    yes?: boolean;
+    allowSwitch?: boolean;
+    model?: string | undefined;
+    check?: (projectDir: string, runtime: AgentRuntime) => void;
+    checkClaudeSdk?: () => Promise<void>;
+    choose?: (err: RuntimeAuthError, context: RuntimeCommandRecoveryContext) => Promise<RuntimeCommandRecoveryChoice>;
+}
+export interface RuntimeReadyForCommandResult {
+    runtime: AgentRuntime;
+    model?: string;
+    fellBack: boolean;
+}
+export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, labelOrOptions: string | RuntimeReadyForCommandOptions): Promise<RuntimeReadyForCommandResult>;

package/dist/cli/runtimeAuthPrompt.js

@@ -1,27 +1,79 @@
 import { select, isCancel, log } from "@clack/prompts";
+import { requireClaudeSDK } from "../adapters/claude.js";
 import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../runtimeAuth.js";
-export async function ensureRuntimeReadyForCommand(projectDir, runtime, label) {
+import { otherRuntime, runtimeDisplayName } from "./runtimeSelection.js";
+export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrOptions) {
+    const opts = typeof labelOrOptions === "string"
+        ? { label: labelOrOptions }
+        : labelOrOptions;
+    const check = opts.check ?? checkRuntimeReady;
+    const checkClaudeSdk = opts.checkClaudeSdk ?? requireClaudeSDK;
+    const allowSwitch = opts.allowSwitch !== false;
+    const nonInteractive = !opts.choose && (Boolean(opts.yes) || !process.stdin.isTTY || !process.stdout.isTTY);
     while (true) {
         try {
-            checkRuntimeReady(projectDir, runtime);
-            return;
+            check(projectDir, runtime);
+            return { runtime, model: opts.model, fellBack: false };
         }
         catch (err) {
             const failure = err instanceof RuntimeAuthError
                 ? err
-                : new RuntimeAuthError({ runtime, context: label, cause: err });
-            log.error(failure.message);
-            const choice = await select({
-                message: `${runtimeCommandLabel(runtime)} is not ready for ${label}. Fix authentication, then retry the check.`,
-                options: [
-                    { value: "retry", label: "Retry check" },
-                    { value: "cancel", label: "Cancel" },
-                ],
-            });
-            if (isCancel(choice) || choice === "cancel") {
+                : new RuntimeAuthError({ runtime, context: opts.label, cause: err });
+            if (nonInteractive) {
+                throw failure;
+            }
+            const fallbackRuntime = otherRuntime(runtime);
+            const choice = opts.choose
+                ? await opts.choose(failure, { otherRuntime: fallbackRuntime, allowSwitch })
+                : await promptRuntimeRecovery(failure, opts.label, fallbackRuntime, allowSwitch);
+            if (choice === "retry")
+                continue;
+            if (choice === "switch" && allowSwitch) {
+                try {
+                    check(projectDir, fallbackRuntime);
+                    if (fallbackRuntime === "claude") {
+                        await checkClaudeSdk();
+                    }
+                    if (opts.model) {
+                        console.log(`foreman: ignored --model ${opts.model} after switching to ${fallbackRuntime}; model names are provider-specific.`);
+                    }
+                    console.log(`foreman: using ${runtimeDisplayName(fallbackRuntime)} for this run.`);
+                    return { runtime: fallbackRuntime, model: undefined, fellBack: true };
+                }
+                catch (switchErr) {
+                    const switchFailure = switchErr instanceof RuntimeAuthError
+                        ? switchErr
+                        : new RuntimeAuthError({ runtime: fallbackRuntime, context: opts.label, cause: switchErr });
+                    log.error(`Fallback runtime is not ready:\n${switchFailure.message}`);
+                    continue;
+                }
+            }
+            if (choice === "cancel") {
                 console.log("foreman: cancelled");
                 process.exit(0);
             }
+            throw failure;
         }
     }
 }
+async function promptRuntimeRecovery(err, label, fallbackRuntime, allowSwitch) {
+    log.error(err.message);
+    log.info("Cancel stops this command and keeps project files in place. It does not uninstall packages, delete generated files, or change configuration.");
+    if (!allowSwitch) {
+        log.info("Switching runtimes is disabled while resuming because session IDs are runtime-specific.");
+    }
+    const options = [
+        { value: "retry", label: "Fix manually and retry check" },
+        ...(allowSwitch
+            ? [{ value: "switch", label: `Use ${runtimeDisplayName(fallbackRuntime)} for now` }]
+            : []),
+        { value: "cancel", label: "Cancel - stop here; keep generated files" },
+    ];
+    const choice = await select({
+        message: `${runtimeCommandLabel(err.runtime)} is not ready for ${label}. What should Foreman do?`,
+        options,
+    });
+    if (isCancel(choice))
+        return "cancel";
+    return choice;
+}

package/dist/cli/runtimeSelection.d.ts

@@ -0,0 +1,9 @@
+import type { AgentRuntime } from "../runtimeAuth.js";
+export declare const VALID_AGENTS: readonly ["claude", "codex"];
+export declare function isAgentRuntime(value: string): value is AgentRuntime;
+export declare function validateAgentRuntime(value: string): AgentRuntime;
+export declare function otherRuntime(runtime: AgentRuntime): AgentRuntime;
+export declare function runtimeDisplayName(runtime: AgentRuntime): string;
+export declare function defaultAgentForProject(projectDir: string): AgentRuntime;
+export declare function resolveAgentForProject(projectDir: string, explicitAgent?: string): AgentRuntime;
+export declare function readRafiRuntimeTargets(projectDir: string): AgentRuntime[] | undefined;

package/dist/cli/runtimeSelection.js

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const VALID_AGENTS = ["claude", "codex"];
+export function isAgentRuntime(value) {
+    return VALID_AGENTS.includes(value);
+}
+export function validateAgentRuntime(value) {
+    if (isAgentRuntime(value))
+        return value;
+    throw new Error(`unknown agent "${value}" - choose: ${VALID_AGENTS.join(" | ")}`);
+}
+export function otherRuntime(runtime) {
+    return runtime === "claude" ? "codex" : "claude";
+}
+export function runtimeDisplayName(runtime) {
+    return runtime === "claude" ? "Claude" : "Codex";
+}
+export function defaultAgentForProject(projectDir) {
+    const targets = readRafiRuntimeTargets(projectDir);
+    return targets?.length === 1 ? targets[0] : "claude";
+}
+export function resolveAgentForProject(projectDir, explicitAgent) {
+    if (explicitAgent !== undefined)
+        return validateAgentRuntime(explicitAgent);
+    return defaultAgentForProject(projectDir);
+}
+export function readRafiRuntimeTargets(projectDir) {
+    const configPath = join(projectDir, "rafi-config.yaml");
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const raw = parseYaml(readFileSync(configPath, "utf8"));
+        const targets = raw?.harness?.targets;
+        if (!Array.isArray(targets))
+            return undefined;
+        const out = [];
+        for (const target of targets) {
+            if ((target === "claude" || target === "codex") && !out.includes(target)) {
+                out.push(target);
+            }
+        }
+        return out.length > 0 ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli/start.js

@@ -11,6 +11,7 @@ import { Foreman, createPermissionHandler } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { loadRoleBundle } from "../roles.js";
 import { ensureRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
+import { resolveAgentForProject } from "./runtimeSelection.js";
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../tickets/config.js";
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
@@ -43,6 +44,9 @@ function findLastSessionId(dir) {
 function collectTicket(value, previous) {
     return [...previous, value];
 }
+function unique(values) {
+    return [...new Set(values)];
+}
 function branchContinueTicketHelp(cwd, flag = "--continue") {
     const sessions = findResumableBranchSessions(join(cwd, ".foreman"));
     if (sessions.length === 0) {
@@ -94,7 +98,7 @@ export function buildStartCommand() {
         .description("Enlist a builder and drive it through a batch of N steps.")
         .argument("<project>", "path to the project directory the builder works in")
         .requiredOption("-s, --steps <n>", "number of steps to drive")
-        .option("-a, --agent <agent>", "builder agent (claude | codex)", "claude")
+        .option("-a, --agent <agent>", "builder agent (claude | codex)")
         .option("-m, --model <model>", "override the builder's model")
         .option("-r, --resume <sessionId>", "resume a prior builder session")
         .option("--continue", "resume the most recent logged session for this project")
@@ -116,10 +120,6 @@ export function buildStartCommand() {
         if (!Number.isInteger(steps) || steps < 1) {
             fail("--steps must be a positive integer");
         }
-        const VALID_AGENTS = ["claude", "codex"];
-        if (!VALID_AGENTS.includes(opts.agent)) {
-            fail(`unknown agent "${opts.agent}" — choose: ${VALID_AGENTS.join(" | ")}`);
-        }
         const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
         if (opts.effort && !VALID_EFFORT.includes(opts.effort)) {
             fail(`unknown effort "${opts.effort}" — choose: ${VALID_EFFORT.join(" | ")}`);
@@ -127,7 +127,22 @@ export function buildStartCommand() {
         const cwd = resolve(project);
         if (!existsSync(cwd))
             fail(`project directory not found: ${cwd}`);
-        const TRACKER_SEARCH_PATHS = ["docs/ticket-progress.md", "ticket-progress.md"];
+        let agent;
+        try {
+            agent = resolveAgentForProject(cwd, opts.agent);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+        let model = opts.model;
+        const configuredTrackerPath = isTicketsInitialized(cwd)
+            ? loadTicketsConfig(cwd).paths.progressDoc
+            : undefined;
+        const TRACKER_SEARCH_PATHS = unique([
+            configuredTrackerPath,
+            "docs/ticket-progress.md",
+            "ticket-progress.md",
+        ].filter(Boolean));
         let ticketsContent;
         let trackerRelPath;
         if (opts.tickets) {
@@ -183,14 +198,13 @@ export function buildStartCommand() {
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
         const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
         const log = new Log(logPath);
-        const agent = opts.agent;
         const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
         const createBuilder = async (builderCwd, sessionId) => {
             const builderPolicy = new PermissionPolicy(config.permissions, builderCwd);
             const roleBundle = loadRoleBundle("builder", { projectDir: builderCwd });
             const adapterOpts = {
                 cwd: builderCwd,
-                model: opts.model,
+                model,
                 resumeSessionId: sessionId,
                 permission: createPermissionHandler(builderPolicy, log),
                 effort: opts.effort,
@@ -214,7 +228,14 @@ export function buildStartCommand() {
             if (opts.createPr) {
                 await ensureGitHubReadyForCreatePr(cwd, log, Boolean(opts.yes));
             }
-            await ensureRuntimeReadyForCommand(cwd, agent, "start");
+            const ready = await ensureRuntimeReadyForCommand(cwd, agent, {
+                label: "start",
+                yes: Boolean(opts.yes),
+                allowSwitch: !(opts.resume || opts.continue),
+                model,
+            });
+            agent = ready.runtime;
+            model = ready.model;
             const ticketPaths = resolveTicketPaths(ticketsConfig, cwd);
             const tickets = loadTickets(ticketPaths.tickets);
             const db = new StateDb(ticketPaths.stateDb);
@@ -327,7 +348,7 @@ export function buildStartCommand() {
                 plan,
                 log,
                 agent,
-                model: opts.model,
+                model,
                 effort: opts.effort,
                 fast: opts.fast,
                 notificationsEnabled: config.notifications.enabled,
@@ -336,6 +357,10 @@ export function buildStartCommand() {
                 prReady: Boolean(opts.prReady),
                 keepWorktrees: Boolean(opts.keepWorktrees),
                 allowedBaseDirtyPaths,
+                trackerPaths: {
+                    progressDoc: ticketsConfig.paths.progressDoc,
+                    archiveDoc: ticketsConfig.paths.archiveDoc,
+                },
                 resumeSessions: resumeSessionByTicket,
                 createBuilder: (builderCwd, sessionId) => createBuilder(builderCwd, sessionId),
                 observeBuilder: (builder) => printEvents(builder.events()),
@@ -364,11 +389,18 @@ export function buildStartCommand() {
             const failed = summaries.some((row) => row.buildStatus === "blocked" || row.buildStatus === "needs-human");
             process.exit(failed ? 2 : 0);
         }
-        await ensureRuntimeReadyForCommand(cwd, agent, "start");
+        const ready = await ensureRuntimeReadyForCommand(cwd, agent, {
+            label: "start",
+            yes: Boolean(opts.yes),
+            allowSwitch: !(opts.resume || opts.continue),
+            model,
+        });
+        agent = ready.runtime;
+        model = ready.model;
         const builder = await createBuilder(cwd, resumeSessionId);
         const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd);
         const modifiers = [
-            opts.model ? `model=${opts.model}` : null,
+            model ? `model=${model}` : null,
             opts.effort ? `effort=${opts.effort}` : null,
             opts.fast ? "fast" : null,
             qaEnabled ? null : "qa=off",

package/dist/cli/tickets.d.ts

@@ -1,3 +1,3 @@
 import { Command } from "commander";
-export declare function buildPopulateInstruction(sourceHints?: string[]): string;
+export declare function buildPopulateInstruction(sourceHints?: string[], progressDoc?: string): string;
 export declare function buildTicketsCommand(): Command;

package/dist/cli/tickets.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { select, isCancel } from "@clack/prompts";
 import { loadConfig } from "../config.js";
 import { Log } from "../log.js";
@@ -10,10 +10,11 @@ import { CodexAdapter } from "../adapters/codex.js";
 import { Foreman, createPermissionHandler } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { cmdInit, cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdCancel, cmdDiscover, cmdAcceptFutureWork, cmdReorder, cmdRender, cmdValidate, cmdQueue, cmdArchive, } from "../tickets/commands.js";
-import { isTicketsInitialized } from "../tickets/config.js";
+import { isTicketsInitialized, loadTicketsConfig } from "../tickets/config.js";
 import { importFromMarkdown } from "../tickets/importer.js";
 import { formatValidationIssues } from "../tickets/validate.js";
 import { ensureRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
+import { resolveAgentForProject } from "./runtimeSelection.js";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
@@ -21,13 +22,7 @@ function fail(msg) {
 function cwd(opts) {
     return resolve(opts.project ?? ".");
 }
-const VALID_AGENTS = ["claude", "codex"];
 const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
-function validateAgent(agent) {
-    if (!VALID_AGENTS.includes(agent)) {
-        fail(`unknown agent "${agent}" — choose: ${VALID_AGENTS.join(" | ")}`);
-    }
-}
 function validateEffort(effort) {
     if (effort && !VALID_EFFORT.includes(effort)) {
         fail(`unknown effort "${effort}" — choose: ${VALID_EFFORT.join(" | ")}`);
@@ -37,7 +32,7 @@ function makeLogPath(projectDir, label) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     return join(projectDir, ".foreman", `${stamp}-${label}.jsonl`);
 }
-export function buildPopulateInstruction(sourceHints) {
+export function buildPopulateInstruction(sourceHints, progressDoc = "docs/ticket-progress.md") {
     const sources = sourceHints ?? [];
     const sourceHintBlock = sources.length > 0
         ? `
@@ -60,7 +55,7 @@ Before editing, read these tracker control files:
 - .tickets/config.yaml
 - .tickets/tickets.yaml
 - .tickets/tracker-rules.md
-- docs/ticket-progress.md if it exists
+- ${progressDoc} if it exists
 
 Then inspect the repository for existing planning sources. Check root and docs-style Markdown/YAML/TXT files whose names suggest tickets, backlog, roadmap, plan, TODOs, milestones, progress, specs, phases, or implementation steps. Preserve every ticket or task you find. Do not leave out details.
 
@@ -96,6 +91,7 @@ export function buildTicketsCommand() {
         .option("--app-name <name>", "application name")
         .option("--timezone <tz>", "IANA timezone (e.g. America/Chicago)", "UTC")
         .option("--queue-limit <n>", "next-queue window size", "50")
+        .option("--docs-root <dir>", "repo-relative directory for generated ticket docs")
         .action((opts) => {
         const dir = cwd(opts);
         try {
@@ -103,6 +99,7 @@ export function buildTicketsCommand() {
                 appName: opts.appName,
                 timezone: opts.timezone,
                 queueLimit: Number(opts.queueLimit),
+                docsRoot: opts.docsRoot,
             });
             console.log(`foreman tickets: initialized .tickets/ in ${dir}`);
             console.log(`foreman tickets: next — add tickets to .tickets/tickets.yaml and run \`foreman tickets render\``);
@@ -116,7 +113,7 @@ export function buildTicketsCommand() {
         .command("populate")
         .description("Ask a builder to populate .tickets/tickets.yaml from existing project ticket/backlog docs.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
-        .option("-a, --agent <agent>", "builder agent (claude | codex)", "claude")
+        .option("-a, --agent <agent>", "builder agent (claude | codex)")
         .option("-m, --model <model>", "override the builder's model")
         .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
         .option("--sources <paths...>", "source hint files, folders, or globs to check first")
@@ -124,11 +121,17 @@ export function buildTicketsCommand() {
         .option("-y, --yes", "skip confirmation prompt before letting the builder edit tickets")
         .action(async (opts) => {
         const dir = cwd(opts);
-        const agent = opts.agent;
-        validateAgent(agent);
         validateEffort(opts.effort);
         if (!existsSync(dir))
             fail(`project directory not found: ${dir}`);
+        let agent;
+        try {
+            agent = resolveAgentForProject(dir, opts.agent);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+        let model = opts.model;
         if (!isTicketsInitialized(dir)) {
             fail(`ticket tracker is not initialized in ${dir}; run \`foreman tickets init --project ${dir}\` first`);
         }
@@ -149,10 +152,16 @@ export function buildTicketsCommand() {
         const logPath = makeLogPath(dir, "tickets-populate");
         const log = new Log(logPath);
         const policy = new PermissionPolicy(config.permissions, dir);
-        await ensureRuntimeReadyForCommand(dir, agent, "tickets populate");
+        const ready = await ensureRuntimeReadyForCommand(dir, agent, {
+            label: "tickets populate",
+            yes: Boolean(opts.yes),
+            model,
+        });
+        agent = ready.runtime;
+        model = ready.model;
         const adapterOpts = {
             cwd: dir,
-            model: opts.model,
+            model,
             permission: createPermissionHandler(policy, log),
             effort: opts.effort,
             fast: opts.fast,
@@ -166,7 +175,8 @@ export function buildTicketsCommand() {
         console.log(`foreman tickets: project ${dir}`);
         console.log(`foreman tickets: log ${logPath}\n`);
         try {
-            const turn = await foreman.runInstruction(buildPopulateInstruction(opts.sources));
+            const ticketsConfig = loadTicketsConfig(dir);
+            const turn = await foreman.runInstruction(buildPopulateInstruction(opts.sources, ticketsConfig.paths.progressDoc));
             await builder.close();
             await viewer;
             log.write("ticket-populate", {
@@ -198,7 +208,7 @@ export function buildTicketsCommand() {
             else {
                 console.log("foreman tickets: validation passed — all 4 passes clean");
             }
-            console.log("foreman tickets: populated .tickets/tickets.yaml and rendered docs/ticket-progress.md");
+            console.log(`foreman tickets: populated .tickets/tickets.yaml and rendered ${ticketsConfig.paths.progressDoc}`);
         }
         catch (err) {
             await builder.close().catch(() => { });
@@ -406,12 +416,13 @@ export function buildTicketsCommand() {
     // ── render ───────────────────────────────────────────────────────────────────
     tickets
         .command("render")
-        .description("Regenerate docs/ticket-progress.md from current structured sources.")
+        .description("Regenerate the configured ticket progress doc from current structured sources.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .action((opts) => {
         try {
+            const ticketsConfig = loadTicketsConfig(cwd(opts));
             cmdRender(cwd(opts));
-            console.log("foreman tickets: rendered docs/ticket-progress.md");
+            console.log(`foreman tickets: rendered ${ticketsConfig.paths.progressDoc}`);
         }
         catch (err) {
             fail(String(err instanceof Error ? err.message : err));
@@ -464,7 +475,7 @@ export function buildTicketsCommand() {
     // ── archive ───────────────────────────────────────────────────────────────────
     tickets
         .command("archive")
-        .description("Update docs/ticket-archive.md and prune old completed rows.")
+        .description("Update the configured ticket archive doc and prune old completed rows.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--older-than-days <n>", "only archive tickets completed more than N days ago")
         .action((opts) => {
@@ -483,10 +494,13 @@ export function buildTicketsCommand() {
         .command("import")
         .description("(stub) Migrate an existing Markdown tracker.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
-        .option("--progress <path>", "path to existing docs/ticket-progress.md")
+        .option("--progress <path>", "path to existing ticket progress Markdown")
         .action((opts) => {
         try {
-            importFromMarkdown(opts.progress ?? "docs/ticket-progress.md");
+            const dir = cwd(opts);
+            const configuredProgress = opts.progress ?? loadTicketsConfig(dir).paths.progressDoc;
+            const progress = isAbsolute(configuredProgress) ? configuredProgress : join(dir, configuredProgress);
+            importFromMarkdown(progress);
         }
         catch (err) {
             console.error(String(err instanceof Error ? err.message : err));

package/dist/foreman.js

@@ -104,7 +104,8 @@ export { QA_MARKER_SPEC } from "./markers.js";
 export function buildPrimer(n, trackerPath, ticketsEnabled = false) {
     let trackerRule;
     if (ticketsEnabled) {
-        trackerRule = `\n- Ticket state is managed by foreman — you do NOT need to manually edit docs/ticket-progress.md.` +
+        const progressDoc = trackerPath ?? "docs/ticket-progress.md";
+        trackerRule = `\n- Ticket state is managed by foreman — you do NOT need to manually edit ${progressDoc}.` +
             `\n- Use \`foreman tickets discover --summary "..." --rationale "..."\` to log newly discovered work.` +
             `\n- Use \`foreman tickets update <id> --next-action "..."\` to record mid-turn notes.` +
             `\n- Always include ticket="<id>" in your STEP_STATUS marker so foreman can update the tracker.`;

package/dist/tickets/commands.d.ts

@@ -15,6 +15,7 @@ export interface InitOptions {
     appName?: string;
     timezone?: string;
     queueLimit?: number;
+    docsRoot?: string;
 }
 export declare function cmdInit(projectDir: string, opts: InitOptions): void;
 export interface UpdateOptions {

package/dist/tickets/commands.js

@@ -1,11 +1,11 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { stringify } from "yaml";
-import { loadTicketsConfig, resolveTicketPaths, isTicketsInitialized } from "./config.js";
+import { initDocsRoot, loadTicketsConfig, pathExistsOrSymlink, resolveTicketPaths, isTicketsInitialized, } from "./config.js";
 import { loadTickets, saveTickets } from "./ticketLoader.js";
 import { StateDb } from "./stateDb.js";
 import { nowTimestamp, logEvent } from "./events.js";
-import { renderAndWrite, DEFAULT_TRACKER_RULES } from "./renderMarkdown.js";
+import { renderAndWrite, renderTrackerRules } from "./renderMarkdown.js";
 import { runAllValidation } from "./validate.js";
 import { buildNextQueue } from "./queue.js";
 export function openContext(projectDir) {
@@ -33,10 +33,17 @@ export function cmdInit(projectDir, opts) {
         throw new Error(".tickets/config.yaml already exists — already initialized.");
     }
     const ticketsDir = join(projectDir, ".tickets");
+    const docsRoot = initDocsRoot(projectDir, opts.docsRoot);
+    const progressDoc = `${docsRoot}/ticket-progress.md`;
+    const archiveDoc = `${docsRoot}/ticket-archive.md`;
+    if (pathExistsOrSymlink(join(projectDir, progressDoc))) {
+        throw new Error(`${progressDoc} already exists. Choose another docs root with --docs-root <dir> ` +
+            "or move the existing progress doc before initializing tickets.");
+    }
     mkdirSync(join(ticketsDir, "schema"), { recursive: true });
     mkdirSync(join(ticketsDir, "migrations"), { recursive: true });
     mkdirSync(join(ticketsDir, "backups"), { recursive: true });
-    mkdirSync(join(projectDir, "docs"), { recursive: true });
+    mkdirSync(join(projectDir, docsRoot), { recursive: true });
     const config = {
         app_name: opts.appName ?? "My App",
         queue_limit: opts.queueLimit ?? 50,
@@ -46,8 +53,8 @@ export function cmdInit(projectDir, opts) {
             tickets: ".tickets/tickets.yaml",
             state_db: ".tickets/ticket-state.sqlite",
             tracker_rules: ".tickets/tracker-rules.md",
-            progress_doc: "docs/ticket-progress.md",
-            archive_doc: "docs/ticket-archive.md",
+            progress_doc: progressDoc,
+            archive_doc: archiveDoc,
         },
         rendering: {
             preserve_legacy_llm_queue_heading: true,
@@ -67,7 +74,7 @@ export function cmdInit(projectDir, opts) {
     };
     writeFileSync(join(ticketsDir, "config.yaml"), stringify(config, { lineWidth: 80 }), "utf8");
     writeFileSync(join(ticketsDir, "tickets.yaml"), "tickets: []\n", "utf8");
-    writeFileSync(join(ticketsDir, "tracker-rules.md"), DEFAULT_TRACKER_RULES, "utf8");
+    writeFileSync(join(ticketsDir, "tracker-rules.md"), renderTrackerRules(progressDoc), "utf8");
     const ticketSchema = {
         $schema: "http://json-schema.org/draft-07/schema#",
         title: "Ticket",

package/dist/tickets/config.d.ts

@@ -29,6 +29,10 @@ export interface TicketsConfig {
     behavior: TicketsBehavior;
 }
 export declare const DEFAULT_TICKETS_CONFIG: TicketsConfig;
+export declare const DEFAULT_DOCS_ROOT = "docs";
+export declare function normalizeDocsRoot(docsRoot: string): string;
+export declare function validateDocsRoot(projectDir: string, docsRoot: string): string;
+export declare function initDocsRoot(projectDir: string, override?: string): string;
 export declare function loadTicketsConfig(projectDir: string): TicketsConfig;
 export declare function isTicketsInitialized(projectDir: string): boolean;
 export declare function resolveTicketPaths(config: TicketsConfig, projectDir: string): {
@@ -38,3 +42,4 @@ export declare function resolveTicketPaths(config: TicketsConfig, projectDir: st
     progressDoc: string;
     archiveDoc: string;
 };
+export declare function pathExistsOrSymlink(path: string): boolean;

package/dist/tickets/config.js

@@ -1,5 +1,5 @@
-import { readFileSync, existsSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { readFileSync, existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve } from "node:path";
 import { parse } from "yaml";
 export const DEFAULT_TICKETS_CONFIG = {
     appName: "My App",
@@ -28,6 +28,75 @@ export const DEFAULT_TICKETS_CONFIG = {
         backupBeforeImportOrMigration: true,
     },
 };
+export const DEFAULT_DOCS_ROOT = "docs";
+const GLOB_CHARS = /[*?[\]{}]/;
+export function normalizeDocsRoot(docsRoot) {
+    const raw = docsRoot.trim();
+    if (!raw)
+        throw new Error("docs root must be a non-empty repo-relative directory");
+    if (isAbsolute(raw) || /^[A-Za-z]:[\\/]/.test(raw)) {
+        throw new Error(`docs root must be repo-relative: ${docsRoot}`);
+    }
+    if (GLOB_CHARS.test(raw)) {
+        throw new Error(`docs root must be a concrete directory, not a glob: ${docsRoot}`);
+    }
+    const normalized = normalize(raw.replace(/\\/g, "/")).replace(/\\/g, "/").replace(/\/+$/, "");
+    if (!normalized || normalized === "." || normalized === "..") {
+        throw new Error(`docs root must be a named repo-relative directory: ${docsRoot}`);
+    }
+    if (normalized.split("/").includes("..")) {
+        throw new Error(`docs root must not contain parent-directory traversal: ${docsRoot}`);
+    }
+    return normalized.replace(/^\.\/+/, "");
+}
+export function validateDocsRoot(projectDir, docsRoot) {
+    const normalized = normalizeDocsRoot(docsRoot);
+    const repoRoot = resolve(projectDir);
+    const repoRootReal = realOrResolved(repoRoot);
+    const rootPath = resolve(repoRoot, normalized);
+    const rel = relative(repoRoot, rootPath);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`docs root must stay inside the repository: ${docsRoot}`);
+    }
+    if (pathExistsOrSymlink(rootPath)) {
+        let realRoot;
+        try {
+            realRoot = realpathSync(rootPath);
+        }
+        catch {
+            throw new Error(`docs root resolves to a non-directory: ${normalized}`);
+        }
+        assertInsideRepo(repoRootReal, realRoot, docsRoot);
+        let stat;
+        try {
+            stat = statSync(rootPath);
+        }
+        catch {
+            throw new Error(`docs root resolves to a non-directory: ${normalized}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`docs root resolves to a non-directory: ${normalized}`);
+        }
+    }
+    else {
+        assertExistingAncestorInsideRepo(repoRoot, repoRootReal, rootPath, docsRoot);
+    }
+    return normalized;
+}
+export function initDocsRoot(projectDir, override) {
+    if (override)
+        return validateDocsRoot(projectDir, override);
+    const configured = readRafiDocsRoot(projectDir);
+    return validateDocsRoot(projectDir, configured ?? DEFAULT_DOCS_ROOT);
+}
+function readRafiDocsRoot(projectDir) {
+    const configPath = join(projectDir, "rafi-config.yaml");
+    if (!existsSync(configPath))
+        return undefined;
+    const raw = parse(readFileSync(configPath, "utf8")) ?? {};
+    const docs = raw.docs;
+    return typeof docs?.root === "string" ? docs.root : undefined;
+}
 function snakeToCamel(s) {
     return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
@@ -131,3 +200,56 @@ export function resolveTicketPaths(config, projectDir) {
         archiveDoc: r(p.archiveDoc),
     };
 }
+export function pathExistsOrSymlink(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function realOrResolved(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function assertExistingAncestorInsideRepo(repoRoot, repoRootReal, rootPath, docsRoot) {
+    let current = dirname(rootPath);
+    while (current !== repoRoot && !pathExistsOrSymlink(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+    if (!pathExistsOrSymlink(current))
+        return;
+    try {
+        const stat = statSync(current);
+        if (!stat.isDirectory()) {
+            throw new Error(`docs root resolves to a non-directory: ${docsRoot}`);
+        }
+    }
+    catch {
+        throw new Error(`docs root resolves to a non-directory: ${docsRoot}`);
+    }
+    if (current === repoRoot)
+        return;
+    let realAncestor;
+    try {
+        realAncestor = realpathSync(current);
+    }
+    catch {
+        throw new Error(`docs root resolves to a non-directory: ${docsRoot}`);
+    }
+    assertInsideRepo(repoRootReal, realAncestor, docsRoot);
+}
+function assertInsideRepo(repoRootReal, candidateReal, docsRoot) {
+    const rel = relative(repoRootReal, candidateReal);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`docs root must stay inside the repository: ${docsRoot}`);
+    }
+}

package/dist/tickets/renderMarkdown.d.ts

@@ -1,7 +1,8 @@
 import type { TicketsConfig } from "./config.js";
 import type { TicketDef } from "./ticketSchema.js";
 import type { StateDb, TicketState } from "./stateDb.js";
-export declare const DEFAULT_TRACKER_RULES = "# Tracker Rules\n\n## Purpose\nThis tracker is the operational build control surface for humans and builder agents.\n\n## First file to read\nRead `docs/ticket-progress.md` first. Do not scan the full backlog to choose work\nunless the queue is empty or the user explicitly asks for broader planning.\n\n## How to choose work\nChoose the first row in `LLM_NEXT_QUEUE` where `Status` is `next` and `Blocked By` is `None`.\n\n## Required queue maintenance rule\nEvery ticket update must regenerate `docs/ticket-progress.md`, including `LLM_NEXT_QUEUE`.\nUse `foreman tickets update <id>` \u2014 never manually edit generated sections.\n\n## Blocked work\nDo not implement blocked rows unless the blocker itself is the approved next work.\n\n## Done policy\nNever mark a ticket `done` without required validation evidence or a documented test exception.\nUse `foreman tickets complete <id> --validation-result passed --evidence \"...\"`.\n\n## New work policy\nNewly discovered work belongs in the Discovered Future Work Inbox.\nUse `foreman tickets discover --summary \"...\" --rationale \"...\"`.\n\n## Generated document policy\nDo not manually edit generated sections of `docs/ticket-progress.md`.\nUse the `foreman tickets` commands instead.\n\n## STEP_STATUS protocol\nWhen Foreman is running this project, include the ticket ID in your done marker:\n  STEP_STATUS: done | ticket=\"T001\" summary=\"implemented the feature\"\nUse `foreman tickets discover` for newly discovered work during a build run.\n";
+export declare function renderTrackerRules(progressDoc?: string): string;
+export declare const DEFAULT_TRACKER_RULES: string;
 export interface RenderInput {
     config: TicketsConfig;
     projectDir: string;

package/dist/tickets/renderMarkdown.js

@@ -17,20 +17,21 @@ function section(marker, content) {
     return `<!-- ${marker}_START -->\n${content}\n<!-- ${marker}_END -->`;
 }
 // ── Default tracker-rules content ─────────────────────────────────────────────
-export const DEFAULT_TRACKER_RULES = `# Tracker Rules
+export function renderTrackerRules(progressDoc = "docs/ticket-progress.md") {
+    return `# Tracker Rules
 
 ## Purpose
 This tracker is the operational build control surface for humans and builder agents.
 
 ## First file to read
-Read \`docs/ticket-progress.md\` first. Do not scan the full backlog to choose work
+Read \`${progressDoc}\` first. Do not scan the full backlog to choose work
 unless the queue is empty or the user explicitly asks for broader planning.
 
 ## How to choose work
 Choose the first row in \`LLM_NEXT_QUEUE\` where \`Status\` is \`next\` and \`Blocked By\` is \`None\`.
 
 ## Required queue maintenance rule
-Every ticket update must regenerate \`docs/ticket-progress.md\`, including \`LLM_NEXT_QUEUE\`.
+Every ticket update must regenerate \`${progressDoc}\`, including \`LLM_NEXT_QUEUE\`.
 Use \`foreman tickets update <id>\` — never manually edit generated sections.
 
 ## Blocked work
@@ -45,7 +46,7 @@ Newly discovered work belongs in the Discovered Future Work Inbox.
 Use \`foreman tickets discover --summary "..." --rationale "..."\`.
 
 ## Generated document policy
-Do not manually edit generated sections of \`docs/ticket-progress.md\`.
+Do not manually edit generated sections of \`${progressDoc}\`.
 Use the \`foreman tickets\` commands instead.
 
 ## STEP_STATUS protocol
@@ -53,6 +54,8 @@ When Foreman is running this project, include the ticket ID in your done marker:
   STEP_STATUS: done | ticket="T001" summary="implemented the feature"
 Use \`foreman tickets discover\` for newly discovered work during a build run.
 `;
+}
+export const DEFAULT_TRACKER_RULES = renderTrackerRules();
 export function renderProgressDoc(input) {
     const { config, projectDir, ticketDefs, states, db } = input;
     const now = input.now ?? DateTime.now().setZone(config.timezone).toISO();
@@ -66,7 +69,7 @@ export function renderProgressDoc(input) {
     const rulesPath = join(projectDir, config.paths.trackerRules);
     const rulesContent = existsSync(rulesPath)
         ? readFileSync(rulesPath, "utf8").trim()
-        : DEFAULT_TRACKER_RULES.trim();
+        : renderTrackerRules(config.paths.progressDoc).trim();
     const lines = [];
     // Header
     lines.push("# Ticket Progress Tracker");

package/dist/tickets/validate.js

@@ -46,7 +46,7 @@ export function runAllValidation(config, projectDir, ticketDefs, states, db) {
     // Pass 4: generated Markdown doc
     const progressDocPath = join(projectDir, config.paths.progressDoc);
     if (!existsSync(progressDocPath)) {
-        issues.push({ pass: 4, severity: "error", message: "[doc] docs/ticket-progress.md does not exist; run `foreman tickets render`" });
+        issues.push({ pass: 4, severity: "error", message: `[doc] ${config.paths.progressDoc} does not exist; run \`foreman tickets render\`` });
     }
     else {
         const doc = readFileSync(progressDocPath, "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.0.12",
+  "version": "1.2.0",
   "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",
@@ -14,7 +14,7 @@
   },
   "homepage": "https://github.com/ttante/rafi/tree/main/packages/ai-foreman#readme",
   "bin": {
-    "ai-foreman": "./dist/index.js"
+    "ai-foreman": "dist/index.js"
   },
   "exports": {
     "./cli/tickets.js": {
@@ -65,7 +65,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.148"
   },
   "dependencies": {
-    "special-agents": "0.3.7",
+    "special-agents": "0.4.0",
     "@clack/prompts": "^1.4.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",