ai-foreman 1.6.2 → 1.7.0

package/dist/cli/tickets.js

@@ -7,15 +7,19 @@ import { loadConfig } from "../config.js";
 import { Log } from "../log.js";
 import { Foreman } from "../foreman.js";
 import { printEvents } from "./events.js";
-import { cmdInit, cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdCancel, cmdDiscover, cmdAcceptFutureWork, cmdReorder, cmdRender, cmdValidate, cmdQueue, cmdArchive, cmdReview, } from "../tickets/commands.js";
+import { cmdInit, cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdCancel, cmdDiscover, cmdAcceptFutureWork, cmdReorder, cmdRender, cmdValidate, cmdQueue, cmdStackQueue, cmdArchive, cmdReview, } from "../tickets/commands.js";
+import { loadDeliveryConfig } from "../tickets/delivery.js";
 import { DEFAULT_TICKETS_CONFIG, isTicketsInitialized, loadTicketsConfig } from "../tickets/config.js";
 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 { 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 { 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";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
@@ -59,30 +63,28 @@ Goal:
 - Do not implement product/code changes. Only update ticket-tracker files.
 ${sourceHintBlock}
 
-Before editing, read these tracker control files:
+Before proposing, read these tracker control files:
 - .tickets/config.yaml
 - .tickets/tickets.yaml
 - .tickets/tracker-rules.md
 - ${progressDoc} if it exists
 
-Then inspect the repository for existing planning sources. Check root and docs-style Markdown/YAML/TXT files whose names suggest tickets, backlog, roadmap, plan, TODOs, milestones, progress, specs, phases, or implementation steps. Preserve every ticket or task you find. Do not leave out details.
+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.
 
-Write the canonical ticket definitions to .tickets/tickets.yaml using Foreman's schema:
-- id: stable ticket ID. Preserve existing IDs. If no IDs exist, assign T001, T002, ... in implementation order.
+Return ticket content using Foreman's schema:
+- slice_ref: the exact approved plan slice reference. Do not allocate ticket IDs.
 - order: unique numeric implementation order. Use gaps like 1000, 2000, 3000.
 - title, area, priority, size, risk, depends_on, summary, acceptance, required_tests, likely_files, rollback, notes.
 - Keep dependencies, acceptance criteria, testing expectations, file hints, risk notes, and implementation notes from the source material.
 - Do not store mutable status/progress fields in .tickets/tickets.yaml.
-- Do not edit .tickets/ticket-state.sqlite directly.
+- Dependencies must reference slice_ref values. Include the exact IDs of existing populated tickets whose removed slices should become obsolete.
 
 If source content does not cleanly map to the new schema, ask for guidance instead of guessing. Use:
 STEP_STATUS: needs_input | question="..." choices="..."
 
-After editing:
-- Run foreman tickets render.
-- Run foreman tickets validate.
-- Fix validation errors if possible.
-- Triple-check that every source ticket/task is represented exactly once and no important detail was dropped.
+Output one JSON object between ${TICKET_POPULATION_PROPOSAL_START} and ${TICKET_POPULATION_PROPOSAL_END} with shape:
+{"version":1,"plan_id":"approved plan ID","revision":1,"tickets":[{"slice_ref":"slc_...","title":"...","area":"...","priority":"P1","size":"S","risk":"Low","summary":"...","acceptance":["..."],"required_tests":["..."],"likely_files":["..."],"depends_on":["slice_ref"],"rollback":null,"notes":null}],"retirements":["exact existing ticket ID"]}
+Triple-check that every approved slice appears exactly once.
 
 End with exactly one marker line as the final non-empty line:
 STEP_STATUS: done | summary="populated Foreman tickets from existing project ticket sources"
@@ -134,6 +136,8 @@ export function buildPopulateAgentRunOptions(opts) {
         yes: opts.yes,
         label: "tickets populate",
         log: opts.log,
+        permissionConfig: readOnlyPermissionConfig(),
+        sandboxMode: "read-only",
     };
 }
 async function cmdSetupInitCli(opts) {
@@ -713,11 +717,12 @@ export async function cmdPopulateCli(opts) {
             return;
         }
     }
+    const structuredPlan = loadPopulationPlan(dir, sourceHints);
     if (!opts.yes) {
         const action = await select({
-            message: "Populate .tickets/tickets.yaml by letting the builder edit this project?",
+            message: "Ask the read-only Ticket Maker for a structured population proposal?",
             options: [
-                { value: "proceed", label: "Proceed - builder may edit ticket files" },
+                { value: "proceed", label: "Proceed - generate proposal only" },
                 { value: "cancel", label: "Cancel" },
             ],
         });
@@ -772,18 +777,29 @@ export async function cmdPopulateCli(opts) {
             console.error(`foreman tickets: needs human — ${turn.status.error ?? "builder did not emit done"}`);
             process.exit(2);
         }
-        cmdRender(dir);
-        const validation = cmdValidate(dir);
-        if (validation.issues.length > 0) {
-            console.log(`foreman tickets: ${validation.issues.length} validation issue(s) found:`);
-            console.log(formatValidationIssues(validation.issues));
-            if (!validation.clean)
-                process.exit(1);
-        }
-        else {
-            console.log("foreman tickets: validation passed — all 4 passes clean");
+        const existing = loadTickets(resolveTicketPaths(ticketsConfig, dir).tickets);
+        const proposal = extractTicketPopulationProposal(turn.result.text);
+        const materialized = materializeTicketPopulation(proposal, structuredPlan, existing);
+        let retirementsConfirmed = false;
+        if (!opts.yes) {
+            console.log(`foreman tickets: proposal maps ${materialized.sliceToTicket.size} slice(s) and retires ${materialized.retirements.join(", ") || "none"}`);
+            const approved = await confirm({ message: "Apply this exact ticket and delivery proposal?", initialValue: false });
+            if (isCancel(approved) || !approved) {
+                console.log("foreman tickets: cancelled; no files or tracker state changed");
+                return;
+            }
+            if (materialized.retirements.length) {
+                const retirement = await confirm({ message: `Mark these removed-slice tickets obsolete: ${materialized.retirements.join(", ")}?`, initialValue: false });
+                if (isCancel(retirement) || !retirement) {
+                    console.log("foreman tickets: cancelled; no files or tracker state changed");
+                    return;
+                }
+                retirementsConfirmed = true;
+            }
         }
-        console.log(`foreman tickets: populated .tickets/tickets.yaml and rendered ${ticketsConfig.paths.progressDoc}`);
+        authorizeTicketRetirements(materialized.retirements, { interactiveConfirmed: retirementsConfirmed, authorizedIds: opts.authorizeRetire, computerRun: Boolean(opts.yes) });
+        const applied = applyTicketPopulation(dir, materialized);
+        console.log(`foreman tickets: populated atomically (run ${applied.runId}, transaction ${applied.transactionId})`);
     }
     catch (err) {
         await builder?.close().catch(() => { });
@@ -806,6 +822,17 @@ 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))
+            continue;
+        const plan = JSON.parse(readFileSync(candidate, "utf8"));
+        if (plan.version === 1 && plan.plan_id && Number.isInteger(plan.revision) && plan.content_digest)
+            return plan;
+    }
+    throw new Error("ticket population requires the approved paired structured plan (normally docs/rafi-plan.json); run `rafi plan --validate` first");
+}
 export function buildTicketsCommand() {
     const tickets = new Command("tickets").description("Manage the structured ticket tracker for a project.");
     // ── setup:init / setup:update ─────────────────────────────────────────────
@@ -915,7 +942,8 @@ export function buildTicketsCommand() {
         .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
         .option("--sources <paths...>", "source hint files, folders, or globs to check first")
         .option("--fast", "fast mode - lower latency")
-        .option("-y, --yes", "skip confirmation prompt before letting the builder edit tickets")
+        .option("--authorize-retire <ids...>", "exact ticket IDs authorized to become obsolete in computer-run mode")
+        .option("-y, --yes", "computer-run approval; retirements still require --authorize-retire exact IDs")
         .action(async (opts) => {
         try {
             await cmdPopulateCli(opts);
@@ -1233,9 +1261,21 @@ export function buildTicketsCommand() {
         .description("Print the ticket queue to stdout.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--limit <n>", "override view limit")
+        .option("--refresh", "query GitHub/GitLab and refresh cached stack review state")
         .action((opts) => {
         try {
-            const rows = cmdQueue(cwd(opts), opts.limit !== undefined ? Number(opts.limit) : undefined);
+            const dir = cwd(opts);
+            const delivery = loadDeliveryConfig(dir);
+            if (delivery?.stacks?.length) {
+                const lines = cmdStackQueue(dir, Boolean(opts.refresh));
+                if (!lines.length)
+                    console.log("No remaining tickets.");
+                else
+                    for (const line of lines)
+                        console.log(line);
+                return;
+            }
+            const rows = cmdQueue(dir, opts.limit !== undefined ? Number(opts.limit) : undefined);
             if (rows.length === 0) {
                 console.log("No remaining tickets.");
             }

package/dist/foreman.d.ts

@@ -1,6 +1,8 @@
 import type { BuilderAdapter, PermissionHandler, TurnResult } from "./adapters/types.js";
 import type { PermissionPolicy } from "./permissions/policy.js";
 import type { Log } from "./log.js";
+import { type QaNonconvergenceContext, type QaNonconvergenceDecision } from "./qaReview.js";
+import type { SessionStrategy } from "rafi-spec";
 /** Parsed STEP_STATUS marker from a builder's turn. */
 export interface StepStatus {
     kind: "done" | "blocked" | "plan_complete" | "needs_input" | "qa_pass" | "qa_fail" | "unknown";
@@ -43,20 +45,28 @@ export interface BatchResult {
 }
 /** Drives one builder through a batch of N steps via the STEP_STATUS protocol. */
 export declare class Foreman {
-    private readonly builder;
+    private builder;
     private readonly log;
     private readonly notificationsEnabled;
     private readonly qaEnabled;
     private readonly qaMaxCycles;
     private readonly projectDir?;
     private readonly qaReviewer?;
+    private readonly qaFactory?;
+    private readonly qaSessionStrategy;
+    private readonly builderFactory?;
+    private readonly builderSessionStrategy;
+    private readonly qaNonconvergence?;
     private readonly ticketsEnabled;
-    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined);
+    private readonly qaStream;
+    private builderWorkSessions;
+    constructor(builder: BuilderAdapter, log: Log, notificationsEnabled?: boolean, qaEnabled?: boolean, qaMaxCycles?: number, projectDir?: string | undefined, qaReviewer?: BuilderAdapter | undefined, qaFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, qaSessionStrategy?: SessionStrategy, builderFactory?: ((cwd: string, sessionId?: string) => Promise<BuilderAdapter>) | undefined, builderSessionStrategy?: SessionStrategy, qaNonconvergence?: ((context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>) | 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 prepareBuilderBoundary;
     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>;
@@ -74,9 +84,14 @@ export declare class Foreman {
      */
     private runQa;
     runQaReview(stepIndex: number): Promise<{
-        outcome: "passed" | "blocked" | "needs-human";
+        outcome: "passed" | "blocked" | "needs-human" | "waived";
         detail?: string;
         summary?: string;
     }>;
+    qaSessionId(): string | undefined;
+    builderSessionId(): string | undefined;
+    builderAdapter(): BuilderAdapter;
+    close(): Promise<void>;
+    private ticketForQa;
     runBatch(n: number, trackerPath?: string): Promise<BatchResult>;
 }

package/dist/foreman.js

@@ -1,8 +1,10 @@
 import { select, isCancel } from "@clack/prompts";
 import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { fireNotification } from "./notify.js";
-import { isTicketsInitialized } from "./tickets/config.js";
+import { isTicketsInitialized, loadTicketsConfig } from "./tickets/config.js";
 import { cmdUpdate, cmdComplete, cmdBlock, cmdImplementationQueue } from "./tickets/commands.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { runIsolatedQa } from "./qaReview.js";
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
@@ -196,8 +198,15 @@ export class Foreman {
     qaMaxCycles;
     projectDir;
     qaReviewer;
+    qaFactory;
+    qaSessionStrategy;
+    builderFactory;
+    builderSessionStrategy;
+    qaNonconvergence;
     ticketsEnabled;
-    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer) {
+    qaStream = { reviews: 0, modificationViolations: 0 };
+    builderWorkSessions = 0;
+    constructor(builder, log, notificationsEnabled = false, qaEnabled = true, qaMaxCycles = 3, projectDir, qaReviewer, qaFactory, qaSessionStrategy = "compact", builderFactory, builderSessionStrategy = "compact", qaNonconvergence) {
         this.builder = builder;
         this.log = log;
         this.notificationsEnabled = notificationsEnabled;
@@ -205,6 +214,11 @@ export class Foreman {
         this.qaMaxCycles = qaMaxCycles;
         this.projectDir = projectDir;
         this.qaReviewer = qaReviewer;
+        this.qaFactory = qaFactory;
+        this.qaSessionStrategy = qaSessionStrategy;
+        this.builderFactory = builderFactory;
+        this.builderSessionStrategy = builderSessionStrategy;
+        this.qaNonconvergence = qaNonconvergence;
         this.ticketsEnabled = !!(projectDir && isTicketsInitialized(projectDir));
     }
     /**
@@ -214,9 +228,54 @@ export class Foreman {
     async doTurn(instruction) {
         return this.doTurnWith(this.builder, instruction);
     }
+    async prepareBuilderBoundary() {
+        if (!this.builderFactory || !this.projectDir)
+            return;
+        if (this.builderSessionStrategy === "fresh") {
+            await this.builder.close();
+            this.builder = await this.builderFactory(this.projectDir);
+            this.log.write("branch-session", { role: "builder", transition: "fresh", workSession: this.builderWorkSessions + 1 });
+            return;
+        }
+        const priorSession = this.builder.sessionId();
+        if (priorSession && this.builder.compact) {
+            let error = "";
+            for (let attempt = 1; attempt <= 2; attempt++) {
+                const result = await this.builder.compact().catch((cause) => ({ ok: false, error: cause instanceof Error ? cause.message : String(cause) }));
+                if (result.ok) {
+                    this.log.write("branch-session", { role: "builder", transition: attempt === 1 ? "compacted" : "compaction-retry-succeeded", workSession: this.builderWorkSessions + 1, sessionId: priorSession });
+                    return;
+                }
+                error = result.error ?? "native compaction failed";
+                if (attempt === 1)
+                    this.log.write("branch-session", { role: "builder", transition: "compaction-retry", detail: error });
+            }
+            await this.builder.close();
+            this.builder = await this.builderFactory(this.projectDir);
+            this.log.write("branch-session", { role: "builder", transition: "compaction-fallback-fresh", continuityLost: true, detail: error });
+            return;
+        }
+        await this.builder.close();
+        this.builder = await this.builderFactory(this.projectDir);
+        this.log.write("branch-session", { role: "builder", transition: "missing-session-fresh", continuityLost: true });
+    }
     async doTurnWith(adapter, instruction) {
         let result = await adapter.sendTurn(instruction);
         let status = parseStepStatus(result.text);
+        if (status.kind === "unknown") {
+            if (!status.error && looksLikeQuestion(result.text)) {
+                status = { kind: "needs_input", question: lastLine(result.text), choices: ["Continue", "Cancel"] };
+            }
+            else {
+                const qa = /\bQA\b|qa_pass|qa_fail/i.test(instruction);
+                result = await adapter.sendTurn(qa
+                    ? "Protocol correction only: based on the review already completed, return exactly one final STEP_STATUS: qa_pass or STEP_STATUS: qa_fail marker. Do not repeat QA, tests, tools, or compaction."
+                    : "Protocol correction only: based on the work already completed, return exactly one final STEP_STATUS: done, plan_complete, blocked, or needs_input marker. Do not repeat implementation, tools, or compaction.");
+                status = parseStepStatus(result.text);
+                if (status.kind === "unknown")
+                    status = { ...status, error: `protocol correction exhausted: ${status.error ?? "missing final marker"}` };
+            }
+        }
         while (status.kind === "needs_input") {
             const question = status.question ?? "The builder has a question";
             const choices = status.choices?.length
@@ -272,6 +331,31 @@ export class Foreman {
      * QA turns are free — they do not advance the step counter.
      */
     async runQa(stepIndex) {
+        if (this.projectDir && this.qaFactory) {
+            const review = await runIsolatedQa({
+                ticket: this.ticketForQa(stepIndex),
+                builderWorktree: this.projectDir,
+                builderSummary: `Builder completed step ${stepIndex}`,
+                qaStrategy: this.qaSessionStrategy,
+                state: this.qaStream,
+                createQa: this.qaFactory,
+                maxCycles: this.qaMaxCycles,
+                fix: async (issues) => {
+                    await this.prepareBuilderBoundary();
+                    this.builderWorkSessions += 1;
+                    const fix = await this.doTurn(buildQaFixInstruction(issues));
+                    this.log.write("qa-fix", { stepIndex, statusKind: fix.status.kind, costUsd: fix.result.costUsd, isError: fix.result.isError });
+                    return fix.result.isError || fix.status.kind !== "done"
+                        ? { ok: false, detail: fix.status.reason ?? fix.status.error ?? fix.result.text.slice(0, 200) }
+                        : { ok: true };
+                },
+                evidence: ({ cycle, outcome, detail, qaDiff }) => this.log.write("qa", { stepIndex, cycle, outcome, detail, qaDiff, disposable: true }),
+                onNonconvergence: this.qaNonconvergence,
+            });
+            if (review.outcome === "nonconverged")
+                return { outcome: "needs-human", detail: review.detail };
+            return { outcome: review.outcome, detail: review.detail, summary: review.summary };
+        }
         for (let cycle = 1; cycle <= this.qaMaxCycles; cycle++) {
             const before = this.qaReviewer && this.projectDir ? fingerprintProtectedTree(this.projectDir) : undefined;
             const qa = await this.doTurnWith(this.qaReviewer ?? this.builder, buildQaInstruction());
@@ -335,6 +419,24 @@ export class Foreman {
     async runQaReview(stepIndex) {
         return this.runQa(stepIndex);
     }
+    qaSessionId() { return this.qaStream.sessionId ?? this.qaReviewer?.sessionId(); }
+    builderSessionId() { return this.builder.sessionId(); }
+    builderAdapter() { return this.builder; }
+    async close() { await this.builder.close(); }
+    ticketForQa(stepIndex) {
+        if (this.projectDir && this.ticketsEnabled) {
+            const config = loadTicketsConfig(this.projectDir);
+            const active = cmdImplementationQueue(this.projectDir).find((row) => row.status === "next" || row.status === "in_progress");
+            const ticket = loadTickets(join(this.projectDir, config.paths.tickets)).find((candidate) => candidate.id === active?.ticket);
+            if (ticket)
+                return ticket;
+        }
+        return {
+            id: `STEP-${stepIndex}`, order: stepIndex, title: `Implementation step ${stepIndex}`, area: "project",
+            priority: "P2", size: "M", risk: "Low", depends_on: [], summary: `Review implementation step ${stepIndex}`,
+            acceptance: ["The requested implementation step is complete"], required_tests: ["Run the relevant project validation"], likely_files: [],
+        };
+    }
     async runBatch(n, trackerPath) {
         this.log.write("batch-start", { requested: n, agent: this.builder.agent });
         let completed = 0;
@@ -365,6 +467,9 @@ export class Foreman {
             const instruction = i === 1
                 ? buildPrimer(n, trackerPath, this.ticketsEnabled)
                 : buildNextStepInstruction(i, n);
+            if (i > 1)
+                await this.prepareBuilderBoundary();
+            this.builderWorkSessions += 1;
             const { result, status } = await this.doTurn(instruction);
             this.log.write("step", {
                 index: i,
@@ -383,6 +488,7 @@ export class Foreman {
             }
             if (status.kind === "done" || status.kind === "plan_complete") {
                 let qaSummary;
+                let qaWaived = false;
                 if (this.qaEnabled) {
                     const qa = await this.runQa(i);
                     if (qa.outcome === "blocked") {
@@ -395,6 +501,7 @@ export class Foreman {
                         detail = qa.detail;
                         break;
                     }
+                    qaWaived = qa.outcome === "waived";
                     qaSummary = qa.summary;
                 }
                 // Update ticket state only after QA has passed, so generated tracker
@@ -406,12 +513,12 @@ export class Foreman {
                             cmdComplete(this.projectDir, ticketId, {
                                 actor: "foreman",
                                 summary: status.summary ?? `Step ${i} complete`,
-                                validationResult: this.qaEnabled ? "passed" : "not_applicable",
+                                validationResult: qaWaived ? "failed" : this.qaEnabled ? "passed" : "not_applicable",
                                 validationNotes: this.qaEnabled
-                                    ? "Foreman QA emitted qa_pass"
+                                    ? qaWaived ? "User explicitly waived unresolved QA failures" : "Foreman QA emitted qa_pass"
                                     : "Foreman QA disabled for this run",
                                 evidence: this.qaEnabled
-                                    ? (qaSummary ?? "Foreman QA emitted qa_pass")
+                                    ? (qaSummary ?? (qaWaived ? "Unresolved QA issues preserved in run evidence" : "Foreman QA emitted qa_pass"))
                                     : undefined,
                             });
                         }

package/dist/log.d.ts

@@ -1,7 +1,7 @@
 /** A single structured log record. */
 export interface LogRecord {
     ts: string;
-    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "error";
+    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "uninstall-proposal" | "qa" | "qa-fix" | "qa-protected-files-changed" | "qa-evidence" | "agent-status" | "error";
     [key: string]: unknown;
 }
 /** Append-only JSONL logger. One line per record, plus an echo to the console. */

package/dist/operationRecovery.d.ts

@@ -0,0 +1,25 @@
+import type { OperationRecord } from "./workflowDb.js";
+export type ReconciliationResult = {
+    outcome: "confirmed";
+    externalId?: string;
+    detail: string;
+} | {
+    outcome: "absent";
+    detail: string;
+} | {
+    outcome: "uncertain";
+    detail: string;
+    inspectionCommands: string[];
+};
+export interface RemoteReviewInspector {
+    (intent: Record<string, unknown>): Promise<{
+        found: boolean;
+        url?: string;
+        head?: string;
+        base?: string;
+        uncertain?: string;
+    }>;
+}
+/** Prove a side effect before recovery decides whether the stable operation may retry. */
+export declare function reconcileOperation(projectDir: string, operation: OperationRecord, inspectReview?: RemoteReviewInspector): Promise<ReconciliationResult>;
+export declare function recoveryDecision(result: ReconciliationResult): "continue" | "retry" | "pause";

package/dist/operationRecovery.js

@@ -0,0 +1,46 @@
+import { spawnSync } from "node:child_process";
+/** Prove a side effect before recovery decides whether the stable operation may retry. */
+export async function reconcileOperation(projectDir, operation, inspectReview) {
+    const intent = operation.intent;
+    if (operation.status === "confirmed")
+        return { outcome: "confirmed", externalId: operation.externalId, detail: "operation already has a confirmed receipt" };
+    if (operation.kind === "commit") {
+        const sha = String(operation.result?.sha ?? operation.externalId ?? "");
+        if (!sha)
+            return { outcome: "absent", detail: "no commit receipt or SHA exists" };
+        const exists = spawnSync("git", ["-C", projectDir, "cat-file", "-e", `${sha}^{commit}`], { encoding: "utf8" });
+        return exists.status === 0 ? { outcome: "confirmed", externalId: sha, detail: `commit ${sha} exists` } : { outcome: "absent", detail: `commit ${sha} is absent` };
+    }
+    if (operation.kind === "push") {
+        const branch = String(intent.branch ?? "");
+        const expected = String(intent.sha ?? "");
+        const check = spawnSync("git", ["-C", projectDir, "ls-remote", "--heads", "origin", `refs/heads/${branch}`], { encoding: "utf8" });
+        if (check.status !== 0)
+            return { outcome: "uncertain", detail: check.stderr.trim() || "remote branch lookup failed", inspectionCommands: [`git -C ${quote(projectDir)} ls-remote --heads origin refs/heads/${branch}`] };
+        const actual = check.stdout.trim().split(/\s+/)[0] ?? "";
+        if (!actual)
+            return { outcome: "absent", detail: `remote branch ${branch} is absent` };
+        if (expected && actual !== expected)
+            return { outcome: "uncertain", detail: `remote branch ${branch} is ${actual}, expected ${expected}`, inspectionCommands: [`git -C ${quote(projectDir)} fetch origin ${quote(branch)}`, `git -C ${quote(projectDir)} log --oneline --decorate -5 origin/${quote(branch)}`] };
+        return { outcome: "confirmed", externalId: branch, detail: `remote branch ${branch} points at ${actual}` };
+    }
+    if (operation.kind === "pr-create" || operation.kind === "mr-create") {
+        if (!inspectReview)
+            return { outcome: "uncertain", detail: "no authenticated review inspector is available", inspectionCommands: [operation.kind === "pr-create" ? "gh pr list --state all --json url,headRefName,baseRefName" : "glab mr list --all"] };
+        const result = await inspectReview(intent);
+        if (result.uncertain)
+            return { outcome: "uncertain", detail: result.uncertain, inspectionCommands: [operation.kind === "pr-create" ? "gh pr list --state all --json url,headRefName,baseRefName" : "glab mr list --all"] };
+        if (!result.found)
+            return { outcome: "absent", detail: "matching review is absent" };
+        if (result.head !== intent.head || result.base !== intent.base)
+            return { outcome: "uncertain", detail: `review head/base does not match intended ${intent.head} -> ${intent.base}`, inspectionCommands: [operation.kind === "pr-create" ? `gh pr view ${quote(result.url ?? "")}` : `glab mr view ${quote(result.url ?? "")}`] };
+        return { outcome: "confirmed", externalId: result.url, detail: "matching review exists with the intended head and base" };
+    }
+    if (operation.kind === "ticket-complete" || operation.kind === "tracker-update")
+        return { outcome: "uncertain", detail: "tracker reconciliation requires the tracker state adapter", inspectionCommands: ["rafi tickets validate", "rafi tickets queue"] };
+    return { outcome: "uncertain", detail: `no reconciler registered for ${operation.kind}`, inspectionCommands: ["rafi status"] };
+}
+export function recoveryDecision(result) {
+    return result.outcome === "confirmed" ? "continue" : result.outcome === "absent" ? "retry" : "pause";
+}
+function quote(value) { return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`; }

package/dist/outcomes.d.ts

@@ -0,0 +1,16 @@
+import type { ConfigurableAgentRole, WorkflowIssue, WorkflowIssueCode } from "rafi-spec";
+import type { StepStatus } from "./foreman.js";
+export interface IssueContext {
+    role?: ConfigurableAgentRole;
+    phase: string;
+    step?: number;
+    ticket?: string;
+    stack?: string;
+    qaCycle?: number;
+    provider?: "claude" | "codex";
+    model?: string;
+    now?: Date;
+}
+export declare function protocolIssue(status: StepStatus, context: IssueContext): WorkflowIssue;
+export declare function issue(code: WorkflowIssueCode, context: IssueContext, detail: string, humanRequired: boolean, recoverable: boolean, suggestedAction: string): WorkflowIssue;
+export declare function formatWorkflowIssue(value: WorkflowIssue): string;

package/dist/outcomes.js

@@ -0,0 +1,27 @@
+export function protocolIssue(status, context) {
+    const detail = status.error ?? "role did not emit a final marker";
+    let code = "role_marker_missing";
+    if (/multiple|duplicate/i.test(detail))
+        code = "role_marker_duplicated";
+    else if (/not the final/i.test(detail))
+        code = "role_marker_non_final";
+    else if (/malformed|unterminated|field/i.test(detail))
+        code = "role_marker_malformed";
+    else if (/exhausted/i.test(detail))
+        code = "role_protocol_exhausted";
+    else if (status.kind !== "unknown")
+        code = "role_marker_invalid";
+    return issue(code, context, detail, true, true, "Inspect the saved output and resume the exact checkpoint after correcting the protocol response.");
+}
+export function issue(code, context, detail, humanRequired, recoverable, suggestedAction) {
+    return {
+        code, role: context.role, phase: context.phase, step: context.step, ticket: context.ticket, stack: context.stack,
+        qa_cycle: context.qaCycle, provider: context.provider, model: context.model, detail,
+        human_required: humanRequired, recoverable, suggested_action: suggestedAction,
+        occurred_at: (context.now ?? new Date()).toISOString(),
+    };
+}
+export function formatWorkflowIssue(value) {
+    const scope = [value.role, value.ticket && `ticket=${value.ticket}`, value.stack && `stack=${value.stack}`, value.step && `step=${value.step}`].filter(Boolean).join(" ");
+    return `${value.code}${scope ? ` (${scope})` : ""}: ${value.detail}\nSuggested action: ${value.suggested_action}`;
+}

package/dist/qaReview.d.ts

@@ -0,0 +1,52 @@
+import type { SessionStrategy } from "rafi-spec";
+import type { BuilderAdapter } from "./adapters/types.js";
+import type { TicketDef } from "./tickets/ticketSchema.js";
+export interface QaStreamState {
+    sessionId?: string;
+    reviews: number;
+    modificationViolations: number;
+}
+export interface QaNonconvergenceContext {
+    ticket: TicketDef;
+    history: Array<{
+        cycle: number;
+        outcome: string;
+        detail: string;
+    }>;
+    builderWorktree: string;
+}
+export type QaNonconvergenceDecision = {
+    action: "retry" | "pause" | "waive" | "remediate";
+    remediation?: string;
+};
+export interface IsolatedQaOptions {
+    ticket: TicketDef;
+    builderWorktree: string;
+    builderSummary: string;
+    qaStrategy: SessionStrategy;
+    state: QaStreamState;
+    createQa: (cwd: string, sessionId?: string) => Promise<BuilderAdapter>;
+    fix: (issues: string) => Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+    maxCycles: number;
+    evidence?: (entry: {
+        cycle: number;
+        outcome: string;
+        detail: string;
+        qaDiff?: string[];
+    }) => void;
+    onNonconvergence?: (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
+}
+export interface IsolatedQaResult {
+    outcome: "passed" | "blocked" | "needs-human" | "nonconverged" | "waived";
+    detail?: string;
+    summary?: string;
+}
+export declare function runIsolatedQa(opts: IsolatedQaOptions): Promise<IsolatedQaResult>;
+export declare function compactWithRetry(adapter: BuilderAdapter): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+export declare function buildDurableQaFixHandoff(ticket: TicketDef, issues: string, worktree: string, priorResult: string, diffDigest: string): string;