ai-foreman 1.7.29 → 2.0.1

package/dist/foreman.js

@@ -7,12 +7,13 @@ import { renderBuildWorkContext } from "./buildWorkContext.js";
 import { loadTicketSetupConfigWithDefaults } from "./tickets/setupConfig.js";
 import { deliverBuilderGuidanceFollowup } from "./builderGuidanceFollowup.js";
 import { graphContext, sendGraphTurn } from "./graph/turn.js";
+import { workReportOutput, preflightOutput, qaVerdictOutput } from "rafi-spec";
+import { operationInstruction, operationStatus, operationPayload, nativePolicy, structuredTurnErrorMessage } from "./structuredOperation.js";
 import { qaDigest } from "./qaProtocolV2.js";
 import { BuildControlBoundary } from "./buildInterventions.js";
 import { buildScopeRevision } from "./buildApproval.js";
 import { durableHumanDecision, HumanDecisionRequired, HumanDecisionCancelled, servicePendingHumanDecisions, decisionResponse } from "./humanDecision.js";
 import { select, text, isCancel } from "@clack/prompts";
-import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { countProviderQuestions, handleProviderQuestionTool } from "./providerQuestions.js";
 import { bestEffortDiagnostic } from "./questionTrace.js";
 import { signalAttention } from "./notify.js";
@@ -30,22 +31,6 @@ import { join, relative } from "node:path";
 import { SessionUnavailableError, recoverableBuilderTurnError, sessionUnavailableErrorFromFailure } from "./adapters/sessionFailure.js";
 import { WorkflowDb } from "./workflowDb.js";
 import { assertBuildAssignmentReconciled, beginBuildAssignment, BuildAssignmentRejected, captureBuildSource, finishBuildAssignment, validateBuildAssignment } from "./buildAssignment.js";
