ai-foreman 1.7.4 → 1.7.6

package/dist/cli/start.js

@@ -17,19 +17,22 @@ import { resolveAgentForProject } from "./runtimeSelection.js";
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../tickets/config.js";
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
-import { applySharedDeliveryBranch, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
-import { collectBaseWorktreeDirtyPaths, currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
+import { applySharedDeliveryBranch, applySizeBranchPolicy, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
+import { 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";
-import { checkpointBuildRun, completeBuildRun, createBuildRun, heartbeatBuildRun, persistBuildSession, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
+import { branchPlanLogMetadata, presentBranchPlan } from "../branch/presentation.js";
+import { checkpointBuildRun, completeBuildRun, createBuildRun, heartbeatBuildRun, persistBuildSession, projectBuildRecovery, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
 import { parse as parseYaml } from "yaml";
 import { findResumableBranchSessions, formatBranchContinueCommand, formatBranchSummaryFollowupCommands, } from "../branch/resume.js";
 import { detectGitProvider, loadTicketSetupConfig } from "../tickets/setupConfig.js";
 import { loadDeliveryConfig, selectDeliveryUnitForRun, selectStacksForRun, updateStackDeliveryState } from "../tickets/delivery.js";
 import { AgentStatusReporter } from "../statusReporter.js";
-import { WorkflowDb } from "../workflowDb.js";
+import { currentActivity, withActivityPhase } from "../activity.js";
+import { WorkflowDb, readCurrentWorkflowLease } from "../workflowDb.js";
 import { makeLogPath as makeRoleLogPath, readOnlyPermissionConfig, runRoleInstruction } from "../agentRun.js";
+import { eligibleTickets, evaluateTicketEligibility } from "../tickets/eligibility.js";
 function fail(message) {
     console.error(`foreman: ${message}`);
     process.exit(1);
@@ -185,7 +188,10 @@ function branchContinueTicketHelp(cwd, flag = "--continue") {
 }
 async function ensureGitHubReadyForCreatePr(cwd, log, yes) {
     while (true) {
-        const result = preflightGh(cwd);
+        const result = await withActivityPhase("checking GitHub readiness", async () => {
+            currentActivity()?.update("checking GitHub readiness", "remote, authentication, and repository access");
+            return preflightGh(cwd);
+        });
         if (result.ok)
             return;
         log.write("github-readiness-failed", {
@@ -211,6 +217,7 @@ async function ensureGitHubReadyForCreatePr(cwd, log, yes) {
             console.log("ai-foreman: cancelled");
             process.exit(0);
         }
+        currentActivity()?.note("rafi: retrying GitHub readiness check");
     }
 }
 async function ensureReviewProviderReady(cwd, provider, log, yes) {
@@ -219,7 +226,10 @@ async function ensureReviewProviderReady(cwd, provider, log, yes) {
         return;
     }
     while (true) {
-        const result = preflightGlab(cwd);
+        const result = await withActivityPhase("checking GitLab readiness", async () => {
+            currentActivity()?.update("checking GitLab readiness", "remote, authentication, and repository access");
+            return preflightGlab(cwd);
+        });
         if (result.ok)
             return;
         log.write("gitlab-readiness-failed", {
@@ -245,6 +255,7 @@ async function ensureReviewProviderReady(cwd, provider, log, yes) {
             console.log("ai-foreman: cancelled");
             process.exit(0);
         }
+        currentActivity()?.note("rafi: retrying GitLab readiness check");
     }
 }
 export function buildStartCommand() {
@@ -274,13 +285,21 @@ export function buildStartCommand() {
         .option("--no-auto-merge-wait", "do not wait for dependency PR/MRs before dependent tickets")
         .option("--auto-merge-timeout-minutes <n>", "auto-merge dependency wait timeout in minutes (blank means no timeout)")
         .option("--base <ref>", "base ref for root ticket branches (default: current branch or HEAD)")
-        .option("--branch-prefix <prefix>", "branch name prefix for ticket branches", "rafi")
+        .option("--branch-prefix <prefix>", "branch name prefix for ticket branches", "feature")
         .option("--max-branch-depth <n>", "maximum selected branch stack depth", "5")
         .option("--pr-ready", "create ready-for-review PRs instead of draft PRs")
         .option("--keep-worktrees", "keep successful ticket worktrees for inspection")
-        .option("--ticket <id>", "ticket id to continue in branch mode; repeat for multiple tickets", collectTicket, [])
+        .option("--ticket <id>", "select one new ticket, or identify recovery tickets with --resume/--continue/--recover-run", collectTicket, [])
         .option("--skip-delivery-unit <id>", "skip one unfinished delivery unit for this run", collectTicket, [])
         .action(async (project, opts, command) => {
+        const requestedTicketIds = opts.ticket ?? [];
+        const recoveryIntent = Boolean(opts.resume || opts.continue || opts.recoverRun);
+        if (!recoveryIntent && requestedTicketIds.length > 1)
+            fail("new-ticket selection supports exactly one --ticket");
+        if (!recoveryIntent && requestedTicketIds.length === 1 && opts.steps === undefined && opts.stacks === undefined)
+            opts.steps = "1";
+        if (!recoveryIntent && requestedTicketIds.length && opts.stacks !== undefined)
+            fail("new-ticket selection cannot be combined with --stacks");
         if (opts.steps !== undefined && opts.stacks !== undefined)
             fail("--steps and --stacks are mutually exclusive");
         if (opts.steps === undefined && opts.stacks === undefined) {
@@ -409,13 +428,14 @@ export function buildStartCommand() {
             fail("choose either --resume <sessionId> or --continue, not both");
         }
         const branchMode = branchDefaults.branchMode;
-        const continueTickets = opts.ticket ?? [];
+        const continueTickets = recoveryIntent ? requestedTicketIds : [];
+        let selectedNewTicket = !recoveryIntent ? requestedTicketIds[0] : undefined;
         const maxBranchDepth = Number.parseInt(opts.maxBranchDepth, 10);
         if (!Number.isInteger(maxBranchDepth) || maxBranchDepth < 1) {
             fail("--max-branch-depth must be a positive integer");
         }
-        if (!branchMode && continueTickets.length > 0) {
-            fail("--ticket is only supported with --branch-per-ticket --continue or --branch-per-ticket --resume");
+        if (!branchMode && continueTickets.length > 1) {
+            fail("current-branch build recovery supports exactly one --ticket");
         }
         if (branchMode) {
             if (opts.resume && continueTickets.length > 1) {
@@ -424,13 +444,10 @@ export function buildStartCommand() {
             if ((opts.resume || opts.continue) && continueTickets.length === 0 && !recoveryRecord) {
                 fail(branchContinueTicketHelp(cwd, opts.resume ? "--resume" : "--continue"));
             }
-            if (continueTickets.length > 0 && !(opts.resume || opts.continue)) {
-                fail("--ticket in branch mode requires --continue or --resume <sessionId>");
-            }
             if (opts.tickets)
-                fail("--tickets is not supported with --branch-per-ticket; initialize and use .tickets/tickets.yaml");
+                fail("--tickets is not supported with an isolated branch run; initialize and use .tickets/tickets.yaml");
             if (!isTicketsInitialized(cwd))
-                fail("--branch-per-ticket requires initialized .tickets/ (run ai-foreman tickets init)");
+                fail("isolated branch runs require initialized .tickets/ (run ai-foreman tickets init)");
             if (branchDefaults.createReview && !branchDefaults.reviewProvider) {
                 fail("PR/MR completion is enabled but no GitHub or GitLab origin remote was detected; pass --provider github|gitlab or --completion none");
             }
@@ -440,6 +457,60 @@ export function buildStartCommand() {
         if (!branchMode && opts.continue && !resumeSessionId) {
             fail(`no previous session id found under ${join(cwd, ".foreman")}`);
         }
+        if (selectedNewTicket) {
+            if (!isTicketsInitialized(cwd))
+                fail("--ticket requires initialized .tickets/ (run `rafi tickets init`)");
+            const eligibilityConfig = loadTicketsConfig(cwd);
+            const eligibilityPaths = resolveTicketPaths(eligibilityConfig, cwd);
+            const eligibilityDefs = loadTickets(eligibilityPaths.tickets);
+            const eligibilityDb = new StateDb(eligibilityPaths.stateDb);
+            const eligibilityStates = eligibilityDb.getAllStates();
+            eligibilityDb.close();
+            const activeLease = readCurrentWorkflowLease(cwd);
+            let assessment = evaluateTicketEligibility({
+                tickets: eligibilityDefs,
+                states: eligibilityStates,
+                implementationLimit: eligibilityConfig.implementationLimit,
+                delivery: deliveryConfig,
+                activeLease: activeLease ? { runId: activeLease.runId } : undefined,
+            }, selectedNewTicket);
+            if (!assessment.eligible) {
+                console.error(`foreman: ${selectedNewTicket} is not eligible:`);
+                for (const blocker of assessment.blockers)
+                    console.error(`  - ${blocker.detail}`);
+                const dependency = assessment.eligibleDependencies[0];
+                if (!dependency || opts.yes || !process.stdin.isTTY || !process.stdout.isTTY)
+                    fail(`cannot start ${selectedNewTicket}`);
+                const answer = await select({ message: `Start eligible dependency ${dependency.id}: ${dependency.title} instead?`, options: [
+                        { value: "dependency", label: `Start ${dependency.id} (Recommended)` },
+                        { value: "cancel", label: "Cancel" },
+                    ] });
+                if (isCancel(answer) || answer === "cancel") {
+                    console.log("ai-foreman: cancelled; nothing changed");
+                    return;
+                }
+                selectedNewTicket = dependency.id;
+                assessment = evaluateTicketEligibility({ tickets: eligibilityDefs, states: eligibilityStates, implementationLimit: eligibilityConfig.implementationLimit, delivery: deliveryConfig }, selectedNewTicket);
+            }
+            const recommended = eligibleTickets({ tickets: eligibilityDefs, states: eligibilityStates, implementationLimit: eligibilityConfig.implementationLimit, delivery: deliveryConfig })[0];
+            if (assessment.eligible && recommended && recommended.id !== selectedNewTicket) {
+                console.log(`foreman: recommended ${recommended.id}: ${recommended.title}`);
+                console.log(`foreman: requested ${assessment.ticket.id}: ${assessment.ticket.title}`);
+                if (!opts.yes) {
+                    if (!process.stdin.isTTY || !process.stdout.isTTY)
+                        fail(`starting non-recommended ${selectedNewTicket} requires --yes`);
+                    const answer = await select({ message: `Start ${selectedNewTicket} anyway?`, options: [
+                            { value: "start", label: `Start ${selectedNewTicket}` }, { value: "cancel", label: "Cancel" },
+                        ] });
+                    if (isCancel(answer) || answer === "cancel") {
+                        console.log("ai-foreman: cancelled; nothing changed");
+                        return;
+                    }
+                }
+            }
+        }
+        const recoveryTicket = !branchMode && recoveryRecord ? continueTickets[0] : undefined;
+        const preferredTicket = selectedNewTicket ?? recoveryTicket;
         const config = loadConfig(join(cwd, "foreman.yaml"));
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
         const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
@@ -531,9 +602,15 @@ export function buildStartCommand() {
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
             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")}`);
+                const projection = recoveryRecord ? projectBuildRecovery(cwd, recoveryRecord) : undefined;
+                if (projection?.expectedChanges.length) {
+                    console.log(`foreman: preserved expected in-progress work: ${projection.expectedChanges.join(", ")}`);
+                }
+                if (projection?.unexpectedChanges.length) {
+                    console.warn("foreman: warning: unexpected changes may conflict with recovery; recovery is still allowed:");
+                    for (const item of projection.unexpectedChanges)
+                        console.warn(`  ${item.path}: ${item.risk}`);
+                    console.warn("foreman: recommended action: preserve or move overlapping changes before continuing");
                 }
             }
             else {
@@ -563,6 +640,7 @@ export function buildStartCommand() {
             db.close();
             const ticketById = new Map(tickets.map((ticket) => [ticket.id, ticket]));
             const resumeSessionByTicket = new Map();
+            let auditDependencyCount;
             let plan;
             if (continueTickets.length > 0) {
                 const sessions = findResumableBranchSessions(join(cwd, ".foreman"));
@@ -589,6 +667,8 @@ export function buildStartCommand() {
                         dependencies: [],
                         depth: 1,
                         worktreePath: session.worktreePath,
+                        deliveryUnitId: session.deliveryUnitId,
+                        deliveryUnitFinal: session.deliveryUnitFinal,
                     });
                 }
                 plan = {
@@ -596,22 +676,15 @@ export function buildStartCommand() {
                     nodes,
                     issues: [],
                 };
-                log.write("branch-plan", {
-                    baseRef: plan.baseRef,
-                    tickets: plan.nodes.map((node) => node.ticket.id),
-                    branches: plan.nodes.map((node) => ({ ticket: node.ticket.id, branch: node.branch, base: node.baseBranch })),
-                    issues: plan.issues,
-                    resume: true,
-                });
             }
             else {
                 plan = buildBranchPlan(tickets, states, {
                     steps,
-                    baseRef: opts.base ?? currentGitRef(cwd),
+                    baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch ?? currentGitRef(cwd),
                     branchPrefix: opts.branchPrefix,
                     maxBranchDepth,
                     rootBaseBranches: branchDefaults.rootBaseBranches,
-                    ticketIds: selectedStackTickets ?? deliveryRun?.remaining.slice(0, steps) ?? recoveryRecord?.tickets,
+                    ticketIds: selectedNewTicket ? [selectedNewTicket] : selectedStackTickets ?? deliveryRun?.remaining.slice(0, steps) ?? recoveryRecord?.tickets,
                 });
                 let auditBuilder;
                 let auditViewer;
@@ -624,20 +697,14 @@ export function buildStartCommand() {
                     const auditDependencies = parseAuditDependencies(audit.text);
                     plan = buildBranchPlan(tickets, states, {
                         steps,
-                        baseRef: opts.base ?? currentGitRef(cwd),
+                        baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch ?? currentGitRef(cwd),
                         branchPrefix: opts.branchPrefix,
                         maxBranchDepth,
                         auditDependencies,
                         rootBaseBranches: branchDefaults.rootBaseBranches,
-                        ticketIds: selectedStackTickets ?? deliveryRun?.remaining.slice(0, steps) ?? recoveryRecord?.tickets,
-                    });
-                    log.write("branch-plan", {
-                        baseRef: plan.baseRef,
-                        tickets: plan.nodes.map((node) => node.ticket.id),
-                        branches: plan.nodes.map((node) => ({ ticket: node.ticket.id, branch: node.branch, base: node.baseBranch })),
-                        issues: plan.issues,
-                        auditDependencyCount: auditDependencies.length,
+                        ticketIds: selectedNewTicket ? [selectedNewTicket] : selectedStackTickets ?? deliveryRun?.remaining.slice(0, steps) ?? recoveryRecord?.tickets,
                     });
+                    auditDependencyCount = auditDependencies.length;
                 }
                 finally {
                     await auditBuilder?.close().catch(() => { });
@@ -654,13 +721,27 @@ export function buildStartCommand() {
                 if (selectedStacks.length && deliveryConfig) {
                     plan = applyExplicitStackTopology(plan, selectedStacks, deliveryConfig, opts.branchPrefix);
                 }
+                else if (!deliveryRun) {
+                    const branchPolicy = loadTicketSetupConfig(cwd)?.build.branch_policy;
+                    if (branchPolicy)
+                        plan = applySizeBranchPolicy(plan, branchPolicy, deliveryConfig, opts.branchPrefix);
+                }
                 if (recoveryRecord && opts.resume && plan.nodes[0]) {
                     const prior = findResumableBranchSessions(join(cwd, ".foreman")).find((session) => session.ticket === (recoveryRecord.currentTicket ?? plan.nodes[0].ticket.id));
                     if (prior)
                         resumeSessionByTicket.set(plan.nodes[0].ticket.id, { worktreePath: prior.worktreePath, sessionId: opts.resume });
                 }
             }
-            console.log(`foreman: ${continueTickets.length > 0 ? "resuming branch-per-ticket mode" : "branch-per-ticket mode"} for ${plan.nodes.length} ticket(s)`);
+            const branchPresentation = presentBranchPlan(plan, {
+                stacked: selectedStacks.length > 0,
+                resumed: continueTickets.length > 0 || Boolean(recoveryRecord),
+            });
+            log.write("branch-plan", {
+                ...branchPlanLogMetadata(plan, branchPresentation),
+                ...(auditDependencyCount === undefined ? {} : { auditDependencyCount }),
+                ...(continueTickets.length > 0 || recoveryRecord ? { resume: true } : {}),
+            });
+            console.log(branchPresentation.banner);
             console.log(`foreman: project ${cwd}`);
             console.log(`foreman: base ${plan.baseRef}`);
             console.log(`foreman: log ${logPath}\n`);
@@ -680,7 +761,7 @@ export function buildStartCommand() {
             console.log();
             if (!opts.yes && plan.issues.every((issue) => !issue.blocking)) {
                 const action = await select({
-                    message: "Proceed with branch-per-ticket run?",
+                    message: branchPresentation.prompt,
                     options: [
                         { value: "proceed", label: "Proceed" },
                         { value: "cancel", label: "Cancel" },
@@ -702,7 +783,7 @@ export function buildStartCommand() {
             };
             let masterRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBranchBuilder, qa: capturedBranchQa, builderSessionId: opts.resume ? String(opts.resume) : null }) : createBuildRun({
                 tickets: plan.nodes.map((node) => node.ticket.id), deliveryUnit: selectedStacks.length ? selectedStacks.map((stack) => stack.id).join(",") : deliveryRun?.unit.id,
-                repositoryRoot: cwd, branchMode: "per-ticket", builder: capturedBranchBuilder, qa: capturedBranchQa,
+                repositoryRoot: cwd, branchMode: branchPresentation.allocationMode, baseRef: plan.baseRef, builder: capturedBranchBuilder, qa: capturedBranchQa,
             });
             const branchHeartbeat = setInterval(() => { masterRun = heartbeatBuildRun(cwd, masterRun); }, 10_000);
             branchHeartbeat.unref();
@@ -808,7 +889,7 @@ export function buildStartCommand() {
         };
         const capturedQa = { role: "qa", source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default", reasoning: qaEffort ?? "default", fast: qaFast, session_strategy: roleDefaults.qa?.session_strategy ?? "compact", settings_revision: settingsRevision };
         let buildRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBuilder, qa: capturedQa, builderSessionId: opts.resume ? String(opts.resume) : null }) : createBuildRun({
-            tickets: [], repositoryRoot: cwd, branchMode: "current", builder: capturedBuilder, qa: capturedQa,
+            tickets: [], repositoryRoot: cwd, branchMode: "current", baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch, builder: capturedBuilder, qa: capturedQa,
         });
         const heartbeat = setInterval(() => { buildRun = heartbeatBuildRun(cwd, buildRun); }, 10_000);
         heartbeat.unref();
@@ -827,7 +908,11 @@ export function buildStartCommand() {
             reasoning: capturedBuilder.reasoning, fast: capturedBuilder.fast, step: 1, total: steps,
             phase: "builder work session", sessionTransition: resumeSessionId ? "resumed exact session" : "initial session", adapter: () => foreman.builderAdapter(),
         }, (line, snapshot) => {
-            console.log(line);
+            const activity = currentActivity();
+            if (activity)
+                activity.writePersistent(line);
+            else
+                console.log(line);
             log.write("agent-status", { ...snapshot });
             const db = new WorkflowDb(cwd);
             try {
@@ -853,7 +938,7 @@ export function buildStartCommand() {
         try {
             console.log("ai-foreman: asking builder to plan the next tickets or steps...\n");
             buildRun = checkpointBuildRun(cwd, buildRun, "before-preflight");
-            await foreman.runPreflight(steps, ticketsContent);
+            await foreman.runPreflight(steps, ticketsContent, preferredTicket);
             if (foreman.builderSessionId())
                 buildRun = persistBuildSession(cwd, buildRun, "builder", foreman.builderSessionId());
             if (foreman.qaSessionId())
@@ -896,7 +981,15 @@ export function buildStartCommand() {
                     await foreman.sendPreflightFeedback(String(fb));
                 }
             }
-            const result = await foreman.runBatch(steps, trackerRelPath);
+            const result = await foreman.runBatch(steps, trackerRelPath, (ticketId) => {
+                const tickets = buildRun.tickets.includes(ticketId)
+                    ? buildRun.tickets
+                    : [...buildRun.tickets, ticketId];
+                buildRun = checkpointBuildRun(cwd, buildRun, "ticket-selected", {
+                    tickets,
+                    currentTicket: ticketId,
+                });
+            }, preferredTicket);
             if (foreman.qaSessionId())
                 buildRun = persistBuildSession(cwd, buildRun, "qa", foreman.qaSessionId());
             buildRun = result.outcome === "all-done" || result.outcome === "plan-complete"
@@ -1045,7 +1138,7 @@ export function applyExplicitStackTopology(plan, stacks, delivery, branchPrefix)
             const unit = unitById.get(unitId);
             if (!unit)
                 throw new Error(`stack ${stack.id} references missing delivery unit ${unitId}`);
-            const sharedBranch = unit.branch_mode === "shared" ? `${branchPrefix.replace(/^\/+|\/+$/g, "") || "rafi"}/${slug(unitId)}` : undefined;
+            const sharedBranch = unit.branch_mode === "shared" ? `${branchPrefix || "feature"}/${slug(unitId)}` : undefined;
             const unitBaseBranch = predecessorBranch;
             for (let ticketIndex = 0; ticketIndex < unit.tickets.length; ticketIndex++) {
                 const ticketId = unit.tickets[ticketIndex];

package/dist/cli/tickets.d.ts

@@ -24,6 +24,15 @@ interface PopulateCommandOptions {
     yes?: boolean;
     authorizeRetire?: string[];
 }
+export declare function combineRequirementSelections(selected: string[], additions: string): string[];
 export declare function cmdPopulateCli(opts: PopulateCommandOptions): Promise<void>;
-export declare function buildTicketsCommand(): Command;
+export interface TicketOwnershipReceipt {
+    path: string;
+    category: "tickets";
+    origin: string;
+}
+export declare function buildTicketsCommand(options?: {
+    prepareOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;
+    recordOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;
+}): Command;
 export {};