ai-foreman 1.5.0 → 1.6.0

package/dist/log.d.ts

@@ -1,7 +1,7 @@
 /** A single structured log record. */
 export interface LogRecord {
     ts: string;
-    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "qa" | "qa-fix" | "error";
+    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "error";
     [key: string]: unknown;
 }
 /** Append-only JSONL logger. One line per record, plus an echo to the console. */

package/dist/roles.d.ts

@@ -1,3 +1,14 @@
+import type { ConfigurableAgentRole } from "rafi-spec";
+export interface AgentRoleRegistration {
+    id: ConfigurableAgentRole;
+    label: string;
+    consumers: string[];
+    configurable: boolean;
+    manifest: string;
+    commands: string[];
+}
+/** One registry drives compilation, settings UI, and independently launched roles. */
+export declare const AGENT_ROLE_REGISTRY: readonly AgentRoleRegistration[];
 export interface RoleBundle {
     system: string;
     skills: string[];

package/dist/roles.js

@@ -11,6 +11,14 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgent } from "special-agents";
+/** One registry drives compilation, settings UI, and independently launched roles. */
+export const AGENT_ROLE_REGISTRY = [
+    { id: "planner", label: "Planner", consumers: ["initial planning", "ticket planning"], configurable: true, manifest: "planner", commands: ["rafi create", "rafi plan", "rafi tickets plan"] },
+    { id: "builder", label: "Builder", consumers: ["implementation"], configurable: true, manifest: "builder", commands: ["rafi start", "rafi build:resume"] },
+    { id: "qa", label: "QA (separate review session)", consumers: ["run-wide independent review"], configurable: true, manifest: "qa", commands: ["rafi start", "rafi build:resume"] },
+    { id: "ticket-maker", label: "Ticket maker", consumers: ["ticket population"], configurable: true, manifest: "ticket-maker", commands: ["rafi tickets populate"] },
+    { id: "uninstaller", label: "Uninstaller", consumers: ["non-empty uninstall instructions only"], configurable: true, manifest: "uninstaller", commands: ["rafi uninstall"] },
+];
 function libraryGetter(role) {
     const a = getAgent(role);
     return { system: a.system, skills: a.skills, model: a.model, effort: a.effort };

package/dist/runtimeAuth.d.ts

@@ -15,7 +15,7 @@ export declare class RuntimeAuthError extends Error {
     readonly authLikely: boolean;
     constructor(opts: RuntimeAuthErrorOptions);
 }
-export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime): void;
+export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime): Promise<void>;
 export declare function normalizeRuntimeErrorText(runtime: AgentRuntime, text: string, exitCode?: number | null, context?: string): string;
 export declare function isRuntimeAuthFailure(output: string): boolean;
 export declare function runtimeCommandLabel(runtime: AgentRuntime): string;

package/dist/runtimeAuth.js

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { formatRuntimeProbeFailure, probeRuntime } from "./runtimeReadiness.js";
 export class RuntimeAuthError extends Error {
     runtime;
     exitCode;
@@ -15,34 +15,15 @@ export class RuntimeAuthError extends Error {
         this.authLikely = isRuntimeAuthFailure(`${this.stderr}\n${this.stdout}`);
     }
 }
