ai-foreman 1.7.0 → 1.7.2

package/README.md

@@ -176,7 +176,7 @@ gh repo view <host>/<owner>/<repo>
 | `--fast` | flag | off | Lower latency. |
 | `-y, --yes` | flag | off | Skips confirmation before builder edits ticket files. |
 
-Use `ai-foreman tickets setup:init` or `setup:update` to save local, Linear, or Jira Cloud ticket sources in `rafi-config.yaml`. Linear imports use `LINEAR_API_KEY`; Jira Cloud imports use `JIRA_EMAIL` and `JIRA_API_TOKEN`. Imported provider payloads are snapshotted under ignored `.tickets/imports/`, and mirrored tickets carry `external_refs`.
+Use `ai-foreman tickets setup:init` or `setup:update` to append local, Linear, or Jira Cloud sources to the project-wide registry in `rafi-config.yaml`. Linear imports use `LINEAR_API_KEY`; Jira Cloud imports use `JIRA_EMAIL` and `JIRA_API_TOKEN`. Credentials are never persisted, and mirrored tickets retain source provenance.
 
 Use `ai-foreman tickets review` to accept, defer, or dismiss pending split/combine/duplicate recommendations rendered in the progress doc.
 

package/dist/branch/git.d.ts

@@ -11,6 +11,7 @@ export declare function generatedTrackerDirtyPaths(paths: {
     progressDoc: string;
     archiveDoc?: string;
 }): string[];
+export declare function collectBaseWorktreeDirtyPaths(cwd: string, opts?: BaseWorktreeCleanOptions): string[];
 export declare function ensureCleanBaseWorktree(cwd: string, opts?: BaseWorktreeCleanOptions): void;
 export declare function ensureForemanExcluded(cwd: string): void;
 export declare function createTicketWorktree(projectDir: string, runId: string, branch: string, base: string): string;

package/dist/branch/git.js

@@ -25,13 +25,16 @@ export function generatedTrackerDirtyPaths(paths) {
     }
     return out;
 }
