ai-foreman 1.0.0

package/dist/tickets/commands.js

@@ -0,0 +1,438 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { loadTicketsConfig, 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 { runAllValidation } from "./validate.js";
+import { buildNextQueue } from "./queue.js";
+export function openContext(projectDir) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    const tickets = loadTickets(paths.tickets);
+    const db = new StateDb(paths.stateDb);
+    return { config, projectDir, paths, tickets, db };
+}
+function withContext(projectDir, fn) {
+    const ctx = openContext(projectDir);
+    try {
+        return fn(ctx);
+    }
+    finally {
+        ctx.db.close();
+    }
+}
+function renderAfterUpdate(ctx) {
+    const states = ctx.db.getAllStates();
+    renderAndWrite({ config: ctx.config, projectDir: ctx.projectDir, ticketDefs: ctx.tickets, states, db: ctx.db });
+}
+export function cmdInit(projectDir, opts) {
+    if (isTicketsInitialized(projectDir)) {
+        throw new Error(".tickets/config.yaml already exists — already initialized.");
+    }
+    const ticketsDir = join(projectDir, ".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 });
+    const config = {
+        app_name: opts.appName ?? "My App",
+        queue_limit: opts.queueLimit ?? 50,
+        timezone: opts.timezone ?? "UTC",
+        timestamp_format: "iso8601_offset",
+        paths: {
+            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",
+        },
+        rendering: {
+            preserve_legacy_llm_queue_heading: true,
+            include_rules_in_progress_doc: true,
+            max_work_log_rows: 50,
+            max_validation_snapshot_rows: 20,
+            max_recent_completed_rows: 20,
+            generated_doc_warning: true,
+        },
+        behavior: {
+            regenerate_progress_doc_after_every_update: true,
+            require_validation_evidence_for_done: true,
+            block_on_unresolved_dependencies: true,
+            use_atomic_file_writes: true,
+            backup_before_import_or_migration: true,
+        },
+    };
+    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");
+    const ticketSchema = {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        title: "Ticket",
+        type: "object",
+        required: ["id", "order", "title", "area", "priority", "size", "risk",
+            "depends_on", "summary", "acceptance", "required_tests", "likely_files"],
+        properties: {
+            id: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9-_]*$" },
+            order: { type: "number", minimum: 0 },
+            title: { type: "string" },
+            area: { type: "string" },
+            priority: { type: "string", enum: ["P0", "P1", "P2", "P3"] },
+            size: { type: "string", enum: ["XS", "S", "M", "L", "XL"] },
+            risk: { type: "string", enum: ["Low", "Medium", "High"] },
+            depends_on: { type: "array", items: { type: "string" } },
+            summary: { type: "string" },
+            acceptance: { type: "array", items: { type: "string" }, minItems: 1 },
+            required_tests: { type: "array", items: { type: "string" }, minItems: 1 },
+            likely_files: { type: "array", items: { type: "string" } },
+            rollback: { type: ["string", "null"] },
+            notes: { type: ["string", "null"] },
+        },
+    };
+    writeFileSync(join(ticketsDir, "schema", "tickets.schema.json"), JSON.stringify(ticketSchema, null, 2), "utf8");
+    writeFileSync(join(ticketsDir, "migrations", "001_init.sql"), "-- Auto-applied by foreman tickets init via the StateDb class.\n" +
+        "-- See src/tickets/stateDb.ts for the full SQL schema.\n", "utf8");
+    // Open DB (runs migrations), render initial doc, close
+    const loadedConfig = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(loadedConfig, projectDir);
+    const db = new StateDb(paths.stateDb);
+    try {
+        const states = db.getAllStates();
+        renderAndWrite({ config: loadedConfig, projectDir, ticketDefs: [], states, db });
+    }
+    finally {
+        db.close();
+    }
+}
+export function cmdUpdate(projectDir, ticketId, opts) {
+    withContext(projectDir, (ctx) => {
+        const now = nowTimestamp(ctx.config.timezone);
+        const state = ctx.db.getState(ticketId);
+        const oldStatus = state?.status ?? null;
+        const patch = { last_worked_at: now };
+        if (opts.status)
+            patch.status = opts.status;
+        if (opts.nextAction !== undefined)
+            patch.next_action = opts.nextAction;
+        if (opts.currentStep !== undefined)
+            patch.current_step = opts.currentStep;
+        if (opts.owner !== undefined)
+            patch.owner = opts.owner;
+        if (opts.validationResult !== undefined)
+            patch.validation_result = opts.validationResult;
+        if (opts.validationCommands !== undefined)
+            patch.validation_commands = opts.validationCommands;
+        if (opts.validationNotes !== undefined)
+            patch.validation_notes = opts.validationNotes;
+        if (opts.evidence !== undefined)
+            patch.evidence = opts.evidence;
+        if (opts.lastError !== undefined)
+            patch.last_error = opts.lastError;
+        if (opts.status === "done" || opts.status === "canceled")
+            patch.completed_at = now;
+        ctx.db.transaction(() => {
+            ctx.db.upsertState(ticketId, patch, now);
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId,
+                eventType: "update",
+                oldStatus,
+                newStatus: opts.status ?? null,
+                summary: opts.summary ?? `Updated ticket ${ticketId}`,
+            });
+        });
+        renderAfterUpdate(ctx);
+    });
+}
+export function cmdComplete(projectDir, ticketId, opts) {
+    withContext(projectDir, (ctx) => {
+        const requireEvidence = ctx.config.behavior.requireValidationEvidenceForDone;
+        const vr = opts.validationResult ?? "not_run";
+        if (requireEvidence && !opts.evidence && vr !== "not_applicable") {
+            throw new Error(`--evidence is required to mark a ticket done (config.behavior.requireValidationEvidenceForDone=true).\n` +
+                `Use --validation-result not_applicable --validation-notes "<reason>" to skip.`);
+        }
+        const now = nowTimestamp(ctx.config.timezone);
+        const state = ctx.db.getState(ticketId);
+        const oldStatus = state?.status ?? null;
+        ctx.db.transaction(() => {
+            ctx.db.upsertState(ticketId, {
+                status: "done",
+                completed_at: now,
+                last_worked_at: now,
+                validation_result: vr,
+                validation_commands: opts.validationCommands ?? null,
+                validation_notes: opts.validationNotes ?? null,
+                evidence: opts.evidence ?? null,
+                attempt_count: (state?.attempt_count ?? 0) + 1,
+            }, now);
+            if (opts.validationResult && opts.evidence) {
+                ctx.db.insertValidationSnapshot({
+                    timestamp: now,
+                    scope: ticketId,
+                    result: opts.validationResult,
+                    commands: opts.validationCommands ?? null,
+                    evidence: opts.evidence,
+                    notes: opts.validationNotes ?? null,
+                });
+            }
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId,
+                eventType: "complete",
+                oldStatus,
+                newStatus: "done",
+                summary: opts.summary ?? `Completed ticket ${ticketId}`,
+                validation: opts.validationResult ?? null,
+                evidence: opts.evidence ?? null,
+            });
+        });
+        renderAfterUpdate(ctx);
+    });
+}
+export function cmdBlock(projectDir, ticketId, opts) {
+    withContext(projectDir, (ctx) => {
+        const now = nowTimestamp(ctx.config.timezone);
+        const state = ctx.db.getState(ticketId);
+        const oldStatus = state?.status ?? null;
+        const existing = JSON.parse(state?.blocked_by_json ?? "[]");
+        const merged = [...new Set([...existing, ...(opts.blockedBy ?? [])])];
+        ctx.db.transaction(() => {
+            ctx.db.upsertState(ticketId, {
+                status: "blocked",
+                blocked_by_json: JSON.stringify(merged),
+                blocker_type: opts.blockerType ?? "dependency",
+                blocker_notes: opts.unblockCriteria ?? null,
+                first_blocked_at: state?.first_blocked_at ?? now,
+                last_checked_at: now,
+                last_worked_at: now,
+            }, now);
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId,
+                eventType: "block",
+                oldStatus,
+                newStatus: "blocked",
+                summary: opts.summary ?? `Blocked ticket ${ticketId} by ${merged.join(", ")}`,
+            });
+        });
+        renderAfterUpdate(ctx);
+    });
+}
+// ── unblock ───────────────────────────────────────────────────────────────────
+export function cmdUnblock(projectDir, ticketId, opts) {
+    withContext(projectDir, (ctx) => {
+        const now = nowTimestamp(ctx.config.timezone);
+        const state = ctx.db.getState(ticketId);
+        const oldStatus = state?.status ?? null;
+        ctx.db.transaction(() => {
+            ctx.db.upsertState(ticketId, {
+                status: "planned",
+                blocked_by_json: "[]",
+                blocker_type: null,
+                blocker_notes: null,
+                first_blocked_at: null,
+                last_checked_at: null,
+                last_worked_at: now,
+            }, now);
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId,
+                eventType: "unblock",
+                oldStatus,
+                newStatus: "planned",
+                summary: opts.summary ?? `Unblocked ticket ${ticketId}`,
+            });
+        });
+        renderAfterUpdate(ctx);
+    });
+}
+// ── cancel ────────────────────────────────────────────────────────────────────
+export function cmdCancel(projectDir, ticketId, opts) {
+    withContext(projectDir, (ctx) => {
+        const now = nowTimestamp(ctx.config.timezone);
+        const state = ctx.db.getState(ticketId);
+        const oldStatus = state?.status ?? null;
+        ctx.db.transaction(() => {
+            ctx.db.upsertState(ticketId, {
+                status: "canceled",
+                completed_at: now,
+                last_worked_at: now,
+            }, now);
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId,
+                eventType: "cancel",
+                oldStatus,
+                newStatus: "canceled",
+                summary: opts.summary,
+            });
+        });
+        renderAfterUpdate(ctx);
+    });
+}
+export function cmdDiscover(projectDir, opts) {
+    return withContext(projectDir, (ctx) => {
+        const now = nowTimestamp(ctx.config.timezone);
+        let id;
+        ctx.db.transaction(() => {
+            id = ctx.db.insertFutureWork({
+                discovered_at: now,
+                source_ticket: opts.sourceTicket ?? null,
+                proposed_ticket: opts.proposedTicket ?? null,
+                priority_guess: opts.priorityGuess ?? null,
+                area: opts.area ?? null,
+                summary: opts.summary,
+                rationale: opts.rationale ?? null,
+                needs_decision_from: opts.needsDecisionFrom ?? null,
+                disposition: "triage",
+            });
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId: opts.sourceTicket ?? null,
+                eventType: "discover",
+                oldStatus: null,
+                newStatus: null,
+                summary: `Discovered future work: ${opts.summary}`,
+            });
+        });
+        renderAfterUpdate(ctx);
+        return id;
+    });
+}
+// ── accept-future-work ────────────────────────────────────────────────────────
+export function cmdAcceptFutureWork(projectDir, futureWorkId, opts) {
+    withContext(projectDir, (ctx) => {
+        const fw = ctx.db.getFutureWorkById(futureWorkId);
+        if (!fw)
+            throw new Error(`Future work item ${futureWorkId} not found`);
+        const now = nowTimestamp(ctx.config.timezone);
+        const newTicket = {
+            id: opts.ticketId,
+            order: opts.order,
+            title: fw.summary,
+            area: fw.area ?? "General",
+            priority: fw.priority_guess ?? "P2",
+            size: "M",
+            risk: "Low",
+            depends_on: [],
+            summary: fw.summary,
+            acceptance: ["TODO: fill acceptance criteria"],
+            required_tests: ["TODO: fill required tests"],
+            likely_files: [],
+            rollback: null,
+            notes: fw.rationale ?? null,
+        };
+        ctx.db.transaction(() => {
+            ctx.db.updateFutureWorkDisposition(futureWorkId, "accepted");
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId: opts.ticketId,
+                eventType: "accept-future-work",
+                oldStatus: null,
+                newStatus: "planned",
+                summary: `Accepted future work ${futureWorkId} as ticket ${opts.ticketId}`,
+            });
+        });
+        saveTickets(ctx.paths.tickets, [...ctx.tickets, newTicket]);
+        // Re-open context to pick up new ticket list
+        const newCtx = openContext(projectDir);
+        try {
+            renderAfterUpdate(newCtx);
+        }
+        finally {
+            newCtx.db.close();
+        }
+    });
+}
+// ── reorder ───────────────────────────────────────────────────────────────────
+export function cmdReorder(projectDir, ticketId, opts) {
+    withContext(projectDir, (ctx) => {
+        const ticket = ctx.tickets.find((t) => t.id === ticketId);
+        if (!ticket)
+            throw new Error(`Ticket ${ticketId} not found`);
+        let newOrder;
+        if (opts.order !== undefined) {
+            newOrder = opts.order;
+        }
+        else if (opts.afterTicketId) {
+            const afterTicket = ctx.tickets.find((t) => t.id === opts.afterTicketId);
+            if (!afterTicket)
+                throw new Error(`Ticket ${opts.afterTicketId} not found`);
+            const sorted = [...ctx.tickets].sort((a, b) => a.order - b.order);
+            const afterIdx = sorted.findIndex((t) => t.id === opts.afterTicketId);
+            const next = sorted[afterIdx + 1];
+            newOrder = next ? Math.floor((afterTicket.order + next.order) / 2) : afterTicket.order + 1000;
+        }
+        else {
+            throw new Error("Provide --after <ticketId> or --order <n>");
+        }
+        const now = nowTimestamp(ctx.config.timezone);
+        const updated = ctx.tickets.map((t) => t.id === ticketId ? { ...t, order: newOrder } : t);
+        saveTickets(ctx.paths.tickets, updated);
+        ctx.db.transaction(() => {
+            logEvent(ctx.db, {
+                timestamp: now,
+                actor: opts.actor ?? null,
+                ticketId,
+                eventType: "reorder",
+                oldStatus: null,
+                newStatus: null,
+                summary: `Reordered ticket ${ticketId} to order ${newOrder}`,
+            });
+        });
+        // Re-open with updated tickets
+        const newCtx = openContext(projectDir);
+        try {
+            renderAfterUpdate(newCtx);
+        }
+        finally {
+            newCtx.db.close();
+        }
+    });
+}
+// ── render ────────────────────────────────────────────────────────────────────
+export function cmdRender(projectDir) {
+    withContext(projectDir, (ctx) => {
+        renderAfterUpdate(ctx);
+    });
+}
+export function cmdValidate(projectDir) {
+    return withContext(projectDir, (ctx) => {
+        const states = ctx.db.getAllStates();
+        const issues = runAllValidation(ctx.config, projectDir, ctx.tickets, states, ctx.db);
+        return { issues, clean: issues.filter((i) => i.severity === "error").length === 0 };
+    });
+}
+// ── queue ─────────────────────────────────────────────────────────────────────
+export function cmdQueue(projectDir, limit) {
+    return withContext(projectDir, (ctx) => {
+        const states = ctx.db.getAllStates();
+        return buildNextQueue(ctx.tickets, states, limit ?? ctx.config.queueLimit);
+    });
+}
+// ── archive ───────────────────────────────────────────────────────────────────
+export function cmdArchive(projectDir, _opts) {
+    withContext(projectDir, (ctx) => {
+        const now = nowTimestamp(ctx.config.timezone);
+        logEvent(ctx.db, {
+            timestamp: now,
+            actor: "system",
+            ticketId: null,
+            eventType: "archive",
+            oldStatus: null,
+            newStatus: null,
+            summary: "Archive pass executed",
+        });
+        renderAfterUpdate(ctx);
+    });
+}

