ai-foreman 1.6.2 → 1.7.0

package/dist/ticketPopulation.js

@@ -0,0 +1,205 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { stringify } from "yaml";
+import { WorkflowDb } from "./workflowDb.js";
+import { cmdRender, cmdValidate } from "./tickets/commands.js";
+import { validateTicketDefs } from "./tickets/ticketLoader.js";
+import { normalizeDeliveryConfig, validateDeliveryConfig } from "./tickets/delivery.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { StateDb } from "./tickets/stateDb.js";
+export const TICKET_POPULATION_PROPOSAL_START = "RAFI_TICKET_POPULATION_PROPOSAL_START";
+export const TICKET_POPULATION_PROPOSAL_END = "RAFI_TICKET_POPULATION_PROPOSAL_END";
+export function extractTicketPopulationProposal(output) {
+    const start = output.lastIndexOf(TICKET_POPULATION_PROPOSAL_START);
+    const end = output.lastIndexOf(TICKET_POPULATION_PROPOSAL_END);
+    if (start < 0 || end <= start)
+        throw new Error(`ticket-maker output is missing ${TICKET_POPULATION_PROPOSAL_START}/${TICKET_POPULATION_PROPOSAL_END}`);
+    const raw = output.slice(start + TICKET_POPULATION_PROPOSAL_START.length, end).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`ticket-maker proposal is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function validateTicketPopulationProposal(proposal, plan, existing) {
+    const issues = [];
+    if (proposal.version !== 1 || proposal.plan_id !== plan.plan_id || proposal.revision !== plan.revision)
+        issues.push("proposal plan identity does not match the approved structured plan");
+    const planned = new Set(plan.slices.map((slice) => slice.slice_ref));
+    const mapped = new Set();
+    for (const ticket of proposal.tickets) {
+        if (!planned.has(ticket.slice_ref))
+            issues.push(`unknown slice mapping ${ticket.slice_ref}`);
+        if (mapped.has(ticket.slice_ref))
+            issues.push(`duplicate slice mapping ${ticket.slice_ref}`);
+        else
+            mapped.add(ticket.slice_ref);
+        for (const dep of ticket.depends_on)
+            if (!planned.has(dep))
+                issues.push(`slice ${ticket.slice_ref} depends on unknown slice ${dep}`);
+    }
+    for (const ref of planned)
+        if (!mapped.has(ref))
+            issues.push(`missing ticket mapping for slice ${ref}`);
+    const expectedRetirements = existing.filter((ticket) => ticket.plan_ref?.plan_id === plan.plan_id && !planned.has(ticket.plan_ref.slice_ref) && ticket.plan_ref.revision < plan.revision).map((ticket) => ticket.id).sort();
+    if (JSON.stringify([...proposal.retirements].sort()) !== JSON.stringify(expectedRetirements))
+        issues.push(`retirements must exactly match removed populated slices: ${expectedRetirements.join(",") || "none"}`);
+    return issues;
+}
+export function materializeTicketPopulation(proposal, plan, existing) {
+    const issues = validateTicketPopulationProposal(proposal, plan, existing);
+    if (issues.length)
+        throw new Error(issues.join("; "));
+    const byPlanSlice = new Map(existing.filter((ticket) => ticket.plan_ref).map((ticket) => [`${ticket.plan_ref.plan_id}:${ticket.plan_ref.slice_ref}`, ticket]));
+    const reserved = new Set(existing.map((ticket) => ticket.id));
+    const sliceToTicket = new Map();
+    for (const slice of proposal.tickets) {
+        const retained = byPlanSlice.get(`${plan.plan_id}:${slice.slice_ref}`);
+        const id = retained?.id ?? allocateTicketId(reserved);
+        reserved.add(id);
+        sliceToTicket.set(slice.slice_ref, id);
+    }
+    const materialized = proposal.tickets.map((slice, index) => {
+        const retained = byPlanSlice.get(`${plan.plan_id}:${slice.slice_ref}`);
+        return {
+            ...(retained ?? {}), id: sliceToTicket.get(slice.slice_ref), order: retained?.order ?? nextOrder(existing, index),
+            title: slice.title, area: slice.area, priority: slice.priority, size: slice.size, risk: slice.risk,
+            depends_on: slice.depends_on.map((ref) => sliceToTicket.get(ref)), summary: slice.summary,
+            acceptance: [...slice.acceptance], required_tests: [...slice.required_tests], likely_files: [...slice.likely_files],
+            rollback: slice.rollback, notes: slice.notes, plan_ref: { plan_id: plan.plan_id, revision: plan.revision, slice_ref: slice.slice_ref },
+        };
+    });
+    const ownedIds = new Set(materialized.map((ticket) => ticket.id));
+    const tickets = [...existing.filter((ticket) => !ownedIds.has(ticket.id)), ...materialized].sort((a, b) => a.order - b.order);
+    const delivery = normalizeDeliveryConfig({
+        version: 1, plan: { plan_id: plan.plan_id, revision: plan.revision },
+        units: plan.delivery_units.map((unit) => ({
+            id: unit.id, tickets: unit.slice_refs.map((ref) => sliceToTicket.get(ref)), branch_mode: unit.branch_mode,
+            completion: unit.completion, provider: unit.provider, pr_ready: unit.pr_ready, merge_method: unit.merge_method,
+            cleanup: unit.cleanup, depends_on: unit.depends_on, dependency_mode: unit.dependency_mode,
+        })),
+        stacks: plan.stacks.map((stack) => ({ id: stack.stack_id, name: stack.name, units: stack.units, status: "planned" })),
+    });
+    const validation = [...validateTicketDefs(tickets).map((issue) => `${issue.path}: ${issue.message}`), ...validateDeliveryConfig(delivery, tickets).map((issue) => `${issue.path}: ${issue.message}`)];
+    if (validation.length)
+        throw new Error(`materialized ticket population is invalid:\n${validation.map((issue) => `- ${issue}`).join("\n")}`);
+    return { tickets, delivery, retirements: [...proposal.retirements], sliceToTicket };
+}
+export function authorizeTicketRetirements(retirements, input) {
+    if (!retirements.length)
+        return;
+    if (input.computerRun) {
+        const authorized = [...(input.authorizedIds ?? [])].sort();
+        if (JSON.stringify(authorized) !== JSON.stringify([...retirements].sort()))
+            throw new Error(`computer-run retirement requires exact authorized ticket IDs: ${retirements.join(",")}`);
+    }
+    else if (!input.interactiveConfirmed)
+        throw new Error(`retirement confirmation required for: ${retirements.join(",")}`);
+}
+export function applyTicketPopulation(projectDir, materialized, runId, now = new Date()) {
+    const root = resolve(projectDir);
+    const config = loadTicketsConfig(root);
+    const paths = resolveTicketPaths(config, root);
+    const workflow = new WorkflowDb(root);
+    let actualRunId = runId;
+    let lease;
+    try {
+        if (!actualRunId)
+            actualRunId = workflow.createRun({ kind: "ticket-populate", originalWork: { tickets: materialized.tickets.map((ticket) => ticket.id) }, state: {} }, now).runId;
+        lease = workflow.acquireLease(actualRunId, undefined, now);
+        const deliveryPath = join(root, ".tickets", "delivery.yaml");
+        const stage = join(root, ".rafi", "staging", randomUUID());
+        mkdirSync(stage, { recursive: true });
+        const stagedTickets = join(stage, "tickets.yaml");
+        const stagedDelivery = join(stage, "delivery.yaml");
+        const tx = workflow.beginPublication(actualRunId, { files: [{ staged: stagedTickets, target: paths.tickets }, { staged: stagedDelivery, target: deliveryPath }], stage }, {
+            [paths.tickets]: fileDigest(paths.tickets), [deliveryPath]: fileDigest(deliveryPath),
+        }, now);
+        fsyncWrite(stagedTickets, stringify({ tickets: materialized.tickets }, { lineWidth: 120 }));
+        fsyncWrite(stagedDelivery, stringify(materialized.delivery, { lineWidth: 120 }));
+        workflow.updatePublication(tx.transactionId, "staged", now);
+        const db = new StateDb(paths.stateDb);
+        try {
+            db.transaction(() => {
+                const at = now.toISOString();
+                for (const ticket of materialized.tickets)
+                    if (!db.getState(ticket.id))
+                        db.upsertState(ticket.id, { status: "planned", updated_by: "rafi tickets populate" }, at);
+                for (const id of materialized.retirements) {
+                    const prior = db.getState(id);
+                    if (prior?.status === "done")
+                        continue;
+                    db.upsertState(id, { status: "obsolete", completed_at: at, updated_by: "rafi tickets populate" }, at);
+                    db.insertEvent({ timestamp: at, actor: "rafi tickets populate", ticket_id: id, event_type: "obsolete", old_status: prior?.status ?? "planned", new_status: "obsolete", summary: "Removed by approved plan revision", validation: null, evidence: null, payload_json: JSON.stringify({ runId: actualRunId }) });
+                }
+            });
+        }
+        finally {
+            db.close();
+        }
+        workflow.updatePublication(tx.transactionId, "tracker_committed", now);
+        publishStaged(stagedTickets, paths.tickets);
+        publishStaged(stagedDelivery, deliveryPath);
+        workflow.updatePublication(tx.transactionId, "published", now);
+        cmdRender(root);
+        const validation = cmdValidate(root);
+        if (!validation.clean)
+            throw new Error(`published ticket population failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`);
+        workflow.updatePublication(tx.transactionId, "committed", now);
+        workflow.transition(actualRunId, { status: "completed", checkpoint: "population-committed", remainingWork: {}, state: { transactionId: tx.transactionId } }, now);
+        rmSync(stage, { recursive: true, force: true });
+        return { runId: actualRunId, transactionId: tx.transactionId };
+    }
+    finally {
+        if (lease)
+            workflow.releaseLease(lease, now);
+        workflow.close();
+    }
+}
+/** Startup recovery deterministically finishes publications after tracker commit. */
+export function recoverTicketPublications(projectDir) {
+    const workflow = new WorkflowDb(projectDir);
+    const recovered = [];
+    try {
+        for (const tx of workflow.incompletePublications()) {
+            const intent = tx.intent;
+            if (["tracker_committed", "published"].includes(tx.status)) {
+                if (tx.status === "tracker_committed")
+                    for (const file of intent.files)
+                        if (existsSync(file.staged))
+                            publishStaged(file.staged, file.target);
+                workflow.updatePublication(tx.transactionId, "committed");
+                recovered.push(tx.transactionId);
+                rmSync(intent.stage, { recursive: true, force: true });
+            }
+            else {
+                rmSync(intent.stage, { recursive: true, force: true });
+                workflow.updatePublication(tx.transactionId, "rolled_back");
+                recovered.push(tx.transactionId);
+            }
+        }
+        return recovered;
+    }
+    finally {
+        workflow.close();
+    }
+}
+function allocateTicketId(reserved) { let n = 1; while (reserved.has(`T${String(n).padStart(3, "0")}`))
+    n++; return `T${String(n).padStart(3, "0")}`; }
+function nextOrder(existing, offset) { return Math.max(-1, ...existing.map((ticket) => ticket.order)) + 1 + offset; }
+function fileDigest(path) { return existsSync(path) ? createHash("sha256").update(readFileSync(path)).digest("hex") : null; }
+function fsyncWrite(path, value) { mkdirSync(dirname(path), { recursive: true }); const fd = openSync(path, "wx", 0o600); try {
+    writeFileSync(fd, value);
+    fsyncSync(fd);
+}
+finally {
+    closeSync(fd);
+} }
+function publishStaged(staged, target) { mkdirSync(dirname(target), { recursive: true }); const temp = `${target}.${process.pid}.${randomUUID()}.tmp`; copyFileSync(staged, temp); const fd = openSync(temp, "r"); try {
+    fsyncSync(fd);
+}
+finally {
+    closeSync(fd);
+} renameSync(temp, target); }

package/dist/tickets/blockers.d.ts

@@ -1,5 +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 type DisplayStatus = "next" | "in_progress" | "blocked" | "done" | "canceled" | "obsolete";
 export declare function computeDisplayStatus(storedStatus: string, blockedBy: string[]): DisplayStatus;

package/dist/tickets/blockers.js

@@ -14,6 +14,8 @@ export function computeDisplayStatus(storedStatus, blockedBy) {
         return "done";
     if (storedStatus === "canceled")
         return "canceled";
+    if (storedStatus === "obsolete")
+        return "obsolete";
     if (storedStatus === "in_progress")
         return "in_progress";
     if (blockedBy.length > 0 || storedStatus === "blocked")

package/dist/tickets/commands.d.ts

@@ -89,6 +89,7 @@ export interface ValidateResult {
 }
 export declare function cmdValidate(projectDir: string): ValidateResult;
 export declare function cmdQueue(projectDir: string, limit?: number): import("./queue.js").QueueRow[];
+export declare function cmdStackQueue(projectDir: string, refresh?: boolean): string[];
 export declare function cmdImplementationQueue(projectDir: string): import("./queue.js").QueueRow[];
 export declare function cmdArchive(projectDir: string, _opts: {
     olderThanDays?: number;

package/dist/tickets/commands.js

@@ -7,7 +7,10 @@ import { StateDb } from "./stateDb.js";
 import { nowTimestamp, logEvent } from "./events.js";
 import { renderAndWrite, renderTrackerRules } from "./renderMarkdown.js";
 import { runAllValidation } from "./validate.js";
-import { buildNextQueue } from "./queue.js";
+import { buildNextQueue, formatStackAwareQueue } from "./queue.js";
+import { loadDeliveryConfig, saveDeliveryConfig } from "./delivery.js";
+import { checkGitHubPrMerged } from "../branch/github.js";
+import { checkGitLabMrMerged } from "../branch/gitlab.js";
 import { cmdReviewRecommendations } from "./recommendations.js";
 export function openContext(projectDir) {
     const config = loadTicketsConfig(projectDir);
@@ -470,6 +473,32 @@ export function cmdQueue(projectDir, limit) {
         return buildNextQueue(ctx.tickets, states, limit ?? ctx.config.viewLimit);
     });
 }
+export function cmdStackQueue(projectDir, refresh = false) {
+    return withContext(projectDir, (ctx) => {
+        let delivery = loadDeliveryConfig(projectDir);
+        if (delivery && refresh) {
+            const unitById = new Map(delivery.units.map((unit) => [unit.id, unit]));
+            delivery = { ...delivery, stacks: (delivery.stacks ?? []).map((stack) => {
+                    const links = stack.review_links ?? [];
+                    const providers = new Set(stack.units.map((id) => unitById.get(id)?.provider).filter((value) => value === "github" || value === "gitlab"));
+                    if (!links.length || providers.size !== 1)
+                        return { ...stack, remote_stale: true };
+                    const provider = [...providers][0];
+                    const checks = links.map((link) => provider === "gitlab" ? checkGitLabMrMerged(projectDir, link) : checkGitHubPrMerged(projectDir, link));
+                    if (checks.some((check) => !check.ok))
+                        return { ...stack, remote_stale: true };
+                    return {
+                        ...stack,
+                        status: checks.every((check) => check.ok && check.merged) ? "merged" : "awaiting_review",
+                        review_links: checks.map((check, index) => check.ok ? (check.url ?? links[index]) : links[index]),
+                        remote_checked_at: new Date().toISOString(), remote_stale: false,
+                    };
+                }) };
+            saveDeliveryConfig(projectDir, delivery);
+        }
+        return formatStackAwareQueue(ctx.tickets, ctx.db.getAllStates(), delivery);
+    });
+}
 export function cmdImplementationQueue(projectDir) {
     return withContext(projectDir, (ctx) => {
         const states = ctx.db.getAllStates();

package/dist/tickets/delivery.d.ts

@@ -16,17 +16,45 @@ export interface DeliveryUnit {
     depends_on?: string[];
     dependency_mode?: DeliveryDependencyMode;
 }
+export type StackDeliveryState = "planned" | "in_progress" | "partial" | "blocked" | "awaiting_review" | "merged";
+export interface DeliveryStack {
+    id: string;
+    name: string;
+    /** Straight root-to-tip chain of delivery unit IDs. */
+    units: string[];
+    status?: StackDeliveryState;
+    completed_prefix?: string[];
+    next_ticket?: string;
+    review_links?: string[];
+    remote_checked_at?: string;
+    remote_stale?: boolean;
+    /** Stable PR-node branch identities retained for partial-stack recovery. */
+    published_branches?: Record<string, string>;
+}
 export interface DeliveryConfig {
     version: 1;
+    plan?: {
+        plan_id: string;
+        revision: number;
+    };
     units: DeliveryUnit[];
+    stacks?: DeliveryStack[];
 }
 export interface DeliveryIssue {
     path: string;
     message: string;
 }
 export declare function loadDeliveryConfig(projectDir: string): DeliveryConfig | undefined;
+export declare function saveDeliveryConfig(projectDir: string, config: DeliveryConfig): void;
 export declare function normalizeDeliveryConfig(raw: unknown): DeliveryConfig;
 export declare function validateDeliveryConfig(raw: unknown, ticketDefs?: TicketDef[]): DeliveryIssue[];
+export interface NormalizedStackNode {
+    stackId: string;
+    unitId: string;
+    ticketId: string;
+    depth: number;
+}
+export declare function normalizeStackNodes(stack: DeliveryStack, units: DeliveryUnit[], ticketDefs?: TicketDef[]): NormalizedStackNode[];
 export interface DeliveryUnitProgress {
     unit: DeliveryUnit;
     completed: number;
@@ -36,3 +64,11 @@ export interface DeliveryUnitProgress {
 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;
+export interface StackBatchSelection {
+    stacks: DeliveryStack[];
+    tickets: string[];
+    error?: string;
+}
+/** Complete preflight simulation for exact `--stacks N` selection. */
+export declare function selectStacksForRun(config: DeliveryConfig, ticketDefs: TicketDef[], states: Map<string, TicketState>, count: number): StackBatchSelection;
+export declare function updateStackDeliveryState(projectDir: string, stackIds: readonly string[], status: StackDeliveryState, patch?: Partial<DeliveryStack>): DeliveryConfig;

package/dist/tickets/delivery.js

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { parse } from "yaml";
+import { parse, stringify } from "yaml";
+import { randomUUID } from "node:crypto";
 export const DELIVERY_FILE = ".tickets/delivery.yaml";
 export function loadDeliveryConfig(projectDir) {
     const path = join(projectDir, DELIVERY_FILE);
@@ -13,10 +14,20 @@ export function loadDeliveryConfig(projectDir) {
     }
     return normalizeDeliveryConfig(raw);
 }
+export function saveDeliveryConfig(projectDir, config) {
+    const issues = validateDeliveryConfig(config);
+    if (issues.length)
+        throw new Error(`${DELIVERY_FILE}: ${issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+    const target = join(projectDir, DELIVERY_FILE);
+    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, stringify(config, { lineWidth: 120 }), "utf8");
+    renameSync(temp, target);
+}
 export function normalizeDeliveryConfig(raw) {
     const value = raw;
     return {
         version: 1,
+        ...(value.plan && typeof value.plan === "object" ? { plan: { plan_id: String(value.plan.plan_id), revision: Number(value.plan.revision) } } : {}),
         units: value.units.map((unit) => ({
             id: String(unit.id),
             tickets: [...unit.tickets],
@@ -29,6 +40,16 @@ export function normalizeDeliveryConfig(raw) {
             ...(Array.isArray(unit.depends_on) ? { depends_on: [...unit.depends_on] } : {}),
             ...(unit.dependency_mode ? { dependency_mode: unit.dependency_mode } : {}),
         })),
+        ...(Array.isArray(value.stacks) ? { stacks: value.stacks.map((stack) => ({
+                id: String(stack.id), name: String(stack.name), units: [...stack.units],
+                ...(stack.status ? { status: stack.status } : {}),
+                ...(Array.isArray(stack.completed_prefix) ? { completed_prefix: [...stack.completed_prefix] } : {}),
+                ...(stack.next_ticket ? { next_ticket: String(stack.next_ticket) } : {}),
+                ...(Array.isArray(stack.review_links) ? { review_links: [...stack.review_links] } : {}),
+                ...(stack.remote_checked_at ? { remote_checked_at: String(stack.remote_checked_at) } : {}),
+                ...(typeof stack.remote_stale === "boolean" ? { remote_stale: stack.remote_stale } : {}),
+                ...(stack.published_branches && typeof stack.published_branches === "object" ? { published_branches: { ...stack.published_branches } } : {}),
+            })) } : {}),
     };
 }
 export function validateDeliveryConfig(raw, ticketDefs) {
@@ -38,6 +59,11 @@ export function validateDeliveryConfig(raw, ticketDefs) {
     const value = raw;
     if (value.version !== undefined && value.version !== 1)
         issues.push({ path: "version", message: "expected 1" });
+    if (value.plan !== undefined) {
+        const plan = value.plan;
+        if (!plan || typeof plan !== "object" || typeof plan.plan_id !== "string" || !Number.isInteger(plan.revision) || Number(plan.revision) < 1)
+            issues.push({ path: "plan", message: "expected plan_id and positive integer revision" });
+    }
     if (!Array.isArray(value.units))
         return [...issues, { path: "units", message: "expected an array" }];
     const unitIds = new Set();
@@ -95,6 +121,113 @@ export function validateDeliveryConfig(raw, ticketDefs) {
     }
     for (const cycle of deliveryCycles(units))
         issues.push({ path: "units", message: `dependency cycle: ${cycle}` });
+    issues.push(...validateDeliveryStacks(value.stacks, units, ticketDefs, value.plan));
+    return issues;
+}
+export function normalizeStackNodes(stack, units, ticketDefs = []) {
+    const order = new Map(ticketDefs.map((ticket) => [ticket.id, ticket.order]));
+    const byId = new Map(units.map((unit) => [unit.id, unit]));
+    const nodes = [];
+    for (const unitId of stack.units) {
+        const unit = byId.get(unitId);
+        if (!unit)
+            continue;
+        const tickets = [...unit.tickets].sort((a, b) => (order.get(a) ?? Number.MAX_SAFE_INTEGER) - (order.get(b) ?? Number.MAX_SAFE_INTEGER));
+        if (unit.branch_mode === "shared")
+            nodes.push({ stackId: stack.id, unitId, ticketId: tickets.join("+"), depth: nodes.length + 1 });
+        else
+            for (const ticketId of tickets)
+                nodes.push({ stackId: stack.id, unitId, ticketId, depth: nodes.length + 1 });
+    }
+    return nodes;
+}
+function validateDeliveryStacks(raw, units, ticketDefs, plan) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return [{ path: "stacks", message: "expected an array" }];
+    const issues = [];
+    const byId = new Map(units.map((unit) => [String(unit.id), unit]));
+    const stackIds = new Set();
+    const assigned = new Set();
+    const ticketById = new Map((ticketDefs ?? []).map((ticket) => [ticket.id, ticket]));
+    const queueIndex = new Map((ticketDefs ?? []).slice().sort((a, b) => a.order - b.order).map((ticket, index) => [ticket.id, index]));
+    const stackedTicketIds = new Set();
+    for (let index = 0; index < raw.length; index++) {
+        const stack = raw[index];
+        const path = `stacks[${index}]`;
+        if (!stack || typeof stack !== "object" || typeof stack.id !== "string" || !stack.id) {
+            issues.push({ path: `${path}.id`, message: "expected stable stack ID" });
+            continue;
+        }
+        if (stackIds.has(stack.id))
+            issues.push({ path: `${path}.id`, message: `duplicate stack ID ${stack.id}` });
+        else
+            stackIds.add(stack.id);
+        if (typeof stack.name !== "string" || !stack.name.trim())
+            issues.push({ path: `${path}.name`, message: "expected a name" });
+        if (!Array.isArray(stack.units) || stack.units.length === 0 || !stack.units.every((id) => typeof id === "string")) {
+            issues.push({ path: `${path}.units`, message: "expected ordered unit IDs" });
+            continue;
+        }
+        for (const unitId of stack.units) {
+            const unit = byId.get(unitId);
+            if (!unit) {
+                issues.push({ path: `${path}.units`, message: `unknown unit ${unitId}` });
+                continue;
+            }
+            if (assigned.has(unitId))
+                issues.push({ path: `${path}.units`, message: `unit ${unitId} belongs to more than one stack` });
+            else
+                assigned.add(unitId);
+            if (unit.branch_mode === "current")
+                issues.push({ path: `${path}.units`, message: `current-branch unit ${unitId} cannot be stacked` });
+            if (unit.completion !== "pr")
+                issues.push({ path: `${path}.units`, message: `stacked unit ${unitId} must use completion: pr` });
+            if (!["github", "gitlab"].includes(String(unit.provider)))
+                issues.push({ path: `${path}.units`, message: `stacked unit ${unitId} must use github or gitlab` });
+            if (unit.dependency_mode !== "stack")
+                issues.push({ path: `${path}.units`, message: `stacked unit ${unitId} must use dependency_mode: stack` });
+            for (const ticketId of Array.isArray(unit.tickets) ? unit.tickets : [])
+                stackedTicketIds.add(ticketId);
+        }
+        const providers = new Set(stack.units.map((id) => String(byId.get(id)?.provider ?? "")));
+        if (providers.size > 1)
+            issues.push({ path: `${path}.units`, message: "all nodes in a stack must use the same provider" });
+        const typed = { id: stack.id, name: String(stack.name), units: stack.units };
+        const nodes = normalizeStackNodes(typed, units, ticketDefs);
+        if (nodes.length > 5)
+            issues.push({ path: `${path}.units`, message: `normalized PR depth ${nodes.length} exceeds maximum 5` });
+        const rootDeps = Array.isArray(byId.get(typed.units[0])?.depends_on) ? byId.get(typed.units[0]).depends_on : [];
+        if (rootDeps.length)
+            issues.push({ path: `${path}.units`, message: `root unit ${typed.units[0]} cannot have a stack parent` });
+        for (let unitIndex = 1; unitIndex < typed.units.length; unitIndex++) {
+            const id = typed.units[unitIndex];
+            const predecessor = typed.units[unitIndex - 1];
+            const deps = Array.isArray(byId.get(id)?.depends_on) ? byId.get(id).depends_on : [];
+            if (deps.length !== 1 || deps[0] !== predecessor)
+                issues.push({ path: `${path}.units`, message: `unit ${id} must depend only on immediate predecessor ${predecessor}` });
+        }
+        for (const unitId of typed.units) {
+            const unit = byId.get(unitId);
+            if (unit?.branch_mode !== "per-ticket")
+                continue;
+            const tickets = unit.tickets.slice().sort((a, b) => (queueIndex.get(a) ?? 0) - (queueIndex.get(b) ?? 0));
+            for (let ticketIndex = 1; ticketIndex < tickets.length; ticketIndex++) {
+                const deps = ticketById.get(tickets[ticketIndex])?.depends_on ?? [];
+                if (!deps.includes(tickets[ticketIndex - 1]))
+                    issues.push({ path: `${path}.units`, message: `per-ticket node ${tickets[ticketIndex]} must depend on predecessor ${tickets[ticketIndex - 1]}` });
+            }
+        }
+        const indices = typed.units.flatMap((unitId) => Array.isArray(byId.get(unitId)?.tickets) ? byId.get(unitId).tickets : [])
+            .map((ticketId) => queueIndex.get(ticketId)).filter((value) => value !== undefined).sort((a, b) => a - b);
+        if (indices.some((value, position) => position > 0 && value !== indices[position - 1] + 1))
+            issues.push({ path: `${path}.units`, message: "stack tickets must be contiguous in queue order" });
+    }
+    if (plan && ticketDefs)
+        for (const ticket of ticketDefs)
+            if (stackedTicketIds.has(ticket.id) && ticket.plan_ref && ticket.plan_ref.plan_id !== plan.plan_id)
+                issues.push({ path: "plan", message: `stack ticket ${ticket.id} belongs to plan ${ticket.plan_ref.plan_id}, not ${plan.plan_id}` });
     return issues;
 }
 function enumValue(issues, path, value, allowed, required = false) {
@@ -127,10 +260,10 @@ function deliveryCycles(units) {
     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 completedUnits = new Set(config.units.filter((unit) => unit.tickets.every((id) => ["done", "canceled", "obsolete"].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 remaining = unit.tickets.filter((id) => !["done", "canceled", "obsolete"].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({
@@ -150,3 +283,70 @@ export function selectDeliveryUnitForRun(config, states, 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");
 }
+/** Complete preflight simulation for exact `--stacks N` selection. */
+export function selectStacksForRun(config, ticketDefs, states, count) {
+    if (!Number.isInteger(count) || count < 1)
+        return { stacks: [], tickets: [], error: "--stacks must be a positive integer" };
+    const stacks = config.stacks ?? [];
+    const unitById = new Map(config.units.map((unit) => [unit.id, unit]));
+    const defs = new Map(ticketDefs.map((ticket) => [ticket.id, ticket]));
+    const candidates = [...stacks].sort((a, b) => {
+        const ap = stackStarted(a, unitById, states) ? 0 : 1;
+        const bp = stackStarted(b, unitById, states) ? 0 : 1;
+        return ap - bp;
+    });
+    const firstPartial = candidates.find((stack) => stackStarted(stack, unitById, states) && !stackComplete(stack, unitById, states));
+    if (firstPartial) {
+        const blocker = externalStackBlocker(firstPartial, unitById, defs, states);
+        if (blocker)
+            return { stacks: [], tickets: [], error: `partial stack ${firstPartial.name} (${firstPartial.id}) is blocked by ${blocker}; finish or unblock it before starting a newer stack` };
+    }
+    const selected = [];
+    const tickets = [];
+    for (const stack of candidates) {
+        if (stackComplete(stack, unitById, states))
+            continue;
+        const blocker = externalStackBlocker(stack, unitById, defs, states);
+        if (blocker) {
+            if (stack === firstPartial)
+                return { stacks: [], tickets: [], error: `partial stack ${stack.id} is blocked by ${blocker}` };
+            continue;
+        }
+        selected.push(stack);
+        for (const unitId of stack.units)
+            for (const id of unitById.get(unitId)?.tickets ?? [])
+                if (!terminalDelivery(states.get(id)?.status))
+                    tickets.push(id);
+        if (selected.length === count)
+            break;
+    }
+    if (selected.length !== count)
+        return { stacks: [], tickets: [], error: `requested exactly ${count} complete eligible stack(s), but only ${selected.length} can legally run` };
+    return { stacks: selected, tickets };
+}
+export function updateStackDeliveryState(projectDir, stackIds, status, patch = {}) {
+    const config = loadDeliveryConfig(projectDir);
+    if (!config)
+        throw new Error(`${DELIVERY_FILE} not found`);
+    const selected = new Set(stackIds);
+    let matched = 0;
+    const next = { ...config, stacks: (config.stacks ?? []).map((stack) => selected.has(stack.id) ? (matched++, { ...stack, ...patch, id: stack.id, name: stack.name, units: stack.units, status }) : stack) };
+    if (matched !== selected.size)
+        throw new Error(`unknown stack IDs: ${[...selected].filter((id) => !next.stacks?.some((stack) => stack.id === id)).join(",")}`);
+    const target = join(projectDir, DELIVERY_FILE);
+    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, stringify(next, { lineWidth: 120 }), "utf8");
+    renameSync(temp, target);
+    return next;
+}
+function terminalDelivery(status) { return status === "done" || status === "canceled" || status === "obsolete"; }
+function stackStarted(stack, units, states) { return stack.units.some((unit) => (units.get(unit)?.tickets ?? []).some((id) => ["in_progress", "blocked", "done"].includes(states.get(id)?.status ?? "planned"))); }
+function stackComplete(stack, units, states) { return stack.units.every((unit) => (units.get(unit)?.tickets ?? []).every((id) => terminalDelivery(states.get(id)?.status))); }
+function externalStackBlocker(stack, units, defs, states) {
+    const inside = new Set(stack.units.flatMap((unit) => units.get(unit)?.tickets ?? []));
+    for (const id of inside)
+        for (const dep of defs.get(id)?.depends_on ?? [])
+            if (!inside.has(dep) && !terminalDelivery(states.get(dep)?.status))
+                return dep;
+    return undefined;
+}

package/dist/tickets/queue.d.ts

@@ -1,5 +1,6 @@
 import type { TicketDef } from "./ticketSchema.js";
 import type { TicketState } from "./stateDb.js";
+import type { DeliveryConfig } from "./delivery.js";
 export interface QueueRow {
     rank: number;
     ticket: string;
@@ -34,3 +35,5 @@ export interface ActiveStatusRow {
 }
 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[];
+/** Human-readable queue blocks keep a whole unfinished stack and its resume point visible. */
+export declare function formatStackAwareQueue(ticketDefs: TicketDef[], states: Map<string, TicketState>, delivery?: DeliveryConfig): string[];