-/** Compare Builder product state without Rafi's own tracker bookkeeping. */
-function builderProductDigest(source, hostOwnedPaths) {
-    const ignored = new Set(hostOwnedPaths.map(path => path.replace(/\\/g, "/").replace(/^\.\//, "")));
-    const hostOwned = (path) => {
-        const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
-        return ignored.has(normalized)
-            || [".foreman/", ".rafi/", ".tickets/", ".codex/", ".agents/", "docs-rafi/"]
-                .some(prefix => normalized.startsWith(prefix))
-            || [".gitignore", "AGENTS.md", "rafi-config.yaml", "foreman.yaml"].includes(normalized);
-    };
-    const inventory = source.pathInventory
-        .filter(item => !hostOwned(item.path))
-        .map(item => ({ ...item, path: item.path.replace(/\\/g, "/") }))
-        .sort((a, b) => a.path.localeCompare(b.path));
-    return createHash("sha256").update(JSON.stringify(inventory)).digest("hex");
-}
 /** Phrases that suggest the builder ended its turn by asking the human. */
 const QUESTION_HINTS = [
     "should i",
@@ -56,87 +41,6 @@ const QUESTION_HINTS = [
     "could you clarify",
     "which option",
 ];
-/**
- * Pull the STEP_STATUS marker out of a turn's final text.
- * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
- */
-export function parseStepStatus(text, options = {}) {
-    const markerLines = text.split(/\r?\n/).filter((line) => /^\s*STEP_STATUS:/.test(line));
-    const markerCount = markerLines.length;
-    if (markerCount > 1) {
-        return { kind: "unknown", error: "builder emitted multiple STEP_STATUS markers" };
-    }
-    const lines = text.trimEnd().split(/\r?\n/).filter((line) => line.trim().length > 0);
-    const last = lines[lines.length - 1] ?? "";
-    if (!last.includes("STEP_STATUS:")) {
-        if (markerCount === 1 && options.requireFinalLine !== false) {
-            return { kind: "unknown", error: "STEP_STATUS marker was not the final non-empty line" };
-        }
-        if (markerCount === 0)
-            return { kind: "unknown" };
-    }
-    const marker = options.requireFinalLine === false ? markerLines[0]?.trim() ?? "" : last;
-    const match = marker.match(/^STEP_STATUS:\s*(done|blocked|plan_complete|needs_input|qa_pass|qa_fail)\b\s*(?:\|\s*(.*))?$/i);
-    if (!match) {
-        return { kind: "unknown", error: "malformed STEP_STATUS marker" };
-    }
-    const kind = match[1].toLowerCase();
-    const fields = parseMarkerFields(match[2] ?? "");
-    if (fields instanceof Error) {
-        return { kind: "unknown", error: fields.message };
-    }
-    return {
-        kind,
-        summary: fields.summary,
-        next: fields.next,
-        reason: fields.reason,
-        question: fields.question,
-        issues: fields.issues,
-        ticket: fields.ticket,
-        branchDependency: fields.branch_dependency,
-        choices: fields.choices
-            ? fields.choices.split("|").map((c) => c.trim()).filter(Boolean)
-            : undefined,
-    };
-}
-function parseMarkerFields(input) {
-    const fields = {};
-    let rest = input.trim();
-    while (rest.length > 0) {
-        const key = rest.match(/^(\w+)="/);
-        if (!key)
-            return new Error(`malformed STEP_STATUS field near: ${rest.slice(0, 40)}`);
-        const name = key[1];
-        let i = key[0].length;
-        let value = "";
-        let closed = false;
-        while (i < rest.length) {
-            const ch = rest[i];
-            if (ch === "\\") {
-                const next = rest[i + 1];
-                if (next === undefined)
-                    return new Error(`unterminated escape in STEP_STATUS field: ${name}`);
-                value += next;
-                i += 2;
-                continue;
-            }
-            if (ch === "\"") {
-                closed = true;
-                i++;
-                break;
-            }
-            value += ch;
-            i++;
-        }
-        if (!closed)
-            return new Error(`unterminated STEP_STATUS field: ${name}`);
-        if (fields[name] !== undefined)
-            return new Error(`duplicate STEP_STATUS field: ${name}`);
-        fields[name] = value;
-        rest = rest.slice(i).trim();
-    }
-    return fields;
-}
 /** Heuristic: did a marker-less turn end by asking the human something? */
 export function looksLikeQuestion(text) {
     const tail = text.trim().toLowerCase().slice(-400);
@@ -155,7 +59,7 @@ export function buildPrimer(n, trackerPath, ticketsEnabled = false, preferredTic
             `\n- Foreman records completion and regenerates the tracker after independent QA passes. Do not run ticket-complete commands or mark tracker records done yourself.` +
             `\n- When available and permitted, \`foreman tickets discover --summary "..." --rationale "..."\` can log newly discovered work and \`foreman tickets update <id> --next-action "..."\` can record optional mid-turn notes.` +
             `\n- If a ticket CLI is unavailable, include those notes in your response; it is not an implementation blocker.` +
-            `\n- Always include ticket="<id>" in your STEP_STATUS marker so foreman can update the tracker.`;
+            `\n- The host binds your result to the assigned ticket; report completion only for that exact work.`;
     }
     else if (trackerPath) {
         trackerRule = `\n- After completing each ticket or step, update its status in the ticket progress tracker at \`${trackerPath}\`, following the Standard Update Workflow documented in that file.`;
@@ -166,18 +70,31 @@ export function buildPrimer(n, trackerPath, ticketsEnabled = false, preferredTic
     const preferredTicketRule = preferredTicketId
         ? `\n- Resume and finish ticket ${preferredTicketId} first. Do not substitute a different queued ticket.`
         : "";
+    // With structured tickets the host assigns one whole ticket per step and QA
+    // reviews that ticket after the turn, so "step" must never mean a sub-task.
+    if (ticketsEnabled)
+        return `You are being run by an automated foreman. We will work through up to ${n} assigned tickets, one complete ticket per turn.
+
+Rules:
+- Implement the ENTIRE assigned ticket this turn: every acceptance criterion and required test. Do not split it into sub-steps across turns; independent QA reviews the whole ticket as soon as you report.
+- Return the result using the selected native JSON output contract.
+- If a tool action is denied by foreman policy, do not retry the denied form; report it using the blocked result. The one exception is a required test that you changed by adding a pipe, redirection, substitution, or wrapper: retry the exact required-test command without that extra shell syntax before reporting it blocked.${trackerRule}${preferredTicketRule}
+
+This is ticket 1 of up to ${n} in this batch. Implement the assigned ticket completely now.`;
     return `You are being run by an automated foreman. We will work through your next ${n} tickets or implementation steps, one per turn.
 
 Rules:
 - Do exactly ONE ticket or step this turn, then stop.
-- ${MARKER_SPEC}
-- If a tool action is denied by foreman policy, do not retry the denied form; report it via the blocked marker. The one exception is a required test that you changed by adding a pipe, redirection, substitution, or wrapper: retry the exact required-test command without that extra shell syntax before reporting it blocked.${trackerRule}${preferredTicketRule}
+- Return the result using the selected native JSON output contract.
+- If a tool action is denied by foreman policy, do not retry the denied form; report it using the blocked result. The one exception is a required test that you changed by adding a pipe, redirection, substitution, or wrapper: retry the exact required-test command without that extra shell syntax before reporting it blocked.${trackerRule}${preferredTicketRule}
 
 This is step 1 of ${n}. Implement the next ticket or step now.`;
 }
 /** Instruction sent on turns 2–N. */
-export function buildNextStepInstruction(i, n) {
-    return `Implement the next ticket or step now (exactly one) — this is step ${i} of ${n}. Then end with the STEP_STATUS marker line.`;
+export function buildNextStepInstruction(i, n, ticketsEnabled = false) {
+    if (ticketsEnabled)
+        return `Implement the assigned ticket completely now — every acceptance criterion and required test, not a sub-step. This is ticket ${i} of up to ${n} in this batch; independent QA reviews the whole ticket when you report. Return the completed work-report through the selected native JSON contract.`;
+    return `Implement the next ticket or step now (exactly one) — this is step ${i} of ${n}. Return the completed work-report through the selected native JSON contract.`;
 }
 /** QA review turn: ask the builder to triple-check the ticket or step it just completed. */
 export function buildQaInstruction() {
@@ -194,10 +111,7 @@ The independent QA workspace is a disposable snapshot and may have a detached HE
 
 If an otherwise required test is denied only because you added a pipe, redirection, substitution, or wrapper, retry the exact required-test command without that extra shell syntax. Do not retry other denied actions.
 
-If everything is solid, end with STEP_STATUS: qa_pass.
-If anything is off, return the required RAFI_QA_FAILURE_REPORT_START/RAFI_QA_FAILURE_REPORT_END JSON envelope immediately before STEP_STATUS: qa_fail. The report must contain every check, every blocking finding, and all nonblocking observations. Do NOT fix issues on this turn — just report them. Foreman will instruct the Builder to fix them next.
-
-${QA_MARKER_SPEC}`;
+Return a native qa-verdict result. Use a passed payload only when verification succeeds. A failed payload must contain the full report: every check, blocking finding, and nonblocking observation. Do not fix issues during this review; the Builder receives failures separately.`;
 }
 /** Follow-up turn after qa_fail: have the builder implement the listed fixes. */
 export function buildQaFixInstruction(issues) {
@@ -205,17 +119,19 @@ export function buildQaFixInstruction(issues) {
 
 ${issues}
 
-Fix every one of them now. Then end with STEP_STATUS: done so foreman can re-run QA on the fixes. Triple-check that your fixes actually resolve the issues before emitting done.`;
+Fix every one of them now. Submit the selected native remediation result so Foreman can rerun independent QA. Verify that your fixes resolve the reported issues.`;
 }
 /** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
-export function buildPlanningTurn(n, ticketsContent, preferredTicketId) {
+export function buildPlanningTurn(n, ticketsContent, preferredTicketId, ticketsEnabled = false) {
     const header = ticketsContent
         ? `Here is the project's ticket list:\n\n${ticketsContent}\n\n`
         : "";
     const preferred = preferredTicketId
         ? ` The first item must be ticket ${preferredTicketId}; this is an interrupted ticket being resumed.`
         : "";
-    return `${header}Before we begin, list the next ${n} ticket(s) or step(s) you plan to implement, in order.${preferred} Be specific — reference ticket IDs or titles where applicable. Do not implement anything yet; output the numbered list only. Do not emit a STEP_STATUS marker on this turn.`;
+    if (ticketsEnabled)
+        return `${header}Before we begin, list up to ${n} ticket(s) you plan to implement, in dependency order, one entry per complete ticket.${preferred} Never split one ticket into several entries; each entry is implemented and independently reviewed as a whole ticket. A ticket whose dependencies are earlier entries in your list may be included. List fewer than ${n} if fewer can be built. Do not implement anything yet; return the ordered tickets through the build-preflight response.`;
+    return `${header}Before we begin, list the next ${n} ticket(s) or step(s) you plan to implement, in order.${preferred} Be specific — reference ticket IDs or titles where applicable. Do not implement anything yet; return the ordered steps through the build-preflight response.`;
 }
 /** Builds the permission callback: classify, log, allow or escalate. */
 export function createPermissionHandler(policy, log, opts = {}) {
@@ -276,11 +192,11 @@ export function createPermissionHandler(policy, log, opts = {}) {
             behavior: "deny",
             message: `Foreman policy: this action needs human approval (${verdict.reason}) ` +
                 `and was NOT performed. Do not retry this exact action. An allow-listed alternative is permitted; for project tests use a literal in-worktree cd, project-local PYTHONPATH, existing virtualenv Python, or uv run --offline --no-sync with an allowed test command. If no permitted alternative can complete the step, ` +
-                `end your turn with: STEP_STATUS: blocked | reason="needs human approval: ${verdict.reason}".`,
+                `return a native blocked result explaining the required approval: ${verdict.reason}.`,
         };
     };
 }
-/** Drives one builder through a batch of N steps via the STEP_STATUS protocol. */
+/** Drives one builder through contracted native operations. */
 export class BuildInterruptedError extends Error {
     constructor() { super("Build interrupted; current work is preserved for recovery"); this.name = "BuildInterruptedError"; }
 }
@@ -392,7 +308,7 @@ export class Foreman {
      * The returned result and status always reflect the final (non-needs_input) turn.
      */
     async doTurn(instruction) {
-        return this.doTurnWith(this.builder, instruction);
+        return this.runBuilderWork(instruction);
     }
     async prepareBuilderBoundary(frozenAction) {
         if (!this.builderFactory || !this.projectDir)
@@ -440,19 +356,24 @@ export class Foreman {
         this.builder = await this.builderFactory(this.projectDir);
         this.log.write("branch-session", { role: "builder", transition: "missing-session-fresh", continuityLost: true });
     }
-    async doTurnWith(adapter, instruction, mode = "builder", completion) {
+    async doTurnWith(adapter, instruction, mode = "builder", output, completion) {
         return this.projectDir
-            ? withGraphSessionAccess(this.projectDir, adapter, () => this.doTurnWithOwned(adapter, instruction, mode, completion))
-            : this.doTurnWithOwned(adapter, instruction, mode, completion);
+            ? withGraphSessionAccess(this.projectDir, adapter, () => this.doTurnWithOwned(adapter, instruction, mode, output, completion))
+            : this.doTurnWithOwned(adapter, instruction, mode, output, completion);
     }
-    async doTurnWithOwned(adapter, instruction, mode = "builder", completion) {
+    async doTurnWithOwned(adapter, instruction, mode = "builder", output, completion) {
+        if (completion)
+            throw new Error("Text completion predicates cannot authorize native operation results");
         const ticket = mode === "builder" ? this.currentTicketId : undefined;
+        const statusOf = (turn) => operationStatus(turn, output, ticket);
         const hostToolObservations = [];
         const scopedInstruction = (text) => !ticket || text.includes(`Ticket scope: ${ticket}.`) ? text
-            : `${text}\nTicket scope: ${ticket}. Do not substitute another ticket. Include ticket="${ticket}" in any STEP_STATUS marker.`;
+            : `${text}\nTicket scope: ${ticket}. Do not substitute another ticket.`;
         instruction = scopedInstruction(instruction);
+        instruction += `\n\n${operationInstruction(output)}`;
         const send = async (text, policy) => {
             this.assertNotInterrupted();
+            policy = nativePolicy(output, { ...policy, dispatchId: undefined, journalRunId: this.qaRunId });
             const context = ticket && this.projectDir ? renderBuildWorkContext(this.ticketForQa(0, ticket), loadTicketSetupConfigWithDefaults(this.projectDir).build.validation_checklist) : "";
             const contractContext = ticket && this.projectDir ? await ensureBuilderContract(this.projectDir, this.qaRunId, ticket, this.builderWorktree ?? this.projectDir, adapter, this.qaFactory ? (...args) => this.createOwnedQa(...args) : undefined) : "";
             this.assertNotInterrupted();
@@ -472,8 +393,8 @@ export class Foreman {
             finally {
                 stopHostObservation();
             }
-            const parsed = parseStepStatus(response.text);
-            const applicable = parsed.kind === "unknown" && looksLikeQuestion(response.text) ? { kind: "needs_input", question: lastLine(response.text) } : parsed;
+            const parsed = statusOf(response);
+            const applicable = parsed;
             if (!this.interruptionRequested && assignment && !response.isError && !response.failure && ["done", "plan_complete"].includes(applicable.kind))
                 await collectBuilderContractCoverage(this.projectDir, assignment.runId, assignment.ticketId, assignment.worktree, adapter, assignment.operationId, submitted, response, hostToolObservations, initialSourceDigest);
             const rejection = assignment ? finishBuildAssignment(this.projectDir, assignment, response, applicable) : undefined;
@@ -496,60 +417,16 @@ export class Foreman {
             this.builder = await this.beforeBuilderTurn(this.builder, instruction);
             adapter = this.builder;
         }
-        const turnPolicy = { logicalActionId: this.currentTicketId ?? createHash("sha256").update(instruction).digest("hex") };
+        const turnPolicy = { logicalActionId: randomUUID() };
         let result = await send(instruction, turnPolicy);
         await this.observeBuilderNative(adapter);
-        let status = parseStepStatus(result.text);
-        if (!result.isError && !result.failure) {
-            const completed = completion?.(result.text);
-            if (completed)
-                return { result, status: completed };
-        }
+        let status = statusOf(result);
         if (ticket && validateBuildAssignment(ticket, status))
             return { result, status };
         if (result.isError || result.failure)
             return { result: { ...result, isError: true }, status };
-        if (status.kind === "unknown") {
-            if (!status.error && looksLikeQuestion(result.text)) {
-                status = { kind: "needs_input", question: lastLine(result.text), choices: ["Continue", "Cancel"] };
-            }
-            else {
-                if (adapter === this.builder && this.beforeBuilderTurn) {
-                    this.builder = await this.beforeBuilderTurn(this.builder, instruction);
-                    adapter = this.builder;
-                }
-                if (this.projectDir) {
-                    const budget = new WorkflowDb(this.projectDir);
-                    try {
-                        if (!budget.reserveRecoveryAllowance(this.qaRunId, turnPolicy.logicalActionId, "protocol-correction", budget.autonomyPolicy(this.qaRunId)?.limits.protocolCorrections ?? 1))
-                            return { result, status: { kind: "blocked", reason: "shared protocol correction budget exhausted" } };
-                    }
-                    finally {
-                        budget.close();
-                    }
-                }
-                const correction = mode === "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.";
-                result = await send([
-                    correction,
-                    `The previous marker was rejected: ${JSON.stringify(status.error ?? "missing final marker")}.`,
-                    "STEP_STATUS is a separate plain-text line, not JSON. Do not append braces, commas, a code fence, or commentary after it. Keep the continuity JSON on its own preceding line.",
-                    ...(mode === "builder" ? [
-                        `Only if the assigned work is complete, the exact marker form is: STEP_STATUS: done${ticket ? ` | ticket="${ticket}"` : ""}`,
-                        `If blocked, use: STEP_STATUS: blocked | ${ticket ? `ticket="${ticket}" ` : ""}reason="the actual blocker"`,
-                        "Choose the status supported by the work already performed; do not invent completion.",
-                    ] : ["If successful, use exactly: STEP_STATUS: qa_pass", "If failed, retain the required failure report and use exactly: STEP_STATUS: qa_fail"]),
-                ].join("\n"), { ...turnPolicy, responseOnly: true });
-                await this.observeBuilderNative(adapter);
-                if (result.isError || result.failure)
-                    return { result: { ...result, isError: true }, status: { kind: "blocked", reason: result.text } };
-                status = parseStepStatus(result.text);
-                if (status.kind === "unknown")
-                    status = { ...status, error: `protocol correction exhausted: ${status.error ?? "missing final marker"}` };
-            }
-        }
-        let blockerExplanations = 0;
+        if (status.kind === "unknown")
+            return { result: { ...result, isError: true }, status };
         while (true) {
             if (ticket && validateBuildAssignment(ticket, status))
                 return { result, status };
@@ -632,69 +509,23 @@ export class Foreman {
                 await this.observeBuilderNative(adapter);
                 if (result.isError || result.failure)
                     return { result: { ...result, isError: true }, status: { kind: "blocked", reason: result.text } };
-                status = parseStepStatus(result.text);
-                if (completion) {
-                    const completed = completion(result.text);
-                    if (completed)
-                        return { result, status: completed };
-                }
+                status = statusOf(result);
                 if (ticket && validateBuildAssignment(ticket, status))
                     return { result, status };
             }
-            if (status.kind !== "blocked" || (status.reason?.startsWith("user chose safe pause") || status.reason?.includes("Rafi is waiting for input")) || !process.stdin.isTTY || !process.stdout.isTTY)
-                break;
-            if (blockerExplanations++ >= 1)
-                break;
-            if (this.projectDir) {
-                const budget = new WorkflowDb(this.projectDir);
-                try {
-                    if (!budget.reserveRecoveryAllowance(this.qaRunId, this.currentTicketId ?? "instruction", "blocker-explanation", 1))
-                        break;
-                }
-                finally {
-                    budget.close();
-                }
-            }
-            const reason = status.reason ?? "the agent reported an unspecified blocker";
-            this.log.write("blocked-recovery", { reason, role: adapter === this.builder ? "builder" : "qa" });
-            const recoveryInstruction = buildBlockerRecoveryInstruction(reason);
-            if (adapter === this.builder && this.beforeBuilderTurn) {
-                this.builder = await this.beforeBuilderTurn(this.builder, scopedInstruction(recoveryInstruction));
-                adapter = this.builder;
-            }
-            result = await send(recoveryInstruction, turnPolicy);
-            await this.observeBuilderNative(adapter);
-            if (result.isError || result.failure)
-                return { result: { ...result, isError: true }, status: { kind: "blocked", reason: result.text } };
-            status = parseStepStatus(result.text);
-            if (status.kind === "unknown") {
-                if (this.projectDir && this.qaRunId) {
-                    const budget = new WorkflowDb(this.projectDir);
-                    try {
-                        if (!budget.reserveRecoveryAllowance(this.qaRunId, turnPolicy.logicalActionId, "protocol-correction", budget.autonomyPolicy(this.qaRunId)?.limits.protocolCorrections ?? 1))
-                            break;
-                    }
-                    finally {
-                        budget.close();
-                    }
-                }
-                result = await send('Protocol correction only: return the blocker approaches now using exactly one final STEP_STATUS: needs_input marker with question="..." and choices="recommended (Recommended)|alternative|alternative". Do not repeat tools or implementation.', { ...turnPolicy, responseOnly: true });
-                await this.observeBuilderNative(adapter);
-                if (result.isError || result.failure)
-                    return { result: { ...result, isError: true }, status: { kind: "blocked", reason: result.text } };
-                status = parseStepStatus(result.text);
-            }
+            break;
         }
         return { result, status };
     }
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
     async runPreflight(n, ticketsContent, preferredTicketId, executionTickets) {
         this.assertNotInterrupted();
-        const instruction = buildPlanningTurn(n, ticketsContent, preferredTicketId) + (executionTickets ? `\nAuthorized ticket scope: ${executionTickets.join(", ")}. Plan only these tickets. Tickets awaiting answers are not eligible for implementation.` : "");
+        const instruction = buildPlanningTurn(n, ticketsContent, preferredTicketId, this.ticketsEnabled) + (executionTickets ? `\nAuthorized ticket scope: ${executionTickets.join(", ")}. Plan only these tickets. Tickets awaiting answers are not eligible for implementation.` : "");
         if (this.beforeBuilderTurn)
             this.builder = await this.beforeBuilderTurn(this.builder, instruction);
         this.assertNotInterrupted();
-        const result = this.projectDir ? await sendGraphTurn(this.builder, instruction, graphContext(this.projectDir, this.builderWorktree ?? this.projectDir, "build-preflight", instruction), { purpose: "planning" }) : await this.builder.sendTurn(instruction, { purpose: "planning" });
+        const policy = nativePolicy(preflightOutput, { purpose: "planning", journalRunId: this.qaRunId });
+        const result = this.projectDir ? await sendGraphTurn(this.builder, `${instruction}\n\n${operationInstruction(preflightOutput)}`, graphContext(this.projectDir, this.builderWorktree ?? this.projectDir, "build-preflight", instruction), policy) : await this.builder.sendTurn(instruction, policy);
         this.assertNotInterrupted();
         await this.observeBuilderNative(this.builder);
         this.log.write("preflight", {
@@ -703,9 +534,9 @@ export class Foreman {
             isError: result.isError,
         });
         if (result.isError)
-            throw new Error(result.text);
-        this.preflightPlan = result.text;
-        return result.text;
+            throw new Error(structuredTurnErrorMessage(result, "Build preflight"));
+        this.preflightPlan = operationPayload(result, preflightOutput).steps.map((step, index) => `${index + 1}. ${step.ticket ? step.ticket + ": " : ""}${step.work}`).join("\n");
+        return this.preflightPlan;
     }
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
     async sendPreflightFeedback(feedback) {
@@ -713,21 +544,26 @@ export class Foreman {
         if (this.beforeBuilderTurn)
             this.builder = await this.beforeBuilderTurn(this.builder, feedback);
         this.assertNotInterrupted();
-        const result = this.projectDir ? await sendGraphTurn(this.builder, feedback, graphContext(this.projectDir, this.builderWorktree ?? this.projectDir, "build-preflight", feedback), { purpose: "planning" }) : await this.builder.sendTurn(feedback, { purpose: "planning" });
+        const policy = nativePolicy(preflightOutput, { purpose: "planning", journalRunId: this.qaRunId });
+        const result = this.projectDir ? await sendGraphTurn(this.builder, feedback, graphContext(this.projectDir, this.builderWorktree ?? this.projectDir, "build-preflight", feedback), policy) : await this.builder.sendTurn(feedback, policy);
         this.assertNotInterrupted();
         await this.observeBuilderNative(this.builder);
         this.log.write("preflight", { feedback: true, costUsd: result.costUsd, isError: result.isError });
         if (result.isError)
-            throw new Error(result.text);
-        this.preflightPlan = result.text;
+            throw new Error(structuredTurnErrorMessage(result, "Build preflight"));
+        this.preflightPlan = operationPayload(result, preflightOutput).steps.map((step, index) => `${index + 1}. ${step.ticket ? step.ticket + ": " : ""}${step.work}`).join("\n");
     }
     /** Send one custom instruction through the same needs_input loop as a batch turn. */
-    async runInstruction(instruction, options = {}) {
-        return this.doTurnWith(this.builder, instruction, "builder", options.completion);
+    async runInstruction(instruction, options) {
+        return this.doTurnWith(this.builder, instruction, "builder", options.output, options.completion);
+    }
+    /** The sole convenience path that selects the Builder's work-report contract. */
+    async runBuilderWork(instruction) {
+        return this.doTurnWith(this.builder, instruction, "builder", workReportOutput);
     }
     /** Ask an already-active role session to propose choices for its reported blocker. */
-    async resolveBlocker(adapter, reason, mode = "builder") {
-        return this.doTurnWith(adapter, buildBlockerRecoveryInstruction(reason), mode);
+    async resolveBlocker(adapter, reason, mode, output) {
+        return this.doTurnWith(adapter, buildBlockerRecoveryInstruction(reason), mode, output);
     }
     async observeBuilderNative(adapter) {
         if (adapter === this.builder)
@@ -807,7 +643,7 @@ export class Foreman {
                 },
                 evidence: ({ cycle, outcome, detail, qaDiff }) => this.log.write("qa", { stepIndex, cycle, outcome, detail, qaDiff, disposable: true }),
                 onNonconvergence: this.qaNonconvergence,
-                resolveBlocked: (adapter, reason) => this.resolveBlocker(adapter, reason, "qa"),
+                resolveBlocked: (adapter, reason) => this.resolveBlocker(adapter, reason, "qa", qaVerdictOutput),
             });
             if (resumedRecovery) {
                 const recoveryDb = new WorkflowDb(this.projectDir);
@@ -1116,9 +952,9 @@ export class Foreman {
             // have no preflight still receive the primer for compatibility.
             let instruction = i === 1 && !this.preflightPlan
                 ? buildPrimer(n, trackerPath, this.ticketsEnabled, pendingTicketId)
-                : buildNextStepInstruction(i, n);
+                : buildNextStepInstruction(i, n, this.ticketsEnabled);
             if (pendingTicketId)
-                instruction += `\n\nAssigned ticket: ${pendingTicketId}. Implement exactly this ticket. Do not substitute another ticket. End with ticket="${pendingTicketId}" in the STEP_STATUS marker.`;
+                instruction += `\n\nAssigned ticket: ${pendingTicketId}. Implement exactly this ticket. Do not substitute another ticket. Return the native work report for this assigned ticket.`;
             const continuations = answered.filter(decision => decision.interruptionId === `ticket:${pendingTicketId}`);
             const continuationKeys = [];
             if (continuations.length) {
@@ -1140,14 +976,6 @@ export class Foreman {
             }
             if (i > 1)
                 await this.prepareBuilderBoundary(instruction);
-            // Current-branch builds do not always populate builderWorktree.  The
-            // project directory is still the authoritative source boundary, so a
-            // plan-only resumed turn must be compared there before QA can run.
-            const builderSourceRoot = this.builderWorktree ?? this.projectDir;
-            const hostOwnedSourcePaths = this.projectDir && this.ticketsEnabled
-                ? generatedTrackerDirtyPaths(loadTicketsConfig(this.projectDir).paths)
-                : [];
-            const sourceBeforeTurn = builderSourceRoot ? captureBuildSource(builderSourceRoot) : undefined;
             this.builderWorkSessions += 1;
             const turn = () => this.doTurn(instruction);
             let response;
@@ -1190,41 +1018,6 @@ export class Foreman {
                 detail = `builder turn errored: ${result.text.slice(0, 200)}`;
                 break;
             }
-            // A resumed provider can answer the mandatory primer with a planning
-            // response while still emitting a done marker. Do not send unchanged
-            // source to QA or mark the ticket complete. Retry the bounded
-            // implementation once; if it still produces no work, stop as a real
-            // Builder blocker.
-            if (["done", "plan_complete"].includes(status.kind) && pendingTicketId && sourceBeforeTurn && builderSourceRoot) {
-                const sourceAfterTurn = captureBuildSource(builderSourceRoot);
-                const beforeProductDigest = builderProductDigest(sourceBeforeTurn, hostOwnedSourcePaths);
-                const afterProductDigest = builderProductDigest(sourceAfterTurn, hostOwnedSourcePaths);
-                // plan_complete is explicitly a planning response. Even if the
-                // provider touched bookkeeping while planning, never send that state
-                // to QA as if implementation were complete.
-                const responseIsPlanningOnly = /\bplan(?:ning)?\s+only\b|\bdo not implement(?: yet)?\b|\bawait(?:ing)? (?:approval|go-ahead)\b/i.test(result.text)
-                    && !/\bimplemented\b|\badded\b|\bchanged\b/i.test(result.text);
-                if (status.kind === "plan_complete" || responseIsPlanningOnly || afterProductDigest === beforeProductDigest) {
-                    this.log.write("step", { index: i, statusKind: "plan_only_without_source_change", ticket: pendingTicketId });
-                    const retry = await this.doTurn(`The previous turn did not complete implementation. Implement the assigned ticket now: ${pendingTicketId}. Inspect the current files, make the required changes and tests, then report truthful evidence with STEP_STATUS: done | ticket="${pendingTicketId}" summary="...". Do not return another plan-only response.`);
-                    result = retry.result;
-                    status = retry.status;
-                    if (result.isError) {
-                        const recoverable = recoverableBuilderTurnError(result);
-                        if (recoverable)
-                            throw recoverable;
-                        outcome = "blocked";
-                        detail = `builder implementation retry errored: ${result.text.slice(0, 200)}`;
-                        break;
-                    }
-                    const sourceAfterRetry = captureBuildSource(builderSourceRoot);
-                    if (status.kind === "plan_complete" || (status.kind === "done" && builderProductDigest(sourceAfterRetry, hostOwnedSourcePaths) === beforeProductDigest)) {
-                        outcome = "needs-human";
-                        detail = `Builder returned planning-only responses without changing product source for ${pendingTicketId}`;
-                        break;
-                    }
-                }
-            }
             if (status.kind === "done" || status.kind === "plan_complete") {
                 let qaSummary;
                 let qaWaived = false;
@@ -1368,7 +1161,7 @@ export class Foreman {
                 ? status.error
                 : looksLikeQuestion(result.text)
                     ? `builder ended with a question: ${lastLine(result.text)}`
-                    : "builder did not emit a STEP_STATUS marker";
+                    : "builder did not submit a valid native operation result";
             break;
         }
         if (completed >= n && this.projectDir) {
@@ -1402,8 +1195,7 @@ function buildBlockerRecoveryInstruction(reason) {
         `You reported this blocker: ${reason}`,
         "Do not end the run. Analyze the durable state and propose two or three safe, materially different approaches the user can choose from.",
         "Put your recommended approach first and end its label with (Recommended). Include the important consequence or tradeoff in every choice label.",
-        "Do not perform more implementation or QA work until the user chooses. End exactly with:",
-        'STEP_STATUS: needs_input | question="How should Rafi unblock this work?" choices="recommended approach and consequence (Recommended)|alternative and consequence|another alternative and consequence"',
+        "Do not perform more implementation or QA work until the user chooses. Return a native needs-input result with the question and concrete choices.",
         "After the user answers, apply that guidance in this same session. If still blocked, report blocked again so Rafi can offer a new set of approaches.",
     ].join("\n\n");
 }

package/dist/gitExclude.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Add missing ignore entries for Rafi's local state to a repository.
+ *
+ * Prefers the repository-local `.git/info/exclude`. A git template
+ * (`init.templateDir`) can install that file as a symlink to one shared
+ * file, so appending through it would add this project's entries to every
+ * repository using the template. Such a link is first replaced by a regular
+ * file with the same rules, keeping the change local to this repository.
+ *
+ * Without a local exclude file, entries go to `.gitignore` when
+ * `fallbackToGitignore` is set; otherwise nothing is written.
+ */
+export declare function ensureLocalGitExcludes(projectDir: string, entries: readonly string[], options?: {
+    fallbackToGitignore?: boolean;
+    leadingBlankLine?: boolean;
+}): void;

package/dist/gitExclude.js

@@ -0,0 +1,46 @@
+import { appendFileSync, existsSync, lstatSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Add missing ignore entries for Rafi's local state to a repository.
+ *
+ * Prefers the repository-local `.git/info/exclude`. A git template
+ * (`init.templateDir`) can install that file as a symlink to one shared
+ * file, so appending through it would add this project's entries to every
+ * repository using the template. Such a link is first replaced by a regular
+ * file with the same rules, keeping the change local to this repository.
+ *
+ * Without a local exclude file, entries go to `.gitignore` when
+ * `fallbackToGitignore` is set; otherwise nothing is written.
+ */
+export function ensureLocalGitExcludes(projectDir, entries, options = {}) {
+    const localExclude = join(projectDir, ".git", "info", "exclude");
+    let path;
+    let isLink = false;
+    try {
+        isLink = lstatSync(localExclude).isSymbolicLink();
+        path = localExclude;
+    }
+    catch { /* no local exclude file */ }
+    if (!path) {
+        if (!options.fallbackToGitignore)
+            return;
+        path = join(projectDir, ".gitignore");
+    }
+    let existing = "";
+    try {
+        existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    }
+    catch {
+        existing = "";
+    }
+    const lines = existing.split(/\r?\n/);
+    const missing = entries.filter((entry) => !lines.includes(entry));
+    if (!missing.length)
+        return;
+    if (isLink) {
+        unlinkSync(path);
+        writeFileSync(path, existing, "utf8");
+    }
+    const separator = options.leadingBlankLine ? "\n" : existing && !existing.endsWith("\n") ? "\n" : "";
+    appendFileSync(path, `${separator}${missing.join("\n")}\n`, "utf8");
+}

package/dist/graph/boundary.d.ts

@@ -11,5 +11,5 @@ export interface GraphPendingTask {
 }
 /** A completed editing assignment plus host-observed source change is required.
  * Changed bytes alone are deliberately insufficient to establish this trigger. */
-export declare function queueGraphMaintenance(root: string, workspace: string, logicalTaskId: string, response: string, sourceChanged: boolean): void;
+export declare function queueGraphMaintenance(root: string, workspace: string, logicalTaskId: string, response: string | boolean, sourceChanged: boolean): void;
 export declare function maintainGraphTask(root: string, workspace: string, logicalTaskId: string, host: BuilderAdapter): Promise<unknown>;

package/dist/graph/boundary.js

@@ -9,7 +9,7 @@ export const GRAPH_CHANGE_SIGNAL = "RAFI_GRAPH_MAINTENANCE: meaningful-indexed-c
 /** A completed editing assignment plus host-observed source change is required.
  * Changed bytes alone are deliberately insufficient to establish this trigger. */
 export function queueGraphMaintenance(root, workspace, logicalTaskId, response, sourceChanged) {
-    if (!sourceChanged || !response.split(/\r?\n/).some(line => line.trim() === GRAPH_CHANGE_SIGNAL))
+    if (!sourceChanged || !(typeof response === "boolean" ? response : response.split(/\r?\n/).some(line => line.trim() === GRAPH_CHANGE_SIGNAL)))
         return;
     const effective = loadGraphConfig(root);
     if (!effective.enabled || effective.config?.maintenance !== "selective")