ai-foreman 1.7.16 → 1.7.17

package/dist/adapters/claude.js

@@ -33,7 +33,10 @@ export function buildClaudeQueryOptions(opts) {
         permissionMode: qaReadOnly ? "default" : "acceptEdits",
         effort: opts.effort,
         extraArgs: opts.fast ? { fast: null } : undefined,
-        settingSources: qaReadOnly ? [] : ["user", "project", "local"],
+        // Read-only roles still need the user's Claude authentication settings (for
+        // example, an enterprise apiKeyHelper). Do not load repository-controlled
+        // settings in those roles.
+        settingSources: qaReadOnly ? ["user"] : ["user", "project", "local"],
         ...(qaReadOnly ? { disallowedTools: ["Write", "Edit", "NotebookEdit"] } : {}),
         ...(qaReadOnly ? { sandbox: {
                 enabled: true,
@@ -56,7 +59,7 @@ export function buildClaudeQueryOptions(opts) {
     return base;
 }
 function qaEnvironment(source, cwd) {
-    const allowed = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "TMPDIR", "LANG", "LC_ALL", "TERM", "NO_COLOR", "FORCE_COLOR", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS"];
+    const allowed = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "TMPDIR", "LANG", "LC_ALL", "TERM", "NO_COLOR", "FORCE_COLOR", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL", "CLAUDE_CODE_API_KEY_HELPER_TTL_MS", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS"];
     return { ...Object.fromEntries(allowed.flatMap((key) => source[key] === undefined ? [] : [[key, source[key]]])), TMPDIR: join(dirname(cwd), "scratch") };
 }
 export async function probeClaudeSession(ref, input) {

package/dist/branch/git.js

@@ -129,7 +129,9 @@ export function mergeBranchToLocalBase(projectDir, branch, baseBranch, message,
         runGit(projectDir, ["checkout", baseBranch]);
     }
     if (method === "squash") {
-        runGit(projectDir, ["merge", "--squash", branch]);
+        // A user's global `merge.ff=only` conflicts with `--squash`; pin the
+        // ordinary merge policy so direct delivery remains independent of it.
+        runGit(projectDir, ["-c", "merge.ff=true", "merge", "--squash", branch]);
         runGit(projectDir, ["commit", "-m", message]);
     }
     else if (method === "merge") {

package/dist/branch/github.js

@@ -53,10 +53,10 @@ export function originLooksLikeGitHub(cwd) {
 export function checkGitHubReadiness(cwd) {
     const ghVersion = runCommand(cwd, "gh", ["--version"], 5_000);
     if (!ghVersion.ok) {
-        return failure("gh_missing", "GitHub CLI is not installed or is not on PATH.", [
+        return classifyCommandFailure(ghVersion, "gh_missing", "GitHub CLI is not installed or is not on PATH.", [
             "Install GitHub CLI: https://cli.github.com/",
             "gh --version",
-        ], ghVersion);
+        ]);
     }
     const remote = inspectGitHubRemote(cwd);
     if (!remote.ok)

package/dist/cli/tickets.d.ts

@@ -1,9 +1,10 @@
 import { Command } from "commander";
+import type { StructuredPlanV1 } from "rafi-spec";
 import { Log } from "../log.js";
 import type { EffortLevel } from "../adapters/types.js";
 import { type RoleBuilderOptions } from "../agentRun.js";
 import type { TicketsConfig } from "../tickets/config.js";
-export declare function buildPopulateInstruction(sourceHints?: string[], progressDoc?: string): string;
+export declare function buildPopulateInstruction(approvedPlanPath: string, contextSources?: string[], progressDoc?: string): string;
 export declare function resolvePopulateSources(projectDir: string, explicitSources: string[] | undefined, ticketsConfig: TicketsConfig): string[] | undefined;
 export declare function buildPopulateAgentRunOptions(opts: {
     projectDir: string;
@@ -26,6 +27,17 @@ interface PopulateCommandOptions {
 }
 export declare function combineRequirementSelections(selected: string[], additions: string): string[];
 export declare function cmdPopulateCli(opts: PopulateCommandOptions): Promise<void>;
+export interface PopulationPlanResolution {
+    /** Repository-relative path when possible, for both agent instructions and diagnostics. */
+    path: string;
+    plan: StructuredPlanV1;
+}
+/**
+ * Locate the plan that Rafi approved independently of the documents the user
+ * wants Ticket Maker to use as context. In particular, FEATURES.md is not a
+ * promise that FEATURES.json is a Rafi plan.
+ */
+export declare function resolvePopulationPlan(projectDir: string, contextSources: string[], ticketsConfig: TicketsConfig): PopulationPlanResolution;
 export interface TicketOwnershipReceipt {
     path: string;
     category: "tickets";

package/dist/cli/tickets.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { select, text, confirm, isCancel, multiselect } from "@clack/prompts";
 import { loadConfig } from "../config.js";
@@ -64,23 +64,27 @@ function validateEffort(effort) {
         fail(err instanceof Error ? err.message : String(err));
     }
 }
-export function buildPopulateInstruction(sourceHints, progressDoc = "docs/ticket-progress.md") {
-    const sources = sourceHints ?? [];
+export function buildPopulateInstruction(approvedPlanPath, contextSources, progressDoc = "docs/ticket-progress.md") {
+    const sources = contextSources ?? [];
     const sourceHintBlock = sources.length > 0
         ? `
-User-provided planning source hints:
+Original context source hints:
 ${sources.map((source) => `- ${source}`).join("\n")}
 
 Treat these as files, folders, or globs to check first. Any reasonable project-planning format is acceptable because you are responsible for interpreting it. If a hinted source does not exist or is ambiguous, continue scanning the repository before asking for help.
 `
         : `
-No specific planning sources were provided. Scan the repository for relevant planning and ticketing documents.
+No original context sources were provided. Use the approved plan and scan the repository only when it is needed to resolve its references.
 `;
     return `You are being run by Foreman to populate this repository's Foreman ticket tracker.
 
 Goal:
 - Convert every existing project ticket, task, backlog item, roadmap item, or implementation step into Foreman's structured ticket system.
 - Do not implement product/code changes. Only update ticket-tracker files.
+\nApproved structured Rafi plan (authoritative for plan identity and slice mapping):
+- ${approvedPlanPath}
+
+Read this approved plan before all other sources. It determines the exact plan_id, revision, and slice_ref values that the proposal must use. The context sources below provide supporting product and implementation detail; they do not replace or redefine the approved plan.
 ${sourceHintBlock}
 
 Before proposing, read these tracker control files:
@@ -89,7 +93,7 @@ Before proposing, read these tracker control files:
 - .tickets/tracker-rules.md
 - ${progressDoc} if it exists
 
-Then inspect the repository for existing planning sources, beginning with the approved structured Rafi plan. You are proposal-only: do not edit any file, run tracker mutation commands, allocate final ticket IDs, or write delivery configuration. Rafi validates and performs all writes after approval.
+Then inspect the repository for the context required by the approved structured Rafi plan. You are proposal-only: do not edit any file, run tracker mutation commands, allocate final ticket IDs, or write delivery configuration. Rafi validates and performs all writes after approval.
 
 Return ticket content using Foreman's schema:
 - slice_ref: the exact approved plan slice reference. Do not allocate ticket IDs.
@@ -355,13 +359,13 @@ async function collectTicketSetupPatch(dir, opts, current) {
         };
     }
     const section = await select({
-        message: "Which ticket setup section should be configured?",
+        message: "What would you like to configure for tickets?",
         options: [
-            { 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" },
+            { value: "sources", label: "Where tickets come from", hint: "Choose planning files, issue trackers, or other sources." },
+            { value: "populate", label: "How Rafi creates tickets from those sources", hint: "Set import and enrichment behavior." },
+            { value: "build", label: "How Rafi implements tickets", hint: "Set branches, validation, and completion behavior." },
+            { value: "limits", label: "Ticket tracker limits", hint: "Set how many tickets Rafi can show or work on at once." },
+            { value: "all", label: "Configure everything", hint: "Walk through every ticket setting." },
         ],
     });
     if (isCancel(section))
@@ -387,6 +391,15 @@ async function collectTicketSetupPatch(dir, opts, current) {
         };
     }
     if (section === "populate" || section === "all") {
+        console.log([
+            "Recommended population settings:",
+            "  • Use the saved ticket sources by default.",
+            "  • Use the project's configured agent when both runtimes are available.",
+            `  • Import up to ${DEFAULT_TICKET_SETUP.populate.import_cap} tickets per run.`,
+            `  • Import up to ${DEFAULT_TICKET_SETUP.populate.comment_limit} comments per external ticket.`,
+            "  • Generate deterministic recommendations during population.",
+            "  • Recommend splitting XL tickets.",
+        ].join("\n"));
         const defaults = await confirm({ message: "Use the recommended population settings?", initialValue: true });
         if (isCancel(defaults))
             cancelTicketInterview();
@@ -492,7 +505,7 @@ 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);
+            buildPatch.validation_checklist = await promptValidationChecklist(current.build.validation_checklist);
             return {
                 sources,
                 limits,
@@ -540,7 +553,7 @@ async function collectTicketSetupPatch(dir, opts, current) {
                 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);
+        buildPatch.validation_checklist = await promptValidationChecklist(current.build.validation_checklist);
         if (completion === "auto-merge") {
             const wait = await confirm({
                 message: "Wait for dependency PR/MRs to merge before starting dependent tickets?",
@@ -596,6 +609,44 @@ async function promptNonNegativeInteger(message, initial) {
         cancelTicketInterview();
     return Number(answer);
 }
+async function promptValidationChecklist(initial) {
+    console.log([
+        "Rafi gives these project-wide checks to its QA reviewer for every ticket.",
+        "Current validation checklist:",
+        ...(initial.length ? initial.map((item) => `  • ${item}`) : ["  • No checks configured."]),
+    ].join("\n"));
+    const mode = await select({
+        message: "Which project-wide checks should Rafi's QA reviewer verify for every ticket?",
+        initialValue: "keep",
+        options: [
+            { value: "keep", label: "Keep all of these checks for every ticket (Recommended)" },
+            { value: "choose", label: "Choose from these checks and add others" },
+            { value: "replace", label: "Replace these with my own checks" },
+        ],
+    });
+    if (isCancel(mode))
+        cancelTicketInterview();
+    if (mode === "keep")
+        return [...initial];
+    if (mode === "replace") {
+        const replacement = await text({ message: "Project-wide checks for QA to verify on every ticket (comma-separated):", defaultValue: "" });
+        if (isCancel(replacement))
+            cancelTicketInterview();
+        return splitCommaList(String(replacement));
+    }
+    const selected = initial.length ? await multiselect({
+        message: "Select the project-wide checks QA should verify for every ticket:",
+        options: initial.map((value) => ({ value, label: value })),
+        initialValues: initial,
+        required: false,
+    }) : [];
+    if (isCancel(selected))
+        cancelTicketInterview();
+    const additions = await text({ message: "Additional project-wide QA checks (comma-separated, optional):", defaultValue: "" });
+    if (isCancel(additions))
+        cancelTicketInterview();
+    return combineRequirementSelections(selected, String(additions));
+}
 async function promptRequirementList(label, initial) {
     console.log(`Current recommended ${label}: ${initial.join("; ") || "none"}`);
     const mode = await select({
@@ -996,7 +1047,8 @@ export async function cmdPopulateCli(opts) {
             return;
         }
     }
-    const structuredPlan = loadPopulationPlan(dir, sourceHints);
+    const approvedPlan = resolvePopulationPlan(dir, sourceHints, ticketsConfig);
+    const contextSources = sourceHints.filter((source) => !isApprovedPlanArtifact(dir, source, approvedPlan.path));
     if (!opts.yes) {
         const action = await select({
             message: "Ask the read-only Ticket Maker for a structured population proposal?",
@@ -1032,10 +1084,11 @@ export async function cmdPopulateCli(opts) {
         console.log(`foreman tickets: project ${dir}`);
         console.log(`foreman tickets: role ${TICKET_POPULATE_ROLE}`);
         console.log(`foreman tickets: log ${logPath}\n`);
-        if (sourceHints.length) {
-            console.log(`foreman tickets: source hints ${sourceHints.join(" ")}`);
+        console.log(`foreman tickets: approved plan ${approvedPlan.path}`);
+        if (contextSources.length) {
+            console.log(`foreman tickets: context sources ${contextSources.join(" ")}`);
         }
-        const turn = await foreman.runInstruction(buildPopulateInstruction(sourceHints, ticketsConfig.paths.progressDoc));
+        const turn = await foreman.runInstruction(buildPopulateInstruction(approvedPlan.path, contextSources, ticketsConfig.paths.progressDoc));
         await builder.close();
         await viewer;
         log.write("ticket-populate", {
@@ -1056,7 +1109,7 @@ export async function cmdPopulateCli(opts) {
         }
         const existing = loadTickets(resolveTicketPaths(ticketsConfig, dir).tickets);
         const proposal = extractTicketPopulationProposal(turn.result.text);
-        const materialized = materializeTicketPopulation(proposal, structuredPlan, existing);
+        const materialized = materializeTicketPopulation(proposal, approvedPlan.plan, existing);
         let retirementsConfirmed = false;
         if (!opts.yes) {
             console.log(`foreman tickets: proposal maps ${materialized.sliceToTicket.size} slice(s) and retires ${materialized.retirements.join(", ") || "none"}`);
@@ -1099,16 +1152,76 @@ async function prepareDocumentSources(projectDir, sources) {
     }
     return unique(prepared);
 }
-function loadPopulationPlan(projectDir, sources) {
-    for (const source of sources) {
-        const candidate = source.endsWith(".json") ? resolve(projectDir, source) : source.endsWith(".md") ? resolve(projectDir, source.replace(/\.md$/, ".json")) : undefined;
-        if (!candidate || !existsSync(candidate))
+/**
+ * Locate the plan that Rafi approved independently of the documents the user
+ * wants Ticket Maker to use as context. In particular, FEATURES.md is not a
+ * promise that FEATURES.json is a Rafi plan.
+ */
+export function resolvePopulationPlan(projectDir, contextSources, ticketsConfig) {
+    const explicit = unique(contextSources.filter((source) => source.toLowerCase().endsWith(".json")));
+    const explicitResolution = findPopulationPlan(projectDir, explicit);
+    if (explicitResolution)
+        return explicitResolution;
+    const activeCandidates = activePopulationPlanCandidates(projectDir, ticketsConfig);
+    const activeResolution = findPopulationPlan(projectDir, activeCandidates);
+    if (activeResolution)
+        return activeResolution;
+    const locations = unique([...explicit, ...activeCandidates]);
+    throw new Error(`ticket population could not find a valid approved Rafi plan. Looked for: ${locations.join(", ") || "configured Rafi plan locations"}. `
+        + "Run `rafi plan --validate` (or run `rafi plan` first) and retry.");
+}
+function activePopulationPlanCandidates(projectDir, ticketsConfig) {
+    const configured = RAFI_CONFIG_FILES.map((file) => resolveConfiguredRafiPlanPath(projectDir, file)).filter((path) => Boolean(path));
+    return unique([
+        ...configured,
+        join(dirname(ticketsConfig.paths.progressDoc), "rafi-plan.json"),
+        "docs/rafi-plan.json",
+    ]);
+}
+function resolveConfiguredRafiPlanPath(projectDir, file) {
+    const configPath = join(projectDir, file);
+    if (!existsSync(configPath))
+        return undefined;
+    const raw = parseYaml(readFileSync(configPath, "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${file}: expected a YAML object`);
+    }
+    const docs = raw.docs;
+    if (typeof docs?.root !== "string")
+        return undefined;
+    return `${validateDocsRoot(projectDir, docs.root)}/rafi-plan.json`;
+}
+function findPopulationPlan(projectDir, candidates) {
+    for (const candidate of candidates) {
+        const absolute = resolve(projectDir, candidate);
+        if (!existsSync(absolute))
             continue;
-        const plan = JSON.parse(readFileSync(candidate, "utf8"));
-        if (plan.version === 1 && plan.plan_id && Number.isInteger(plan.revision) && plan.content_digest)
-            return plan;
+        try {
+            const plan = JSON.parse(readFileSync(absolute, "utf8"));
+            if (plan.version === 1 && typeof plan.plan_id === "string" && plan.plan_id && Number.isInteger(plan.revision) && typeof plan.content_digest === "string" && plan.content_digest) {
+                return { path: displayPath(projectDir, absolute), plan };
+            }
+        }
+        catch {
+            // A JSON context document is not necessarily a Rafi plan. Keep looking
+            // for the active approved plan and report every location if none exists.
+        }
     }
-    throw new Error("ticket population requires the approved paired structured plan (normally docs/rafi-plan.json); run `rafi plan --validate` first");
+    return undefined;
+}
+function displayPath(projectDir, absolutePath) {
+    const path = relative(projectDir, absolutePath).replace(/\\/g, "/");
+    return path && !path.startsWith("../") ? path : absolutePath;
+}
+function samePath(projectDir, first, second) {
+    return resolve(projectDir, first) === resolve(projectDir, second);
+}
+function isApprovedPlanArtifact(projectDir, source, approvedDataPath) {
+    if (samePath(projectDir, source, approvedDataPath))
+        return true;
+    const dataPath = resolve(projectDir, approvedDataPath);
+    return source.toLowerCase().endsWith(".md")
+        && resolve(projectDir, source) === dataPath.replace(/\.json$/i, ".md");
 }
 function ticketOwnershipReceipts(projectDir, commandName, _afterWrite) {
     const candidates = [

package/dist/qaProtocolV2.d.ts

@@ -28,7 +28,8 @@ export interface QaConfinementV2 {
     sourceMode: "read-only";
     scratchMode: "isolated";
     networkMode: "disabled" | "provider-required";
-    settingsSources: "none";
+    /** "user" permits the machine owner's Claude authentication settings, but no project settings. */
+    settingsSources: "none" | "user";
     environmentDigest: string;
     policyDigest: string;
 }

package/dist/qaReview.js

@@ -8,6 +8,7 @@ import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
 import { WorkflowDb } from "./workflowDb.js";
+import { canonicalSessionPath } from "./sessionIdentity.js";
 import { loadProjectAutonomyConfig, resolveAutonomyPolicy } from "./recoveryPolicy.js";
 import { appendQaRecoveryAttempt, appendQaRecoveryResource, appendQaRecoveryReviewedState, compareQaRecoveryReviewedState, createQaRecoveryPacket, ensureQaRecoveryExcluded, loadQaRecoveryPacket, materializeQaRecoveryContext, qaRecoveryInventory, qaReportDigest, renderQaRecoveryAcknowledgementInstruction, updateQaRecoveryPosition, updateQaRecoveryReviewIdentity, validateManualQaReport, validateQaRecoveryAcknowledgement, } from "./qaRecovery.js";
 import { canonicalJson, createQaFindingRefs, qaDigest } from "./qaProtocolV2.js";
@@ -1445,14 +1446,14 @@ function validateQaSessionHandle(handle, reviewedSnapshotPath) {
     if (identity.version !== 1 || identity.role !== "qa" || identity.stream !== "qa" || identity.provider !== handle.adapter.agent
         || !identity.sessionId || /^(?:unavailable|unknown)$/i.test(identity.sessionId.trim())
         || !Number.isSafeInteger(identity.generation) || identity.generation < 0
-        || resolve(identity.cwd) !== resolve(reviewedSnapshotPath) || !identity.configRoot
+        || canonicalSessionPath(identity.cwd) !== canonicalSessionPath(reviewedSnapshotPath) || !identity.configRoot
         || Number.isNaN(Date.parse(identity.createdAt)) || !identity.validatedAt || Number.isNaN(Date.parse(identity.validatedAt))
         || handle.adapter.sessionId() !== identity.sessionId || !adapterIdentity
         || stableProviderSessionIdentity(adapterIdentity) !== stableProviderSessionIdentity(identity)) {
         throw new Error("QA session handle has an invalid or mismatched scoped identity");
     }
     if (!handle.effectiveRoleInstructions.trim() || confinement.version !== 2 || confinement.sourceMode !== "read-only"
-        || confinement.scratchMode !== "isolated" || confinement.settingsSources !== "none"
+        || confinement.scratchMode !== "isolated" || !["none", "user"].includes(confinement.settingsSources)
         || !["disabled", "provider-required"].includes(confinement.networkMode)
         || !/^[a-f0-9]{64}$/.test(confinement.environmentDigest) || !/^[a-f0-9]{64}$/.test(confinement.policyDigest)
         || digest !== qaDigest("qa-confinement", confinementFields)) {

package/dist/qaRuntime.js

@@ -9,10 +9,14 @@ export function frozenQaRuntimeSettings(adapter, metadata) {
 }
 export function describeQaRuntimeHandle(adapter, metadata, handoffReceipt) {
     const settings = frozenQaRuntimeSettings(adapter, metadata);
-    const confinementPolicy = { sandboxMode: "read-only", settingsSources: "none", permissions: readOnlyPermissionConfig(), dependencyProjection: "read-only-symlink", scratch: "sibling-temp-directory" };
+    // `settingSources` is a Claude Agent SDK control. Claude read-only sessions
+    // need the machine owner's authentication settings; Codex does not receive
+    // that SDK option.
+    const settingsSources = adapter.agent === "claude" ? "user" : "none";
+    const confinementPolicy = { sandboxMode: "read-only", settingsSources, permissions: readOnlyPermissionConfig(), dependencyProjection: "read-only-symlink", scratch: "sibling-temp-directory" };
     const confinementBase = {
         version: 2, sourceMode: "read-only", scratchMode: "isolated",
-        settingsSources: "none", networkMode: "provider-required",
+        settingsSources, networkMode: "provider-required",
         environmentDigest: qaDigest("qa-confinement-environment", { runtime: settings.make, model: settings.model, reasoning: settings.reasoning, fast: settings.fast, platform: process.platform, arch: process.arch }),
         policyDigest: qaDigest("qa-confinement-policy", confinementPolicy),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.16",
+  "version": "1.7.17",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -195,7 +195,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsx src/index.ts",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --test --test-concurrency=1 test/*.test.ts",
     "typecheck": "tsc --noEmit",
     "test:live-providers": "RAFI_LIVE_PROVIDER_SESSIONS=1 tsx --test test/providerSmoke.test.ts",
     "prepublishOnly": "tsc -p ../spec/tsconfig.build.json && tsc -p tsconfig.build.json && pnpm --filter ai-foreman test && tsc --noEmit"