ai-foreman 1.0.0

package/dist/tickets/renderMarkdown.js

@@ -0,0 +1,223 @@
+import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DateTime } from "luxon";
+import { buildNextQueue, buildActiveStatusRows } from "./queue.js";
+// ── Table helpers ─────────────────────────────────────────────────────────────
+function esc(v) {
+    return v.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
+}
+function table(headers, rows) {
+    const sep = `|${headers.map(() => "---").join("|")}|`;
+    const head = `| ${headers.join(" | ")} |`;
+    const body = rows.map((r) => `| ${r.map(esc).join(" | ")} |`).join("\n");
+    return body ? `${head}\n${sep}\n${body}` : `${head}\n${sep}`;
+}
+// ── Section helpers ───────────────────────────────────────────────────────────
+function section(marker, content) {
+    return `<!-- ${marker}_START -->\n${content}\n<!-- ${marker}_END -->`;
+}
+// ── Default tracker-rules content ─────────────────────────────────────────────
+export const DEFAULT_TRACKER_RULES = `# 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
+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\`.
+Use \`foreman tickets update <id>\` — never manually edit generated sections.
+
+## Blocked work
+Do not implement blocked rows unless the blocker itself is the approved next work.
+
+## Done policy
+Never mark a ticket \`done\` without required validation evidence or a documented test exception.
+Use \`foreman tickets complete <id> --validation-result passed --evidence "..."\`.
+
+## New work policy
+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\`.
+Use the \`foreman tickets\` commands instead.
+
+## STEP_STATUS protocol
+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 function renderProgressDoc(input) {
+    const { config, projectDir, ticketDefs, states, db } = input;
+    const now = input.now ?? DateTime.now().setZone(config.timezone).toISO();
+    const queueRows = buildNextQueue(ticketDefs, states, config.queueLimit);
+    const activeRows = buildActiveStatusRows(queueRows, ticketDefs, states);
+    const futureWork = db.getFutureWork();
+    const recentEvents = db.getRecentEvents(config.rendering.maxWorkLogRows);
+    const lastSnap = db.getRecentValidationSnapshot();
+    const recentCompleted = db.getRecentCompleted();
+    const archiveIndex = db.getArchiveIndex();
+    const rulesPath = join(projectDir, config.paths.trackerRules);
+    const rulesContent = existsSync(rulesPath)
+        ? readFileSync(rulesPath, "utf8").trim()
+        : DEFAULT_TRACKER_RULES.trim();
+    const lines = [];
+    // Header
+    lines.push("# Ticket Progress Tracker");
+    lines.push("");
+    if (config.rendering.generatedDocWarning) {
+        lines.push("> Generated file. Do not manually edit generated sections. Use `foreman tickets` commands.");
+        lines.push("");
+    }
+    // Tracker Metadata
+    lines.push("## Tracker Metadata");
+    lines.push(section("TRACKER_METADATA", table(["Field", "Value"], [
+        ["App", config.appName],
+        ["Queue Limit", String(config.queueLimit)],
+        ["Timezone", config.timezone],
+        ["Generated At", now],
+        ["Remaining Tickets", String(queueRows.length > 0 ? "≥" + queueRows.length : "0")],
+    ])));
+    lines.push("");
+    // Rules
+    if (config.rendering.includeRulesInProgressDoc) {
+        lines.push(rulesContent);
+        lines.push("");
+    }
+    // LLM_NEXT_QUEUE
+    lines.push("## LLM_NEXT_QUEUE");
+    const queueTableContent = queueRows.length === 0
+        ? "_No remaining tickets. All work is complete or no tickets have been defined._"
+        : table(["Rank", "Ticket", "Title", "Status", "Priority", "Area", "Depends On", "Blocked By",
+            "Size", "Risk", "Next Action", "Required Tests", "Evidence", "Likely Files"], queueRows.map((r) => [
+            String(r.rank), r.ticket, r.title, r.status, r.priority, r.area,
+            r.dependsOn, r.blockedBy, r.size, r.risk, r.nextAction,
+            r.requiredTests, r.evidence, r.likelyFiles,
+        ]));
+    lines.push(section("LLM_NEXT_QUEUE", queueTableContent));
+    lines.push("");
+    // Active Ticket Status
+    lines.push("## Active Ticket Status");
+    const activeContent = activeRows.length === 0
+        ? "_No active tickets._"
+        : table(["Ticket", "Title", "Status", "Priority", "Area", "Owner", "last_worked_at",
+            "completed_at", "Depends On", "Blockers", "Next Action", "Acceptance / Test Gate",
+            "Evidence", "Future Work / Notes"], activeRows.map((r) => [
+            r.ticket, r.title, r.status, r.priority, r.area, r.owner,
+            r.lastWorkedAt, r.completedAt, r.dependsOn, r.blockers, r.nextAction,
+            r.acceptanceTestGate, r.evidence, r.futureWorkNotes,
+        ]));
+    lines.push(section("ACTIVE_TICKET_STATUS", activeContent));
+    lines.push("");
+    // Blocked Tickets
+    const blockedRows = queueRows.filter((r) => r.blockedBy !== "None");
+    lines.push("## Blocked Tickets");
+    const blockedContent = blockedRows.length === 0
+        ? "_No blocked tickets._"
+        : table(["Ticket", "Blocked By", "Blocker Type", "Owner", "First Blocked At",
+            "Last Checked At", "Needed Decision / Action", "Unblock Criteria", "Notes"], blockedRows.map((r) => {
+            const state = states.get(r.ticket);
+            return [
+                r.ticket, r.blockedBy,
+                state?.blocker_type ?? "dependency",
+                state?.owner ?? "unassigned",
+                state?.first_blocked_at ?? "N/A",
+                state?.last_checked_at ?? "N/A",
+                state?.next_action ?? "Resolve blockers",
+                state?.blocker_notes ?? "N/A",
+                "N/A",
+            ];
+        }));
+    lines.push(section("BLOCKED_TICKETS", blockedContent));
+    lines.push("");
+    // Recently Completed Context
+    lines.push("## Recently Completed Context");
+    const recentCompContent = recentCompleted.length === 0
+        ? "_No recently completed tickets pinned for context._"
+        : table(["Ticket", "Why It Remains Here", "Pinned Until", "Updated At"], recentCompleted.map((r) => [
+            r.ticket_id, r.why_it_remains_here, r.pinned_until ?? "N/A", r.updated_at,
+        ]));
+    lines.push(section("RECENTLY_COMPLETED_CONTEXT", recentCompContent));
+    lines.push("");
+    // Discovered Future Work Inbox
+    lines.push("## Discovered Future Work Inbox");
+    const openFutureWork = futureWork.filter((fw) => fw.disposition === "triage");
+    const futureContent = openFutureWork.length === 0
+        ? "_No discovered future work items._"
+        : table(["ID", "Discovered At", "Source Ticket", "Proposed Ticket", "Priority Guess",
+            "Area", "Summary", "Rationale", "Needs Decision From", "Disposition"], openFutureWork.map((fw) => [
+            String(fw.id ?? ""),
+            fw.discovered_at,
+            fw.source_ticket ?? "N/A",
+            fw.proposed_ticket ?? "N/A",
+            fw.priority_guess ?? "N/A",
+            fw.area ?? "N/A",
+            fw.summary,
+            fw.rationale ?? "N/A",
+            fw.needs_decision_from ?? "N/A",
+            fw.disposition,
+        ]));
+    lines.push(section("DISCOVERED_FUTURE_WORK", futureContent));
+    lines.push("");
+    // Archive Index
+    lines.push("## Archive Index");
+    const archiveContent = archiveIndex.length === 0
+        ? "_No archived tickets yet._"
+        : table(["Archive File", "Scope", "Last Updated", "Notes"], archiveIndex.map((a) => [
+            a.archive_file, a.scope, a.last_updated ?? "N/A", a.notes ?? "N/A",
+        ]));
+    lines.push(section("ARCHIVE_INDEX", archiveContent));
+    lines.push("");
+    // Last Validation Snapshot
+    lines.push("## Last Validation Snapshot");
+    const snapRow = lastSnap
+        ? [lastSnap.timestamp, lastSnap.scope, lastSnap.result,
+            lastSnap.commands ?? "N/A", lastSnap.evidence ?? "N/A", lastSnap.notes ?? "N/A"]
+        : ["N/A", "tracker", "not_run", "N/A", "N/A", "No validation snapshots recorded yet."];
+    lines.push(table(["Timestamp", "Scope", "Result", "Commands", "Evidence", "Notes"], [snapRow]));
+    lines.push("");
+    // Work Log
+    lines.push("## Work Log");
+    const workLogContent = recentEvents.length === 0
+        ? "_No work log entries yet._"
+        : table(["Timestamp", "Actor", "Ticket", "Event", "Old Status", "New Status", "Summary"], recentEvents.map((e) => [
+            e.timestamp, e.actor ?? "system", e.ticket_id ?? "—",
+            e.event_type, e.old_status ?? "—", e.new_status ?? "—", e.summary,
+        ]));
+    lines.push(section("WORK_LOG", workLogContent));
+    lines.push("");
+    // Four-Pass Validation Checklist
+    lines.push("## Four-Pass Validation Checklist");
+    lines.push("");
+    lines.push("Run `foreman tickets validate` to execute all passes.");
+    lines.push("");
+    lines.push("1. **Schema & source** — config.yaml, tickets.yaml schema, unique IDs/orders, valid deps, no cycles.");
+    lines.push("2. **State** — SQLite migrations applied, all state ticket_ids exist in tickets.yaml, done tickets have evidence.");
+    lines.push("3. **Queue** — correct length, contiguous ranks, no done/canceled, sorted by order, blocked rows marked.");
+    lines.push("4. **Generated doc** — required sections and marker comments present, every queued ticket in Active Status.");
+    lines.push("");
+    return lines.join("\n");
+}
+export function writeProgressDoc(progressDocPath, content, atomic) {
+    mkdirSync(dirname(progressDocPath), { recursive: true });
+    if (atomic) {
+        const tmp = `${progressDocPath}.tmp`;
+        writeFileSync(tmp, content, "utf8");
+        renameSync(tmp, progressDocPath);
+    }
+    else {
+        writeFileSync(progressDocPath, content, "utf8");
+    }
+}
+export function renderAndWrite(input) {
+    const { config, projectDir } = input;
+    const progressDocPath = join(projectDir, config.paths.progressDoc);
+    const content = renderProgressDoc(input);
+    writeProgressDoc(progressDocPath, content, config.behavior.useAtomicFileWrites);
+}

package/dist/tickets/stateDb.js

@@ -0,0 +1,252 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+const INIT_SQL = `
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS ticket_state (
+  ticket_id TEXT PRIMARY KEY,
+  status TEXT NOT NULL DEFAULT 'planned',
+  owner TEXT,
+  current_step TEXT,
+  next_action TEXT,
+  blocked_by_json TEXT NOT NULL DEFAULT '[]',
+  blocker_type TEXT,
+  blocker_notes TEXT,
+  first_blocked_at TEXT,
+  last_checked_at TEXT,
+  last_worked_at TEXT,
+  completed_at TEXT,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  evidence TEXT,
+  validation_result TEXT,
+  validation_commands TEXT,
+  validation_notes TEXT,
+  updated_at TEXT NOT NULL,
+  updated_by TEXT,
+  CHECK (status IN ('planned','next','in_progress','blocked','done','canceled')),
+  CHECK (validation_result IS NULL OR validation_result IN ('passed','failed','not_run','not_applicable'))
+);
+
+CREATE TABLE IF NOT EXISTS ticket_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL,
+  actor TEXT,
+  ticket_id TEXT,
+  event_type TEXT NOT NULL,
+  old_status TEXT,
+  new_status TEXT,
+  summary TEXT NOT NULL,
+  validation TEXT,
+  evidence TEXT,
+  payload_json TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE IF NOT EXISTS validation_snapshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  result TEXT NOT NULL,
+  commands TEXT,
+  evidence TEXT,
+  notes TEXT,
+  CHECK (result IN ('passed','failed','not_run','not_applicable'))
+);
+
+CREATE TABLE IF NOT EXISTS future_work (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  discovered_at TEXT NOT NULL,
+  source_ticket TEXT,
+  proposed_ticket TEXT,
+  priority_guess TEXT,
+  area TEXT,
+  summary TEXT NOT NULL,
+  rationale TEXT,
+  needs_decision_from TEXT,
+  disposition TEXT NOT NULL DEFAULT 'triage',
+  CHECK (disposition IN ('triage','accepted','rejected','merged','queued'))
+);
+
+CREATE TABLE IF NOT EXISTS recent_completed_context (
+  ticket_id TEXT PRIMARY KEY,
+  why_it_remains_here TEXT NOT NULL,
+  pinned_until TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS archive_index (
+  archive_file TEXT PRIMARY KEY,
+  scope TEXT NOT NULL,
+  last_updated TEXT,
+  notes TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_ticket_state_status ON ticket_state(status);
+CREATE INDEX IF NOT EXISTS idx_ticket_events_ticket_id ON ticket_events(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_events_timestamp ON ticket_events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_validation_snapshots_timestamp ON validation_snapshots(timestamp);
+CREATE INDEX IF NOT EXISTS idx_future_work_disposition ON future_work(disposition);
+`;
+export class StateDb {
+    db;
+    constructor(dbPath) {
+        mkdirSync(dirname(dbPath), { recursive: true });
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.exec(INIT_SQL);
+    }
+    close() {
+        this.db.close();
+    }
+    // ── ticket_state ──────────────────────────────────────────────────────────
+    getState(ticketId) {
+        return this.db
+            .prepare("SELECT * FROM ticket_state WHERE ticket_id = ?")
+            .get(ticketId);
+    }
+    getAllStates() {
+        const rows = this.db.prepare("SELECT * FROM ticket_state").all();
+        const m = new Map();
+        for (const row of rows)
+            m.set(row.ticket_id, row);
+        return m;
+    }
+    upsertState(ticketId, patch, now) {
+        const existing = this.getState(ticketId);
+        const base = existing ?? {
+            ticket_id: ticketId,
+            status: "planned",
+            owner: null,
+            current_step: null,
+            next_action: null,
+            blocked_by_json: "[]",
+            blocker_type: null,
+            blocker_notes: null,
+            first_blocked_at: null,
+            last_checked_at: null,
+            last_worked_at: null,
+            completed_at: null,
+            attempt_count: 0,
+            last_error: null,
+            evidence: null,
+            validation_result: null,
+            validation_commands: null,
+            validation_notes: null,
+            updated_at: now,
+            updated_by: null,
+        };
+        const merged = { ...base, ...patch, ticket_id: ticketId, updated_at: now };
+        if (existing) {
+            this.db.prepare(`
+        UPDATE ticket_state SET
+          status=@status, owner=@owner, current_step=@current_step,
+          next_action=@next_action, blocked_by_json=@blocked_by_json,
+          blocker_type=@blocker_type, blocker_notes=@blocker_notes,
+          first_blocked_at=@first_blocked_at, last_checked_at=@last_checked_at,
+          last_worked_at=@last_worked_at, completed_at=@completed_at,
+          attempt_count=@attempt_count, last_error=@last_error,
+          evidence=@evidence, validation_result=@validation_result,
+          validation_commands=@validation_commands, validation_notes=@validation_notes,
+          updated_at=@updated_at, updated_by=@updated_by
+        WHERE ticket_id=@ticket_id
+      `).run(merged);
+        }
+        else {
+            this.db.prepare(`
+        INSERT INTO ticket_state (
+          ticket_id,status,owner,current_step,next_action,blocked_by_json,
+          blocker_type,blocker_notes,first_blocked_at,last_checked_at,
+          last_worked_at,completed_at,attempt_count,last_error,evidence,
+          validation_result,validation_commands,validation_notes,updated_at,updated_by
+        ) VALUES (
+          @ticket_id,@status,@owner,@current_step,@next_action,@blocked_by_json,
+          @blocker_type,@blocker_notes,@first_blocked_at,@last_checked_at,
+          @last_worked_at,@completed_at,@attempt_count,@last_error,@evidence,
+          @validation_result,@validation_commands,@validation_notes,@updated_at,@updated_by
+        )
+      `).run(merged);
+        }
+    }
+    // ── ticket_events ─────────────────────────────────────────────────────────
+    insertEvent(event) {
+        this.db.prepare(`
+      INSERT INTO ticket_events (
+        timestamp,actor,ticket_id,event_type,old_status,new_status,
+        summary,validation,evidence,payload_json
+      ) VALUES (
+        @timestamp,@actor,@ticket_id,@event_type,@old_status,@new_status,
+        @summary,@validation,@evidence,@payload_json
+      )
+    `).run(event);
+    }
+    getRecentEvents(limit) {
+        return this.db
+            .prepare("SELECT * FROM ticket_events ORDER BY timestamp DESC, id DESC LIMIT ?")
+            .all(limit);
+    }
+    // ── validation_snapshots ──────────────────────────────────────────────────
+    insertValidationSnapshot(snap) {
+        this.db.prepare(`
+      INSERT INTO validation_snapshots (timestamp,scope,result,commands,evidence,notes)
+      VALUES (@timestamp,@scope,@result,@commands,@evidence,@notes)
+    `).run(snap);
+    }
+    getRecentValidationSnapshot() {
+        return this.db
+            .prepare("SELECT * FROM validation_snapshots ORDER BY timestamp DESC, id DESC LIMIT 1")
+            .get();
+    }
+    // ── future_work ───────────────────────────────────────────────────────────
+    insertFutureWork(item) {
+        const r = this.db.prepare(`
+      INSERT INTO future_work (
+        discovered_at,source_ticket,proposed_ticket,priority_guess,
+        area,summary,rationale,needs_decision_from,disposition
+      ) VALUES (
+        @discovered_at,@source_ticket,@proposed_ticket,@priority_guess,
+        @area,@summary,@rationale,@needs_decision_from,@disposition
+      )
+    `).run(item);
+        return r.lastInsertRowid;
+    }
+    getFutureWork() {
+        return this.db
+            .prepare("SELECT * FROM future_work ORDER BY id")
+            .all();
+    }
+    getFutureWorkById(id) {
+        return this.db
+            .prepare("SELECT * FROM future_work WHERE id = ?")
+            .get(id);
+    }
+    updateFutureWorkDisposition(id, disposition) {
+        this.db.prepare("UPDATE future_work SET disposition = ? WHERE id = ?").run(disposition, id);
+    }
+    // ── recent_completed_context ──────────────────────────────────────────────
+    getRecentCompleted() {
+        return this.db
+            .prepare("SELECT * FROM recent_completed_context ORDER BY updated_at DESC")
+            .all();
+    }
+    upsertRecentCompleted(row) {
+        this.db.prepare(`
+      INSERT INTO recent_completed_context (ticket_id,why_it_remains_here,pinned_until,updated_at)
+      VALUES (@ticket_id,@why_it_remains_here,@pinned_until,@updated_at)
+      ON CONFLICT(ticket_id) DO UPDATE SET
+        why_it_remains_here=excluded.why_it_remains_here,
+        pinned_until=excluded.pinned_until,
+        updated_at=excluded.updated_at
+    `).run(row);
+    }
+    // ── archive_index ─────────────────────────────────────────────────────────
+    getArchiveIndex() {
+        return this.db
+            .prepare("SELECT * FROM archive_index ORDER BY last_updated DESC")
+            .all();
+    }
+    // ── transactions ──────────────────────────────────────────────────────────
+    transaction(fn) {
+        return this.db.transaction(fn)();
+    }
+}

package/dist/tickets/ticketLoader.js

@@ -0,0 +1,84 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { parse, stringify } from "yaml";
+import { Ajv } from "ajv";
+import { TICKET_JSON_SCHEMA } from "./ticketSchema.js";
+const ajv = new Ajv({ allErrors: true });
+const validateTicketSchema = ajv.compile(TICKET_JSON_SCHEMA);
+export function loadTickets(ticketsPath) {
+    if (!existsSync(ticketsPath))
+        return [];
+    const raw = parse(readFileSync(ticketsPath, "utf8"));
+    if (!raw || !Array.isArray(raw.tickets))
+        return [];
+    return raw.tickets;
+}
+export function saveTickets(ticketsPath, tickets) {
+    writeFileSync(ticketsPath, stringify({ tickets }, { lineWidth: 120 }), "utf8");
+}
+export function validateTicketDefs(tickets) {
+    const errors = [];
+    for (const ticket of tickets) {
+        if (!validateTicketSchema(ticket)) {
+            for (const err of validateTicketSchema.errors ?? []) {
+                errors.push({
+                    path: `tickets[${ticket.id ?? "?"}]${err.instancePath}`,
+                    message: err.message ?? "unknown error",
+                });
+            }
+        }
+    }
+    const ids = new Set();
+    for (const t of tickets) {
+        if (ids.has(t.id)) {
+            errors.push({ path: `tickets[${t.id}]`, message: `duplicate ticket ID: ${t.id}` });
+        }
+        ids.add(t.id);
+    }
+    const orders = new Set();
+    for (const t of tickets) {
+        if (orders.has(t.order)) {
+            errors.push({ path: `tickets[${t.id}]`, message: `duplicate order value: ${t.order}` });
+        }
+        orders.add(t.order);
+    }
+    for (const t of tickets) {
+        for (const dep of t.depends_on) {
+            if (!ids.has(dep)) {
+                errors.push({ path: `tickets[${t.id}].depends_on`, message: `references unknown ticket: ${dep}` });
+            }
+        }
+    }
+    for (const t of tickets) {
+        if ((t.risk === "Medium" || t.risk === "High") && !t.rollback) {
+            errors.push({ path: `tickets[${t.id}]`, message: `${t.risk} risk ticket requires rollback/mitigation notes` });
+        }
+    }
+    return errors;
+}
+export function detectCycles(tickets) {
+    const adj = new Map();
+    for (const t of tickets)
+        adj.set(t.id, t.depends_on);
+    const visited = new Set();
+    const inStack = new Set();
+    const cycles = [];
+    function dfs(id, path) {
+        if (inStack.has(id)) {
+            const cycleStart = path.indexOf(id);
+            cycles.push([...path.slice(cycleStart), id].join(" → "));
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        inStack.add(id);
+        for (const dep of adj.get(id) ?? [])
+            dfs(dep, [...path, id]);
+        inStack.delete(id);
+    }
+    for (const t of tickets) {
+        if (!visited.has(t.id))
+            dfs(t.id, []);
+    }
+    return cycles;
+}

package/dist/tickets/ticketSchema.js

@@ -0,0 +1,31 @@
+export const TICKET_JSON_SCHEMA = {
+    type: "object",
+    required: [
+        "id", "order", "title", "area", "priority", "size", "risk",
+        "depends_on", "summary", "acceptance", "required_tests", "likely_files",
+    ],
+    additionalProperties: true,
+    properties: {
+        id: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9-_]*$" },
+        order: { type: "number", minimum: 0 },
+        title: { type: "string", minLength: 1 },
+        area: { type: "string", minLength: 1 },
+        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", minLength: 1 },
+        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"] },
+    },
+};
+export const TICKETS_FILE_SCHEMA = {
+    type: "object",
+    required: ["tickets"],
+    properties: {
+        tickets: { type: "array", items: TICKET_JSON_SCHEMA },
+    },
+};

package/dist/tickets/validate.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateTicketDefs, detectCycles } from "./ticketLoader.js";
+import { buildNextQueue } from "./queue.js";
+export function runAllValidation(config, projectDir, ticketDefs, states, db) {
+    const issues = [];
+    // Pass 1: schema and source
+    for (const err of validateTicketDefs(ticketDefs)) {
+        issues.push({ pass: 1, severity: "error", message: `[schema] ${err.path}: ${err.message}` });
+    }
+    for (const cycle of detectCycles(ticketDefs)) {
+        issues.push({ pass: 1, severity: "error", message: `[cycle] dependency cycle: ${cycle}` });
+    }
+    // Pass 2: state validation
+    const ticketIds = new Set(ticketDefs.map((t) => t.id));
+    for (const [id, state] of states) {
+        if (!ticketIds.has(id)) {
+            issues.push({ pass: 2, severity: "error", message: `[state] ticket_state row for unknown ticket: ${id}` });
+        }
+        if (state.status === "done" && !state.completed_at) {
+            issues.push({ pass: 2, severity: "error", message: `[state] done ticket ${id} missing completed_at` });
+        }
+        if (state.status === "done" && !state.evidence && config.behavior.requireValidationEvidenceForDone) {
+            issues.push({ pass: 2, severity: "warn", message: `[state] done ticket ${id} has no evidence` });
+        }
+    }
+    // Pass 3: queue validation
+    const queueRows = buildNextQueue(ticketDefs, states, config.queueLimit);
+    const remaining = ticketDefs.filter((t) => {
+        const s = states.get(t.id);
+        return s?.status !== "done" && s?.status !== "canceled";
+    });
+    const expectedLen = Math.min(config.queueLimit, remaining.length);
+    if (queueRows.length !== expectedLen) {
+        issues.push({ pass: 3, severity: "error", message: `[queue] expected ${expectedLen} rows, got ${queueRows.length}` });
+    }
+    for (let i = 0; i < queueRows.length; i++) {
+        if (queueRows[i].rank !== i + 1) {
+            issues.push({ pass: 3, severity: "error", message: `[queue] rank gap at position ${i + 1}: got ${queueRows[i].rank}` });
+        }
+    }
+    const blockedWithNone = queueRows.filter((r) => r.status === "blocked" && r.blockedBy === "None");
+    for (const r of blockedWithNone) {
+        issues.push({ pass: 3, severity: "error", message: `[queue] ${r.ticket} is blocked but Blocked By is None` });
+    }
+    // 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`" });
+    }
+    else {
+        const doc = readFileSync(progressDocPath, "utf8");
+        const requiredMarkers = [
+            "LLM_NEXT_QUEUE_START", "LLM_NEXT_QUEUE_END",
+            "ACTIVE_TICKET_STATUS_START", "ACTIVE_TICKET_STATUS_END",
+            "BLOCKED_TICKETS_START", "BLOCKED_TICKETS_END",
+            "WORK_LOG_START", "WORK_LOG_END",
+        ];
+        for (const marker of requiredMarkers) {
+            if (!doc.includes(`<!-- ${marker} -->`)) {
+                issues.push({ pass: 4, severity: "error", message: `[doc] missing marker: <!-- ${marker} -->` });
+            }
+        }
+        if (!doc.includes("## LLM_NEXT_QUEUE")) {
+            issues.push({ pass: 4, severity: "error", message: "[doc] missing ## LLM_NEXT_QUEUE section" });
+        }
+    }
+    return issues;
+}
+export function formatValidationIssues(issues) {
+    if (issues.length === 0)
+        return "All validation passes clean.";
+    return issues.map((i) => `  [pass ${i.pass}] [${i.severity}] ${i.message}`).join("\n");
+}