-export function checkRuntimeReady(projectDir, runtime) {
-    try {
-        if (runtime === "claude") {
-            execFileSync("claude", ["-p", "Return exactly OK"], {
-                cwd: projectDir,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-        }
-        else {
-            execFileSync("codex", ["exec", "--skip-git-repo-check", "-C", projectDir, "Return exactly OK"], {
-                cwd: projectDir,
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-        }
-    }
-    catch (err) {
-        const failure = err;
+export async function checkRuntimeReady(projectDir, runtime) {
+    const result = await probeRuntime(projectDir, runtime);
+    if (!result.ok)
         throw new RuntimeAuthError({
             runtime,
             context: "readiness check",
-            exitCode: failure.status,
-            stdout: outputToString(failure.stdout),
-            stderr: outputToString(failure.stderr),
-            cause: err,
+            exitCode: result.exitCode,
+            stderr: formatRuntimeProbeFailure(result),
         });
-    }
 }
 export function normalizeRuntimeErrorText(runtime, text, exitCode, context = "builder turn") {
     if (!isRuntimeAuthFailure(text))

package/dist/runtimeReadiness.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeProbeCategory, RuntimeProbePhase, RuntimeProbeResult } from "rafi-spec";
+import type { AgentRuntime } from "./runtimeAuth.js";
+export declare const RUNTIME_PROBE_TIMEOUT_MS = 30000;
+export declare const RUNTIME_DIAGNOSTIC_LIMIT: number;
+export interface ProbeRuntimeOptions {
+    phase?: RuntimeProbePhase;
+    timeoutMs?: number;
+    maxDiagnosticsBytes?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function probeRuntime(cwd: string, runtime: AgentRuntime, opts?: ProbeRuntimeOptions): Promise<RuntimeProbeResult>;
+export declare function classifyRuntimeFailure(text: string, phase?: RuntimeProbePhase): RuntimeProbeCategory;
+export declare function sanitizeDiagnostics(text: string, maxBytes?: number): string;
+export declare function formatRuntimeProbeFailure(result: RuntimeProbeResult): string;

package/dist/runtimeReadiness.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+export const RUNTIME_PROBE_TIMEOUT_MS = 30_000;
+export const RUNTIME_DIAGNOSTIC_LIMIT = 8 * 1024;
+const RELEVANT_ENV = /^(ANTHROPIC|CLAUDE|CODEX|OPENAI|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i;
+export async function probeRuntime(cwd, runtime, opts = {}) {
+    const executable = runtime === "claude" ? "claude" : "codex";
+    const args = runtime === "claude"
+        ? ["-p", "Return exactly OK"]
+        : ["exec", "--skip-git-repo-check", "-C", cwd, "Return exactly OK"];
+    const phase = opts.phase ?? "readiness";
+    const env = opts.env ?? process.env;
+    const limit = opts.maxDiagnosticsBytes ?? RUNTIME_DIAGNOSTIC_LIMIT;
+    const timeoutMs = opts.timeoutMs ?? RUNTIME_PROBE_TIMEOUT_MS;
+    return new Promise((resolveResult) => {
+        let output = Buffer.alloc(0);
+        let timedOut = false;
+        let settled = false;
+        const spawnOpts = { cwd, env, stdio: ["ignore", "pipe", "pipe"] };
+        const child = spawn(executable, args, spawnOpts);
+        const append = (chunk) => {
+            if (output.length >= limit)
+                return;
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            output = Buffer.concat([output, bytes.subarray(0, Math.max(0, limit - output.length))]);
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 1_000).unref();
+        }, timeoutMs);
+        timer.unref();
+        const finish = (exitCode, signal, spawnError) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const diagnostics = sanitizeDiagnostics(spawnError?.message
+                ? `${spawnError.message}\n${output.toString("utf8")}`
+                : output.toString("utf8"), limit);
+            const category = timedOut
+                ? "timeout"
+                : spawnError?.code === "ENOENT"
+                    ? "missing-executable"
+                    : exitCode === 0
+                        ? "ready"
+                        : classifyRuntimeFailure(diagnostics, phase);
+            resolveResult({
+                ok: category === "ready",
+                runtime,
+                phase,
+                category,
+                executable,
+                cwd,
+                timedOut,
+                exitCode,
+                signal,
+                diagnostics,
+                environmentNames: Object.keys(env).filter((name) => RELEVANT_ENV.test(name)).sort(),
+                recoveryChoices: category === "ready" ? [] : ["retry", "switch", "cancel"],
+            });
+        };
+        child.once("error", (error) => finish(null, null, error));
+        child.once("close", (code, signal) => finish(code, signal));
+    });
+}
+export function classifyRuntimeFailure(text, phase = "readiness") {
+    const value = text.toLowerCase();
+    if (/not logged in|login required|unauthenticated|invalid authentication|expired.{0,20}token|token.{0,20}expired|\b401\b/.test(value))
+        return "authentication";
+    if (/forbidden|not authorized|unauthorized|entitlement|permission denied|\b403\b/.test(value))
+        return "authorization";
+    if (/rate.?limit|too many requests|\b429\b|quota exceeded/.test(value))
+        return "rate-limit";
+    if (/enotfound|econnreset|econnrefused|network|dns|socket hang up|timed? out|tls|certificate/.test(value))
+        return "network";
+    if (/cannot find module|module not found|sdk/.test(value))
+        return "sdk-load";
+    if (/malformed|invalid json|protocol|unexpected token/.test(value))
+        return "malformed-protocol";
+    if (/stream|agent turn|agent error/.test(value))
+        return "agent-stream";
+    if (/config|configuration|invalid model|unsupported model/.test(value))
+        return "configuration";
+    if (phase === "compiler-update")
+        return "compiler-update";
+    if (phase === "capability-discovery")
+        return "capability-discovery";
+    return "unknown";
+}
+export function sanitizeDiagnostics(text, maxBytes = RUNTIME_DIAGNOSTIC_LIMIT) {
+    const clean = text
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/((?:api[_-]?key|access[_-]?token|auth(?:orization)?|password|secret)\s*[=:]\s*)(?:bearer\s+)?[^\s,;]+/gi, "$1<redacted>")
+        .replace(/\b(?:sk|rk|ghp|github_pat)_[A-Za-z0-9_-]+\b/g, "<redacted>")
+        .replace(/Bearer\s+[A-Za-z0-9._~+\/-]+=*/gi, "Bearer <redacted>")
+        .replace(/\s+$/g, "")
+        .trim();
+    const bytes = Buffer.from(clean);
+    if (bytes.length <= maxBytes)
+        return clean;
+    return `${bytes.subarray(0, Math.max(0, maxBytes - 18)).toString("utf8")}\n... truncated ...`;
+}
+export function formatRuntimeProbeFailure(result) {
+    if (result.ok)
+        return `${result.executable} is ready.`;
+    const lines = [
+        `${result.executable} failed during ${result.phase} (${result.category}${result.timedOut ? ", timed out" : result.exitCode === null ? "" : `, exit ${result.exitCode}`}).`,
+    ];
+    if (result.category === "authentication") {
+        lines.push(result.runtime === "claude"
+            ? "Authenticate with `claude auth login --claudeai`, then retry."
+            : "Authenticate with `codex login`, then retry.");
+    }
+    else {
+        lines.push("Review the diagnostic below, then retry, switch to a verified provider, or cancel.");
+    }
+    if (result.diagnostics)
+        lines.push("", result.diagnostics);
+    return lines.join("\n");
+}

package/dist/ticketPlanning.d.ts

@@ -0,0 +1,83 @@
+import type { TicketDef } from "./tickets/ticketSchema.js";
+import { type TicketStatus } from "./tickets/stateDb.js";
+import { type DeliveryConfig } from "./tickets/delivery.js";
+import { type TicketBuildSetupConfig } from "./tickets/setupConfig.js";
+export declare const PROPOSAL_START = "RAFI_PROPOSAL_START";
+export declare const PROPOSAL_END = "RAFI_PROPOSAL_END";
+export interface TicketEdit {
+    id: string;
+    patch: Partial<Omit<TicketDef, "id">>;
+}
+export interface TicketSupersession {
+    replaced: string[];
+    replacements: string[];
+    reason: string;
+}
+export interface TicketStateChange {
+    id: string;
+    status: TicketStatus;
+    reason: string;
+}
+export interface SourceReconciliation {
+    source: string;
+    item: string;
+    disposition: "mapped" | "split" | "combined" | "deferred" | "excluded";
+    ticket_ids: string[];
+    reason?: string;
+}
+export interface FutureWorkDisposition {
+    id: number;
+    disposition: "accepted" | "rejected" | "merged" | "queued";
+}
+export interface TicketPlanProposal {
+    version: 1;
+    title: string;
+    markdown: string;
+    additions: TicketDef[];
+    edits: TicketEdit[];
+    supersessions: TicketSupersession[];
+    state_changes: TicketStateChange[];
+    source_reconciliation: SourceReconciliation[];
+    delivery?: DeliveryConfig | null;
+    build_defaults?: Partial<TicketBuildSetupConfig> | null;
+    future_work: FutureWorkDisposition[];
+    next: {
+        ticket_ids: string[];
+        replace_existing: boolean;
+    };
+}
+export interface PlanningFingerprint {
+    path: string;
+    sha256: string | null;
+}
+export interface TicketPlanningContext {
+    tickets: TicketDef[];
+    states: Array<{
+        ticket_id: string;
+        status: TicketStatus;
+    }>;
+    futureWork: Array<{
+        id?: number;
+        summary: string;
+        disposition: string;
+        rationale: string | null;
+    }>;
+    existingNext: string[];
+}
+export declare function readTicketPlanningContext(projectDir: string): TicketPlanningContext;
+export declare function ticketPlanningFingerprint(projectDir: string): PlanningFingerprint[];
+export declare function planningFingerprintChanges(projectDir: string, expected: PlanningFingerprint[]): string[];
+export declare function extractTicketPlanProposal(output: string, existingTickets?: TicketDef[]): TicketPlanProposal;
+export declare function validateTicketPlanProposal(value: unknown, existingTickets?: TicketDef[]): string[];
+export interface ApplyTicketPlanOptions {
+    expectedFingerprint: PlanningFingerprint[];
+    docsRoot: string;
+    now?: Date;
+}
+export interface AppliedTicketPlan {
+    added: string[];
+    edited: string[];
+    artifacts: string[];
+    backupDir: string;
+}
+export declare function applyApprovedTicketPlan(projectDir: string, proposal: TicketPlanProposal, opts: ApplyTicketPlanOptions): AppliedTicketPlan;

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");