ai-foreman 1.7.4 → 1.7.6

package/dist/cli/tickets.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { select, text, confirm, isCancel } from "@clack/prompts";
+import { select, text, confirm, isCancel, multiselect } from "@clack/prompts";
 import { loadConfig } from "../config.js";
 import { Log } from "../log.js";
 import { Foreman } from "../foreman.js";
@@ -14,16 +14,33 @@ import { validateDocsRoot } from "../tickets/config.js";
 import { importExternalSources, importFromMarkdown, validateExternalSourceAccess } from "../tickets/importer.js";
 import { formatValidationIssues } from "../tickets/validate.js";
 import { assertEffortLevel, createRoleBuilder, makeLogPath, readOnlyPermissionConfig, } from "../agentRun.js";
-import { DEFAULT_TICKET_SETUP, configuredPlanningSources, defaultAppName, ensureRafiConfigForTicketSetup, externalSources, hasTicketSetupConfig, loadTicketSetupConfig, loadTicketSetupConfigWithDefaults, localSourcePaths, mergeTicketSetup, recommendedBuildDefaults, saveTicketSetupConfig, urlSources, } from "../tickets/setupConfig.js";
+import { DEFAULT_TICKET_SETUP, configuredPlanningSources, configuredAppName, defaultAppName, detectDefaultBranch, detectPackageName, ensureRafiConfigForTicketSetup, externalSources, hasTicketSetupConfig, loadTicketSetupConfig, loadTicketSetupConfigWithDefaults, localSourcePaths, mergeTicketSetup, recommendedBuildDefaults, saveTicketSetupConfig, syncTicketLimits, urlSources, } from "../tickets/setupConfig.js";
 import { fetchAndSnapshotUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { checkpointInterview, completeInterview, createInterviewRecord, failInterview, } from "../interviews.js";
 import { applyTicketPopulation, authorizeTicketRetirements, extractTicketPopulationProposal, materializeTicketPopulation, TICKET_POPULATION_PROPOSAL_END, TICKET_POPULATION_PROPOSAL_START } from "../ticketPopulation.js";
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { resolveTicketPaths } from "../tickets/config.js";
+import { formatTicketDetails, getTicketDetails } from "../tickets/details.js";
+import { previewTicketReset, recoverTicketResetPublications, resetTickets } from "../tickets/reset.js";
+let nestedTicketCommandDepth = 0;
+class TicketInterviewCancelled extends Error {
+}
+function cancelTicketInterview() { throw new TicketInterviewCancelled("ticket interview cancelled"); }
 function fail(msg) {
+    if (nestedTicketCommandDepth > 0)
+        throw new Error(msg);
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
 }
+async function runNestedTicketCommand(action) {
+    nestedTicketCommandDepth += 1;
+    try {
+        return await action();
+    }
+    finally {
+        nestedTicketCommandDepth -= 1;
+    }
+}
 function cwd(opts) {
     return resolve(opts.project ?? ".");
 }
@@ -148,6 +165,8 @@ async function cmdSetupInitCli(opts) {
     if (hasTicketSetupConfig(dir)) {
         console.log("foreman tickets setup: existing setup found; opening setup:update");
         await cmdSetupUpdateCli(opts);
+        const existing = loadTicketSetupConfigWithDefaults(dir);
+        await continueTrackerSetup(dir, opts, existing);
         if (interview)
             completeInterview(dir, interview);
         return;
@@ -168,41 +187,74 @@ async function cmdSetupInitCli(opts) {
             targets: parseRuntimeTargets(opts.runtime),
         });
         console.log(`foreman tickets setup: saved ticket setup in ${join(dir, "rafi-config.yaml")}`);
-        if (!isTicketsInitialized(dir)) {
-            if (interview)
-                interview = checkpointInterview(dir, interview, { checkpoint: "initialize-tracker" });
-            cmdInit(dir, {
-                appName: opts.appName ?? defaultAppName(dir),
-                timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-                docsRoot: opts.docsRoot,
-            });
-            console.log("foreman tickets setup: initialized .tickets/");
-        }
-        if (shouldPrompt(opts)) {
-            if (interview)
-                interview = checkpointInterview(dir, interview, { checkpoint: "populate-confirmation" });
-            const populate = await confirm({
-                message: "Run ticket population now?",
-                initialValue: answers.sources.length > 0,
-            });
-            if (isCancel(populate))
-                return;
-            if (populate) {
-                await cmdPopulateCli({ project: dir, yes: true });
-            }
-        }
-        else {
-            console.log(`foreman tickets setup: next — run \`foreman tickets populate --project ${shellQuote(dir)}\``);
-        }
+        if (interview)
+            interview = checkpointInterview(dir, interview, { checkpoint: "initialize-tracker" });
+        await continueTrackerSetup(dir, opts, answers);
         if (interview)
             completeInterview(dir, interview);
     }
     catch (error) {
-        if (interview)
+        if (interview && !(error instanceof TicketInterviewCancelled))
             failInterview(dir, interview, interview.checkpoint, error);
         throw error;
     }
 }
