ai-foreman 1.4.0 → 1.6.0

package/dist/cli/status.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { resolve, join } from "node:path";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { findResumableBranchSessions, formatBranchContinueCommand } from "../branch/resume.js";
+import { recoverableBuildRuns } from "../buildRuns.js";
 function fail(message) {
     console.error(`foreman: ${message}`);
     process.exit(1);
@@ -10,65 +11,80 @@ export function buildStatusCommand() {
     return new Command("status")
         .description("Summarize the most recent foreman run for a project.")
         .argument("<project>", "path to the project directory")
-        .action((project) => {
-        const projectDir = resolve(project);
-        const dir = join(projectDir, ".foreman");
-        if (!existsSync(dir))
+        .action((project) => runStatus(project));
+}
+/** Print the existing Foreman status report for a resolved project. */
+export function runStatus(project) {
+    const projectDir = resolve(project);
+    const dir = join(projectDir, ".foreman");
+    const recoverable = recoverableBuildRuns(projectDir);
+    if (!existsSync(dir))
+        fail(`no foreman runs found under ${dir}`);
+    const logs = readdirSync(dir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .sort();
+    if (logs.length === 0) {
+        if (recoverable.length === 0)
             fail(`no foreman runs found under ${dir}`);
-        const logs = readdirSync(dir)
-            .filter((f) => f.endsWith(".jsonl"))
-            .sort();
-        if (logs.length === 0)
-            fail(`no foreman runs found under ${dir}`);
-        const latest = join(dir, logs[logs.length - 1]);
-        const records = readFileSync(latest, "utf8")
-            .split("\n")
-            .filter(Boolean)
-            .map((line) => JSON.parse(line));
-        const steps = records.filter((r) => r.event === "step");
-        const escalations = records.filter((r) => r.event === "escalation");
-        const branchEvents = records.filter((r) => String(r.event).startsWith("branch-"));
-        const prEvents = records.filter((r) => ["pr-created", "pr-existing", "pr-failed"].includes(String(r.event)));
-        const latestFailure = findLatestGitHubFailure(records);
-        const batchEnd = [...records].reverse().find((r) => r.event === "batch-end");
-        console.log(`foreman: latest run ${logs[logs.length - 1]}`);
-        console.log(`foreman: ${steps.length} step record(s), ${escalations.length} escalation(s)`);
-        if (branchEvents.length || prEvents.length) {
-            const completed = branchEvents.filter((r) => r.event === "branch-complete").length;
-            const issues = branchEvents.filter((r) => r.event === "branch-issue").length;
-            const prs = prEvents.filter((r) => r.event === "pr-created" || r.event === "pr-existing").length;
-            console.log(`foreman: branch mode — ${completed} completed, ${issues} issue(s), ${prs} PR(s)`);
-        }
-        if (batchEnd) {
-            console.log(`foreman: outcome — ${batchEnd.outcome} (${batchEnd.completed}/${batchEnd.requested})`);
-            if (batchEnd.detail)
-                console.log(`foreman: ${batchEnd.detail}`);
-        }
-        else {
-            console.log("ai-foreman: run is still in progress or did not finish");
-        }
-        if (latestFailure) {
-            console.log(`foreman: latest GitHub failure — ${latestFailure.code}: ${latestFailure.message}`);
-            if (latestFailure.repairCommands.length > 0) {
-                console.log("foreman: repair and verify:");
-                for (const command of latestFailure.repairCommands) {
-                    console.log(`  ${command}`);
-                }
-            }
-            const retry = findRetryCommand(projectDir, dir, latestFailure);
-            if (retry) {
-                console.log("foreman: retry with:");
-                console.log(`  ${retry}`);
-            }
-            if (latestFailure.output) {
-                console.log("foreman: last command output:");
-                console.log(indent(limitLines(latestFailure.output, 8)));
+        printRecoverable(projectDir, recoverable);
+        return;
+    }
+    const latest = join(dir, logs[logs.length - 1]);
+    const records = readFileSync(latest, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+    const steps = records.filter((r) => r.event === "step");
+    const escalations = records.filter((r) => r.event === "escalation");
+    const branchEvents = records.filter((r) => String(r.event).startsWith("branch-"));
+    const prEvents = records.filter((r) => ["pr-created", "pr-existing", "pr-failed"].includes(String(r.event)));
+    const latestFailure = findLatestGitHubFailure(records);
+    const batchEnd = [...records].reverse().find((r) => r.event === "batch-end");
+    console.log(`foreman: latest run ${logs[logs.length - 1]}`);
+    console.log(`foreman: ${steps.length} step record(s), ${escalations.length} escalation(s)`);
+    if (branchEvents.length || prEvents.length) {
+        const completed = branchEvents.filter((r) => r.event === "branch-complete").length;
+        const issues = branchEvents.filter((r) => r.event === "branch-issue").length;
+        const prs = prEvents.filter((r) => r.event === "pr-created" || r.event === "pr-existing").length;
+        console.log(`foreman: branch mode — ${completed} completed, ${issues} issue(s), ${prs} PR(s)`);
+    }
+    if (batchEnd) {
+        console.log(`foreman: outcome — ${batchEnd.outcome} (${batchEnd.completed}/${batchEnd.requested})`);
+        if (batchEnd.detail)
+            console.log(`foreman: ${batchEnd.detail}`);
+    }
+    else {
+        console.log("ai-foreman: run is still in progress or did not finish");
+    }
+    if (latestFailure) {
+        console.log(`foreman: latest GitHub failure — ${latestFailure.code}: ${latestFailure.message}`);
+        if (latestFailure.repairCommands.length > 0) {
+            console.log("foreman: repair and verify:");
+            for (const command of latestFailure.repairCommands) {
+                console.log(`  ${command}`);
             }
         }
-        for (const esc of escalations) {
-            console.log(`  escalated: ${esc.tool} — ${esc.reason}`);
+        const retry = findRetryCommand(projectDir, dir, latestFailure);
+        if (retry) {
+            console.log("foreman: retry with:");
+            console.log(`  ${retry}`);
         }
-    });
+        if (latestFailure.output) {
+            console.log("foreman: last command output:");
+            console.log(indent(limitLines(latestFailure.output, 8)));
+        }
+    }
+    for (const esc of escalations) {
+        console.log(`  escalated: ${esc.tool} — ${esc.reason}`);
+    }
+    if (recoverable.length > 0)
+        printRecoverable(projectDir, recoverable);
+}
+function printRecoverable(projectDir, runs) {
+    console.log(`foreman: ${runs.length} unfinished/recoverable build run(s):`);
+    for (const run of runs)
+        console.log(`  ${run.runId}  ${run.currentTicket ?? run.tickets[0] ?? "unknown"}  ${run.active ? "active" : run.status}  checkpoint=${run.checkpoint}`);
+    console.log(`foreman: recover with \`rafi build:resume ${projectDir}\``);
 }
 function findLatestGitHubFailure(records) {
     for (let i = records.length - 1; i >= 0; i--) {

package/dist/cli/tickets.js

@@ -13,7 +13,9 @@ import { validateDocsRoot } from "../tickets/config.js";
 import { importExternalSources, importFromMarkdown, validateExternalSourceAccess } from "../tickets/importer.js";
 import { formatValidationIssues } from "../tickets/validate.js";
 import { assertEffortLevel, createRoleBuilder, makeLogPath, } from "../agentRun.js";
-import { DEFAULT_TICKET_SETUP, defaultAppName, ensureRafiConfigForTicketSetup, externalSources, hasTicketSetupConfig, loadTicketSetupConfig, loadTicketSetupConfigWithDefaults, localSourcePaths, mergeTicketSetup, recommendedBuildDefaults, saveTicketSetupConfig, } from "../tickets/setupConfig.js";
+import { DEFAULT_TICKET_SETUP, configuredPlanningSources, defaultAppName, ensureRafiConfigForTicketSetup, externalSources, hasTicketSetupConfig, loadTicketSetupConfig, loadTicketSetupConfigWithDefaults, localSourcePaths, mergeTicketSetup, recommendedBuildDefaults, saveTicketSetupConfig, urlSources, } from "../tickets/setupConfig.js";
+import { fetchAndSnapshotUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
+import { checkpointInterview, completeInterview, createInterviewRecord, failInterview, } from "../interviews.js";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
@@ -138,73 +140,114 @@ async function cmdSetupInitCli(opts) {
     const dir = cwd(opts);
     if (!existsSync(dir))
         fail(`project directory not found: ${dir}`);
+    let interview = beginTicketSetupInterview(dir, "tickets-setup-init", opts);
     if (hasTicketSetupConfig(dir)) {
         console.log("foreman tickets setup: existing setup found; opening setup:update");
         await cmdSetupUpdateCli(opts);
+        if (interview)
+            completeInterview(dir, interview);
         return;
     }
-    const answers = await collectTicketSetup(dir, opts, undefined);
-    ensureRafiConfigForTicketSetup(dir, {
-        appName: opts.appName ?? defaultAppName(dir),
-        docsRoot: opts.docsRoot,
-        targets: parseRuntimeTargets(opts.runtime),
-    });
-    saveTicketSetupConfig(dir, answers, {
-        appName: opts.appName ?? defaultAppName(dir),
-        docsRoot: opts.docsRoot,
-        targets: parseRuntimeTargets(opts.runtime),
-    });
-    console.log(`foreman tickets setup: saved ticket setup in ${join(dir, "rafi-config.yaml")}`);
-    await validateConfiguredSourcesIfRequested(answers, Boolean(opts.skipAccessCheck));
-    if (!isTicketsInitialized(dir)) {
-        cmdInit(dir, {
+    try {
+        const answers = await collectTicketSetup(dir, opts, undefined);
+        if (interview)
+            interview = checkpointInterview(dir, interview, { checkpoint: "save-setup", answers: { setup: answers } });
+        await validateConfiguredSourcesIfRequested(dir, answers, Boolean(opts.skipAccessCheck));
+        ensureRafiConfigForTicketSetup(dir, {
             appName: opts.appName ?? defaultAppName(dir),
-            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
             docsRoot: opts.docsRoot,
+            targets: parseRuntimeTargets(opts.runtime),
         });
-        console.log("foreman tickets setup: initialized .tickets/");
-    }
-    if (shouldPrompt(opts)) {
-        const populate = await confirm({
-            message: "Run ticket population now?",
-            initialValue: answers.sources.length > 0,
+        saveTicketSetupConfig(dir, answers, {
+            appName: opts.appName ?? defaultAppName(dir),
+            docsRoot: opts.docsRoot,
+            targets: parseRuntimeTargets(opts.runtime),
         });
-        if (isCancel(populate))
-            process.exit(0);
-        if (populate) {
-            await cmdPopulateCli({ project: dir, yes: true });
+        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)
+            completeInterview(dir, interview);
     }
-    else {
-        console.log(`foreman tickets setup: next — run \`foreman tickets populate --project ${shellQuote(dir)}\``);
+    catch (error) {
+        if (interview)
+            failInterview(dir, interview, interview.checkpoint, error);
+        throw error;
     }
 }
 async function cmdSetupUpdateCli(opts) {
     const dir = cwd(opts);
     if (!existsSync(dir))
         fail(`project directory not found: ${dir}`);
-    const current = loadTicketSetupConfigWithDefaults(dir);
-    const patch = await collectTicketSetupPatch(dir, opts, current);
-    const next = mergeTicketSetup(current, patch);
-    ensureRafiConfigForTicketSetup(dir, {
-        appName: opts.appName ?? defaultAppName(dir),
-        docsRoot: opts.docsRoot,
-        targets: parseRuntimeTargets(opts.runtime),
-    });
-    saveTicketSetupConfig(dir, next, {
-        appName: opts.appName ?? defaultAppName(dir),
-        docsRoot: opts.docsRoot,
-        targets: parseRuntimeTargets(opts.runtime),
-    });
-    console.log(`foreman tickets setup: updated ticket setup in ${join(dir, "rafi-config.yaml")}`);
-    await validateConfiguredSourcesIfRequested(next, Boolean(opts.skipAccessCheck));
-    if (isTicketsInitialized(dir)) {
-        const rows = cmdQueue(dir, 1);
-        if (rows.length === 0) {
-            console.log(`foreman tickets setup: queue is empty; run \`foreman tickets populate --project ${shellQuote(dir)}\` to import or refresh tickets.`);
+    let interview = beginTicketSetupInterview(dir, "tickets-setup-update", opts);
+    try {
+        const current = loadTicketSetupConfigWithDefaults(dir);
+        const patch = await collectTicketSetupPatch(dir, opts, current);
+        const next = mergeTicketSetup(current, patch);
+        if (interview)
+            interview = checkpointInterview(dir, interview, { checkpoint: "save-setup", answers: { setup: next } });
+        await validateConfiguredSourcesIfRequested(dir, next, Boolean(opts.skipAccessCheck));
+        ensureRafiConfigForTicketSetup(dir, {
+            appName: opts.appName ?? defaultAppName(dir),
+            docsRoot: opts.docsRoot,
+            targets: parseRuntimeTargets(opts.runtime),
+        });
+        saveTicketSetupConfig(dir, next, {
+            appName: opts.appName ?? defaultAppName(dir),
+            docsRoot: opts.docsRoot,
+            targets: parseRuntimeTargets(opts.runtime),
+        });
+        console.log(`foreman tickets setup: updated ticket setup in ${join(dir, "rafi-config.yaml")}`);
+        if (isTicketsInitialized(dir)) {
+            const rows = cmdQueue(dir, 1);
+            if (rows.length === 0) {
+                console.log(`foreman tickets setup: queue is empty; run \`foreman tickets populate --project ${shellQuote(dir)}\` to import or refresh tickets.`);
+            }
         }
+        if (interview)
+            completeInterview(dir, interview);
+    }
+    catch (error) {
+        if (interview)
+            failInterview(dir, interview, interview.checkpoint, error);
+        throw error;
     }
 }
+function beginTicketSetupInterview(projectDir, workflow, opts) {
+    if (!shouldPrompt(opts))
+        return undefined;
+    const record = createInterviewRecord({
+        workflow,
+        invocation: { projectDir, ...opts },
+        checkpoint: "setup-section",
+        outputs: ["rafi-config.yaml", ".tickets/config.yaml"],
+    });
+    return checkpointInterview(projectDir, record, { checkpoint: "setup-section" });
+}
 async function collectTicketSetup(dir, opts, current) {
     const patch = await collectTicketSetupPatch(dir, opts, current ?? DEFAULT_TICKET_SETUP);
     const build = patch.build ?? {};
@@ -229,8 +272,11 @@ async function collectTicketSetupPatch(dir, opts, current) {
         buildPatch.auto_merge_timeout_minutes = parseOptionalPositiveInteger(opts.autoMergeTimeoutMinutes, "--auto-merge-timeout-minutes");
     }
     if (!shouldPrompt(opts)) {
+        const prefill = current.sources.length === 0
+            ? configuredPlanningSources(dir).map((path) => ({ type: "local", paths: [path] }))
+            : current.sources;
         return {
-            sources: nonInteractiveSources.length > 0 ? nonInteractiveSources : current.sources,
+            sources: nonInteractiveSources.length > 0 ? nonInteractiveSources : prefill,
             populate: populatePatch,
             build: Object.keys(buildPatch).length > 0 ? buildPatch : {},
         };
@@ -246,7 +292,12 @@ async function collectTicketSetupPatch(dir, opts, current) {
     });
     if (isCancel(section))
         process.exit(0);
-    let sources = nonInteractiveSources.length > 0 ? nonInteractiveSources : current.sources;
+    // 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;
     if (section === "sources" || section === "all") {
         sources = await promptTicketSources(dir, current.sources);
     }
@@ -333,6 +384,7 @@ async function promptTicketSources(dir, current) {
             { value: "local", label: "Local docs, files, folders, or globs" },
             { value: "linear", label: "Linear" },
             { value: "jira", label: "Jira Cloud" },
+            { value: "url", label: "Public URL (HTML, text, Markdown, or PDF)" },
             { value: "none", label: "No saved source" },
         ],
     });
@@ -365,6 +417,17 @@ async function promptTicketSources(dir, current) {
                 filter: String(filter).trim() || null,
             }];
     }
+    if (kind === "url") {
+        const existing = current.find((source) => source.type === "url");
+        const answer = await text({
+            message: "Public HTTP(S) URL:",
+            initialValue: existing?.url,
+            validate: (value) => /^https?:\/\//i.test(String(value ?? "")) ? undefined : "Enter an HTTP(S) URL",
+        });
+        if (isCancel(answer))
+            process.exit(0);
+        return [{ type: "url", url: String(answer).trim() }];
+    }
     const site = await text({
         message: "Jira Cloud site URL:",
         placeholder: "https://your-domain.atlassian.net",
@@ -410,9 +473,11 @@ function sourcesFromSetupOptions(opts) {
             jql: opts.jiraJql,
         });
     }
+    for (const url of opts.urlSource ?? [])
+        sources.push({ type: "url", url });
     return sources;
 }
-async function validateConfiguredSourcesIfRequested(setup, skip) {
+async function validateConfiguredSourcesIfRequested(projectDir, setup, skip) {
     if (skip)
         return;
     for (const source of externalSources(setup)) {
@@ -424,6 +489,12 @@ async function validateConfiguredSourcesIfRequested(setup, skip) {
             console.log(`foreman tickets setup: ${source.type} access check skipped/failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    for (const source of urlSources(setup)) {
+        const fetched = await fetchAndSnapshotUrl(projectDir, source.url).catch((err) => {
+            throw new Error(`URL access validation failed for ${source.url}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        console.log(`foreman tickets setup: validated URL access (${fetched.contentType}, ${fetched.bytes} bytes)`);
+    }
 }
 function shouldPrompt(opts) {
     return !opts.defaults && !opts.yes && process.stdin.isTTY && process.stdout.isTTY;
@@ -587,12 +658,21 @@ export async function cmdPopulateCli(opts) {
     }
     const ticketsConfig = loadTicketsConfig(dir);
     const setup = loadTicketSetupConfig(dir);
-    const explicitSources = opts.sources;
+    const explicitSources = opts.sources ? await prepareDocumentSources(dir, opts.sources) : undefined;
     const configuredExternalSources = explicitSources?.length ? [] : externalSources(setup);
+    const configuredUrlSources = explicitSources?.length ? [] : urlSources(setup);
     const savedLocalSources = explicitSources?.length ? [] : localSourcePaths(setup);
-    const sourceHints = configuredExternalSources.length > 0 && savedLocalSources.length === 0
+    const selectedLocalHints = configuredExternalSources.length > 0 && savedLocalSources.length === 0 && configuredUrlSources.length === 0
         ? undefined
         : await resolvePopulateSourceSelection(dir, explicitSources, ticketsConfig, Boolean(opts.yes));
+    const localHints = selectedLocalHints ? await prepareDocumentSources(dir, selectedLocalHints) : undefined;
+    const urlHints = [];
+    for (const source of configuredUrlSources) {
+        const fetched = await fetchAndSnapshotUrl(dir, source.url);
+        urlHints.push(fetched.snapshotPath);
+        console.log(`foreman tickets: fetched ${source.url} -> ${fetched.snapshotPath}`);
+    }
+    const sourceHints = unique([...(localHints ?? []), ...urlHints]);
     const populateAgent = opts.agent
         ?? (setup?.populate.agent_preference && setup.populate.agent_preference !== "configured"
             ? setup.populate.agent_preference
@@ -628,7 +708,7 @@ export async function cmdPopulateCli(opts) {
             if (!validation.clean)
                 process.exit(1);
         }
-        if (!sourceHints?.length) {
+        if (!sourceHints.length) {
             console.log(`foreman tickets: imported external tickets and rendered ${ticketsConfig.paths.progressDoc}`);
             return;
         }
@@ -668,7 +748,7 @@ 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) {
+        if (sourceHints.length) {
             console.log(`foreman tickets: source hints ${sourceHints.join(" ")}`);
         }
         const turn = await foreman.runInstruction(buildPopulateInstruction(sourceHints, ticketsConfig.paths.progressDoc));
@@ -711,6 +791,21 @@ export async function cmdPopulateCli(opts) {
         fail(String(err instanceof Error ? err.message : err));
     }
 }
+async function prepareDocumentSources(projectDir, sources) {
+    const prepared = [];
+    for (const source of sources) {
+        if (/^https?:\/\//i.test(source)) {
+            prepared.push((await fetchAndSnapshotUrl(projectDir, source)).snapshotPath);
+            continue;
+        }
+        const absolute = resolve(source);
+        if (isAbsolute(source) && existsSync(absolute))
+            prepared.push(snapshotExternalLocalFile(projectDir, absolute));
+        else
+            prepared.push(source);
+    }
+    return unique(prepared);
+}
 export function buildTicketsCommand() {
     const tickets = new Command("tickets").description("Manage the structured ticket tracker for a project.");
     // ── setup:init / setup:update ─────────────────────────────────────────────
@@ -729,12 +824,13 @@ export function buildTicketsCommand() {
         .option("--linear-filter <filter>", "Linear IssueFilter JSON or title search text")
         .option("--jira-site <url>", "Jira Cloud site URL")
         .option("--jira-jql <jql>", "Jira JQL query")
+        .option("--url-source <urls...>", "add public HTTP(S) source URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
         .option("--auto-merge-timeout-minutes <n>", "auto-merge dependency wait timeout in minutes (blank means no timeout)")
-        .option("--skip-access-check", "do not validate Linear/Jira access during setup")
+        .option("--skip-access-check", "do not validate configured source access during setup")
         .action(async (opts) => {
         try {
             await cmdSetupInitCli(opts);
@@ -758,12 +854,13 @@ export function buildTicketsCommand() {
         .option("--linear-filter <filter>", "Linear IssueFilter JSON or title search text")
         .option("--jira-site <url>", "Jira Cloud site URL")
         .option("--jira-jql <jql>", "Jira JQL query")
+        .option("--url-source <urls...>", "replace saved sources with public HTTP(S) URLs")
         .option("--agent-preference <agent>", "populate runtime preference (configured | claude | codex)")
         .option("--completion <mode>", "build completion default (pr | auto-merge | direct-merge | none)")
         .option("--provider <provider>", "PR/MR provider default (auto | github | gitlab | local)")
         .option("--auto-merge-wait", "wait for dependency PR/MRs to merge before starting dependent tickets")
         .option("--auto-merge-timeout-minutes <n>", "auto-merge dependency wait timeout in minutes (blank means no timeout)")
-        .option("--skip-access-check", "do not validate Linear/Jira access during setup")
+        .option("--skip-access-check", "do not validate configured source access during setup")
         .action(async (opts) => {
         try {
             await cmdSetupUpdateCli(opts);

package/dist/foreman.d.ts

@@ -49,13 +49,15 @@ export declare class Foreman {
     private readonly qaEnabled;
     private readonly qaMaxCycles;
     private readonly projectDir?;
+    private readonly qaReviewer?;
     private readonly ticketsEnabled;
-    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined);
+    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined);
     /**
      * Send one instruction and resolve any needs_input exchanges before returning.
      * The returned result and status always reflect the final (non-needs_input) turn.
      */
     private doTurn;
+    private doTurnWith;
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
     runPreflight(n: number, ticketsContent?: string): Promise<string>;
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */

package/dist/foreman.js

@@ -3,6 +3,9 @@ import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { fireNotification } from "./notify.js";
 import { isTicketsInitialized } from "./tickets/config.js";
 import { cmdUpdate, cmdComplete, cmdBlock, cmdImplementationQueue } from "./tickets/commands.js";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
 /** Phrases that suggest the builder ended its turn by asking the human. */
 const QUESTION_HINTS = [
     "should i",
@@ -192,14 +195,16 @@ export class Foreman {
     qaEnabled;
     qaMaxCycles;
     projectDir;
+    qaReviewer;
     ticketsEnabled;
-    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir) {
+    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer) {
         this.builder = builder;
         this.log = log;
         this.notificationsEnabled = notificationsEnabled;
         this.qaEnabled = qaEnabled;
         this.qaMaxCycles = qaMaxCycles;
         this.projectDir = projectDir;
+        this.qaReviewer = qaReviewer;
         this.ticketsEnabled = !!(projectDir && isTicketsInitialized(projectDir));
     }
     /**
@@ -207,7 +212,10 @@ export class Foreman {
      * The returned result and status always reflect the final (non-needs_input) turn.
      */
     async doTurn(instruction) {
-        let result = await this.builder.sendTurn(instruction);
+        return this.doTurnWith(this.builder, instruction);
+    }
+    async doTurnWith(adapter, instruction) {
+        let result = await adapter.sendTurn(instruction);
         let status = parseStepStatus(result.text);
         while (status.kind === "needs_input") {
             const question = status.question ?? "The builder has a question";
@@ -229,7 +237,7 @@ export class Foreman {
                 status = { kind: "blocked", reason: "user cancelled at input prompt" };
                 break;
             }
-            result = await this.builder.sendTurn(String(answer));
+            result = await adapter.sendTurn(String(answer));
             status = parseStepStatus(result.text);
         }
         return { result, status };
@@ -260,7 +268,15 @@ export class Foreman {
      */
     async runQa(stepIndex) {
         for (let cycle = 1; cycle <= this.qaMaxCycles; cycle++) {
-            const qa = await this.doTurn(buildQaInstruction());
+            const before = this.qaReviewer && this.projectDir ? fingerprintProtectedTree(this.projectDir) : undefined;
+            const qa = await this.doTurnWith(this.qaReviewer ?? this.builder, buildQaInstruction());
+            if (before && this.projectDir) {
+                const changes = changedProtectedFiles(before, fingerprintProtectedTree(this.projectDir));
+                if (changes.length > 0) {
+                    this.log.write("qa-protected-files-changed", { stepIndex, cycle, paths: changes });
+                    return { outcome: "needs-human", detail: `independent QA changed protected files: ${changes.join(", ")}` };
+                }
+            }
             this.log.write("qa", {
                 stepIndex,
                 cycle,
@@ -448,3 +464,29 @@ function lastLine(text) {
     const lines = text.trim().split("\n");
     return (lines[lines.length - 1] ?? "").slice(0, 200);
 }
+function fingerprintProtectedTree(root) {
+    const out = new Map();
+    const ignored = new Set([".git", "node_modules", "dist", "coverage"]);
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            const rel = relative(root, path).replace(/\\/g, "/");
+            if (entry.isDirectory()) {
+                if (ignored.has(entry.name) || rel.startsWith(".foreman/") || rel.startsWith(".rafi/cache/"))
+                    continue;
+                visit(path);
+            }
+            else if (entry.isFile() && statSync(path).size <= 10 * 1024 * 1024) {
+                out.set(rel, createHash("sha256").update(readFileSync(path)).digest("hex"));
+            }
+        }
+    };
+    if (existsSync(root))
+        visit(root);
+    return out;
+}
+function changedProtectedFiles(before, after) {
+    return [...new Set([...before.keys(), ...after.keys()])]
+        .filter((path) => before.get(path) !== after.get(path))
+        .sort();
+}