ai-foreman 1.0.0

package/dist/index.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { resolve, join, relative } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { select, text, isCancel } from "@clack/prompts";
+import { loadConfig } from "./config.js";
+import { Log } from "./log.js";
+import { PermissionPolicy } from "./permissions/policy.js";
+import { ClaudeAdapter } from "./adapters/claude.js";
+import { CodexAdapter } from "./adapters/codex.js";
+import { Foreman, createPermissionHandler } from "./foreman.js";
+import { buildTicketsCommand } from "./cli/tickets.js";
+import { printEvents } from "./cli/events.js";
+import { isTicketsInitialized } from "./tickets/config.js";
+import { cmdValidate } from "./tickets/commands.js";
+import { loadRoleBundle } from "./roles.js";
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
+const program = new Command();
+program
+    .name("ai-foreman")
+    .description("Keep Codex / Claude Code builders moving through their step list.")
+    .version(PACKAGE_VERSION);
+program.addCommand(buildTicketsCommand());
+program
+    .command("start")
+    .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("-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")
+    .option("-t, --tickets <path>", "path to ticket file (.md, .txt, .yaml, …) — passed to the builder as context")
+    .option("-y, --yes", "skip pre-flight confirmation prompt")
+    .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
+    .option("--fast", "fast mode — lower latency (maps to effort=low for codex)")
+    .option("--no-qa", "disable per-ticket QA review (enabled by default)")
+    .action(async (project, opts) => {
+    const steps = Number.parseInt(opts.steps, 10);
+    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(" | ")}`);
+    }
+    const cwd = resolve(project);
+    if (!existsSync(cwd))
+        fail(`project directory not found: ${cwd}`);
+    // Locate ticket progress tracker: explicit --tickets > auto-detect standard paths
+    const TRACKER_SEARCH_PATHS = ["docs/ticket-progress.md", "ticket-progress.md"];
+    let ticketsContent;
+    let trackerRelPath;
+    if (opts.tickets) {
+        const ticketPath = resolve(opts.tickets);
+        if (!existsSync(ticketPath))
+            fail(`ticket file not found: ${ticketPath}`);
+        ticketsContent = readFileSync(ticketPath, "utf8");
+        trackerRelPath = relative(cwd, ticketPath);
+    }
+    else {
+        for (const rel of TRACKER_SEARCH_PATHS) {
+            const abs = join(cwd, rel);
+            if (existsSync(abs)) {
+                ticketsContent = readFileSync(abs, "utf8");
+                trackerRelPath = rel;
+                break;
+            }
+        }
+    }
+    if (opts.resume && opts.continue) {
+        fail("choose either --resume <sessionId> or --continue, not both");
+    }
+    const resumeSessionId = opts.resume ??
+        (opts.continue ? findLastSessionId(join(cwd, ".foreman")) : undefined);
+    if (opts.continue && !resumeSessionId) {
+        fail(`no previous session id found under ${join(cwd, ".foreman")}`);
+    }
+    const config = loadConfig(join(cwd, "foreman.yaml"));
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
+    const log = new Log(logPath);
+    const policy = new PermissionPolicy(config.permissions, cwd);
+    const roleBundle = loadRoleBundle("builder", { projectDir: cwd });
+    const adapterOpts = {
+        cwd,
+        model: opts.model,
+        resumeSessionId,
+        permission: createPermissionHandler(policy, log),
+        effort: opts.effort,
+        fast: opts.fast,
+        systemPromptAppend: roleBundle.system || undefined,
+        skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
+    };
+    const builder = opts.agent === "codex"
+        ? new CodexAdapter(adapterOpts)
+        : new ClaudeAdapter(adapterOpts);
+    // Commander surfaces --no-qa as opts.qa === false; when --qa/--no-qa is not
+    // passed, opts.qa is undefined and we fall back to the config default.
+    const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
+    const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd);
+    const modifiers = [
+        opts.model ? `model=${opts.model}` : null,
+        opts.effort ? `effort=${opts.effort}` : null,
+        opts.fast ? "fast" : null,
+        qaEnabled ? null : "qa=off",
+    ].filter(Boolean).join(" ");
+    console.log(`foreman: driving a ${opts.agent} builder through ${steps} step(s)${modifiers ? ` [${modifiers}]` : ""}`);
+    console.log(`foreman: project ${cwd}`);
+    if (trackerRelPath)
+        console.log(`foreman: tracker ${trackerRelPath}`);
+    console.log(`foreman: log ${logPath}\n`);
+    const viewer = printEvents(builder.events());
+    try {
+        // Pre-flight: builder lists the next N tickets or steps; user confirms before any step runs
+        console.log("ai-foreman: asking builder to plan the next tickets or steps...\n");
+        await foreman.runPreflight(steps, ticketsContent);
+        if (!opts.yes) {
+            while (true) {
+                console.log();
+                const action = await select({
+                    message: "How does this plan look?",
+                    options: [
+                        { value: "proceed", label: "Proceed — start implementing" },
+                        { value: "feedback", label: "Give feedback — revise the plan" },
+                        { value: "cancel", label: "Cancel" },
+                    ],
+                });
+                if (isCancel(action) || action === "cancel") {
+                    console.log("ai-foreman: cancelled");
+                    await builder.close();
+                    await viewer;
+                    process.exit(0);
+                }
+                if (action === "proceed") {
+                    console.log();
+                    break;
+                }
+                const fb = await text({
+                    message: "Your feedback:",
+                    validate: (v) => (v?.trim() ? undefined : "Please enter some feedback"),
+                });
+                if (isCancel(fb)) {
+                    console.log("ai-foreman: cancelled");
+                    await builder.close();
+                    await viewer;
+                    process.exit(0);
+                }
+                console.log();
+                await foreman.sendPreflightFeedback(String(fb));
+            }
+        }
+        const result = await foreman.runBatch(steps, trackerRelPath);
+        await builder.close();
+        await viewer;
+        console.log(`\nforeman: ${result.completed}/${result.requested} step(s) completed`);
+        console.log(`foreman: outcome — ${result.outcome}`);
+        if (result.detail)
+            console.log(`foreman: ${result.detail}`);
+        const sid = builder.sessionId();
+        if (sid)
+            console.log(`foreman: resume this builder with  --resume ${sid}`);
+        process.exit(result.outcome === "needs-human" ? 2 : 0);
+    }
+    catch (err) {
+        await builder.close().catch(() => { });
+        log.write("error", { message: String(err) });
+        fail(`run failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+program
+    .command("status")
+    .description("Summarize the most recent foreman run for a project.")
+    .argument("<project>", "path to the project directory")
+    .action((project) => {
+    const dir = join(resolve(project), ".foreman");
+    if (!existsSync(dir))
+        fail(`no foreman runs found under ${dir}`);
+    const logs = readdirSync(dir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .sort();
+    if (logs.length === 0)
+        fail(`no foreman runs found under ${dir}`);
+    const latest = join(dir, logs[logs.length - 1]);
+    const records = readFileSync(latest, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+    const steps = records.filter((r) => r.event === "step");
+    const escalations = records.filter((r) => r.event === "escalation");
+    const batchEnd = records.reverse().find((r) => r.event === "batch-end");
+    console.log(`foreman: latest run ${logs[logs.length - 1]}`);
+    console.log(`foreman: ${steps.length} step record(s), ${escalations.length} escalation(s)`);
+    if (batchEnd) {
+        console.log(`foreman: outcome — ${batchEnd.outcome} (${batchEnd.completed}/${batchEnd.requested})`);
+        if (batchEnd.detail)
+            console.log(`foreman: ${batchEnd.detail}`);
+    }
+    else {
+        console.log("ai-foreman: run is still in progress or did not finish");
+    }
+    for (const esc of escalations) {
+        console.log(`  escalated: ${esc.tool} — ${esc.reason}`);
+    }
+});
+program
+    .command("doctor")
+    .description("Check Foreman, agent CLIs, config, and optional ticket tracker readiness.")
+    .argument("[project]", "path to the project directory", ".")
+    .action((project) => {
+    const cwd = resolve(project);
+    let errors = 0;
+    const report = (ok, label, detail) => {
+        console.log(`${ok ? "ok" : "!!"} ${label}${detail ? ` — ${detail}` : ""}`);
+        if (!ok)
+            errors++;
+    };
+    const warn = (label, detail) => {
+        console.log(`-- ${label}${detail ? ` — ${detail}` : ""}`);
+    };
+    report(Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10) >= 20, "node >=20", process.version);
+    report(Boolean(PACKAGE_VERSION), "foreman package version", PACKAGE_VERSION);
+    report(existsSync(cwd), "project directory exists", cwd);
+    if (!existsSync(cwd))
+        process.exit(1);
+    try {
+        loadConfig(join(cwd, "foreman.yaml"));
+        report(true, "foreman.yaml", existsSync(join(cwd, "foreman.yaml")) ? "valid" : "not present, using defaults");
+    }
+    catch (err) {
+        report(false, "foreman.yaml", err instanceof Error ? err.message : String(err));
+    }
+    const claude = commandVersion("claude");
+    if (claude.ok)
+        warn("claude CLI found", claude.detail);
+    else
+        warn("claude CLI not found", "Claude adapter may still work through the SDK if credentials are configured");
+    const codex = commandVersion("codex");
+    if (codex.ok)
+        warn("codex CLI found", codex.detail);
+    else
+        warn("codex CLI not found", "required only for --agent codex");
+    if (isTicketsInitialized(cwd)) {
+        try {
+            const result = cmdValidate(cwd);
+            report(result.clean, ".tickets validation", result.clean ? "clean" : `${result.issues.length} issue(s)`);
+        }
+        catch (err) {
+            report(false, ".tickets validation", err instanceof Error ? err.message : String(err));
+        }
+    }
+    else {
+        warn(".tickets", "not initialized; start will run in plain mode");
+    }
+    process.exit(errors === 0 ? 0 : 1);
+});
+// pnpm passes its `--` separator through to the script; strip it so Commander
+// sees the subcommand args correctly.
+const argv = [...process.argv];
+if (argv[2] === "--")
+    argv.splice(2, 1);
+program.parseAsync(argv).catch((err) => fail(String(err)));
+function fail(message) {
+    console.error(`foreman: ${message}`);
+    process.exit(1);
+}
+function commandVersion(command) {
+    const result = spawnSync(command, ["--version"], {
+        encoding: "utf8",
+        timeout: 3000,
+    });
+    if (result.error)
+        return { ok: false, detail: result.error.message };
+    if (result.status !== 0)
+        return { ok: false, detail: result.stderr.trim() };
+    return { ok: true, detail: (result.stdout.trim() || result.stderr.trim()).slice(0, 120) };
+}
+/** Read the most recent batch-end sessionId from the last .foreman log, for auto-resume. */
+function findLastSessionId(dir) {
+    if (!existsSync(dir))
+        return undefined;
+    const logs = readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort();
+    if (logs.length === 0)
+        return undefined;
+    const lines = readFileSync(join(dir, logs[logs.length - 1]), "utf8")
+        .split("\n")
+        .filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const r = JSON.parse(lines[i]);
+        if (r.event === "batch-end" && typeof r.sessionId === "string") {
+            return r.sessionId;
+        }
+    }
+    return undefined;
+}

package/dist/log.js

@@ -0,0 +1,18 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/** Append-only JSONL logger. One line per record, plus an echo to the console. */
+export class Log {
+    path;
+    constructor(path) {
+        this.path = path;
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    write(event, fields) {
+        const record = {
+            ts: new Date().toISOString(),
+            event,
+            ...fields,
+        };
+        appendFileSync(this.path, JSON.stringify(record) + "\n");
+    }
+}

package/dist/markers.js

@@ -0,0 +1,20 @@
+/**
+ * STEP_STATUS protocol strings. Extracted from foreman.ts so tests can import
+ * them without pulling in @clack/prompts (which requires Node >=20 for styleText).
+ */
+export const MARKER_SPEC = `End EVERY turn with exactly one marker line as the LAST line, nothing after it:
+  STEP_STATUS: done | ticket="T001" summary="what you just did" next="the next ticket or step"
+  STEP_STATUS: blocked | ticket="T001" reason="why you cannot proceed"
+  STEP_STATUS: plan_complete | ticket="T001" summary="what you just did"
+  STEP_STATUS: needs_input | question="your question for the user" choices="Option A|Option B|Option C"
+Use "done" after finishing a ticket or step when more remain, "plan_complete" after
+the final ticket or step, "blocked" if you cannot proceed without help, and "needs_input"
+if you need the user to make a decision before continuing.
+Always include ticket="<ticket-id>" in done/blocked/plan_complete markers when working from a ticket queue.
+After "done" or "plan_complete", foreman may run a QA pass on your work — expect a
+follow-up instruction asking you to triple-check accuracy, tests, and ticket satisfaction.`;
+export const QA_MARKER_SPEC = `End EVERY turn with exactly one marker line as the LAST line, nothing after it:
+  STEP_STATUS: qa_pass | summary="confirmed everything checks out"
+  STEP_STATUS: qa_fail | issues="bullet-list of concrete problems found"
+  STEP_STATUS: blocked | reason="why QA itself cannot proceed"
+  STEP_STATUS: needs_input | question="..." choices="..."`;

package/dist/notify.js

@@ -0,0 +1,49 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+function isWSL() {
+    try {
+        return readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft");
+    }
+    catch {
+        return false;
+    }
+}
+/** Strip characters that break notification string literals. */
+function safe(s) {
+    return s.replace(/["\\\n\r]/g, " ").slice(0, 120);
+}
+function xmlEsc(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Fire a non-interactive desktop notification. Always best-effort — if the
+ * platform tool is unavailable the error is silently swallowed.
+ *
+ * macOS  : osascript (built-in)
+ * Linux  : notify-send (libnotify)
+ * WSL    : powershell.exe Windows toast (no extra install required)
+ */
+export function fireNotification(title, body) {
+    try {
+        if (process.platform === "darwin") {
+            spawnSync("osascript", ["-e", `display notification "${safe(body)}" with title "${safe(title)}"`], { timeout: 3000 });
+        }
+        else if (isWSL()) {
+            const xml = `<toast><visual><binding template="ToastGeneric"><text>${xmlEsc(title)}</text><text>${xmlEsc(body)}</text></binding></visual></toast>`;
+            const ps = `$d=New-Object Windows.Data.Xml.Dom.XmlDocument;$d.LoadXml(${JSON.stringify(xml)});$t=New-Object Windows.UI.Notifications.ToastNotification($d);[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Foreman').Show($t)`;
+            spawnSync("powershell.exe", ["-NonInteractive", "-WindowStyle", "Hidden", "-Command", ps], {
+                timeout: 5000,
+            });
+        }
+        else if (process.platform === "linux") {
+            spawnSync("notify-send", [title, body], { timeout: 3000 });
+        }
+    }
+    catch {
+        // best-effort — never crash the run
+    }
+}

package/dist/permissions/policy.js

@@ -0,0 +1,84 @@
+import { resolve, isAbsolute } from "node:path";
+/** Tools that write to disk — allowed only inside the worktree. */
+const FILE_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+/** Shell operators we split on to vet each segment of a chained command. */
+const SHELL_SPLIT = /\s*(?:&&|\|\||;|\|)\s*/;
+/** Shell features that make a prefix allow-list too easy to bypass. */
+const ESCALATE_SHELL_SYNTAX = [
+    { pattern: /\s\d?>|\s>>|\s</, reason: "shell redirection is not auto-approved" },
+    { pattern: /\$\(|`/, reason: "shell substitution is not auto-approved" },
+];
+/**
+ * Rules-based permission classifier. No LLM: routine requests are auto-approved,
+ * anything risky or unrecognized escalates to the human (fail safe).
+ */
+export class PermissionPolicy {
+    config;
+    cwd;
+    constructor(config, cwd) {
+        this.config = config;
+        this.cwd = cwd;
+    }
+    classify(req) {
+        const { toolName, input } = req;
+        if (this.config.escalateTools.includes(toolName)) {
+            return { decision: "escalate", reason: `tool ${toolName} always escalates` };
+        }
+        if (toolName === "Bash") {
+            return this.classifyBash(String(input.command ?? ""));
+        }
+        if (FILE_TOOLS.has(toolName)) {
+            const target = this.filePath(input);
+            if (target && !this.insideCwd(target)) {
+                return {
+                    decision: "escalate",
+                    reason: `writes outside the worktree: ${target}`,
+                };
+            }
+            if (this.config.allowTools.includes(toolName)) {
+                return { decision: "allow", reason: `${toolName} inside the worktree` };
+            }
+        }
+        if (this.config.allowTools.includes(toolName)) {
+            return { decision: "allow", reason: `${toolName} is allow-listed` };
+        }
+        return { decision: "escalate", reason: `tool ${toolName} not recognized` };
+    }
+    classifyBash(command) {
+        // Always-escalate list is checked first against the full command string —
+        // a dangerous pattern anywhere in a chained command escalates the whole call.
+        const hitEscalate = this.config.escalateBash.find((p) => command.includes(p));
+        if (hitEscalate) {
+            return { decision: "escalate", reason: `command matches "${hitEscalate}"` };
+        }
+        const syntax = ESCALATE_SHELL_SYNTAX.find((s) => s.pattern.test(command));
+        if (syntax) {
+            return { decision: "escalate", reason: syntax.reason };
+        }
+        const segments = command.split(SHELL_SPLIT).map((s) => s.trim()).filter(Boolean);
+        if (segments.length === 0) {
+            return { decision: "escalate", reason: "empty bash command" };
+        }
+        for (const segment of segments) {
+            const allow = this.config.allowBash.find((p) => this.matchesAllowedPrefix(segment, p));
+            if (!allow) {
+                return { decision: "escalate", reason: `command segment is not allow-listed: ${segment}` };
+            }
+        }
+        return { decision: "allow", reason: "all command segments are allow-listed" };
+    }
+    matchesAllowedPrefix(command, prefix) {
+        if (prefix.endsWith(" "))
+            return command.startsWith(prefix);
+        return command === prefix || command.startsWith(prefix + " ");
+    }
+    filePath(input) {
+        const p = input.file_path ?? input.path ?? input.notebook_path;
+        return typeof p === "string" ? p : undefined;
+    }
+    insideCwd(target) {
+        const abs = isAbsolute(target) ? target : resolve(this.cwd, target);
+        const root = resolve(this.cwd);
+        return abs === root || abs.startsWith(root + "/");
+    }
+}

package/dist/roles.js

@@ -0,0 +1,49 @@
+/**
+ * 3-tier role bundle loader. Returns the composed system text + metadata for a
+ * given role, trying each tier in order:
+ *
+ *   1. `.rafi/compiled/<role>/` in the target repo — written by `rafi compile`.
+ *   2. Library defaults from `special-agents` — the prebuilt default bundle.
+ *   3. Hardcoded fallback — empty system text, no skills (today's behavior).
+ *
+ * `libraryGetAgent` can be injected for tests; pass `null` to force tier 3.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgent } from "special-agents";
+function libraryGetter(role) {
+    const a = getAgent(role);
+    return { system: a.system, skills: a.skills, model: a.model, effort: a.effort };
+}
+export function loadRoleBundle(role, opts = {}) {
+    // Tier 1: compiled bundle in the target repo
+    if (opts.projectDir) {
+        const base = join(opts.projectDir, ".rafi", "compiled", role);
+        const sysPath = join(base, "system.md");
+        const metaPath = join(base, "meta.json");
+        if (existsSync(sysPath) && existsSync(metaPath)) {
+            const system = readFileSync(sysPath, "utf8");
+            const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+            return {
+                system,
+                skills: meta.skills ?? [],
+                model: meta.model ?? null,
+                effort: meta.effort ?? null,
+                source: "compiled",
+            };
+        }
+    }
+    // Tier 2: library defaults (special-agents)
+    const getter = opts.libraryGetAgent !== undefined ? opts.libraryGetAgent : libraryGetter;
+    if (getter !== null) {
+        try {
+            const b = getter(role);
+            return { ...b, source: "library" };
+        }
+        catch {
+            // fall through to tier 3
+        }
+    }
+    // Tier 3: hardcoded fallback — preserves behavior from before Phase 5
+    return { system: "", skills: [], model: null, effort: null, source: "fallback" };
+}

package/dist/tickets/blockers.js

@@ -0,0 +1,22 @@
+export function resolveBlockers(ticket, states) {
+    const unresolvedDeps = ticket.depends_on.filter((depId) => {
+        const dep = states.get(depId);
+        return dep?.status !== "done";
+    });
+    const state = states.get(ticket.id);
+    const explicitBlockers = state
+        ? JSON.parse(state.blocked_by_json || "[]")
+        : [];
+    return [...new Set([...unresolvedDeps, ...explicitBlockers])];
+}
+export function computeDisplayStatus(storedStatus, blockedBy) {
+    if (storedStatus === "done")
+        return "done";
+    if (storedStatus === "canceled")
+        return "canceled";
+    if (storedStatus === "in_progress")
+        return "in_progress";
+    if (blockedBy.length > 0 || storedStatus === "blocked")
+        return "blocked";
+    return "next";
+}