+async function continueTrackerSetup(dir, opts, setup) {
+    if (!isTicketsInitialized(dir)) {
+        let initialize = true;
+        if (shouldPrompt(opts)) {
+            const answer = await confirm({ message: "Initialize the ticket tracker now?", initialValue: true });
+            if (isCancel(answer))
+                return;
+            initialize = Boolean(answer);
+        }
+        if (!initialize) {
+            console.log("foreman tickets setup: preferences were saved. Ticket infrastructure is still required before building.");
+            console.log(`  rafi tickets init --project ${shellQuote(dir)}`);
+            console.log(`  rafi tickets populate --project ${shellQuote(dir)}`);
+            return;
+        }
+        const initialized = await retrySetupStage("ticket initialization", async () => {
+            const appName = opts.appName ?? await resolveInitAppName(dir, Boolean(opts.yes || opts.defaults));
+            cmdInit(dir, { appName, timezone: Intl.DateTimeFormat().resolvedOptions().timeZone, docsRoot: opts.docsRoot, implementationLimit: setup.limits.implementation, viewLimit: setup.limits.view });
+            syncTicketLimits(dir, setup.limits);
+        }, shouldPrompt(opts));
+        if (!initialized)
+            return;
+        console.log("foreman tickets setup: initialized .tickets/");
+    }
+    if (shouldPrompt(opts)) {
+        const populate = await confirm({ message: "Populate tickets now?", initialValue: true });
+        if (isCancel(populate))
+            return;
+        if (populate)
+            await retrySetupStage("ticket population", () => runNestedTicketCommand(() => cmdPopulateCli({ project: dir, yes: true })), true);
+        else {
+            console.log("foreman tickets setup: population is the final prerequisite before building.");
+            console.log(`foreman tickets setup: run \`rafi tickets populate --project ${shellQuote(dir)}\` later.`);
+        }
+    }
+    else {
+        console.log(`foreman tickets setup: next — run \`rafi tickets populate --project ${shellQuote(dir)}\``);
+    }
+}
+async function retrySetupStage(label, action, interactive) {
+    while (true) {
+        try {
+            await action();
+            return true;
+        }
+        catch (error) {
+            if (!interactive)
+                throw error;
+            console.error(`foreman tickets setup: ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+            console.error("Fix the reported problem, then press Enter to retry; enter q to leave setup with saved progress.");
+            const answer = await text({ message: `Retry ${label}?`, defaultValue: "" });
+            if (isCancel(answer) || String(answer).trim().toLowerCase() === "q")
+                return false;
+        }
+    }
+}
 async function cmdSetupUpdateCli(opts) {
     const dir = cwd(opts);
     if (!existsSync(dir))
@@ -225,6 +277,7 @@ async function cmdSetupUpdateCli(opts) {
             docsRoot: opts.docsRoot,
             targets: parseRuntimeTargets(opts.runtime),
         });
+        syncTicketLimits(dir, next.limits);
         console.log(`foreman tickets setup: updated ticket setup in ${join(dir, "rafi-config.yaml")}`);
         if (isTicketsInitialized(dir)) {
             const rows = cmdQueue(dir, 1);
@@ -236,7 +289,7 @@ async function cmdSetupUpdateCli(opts) {
             completeInterview(dir, interview);
     }
     catch (error) {
-        if (interview)
+        if (interview && !(error instanceof TicketInterviewCancelled))
             failInterview(dir, interview, interview.checkpoint, error);
         throw error;
     }
@@ -302,38 +355,107 @@ async function collectTicketSetupPatch(dir, opts, current) {
             { value: "sources", label: "Ticket sources" },
             { value: "populate", label: "Populate defaults" },
             { value: "build", label: "Build defaults" },
+            { value: "limits", label: "Tracker limits" },
             { value: "all", label: "All sections" },
         ],
     });
     if (isCancel(section))
-        process.exit(0);
+        cancelTicketInterview();
     // Do not silently persist planning hints over a completed ticket setup. They
     // are only the initial local-source suggestion for a fresh setup.
     const planningPrefill = current.sources.length === 0
         ? configuredPlanningSources(dir).map((path) => ({ type: "local", paths: [path] }))
         : current.sources;
     let sources = nonInteractiveSources.length > 0 ? nonInteractiveSources : planningPrefill;
+    let limits = current.limits;
     if (section === "sources" || section === "all") {
         sources = await promptTicketSources(dir, current.sources);
     }
+    if (section === "limits" || section === "all") {
+        console.log("The defaults are a 500-ticket implementation window and a 20,000-ticket view limit. After initialization these live in .tickets/config.yaml.");
+        const keep = await confirm({ message: "Keep both default limits?", initialValue: true });
+        if (isCancel(keep))
+            cancelTicketInterview();
+        limits = keep ? { implementation: 500, view: 20_000 } : {
+            implementation: await promptPositiveInteger("Implementation window limit:", current.limits.implementation),
+            view: await promptPositiveInteger("View limit:", current.limits.view),
+        };
+    }
     if (section === "populate" || section === "all") {
-        const agent = await select({
-            message: "When both runtimes are configured, which should populate use?",
-            initialValue: current.populate.agent_preference,
-            options: [
-                { value: "configured", label: "Configured project default" },
-                { value: "claude", label: "Claude" },
-                { value: "codex", label: "Codex" },
-            ],
-        });
-        if (isCancel(agent))
-            process.exit(0);
-        populatePatch.agent_preference = agent;
+        const defaults = await confirm({ message: "Use the recommended population settings?", initialValue: true });
+        if (isCancel(defaults))
+            cancelTicketInterview();
+        if (defaults)
+            Object.assign(populatePatch, DEFAULT_TICKET_SETUP.populate);
+        else {
+            const handling = await select({ message: "How should saved sources be handled?", initialValue: current.populate.source_handling, options: [
+                    { value: "saved", label: "Use saved sources" }, { value: "prompt", label: "Ask each time" }, { value: "manual", label: "Manual only" },
+                ] });
+            if (isCancel(handling))
+                cancelTicketInterview();
+            populatePatch.source_handling = handling;
+            const agent = await select({ message: "When both runtimes are configured, which should populate use?", initialValue: current.populate.agent_preference, options: [
+                    { value: "configured", label: "Configured project default" }, { value: "claude", label: "Claude" }, { value: "codex", label: "Codex" },
+                ] });
+            if (isCancel(agent))
+                cancelTicketInterview();
+            populatePatch.agent_preference = agent;
+            populatePatch.import_cap = await promptPositiveInteger("Maximum tickets imported in one population run (separate from the implementation window):", current.populate.import_cap);
+            populatePatch.comment_limit = await promptNonNegativeInteger("Maximum comments imported per external ticket:", current.populate.comment_limit);
+            const enrichment = await select({ message: "Population enrichment policy:", initialValue: current.populate.enrichment, options: [
+                    { value: "recommendations", label: "Deterministic recommendations" }, { value: "agent", label: "Agent enrichment" }, { value: "none", label: "No enrichment" },
+                ] });
+            if (isCancel(enrichment))
+                cancelTicketInterview();
+            populatePatch.enrichment = enrichment;
+            const split = await confirm({ message: "Recommend splitting XL tickets?", initialValue: current.populate.recommend_split_for_xl });
+            if (isCancel(split))
+                cancelTicketInterview();
+            populatePatch.recommend_split_for_xl = Boolean(split);
+        }
     }
     if (section === "build" || section === "all") {
         const recommended = recommendedBuildDefaults(dir);
-        const strategy = await select({
-            message: "Default ticket work mode:",
+        const base = await text({ message: "Base branch:", initialValue: current.build.base_branch || detectDefaultBranch(dir), defaultValue: detectDefaultBranch(dir) });
+        if (isCancel(base))
+            cancelTicketInterview();
+        buildPatch.base_branch = String(base).trim();
+        const policyMode = await select({ message: "Use one global branch strategy or choose by inferred ticket size?", initialValue: current.build.branch_policy.mode, options: [
+                { value: "size", label: "Size-based: XS/S shared, M/L/XL per ticket (Recommended)" },
+                { value: "global", label: "One global strategy" },
+            ] });
+        if (isCancel(policyMode))
+            cancelTicketInterview();
+        let sizeMapping = { XS: "shared", S: "shared", M: "per-ticket", L: "per-ticket", XL: "per-ticket" };
+        if (policyMode === "size") {
+            console.log("Rafi infers size from each canonical ticket. Recommended mapping: XS/S share a compatible run branch; M/L/XL use one branch per ticket. This never creates stack dependencies, and explicit delivery configuration wins.");
+            const keepMapping = await confirm({ message: "Keep the recommended size mapping?", initialValue: true });
+            if (isCancel(keepMapping))
+                cancelTicketInterview();
+            if (!keepMapping) {
+                sizeMapping = { ...sizeMapping };
+                for (const size of ["XS", "S", "M", "L", "XL"]) {
+                    const allocation = await select({
+                        message: `${size} ticket branch allocation:`,
+                        initialValue: current.build.branch_policy.by_size[size],
+                        options: [
+                            { value: "shared", label: "Share with compatible tickets selected in this run" },
+                            { value: "per-ticket", label: "Use a separate branch per ticket" },
+                        ],
+                    });
+                    if (isCancel(allocation))
+                        cancelTicketInterview();
+                    sizeMapping[size] = allocation;
+                }
+            }
+        }
+        buildPatch.branch_policy = {
+            ...current.build.branch_policy,
+            mode: policyMode,
+            by_size: policyMode === "size" ? sizeMapping : current.build.branch_policy.by_size,
+        };
+        const strategy = policyMode === "size" ? "branch-per-ticket" : await select({
+            message: "Default global ticket work mode:",
             initialValue: current.build.branch_strategy,
             options: [
                 { value: "current", label: "One branch - work the queue on the current branch" },
@@ -342,8 +464,9 @@ async function collectTicketSetupPatch(dir, opts, current) {
             ],
         });
         if (isCancel(strategy))
-            process.exit(0);
+            cancelTicketInterview();
         buildPatch.branch_strategy = strategy;
+        buildPatch.branch_policy.global_strategy = buildPatch.branch_strategy;
         if (strategy === "current") {
             buildPatch.completion = "none";
             buildPatch.provider = "local";
@@ -352,8 +475,10 @@ async function collectTicketSetupPatch(dir, opts, current) {
             buildPatch.cleanup = true;
             buildPatch.auto_merge_wait = false;
             buildPatch.auto_merge_timeout_minutes = null;
+            buildPatch.validation_checklist = await promptRequirementList("validation checklist", current.build.validation_checklist);
             return {
                 sources,
+                limits,
                 populate: populatePatch,
                 build: buildPatch,
             };
@@ -369,19 +494,43 @@ async function collectTicketSetupPatch(dir, opts, current) {
             ],
         });
         if (isCancel(completion))
-            process.exit(0);
+            cancelTicketInterview();
         buildPatch.completion = completion;
         buildPatch.provider = recommended.provider;
         buildPatch.pr_ready = completion === "auto-merge";
         buildPatch.merge_method = "squash";
         buildPatch.cleanup = true;
+        if (completion === "pr" || completion === "auto-merge") {
+            const title = await select({ message: "PR/MR title standard:", initialValue: current.build.review.title_style, options: [
+                    { value: "ticket-title", label: "T123: Add password reset (Recommended)" },
+                    { value: "conventional", label: "Conventional Commit" },
+                    { value: "none", label: "No required format" },
+                    { value: "custom", label: "Custom template" },
+                ] });
+            if (isCancel(title))
+                cancelTicketInterview();
+            let template = null;
+            if (title === "custom") {
+                const answer = await text({ message: "Custom title template (use {id} and {title}):" });
+                if (isCancel(answer))
+                    cancelTicketInterview();
+                template = String(answer);
+            }
+            buildPatch.review = {
+                ...current.build.review,
+                title_style: title,
+                title_template: template,
+                description_sections: await promptRequirementList("required PR/MR description sections", current.build.review.description_sections),
+            };
+        }
+        buildPatch.validation_checklist = await promptRequirementList("validation checklist", current.build.validation_checklist);
         if (completion === "auto-merge") {
             const wait = await confirm({
                 message: "Wait for dependency PR/MRs to merge before starting dependent tickets?",
                 initialValue: current.build.auto_merge_wait,
             });
             if (isCancel(wait))
-                process.exit(0);
+                cancelTicketInterview();
             buildPatch.auto_merge_wait = Boolean(wait);
             if (wait) {
                 const timeout = await text({
@@ -397,7 +546,7 @@ async function collectTicketSetupPatch(dir, opts, current) {
                     },
                 });
                 if (isCancel(timeout))
-                    process.exit(0);
+                    cancelTicketInterview();
                 buildPatch.auto_merge_timeout_minutes = String(timeout).trim()
                     ? Number.parseInt(String(timeout).trim(), 10)
                     : null;
@@ -413,10 +562,60 @@ async function collectTicketSetupPatch(dir, opts, current) {
     }
     return {
         sources,
+        limits,
         populate: populatePatch,
         build: buildPatch,
     };
 }
+async function promptPositiveInteger(message, initial) {
+    const answer = await text({ message, initialValue: String(initial), defaultValue: String(initial), validate: (value) => Number.isInteger(Number(value)) && Number(value) > 0 ? undefined : "Enter a positive integer" });
+    if (isCancel(answer))
+        cancelTicketInterview();
+    return Number(answer);
+}
+async function promptNonNegativeInteger(message, initial) {
+    const answer = await text({ message, initialValue: String(initial), defaultValue: String(initial), validate: (value) => Number.isInteger(Number(value)) && Number(value) >= 0 ? undefined : "Enter zero or a positive integer" });
+    if (isCancel(answer))
+        cancelTicketInterview();
+    return Number(answer);
+}
+async function promptRequirementList(label, initial) {
+    console.log(`Current recommended ${label}: ${initial.join("; ") || "none"}`);
+    const mode = await select({
+        message: `How should Rafi configure the ${label}?`,
+        initialValue: "keep",
+        options: [
+            { value: "keep", label: "Keep all listed requirements (Recommended)" },
+            { value: "choose", label: "Choose individual requirements and optionally add custom ones" },
+            { value: "replace", label: "Replace with a custom list" },
+        ],
+    });
+    if (isCancel(mode))
+        cancelTicketInterview();
+    if (mode === "keep")
+        return [...initial];
+    if (mode === "replace") {
+        const replacement = await text({ message: `Custom ${label} (comma-separated):`, defaultValue: "" });
+        if (isCancel(replacement))
+            cancelTicketInterview();
+        return splitCommaList(String(replacement));
+    }
+    const selected = initial.length ? await multiselect({
+        message: `Select the ${label} to keep:`,
+        options: initial.map((value) => ({ value, label: value })),
+        initialValues: initial,
+        required: false,
+    }) : [];
+    if (isCancel(selected))
+        cancelTicketInterview();
+    const additions = await text({ message: `Additional custom ${label} (comma-separated, optional):`, defaultValue: "" });
+    if (isCancel(additions))
+        cancelTicketInterview();
+    return combineRequirementSelections(selected, String(additions));
+}
+export function combineRequirementSelections(selected, additions) {
+    return [...new Set([...selected, ...splitCommaList(additions)])];
+}
 async function promptTicketSources(dir, current) {
     const kind = await select({
         message: "Primary ticket source:",
@@ -429,7 +628,7 @@ async function promptTicketSources(dir, current) {
         ],
     });
     if (isCancel(kind))
-        process.exit(0);
+        cancelTicketInterview();
     if (kind === "none")
         return [];
     if (kind === "local") {
@@ -440,16 +639,16 @@ async function promptTicketSources(dir, current) {
             defaultValue: existing?.paths.join(", ") || `${configuredDocsPlanPath(dir)}`,
         });
         if (isCancel(answer))
-            process.exit(0);
+            cancelTicketInterview();
         return [{ type: "local", paths: splitCommaList(String(answer)) }];
     }
     if (kind === "linear") {
         const team = await text({ message: "Linear team key (optional):" });
         if (isCancel(team))
-            process.exit(0);
+            cancelTicketInterview();
         const filter = await text({ message: "Linear IssueFilter JSON or title search text (optional):" });
         if (isCancel(filter))
-            process.exit(0);
+            cancelTicketInterview();
         return [{
                 type: "linear",
                 api_key_env: "LINEAR_API_KEY",
@@ -465,7 +664,7 @@ async function promptTicketSources(dir, current) {
             validate: (value) => /^https?:\/\//i.test(String(value ?? "")) ? undefined : "Enter an HTTP(S) URL",
         });
         if (isCancel(answer))
-            process.exit(0);
+            cancelTicketInterview();
         return [{ type: "url", url: String(answer).trim() }];
     }
     const site = await text({
@@ -474,14 +673,14 @@ async function promptTicketSources(dir, current) {
         validate: (value) => String(value ?? "").trim() ? undefined : "Enter a Jira Cloud site URL",
     });
     if (isCancel(site))
-        process.exit(0);
+        cancelTicketInterview();
     const jql = await text({
         message: "Jira JQL:",
         initialValue: "resolution = Unresolved ORDER BY priority DESC, updated DESC",
         defaultValue: "resolution = Unresolved ORDER BY priority DESC, updated DESC",
     });
     if (isCancel(jql))
-        process.exit(0);
+        cancelTicketInterview();
     return [{
             type: "jira",
             site: String(site).trim(),
@@ -568,6 +767,11 @@ function parseAgentPreference(value) {
         return value;
     fail("--agent-preference must be one of: configured, claude, codex");
 }
+function parseResetScope(value) {
+    if (["all", "completed-and-unfinished", "unfinished"].includes(value))
+        return value;
+    throw new Error("--scope must be all, completed-and-unfinished, or unfinished");
+}
 function parseOptionalPositiveInteger(value, label) {
     if (!value.trim())
         return null;
@@ -599,19 +803,20 @@ function configuredDocsPlanPath(dir) {
     return "docs/rafi-plan.md";
 }
 async function resolveInitAppName(dir, yes) {
-    const configured = defaultAppName(dir);
-    if (configured !== "My App")
-        return configured;
+    const established = configuredAppName(dir);
+    if (established)
+        return established;
+    const detected = detectPackageName(dir) ?? "My App";
     if (yes || !process.stdin.isTTY || !process.stdout.isTTY)
-        return configured;
+        return detected;
     const answer = await text({
         message: "App name:",
-        initialValue: configured,
-        defaultValue: configured,
+        initialValue: detected,
+        defaultValue: detected,
     });
     if (isCancel(answer))
-        process.exit(0);
-    return String(answer).trim() || configured;
+        cancelTicketInterview();
+    return String(answer).trim() || detected;
 }
 async function resolvePopulateSourceSelection(dir, explicitSources, ticketsConfig, yes) {
     if (explicitSources?.length)
@@ -629,7 +834,7 @@ async function resolvePopulateSourceSelection(dir, explicitSources, ticketsConfi
             initialValue: true,
         });
         if (isCancel(usePlan))
-            process.exit(0);
+            return undefined;
         return usePlan ? defaultPlan : undefined;
     }
     if (yes || !process.stdin.isTTY || !process.stdout.isTTY) {
@@ -639,7 +844,7 @@ async function resolvePopulateSourceSelection(dir, explicitSources, ticketsConfi
         console.log("  rafi tickets setup:init");
         console.log("  rafi tickets populate --sources <files-or-globs>");
         console.log("  edit .tickets/tickets.yaml manually");
-        process.exit(2);
+        throw new Error("no ticket sources were found; create a plan, configure sources, or pass --sources");
     }
     const action = await select({
         message: "No ticket sources were found. What should happen next?",
@@ -652,22 +857,22 @@ async function resolvePopulateSourceSelection(dir, explicitSources, ticketsConfi
     });
     if (isCancel(action) || action === "none") {
         console.log("foreman tickets: cancelled");
-        process.exit(0);
+        return undefined;
     }
     if (action === "setup") {
         await cmdSetupInitCli({ project: dir });
-        process.exit(0);
+        return undefined;
     }
     if (action === "plan") {
         console.log(`foreman tickets: run \`rafi plan ${shellQuote(dir)}\`, then \`rafi tickets populate --project ${shellQuote(dir)}\`.`);
-        process.exit(0);
+        return undefined;
     }
     const entered = await text({
         message: "Source paths or globs, comma-separated:",
         validate: (value) => String(value ?? "").trim() ? undefined : "Enter at least one source path or glob",
     });
     if (isCancel(entered))
-        process.exit(0);
+        return undefined;
     return splitCommaList(String(entered));
 }
 function reviewActionFromOptions(opts) {
@@ -733,7 +938,7 @@ export async function cmdPopulateCli(opts) {
             });
             if (isCancel(action) || action === "cancel") {
                 console.log("foreman tickets: cancelled");
-                process.exit(0);
+                return;
             }
         }
         const results = await importExternalSources(dir, configuredExternalSources, {
@@ -751,7 +956,7 @@ export async function cmdPopulateCli(opts) {
             console.log(`foreman tickets: ${validation.issues.length} validation issue(s) found:`);
             console.log(formatValidationIssues(validation.issues));
             if (!validation.clean)
-                process.exit(1);
+                throw new Error("external ticket import failed tracker validation");
         }
         if (!sourceHints.length) {
             console.log(`foreman tickets: imported external tickets and rendered ${ticketsConfig.paths.progressDoc}`);
@@ -769,7 +974,7 @@ export async function cmdPopulateCli(opts) {
         });
         if (isCancel(action) || action === "cancel") {
             console.log("foreman tickets: cancelled");
-            process.exit(0);
+            return;
         }
     }
     const logPath = makeLogPath(dir, "tickets-populate");
@@ -811,12 +1016,10 @@ export async function cmdPopulateCli(opts) {
             fail(`builder turn errored: ${turn.result.text.slice(0, 200)}`);
         }
         if (turn.status.kind === "blocked") {
-            console.error(`foreman tickets: blocked — ${turn.status.reason ?? "builder reported blocked"}`);
-            process.exit(2);
+            throw new Error(`blocked — ${turn.status.reason ?? "builder reported blocked"}`);
         }
         if (turn.status.kind !== "done" && turn.status.kind !== "plan_complete") {
-            console.error(`foreman tickets: needs human — ${turn.status.error ?? "builder did not emit done"}`);
-            process.exit(2);
+            throw new Error(`needs human — ${turn.status.error ?? "builder did not emit done"}`);
         }
         const existing = loadTickets(resolveTicketPaths(ticketsConfig, dir).tickets);
         const proposal = extractTicketPopulationProposal(turn.result.text);
@@ -874,8 +1077,37 @@ function loadPopulationPlan(projectDir, sources) {
     }
     throw new Error("ticket population requires the approved paired structured plan (normally docs/rafi-plan.json); run `rafi plan --validate` first");
 }
