ai-foreman 1.4.0 → 1.6.0

package/dist/ticketPlanning.js

@@ -0,0 +1,287 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { stringify } from "yaml";
+import { loadTicketsConfig, resolveTicketPaths, validateDocsRoot } from "./tickets/config.js";
+import { loadTickets, validateTicketDefs } from "./tickets/ticketLoader.js";
+import { StateDb } from "./tickets/stateDb.js";
+import { detectCycles } from "./tickets/ticketLoader.js";
+import { renderAndWrite } from "./tickets/renderMarkdown.js";
+import { runAllValidation } from "./tickets/validate.js";
+import { normalizeDeliveryConfig, validateDeliveryConfig } from "./tickets/delivery.js";
+import { loadTicketSetupConfig, mergeTicketSetup, saveTicketSetupConfig } from "./tickets/setupConfig.js";
+export const PROPOSAL_START = "RAFI_PROPOSAL_START";
+export const PROPOSAL_END = "RAFI_PROPOSAL_END";
+export function readTicketPlanningContext(projectDir) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    const tickets = loadTickets(paths.tickets);
+    if (tickets.length > 0 && !existsSync(paths.stateDb))
+        throw new Error("tickets exist but the ignored ticket-state database is missing; restore it before planning so completed work is not treated as new");
+    const db = new StateDb(paths.stateDb);
+    try {
+        const states = [...db.getAllStates().values()].map(({ ticket_id, status }) => ({ ticket_id, status }));
+        return {
+            tickets,
+            states,
+            futureWork: db.getFutureWork().map(({ id, summary, disposition, rationale }) => ({ id, summary, disposition, rationale })),
+            existingNext: states.filter((state) => state.status === "next").map((state) => state.ticket_id),
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function ticketPlanningFingerprint(projectDir) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    return ["rafi-config.yaml", relative(projectDir, paths.tickets), relative(projectDir, paths.stateDb), `${relative(projectDir, paths.stateDb)}-wal`, `${relative(projectDir, paths.stateDb)}-shm`, ".tickets/delivery.yaml"]
+        .map((path) => ({ path, sha256: fileHash(join(projectDir, path)) }));
+}
+export function planningFingerprintChanges(projectDir, expected) {
+    return expected.filter((item) => fileHash(join(projectDir, item.path)) !== item.sha256).map((item) => item.path);
+}
+export function extractTicketPlanProposal(output, existingTickets = []) {
+    const start = output.lastIndexOf(PROPOSAL_START);
+    const end = output.lastIndexOf(PROPOSAL_END);
+    if (start < 0 || end <= start)
+        throw new Error(`planner output is missing ${PROPOSAL_START}/${PROPOSAL_END}`);
+    const raw = output.slice(start + PROPOSAL_START.length, end).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`planner proposal is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const issues = validateTicketPlanProposal(parsed, existingTickets);
+    if (issues.length)
+        throw new Error(`invalid planner proposal:\n${issues.map((issue) => `- ${issue}`).join("\n")}`);
+    return parsed;
+}
+export function validateTicketPlanProposal(value, existingTickets = []) {
+    const issues = [];
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return ["proposal must be an object"];
+    const proposal = value;
+    if (proposal.version !== 1)
+        issues.push("version must be 1");
+    for (const field of ["title", "markdown"])
+        if (typeof proposal[field] !== "string" || !proposal[field])
+            issues.push(`${field} must be a non-empty string`);
+    for (const field of ["additions", "edits", "supersessions", "state_changes", "source_reconciliation", "future_work"])
+        if (!Array.isArray(proposal[field]))
+            issues.push(`${field} must be an array`);
+    if (!proposal.next || typeof proposal.next !== "object" || Array.isArray(proposal.next))
+        issues.push("next must be an object");
+    if (issues.length)
+        return issues;
+    const p = proposal;
+    const staged = [...existingTickets];
+    const knownExisting = new Set(existingTickets.map((ticket) => ticket.id));
+    for (const addition of p.additions) {
+        if (!addition || typeof addition !== "object") {
+            issues.push("addition must be a ticket object");
+            continue;
+        }
+        if (knownExisting.has(addition.id) || staged.some((ticket) => ticket.id === addition.id))
+            issues.push(`addition reuses ticket ID ${addition.id}`);
+        staged.push(addition);
+    }
+    for (const edit of p.edits) {
+        if (!edit || typeof edit.id !== "string" || !edit.patch || typeof edit.patch !== "object" || Array.isArray(edit.patch)) {
+            issues.push("edit must contain id and patch");
+            continue;
+        }
+        if (!staged.some((ticket) => ticket.id === edit.id))
+            issues.push(`edit references unknown ticket ${edit.id}`);
+        if ("id" in edit.patch)
+            issues.push(`edit ${edit.id} cannot change a stable ticket ID`);
+        const index = staged.findIndex((ticket) => ticket.id === edit.id);
+        if (index >= 0)
+            staged[index] = { ...staged[index], ...edit.patch, id: edit.id };
+    }
+    const ids = new Set(staged.map((ticket) => ticket.id));
+    for (const link of p.supersessions) {
+        if (!link.reason?.trim() || !link.replaced?.length || !link.replacements?.length)
+            issues.push("each supersession needs replaced, replacements, and reason");
+        for (const id of [...(link.replaced ?? []), ...(link.replacements ?? [])])
+            if (!ids.has(id))
+                issues.push(`supersession references unknown ticket ${id}`);
+    }
+    for (const change of p.state_changes)
+        if (!ids.has(change.id) || !change.reason?.trim())
+            issues.push(`invalid state change for ${change.id}`);
+    for (const item of p.source_reconciliation) {
+        if (!item.source?.trim() || !item.item?.trim())
+            issues.push("source reconciliation needs source and item");
+        if ((item.disposition === "deferred" || item.disposition === "excluded") && !item.reason?.trim())
+            issues.push(`${item.source}:${item.item} ${item.disposition} needs a reason`);
+        for (const id of item.ticket_ids ?? [])
+            if (!ids.has(id))
+                issues.push(`source reconciliation references unknown ticket ${id}`);
+        if (["mapped", "split", "combined"].includes(item.disposition)) {
+            for (const id of item.ticket_ids ?? []) {
+                const ticket = staged.find((candidate) => candidate.id === id);
+                if (ticket && !(ticket.source_refs ?? []).some((ref) => ref.source === item.source && ref.item === item.item)) {
+                    issues.push(`ticket ${id} is missing source_refs provenance for ${item.source}:${item.item}`);
+                }
+            }
+        }
+    }
+    if (!Array.isArray(p.next.ticket_ids) || typeof p.next.replace_existing !== "boolean")
+        issues.push("next needs ticket_ids and replace_existing");
+    else
+        for (const id of p.next.ticket_ids)
+            if (!ids.has(id))
+                issues.push(`next references unknown ticket ${id}`);
+    issues.push(...validateTicketDefs(staged).map((issue) => `${issue.path}: ${issue.message}`));
+    issues.push(...detectCycles(staged).map((cycle) => `dependency cycle: ${cycle}`));
+    if (p.delivery)
+        issues.push(...validateDeliveryConfig(p.delivery, staged).map((issue) => `delivery ${issue.path}: ${issue.message}`));
+    return [...new Set(issues)];
+}
+export function applyApprovedTicketPlan(projectDir, proposal, opts) {
+    const root = resolve(projectDir);
+    const drift = planningFingerprintChanges(root, opts.expectedFingerprint);
+    if (drift.length)
+        throw new Error(`planning inputs changed after proposal generation: ${drift.join(", ")}; refresh the proposal and approve again`);
+    const config = loadTicketsConfig(root);
+    const paths = resolveTicketPaths(config, root);
+    const existing = loadTickets(paths.tickets);
+    if (existing.length > 0 && !existsSync(paths.stateDb))
+        throw new Error("tickets exist but the ignored ticket-state database is missing; restore it before planning so completed work is not treated as new");
+    const proposalIssues = validateTicketPlanProposal(proposal, existing);
+    if (proposalIssues.length)
+        throw new Error(`approved proposal is invalid:\n${proposalIssues.map((issue) => `- ${issue}`).join("\n")}`);
+    const lockPath = join(root, ".tickets", "planning.lock");
+    mkdirSync(dirname(lockPath), { recursive: true });
+    let lock;
+    try {
+        lock = openSync(lockPath, "wx", 0o600);
+    }
+    catch {
+        throw new Error(`another ticket planning apply holds ${lockPath}`);
+    }
+    const lockedDrift = planningFingerprintChanges(root, opts.expectedFingerprint);
+    if (lockedDrift.length) {
+        closeSync(lock);
+        rmSync(lockPath, { force: true });
+        throw new Error(`planning inputs changed while acquiring the apply lock: ${lockedDrift.join(", ")}; refresh the proposal and approve again`);
+    }
+    const docsRoot = validateDocsRoot(root, opts.docsRoot);
+    const stamp = (opts.now ?? new Date()).toISOString().replace(/[:.]/g, "-");
+    const backupDir = join(root, ".tickets", "backups", `ticket-plan-${stamp}-${randomUUID().slice(0, 8)}`);
+    const latestPlan = join(root, docsRoot, "rafi-ticket-plan.md");
+    const historyPlan = join(root, docsRoot, "rafi-ticket-plans", `${stamp}.md`);
+    const deliveryPath = join(root, ".tickets", "delivery.yaml");
+    const configPath = join(root, "rafi-config.yaml");
+    const material = [paths.tickets, paths.stateDb, `${paths.stateDb}-wal`, `${paths.stateDb}-shm`, deliveryPath, configPath, latestPlan, historyPlan, paths.progressDoc, paths.archiveDoc];
+    mkdirSync(backupDir, { recursive: true });
+    const backedUp = [];
+    for (const original of material)
+        if (existsSync(original)) {
+            const backup = join(backupDir, `${backedUp.length}-${original.split(/[\\/]/).pop()}`);
+            copyFileSync(original, backup);
+            backedUp.push({ original, backup });
+        }
+    writeFileSync(join(backupDir, "journal.json"), `${JSON.stringify({ status: "prepared", createdAt: new Date().toISOString(), files: backedUp }, null, 2)}\n`, "utf8");
+    try {
+        const staged = stageTickets(existing, proposal);
+        atomicWrite(paths.tickets, stringify({ tickets: staged }, { lineWidth: 120 }));
+        if (proposal.delivery)
+            atomicWrite(deliveryPath, stringify(normalizeDeliveryConfig(proposal.delivery), { lineWidth: 120 }));
+        if (proposal.build_defaults) {
+            const setup = mergeTicketSetup(loadTicketSetupConfig(root), { build: proposal.build_defaults });
+            saveTicketSetupConfig(root, setup);
+        }
+        mkdirSync(dirname(latestPlan), { recursive: true });
+        mkdirSync(dirname(historyPlan), { recursive: true });
+        atomicWrite(latestPlan, `${proposal.markdown.trimEnd()}\n`);
+        atomicWrite(historyPlan, `${proposal.markdown.trimEnd()}\n`);
+        const db = new StateDb(paths.stateDb);
+        try {
+            const now = new Date().toISOString();
+            db.transaction(() => {
+                const existingNext = [...db.getAllStates().values()].filter((state) => state.status === "next").map((state) => state.ticket_id);
+                if (proposal.next.replace_existing)
+                    for (const id of existingNext)
+                        db.upsertState(id, { status: "planned", updated_by: "rafi tickets plan" }, now);
+                for (const link of proposal.supersessions)
+                    for (const id of link.replaced) {
+                        const current = db.getState(id);
+                        if (current?.status !== "done")
+                            db.upsertState(id, { status: "canceled", last_error: `Superseded: ${link.reason}`, updated_by: "rafi tickets plan" }, now);
+                        db.insertEvent({ timestamp: now, actor: "rafi tickets plan", ticket_id: id, event_type: "superseded", old_status: current?.status ?? "planned", new_status: current?.status === "done" ? "done" : "canceled", summary: link.reason, validation: null, evidence: current?.evidence ?? null, payload_json: JSON.stringify({ replacements: link.replacements }) });
+                    }
+                for (const change of proposal.state_changes) {
+                    const current = db.getState(change.id);
+                    if (current?.status === "done" && change.status !== "done")
+                        throw new Error(`proposal cannot change completed ticket ${change.id} away from done`);
+                    db.upsertState(change.id, { status: change.status, updated_by: "rafi tickets plan" }, now);
+                }
+                for (const id of proposal.next.ticket_ids)
+                    db.upsertState(id, { status: "next", updated_by: "rafi tickets plan" }, now);
+                for (const disposition of proposal.future_work) {
+                    if (!db.getFutureWorkById(disposition.id))
+                        throw new Error(`future work item ${disposition.id} does not exist`);
+                    db.updateFutureWorkDisposition(disposition.id, disposition.disposition);
+                }
+            });
+            const states = db.getAllStates();
+            renderAndWrite({ config, projectDir: root, ticketDefs: staged, states, db });
+            const validation = runAllValidation(config, root, staged, states, db);
+            const errors = validation.filter((issue) => issue.severity === "error");
+            if (errors.length)
+                throw new Error(`post-apply tracker validation failed:\n${errors.map((issue) => `- ${issue.message}`).join("\n")}`);
+        }
+        finally {
+            db.close();
+        }
+        writeFileSync(join(backupDir, "journal.json"), `${JSON.stringify({ status: "committed", committedAt: new Date().toISOString(), files: backedUp }, null, 2)}\n`, "utf8");
+        return { added: proposal.additions.map((ticket) => ticket.id), edited: proposal.edits.map((edit) => edit.id), artifacts: [relative(root, latestPlan), relative(root, historyPlan)], backupDir: relative(root, backupDir) };
+    }
+    catch (err) {
+        for (const original of material)
+            if (existsSync(original) && !backedUp.some((entry) => entry.original === original))
+                rmSync(original);
+        for (const entry of backedUp)
+            copyFileSync(entry.backup, entry.original);
+        writeFileSync(join(backupDir, "journal.json"), `${JSON.stringify({ status: "rolled_back", rolledBackAt: new Date().toISOString(), error: err instanceof Error ? err.message : String(err), files: backedUp }, null, 2)}\n`, "utf8");
+        throw err;
+    }
+    finally {
+        closeSync(lock);
+        rmSync(lockPath, { force: true });
+    }
+}
+function stageTickets(existing, proposal) {
+    const tickets = existing.map((ticket) => ({ ...ticket }));
+    for (const edit of proposal.edits) {
+        const index = tickets.findIndex((ticket) => ticket.id === edit.id);
+        tickets[index] = { ...tickets[index], ...edit.patch, id: edit.id };
+    }
+    tickets.push(...proposal.additions.map((ticket) => ({ ...ticket })));
+    for (const link of proposal.supersessions) {
+        for (const id of link.replaced) {
+            const ticket = tickets.find((candidate) => candidate.id === id);
+            ticket.superseded_by = [...new Set([...(ticket.superseded_by ?? []), ...link.replacements])];
+        }
+        for (const id of link.replacements) {
+            const ticket = tickets.find((candidate) => candidate.id === id);
+            ticket.supersedes = [...new Set([...(ticket.supersedes ?? []), ...link.replaced])];
+        }
+    }
+    return tickets.sort((a, b) => a.order - b.order);
+}
+function atomicWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+function fileHash(path) {
+    if (!existsSync(path))
+        return null;
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}

package/dist/tickets/commands.js

@@ -123,6 +123,22 @@ export function cmdInit(projectDir, opts) {
                     },
                 },
             },
+            source_refs: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["source", "item"],
+                    properties: {
+                        source: { type: "string", minLength: 1 },
+                        item: { type: "string", minLength: 1 },
+                        url: { type: ["string", "null"] },
+                        fingerprint: { type: ["string", "null"] },
+                        note: { type: ["string", "null"] },
+                    },
+                },
+            },
+            superseded_by: { type: "array", items: { type: "string" }, uniqueItems: true },
+            supersedes: { type: "array", items: { type: "string" }, uniqueItems: true },
         },
     };
     writeFileSync(join(ticketsDir, "schema", "tickets.schema.json"), JSON.stringify(ticketSchema, null, 2), "utf8");

package/dist/tickets/delivery.d.ts

@@ -0,0 +1,38 @@
+import type { TicketDef } from "./ticketSchema.js";
+import type { TicketState } from "./stateDb.js";
+import type { TicketBuildCompletionMode, TicketBuildMergeMethod, TicketBuildProvider } from "./setupConfig.js";
+export declare const DELIVERY_FILE = ".tickets/delivery.yaml";
+export type DeliveryBranchMode = "current" | "per-ticket" | "shared";
+export type DeliveryDependencyMode = "combine" | "wait" | "stack";
+export interface DeliveryUnit {
+    id: string;
+    tickets: string[];
+    branch_mode: DeliveryBranchMode;
+    completion?: TicketBuildCompletionMode;
+    provider?: TicketBuildProvider;
+    pr_ready?: boolean;
+    merge_method?: TicketBuildMergeMethod;
+    cleanup?: boolean;
+    depends_on?: string[];
+    dependency_mode?: DeliveryDependencyMode;
+}
+export interface DeliveryConfig {
+    version: 1;
+    units: DeliveryUnit[];
+}
+export interface DeliveryIssue {
+    path: string;
+    message: string;
+}
+export declare function loadDeliveryConfig(projectDir: string): DeliveryConfig | undefined;
+export declare function normalizeDeliveryConfig(raw: unknown): DeliveryConfig;
+export declare function validateDeliveryConfig(raw: unknown, ticketDefs?: TicketDef[]): DeliveryIssue[];
+export interface DeliveryUnitProgress {
+    unit: DeliveryUnit;
+    completed: number;
+    remaining: string[];
+    state: "complete" | "ready" | "waiting" | "resume";
+}
+export declare function deliveryProgress(config: DeliveryConfig, states: Map<string, TicketState>): DeliveryUnitProgress[];
+export declare function formatDeliverySummary(config: DeliveryConfig, states: Map<string, TicketState>): string[];
+export declare function selectDeliveryUnitForRun(config: DeliveryConfig, states: Map<string, TicketState>, skipUnitIds?: readonly string[]): DeliveryUnitProgress | undefined;

package/dist/tickets/delivery.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+export const DELIVERY_FILE = ".tickets/delivery.yaml";
+export function loadDeliveryConfig(projectDir) {
+    const path = join(projectDir, DELIVERY_FILE);
+    if (!existsSync(path))
+        return undefined;
+    const raw = parse(readFileSync(path, "utf8"));
+    const issues = validateDeliveryConfig(raw);
+    if (issues.length > 0) {
+        throw new Error(`${DELIVERY_FILE}:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`);
+    }
+    return normalizeDeliveryConfig(raw);
+}
+export function normalizeDeliveryConfig(raw) {
+    const value = raw;
+    return {
+        version: 1,
+        units: value.units.map((unit) => ({
+            id: String(unit.id),
+            tickets: [...unit.tickets],
+            branch_mode: unit.branch_mode,
+            ...(unit.completion ? { completion: unit.completion } : {}),
+            ...(unit.provider ? { provider: unit.provider } : {}),
+            ...(typeof unit.pr_ready === "boolean" ? { pr_ready: unit.pr_ready } : {}),
+            ...(unit.merge_method ? { merge_method: unit.merge_method } : {}),
+            ...(typeof unit.cleanup === "boolean" ? { cleanup: unit.cleanup } : {}),
+            ...(Array.isArray(unit.depends_on) ? { depends_on: [...unit.depends_on] } : {}),
+            ...(unit.dependency_mode ? { dependency_mode: unit.dependency_mode } : {}),
+        })),
+    };
+}
+export function validateDeliveryConfig(raw, ticketDefs) {
+    const issues = [];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return [{ path: "$", message: "expected an object" }];
+    const value = raw;
+    if (value.version !== undefined && value.version !== 1)
+        issues.push({ path: "version", message: "expected 1" });
+    if (!Array.isArray(value.units))
+        return [...issues, { path: "units", message: "expected an array" }];
+    const unitIds = new Set();
+    const assigned = new Map();
+    const knownTickets = ticketDefs ? new Set(ticketDefs.map((ticket) => ticket.id)) : undefined;
+    for (let index = 0; index < value.units.length; index++) {
+        const path = `units[${index}]`;
+        const unit = value.units[index];
+        if (!unit || typeof unit !== "object" || Array.isArray(unit)) {
+            issues.push({ path, message: "expected an object" });
+            continue;
+        }
+        const u = unit;
+        if (typeof u.id !== "string" || !/^[A-Za-z][A-Za-z0-9-_]*$/.test(u.id))
+            issues.push({ path: `${path}.id`, message: "expected a stable identifier" });
+        else if (unitIds.has(u.id))
+            issues.push({ path: `${path}.id`, message: `duplicate unit ID: ${u.id}` });
+        else
+            unitIds.add(u.id);
+        if (!Array.isArray(u.tickets) || u.tickets.length === 0 || !u.tickets.every((id) => typeof id === "string" && id.length > 0)) {
+            issues.push({ path: `${path}.tickets`, message: "expected a non-empty ticket ID array" });
+        }
+        else {
+            for (const id of u.tickets) {
+                if (knownTickets && !knownTickets.has(id))
+                    issues.push({ path: `${path}.tickets`, message: `unknown ticket: ${id}` });
+                const prior = assigned.get(id);
+                if (prior)
+                    issues.push({ path: `${path}.tickets`, message: `${id} is already assigned to ${prior}` });
+                else
+                    assigned.set(id, typeof u.id === "string" ? u.id : path);
+            }
+        }
+        enumValue(issues, `${path}.branch_mode`, u.branch_mode, ["current", "per-ticket", "shared"], true);
+        enumValue(issues, `${path}.completion`, u.completion, ["pr", "auto-merge", "direct-merge", "none"]);
+        enumValue(issues, `${path}.provider`, u.provider, ["auto", "github", "gitlab", "local"]);
+        enumValue(issues, `${path}.merge_method`, u.merge_method, ["squash", "merge", "rebase"]);
+        enumValue(issues, `${path}.dependency_mode`, u.dependency_mode, ["combine", "wait", "stack"]);
+        for (const field of ["pr_ready", "cleanup"]) {
+            if (u[field] !== undefined && typeof u[field] !== "boolean")
+                issues.push({ path: `${path}.${field}`, message: "expected a boolean" });
+        }
+        if (u.depends_on !== undefined && (!Array.isArray(u.depends_on) || !u.depends_on.every((id) => typeof id === "string"))) {
+            issues.push({ path: `${path}.depends_on`, message: "expected a unit ID array" });
+        }
+    }
+    const units = value.units.filter((unit) => Boolean(unit && typeof unit === "object" && !Array.isArray(unit)));
+    for (const unit of units) {
+        for (const dep of Array.isArray(unit.depends_on) ? unit.depends_on : []) {
+            if (!unitIds.has(String(dep)))
+                issues.push({ path: `units[${String(unit.id)}].depends_on`, message: `unknown unit: ${String(dep)}` });
+            if (dep === unit.id)
+                issues.push({ path: `units[${String(unit.id)}].depends_on`, message: "unit cannot depend on itself" });
+        }
+    }
+    for (const cycle of deliveryCycles(units))
+        issues.push({ path: "units", message: `dependency cycle: ${cycle}` });
+    return issues;
+}
+function enumValue(issues, path, value, allowed, required = false) {
+    if (value === undefined && !required)
+        return;
+    if (typeof value !== "string" || !allowed.includes(value))
+        issues.push({ path, message: `expected one of: ${allowed.join(", ")}` });
+}
+function deliveryCycles(units) {
+    const deps = new Map(units.map((unit) => [String(unit.id), (Array.isArray(unit.depends_on) ? unit.depends_on : []).map(String)]));
+    const visited = new Set();
+    const stack = new Set();
+    const cycles = [];
+    const walk = (id, path) => {
+        if (stack.has(id)) {
+            cycles.push([...path.slice(path.indexOf(id)), id].join(" -> "));
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        stack.add(id);
+        for (const dep of deps.get(id) ?? [])
+            if (deps.has(dep))
+                walk(dep, [...path, id]);
+        stack.delete(id);
+    };
+    for (const id of deps.keys())
+        walk(id, []);
+    return cycles;
+}
+export function deliveryProgress(config, states) {
+    const completedUnits = new Set(config.units.filter((unit) => unit.tickets.every((id) => ["done", "canceled"].includes(states.get(id)?.status ?? "planned"))).map((unit) => unit.id));
+    const out = [];
+    for (const unit of config.units) {
+        const remaining = unit.tickets.filter((id) => !["done", "canceled"].includes(states.get(id)?.status ?? "planned"));
+        const started = unit.tickets.some((id) => ["in_progress", "blocked", "done"].includes(states.get(id)?.status ?? "planned"));
+        const waiting = (unit.depends_on ?? []).some((id) => !completedUnits.has(id));
+        out.push({
+            unit,
+            completed: unit.tickets.length - remaining.length,
+            remaining,
+            state: remaining.length === 0 ? "complete" : waiting ? "waiting" : started ? "resume" : "ready",
+        });
+    }
+    return out;
+}
+export function formatDeliverySummary(config, states) {
+    return deliveryProgress(config, states).map(({ unit, completed, remaining, state }) => `${unit.id}: ${completed}/${unit.tickets.length} complete; ${remaining.length} remaining; ${unit.branch_mode}; ${unit.completion ?? "repository default"}; ${state}${(unit.depends_on ?? []).length ? `; depends on ${(unit.depends_on ?? []).join(", ")}` : ""}`);
+}
+export function selectDeliveryUnitForRun(config, states, skipUnitIds = []) {
+    const skipped = new Set(skipUnitIds);
+    const progress = deliveryProgress(config, states).filter((item) => !skipped.has(item.unit.id));
+    return progress.find((item) => item.state === "resume") ?? progress.find((item) => item.state === "ready");
+}

package/dist/tickets/importer.js

@@ -348,6 +348,10 @@ function importedItemToTicket(item, id, order, existing) {
             key: item.key ?? null,
             url: item.url ?? null,
         }),
+        source_refs: [
+            ...(existing?.source_refs ?? []).filter((ref) => !(ref.source === item.provider && ref.item === item.providerId)),
+            { source: item.provider, item: item.providerId, url: item.url ?? null },
+        ],
     };
 }
 function buildImportedNotes(item) {

package/dist/tickets/renderMarkdown.js

@@ -2,6 +2,7 @@ import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } from "
 import { dirname, join } from "node:path";
 import { DateTime } from "luxon";
 import { buildNextQueue, buildActiveStatusRows } from "./queue.js";
+import { formatDeliverySummary, loadDeliveryConfig } from "./delivery.js";
 // ── Table helpers ─────────────────────────────────────────────────────────────
 function esc(v) {
     return v.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
@@ -90,6 +91,14 @@ export function renderProgressDoc(input) {
         ["Remaining Tickets", String(queueRows.length > 0 ? "≥" + queueRows.length : "0")],
     ])));
     lines.push("");
+    // Delivery units are optional; repositories without delivery.yaml retain legacy defaults.
+    const delivery = loadDeliveryConfig(projectDir);
+    if (delivery) {
+        lines.push("## Delivery Units");
+        const deliveryRows = formatDeliverySummary(delivery, states);
+        lines.push(section("DELIVERY_UNITS", deliveryRows.length > 0 ? deliveryRows.map((row) => `- ${row}`).join("\n") : "_No delivery units configured._"));
+        lines.push("");
+    }
     // Rules
     if (config.rendering.includeRulesInProgressDoc) {
         lines.push(rulesContent);

package/dist/tickets/setupConfig.d.ts

@@ -20,6 +20,9 @@ export type TicketSourceConfig = {
     email_env: string;
     token_env: string;
     jql: string;
+} | {
+    type: "url";
+    url: string;
 };
 export interface TicketPopulateSetupConfig {
     source_handling: "saved" | "prompt" | "manual";
@@ -65,9 +68,20 @@ export declare function mergeTicketSetup(current: TicketsSetupConfig | undefined
     build: Partial<TicketBuildSetupConfig>;
 }>): TicketsSetupConfig;
 export declare function localSourcePaths(setup: TicketsSetupConfig | undefined): string[];
+/**
+ * Create records planning hints separately from completed ticket setup.  Use
+ * them only as a setup prefill so `tickets.sources` remains the source of
+ * truth once the user has configured ticket ingestion.
+ */
+export declare function configuredPlanningSources(projectDir: string): string[];
 export declare function externalSources(setup: TicketsSetupConfig | undefined): Extract<TicketSourceConfig, {
     type: "linear" | "jira";
 }>[];
+export declare function urlSources(setup: TicketsSetupConfig | undefined): Extract<TicketSourceConfig, {
+    type: "url";
+}>[];
+export declare function normalizedSourceKey(source: TicketSourceConfig): string;
+export declare function dedupeTicketSources(sources: TicketSourceConfig[]): TicketSourceConfig[];
 export declare function configuredDocsRoot(projectDir: string): string | undefined;
 export declare function configuredAppName(projectDir: string): string | undefined;
 export declare function configuredHarnessTargets(projectDir: string): HarnessTarget[] | undefined;

package/dist/tickets/setupConfig.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { parse, stringify } from "yaml";
 import { loadDefaults } from "special-agents";
 export const RAFI_CONFIG_FILE = "rafi-config.yaml";
-const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker"];
+const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker", "uninstaller"];
 const SKILL_NAMES = [
     "better-sqlite3-rebuild",
     "grill-me",
@@ -106,9 +106,49 @@ export function localSourcePaths(setup) {
         .filter((source) => source.type === "local")
         .flatMap((source) => source.paths));
 }
+/**
+ * Create records planning hints separately from completed ticket setup.  Use
+ * them only as a setup prefill so `tickets.sources` remains the source of
+ * truth once the user has configured ticket ingestion.
+ */
+export function configuredPlanningSources(projectDir) {
+    const raw = loadRafiConfigObject(projectDir);
+    const planning = raw?.planning;
+    if (!Array.isArray(planning?.sources))
+        return [];
+    return unique(planning.sources.filter((source) => typeof source === "string" && source.trim().length > 0).map((source) => source.trim()));
+}
 export function externalSources(setup) {
     return (setup?.sources ?? []).filter((source) => source.type === "linear" || source.type === "jira");
 }
+export function urlSources(setup) {
+    return (setup?.sources ?? []).filter((source) => source.type === "url");
+}
+export function normalizedSourceKey(source) {
+    if (source.type === "local")
+        return `local:${unique(source.paths.map((path) => path.trim())).sort().join("|")}`;
+    if (source.type === "url") {
+        const url = new URL(source.url);
+        url.hash = "";
+        url.hostname = url.hostname.toLowerCase();
+        if ((url.protocol === "https:" && url.port === "443") || (url.protocol === "http:" && url.port === "80"))
+            url.port = "";
+        return `url:${url.toString()}`;
+    }
+    if (source.type === "linear")
+        return `linear:${source.api_key_env}:${source.team_key ?? ""}:${source.filter ?? ""}`;
+    return `jira:${source.site.replace(/\/+$/, "").toLowerCase()}:${source.jql}`;
+}
+export function dedupeTicketSources(sources) {
+    const seen = new Set();
+    return sources.filter((source) => {
+        const key = normalizedSourceKey(source);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
 export function configuredDocsRoot(projectDir) {
     const raw = loadRafiConfigObject(projectDir);
     const docs = raw?.docs;
@@ -259,7 +299,24 @@ function normalizeSource(value, label) {
             jql,
         };
     }
-    throw new Error(`${label}.type: expected local, linear, or jira`);
+    if (raw.type === "url") {
+        const url = stringField(raw.url);
+        if (!url)
+            throw new Error(`${label}.url: expected a public HTTP(S) URL`);
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new Error(`${label}.url: expected a valid URL`);
+        }
+        if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || parsed.username || parsed.password) {
+            throw new Error(`${label}.url: expected HTTP(S) without embedded credentials`);
+        }
+        parsed.hash = "";
+        return { type: "url", url: parsed.toString() };
+    }
+    throw new Error(`${label}.type: expected local, linear, jira, or url`);
 }
 function normalizePopulate(value, label) {
     const raw = objectOrEmpty(value, label);