ai-foreman 1.0.1 → 1.0.2

package/dist/index.js

@@ -1,20 +1,10 @@
 #!/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 { readFileSync } from "node:fs";
 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";
+import { buildStartCommand } from "./cli/start.js";
+import { buildStatusCommand } from "./cli/status.js";
+import { buildDoctorCommand } from "./cli/doctor.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
 const program = new Command();
 program
@@ -22,279 +12,15 @@ program
     .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)
-        : await ClaudeAdapter.create(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);
-});
+program.addCommand(buildStartCommand());
+program.addCommand(buildStatusCommand());
+program.addCommand(buildDoctorCommand());
 // 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}`);
+program.parseAsync(argv).catch((err) => {
+    console.error(`foreman: ${String(err)}`);
     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.d.ts

@@ -0,0 +1,12 @@
+/** A single structured log record. */
+export interface LogRecord {
+    ts: string;
+    event: "batch-start" | "batch-end" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "ticket-populate" | "qa" | "qa-fix" | "error";
+    [key: string]: unknown;
+}
+/** Append-only JSONL logger. One line per record, plus an echo to the console. */
+export declare class Log {
+    private readonly path;
+    constructor(path: string);
+    write(event: LogRecord["event"], fields: Record<string, unknown>): void;
+}

package/dist/markers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare const MARKER_SPEC = "End EVERY turn with exactly one marker line as the LAST line, nothing after it:\n  STEP_STATUS: done | ticket=\"T001\" summary=\"what you just did\" next=\"the next ticket or step\"\n  STEP_STATUS: blocked | ticket=\"T001\" reason=\"why you cannot proceed\"\n  STEP_STATUS: plan_complete | ticket=\"T001\" summary=\"what you just did\"\n  STEP_STATUS: needs_input | question=\"your question for the user\" choices=\"Option A|Option B|Option C\"\nUse \"done\" after finishing a ticket or step when more remain, \"plan_complete\" after\nthe final ticket or step, \"blocked\" if you cannot proceed without help, and \"needs_input\"\nif you need the user to make a decision before continuing.\nAlways include ticket=\"<ticket-id>\" in done/blocked/plan_complete markers when working from a ticket queue.\nAfter \"done\" or \"plan_complete\", foreman may run a QA pass on your work \u2014 expect a\nfollow-up instruction asking you to triple-check accuracy, tests, and ticket satisfaction.";
+export declare const QA_MARKER_SPEC = "End EVERY turn with exactly one marker line as the LAST line, nothing after it:\n  STEP_STATUS: qa_pass | summary=\"confirmed everything checks out\"\n  STEP_STATUS: qa_fail | issues=\"bullet-list of concrete problems found\"\n  STEP_STATUS: blocked | reason=\"why QA itself cannot proceed\"\n  STEP_STATUS: needs_input | question=\"...\" choices=\"...\"";

package/dist/notify.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function fireNotification(title: string, body: string): void;

package/dist/permissions/policy.d.ts

@@ -0,0 +1,20 @@
+import type { PermissionConfig } from "../config.js";
+import type { PermissionRequest } from "../adapters/types.js";
+export interface Classification {
+    decision: "allow" | "escalate";
+    reason: string;
+}
+/**
+ * Rules-based permission classifier. No LLM: routine requests are auto-approved,
+ * anything risky or unrecognized escalates to the human (fail safe).
+ */
+export declare class PermissionPolicy {
+    private readonly config;
+    private readonly cwd;
+    constructor(config: PermissionConfig, cwd: string);
+    classify(req: PermissionRequest): Classification;
+    private classifyBash;
+    private matchesAllowedPrefix;
+    private filePath;
+    private insideCwd;
+}

package/dist/roles.d.ts

@@ -0,0 +1,24 @@
+export interface RoleBundle {
+    system: string;
+    skills: string[];
+    model: string | null;
+    effort: string | null;
+    /** Which tier provided this bundle. */
+    source: "compiled" | "library" | "fallback";
+}
+export type LibraryGetAgent = (role: string) => {
+    system: string;
+    skills: string[];
+    model: string | null;
+    effort: string | null;
+};
+export interface LoadRoleBundleOpts {
+    /** Target repo root — checked for `.rafi/compiled/<role>/`. */
+    projectDir?: string;
+    /**
+     * Override the library getter. Omit to use the real `special-agents` library.
+     * Pass `null` to simulate the library being absent (forces tier 3).
+     */
+    libraryGetAgent?: LibraryGetAgent | null;
+}
+export declare function loadRoleBundle(role: string, opts?: LoadRoleBundleOpts): RoleBundle;

package/dist/tickets/blockers.d.ts

@@ -0,0 +1,5 @@
+import type { TicketDef } from "./ticketSchema.js";
+import type { TicketState } from "./stateDb.js";
+export declare function resolveBlockers(ticket: TicketDef, states: Map<string, TicketState>): string[];
+export type DisplayStatus = "next" | "in_progress" | "blocked" | "done" | "canceled";
+export declare function computeDisplayStatus(storedStatus: string, blockedBy: string[]): DisplayStatus;

package/dist/tickets/commands.d.ts

@@ -0,0 +1,89 @@
+import type { TicketDef } from "./ticketSchema.js";
+import type { ValidationResult } from "./stateDb.js";
+import { type TicketsConfig, resolveTicketPaths } from "./config.js";
+import { StateDb } from "./stateDb.js";
+import { runAllValidation } from "./validate.js";
+export interface TicketContext {
+    config: TicketsConfig;
+    projectDir: string;
+    paths: ReturnType<typeof resolveTicketPaths>;
+    tickets: TicketDef[];
+    db: StateDb;
+}
+export declare function openContext(projectDir: string): TicketContext;
+export interface InitOptions {
+    appName?: string;
+    timezone?: string;
+    queueLimit?: number;
+}
+export declare function cmdInit(projectDir: string, opts: InitOptions): void;
+export interface UpdateOptions {
+    status?: string;
+    actor?: string;
+    summary?: string;
+    nextAction?: string;
+    currentStep?: string;
+    owner?: string;
+    validationResult?: ValidationResult;
+    validationCommands?: string;
+    validationNotes?: string;
+    evidence?: string;
+    lastError?: string;
+}
+export declare function cmdUpdate(projectDir: string, ticketId: string, opts: UpdateOptions): void;
+export interface CompleteOptions {
+    actor?: string;
+    summary?: string;
+    validationResult?: ValidationResult;
+    validationCommands?: string;
+    evidence?: string;
+    validationNotes?: string;
+}
+export declare function cmdComplete(projectDir: string, ticketId: string, opts: CompleteOptions): void;
+export interface BlockOptions {
+    blockedBy?: string[];
+    blockerType?: string;
+    summary?: string;
+    actor?: string;
+    unblockCriteria?: string;
+}
+export declare function cmdBlock(projectDir: string, ticketId: string, opts: BlockOptions): void;
+export declare function cmdUnblock(projectDir: string, ticketId: string, opts: {
+    summary?: string;
+    actor?: string;
+}): void;
+export declare function cmdCancel(projectDir: string, ticketId: string, opts: {
+    summary: string;
+    actor?: string;
+}): void;
+export interface DiscoverOptions {
+    sourceTicket?: string;
+    proposedTicket?: string;
+    priorityGuess?: string;
+    area?: string;
+    summary: string;
+    rationale?: string;
+    needsDecisionFrom?: string;
+    actor?: string;
+}
+export declare function cmdDiscover(projectDir: string, opts: DiscoverOptions): number;
+export declare function cmdAcceptFutureWork(projectDir: string, futureWorkId: number, opts: {
+    ticketId: string;
+    order: number;
+    actor?: string;
+}): void;
+export declare function cmdReorder(projectDir: string, ticketId: string, opts: {
+    afterTicketId?: string;
+    order?: number;
+    actor?: string;
+}): void;
+export declare function cmdRender(projectDir: string): void;
+export interface ValidateResult {
+    issues: ReturnType<typeof runAllValidation>;
+    clean: boolean;
+}
+export declare function cmdValidate(projectDir: string): ValidateResult;
+export declare function cmdQueue(projectDir: string, limit?: number): import("./queue.js").QueueRow[];
+export declare function cmdArchive(projectDir: string, _opts: {
+    olderThanDays?: number;
+}): void;

package/dist/tickets/config.d.ts

@@ -0,0 +1,40 @@
+export interface TicketsPaths {
+    tickets: string;
+    stateDb: string;
+    trackerRules: string;
+    progressDoc: string;
+    archiveDoc: string;
+}
+export interface TicketsRendering {
+    preserveLegacyLlmQueueHeading: boolean;
+    includeRulesInProgressDoc: boolean;
+    maxWorkLogRows: number;
+    maxValidationSnapshotRows: number;
+    maxRecentCompletedRows: number;
+    generatedDocWarning: boolean;
+}
+export interface TicketsBehavior {
+    regenerateProgressDocAfterEveryUpdate: boolean;
+    requireValidationEvidenceForDone: boolean;
+    blockOnUnresolvedDependencies: boolean;
+    useAtomicFileWrites: boolean;
+    backupBeforeImportOrMigration: boolean;
+}
+export interface TicketsConfig {
+    appName: string;
+    queueLimit: number;
+    timezone: string;
+    paths: TicketsPaths;
+    rendering: TicketsRendering;
+    behavior: TicketsBehavior;
+}
+export declare const DEFAULT_TICKETS_CONFIG: TicketsConfig;
+export declare function loadTicketsConfig(projectDir: string): TicketsConfig;
+export declare function isTicketsInitialized(projectDir: string): boolean;
+export declare function resolveTicketPaths(config: TicketsConfig, projectDir: string): {
+    tickets: string;
+    stateDb: string;
+    trackerRules: string;
+    progressDoc: string;
+    archiveDoc: string;
+};

package/dist/tickets/events.d.ts

@@ -0,0 +1,14 @@
+import type { StateDb } from "./stateDb.js";
+export declare function nowTimestamp(timezone: string): string;
+export declare function logEvent(db: StateDb, opts: {
+    timestamp: string;
+    actor: string | null;
+    ticketId: string | null;
+    eventType: string;
+    oldStatus: string | null;
+    newStatus: string | null;
+    summary: string;
+    validation?: string | null;
+    evidence?: string | null;
+    payload?: Record<string, unknown>;
+}): void;

package/dist/tickets/importer.d.ts

@@ -0,0 +1 @@
+export declare function importFromMarkdown(_progressDocPath: string): never;

package/dist/tickets/queue.d.ts

@@ -0,0 +1,36 @@
+import type { TicketDef } from "./ticketSchema.js";
+import type { TicketState } from "./stateDb.js";
+export interface QueueRow {
+    rank: number;
+    ticket: string;
+    title: string;
+    status: string;
+    priority: string;
+    area: string;
+    dependsOn: string;
+    blockedBy: string;
+    size: string;
+    risk: string;
+    nextAction: string;
+    requiredTests: string;
+    evidence: string;
+    likelyFiles: string;
+}
+export interface ActiveStatusRow {
+    ticket: string;
+    title: string;
+    status: string;
+    priority: string;
+    area: string;
+    owner: string;
+    lastWorkedAt: string;
+    completedAt: string;
+    dependsOn: string;
+    blockers: string;
+    nextAction: string;
+    acceptanceTestGate: string;
+    evidence: string;
+    futureWorkNotes: string;
+}
+export declare function buildNextQueue(ticketDefs: TicketDef[], states: Map<string, TicketState>, queueLimit: number): QueueRow[];
+export declare function buildActiveStatusRows(queueRows: QueueRow[], ticketDefs: TicketDef[], states: Map<string, TicketState>): ActiveStatusRow[];

package/dist/tickets/renderMarkdown.d.ts

@@ -0,0 +1,15 @@
+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 interface RenderInput {
+    config: TicketsConfig;
+    projectDir: string;
+    ticketDefs: TicketDef[];
+    states: Map<string, TicketState>;
+    db: StateDb;
+    now?: string;
+}
+export declare function renderProgressDoc(input: RenderInput): string;
+export declare function writeProgressDoc(progressDocPath: string, content: string, atomic: boolean): void;
+export declare function renderAndWrite(input: RenderInput): void;