-export function buildTicketsCommand() {
+function ticketOwnershipReceipts(projectDir, commandName, _afterWrite) {
+    const candidates = [
+        ".tickets/config.yaml", ".tickets/tickets.yaml", ".tickets/delivery.yaml", ".tickets/tracker-rules.md",
+        ".tickets/schema/tickets.schema.json", ".tickets/migrations/001_init.sql", ".tickets/.gitignore",
+    ];
+    if (isTicketsInitialized(projectDir)) {
+        const config = loadTicketsConfig(projectDir);
+        candidates.push(config.paths.progressDoc, config.paths.archiveDoc);
+    }
+    else {
+        candidates.push(DEFAULT_TICKETS_CONFIG.paths.progressDoc, DEFAULT_TICKETS_CONFIG.paths.archiveDoc);
+    }
+    return unique(candidates).filter((path) => existsSync(join(projectDir, path))).map((path) => ({ path, category: "tickets", origin: `tickets:${commandName}` }));
+}
+export function buildTicketsCommand(options = {}) {
     const tickets = new Command("tickets").description("Manage the structured ticket tracker for a project.");
+    tickets.hook("preAction", (_thisCommand, actionCommand) => {
+        const commandOptions = actionCommand.opts();
+        const projectDir = cwd(commandOptions);
+        recoverTicketResetPublications(projectDir);
+        if (options.prepareOwnership && !["show", "validate", "queue"].includes(actionCommand.name())) {
+            options.prepareOwnership(projectDir, ticketOwnershipReceipts(projectDir, actionCommand.name(), false));
+        }
+    });
+    tickets.hook("postAction", (_thisCommand, actionCommand) => {
+        if (!options.recordOwnership)
+            return;
+        const commandOptions = actionCommand.opts();
+        const projectDir = cwd(commandOptions);
+        options.recordOwnership(projectDir, ticketOwnershipReceipts(projectDir, actionCommand.name(), true));
+    });
     // ── setup:init / setup:update ─────────────────────────────────────────────
     tickets
         .command("setup:init")
@@ -905,6 +1137,10 @@ export function buildTicketsCommand() {
             await cmdSetupInitCli(opts);
         }
         catch (err) {
+            if (err instanceof TicketInterviewCancelled) {
+                console.log("foreman tickets setup: cancelled; saved checkpoints were retained");
+                return;
+            }
             fail(String(err instanceof Error ? err.message : err));
         }
     });
