ai-foreman 1.3.0 → 1.4.0

package/dist/tickets/recommendations.js

@@ -0,0 +1,183 @@
+import { loadTickets, saveTickets, validateTicketDefs } from "./ticketLoader.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
+import { StateDb } from "./stateDb.js";
+import { nowTimestamp } from "./events.js";
+import { renderAndWrite } from "./renderMarkdown.js";
+export function createReviewRecommendation(db, now, input) {
+    return db.insertReviewRecommendation({
+        created_at: now,
+        kind: input.kind,
+        status: "pending",
+        summary: input.summary,
+        rationale: input.rationale ?? null,
+        ticket_ids_json: JSON.stringify(input.ticketIds ?? []),
+        patch_json: JSON.stringify(input.patch),
+        source_json: JSON.stringify(input.source ?? {}),
+        updated_at: null,
+    });
+}
+export function cmdReviewRecommendations(projectDir, opts = {}) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    const db = new StateDb(paths.stateDb);
+    try {
+        const pending = db.getReviewRecommendations("pending");
+        if (!opts.action)
+            return { pending, changed: 0 };
+        const selected = opts.all
+            ? pending
+            : (opts.ids ?? []).map((id) => {
+                const row = db.getReviewRecommendation(id);
+                if (!row)
+                    throw new Error(`review recommendation ${id} not found`);
+                if (row.status !== "pending")
+                    throw new Error(`review recommendation ${id} is ${row.status}, not pending`);
+                return row;
+            });
+        if (selected.length === 0)
+            return { pending, changed: 0, action: opts.action };
+        const now = nowTimestamp(config.timezone);
+        if (opts.action === "accept") {
+            let tickets = loadTickets(paths.tickets);
+            for (const rec of selected) {
+                tickets = applyRecommendationPatch(tickets, parseRecommendationPatch(rec));
+            }
+            const issues = validateTicketDefs(tickets);
+            if (issues.length > 0) {
+                throw new Error(`accepted recommendation produced invalid tickets:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`);
+            }
+            saveTickets(paths.tickets, tickets);
+            db.transaction(() => {
+                for (const rec of selected)
+                    db.updateReviewRecommendationStatus(rec.id, "accepted", now);
+            });
+            const states = db.getAllStates();
+            renderAndWrite({ config, projectDir, ticketDefs: tickets, states, db });
+        }
+        else {
+            const status = opts.action === "defer" ? "deferred" : "dismissed";
+            db.transaction(() => {
+                for (const rec of selected)
+                    db.updateReviewRecommendationStatus(rec.id, status, now);
+            });
+            const tickets = loadTickets(paths.tickets);
+            const states = db.getAllStates();
+            renderAndWrite({ config, projectDir, ticketDefs: tickets, states, db });
+        }
+        return { pending: db.getReviewRecommendations("pending"), changed: selected.length, action: opts.action };
+    }
+    finally {
+        db.close();
+    }
+}
+export function applyRecommendationPatch(tickets, patch) {
+    const byId = new Map(tickets.map((ticket) => [ticket.id, { ...ticket }]));
+    for (const id of patch.remove ?? []) {
+        if (!byId.has(id))
+            throw new Error(`patch cannot remove unknown ticket ${id}`);
+        byId.delete(id);
+    }
+    for (const update of patch.update ?? []) {
+        const current = byId.get(update.id);
+        if (!current)
+            throw new Error(`patch cannot update unknown ticket ${update.id}`);
+        byId.set(update.id, {
+            ...current,
+            ...update.set,
+            id: current.id,
+            order: update.set.order ?? current.order,
+        });
+    }
+    for (const ticket of patch.add ?? []) {
+        if (byId.has(ticket.id))
+            throw new Error(`patch cannot add duplicate ticket ${ticket.id}`);
+        byId.set(ticket.id, { ...ticket });
+    }
+    return Array.from(byId.values()).sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+}
+export function insertXlSplitRecommendations(projectDir, tickets) {
+    const config = loadTicketsConfig(projectDir);
+    const paths = resolveTicketPaths(config, projectDir);
+    const db = new StateDb(paths.stateDb);
+    try {
+        const now = nowTimestamp(config.timezone);
+        const existing = db.getReviewRecommendations().filter((rec) => {
+            const ids = parseStringArray(rec.ticket_ids_json);
+            return rec.kind === "split" && ids.length === 1;
+        });
+        let count = 0;
+        let nextNumber = nextTicketNumber(tickets);
+        const maxOrder = tickets.reduce((highest, ticket) => Math.max(highest, ticket.order), 0);
+        for (const ticket of tickets) {
+            if (ticket.size !== "XL")
+                continue;
+            if (existing.some((rec) => parseStringArray(rec.ticket_ids_json)[0] === ticket.id && rec.status !== "dismissed"))
+                continue;
+            const firstId = `T${String(nextNumber++).padStart(3, "0")}`;
+            const secondId = `T${String(nextNumber++).padStart(3, "0")}`;
+            createReviewRecommendation(db, now, {
+                kind: "split",
+                summary: `Split XL ticket ${ticket.id}: ${ticket.title}`,
+                rationale: "Imported ticket is XL-sized; smaller implementation slices are safer for branch-per-ticket execution.",
+                ticketIds: [ticket.id],
+                patch: {
+                    remove: [ticket.id],
+                    add: [
+                        {
+                            ...ticket,
+                            id: firstId,
+                            order: maxOrder + count * 2000 + 1000,
+                            title: `${ticket.title} - implementation slice`,
+                            size: "L",
+                            depends_on: ticket.depends_on,
+                            notes: appendNote(ticket.notes, `Split from ${ticket.id}.`),
+                        },
+                        {
+                            ...ticket,
+                            id: secondId,
+                            order: maxOrder + count * 2000 + 2000,
+                            title: `${ticket.title} - validation slice`,
+                            size: "M",
+                            depends_on: [firstId],
+                            notes: appendNote(ticket.notes, `Split from ${ticket.id}.`),
+                        },
+                    ],
+                },
+                source: { generated_by: "import", original_ticket: ticket.id },
+            });
+            count++;
+        }
+        return count;
+    }
+    finally {
+        db.close();
+    }
+}
+function parseRecommendationPatch(rec) {
+    const parsed = JSON.parse(rec.patch_json);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`review recommendation ${rec.id} has invalid patch_json`);
+    }
+    return parsed;
+}
+function parseStringArray(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function nextTicketNumber(tickets) {
+    let max = 0;
+    for (const ticket of tickets) {
+        const match = /^T(\d+)$/i.exec(ticket.id);
+        if (match)
+            max = Math.max(max, Number.parseInt(match[1], 10));
+    }
+    return max + 1;
+}
+function appendNote(current, note) {
+    return current?.trim() ? `${current.trim()}\n${note}` : note;
+}

package/dist/tickets/renderMarkdown.js

@@ -59,13 +59,14 @@ export const DEFAULT_TRACKER_RULES = renderTrackerRules();
 export function renderProgressDoc(input) {
     const { config, projectDir, ticketDefs, states, db } = input;
     const now = input.now ?? DateTime.now().setZone(config.timezone).toISO();
-    const queueRows = buildNextQueue(ticketDefs, states, config.queueLimit);
+    const queueRows = buildNextQueue(ticketDefs, states, config.implementationLimit);
     const activeRows = buildActiveStatusRows(queueRows, ticketDefs, states);
     const futureWork = db.getFutureWork();
     const recentEvents = db.getRecentEvents(config.rendering.maxWorkLogRows);
     const lastSnap = db.getRecentValidationSnapshot();
     const recentCompleted = db.getRecentCompleted();
     const archiveIndex = db.getArchiveIndex();
+    const pendingRecommendations = db.getReviewRecommendations("pending");
     const rulesPath = join(projectDir, config.paths.trackerRules);
     const rulesContent = existsSync(rulesPath)
         ? readFileSync(rulesPath, "utf8").trim()
@@ -82,7 +83,8 @@ export function renderProgressDoc(input) {
     lines.push("## Tracker Metadata");
     lines.push(section("TRACKER_METADATA", table(["Field", "Value"], [
         ["App", config.appName],
-        ["Queue Limit", String(config.queueLimit)],
+        ["Implementation Limit", String(config.implementationLimit)],
+        ["View Limit", String(config.viewLimit)],
         ["Timezone", config.timezone],
         ["Generated At", now],
         ["Remaining Tickets", String(queueRows.length > 0 ? "≥" + queueRows.length : "0")],
@@ -168,6 +170,19 @@ export function renderProgressDoc(input) {
         ]));
     lines.push(section("DISCOVERED_FUTURE_WORK", futureContent));
     lines.push("");
+    // Review Recommendations
+    lines.push("## Review Recommendations");
+    const recommendationContent = pendingRecommendations.length === 0
+        ? "_No pending review recommendations._"
+        : table(["ID", "Kind", "Tickets", "Summary", "Rationale"], pendingRecommendations.map((rec) => [
+            String(rec.id ?? ""),
+            rec.kind,
+            parseTicketIds(rec.ticket_ids_json).join(", ") || "N/A",
+            rec.summary,
+            rec.rationale ?? "N/A",
+        ]));
+    lines.push(section("REVIEW_RECOMMENDATIONS", recommendationContent));
+    lines.push("");
     // Archive Index
     lines.push("## Archive Index");
     const archiveContent = archiveIndex.length === 0
@@ -207,6 +222,15 @@ export function renderProgressDoc(input) {
     lines.push("");
     return lines.join("\n");
 }
+function parseTicketIds(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
 export function writeProgressDoc(progressDocPath, content, atomic) {
     mkdirSync(dirname(progressDocPath), { recursive: true });
     if (atomic) {

package/dist/tickets/setupConfig.d.ts

@@ -0,0 +1,77 @@
+export declare const RAFI_CONFIG_FILE = "rafi-config.yaml";
+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 TicketPopulateAgentPreference = "configured" | "claude" | "codex";
+export type TicketPopulateEnrichmentPolicy = "none" | "recommendations" | "agent";
+export type TicketSourceConfig = {
+    type: "local";
+    paths: string[];
+} | {
+    type: "linear";
+    api_key_env: string;
+    team_key?: string | null;
+    filter?: string | null;
+} | {
+    type: "jira";
+    site: string;
+    email_env: string;
+    token_env: string;
+    jql: string;
+};
+export interface TicketPopulateSetupConfig {
+    source_handling: "saved" | "prompt" | "manual";
+    agent_preference: TicketPopulateAgentPreference;
+    import_cap: number;
+    comment_limit: number;
+    enrichment: TicketPopulateEnrichmentPolicy;
+    recommend_split_for_xl: boolean;
+}
+export interface TicketBuildSetupConfig {
+    branch_strategy: TicketBuildBranchStrategy;
+    completion: TicketBuildCompletionMode;
+    provider: TicketBuildProvider;
+    pr_ready: boolean;
+    merge_method: TicketBuildMergeMethod;
+    cleanup: boolean;
+    auto_merge_wait: boolean;
+    auto_merge_timeout_minutes: number | null;
+}
+export interface TicketsSetupConfig {
+    sources: TicketSourceConfig[];
+    populate: TicketPopulateSetupConfig;
+    build: TicketBuildSetupConfig;
+}
+export interface MinimalRafiConfigOptions {
+    appName?: string;
+    timezone?: string;
+    docsRoot?: string;
+    targets?: HarnessTarget[];
+}
+export declare const DEFAULT_TICKET_SETUP: TicketsSetupConfig;
+export declare function loadRafiConfigObject(projectDir: string): Record<string, unknown> | undefined;
+export declare function loadTicketSetupConfig(projectDir: string): TicketsSetupConfig | undefined;
+export declare function loadTicketSetupConfigWithDefaults(projectDir: string): TicketsSetupConfig;
+export declare function hasTicketSetupConfig(projectDir: string): boolean;
+export declare function saveTicketSetupConfig(projectDir: string, setup: TicketsSetupConfig, opts?: MinimalRafiConfigOptions): void;
+export declare function ensureRafiConfigForTicketSetup(projectDir: string, opts?: MinimalRafiConfigOptions): Record<string, unknown>;
+export declare function normalizeTicketsSetupConfig(value: unknown, label?: string): TicketsSetupConfig;
+export declare function denormalizeTicketsSetupConfig(setup: TicketsSetupConfig): Record<string, unknown>;
+export declare function mergeTicketSetup(current: TicketsSetupConfig | undefined, patch: Partial<{
+    sources: TicketSourceConfig[];
+    populate: Partial<TicketPopulateSetupConfig>;
+    build: Partial<TicketBuildSetupConfig>;
+}>): TicketsSetupConfig;
+export declare function localSourcePaths(setup: TicketsSetupConfig | undefined): string[];
+export declare function externalSources(setup: TicketsSetupConfig | undefined): Extract<TicketSourceConfig, {
+    type: "linear" | "jira";
+}>[];
+export declare function configuredDocsRoot(projectDir: string): string | undefined;
+export declare function configuredAppName(projectDir: string): string | undefined;
+export declare function configuredHarnessTargets(projectDir: string): HarnessTarget[] | undefined;
+export declare function detectPackageName(projectDir: string): string | undefined;
+export declare function defaultAppName(projectDir: string): string;
+export declare function detectGitProvider(projectDir: string): Exclude<TicketBuildProvider, "auto" | "local"> | undefined;
+export declare function recommendedBuildDefaults(projectDir: string): TicketBuildSetupConfig;

package/dist/tickets/setupConfig.js

@@ -0,0 +1,369 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+import { loadDefaults } from "special-agents";
+export const RAFI_CONFIG_FILE = "rafi-config.yaml";
+const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker"];
+const SKILL_NAMES = [
+    "better-sqlite3-rebuild",
+    "grill-me",
+    "improve-codebase-architecture",
+    "prd-to-issues",
+    "tdd",
+    "write-a-prd",
+];
+export const DEFAULT_TICKET_SETUP = {
+    sources: [],
+    populate: {
+        source_handling: "saved",
+        agent_preference: "configured",
+        import_cap: 500,
+        comment_limit: 10,
+        enrichment: "recommendations",
+        recommend_split_for_xl: true,
+    },
+    build: {
+        branch_strategy: "branch-per-ticket",
+        completion: "none",
+        provider: "auto",
+        pr_ready: false,
+        merge_method: "squash",
+        cleanup: true,
+        auto_merge_wait: false,
+        auto_merge_timeout_minutes: null,
+    },
+};
+export function loadRafiConfigObject(projectDir) {
+    const configPath = join(projectDir, RAFI_CONFIG_FILE);
+    if (!existsSync(configPath))
+        return undefined;
+    const raw = parse(readFileSync(configPath, "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${RAFI_CONFIG_FILE}: expected a YAML object`);
+    }
+    return raw;
+}
+export function loadTicketSetupConfig(projectDir) {
+    const raw = loadRafiConfigObject(projectDir);
+    if (!raw || raw.tickets === undefined)
+        return undefined;
+    return normalizeTicketsSetupConfig(raw.tickets, `${RAFI_CONFIG_FILE}.tickets`);
+}
+export function loadTicketSetupConfigWithDefaults(projectDir) {
+    return loadTicketSetupConfig(projectDir) ?? cloneTicketSetup(DEFAULT_TICKET_SETUP);
+}
+export function hasTicketSetupConfig(projectDir) {
+    const raw = loadRafiConfigObject(projectDir);
+    return Boolean(raw?.tickets);
+}
+export function saveTicketSetupConfig(projectDir, setup, opts = {}) {
+    const config = loadRafiConfigObject(projectDir) ?? minimalRafiConfig(projectDir, opts);
+    config.tickets = denormalizeTicketsSetupConfig(normalizeTicketsSetupConfig(setup, "tickets"));
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, RAFI_CONFIG_FILE), stringify(config, { lineWidth: 100 }), "utf8");
+}
+export function ensureRafiConfigForTicketSetup(projectDir, opts = {}) {
+    const existing = loadRafiConfigObject(projectDir);
+    if (existing)
+        return existing;
+    const config = minimalRafiConfig(projectDir, opts);
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, RAFI_CONFIG_FILE), stringify(config, { lineWidth: 100 }), "utf8");
+    return config;
+}
+export function normalizeTicketsSetupConfig(value, label = "tickets") {
+    if (value === undefined || value === null)
+        return cloneTicketSetup(DEFAULT_TICKET_SETUP);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label}: expected an object`);
+    }
+    const raw = value;
+    const setup = {
+        sources: normalizeSources(raw.sources, `${label}.sources`),
+        populate: normalizePopulate(raw.populate, `${label}.populate`),
+        build: normalizeBuild(raw.build, `${label}.build`),
+    };
+    return setup;
+}
+export function denormalizeTicketsSetupConfig(setup) {
+    return {
+        sources: setup.sources.map((source) => ({ ...source })),
+        populate: { ...setup.populate },
+        build: { ...setup.build },
+    };
+}
+export function mergeTicketSetup(current, patch) {
+    const base = current ? cloneTicketSetup(current) : cloneTicketSetup(DEFAULT_TICKET_SETUP);
+    return normalizeTicketsSetupConfig({
+        sources: patch.sources ?? base.sources,
+        populate: { ...base.populate, ...(patch.populate ?? {}) },
+        build: { ...base.build, ...(patch.build ?? {}) },
+    });
+}
+export function localSourcePaths(setup) {
+    return unique((setup?.sources ?? [])
+        .filter((source) => source.type === "local")
+        .flatMap((source) => source.paths));
+}
+export function externalSources(setup) {
+    return (setup?.sources ?? []).filter((source) => source.type === "linear" || source.type === "jira");
+}
+export function configuredDocsRoot(projectDir) {
+    const raw = loadRafiConfigObject(projectDir);
+    const docs = raw?.docs;
+    return typeof docs?.root === "string" ? docs.root : undefined;
+}
+export function configuredAppName(projectDir) {
+    const raw = loadRafiConfigObject(projectDir);
+    return typeof raw?.appName === "string" && raw.appName.trim() ? raw.appName : undefined;
+}
+export function configuredHarnessTargets(projectDir) {
+    const raw = loadRafiConfigObject(projectDir);
+    const harness = raw?.harness;
+    if (!Array.isArray(harness?.targets))
+        return undefined;
+    const targets = normalizeTargets(harness.targets);
+    return targets.length > 0 ? targets : undefined;
+}
+export function detectPackageName(projectDir) {
+    const pkgPath = join(projectDir, "package.json");
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return typeof pkg.name === "string" && pkg.name.trim() ? pkg.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function defaultAppName(projectDir) {
+    return configuredAppName(projectDir) ?? detectPackageName(projectDir) ?? "My App";
+}
+export function detectGitProvider(projectDir) {
+    try {
+        const remote = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim().toLowerCase();
+        if (remote.includes("github.com") || remote.includes("github."))
+            return "github";
+        if (remote.includes("gitlab.com") || remote.includes("gitlab."))
+            return "gitlab";
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+export function recommendedBuildDefaults(projectDir) {
+    const provider = detectGitProvider(projectDir);
+    return {
+        ...DEFAULT_TICKET_SETUP.build,
+        provider: provider ?? "local",
+        completion: provider ? "auto-merge" : "direct-merge",
+        pr_ready: Boolean(provider),
+        merge_method: "squash",
+        cleanup: true,
+    };
+}
+function minimalRafiConfig(projectDir, opts) {
+    const defaults = loadDefaults();
+    const docsRoot = opts.docsRoot ?? "docs";
+    const targets = normalizeTargets(opts.targets).length > 0 ? normalizeTargets(opts.targets) : ["claude", "codex"];
+    return {
+        appName: opts.appName ?? defaultAppName(projectDir),
+        timezone: opts.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC",
+        stack: {
+            frontend: defaults.stack.frontend,
+            backend: defaults.stack.backend,
+            database: defaults.stack.database,
+            cloud: defaults.stack.cloud,
+            packageManager: defaults.stack.packageManager,
+        },
+        flags: {
+            hasFrontend: Boolean(defaults.flags.hasFrontend),
+            usesAI: Boolean(defaults.flags.usesAI),
+            runsInCloud: Boolean(defaults.flags.runsInCloud),
+        },
+        harness: {
+            targets,
+            qa: true,
+        },
+        agent_files: {
+            mode: "overwrite",
+            codex: "./AGENTS.md",
+            claude: "./CLAUDE.md",
+        },
+        docs: {
+            root: docsRoot,
+        },
+        agents: Object.fromEntries(AGENT_NAMES.map((name) => [name, artifactPaths("agent", name)])),
+        skills: Object.fromEntries(SKILL_NAMES.map((name) => [name, artifactPaths("skill", name)])),
+    };
+}
+function artifactPaths(kind, name) {
+    if (kind === "agent") {
+        return {
+            artifact_source: "rafi",
+            claude: `./.claude/agents/${name}.md`,
+            codex: `./.codex/agents/${name}.toml`,
+        };
+    }
+    return {
+        artifact_source: "rafi",
+        claude: `./.claude/skills/${name}/SKILL.md`,
+        codex: `./.agents/skills/${name}/SKILL.md`,
+    };
+}
+function normalizeSources(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`${label}: expected an array`);
+    return value.map((item, index) => normalizeSource(item, `${label}[${index}]`));
+}
+function normalizeSource(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label}: expected an object`);
+    }
+    const raw = value;
+    if (raw.type === "local") {
+        if (!Array.isArray(raw.paths) || !raw.paths.every((path) => typeof path === "string" && path.trim())) {
+            throw new Error(`${label}.paths: expected non-empty string array`);
+        }
+        return { type: "local", paths: unique(raw.paths.map((path) => String(path).trim())) };
+    }
+    if (raw.type === "linear") {
+        return {
+            type: "linear",
+            api_key_env: stringField(raw.api_key_env, "LINEAR_API_KEY"),
+            team_key: nullableString(raw.team_key),
+            filter: nullableString(raw.filter),
+        };
+    }
+    if (raw.type === "jira") {
+        const site = stringField(raw.site);
+        const jql = stringField(raw.jql);
+        if (!site)
+            throw new Error(`${label}.site: expected a non-empty Jira Cloud site URL`);
+        if (!jql)
+            throw new Error(`${label}.jql: expected a non-empty JQL string`);
+        return {
+            type: "jira",
+            site: site.replace(/\/+$/, ""),
+            email_env: stringField(raw.email_env, "JIRA_EMAIL"),
+            token_env: stringField(raw.token_env, "JIRA_API_TOKEN"),
+            jql,
+        };
+    }
+    throw new Error(`${label}.type: expected local, linear, or jira`);
+}
+function normalizePopulate(value, label) {
+    const raw = objectOrEmpty(value, label);
+    return {
+        source_handling: enumField(raw.source_handling, ["saved", "prompt", "manual"], DEFAULT_TICKET_SETUP.populate.source_handling, `${label}.source_handling`),
+        agent_preference: enumField(raw.agent_preference, ["configured", "claude", "codex"], DEFAULT_TICKET_SETUP.populate.agent_preference, `${label}.agent_preference`),
+        import_cap: positiveInteger(raw.import_cap, DEFAULT_TICKET_SETUP.populate.import_cap, `${label}.import_cap`),
+        comment_limit: nonNegativeInteger(raw.comment_limit, DEFAULT_TICKET_SETUP.populate.comment_limit, `${label}.comment_limit`),
+        enrichment: enumField(raw.enrichment, ["none", "recommendations", "agent"], DEFAULT_TICKET_SETUP.populate.enrichment, `${label}.enrichment`),
+        recommend_split_for_xl: booleanField(raw.recommend_split_for_xl, DEFAULT_TICKET_SETUP.populate.recommend_split_for_xl, `${label}.recommend_split_for_xl`),
+    };
+}
+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`),
+        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`),
+        merge_method: enumField(raw.merge_method, ["squash", "merge", "rebase"], DEFAULT_TICKET_SETUP.build.merge_method, `${label}.merge_method`),
+        cleanup: booleanField(raw.cleanup, DEFAULT_TICKET_SETUP.build.cleanup, `${label}.cleanup`),
+        auto_merge_wait: booleanField(raw.auto_merge_wait, DEFAULT_TICKET_SETUP.build.auto_merge_wait, `${label}.auto_merge_wait`),
+        auto_merge_timeout_minutes: nullablePositiveInteger(raw.auto_merge_timeout_minutes, DEFAULT_TICKET_SETUP.build.auto_merge_timeout_minutes, `${label}.auto_merge_timeout_minutes`),
+    };
+}
+function objectOrEmpty(value, label) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label}: expected an object`);
+    }
+    return value;
+}
+function enumField(value, allowed, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === "string" && allowed.includes(value))
+        return value;
+    throw new Error(`${label}: expected one of ${allowed.join(", ")}`);
+}
+function stringField(value, fallback) {
+    if (value === undefined || value === null || value === "") {
+        if (fallback !== undefined)
+            return fallback;
+        return "";
+    }
+    if (typeof value !== "string" || !value.trim())
+        throw new Error("expected a non-empty string");
+    return value.trim();
+}
+function nullableString(value) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    if (typeof value !== "string")
+        throw new Error("expected a string or null");
+    return value.trim() || null;
+}
+function booleanField(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === "boolean")
+        return value;
+    throw new Error(`${label}: expected a boolean`);
+}
+function positiveInteger(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    if (Number.isInteger(value) && Number(value) > 0)
+        return Number(value);
+    throw new Error(`${label}: expected a positive integer`);
+}
+function nonNegativeInteger(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    if (Number.isInteger(value) && Number(value) >= 0)
+        return Number(value);
+    throw new Error(`${label}: expected a non-negative integer`);
+}
+function nullablePositiveInteger(value, fallback, label) {
+    if (value === undefined)
+        return fallback;
+    if (value === null)
+        return null;
+    if (Number.isInteger(value) && Number(value) > 0)
+        return Number(value);
+    throw new Error(`${label}: expected a positive integer or null`);
+}
+function normalizeTargets(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if ((item === "claude" || item === "codex") && !out.includes(item))
+            out.push(item);
+    }
+    return out;
+}
+function cloneTicketSetup(setup) {
+    return {
+        sources: setup.sources.map((source) => ({ ...source, ...(source.type === "local" ? { paths: [...source.paths] } : {}) })),
+        populate: { ...setup.populate },
+        build: { ...setup.build },
+    };
+}
+function unique(values) {
+    return [...new Set(values)];
+}