package/dist/tickets/config.js

@@ -0,0 +1,133 @@
+import { readFileSync, existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { parse } from "yaml";
+export const DEFAULT_TICKETS_CONFIG = {
+    appName: "My App",
+    queueLimit: 50,
+    timezone: "UTC",
+    paths: {
+        tickets: ".tickets/tickets.yaml",
+        stateDb: ".tickets/ticket-state.sqlite",
+        trackerRules: ".tickets/tracker-rules.md",
+        progressDoc: "docs/ticket-progress.md",
+        archiveDoc: "docs/ticket-archive.md",
+    },
+    rendering: {
+        preserveLegacyLlmQueueHeading: true,
+        includeRulesInProgressDoc: true,
+        maxWorkLogRows: 50,
+        maxValidationSnapshotRows: 20,
+        maxRecentCompletedRows: 20,
+        generatedDocWarning: true,
+    },
+    behavior: {
+        regenerateProgressDocAfterEveryUpdate: true,
+        requireValidationEvidenceForDone: true,
+        blockOnUnresolvedDependencies: true,
+        useAtomicFileWrites: true,
+        backupBeforeImportOrMigration: true,
+    },
+};
+function snakeToCamel(s) {
+    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function camelizeObject(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        result[snakeToCamel(k)] = v;
+    }
+    return result;
+}
+export function loadTicketsConfig(projectDir) {
+    const configPath = join(projectDir, ".tickets", "config.yaml");
+    if (!existsSync(configPath)) {
+        return {
+            ...DEFAULT_TICKETS_CONFIG,
+            paths: { ...DEFAULT_TICKETS_CONFIG.paths },
+            rendering: { ...DEFAULT_TICKETS_CONFIG.rendering },
+            behavior: { ...DEFAULT_TICKETS_CONFIG.behavior },
+        };
+    }
+    const raw = parse(readFileSync(configPath, "utf8")) ?? {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${configPath}: expected a YAML object`);
+    }
+    assertPlainObject(raw.paths, "paths", configPath);
+    assertPlainObject(raw.rendering, "rendering", configPath);
+    assertPlainObject(raw.behavior, "behavior", configPath);
+    const config = {
+        appName: raw.app_name ?? DEFAULT_TICKETS_CONFIG.appName,
+        queueLimit: raw.queue_limit ?? DEFAULT_TICKETS_CONFIG.queueLimit,
+        timezone: raw.timezone ?? DEFAULT_TICKETS_CONFIG.timezone,
+        paths: {
+            ...DEFAULT_TICKETS_CONFIG.paths,
+            ...(raw.paths ? camelizeObject(raw.paths) : {}),
+        },
+        rendering: {
+            ...DEFAULT_TICKETS_CONFIG.rendering,
+            ...(raw.rendering ? camelizeObject(raw.rendering) : {}),
+        },
+        behavior: {
+            ...DEFAULT_TICKETS_CONFIG.behavior,
+            ...(raw.behavior ? camelizeObject(raw.behavior) : {}),
+        },
+    };
+    validateTicketsConfig(config, configPath);
+    return config;
+}
+function assertPlainObject(value, name, configPath) {
+    if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
+        throw new Error(`${configPath}: ${name} must be an object`);
+    }
+}
+function validateTicketsConfig(config, configPath) {
+    if (!config.appName || typeof config.appName !== "string") {
+        throw new Error(`${configPath}: app_name must be a non-empty string`);
+    }
+    if (!Number.isInteger(config.queueLimit) || config.queueLimit < 1) {
+        throw new Error(`${configPath}: queue_limit must be a positive integer`);
+    }
+    if (!config.timezone || typeof config.timezone !== "string") {
+        throw new Error(`${configPath}: timezone must be a non-empty IANA timezone string`);
+    }
+    for (const [key, value] of Object.entries(config.paths)) {
+        if (!value || typeof value !== "string") {
+            throw new Error(`${configPath}: paths.${camelToSnake(key)} must be a non-empty string`);
+        }
+        if (isAbsolute(value)) {
+            throw new Error(`${configPath}: paths.${camelToSnake(key)} must be repo-relative`);
+        }
+    }
+    for (const [key, value] of Object.entries(config.rendering)) {
+        if (key.startsWith("max")) {
+            if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+                throw new Error(`${configPath}: rendering.${camelToSnake(key)} must be a positive integer`);
+            }
+        }
+        else if (typeof value !== "boolean") {
+            throw new Error(`${configPath}: rendering.${camelToSnake(key)} must be a boolean`);
+        }
+    }
+    for (const [key, value] of Object.entries(config.behavior)) {
+        if (typeof value !== "boolean") {
+            throw new Error(`${configPath}: behavior.${camelToSnake(key)} must be a boolean`);
+        }
+    }
+}
+function camelToSnake(s) {
+    return s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+export function isTicketsInitialized(projectDir) {
+    return existsSync(join(projectDir, ".tickets", "config.yaml"));
+}
+export function resolveTicketPaths(config, projectDir) {
+    const p = config.paths;
+    const r = (rel) => join(projectDir, rel);
+    return {
+        tickets: r(p.tickets),
+        stateDb: r(p.stateDb),
+        trackerRules: r(p.trackerRules),
+        progressDoc: r(p.progressDoc),
+        archiveDoc: r(p.archiveDoc),
+    };
+}

package/dist/tickets/events.js

@@ -0,0 +1,19 @@
+import { DateTime } from "luxon";
+export function nowTimestamp(timezone) {
+    return DateTime.now().setZone(timezone).toISO() ?? new Date().toISOString();
+}
+export function logEvent(db, opts) {
+    const event = {
+        timestamp: opts.timestamp,
+        actor: opts.actor,
+        ticket_id: opts.ticketId,
+        event_type: opts.eventType,
+        old_status: opts.oldStatus,
+        new_status: opts.newStatus,
+        summary: opts.summary,
+        validation: opts.validation ?? null,
+        evidence: opts.evidence ?? null,
+        payload_json: JSON.stringify(opts.payload ?? {}),
+    };
+    db.insertEvent(event);
+}

package/dist/tickets/importer.js

@@ -0,0 +1,11 @@
+export function importFromMarkdown(_progressDocPath) {
+    throw new Error("foreman tickets import is not yet implemented.\n\n" +
+        "To start fresh:\n" +
+        "  1. Run `foreman tickets init --app-name \"My App\" --timezone America/Chicago`\n" +
+        "  2. Add your tickets to .tickets/tickets.yaml\n" +
+        "  3. Run `foreman tickets render`\n\n" +
+        "Manual migration steps:\n" +
+        "  1. Copy ticket definitions into .tickets/tickets.yaml following the schema.\n" +
+        "  2. Run `foreman tickets validate` to check the structure.\n" +
+        "  3. Use `foreman tickets update <id> --status <status>` to restore active ticket states.");
+}

package/dist/tickets/queue.js

@@ -0,0 +1,62 @@
+import { resolveBlockers, computeDisplayStatus } from "./blockers.js";
+function defaultNextAction(ticket, displayStatus, blockedBy) {
+    if (displayStatus === "blocked")
+        return `Resolve blockers: ${blockedBy.join(", ")}`;
+    if (displayStatus === "in_progress")
+        return "Continue implementation";
+    return "Begin implementation";
+}
+export function buildNextQueue(ticketDefs, states, queueLimit) {
+    const remaining = ticketDefs
+        .filter((t) => {
+        const s = states.get(t.id);
+        const status = s?.status ?? "planned";
+        return status !== "done" && status !== "canceled";
+    })
+        .sort((a, b) => a.order - b.order);
+    const window = remaining.slice(0, Math.min(queueLimit, remaining.length));
+    return window.map((ticket, index) => {
+        const state = states.get(ticket.id);
+        const blockedBy = resolveBlockers(ticket, states);
+        const displayStatus = computeDisplayStatus(state?.status ?? "planned", blockedBy);
+        return {
+            rank: index + 1,
+            ticket: ticket.id,
+            title: ticket.title,
+            status: displayStatus,
+            priority: ticket.priority,
+            area: ticket.area,
+            dependsOn: ticket.depends_on.length ? ticket.depends_on.join(", ") : "None",
+            blockedBy: blockedBy.length ? blockedBy.join(", ") : "None",
+            size: ticket.size,
+            risk: ticket.risk,
+            nextAction: state?.next_action ?? defaultNextAction(ticket, displayStatus, blockedBy),
+            requiredTests: ticket.required_tests.join("; "),
+            evidence: state?.evidence ?? "N/A until implemented.",
+            likelyFiles: ticket.likely_files.length ? ticket.likely_files.join(", ") : "unknown",
+        };
+    });
+}
+export function buildActiveStatusRows(queueRows, ticketDefs, states) {
+    const defsById = new Map(ticketDefs.map((t) => [t.id, t]));
+    return queueRows.map((row) => {
+        const state = states.get(row.ticket);
+        const def = defsById.get(row.ticket);
+        return {
+            ticket: row.ticket,
+            title: row.title,
+            status: row.status,
+            priority: row.priority,
+            area: row.area,
+            owner: state?.owner ?? "unassigned",
+            lastWorkedAt: state?.last_worked_at ?? "N/A",
+            completedAt: state?.completed_at ?? "N/A",
+            dependsOn: row.dependsOn,
+            blockers: row.blockedBy,
+            nextAction: row.nextAction,
+            acceptanceTestGate: def?.acceptance.join("; ") ?? "N/A",
+            evidence: row.evidence,
+            futureWorkNotes: state?.blocker_notes ?? "N/A",
+        };
+    });
+}