-export function ensureCleanBaseWorktree(cwd, opts = {}) {
+export function collectBaseWorktreeDirtyPaths(cwd, opts = {}) {
     const allowedDirtyPaths = new Set([".tickets/.gitignore", ...(opts.allowedDirtyPaths ?? []).map(normalizeRepoPath)]);
     const status = runGit(cwd, ["status", "--porcelain", "--untracked-files=all"]).stdout;
-    const dirty = status.split("\n").filter(Boolean).filter((line) => {
+    return status.split("\n").filter(Boolean).filter((line) => {
         const path = normalizeRepoPath(line.slice(3));
         return !path.startsWith(".foreman/") && !allowedDirtyPaths.has(path);
     });
+}
+export function ensureCleanBaseWorktree(cwd, opts = {}) {
+    const dirty = collectBaseWorktreeDirtyPaths(cwd, opts);
     if (dirty.length > 0) {
         throw new Error(`base worktree has uncommitted changes:\n${dirty.join("\n")}`);
     }

package/dist/branch/runner.d.ts

@@ -10,6 +10,7 @@ export interface DeliveryUnitSession {
     sessionId: string;
     ticket: string;
 }
+export type BaseWorktreePolicy = "enforce" | "warn" | "skip";
 export declare function readDeliveryUnitSession(projectDir: string, unitId: string): DeliveryUnitSession | undefined;
 export interface BranchRunnerOptions {
     projectDir: string;
@@ -32,6 +33,7 @@ export interface BranchRunnerOptions {
     autoMergeTimeoutMinutes?: number | null;
     mergeMethod?: MergeMethod;
     allowedBaseDirtyPaths?: string[];
+    baseWorktreePolicy?: BaseWorktreePolicy;
     trackerPaths?: {
         progressDoc: string;
         archiveDoc: string;

package/dist/branch/runner.js

@@ -24,7 +24,20 @@ function deliverySessionPath(projectDir, unitId) {
     return join(projectDir, ".foreman", "delivery-sessions", `${unitId}.json`);
 }
 export async function runBranchPlan(opts) {
-    ensureCleanBaseWorktree(opts.projectDir, { allowedDirtyPaths: opts.allowedBaseDirtyPaths });
+    const baseWorktreePolicy = opts.baseWorktreePolicy ?? "enforce";
+    if (baseWorktreePolicy !== "skip") {
+        try {
+            ensureCleanBaseWorktree(opts.projectDir, { allowedDirtyPaths: opts.allowedBaseDirtyPaths });
+        }
+        catch (error) {
+            if (baseWorktreePolicy === "warn") {
+                console.warn(`foreman: warning: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
     ensureForemanExcluded(opts.projectDir);
     const completionMode = opts.completionMode ?? (opts.createPr ? "pr" : "none");
     const reviewProvider = opts.reviewProvider ?? "github";

package/dist/cli/start.js

@@ -18,7 +18,7 @@ import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
 import { applySharedDeliveryBranch, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
-import { currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
+import { collectBaseWorktreeDirtyPaths, currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
 import { formatGitHubFailure, preflightGh } from "../branch/github.js";
 import { preflightGlab } from "../branch/gitlab.js";
 import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
@@ -529,11 +529,20 @@ export function buildStartCommand() {
         if (branchMode) {
             const ticketsConfig = loadTicketsConfig(cwd);
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
-            try {
-                ensureCleanBaseWorktree(cwd, { allowedDirtyPaths: allowedBaseDirtyPaths });
+            const baseWorktreePolicy = recoveryRecord ? "skip" : "enforce";
+            if (baseWorktreePolicy === "skip") {
+                const dirty = collectBaseWorktreeDirtyPaths(cwd, { allowedDirtyPaths: allowedBaseDirtyPaths });
+                if (dirty.length > 0) {
+                    console.warn(`foreman: warning: base worktree has uncommitted changes; build recovery will continue.\n${dirty.join("\n")}`);
+                }
             }
-            catch (err) {
-                fail(err instanceof Error ? err.message : String(err));
+            else {
+                try {
+                    ensureCleanBaseWorktree(cwd, { allowedDirtyPaths: allowedBaseDirtyPaths });
+                }
+                catch (err) {
+                    fail(err instanceof Error ? err.message : String(err));
+                }
             }
             if (branchDefaults.createReview && branchDefaults.reviewProvider) {
                 await ensureReviewProviderReady(cwd, branchDefaults.reviewProvider, log, Boolean(opts.yes));
@@ -718,6 +727,7 @@ export function buildStartCommand() {
                 autoMergeTimeoutMinutes: branchDefaults.autoMergeTimeoutMinutes,
                 mergeMethod: branchDefaults.mergeMethod,
                 allowedBaseDirtyPaths,
+                baseWorktreePolicy,
                 trackerPaths: {
                     progressDoc: ticketsConfig.paths.progressDoc,
                     archiveDoc: ticketsConfig.paths.archiveDoc,

package/dist/cli/tickets.js

@@ -266,6 +266,8 @@ async function collectTicketSetupPatch(dir, opts, current) {
     const buildPatch = {};
     if (opts.agentPreference)
         populatePatch.agent_preference = parseAgentPreference(opts.agentPreference);
+    if (opts.branchStrategy)
+        buildPatch.branch_strategy = parseBranchStrategy(opts.branchStrategy);
     if (opts.completion)
         buildPatch.completion = parseCompletionMode(opts.completion);
     if (opts.provider)
@@ -275,6 +277,15 @@ async function collectTicketSetupPatch(dir, opts, current) {
     if (opts.autoMergeTimeoutMinutes !== undefined) {
         buildPatch.auto_merge_timeout_minutes = parseOptionalPositiveInteger(opts.autoMergeTimeoutMinutes, "--auto-merge-timeout-minutes");
     }
+    if (buildPatch.branch_strategy === "current") {
+        if (buildPatch.completion && buildPatch.completion !== "none")
+            fail("--branch-strategy current requires --completion none");
+        buildPatch.completion = "none";
+        buildPatch.provider = buildPatch.provider ?? "local";
+        buildPatch.pr_ready = false;
+        buildPatch.auto_merge_wait = false;
+        buildPatch.auto_merge_timeout_minutes = null;
+    }
     if (!shouldPrompt(opts)) {
         const prefill = current.sources.length === 0
             ? configuredPlanningSources(dir).map((path) => ({ type: "local", paths: [path] }))
@@ -321,6 +332,32 @@ async function collectTicketSetupPatch(dir, opts, current) {
     }
     if (section === "build" || section === "all") {
         const recommended = recommendedBuildDefaults(dir);
+        const strategy = await select({
+            message: "Default ticket work mode:",
+            initialValue: current.build.branch_strategy,
+            options: [
+                { value: "current", label: "One branch - work the queue on the current branch" },
+                { value: "batch", label: "Batch branch - use shared branches for explicit delivery batches" },
+                { value: "branch-per-ticket", label: "Branch per ticket - isolate each ticket on its own branch" },
+            ],
+        });
+        if (isCancel(strategy))
+            process.exit(0);
+        buildPatch.branch_strategy = strategy;
+        if (strategy === "current") {
+            buildPatch.completion = "none";
+            buildPatch.provider = "local";
+            buildPatch.pr_ready = false;
+            buildPatch.merge_method = "squash";
+            buildPatch.cleanup = true;
+            buildPatch.auto_merge_wait = false;
+            buildPatch.auto_merge_timeout_minutes = null;
+            return {
+                sources,
+                populate: populatePatch,
+                build: buildPatch,
+            };
+        }
         const completion = await select({
             message: "Default completion behavior for branch ticket runs:",
             initialValue: current.build.completion === "none" ? recommended.completion : current.build.completion,
@@ -333,7 +370,6 @@ async function collectTicketSetupPatch(dir, opts, current) {
         });
         if (isCancel(completion))
             process.exit(0);
-        buildPatch.branch_strategy = "branch-per-ticket";
         buildPatch.completion = completion;
         buildPatch.provider = recommended.provider;
         buildPatch.pr_ready = completion === "auto-merge";
@@ -517,6 +553,11 @@ function parseCompletionMode(value) {
         return value;
     fail("--completion must be one of: pr, auto-merge, direct-merge, none");
 }
+function parseBranchStrategy(value) {
+    if (["current", "batch", "branch-per-ticket"].includes(value))
+        return value;
+    fail("--branch-strategy must be one of: current, batch, branch-per-ticket");
+}
 function parseProvider(value) {
     if (["auto", "github", "gitlab", "local"].includes(value))
         return value;
@@ -853,6 +894,7 @@ export function buildTicketsCommand() {
         .option("--jira-jql <jql>", "Jira JQL query")
         .option("--url-source <urls...>", "add public HTTP(S) source URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
+        .option("--branch-strategy <strategy>", "build branch strategy default (current | batch | branch-per-ticket)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
@@ -883,6 +925,7 @@ export function buildTicketsCommand() {
         .option("--jira-jql <jql>", "Jira JQL query")
         .option("--url-source <urls...>", "replace saved sources with public HTTP(S) URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
+        .option("--branch-strategy <strategy>", "build branch strategy default (current | batch | branch-per-ticket)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
@@ -1261,7 +1304,7 @@ export function buildTicketsCommand() {
         .description("Print the ticket queue to stdout.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--limit <n>", "override view limit")
-        .option("--refresh", "query GitHub/GitLab and refresh cached stack review state")
+        .option("--refresh", "query GitHub/GitLab and refresh cached batch review state")
         .action((opts) => {
         try {
             const dir = cwd(opts);
@@ -1275,6 +1318,7 @@ export function buildTicketsCommand() {
                         console.log(line);
                 return;
             }
+            console.log("Batches: none configured. Queue is flat.");
             const rows = cmdQueue(dir, opts.limit !== undefined ? Number(opts.limit) : undefined);
             if (rows.length === 0) {
                 console.log("No remaining tickets.");

package/dist/sources/sourceRegistry.d.ts

@@ -0,0 +1,49 @@
+import type { ProjectSourceEntry, ProjectSourceLocator, ProjectSourceType, SourceRegistryConfig, SourceSnapshotStorage, TicketSetupSource } from "rafi-spec";
+export declare const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
+export declare const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
+export interface StructuredSourceRequest {
+    type?: ProjectSourceType;
+    description?: string;
+    label?: string;
+    locator?: ProjectSourceLocator;
+}
+export interface LoadedSourceRegistry {
+    registry: SourceRegistryConfig;
+    configured: boolean;
+    migrated: boolean;
+    warnings: string[];
+}
+export interface CaptureResult {
+    registry: SourceRegistryConfig;
+    entries: ProjectSourceEntry[];
+    snapshots: string[];
+    pending: string[];
+}
+export declare function emptySourceRegistry(storage?: SourceSnapshotStorage): SourceRegistryConfig;
+/** Read the shared registry and merge legacy source fields in memory. The next source-aware save persists migration. */
+export declare function loadSourceRegistry(projectDir: string): LoadedSourceRegistry;
+/** Persist the registry while preserving ticket populate/build settings and removing only superseded legacy fields. */
+export declare function saveSourceRegistry(projectDir: string, registry: SourceRegistryConfig): void;
+export declare function addPendingSourceDescription(registry: SourceRegistryConfig, description: string, now?: Date): SourceRegistryConfig;
+export declare function setSourceStorage(registry: SourceRegistryConfig, storage: SourceSnapshotStorage): SourceRegistryConfig;
+export declare function deactivateSource(registry: SourceRegistryConfig, id: string): SourceRegistryConfig;
+/** Remove only capture files introduced by a staged registry; existing history is never touched. */
+export declare function discardStagedSourceCaptures(projectDir: string, original: SourceRegistryConfig, staged: SourceRegistryConfig): void;
+/** Compatibility bridge for legacy ticket setup callers. Existing entries and versions are retained. */
+export declare function appendLegacyTicketSources(registry: SourceRegistryConfig, sources: TicketSetupSource[]): SourceRegistryConfig;
+export declare function extractSourceRequests(output: string): StructuredSourceRequest[];
+/** Deterministically recognize only an entire obvious locator; all other language stays pending for agent interpretation. */
+export declare function sourceRequestFromAnswer(answer: string, projectDir: string): StructuredSourceRequest;
+export declare function registerSourceRequests(projectDir: string, registry: SourceRegistryConfig, requests: StructuredSourceRequest[], opts?: {
+    capture?: boolean;
+    storage?: SourceSnapshotStorage;
+}): Promise<CaptureResult>;
+export declare function refreshSourceRegistry(projectDir: string, registry: SourceRegistryConfig, ids?: string[]): Promise<CaptureResult>;
+export declare function sourceContext(registry: SourceRegistryConfig, options?: {
+    metadataOnly?: Set<string>;
+    pinned?: Map<string, Set<string>>;
+}): Array<Record<string, unknown>>;
+export declare function validateSourceVersionRef(registry: SourceRegistryConfig, ref: {
+    source_id: string;
+    fingerprint: string;
+}, projectDir?: string): string | undefined;

package/dist/sources/sourceRegistry.js

@@ -0,0 +1,577 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { parse, stringify } from "yaml";
+import { fetchAndSnapshotUrl, normalizePublicHttpUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
+import { fetchJiraIssues, fetchLinearIssues } from "../tickets/importer.js";
+export const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
+export const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
+const CONFIG_FILE = "rafi-config.yaml";
+const DEFAULT_REGISTRY = { version: 1, snapshot_storage: "local", entries: [] };
+export function emptySourceRegistry(storage = "local") {
+    return { ...DEFAULT_REGISTRY, snapshot_storage: storage, entries: [] };
+}
+/** Read the shared registry and merge legacy source fields in memory. The next source-aware save persists migration. */
+export function loadSourceRegistry(projectDir) {
+    const path = join(resolve(projectDir), CONFIG_FILE);
+    if (!existsSync(path))
+        return { registry: emptySourceRegistry(), configured: false, migrated: false, warnings: [] };
+    const raw = parse(readFileSync(path, "utf8"));
+    const parsed = normalizeRegistry(raw.sources);
+    const registry = cloneRegistry(parsed ?? DEFAULT_REGISTRY);
+    const warnings = [];
+    let migrated = false;
+    const planning = asObject(raw.planning);
+    if (Array.isArray(planning?.sources)) {
+        for (const value of planning.sources) {
+            if (typeof value !== "string" || !value.trim())
+                continue;
+            migrated = true;
+            migrateLegacyString(registry, value, warnings);
+        }
+    }
+    const tickets = asObject(raw.tickets);
+    if (Array.isArray(tickets?.sources)) {
+        for (const source of tickets.sources) {
+            migrated = true;
+            migrateTicketSource(registry, source, warnings);
+        }
+    }
+    warnings.push(...legacyTicketReferenceWarnings(projectDir, registry));
+    return { registry, configured: Boolean(parsed), migrated, warnings };
+}
+/** Persist the registry while preserving ticket populate/build settings and removing only superseded legacy fields. */
+export function saveSourceRegistry(projectDir, registry) {
+    const root = resolve(projectDir);
+    const configPath = join(root, CONFIG_FILE);
+    const raw = existsSync(configPath) ? parse(readFileSync(configPath, "utf8")) : {};
+    raw.sources = cloneRegistry(registry);
+    const planning = asObject(raw.planning);
+    if (planning) {
+        delete planning.sources;
+        if (Object.keys(planning).length === 0)
+            delete raw.planning;
+        else
+            raw.planning = planning;
+    }
+    const tickets = asObject(raw.tickets);
+    if (tickets) {
+        delete tickets.sources;
+        raw.tickets = tickets;
+    }
+    mkdirSync(root, { recursive: true });
+    writeFileSync(configPath, stringify(raw, { lineWidth: 100 }), "utf8");
+    backfillUniqueTicketSourceIds(root, registry);
+    ensurePrivateCacheIgnored(root);
+}
+export function addPendingSourceDescription(registry, description, now = new Date()) {
+    const value = description.trim();
+    if (!value)
+        return cloneRegistry(registry);
+    const next = cloneRegistry(registry);
+    next.pending ??= [];
+    if (!next.pending.some((item) => item.description === value))
+        next.pending.push({ description: value, created_at: now.toISOString() });
+    return next;
+}
+export function setSourceStorage(registry, storage) {
+    return { ...cloneRegistry(registry), snapshot_storage: storage };
+}
+export function deactivateSource(registry, id) {
+    const next = cloneRegistry(registry);
+    const entry = next.entries.find((item) => item.id === id);
+    if (!entry)
+        throw new Error(`unknown source: ${id}`);
+    entry.active = false;
+    return next;
+}
+/** Remove only capture files introduced by a staged registry; existing history is never touched. */
+export function discardStagedSourceCaptures(projectDir, original, staged) {
+    const root = resolve(projectDir);
+    const retained = new Set(original.entries.flatMap((entry) => entry.versions.map((version) => `${entry.id}:${version.fingerprint}`)));
+    const originalIds = new Set(original.entries.map((entry) => entry.id));
+    for (const entry of staged.entries) {
+        for (const version of entry.versions)
+            if (!retained.has(`${entry.id}:${version.fingerprint}`)) {
+                for (const path of [version.snapshot_path, version.manifest_path]) {
+                    const absolute = resolve(root, path);
+                    const rel = relative(root, absolute);
+                    if (!rel.startsWith("..") && (rel.startsWith(".rafi/source-cache/") || rel.startsWith(".rafi/sources/")))
+                        rmSync(absolute, { force: true });
+                }
+            }
+        if (!originalIds.has(entry.id) && entry.type === "local" && entry.locator.path?.startsWith(".tickets/imports/local-"))
+            rmSync(resolve(root, entry.locator.path), { recursive: true, force: true });
+    }
+}
+/** Compatibility bridge for legacy ticket setup callers. Existing entries and versions are retained. */
+export function appendLegacyTicketSources(registry, sources) {
+    const next = cloneRegistry(registry);
+    const warnings = [];
+    for (const source of sources)
+        migrateTicketSource(next, source, warnings);
+    return next;
+}
+export function extractSourceRequests(output) {
+    const requests = [];
+    let cursor = 0;
+    while (true) {
+        const start = output.indexOf(SOURCE_REQUEST_START, cursor);
+        if (start < 0)
+            break;
+        const end = output.indexOf(SOURCE_REQUEST_END, start + SOURCE_REQUEST_START.length);
+        if (end < 0)
+            throw new Error(`source request is missing ${SOURCE_REQUEST_END}`);
+        const body = output.slice(start + SOURCE_REQUEST_START.length, end).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+        let value;
+        try {
+            value = JSON.parse(body);
+        }
+        catch (error) {
+            throw new Error(`source request is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const values = Array.isArray(value) ? value : [value];
+        for (const item of values)
+            if (item && typeof item === "object" && !Array.isArray(item))
+                requests.push(item);
+        cursor = end + SOURCE_REQUEST_END.length;
+    }
+    // Compatibility with the original single-line protocol. Preserve the complete remainder.
+    for (const match of output.matchAll(/^SOURCE_REQUEST:\s*(.+)$/gim))
+        requests.push({ description: match[1].trim() });
+    return requests;
+}
+/** Deterministically recognize only an entire obvious locator; all other language stays pending for agent interpretation. */
+export function sourceRequestFromAnswer(answer, projectDir) {
+    const value = answer.trim();
+    if (/^https?:\/\/\S+$/i.test(value))
+        return requestFromUrl(value);
+    const candidate = resolve(projectDir, value);
+    if (value && existsSync(candidate))
+        return { type: "local", label: basename(candidate), locator: { path: normalizeLocalPath(projectDir, candidate) } };
+    if (hasGlobMagic(value) || /^(?:\.{0,2}\/|\/)/.test(value) || /[\\/][^\\/]+\.[A-Za-z0-9]{1,12}$/.test(value))
+        return { type: "local", label: basename(value), locator: { path: value } };
+    if (/^(?:open\s+)?issues\s+for\s+(?:this|the)\s+repo(?:sitory)?$/i.test(value))
+        return { type: inferOriginProvider(projectDir), label: "Open repository issues", locator: { repository: inferOriginRepository(projectDir), mode: "issues", filters: { state: "open" } } };
+    return { description: value };
+}
+export async function registerSourceRequests(projectDir, registry, requests, opts = {}) {
+    const next = cloneRegistry(registry);
+    if (opts.storage)
+        next.snapshot_storage = opts.storage;
+    const added = [];
+    const snapshots = [];
+    const pending = [];
+    for (const raw of requests) {
+        const request = raw.description && !raw.locator ? sourceRequestFromAnswer(raw.description, projectDir) : raw;
+        if (!request.type || !request.locator) {
+            if (request.description?.trim()) {
+                const value = request.description.trim();
+                pending.push(value);
+                const updated = addPendingSourceDescription(next, value);
+                next.pending = updated.pending;
+            }
+            continue;
+        }
+        let locatorInput = request.locator;
+        if (request.type === "local" && locatorInput.path && opts.capture !== false) {
+            const absolute = resolve(projectDir, locatorInput.path);
+            const rel = relative(resolve(projectDir), absolute);
+            if (existsSync(absolute) && (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)))
+                locatorInput = { ...locatorInput, path: snapshotExternalLocalFile(projectDir, absolute) };
+        }
+        const locator = normalizeLocator(request.type, locatorInput, projectDir);
+        const key = sourceKey(request.type, locator);
+        let entry = next.entries.find((item) => sourceKey(item.type, item.locator) === key);
+        if (!entry) {
+            entry = { id: stableSourceId(key), type: request.type, label: request.label?.trim() || defaultLabel(request.type, locator), active: true, locator, versions: [] };
+            next.entries.push(entry);
+            added.push(entry);
+        }
+        else if (!entry.active)
+            entry.active = true;
+        if (raw.description?.trim() && next.pending)
+            next.pending = next.pending.filter((item) => item.description !== raw.description.trim());
+        if (opts.capture !== false) {
+            const version = await captureEntry(projectDir, entry, next.snapshot_storage);
+            if (!entry.versions.some((item) => item.fingerprint === version.fingerprint))
+                entry.versions.push(version);
+            snapshots.push(version.snapshot_path);
+        }
+    }
+    return { registry: next, entries: added, snapshots: [...new Set(snapshots)], pending };
+}
+export async function refreshSourceRegistry(projectDir, registry, ids) {
+    if (ids?.length) {
+        const known = new Set(registry.entries.map((entry) => entry.id));
+        const missing = ids.filter((id) => !known.has(id));
+        if (missing.length)
+            throw new Error(`unknown source${missing.length === 1 ? "" : "s"}: ${missing.join(", ")}`);
+    }
+    const selected = registry.entries.filter((entry) => entry.active && (!ids?.length || ids.includes(entry.id)));
+    const next = cloneRegistry(registry);
+    const snapshots = [];
+    for (const selectedEntry of selected) {
+        const entry = next.entries.find((item) => item.id === selectedEntry.id);
+        const version = await captureEntry(projectDir, entry, next.snapshot_storage);
+        if (!entry.versions.some((item) => item.fingerprint === version.fingerprint))
+            entry.versions.push(version);
+        snapshots.push(version.snapshot_path);
+    }
+    return { registry: next, entries: [], snapshots, pending: [] };
+}
+export function sourceContext(registry, options = {}) {
+    return registry.entries.map((entry) => {
+        const pinned = options.pinned?.get(entry.id);
+        const newest = entry.versions.at(-1);
+        const versions = entry.versions.filter((version) => pinned?.has(version.fingerprint) || (!options.metadataOnly?.has(entry.id) && version === newest));
+        return { id: entry.id, type: entry.type, label: entry.label, active: entry.active, locator: entry.locator, versions };
+    });
+}
+export function validateSourceVersionRef(registry, ref, projectDir = process.cwd()) {
+    const source = registry.entries.find((entry) => entry.id === ref.source_id);
+    if (!source)
+        return `unknown source registry entry ${ref.source_id}`;
+    const version = source.versions.find((item) => item.fingerprint === ref.fingerprint);
+    if (!version)
+        return `unknown captured version ${ref.fingerprint} for ${ref.source_id}`;
+    if (!existsSync(resolve(projectDir, version.snapshot_path)))
+        return `${version.storage === "local" ? "private" : "tracked"} source snapshot is missing for ${ref.source_id}@${ref.fingerprint}; restore it instead of substituting a newer version`;
+    return undefined;
+}
+async function captureEntry(projectDir, entry, storage) {
+    if (entry.type === "local")
+        return captureLocal(projectDir, entry, storage);
+    if (entry.type === "url")
+        return captureUrl(projectDir, entry, storage);
+    if (entry.type === "github" || entry.type === "gitlab")
+        return captureCliProvider(projectDir, entry, storage);
+    return captureApiProvider(projectDir, entry, storage);
+}
+function captureLocal(projectDir, entry, storage) {
+    const locator = entry.locator.path;
+    if (!locator)
+        throw new Error(`${entry.id}: local source needs a path`);
+    const absolute = isAbsolute(locator) ? locator : resolve(projectDir, locator);
+    const files = hasGlobMagic(locator) ? expandLocalGlob(projectDir, locator) : existsSync(absolute) ? collectLocalFiles(absolute) : [];
+    if (!files.length)
+        throw new Error(`${entry.id}: local source did not match files: ${locator}`);
+    const chunks = files.map((file) => {
+        const bytes = readFileSync(file);
+        return `\n===== ${isAbsolute(locator) ? basename(file) : relative(projectDir, file)} =====\n${bytes.toString("utf8")}`;
+    });
+    return writeCapture(projectDir, entry, storage, chunks.join("").trimStart(), "text/plain", files.length);
+}
+async function captureUrl(projectDir, entry, storage) {
+    if (!entry.locator.url)
+        throw new Error(`${entry.id}: URL source needs a URL`);
+    const fetched = await fetchAndSnapshotUrl(projectDir, entry.locator.url);
+    const version = writeCapture(projectDir, entry, storage, fetched.text, fetched.contentType, 1);
+    rmSync(resolve(projectDir, fetched.snapshotPath), { force: true });
+    rmSync(resolve(projectDir, fetched.metadataPath), { force: true });
+    return version;
+}
+function captureCliProvider(projectDir, entry, storage) {
+    const repository = entry.locator.repository || inferOriginRepository(projectDir);
+    const mode = entry.locator.mode ?? "issues";
+    let command;
+    let args;
+    if (entry.type === "github") {
+        command = "gh";
+        if (mode === "issue")
+            args = ["issue", "view", String(entry.locator.issue), "--repo", repository, "--json", "number,title,body,state,url,labels,comments"];
+        else if (mode === "project")
+            args = ["project", "item-list", String(entry.locator.project), "--owner", repository.split("/")[0], "--format", "json", "--limit", "500"];
+        else {
+            args = ["issue", "list", "--repo", repository, "--state", entry.locator.filters?.state ?? "open", "--limit", entry.locator.filters?.limit ?? "500", "--json", "number,title,body,state,url,labels"];
+            appendCliFilter(args, "--search", entry.locator.filters?.q ?? entry.locator.filters?.search);
+            appendCliFilter(args, "--label", entry.locator.filters?.label ?? entry.locator.filters?.labels);
+            appendCliFilter(args, "--assignee", entry.locator.filters?.assignee);
+            appendCliFilter(args, "--author", entry.locator.filters?.author);
+            appendCliFilter(args, "--milestone", entry.locator.filters?.milestone);
+        }
+    }
+    else {
+        command = "glab";
+        if (mode === "issue")
+            args = ["issue", "view", String(entry.locator.issue), "--repo", repository, "--output", "json"];
+        else if (mode === "board") {
+            const query = new URLSearchParams({ state: entry.locator.filters?.state ?? "opened", per_page: "100", ...(entry.locator.filters ?? {}) });
+            args = ["api", "--paginate", `projects/${encodeURIComponent(repository)}/issues?${query.toString()}`];
+        }
+        else {
+            args = ["issue", "list", "--repo", repository, "--state", entry.locator.filters?.state ?? "opened", "--per-page", entry.locator.filters?.limit ?? "500", "--output", "json"];
+            appendCliFilter(args, "--search", entry.locator.filters?.search);
+            appendCliFilter(args, "--label", entry.locator.filters?.label ?? entry.locator.filters?.labels);
+            appendCliFilter(args, "--assignee", entry.locator.filters?.assignee);
+        }
+    }
+    let text;
+    try {
+        text = execFileSync(command, args, { cwd: projectDir, encoding: "utf8", maxBuffer: 20 * 1024 * 1024 });
+    }
+    catch (error) {
+        throw new Error(`${entry.type} source ${entry.label} could not be retrieved with authenticated ${command}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return writeCapture(projectDir, entry, storage, text, "application/json", countProviderItems(text));
+}
+async function captureApiProvider(projectDir, entry, storage) {
+    const opts = { importCap: 500, commentLimit: 10 };
+    const items = entry.type === "linear"
+        ? await fetchLinearIssues({ type: "linear", api_key_env: entry.locator.api_key_env ?? "LINEAR_API_KEY", team_key: entry.locator.team_key, filter: entry.locator.filter }, opts)
+        : await fetchJiraIssues({ type: "jira", site: required(entry.locator.site, `${entry.id}: Jira site`), email_env: entry.locator.email_env ?? "JIRA_EMAIL", token_env: entry.locator.token_env ?? "JIRA_API_TOKEN", jql: required(entry.locator.jql, `${entry.id}: Jira JQL`) }, opts);
+    return writeCapture(projectDir, entry, storage, `${JSON.stringify(items.map((item) => item.raw), null, 2)}\n`, "application/json", items.length);
+}
+function writeCapture(projectDir, entry, storage, content, contentType, itemCount) {
+    const normalized = content.endsWith("\n") ? content : `${content}\n`;
+    const fingerprint = createHash("sha256").update(normalized).digest("hex");
+    const root = resolve(projectDir);
+    const base = join(root, storage === "tracked" ? ".rafi/sources" : ".rafi/source-cache", entry.id);
+    const extension = contentType.includes("json") ? "json" : "md";
+    const snapshot = join(base, `${fingerprint}.${extension}`);
+    const manifest = join(base, `${fingerprint}.manifest.json`);
+    mkdirSync(base, { recursive: true });
+    if (!existsSync(snapshot))
+        writeFileSync(snapshot, normalized, "utf8");
+    const version = {
+        fingerprint, captured_at: new Date().toISOString(), storage,
+        snapshot_path: relative(root, snapshot), manifest_path: relative(root, manifest),
+        content_type: contentType, bytes: Buffer.byteLength(normalized), item_count: itemCount,
+    };
+    if (!existsSync(manifest))
+        writeFileSync(manifest, `${JSON.stringify({ source_id: entry.id, type: entry.type, label: entry.label, locator: entry.locator, ...version }, null, 2)}\n`, "utf8");
+    return version;
+}
+function collectLocalFiles(path) {
+    const stat = statSync(path);
+    if (stat.isFile())
+        return [path];
+    if (!stat.isDirectory())
+        throw new Error(`unsupported local source: ${path}`);
+    const out = [];
+    const visit = (dir) => {
+        for (const item of readdirSync(dir, { withFileTypes: true })) {
+            if (item.isSymbolicLink() || [".git", "node_modules", ".rafi", ".tickets"].includes(item.name))
+                continue;
+            const child = join(dir, item.name);
+            if (item.isDirectory())
+                visit(child);
+            else if (item.isFile())
+                out.push(child);
+            if (out.length > 1000)
+                throw new Error("local source directory exceeds 1000 file limit");
+        }
+    };
+    visit(path);
+    return out.sort();
+}
+function hasGlobMagic(value) { return /[*?\[]/.test(value); }
+function expandLocalGlob(projectDir, pattern) {
+    if (isAbsolute(pattern))
+        throw new Error("absolute globs are not supported; name an external file or directory explicitly");
+    const normalized = pattern.split(sep).join("/").replace(/^\.\//, "");
+    let body = "";
+    for (let index = 0; index < normalized.length; index++) {
+        const char = normalized[index];
+        if (char === "*" && normalized[index + 1] === "*") {
+            body += ".*";
+            index++;
+        }
+        else if (char === "*")
+            body += "[^/]*";
+        else if (char === "?")
+            body += "[^/]";
+        else
+            body += /[\\^$.[\]{}()+|]/.test(char) ? `\\${char}` : char;
+    }
+    const expression = new RegExp(`^${body}$`);
+    return collectLocalFiles(projectDir).filter((file) => expression.test(relative(projectDir, file).split(sep).join("/")));
+}
+function requestFromUrl(value) {
+    const url = new URL(normalizePublicHttpUrl(value));
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (url.hostname.toLowerCase() === "github.com" && parts.length >= 2) {
+        const issueIndex = parts.indexOf("issues");
+        const projectIndex = parts.indexOf("projects");
+        if (issueIndex < 0 && projectIndex < 0)
+            return { type: "url", label: url.hostname, locator: { url: url.toString() } };
+        const projectOwner = ["orgs", "users"].includes(parts[0]) && projectIndex === 2 ? parts[1] : undefined;
+        const locator = { repository: projectOwner ?? `${parts[0]}/${parts[1]}`, mode: "issues", filters: Object.fromEntries(url.searchParams) };
+        if (issueIndex >= 0 && /^\d+$/.test(parts[issueIndex + 1] ?? "")) {
+            locator.mode = "issue";
+            locator.issue = Number(parts[issueIndex + 1]);
+        }
+        else if (projectIndex >= 0) {
+            locator.mode = "project";
+            locator.project = parts[projectIndex + 1];
+        }
+        return { type: "github", label: `GitHub ${locator.repository}`, locator };
+    }
+    if (url.hostname.toLowerCase().includes("gitlab") && parts.length >= 2) {
+        const issueIndex = parts.indexOf("issues");
+        if (issueIndex < 0 && !parts.includes("boards"))
+            return { type: "url", label: url.hostname, locator: { url: url.toString() } };
+        const locator = { repository: parts.slice(0, parts.indexOf("-") >= 0 ? parts.indexOf("-") : 2).join("/"), mode: "issues", filters: Object.fromEntries(url.searchParams) };
+        if (issueIndex >= 0 && /^\d+$/.test(parts[issueIndex + 1] ?? "")) {
+            locator.mode = "issue";
+            locator.issue = Number(parts[issueIndex + 1]);
+        }
+        if (parts.includes("boards"))
+            locator.mode = "board";
+        return { type: "gitlab", label: `GitLab ${locator.repository}`, locator };
+    }
+    return { type: "url", label: url.hostname, locator: { url: url.toString() } };
+}
+function normalizeLocator(type, locator, projectDir) {
+    const value = { ...locator, filters: locator.filters ? Object.fromEntries(Object.entries(locator.filters).sort()) : undefined };
+    if (type === "url" && value.url)
+        value.url = normalizePublicHttpUrl(value.url);
+    if (type === "local" && value.path)
+        value.path = normalizeLocalPath(projectDir, value.path);
+    if (value.site)
+        value.site = value.site.replace(/\/+$/, "").toLowerCase();
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+function normalizeLocalPath(projectDir, value) {
+    const root = resolve(projectDir);
+    const absolute = resolve(projectDir, value);
+    const rel = relative(root, absolute);
+    // Do not persist external absolute locators. The immutable snapshot remains usable.
+    return !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel) ? rel || "." : basename(absolute);
+}
+function sourceKey(type, locator) {
+    return `${type}:${canonical(locator)}`;
+}
+function stableSourceId(key) { return `src_${createHash("sha256").update(key).digest("hex").slice(0, 16)}`; }
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+function defaultLabel(type, locator) { return locator.path || locator.url || locator.repository || locator.site || locator.team_key || type; }
+function countProviderItems(text) { try {
+    const value = JSON.parse(text);
+    return Array.isArray(value) ? value.length : 1;
+}
+catch {
+    return 0;
+} }
+function appendCliFilter(args, flag, value) { if (value)
+    args.push(flag, value); }
+function required(value, label) { if (!value)
+    throw new Error(`${label} is required`); return value; }
+function inferOriginProvider(projectDir) {
+    const url = originUrl(projectDir).toLowerCase();
+    return url.includes("gitlab") ? "gitlab" : "github";
+}
+function inferOriginRepository(projectDir) {
+    const value = originUrl(projectDir).replace(/\.git$/, "");
+    const match = value.match(/(?:github|gitlab)(?:\.com|\.[^/:]+)[/:](.+)$/i) ?? value.match(/[:/]([^/:]+\/[^/]+)$/);
+    if (!match?.[1])
+        throw new Error("could not infer repository from git origin; provide owner/repository");
+    return match[1];
+}
+function originUrl(projectDir) {
+    try {
+        return execFileSync("git", ["remote", "get-url", "origin"], { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        throw new Error("could not infer source provider because this project has no readable origin remote");
+    }
+}
+function migrateLegacyString(registry, value, warnings) {
+    const trimmed = value.trim();
+    if (/^https?:\/\/\S+$/i.test(trimmed)) {
+        const req = requestFromUrl(trimmed);
+        addLegacyEntry(registry, req.type, req.label, req.locator);
+        return;
+    }
+    if (/^[.~\/]|[*?\[]|\.[A-Za-z0-9]{1,8}$/i.test(trimmed)) {
+        addLegacyEntry(registry, "local", trimmed, { path: trimmed });
+        return;
+    }
+    registry.pending ??= [];
+    registry.pending.push({ description: trimmed, created_at: new Date().toISOString() });
+    warnings.push(`legacy source needs interpretation: ${trimmed}`);
+}
+function migrateTicketSource(registry, raw, warnings) {
+    if (!raw || typeof raw !== "object")
+        return;
+    if (raw.type === "local")
+        for (const path of raw.paths ?? [])
+            addLegacyEntry(registry, "local", path, { path });
+    else if (raw.type === "url") {
+        const req = requestFromUrl(raw.url);
+        addLegacyEntry(registry, req.type, req.label, req.locator);
+    }
+    else if (raw.type === "linear")
+        addLegacyEntry(registry, "linear", raw.team_key ? `Linear ${raw.team_key}` : "Linear", { api_key_env: raw.api_key_env ?? "LINEAR_API_KEY", team_key: raw.team_key, filter: raw.filter });
+    else if (raw.type === "jira")
+        addLegacyEntry(registry, "jira", `Jira ${raw.site}`, { site: raw.site, email_env: raw.email_env ?? "JIRA_EMAIL", token_env: raw.token_env ?? "JIRA_API_TOKEN", jql: raw.jql });
+    else
+        warnings.push("unsupported legacy ticket source was left unchanged");
+}
+function addLegacyEntry(registry, type, label, locator) {
+    const key = sourceKey(type, locator);
+    if (!registry.entries.some((entry) => sourceKey(entry.type, entry.locator) === key))
+        registry.entries.push({ id: stableSourceId(key), type, label, active: true, locator, versions: [] });
+}
+function normalizeRegistry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (raw.version !== 1 || !Array.isArray(raw.entries))
+        return undefined;
+    return { version: 1, snapshot_storage: raw.snapshot_storage === "tracked" ? "tracked" : "local", entries: raw.entries, ...(Array.isArray(raw.pending) ? { pending: raw.pending } : {}) };
+}
+function cloneRegistry(registry) { return JSON.parse(JSON.stringify(registry)); }
+function asObject(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : undefined; }
+function ensurePrivateCacheIgnored(projectDir) {
+    const path = join(projectDir, ".gitignore");
+    const marker = ".rafi/source-cache/";
+    const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (!current.split(/\r?\n/).includes(marker))
+        writeFileSync(path, `${current}${current && !current.endsWith("\n") ? "\n" : ""}${marker}\n`, "utf8");
+}
+function legacyTicketReferenceWarnings(projectDir, registry) {
+    const path = join(projectDir, ".tickets", "tickets.yaml");
+    if (!existsSync(path))
+        return [];
+    const raw = parse(readFileSync(path, "utf8"));
+    const warnings = [];
+    for (const ticket of raw?.tickets ?? [])
+        for (const ref of ticket.source_refs ?? [])
+            if (!ref.source_id && ref.source) {
+                const matches = matchingSourceIds(registry, ref.source);
+                if (matches.length > 1)
+                    warnings.push(`ticket ${ticket.id ?? "unknown"} has ambiguous legacy source reference ${ref.source}: ${matches.join(", ")}`);
+            }
+    return warnings;
+}
+function backfillUniqueTicketSourceIds(projectDir, registry) {
+    const path = join(projectDir, ".tickets", "tickets.yaml");
+    if (!existsSync(path))
+        return;
+    const raw = parse(readFileSync(path, "utf8"));
+    let changed = false;
+    for (const ticket of raw?.tickets ?? [])
+        for (const ref of ticket.source_refs ?? [])
+            if (!ref.source_id && ref.source) {
+                const matches = matchingSourceIds(registry, ref.source);
+                if (matches.length === 1) {
+                    ref.source_id = matches[0];
+                    changed = true;
+                }
+            }
+    if (changed)
+        writeFileSync(path, stringify(raw, { lineWidth: 120 }), "utf8");
+}
+function matchingSourceIds(registry, value) {
+    return registry.entries.filter((entry) => {
+        const candidates = [entry.id, entry.label, entry.type, entry.locator.url, entry.locator.path, entry.locator.repository, entry.locator.site];
+        return candidates.some((candidate) => candidate === value);
+    }).map((entry) => entry.id);
+}

package/dist/ticketPopulation.d.ts

@@ -15,6 +15,13 @@ export interface TicketSliceProposal {
     depends_on: string[];
     rollback?: string | null;
     notes?: string | null;
+    source_refs?: Array<{
+        source_id: string;
+        fingerprint: string;
+        item?: string;
+        url?: string | null;
+        note?: string | null;
+    }>;
 }
 export interface TicketPopulationProposalV1 {
     version: 1;

package/dist/ticketPopulation.js

@@ -69,6 +69,10 @@ export function materializeTicketPopulation(proposal, plan, existing) {
             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 },
+            source_refs: (plan.slices.find((item) => item.slice_ref === slice.slice_ref)?.source_refs ?? slice.source_refs)?.map((ref) => ({
+                source: ref.source_id, item: ref.item ?? "document", source_id: ref.source_id, fingerprint: ref.fingerprint,
+                ...(ref.url !== undefined ? { url: ref.url } : {}), ...(ref.note !== undefined ? { note: ref.note } : {}),
+            })),
         };
     });
     const ownedIds = new Set(materialized.map((ticket) => ticket.id));

package/dist/tickets/commands.js

@@ -134,6 +134,7 @@ export function cmdInit(projectDir, opts) {
                     properties: {
                         source: { type: "string", minLength: 1 },
                         item: { type: "string", minLength: 1 },
+                        source_id: { type: "string", pattern: "^src_[A-Za-z0-9_-]+$" },
                         url: { type: ["string", "null"] },
                         fingerprint: { type: ["string", "null"] },
                         note: { type: ["string", "null"] },

package/dist/tickets/queue.d.ts

@@ -35,5 +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. */
+/** Human-readable queue blocks keep a whole unfinished batch and its resume point visible. */
 export declare function formatStackAwareQueue(ticketDefs: TicketDef[], states: Map<string, TicketState>, delivery?: DeliveryConfig): string[];

package/dist/tickets/queue.js

@@ -61,15 +61,16 @@ export function buildActiveStatusRows(queueRows, ticketDefs, states) {
         };
     });
 }
-/** Human-readable queue blocks keep a whole unfinished stack and its resume point visible. */
+/** Human-readable queue blocks keep a whole unfinished batch and its resume point visible. */
 export function formatStackAwareQueue(ticketDefs, states, delivery) {
     if (!delivery?.stacks?.length)
-        return buildNextQueue(ticketDefs, states, Number.MAX_SAFE_INTEGER).map((row) => `${row.ticket} ${row.status} ${row.title}`);
+        return ["Batches: none configured. Queue is flat.", ...buildNextQueue(ticketDefs, states, Number.MAX_SAFE_INTEGER).map((row) => `${row.ticket} ${row.status} ${row.title}`)];
     const defs = new Map(ticketDefs.map((ticket) => [ticket.id, ticket]));
     const unitById = new Map(delivery.units.map((unit) => [unit.id, unit]));
     const stackedTickets = new Set();
     const lines = [];
-    for (const stack of delivery.stacks) {
+    lines.push(`Batches: ${delivery.stacks.length} configured.`);
+    for (const [index, stack] of delivery.stacks.entries()) {
         const nodes = normalizeStackNodes(stack, delivery.units, ticketDefs);
         const ticketIds = stack.units.flatMap((id) => unitById.get(id)?.tickets ?? []);
         ticketIds.forEach((id) => stackedTickets.add(id));
@@ -79,16 +80,26 @@ export function formatStackAwareQueue(ticketDefs, states, delivery) {
         const next = ticketIds.find((id) => !terminal(states.get(id)?.status));
         const blockers = next && defs.get(next) ? resolveBlockers(defs.get(next), states) : [];
         const state = deriveStackState(stack, ticketIds, states, blockers);
-        lines.push(`=== STACK START: ${stack.name} (${stack.id}) ===`);
-        lines.push(`status=${state}; size=${ticketIds.length}; pr_depth=${nodes.length}; blockers=${blockers.join(",") || "none"}; completed_prefix=${completed.join(",") || "none"}; next=${next ?? "none"}`);
+        const units = stack.units.map((id) => unitById.get(id)).filter((unit) => Boolean(unit));
+        const branchModes = [...new Set(units.map((unit) => unit.branch_mode))].join(",") || "unknown";
+        const prChain = units.some((unit) => unit.dependency_mode === "stack") || nodes.length > 1;
+        lines.push(`=== Batch ${index + 1}: ${stack.name} (${stack.id}) ===`);
+        lines.push(`status=${state}; tickets=${ticketIds.length}; branch_mode=${branchModes}; blockers=${blockers.join(",") || "none"}; completed=${completed.join(",") || "none"}; next=${next ?? "none"}`);
+        if (prChain)
+            lines.push(`delivery=PR chain (${nodes.length} dependent branch${nodes.length === 1 ? "" : "es"})`);
         lines.push(`reviews=${stack.review_links?.join(",") || "none"}; remote_checked=${stack.remote_checked_at ?? "never"}${stack.remote_stale ? " (stale; run --refresh for a live check)" : ""}`);
         for (const id of ticketIds)
             lines.push(`${id} ${states.get(id)?.status ?? "planned"} ${defs.get(id)?.title ?? "unknown ticket"}`);
-        lines.push(`=== STACK END: ${stack.name} (${stack.id}) ===`);
+        lines.push(`=== End Batch ${index + 1}: ${stack.name} (${stack.id}) ===`);
     }
+    let unbatched = false;
     for (const ticket of ticketDefs.sort((a, b) => a.order - b.order)) {
         if (stackedTickets.has(ticket.id) || terminal(states.get(ticket.id)?.status))
             continue;
+        if (!unbatched) {
+            lines.push("Unbatched tickets:");
+            unbatched = true;
+        }
         const blockers = resolveBlockers(ticket, states);
         lines.push(`${ticket.id} ${computeDisplayStatus(states.get(ticket.id)?.status ?? "planned", blockers)} ${ticket.title}`);
     }

package/dist/tickets/setupConfig.d.ts

@@ -3,7 +3,7 @@ export type HarnessTarget = "claude" | "codex";
 export type TicketBuildCompletionMode = "pr" | "auto-merge" | "direct-merge" | "none";
 export type TicketBuildProvider = "auto" | "github" | "gitlab" | "local";
 export type TicketBuildMergeMethod = "squash" | "merge" | "rebase";
-export type TicketBuildBranchStrategy = "branch-per-ticket" | "batch";
+export type TicketBuildBranchStrategy = "current" | "batch" | "branch-per-ticket";
 export type TicketPopulateAgentPreference = "configured" | "claude" | "codex";
 export type TicketPopulateEnrichmentPolicy = "none" | "recommendations" | "agent";
 export type TicketSourceConfig = {

package/dist/tickets/setupConfig.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse, stringify } from "yaml";
 import { loadDefaults } from "special-agents";
+import { appendLegacyTicketSources, loadSourceRegistry } from "../sources/sourceRegistry.js";
 export const RAFI_CONFIG_FILE = "rafi-config.yaml";
 const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker", "uninstaller"];
 const SKILL_NAMES = [
@@ -48,7 +49,10 @@ export function loadTicketSetupConfig(projectDir) {
     const raw = loadRafiConfigObject(projectDir);
     if (!raw || raw.tickets === undefined)
         return undefined;
-    return normalizeTicketsSetupConfig(raw.tickets, `${RAFI_CONFIG_FILE}.tickets`);
+    const setup = normalizeTicketsSetupConfig(raw.tickets, `${RAFI_CONFIG_FILE}.tickets`);
+    if (setup.sources.length === 0)
+        setup.sources = legacySourcesFromRegistry(loadSourceRegistry(projectDir).registry.entries);
+    return setup;
 }
 export function loadTicketSetupConfigWithDefaults(projectDir) {
     return loadTicketSetupConfig(projectDir) ?? cloneTicketSetup(DEFAULT_TICKET_SETUP);
@@ -59,7 +63,17 @@ export function hasTicketSetupConfig(projectDir) {
 }
 export function saveTicketSetupConfig(projectDir, setup, opts = {}) {
     const config = loadRafiConfigObject(projectDir) ?? minimalRafiConfig(projectDir, opts);
-    config.tickets = denormalizeTicketsSetupConfig(normalizeTicketsSetupConfig(setup, "tickets"));
+    const normalized = normalizeTicketsSetupConfig(setup, "tickets");
+    const ticketConfig = denormalizeTicketsSetupConfig(normalized);
+    delete ticketConfig.sources;
+    config.tickets = ticketConfig;
+    config.sources = appendLegacyTicketSources(loadSourceRegistry(projectDir).registry, normalized.sources);
+    const planning = config.planning && typeof config.planning === "object" && !Array.isArray(config.planning) ? config.planning : undefined;
+    if (planning) {
+        delete planning.sources;
+        if (Object.keys(planning).length === 0)
+            delete config.planning;
+    }
     mkdirSync(projectDir, { recursive: true });
     writeFileSync(join(projectDir, RAFI_CONFIG_FILE), stringify(config, { lineWidth: 100 }), "utf8");
 }
@@ -332,7 +346,7 @@ function normalizePopulate(value, label) {
 function normalizeBuild(value, label) {
     const raw = objectOrEmpty(value, label);
     return {
-        branch_strategy: enumField(raw.branch_strategy, ["branch-per-ticket", "batch"], DEFAULT_TICKET_SETUP.build.branch_strategy, `${label}.branch_strategy`),
+        branch_strategy: enumField(raw.branch_strategy, ["current", "batch", "branch-per-ticket"], DEFAULT_TICKET_SETUP.build.branch_strategy, `${label}.branch_strategy`),
         completion: enumField(raw.completion, ["pr", "auto-merge", "direct-merge", "none"], DEFAULT_TICKET_SETUP.build.completion, `${label}.completion`),
         provider: enumField(raw.provider, ["auto", "github", "gitlab", "local"], DEFAULT_TICKET_SETUP.build.provider, `${label}.provider`),
         pr_ready: booleanField(raw.pr_ready, DEFAULT_TICKET_SETUP.build.pr_ready, `${label}.pr_ready`),
@@ -424,3 +438,17 @@ function cloneTicketSetup(setup) {
 function unique(values) {
     return [...new Set(values)];
 }
+function legacySourcesFromRegistry(entries) {
+    const out = [];
+    for (const entry of entries.filter((item) => item.active)) {
+        if (entry.type === "local" && entry.locator.path)
+            out.push({ type: "local", paths: [entry.locator.path] });
+        else if (entry.type === "url" && entry.locator.url)
+            out.push({ type: "url", url: entry.locator.url });
+        else if (entry.type === "linear")
+            out.push({ type: "linear", api_key_env: entry.locator.api_key_env ?? "LINEAR_API_KEY", team_key: entry.locator.team_key, filter: entry.locator.filter });
+        else if (entry.type === "jira" && entry.locator.site && entry.locator.jql)
+            out.push({ type: "jira", site: entry.locator.site, email_env: entry.locator.email_env ?? "JIRA_EMAIL", token_env: entry.locator.token_env ?? "JIRA_API_TOKEN", jql: entry.locator.jql });
+    }
+    return dedupeTicketSources(out);
+}

package/dist/tickets/sourceFetch.js

@@ -23,7 +23,7 @@ export async function fetchAndSnapshotUrl(projectDir, input, limits = {}) {
             response = await fetch(current, {
                 redirect: "manual",
                 signal: controller.signal,
-                headers: { Accept: "text/html,text/plain,text/markdown,application/pdf;q=0.9" },
+                headers: { Accept: "text/html,text/plain,text/markdown,application/json,application/yaml,text/yaml,application/pdf;q=0.9" },
             });
         }
         finally {
@@ -154,6 +154,11 @@ function detectContentType(header, bytes, url) {
         return "html";
     if (["text/markdown", "text/x-markdown"].includes(mime) || /\.md(?:own)?$/i.test(new URL(url).pathname))
         return "markdown";
+    if (["application/json", "application/yaml", "application/x-yaml", "text/yaml", "text/x-yaml"].includes(mime) || /\.(?:json|ya?ml)$/i.test(new URL(url).pathname)) {
+        if (bytes.subarray(0, Math.min(bytes.length, 1024)).includes(0))
+            throw new Error("binary URL content is not supported");
+        return "text";
+    }
     if (!mime || mime.startsWith("text/") || mime === "application/octet-stream") {
         if (bytes.subarray(0, Math.min(bytes.length, 1024)).includes(0))
             throw new Error("binary URL content is not supported");

package/dist/tickets/ticketSchema.d.ts

@@ -11,6 +11,7 @@ export interface TicketExternalRef {
 export interface TicketSourceRef {
     source: string;
     item: string;
+    source_id?: string;
     url?: string | null;
     fingerprint?: string | null;
     note?: string | null;
@@ -149,6 +150,10 @@ export declare const TICKET_JSON_SCHEMA: {
                         readonly type: "string";
                         readonly minLength: 1;
                     };
+                    readonly source_id: {
+                        readonly type: "string";
+                        readonly pattern: "^src_[A-Za-z0-9_-]+$";
+                    };
                     readonly url: {
                         readonly type: readonly ["string", "null"];
                     };
@@ -310,6 +315,10 @@ export declare const TICKETS_FILE_SCHEMA: {
                                     readonly type: "string";
                                     readonly minLength: 1;
                                 };
+                                readonly source_id: {
+                                    readonly type: "string";
+                                    readonly pattern: "^src_[A-Za-z0-9_-]+$";
+                                };
                                 readonly url: {
                                     readonly type: readonly ["string", "null"];
                                 };

package/dist/tickets/ticketSchema.js

@@ -43,6 +43,7 @@ export const TICKET_JSON_SCHEMA = {
                 properties: {
                     source: { type: "string", minLength: 1 },
                     item: { type: "string", minLength: 1 },
+                    source_id: { type: "string", pattern: "^src_[A-Za-z0-9_-]+$" },
                     url: { type: ["string", "null"] },
                     fingerprint: { type: ["string", "null"] },
                     note: { type: ["string", "null"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -65,6 +65,10 @@
       "types": "./dist/tickets/setupConfig.d.ts",
       "default": "./dist/tickets/setupConfig.js"
     },
+    "./sources/source-registry.js": {
+      "types": "./dist/sources/sourceRegistry.d.ts",
+      "default": "./dist/sources/sourceRegistry.js"
+    },
     "./cli/tickets.js": {
       "types": "./dist/cli/tickets.d.ts",
       "default": "./dist/cli/tickets.js"
@@ -114,8 +118,8 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.148"
   },
   "dependencies": {
-    "special-agents": "0.8.0",
-    "rafi-spec": "0.8.0",
+    "special-agents": "0.8.2",
+    "rafi-spec": "0.8.2",
     "@clack/prompts": "^1.4.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",