ai-foreman 1.0.11 → 1.1.0

package/README.md

@@ -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`
 
@@ -124,6 +125,32 @@ 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`
 
 | Option | Common values | Default | Notes |
@@ -223,6 +250,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:
 
@@ -239,6 +269,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:
@@ -267,7 +299,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
@@ -375,7 +407,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.
@@ -541,4 +573,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/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/start.js

@@ -43,6 +43,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) {
@@ -127,7 +130,14 @@ 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"];
+        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) {
@@ -336,6 +346,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()),

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,7 +10,7 @@ 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";
@@ -37,7 +37,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 +60,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 +96,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 +104,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\``);
@@ -166,7 +168,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 +201,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 +409,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 +468,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 +487,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/config.js

@@ -24,6 +24,7 @@ export const DEFAULT_CONFIG = {
             "ls",
             "cat ",
             "mkdir ",
+            "ai-foreman tickets",
             "foreman tickets",
             "pytest",
             "python ",

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/foreman.yaml

@@ -1,6 +1,6 @@
 # Foreman configuration. Any field omitted here falls back to the built-in
 # defaults in src/config.ts. This file is read from the *project* directory
-# passed to `foreman start`, so each project can tune its own policy.
+# passed to `ai-foreman start`, so each project can tune its own policy.
 
 permissions:
   # Bash commands are auto-approved only when EVERY segment (split on && || ; |)
@@ -26,6 +26,8 @@ permissions:
     - ls
     - "cat "
     - "mkdir "
+    - ai-foreman tickets
+    # Legacy-compatible prefix for older generated docs and logs.
     - foreman tickets
     - pytest
     - "python "

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.0.11",
+  "version": "1.1.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",
@@ -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",