@@ -936,6 +1172,10 @@ export function buildTicketsCommand() {
             await cmdSetupUpdateCli(opts);
         }
         catch (err) {
+            if (err instanceof TicketInterviewCancelled) {
+                console.log("foreman tickets setup: cancelled; saved checkpoints were retained");
+                return;
+            }
             fail(String(err instanceof Error ? err.message : err));
         }
     });
@@ -969,9 +1209,24 @@ export function buildTicketsCommand() {
                 docsRoot: opts.docsRoot,
             });
             console.log(`foreman tickets: initialized .tickets/ in ${dir}`);
-            console.log(`foreman tickets: next — add tickets to .tickets/tickets.yaml and run \`foreman tickets render\``);
+            if (shouldPrompt(opts)) {
+                const populate = await confirm({ message: "Populate tickets now?", initialValue: true });
+                if (!isCancel(populate) && populate)
+                    await runNestedTicketCommand(() => cmdPopulateCli({ project: dir }));
+                else {
+                    console.log("foreman tickets: population is the final prerequisite before building.");
+                    console.log(`foreman tickets: run \`rafi tickets populate --project ${shellQuote(dir)}\` later.`);
+                }
+            }
+            else {
+                console.log(`foreman tickets: next — run \`rafi tickets populate --project ${shellQuote(dir)}\``);
+            }
         }
         catch (err) {
+            if (err instanceof TicketInterviewCancelled) {
+                console.log("foreman tickets: initialization cancelled; no process exit was forced by the nested interview");
+                return;
+            }
             fail(String(err instanceof Error ? err.message : err));
         }
     });
@@ -996,6 +1251,90 @@ export function buildTicketsCommand() {
         }
     });
     // ── update ──────────────────────────────────────────────────────────────────
+    tickets
+        .command("show <ticketId>")
+        .description("Show the complete canonical ticket, active state, validation, delivery, and history.")
+        .option("-p, --project <dir>", "project directory (default: cwd)")
+        .option("--json", "write the complete stable record as JSON")
+        .action((ticketId, opts) => {
+        try {
+            const details = getTicketDetails(cwd(opts), ticketId);
+            if (opts.json)
+                process.stdout.write(`${JSON.stringify(details, null, 2)}\n`);
+            else
+                for (const line of formatTicketDetails(details))
+                    console.log(line);
+        }
+        catch (err) {
+            fail(String(err instanceof Error ? err.message : err));
+        }
+    });
+    tickets
+        .command("reset [ticketId]")
+        .description("Reset one ticket or an explicit ticket scope to pristine active state while retaining history.")
+        .option("-p, --project <dir>", "project directory (default: cwd)")
+        .option("--all", "open the interactive bulk reset scope chooser")
+        .option("--scope <scope>", "bulk scope (all | completed-and-unfinished | unfinished)")
+        .option("--actor <actor>", "who requested the reset", "user")
+        .option("-y, --yes", "confirm an explicit ticket or --scope without prompting")
+        .action(async (ticketId, opts) => {
+        try {
+            if (ticketId && (opts.all || opts.scope))
+                throw new Error("provide a ticket ID or a bulk scope, not both");
+            if (!ticketId && !opts.all && !opts.scope)
+                throw new Error("provide <ticketId>, --all, or --scope <scope>");
+            let target = ticketId;
+            if (opts.scope)
+                target = parseResetScope(String(opts.scope));
+            if (opts.all && !opts.scope) {
+                if (!process.stdin.isTTY || !process.stdout.isTTY)
+                    throw new Error("--all requires an interactive terminal; use --scope <scope> --yes for automation");
+                const answer = await select({
+                    message: "Which tickets should return to an unworked state?",
+                    options: [
+                        { value: "all", label: "All tickets" },
+                        { value: "completed-and-unfinished", label: "Completed and unfinished (exclude canceled/obsolete)" },
+                        { value: "unfinished", label: "Unfinished only (exclude done/canceled/obsolete)" },
+                    ],
+                });
+                if (isCancel(answer)) {
+                    console.log("foreman tickets: reset cancelled; nothing changed");
+                    return;
+                }
+                target = answer;
+            }
+            if (!target)
+                throw new Error("reset target was not selected");
+            const preview = previewTicketReset(cwd(opts), target);
+            console.log(`foreman tickets reset preview (${preview.scope}):`);
+            if (!preview.tickets.length)
+                console.log("  (no matching tickets)");
+            for (const row of preview.tickets)
+                console.log(`  ${row.id}: ${row.title} [${row.status}] — clears ${row.cleared.join(", ")}`);
+            if (preview.relatedRuns.length) {
+                console.log("  ! Matching build/recovery metadata is not deleted. Use `rafi build:start-over` for a coherent whole-run restart.");
+                for (const run of preview.relatedRuns)
+                    console.log(`    ${run.runId.slice(0, 8)} [${run.status}] ${run.tickets.join(", ")}`);
+            }
+            if (!preview.tickets.length)
+                return;
+            const explicitlyConfirmed = Boolean(opts.yes && (ticketId || opts.scope));
+            if (!explicitlyConfirmed) {
+                if (!process.stdin.isTTY || !process.stdout.isTTY)
+                    throw new Error("confirmation requires a TTY; pass --yes with an explicit ticket or --scope");
+                const approved = await confirm({ message: `Reset ${preview.tickets.length} ticket(s)? Historical events and validation remain available.`, initialValue: false });
+                if (isCancel(approved) || !approved) {
+                    console.log("foreman tickets: reset cancelled; nothing changed");
+                    return;
+                }
+            }
+            const result = resetTickets(cwd(opts), target, String(opts.actor));
+            console.log(`foreman tickets: reset ${result.tickets.length} ticket(s) (audit ${result.resetId})`);
+        }
+        catch (err) {
+            fail(String(err instanceof Error ? err.message : err));
+        }
+    });
     tickets
         .command("update <ticketId>")
         .description("Update ticket status or progress fields.")