ai-foreman 1.7.26 → 1.7.28

package/dist/planChanges.js

@@ -1,4 +1,4 @@
-const MATERIAL_KEYS = new Set(["scope", "summary", "acceptance", "acceptance_criteria", "depends_on", "dependencies", "delivery", "delivery_strategy", "branch", "branch_mode", "completion", "completion_mode"]);
+const MATERIAL_KEYS = new Set(["scope", "summary", "acceptance", "acceptance_criteria", "documentation", "depends_on", "dependencies", "delivery", "delivery_strategy", "branch", "branch_mode", "completion", "completion_mode"]);
 const BOOKKEEPING_KEYS = new Set(["status", "evidence", "updated_at", "updatedAt", "timestamp", "notes"]);
 /** Structural classification; agent prose is intentionally ignored. */
 export function classifyPlanChange(before, after) {

package/dist/projectDiagnostics.js

@@ -5,6 +5,8 @@ import { execFileSync } from "node:child_process";
 import { readInterviewRecords } from "./interviews.js";
 import { cmdQueue, cmdValidate } from "./tickets/commands.js";
 import { getAllTicketDetails } from "./tickets/details.js";
+import { loadRafiConfigObject } from "./tickets/setupConfig.js";
+import { resolveQaPreparationConfig } from "./qaPreparationPolicy.js";
 function collectProjectState(root) {
     const state = { configPresent: existsSync(join(root, "rafi-config.yaml")), dirtyPaths: [], planningSessions: [], errors: [] };
     const sessions = readInterviewRecords(root);
@@ -22,6 +24,21 @@ function collectProjectState(root) {
             state.errors.push(String(error));
         }
     }
+    if (state.configPresent) {
+        try {
+            const config = loadRafiConfigObject(root);
+            const legacy = Boolean(config && config.qa_preparation && typeof config.qa_preparation === "object" && !Array.isArray(config.qa_preparation));
+            const policy = resolveQaPreparationConfig(config?.qa_preparation, config?.qa_preparation_shadow === true, config?.qa_preparation_wall_time_ms);
+            state.qaPreparation = {
+                mode: policy.mode,
+                configuration: legacy ? "legacy" : "current",
+                detail: legacy ? "Legacy QA preparation configuration will be rewritten to public booleans by `rafi compile <project>`." : policy.mode === "legacy" ? "QA preparation is disabled; enable qa_preparation: true to require QA requirements before Builder work." : policy.mode === "shadow" ? "QA preparation is collecting non-blocking rollout evidence." : "QA preparation is enabled and requires a ticket contract before Builder work.",
+            };
+        }
+        catch (error) {
+            state.qaPreparation = { mode: "legacy", configuration: "invalid", detail: `QA preparation configuration is invalid: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
     return state;
 }
 import { BUILD_LEASE_STALE_MS, readBuildRuns } from "./buildRuns.js";
@@ -67,6 +84,19 @@ export function collectManagerProjectDiagnostics(projectDir, options = {}) {
         const currentFocus = options.currentFocusRunId ?? initialFocus;
         if (currentFocus && !ids.has(currentFocus))
             throw new Error(`build run not found: ${currentFocus}`);
+        if (projectState.qaPreparation && currentFocus) {
+            const preparation = workflow.qaPreparation(currentFocus);
+            const states = preparation.works.reduce((counts, work) => {
+                if (work.state === "ready")
+                    counts.ready++;
+                else if (["blocked", "incomplete", "uncertain"].includes(work.state))
+                    counts.blocked++;
+                else
+                    counts.pending++;
+                return counts;
+            }, { ready: 0, pending: 0, blocked: 0 });
+            projectState.qaPreparation = { ...projectState.qaPreparation, mode: preparation.mode, runId: currentFocus, contracts: states };
+        }
         const summaries = [...ids].map(runId => mergeSummary({ runId, build: buildById.get(runId), stored: storedById.get(runId), rollup: rollupById.get(runId), workflow: workflowById.get(runId), activeRunId, leaseRunId: lease?.runId, now, schemaVersion: observability.schemaVersion() }))
             .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.createdAt.localeCompare(a.createdAt) || a.runId.localeCompare(b.runId));
         const detailIds = [...new Set([currentFocus, activeRunId, ...(options.referencedRunIds ?? [])].filter((id) => Boolean(id && buildById.has(id))))].slice(0, 5);

package/dist/providerQuestions.js

@@ -2,6 +2,7 @@ import { buildScopeRevision } from "./buildApproval.js";
 import { durableHumanDecision, HumanDecisionRequired } from "./humanDecision.js";
 import { isCancel, multiselect, select, text } from "@clack/prompts";
 import { currentActivity, pauseActivityForInput } from "./activity.js";
+import { providerQuestionV1Schema } from "rafi-spec";
 const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
 const CUSTOM_VALUE = "__rafi_custom_response__";
 export const GRILL_ME_STOP_CHOICE = "Stop questions and make the plan now";
@@ -101,31 +102,10 @@ function parseQuestions(input) {
     if (!Array.isArray(rawQuestions))
         return [];
     return rawQuestions.flatMap((raw) => {
-        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        const result = providerQuestionV1Schema.safeParse(raw);
+        if (!result.success)
             return [];
-        const record = raw;
-        const question = typeof record.question === "string" ? record.question.trim() : "";
-        if (!question)
-            return [];
-        const header = typeof record.header === "string" && record.header.trim()
-            ? record.header.trim()
-            : undefined;
-        const options = Array.isArray(record.options)
-            ? record.options.flatMap((option) => {
-                if (!option || typeof option !== "object" || Array.isArray(option))
-                    return [];
-                const optionRecord = option;
-                const label = typeof optionRecord.label === "string" ? optionRecord.label.trim() : "";
-                if (!label)
-                    return [];
-                return [{
-                        label,
-                        description: typeof optionRecord.description === "string" ? optionRecord.description : undefined,
-                        preview: typeof optionRecord.preview === "string" ? optionRecord.preview : undefined,
-                    }];
-            })
-            : [];
-        return [{ question, header, options, multiSelect: record.multiSelect === true }];
+        return [result.data];
     });
 }
 async function askOneQuestion(question, prompts, signal) {

package/dist/qaBuildGate.d.ts

@@ -1,4 +1,9 @@
-import type { BuilderAdapter } from "./adapters/types.js";
+import type { BuilderAdapter, TurnResult } from "./adapters/types.js";
 import type { QaSessionHandle } from "./qaReview.js";
+/** A received response missing only continuity metadata is a bounded format defect. */
+export declare function preparationTurnPayload(turn: TurnResult): {
+    text: string;
+    formatErrors: string[];
+};
 /** Shared by ordinary, branch, synthetic, remediation and Manager followups. */
 export declare function ensureBuilderContract(projectDir: string, runId: string, workId: string, workspace: string, builder: BuilderAdapter, qaFactory?: (cwd: string) => Promise<QaSessionHandle>): Promise<string>;

package/dist/qaBuildGate.js

@@ -14,13 +14,23 @@ import { WorkflowDb } from "./workflowDb.js";
 import { createRoleBuilder, readOnlyPermissionConfig } from "./agentRun.js";
 import { captureBuildSource, assertBuildAssignmentReconciled } from "./buildAssignment.js";
 import { createDisposableQaSnapshotAsync } from "./qaSnapshot.js";
-import { allocateStableCheckIds, authoritativeInventory, contractDigest, renderVerificationContract } from "./qaVerificationContract.js";
+import { allocateStableCheckIds, authoritativeInventory, bindUniqueBaselineCheckIds, contractDigest, mapSnapshotWorkingDirectories, normalizeSnapshotPaths, renderVerificationContract, rewriteProviderHostScopeChecks } from "./qaVerificationContract.js";
 import { resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
 import { prepareVerificationContract } from "./qaPreparation.js";
+import { qaHostGraphFact } from "./qaHostFacts.js";
 import { actualContractSession, assertContractReceipt, deliverVerificationContract } from "./qaContractDelivery.js";
-import { COVERAGE_INSTRUCTIONS } from "./qaContractCoverage.js";
+import { BUILDER_WORK_COVERAGE_INSTRUCTIONS } from "./qaContractCoverage.js";
 import { renderBuildWorkContext } from "./buildWorkContext.js";
 import { compareContractInputs } from "./qaContractFreshness.js";
+import { readBuildRuns } from "./buildRuns.js";
+/** A received response missing only continuity metadata is a bounded format defect. */
+export function preparationTurnPayload(turn) {
+    const formatErrors = turn.continuityErrors ?? [];
+    return {
+        text: formatErrors.length ? turn.rawResponse ?? turn.cleanedResponse ?? turn.text : turn.text,
+        formatErrors,
+    };
+}
 /** Shared by ordinary, branch, synthetic, remediation and Manager followups. */
 export async function ensureBuilderContract(projectDir, runId, workId, workspace, builder, qaFactory) {
     return withGraphDerivedAccess([], () => ensureBuilderContractWithProvenance(projectDir, runId, workId, workspace, builder, qaFactory));
@@ -33,8 +43,6 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
         const policy = store.policy(runId) ?? store.freezePolicy(runId, resolveQaPreparationConfig(undefined));
         if (policy.mode === "legacy")
             return "";
-        if (policy.mode === "enforce" && !builder.contractCapabilities?.().nativeCompactionBarrier)
-            throw new Error(`unsupported-capability: ${builder.agent} enforcement requires proven native-compaction delivery continuity`);
         assertBuildAssignmentReconciled(projectDir, runId, workspace);
         const admission = db.assertAdmittedWork(runId, workId);
         const ticket = db.workDefinitions(runId).find(work => work.workId === workId)?.definition;
@@ -66,6 +74,24 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
             inventory.push({ id: `req-rules-${contractDigest("rule-identity", { locator, statement }).slice(0, 24)}`, inputRef: "effective-rules", locator, statement, digest: contractDigest("statement", statement), obligation: "mandatory", origin: "explicit", authority: "approved" });
         }
         const source = captureBuildSource(workspace);
+        const preimplementationPathManifestDigest = contractDigest("preimplementation-path-manifest", source.pathInventory.map(path => ({
+            path: path.path,
+            staged: path.staged,
+            unstaged: path.unstaged,
+            ...(path.headObject ? { headObject: path.headObject } : {}),
+            ...(path.indexObject ? { indexObject: path.indexObject } : {}),
+            ...(path.worktreeObject ? { worktreeObject: path.worktreeObject } : {}),
+            ...(path.untracked ? { untracked: path.untracked } : {}),
+        })));
+        const baselineEvidence = store.putArtifact("baseline-observation", {
+            kind: "host-captured-preimplementation-source",
+            sourceDigest: source.digest,
+            contentDigest: source.contentDigest,
+            head: source.head,
+            captureMode: source.captureMode,
+            capturedAt: source.capturedAt,
+        });
+        inputs.push({ id: "preimplementation-source", kind: "baseline", reference: "builder.preimplementation-source", digest: source.digest, authority: "inspected-context", revision: source.head, availability: "available" });
         const head = store.head(runId, workId, admission.requirementsDigest);
         const priorBudget = store.budget(runId, workId, admission.requirementsDigest);
         if (priorBudget)
@@ -87,14 +113,30 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
                 amendmentPredecessor = old.contentDigest;
             }
         }
+        const hostBaseline = { id: "host-preimplementation-source", sourceDigest: source.digest, phase: "preimplementation-host-capture", runtime: "Rafi host", procedure: "Host-captured source identity and per-file path manifest before Builder edits", observedAt: source.capturedAt, status: "passed", evidenceDigest: baselineEvidence, relevance: `Authoritative comparison basis for unchanged-file and scope checks; exact host-owned path-manifest digest is ${preimplementationPathManifestDigest}`, expectedTransition: "Rafi compares the complete postimplementation path inventory with this host-owned baseline; providers do not need the raw manifest" };
         const initial = { version: 1, contractId: head.digest ? store.contract(head.digest).contractId : `contract:${contractDigest("contract-family", { runId, workId, admission: admission.requirementsDigest })}`, revision: head.digest ? store.contract(head.digest).revision + (amendmentPredecessor ? 1 : 0) : 1,
             ...(amendmentPredecessor ? { predecessorDigest: amendmentPredecessor } : {}),
             runId, workId, admissionDigest: admission.requirementsDigest, depthDecision: ticket.qa_preparation,
-            inputs, baseline: [], requirements: inventory, checks: [], coverage: [], preparationEvidence: [], unresolved: [], createdAt: new Date(priorBudget?.startMs ?? Date.now()).toISOString() };
+            documentation: structuredClone(ticket.documentation ?? { required: false, targets: [], criteria: [] }),
+            inputs, baseline: [hostBaseline], requirements: inventory, checks: [], coverage: [], preparationEvidence: [], unresolved: [], createdAt: new Date(priorBudget?.startMs ?? Date.now()).toISOString() };
+        const buildRun = readBuildRuns(projectDir).find(run => run.runId === runId);
+        const deliveryFact = buildRun?.branchMode === "current"
+            ? "Host-owned delivery-mode fact: this admitted build uses current-branch semantics. Do not require an isolated ticket branch, a multiply-only branch, branch identity, or a branch-alone test merely to prove additive ticket independence. HEAD may predate already completed sibling tickets, so never use git status, git diff HEAD, or a HEAD-based whole-tree comparison as the ticket-scope proof. Evaluate independence with the host-captured preimplementation baseline observation, approved product-path scope, ticket-owned tests, and permitted project tests. An isolated execution remains required only if the original approved requirement explicitly says so."
+            : buildRun?.branchMode === "per-ticket"
+                ? "Host-owned delivery-mode fact: this admitted build uses isolated branch-per-ticket semantics. Verify branch/worktree identity when the contract requires it; do not infer it from the independent QA snapshot."
+                : "Host-owned delivery-mode fact: delivery mode was not available from the authoritative build record; do not invent branch-isolation requirements without an explicit approved requirement.";
         const result = await prepareVerificationContract(initial, inventory, {
-            store, now: Date.now,
+            provider: builder.agent,
+            store, now: Date.now, hostFacts: `${qaHostGraphFact(projectDir)}\n${deliveryFact}\nHost-owned baseline fact: Rafi captured the complete preimplementation per-file path manifest and will perform the exact unchanged-file and scope comparison. Its digest is ${preimplementationPathManifestDigest}. Do not require the provider to receive or reproduce the raw manifest; cite the retained host-preimplementation-source observation and assess the host comparison result instead. Do not author a provider-executed check for Rafi's host postimplementation path manifest, complete changed-path inventory, or unchanged-file comparison; Rafi performs that comparison outside the provider snapshot. Ordinary approved product paths, exports, and tests are not a material QA concern merely because the provider cannot prove whether they were present before implementation; Rafi owns that comparison. Do not reconstruct or disclose the full baseline. For current-branch additive tickets, a provider-authored or inferred request to test the branch with an already-completed sibling feature removed is not an applicable requirement when the approved scope says not to remove or reconstruct that sibling; verify the ticket's own behavior and tests against the shared baseline instead. Treat sibling-absence testing as binding only when the user explicitly approved that absence requirement. Escalate only an actual host-observed out-of-scope, destructive, protected-file, or requirement-relevant change.`,
             normalizeDraft: (draft, response) => {
-                const normalized = allocateStableCheckIds(draft);
+                const normalized = rewriteProviderHostScopeChecks(bindUniqueBaselineCheckIds(allocateStableCheckIds(draft)), hostBaseline.id);
+                if (!normalized.baseline.some(observation => observation.id === hostBaseline.id))
+                    normalized.baseline.unshift(structuredClone(hostBaseline));
+                for (const check of normalized.checks)
+                    for (const method of check.verification) {
+                        if (response.workspacePaths && Object.hasOwn(response.workspacePaths, method.cwd))
+                            method.cwd = response.workspacePaths[method.cwd];
+                    }
                 for (const observation of normalized.baseline) {
                     const original = structuredClone(observation);
                     observation.sourceDigest = source.digest;
@@ -110,10 +152,22 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
                         evidence.graphReceiptRefs = [...response.graphReceiptRefs];
                     evidence.evidenceDigest = store.putArtifact("investigation-evidence", response);
                     for (const reference of evidence.references) {
-                        const path = realpathSync(resolve(workspace, reference.path)), root = realpathSync(workspace);
+                        let path;
+                        try {
+                            path = realpathSync(resolve(workspace, reference.path));
+                        }
+                        catch {
+                            throw new Error(`Inspected source reference ${JSON.stringify(reference.path)} is missing or inaccessible; cite an existing file actually inspected in the frozen workspace`);
+                        }
+                        const root = realpathSync(workspace);
                         if (!path.startsWith(root + sep))
                             throw new Error("Inspected source reference escapes actual workspace");
-                        reference.digest = createHash("sha256").update(readFileSync(path)).digest("hex");
+                        try {
+                            reference.digest = createHash("sha256").update(readFileSync(path)).digest("hex");
+                        }
+                        catch {
+                            throw new Error(`Inspected source reference ${JSON.stringify(reference.path)} is not a readable file`);
+                        }
                     }
                 }
                 return normalized;
@@ -121,8 +175,11 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
             inputsCurrent: candidate => {
                 if (db.assertAdmittedWork(runId, workId).requirementsDigest !== admission.requirementsDigest)
                     return false;
+                const currentSource = captureBuildSource(workspace);
+                if (currentSource.contentDigest !== source.contentDigest)
+                    return false;
                 const current = resolveEffectiveQaConfiguration(projectDir, { make: state?.qa?.settings?.make ?? builder.agent });
-                const compared = compareContractInputs(candidate, inputs.map(input => input.id === "effective-rules" ? { ...input, digest: current.digest } : input.id === "project-checklist" ? { ...input, digest: contractDigest("input-checklist", current.checklist) } : input));
+                const compared = compareContractInputs(candidate, inputs.map(input => input.id === "effective-rules" ? { ...input, digest: current.digest } : input.id === "project-checklist" ? { ...input, digest: contractDigest("input-checklist", current.checklist) } : input.id === "preimplementation-source" ? { ...input, digest: currentSource.digest, revision: currentSource.head } : input));
                 return !compared.changed.length && !compared.unavailable.length;
             },
             dispatch: async (phase, instruction, operationId, remainingMs) => new OperationDeadline("QA preparation operation", remainingMs).run(async () => {
@@ -137,13 +194,14 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
                 if (phase === "planner") {
                     const role = await createRoleBuilder({ projectDir: workspace, configRoot: projectDir, role: "planner", label: "QA depth assessment", sandboxMode: "read-only", permissionConfig: readOnlyPermissionConfig(), yes: true, allowSwitch: false });
                     try {
-                        const turn = await sendPreparationGraphTurn(role.builder, `${instruction}\nFrozen admitted work definition: ${JSON.stringify(ticket)}\nOriginal approved plan context: ${JSON.stringify(planInput?.plan ?? null)}\nFrozen effective configuration: ${JSON.stringify(effective)}`, { phase, projectDir, workspace, sourceRef: before.digest, runId, workId, operationId, remainingMs: remaining() });
+                        const turn = await sendPreparationGraphTurn(role.builder, `This is a read-only QA planning subturn, not Builder work. Do not implement anything, edit files, run project tests, or describe a TDD implementation plan. Your response must begin with RAFI_QA_DEPTH_START and contain only the requested depth JSON, ending with RAFI_QA_DEPTH_END.\n${instruction}\nFrozen admitted work definition: ${JSON.stringify(ticket)}\nOriginal approved plan context: ${JSON.stringify(planInput?.plan ?? null)}\nFrozen effective configuration: ${JSON.stringify(effective)}`, { phase, projectDir, workspace, sourceRef: before.digest, runId, workId, operationId, remainingMs: remaining() });
                         store.event(runId, workId, `${operationId}:raw`, "preparation-provider-return", turn);
                         if (captureBuildSource(workspace).contentDigest !== before.contentDigest)
                             throw new Error("Product source changed during confined planning; reconcile retained dispatch");
-                        if (turn.isError || turn.failure || !role.builder.sessionId())
+                        const payload = preparationTurnPayload(turn);
+                        if ((turn.isError && !payload.formatErrors.length) || turn.failure || !role.builder.sessionId())
                             throw new Error(`planner-unavailable: ${turn.text}`);
-                        return { text: turn.text, graphReceiptRefs: turn.graphReceiptRefs, sessionId: role.builder.sessionId(), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
+                        return { text: payload.text, graphReceiptRefs: turn.graphReceiptRefs, sessionId: role.builder.sessionId(), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
                     }
                     finally {
                         await role.builder.close();
@@ -162,11 +220,13 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
                         adapter = (await createRoleBuilder({ projectDir: snapshot.path, configRoot: projectDir, role: "qa", agent: state?.qa?.settings?.make ?? builder.agent, preloadedSkillContent: effective.skills.map(skill => ({ name: skill.name, content: skill.content })), label: "QA preparation", sandboxMode: "read-only", permissionConfig: readOnlyPermissionConfig(), yes: true, allowSwitch: false })).builder;
                     const turn = await sendPreparationGraphTurn(adapter, `${instruction}\nOriginal approved plan context: ${JSON.stringify(planInput?.plan ?? null)}\nFrozen admitted work definition: ${JSON.stringify(ticket)}\nHost early prerequisite observations (host availability is not provider access; classify readiness versus final-only dependencies): ${JSON.stringify({ ...prerequisites, evidenceDigest: prerequisiteDigest })}\nFrozen effective configuration: ${JSON.stringify(effective)}\nOperation: ${operationId}; remaining wall time: ${remainingMs}ms; source: ${source.digest}`, { phase, projectDir, workspace: snapshot.path, accessWorkspace: workspace, sourceRef: snapshot.frozenState.digest, runId, workId, operationId, remainingMs: remaining() });
                     store.event(runId, workId, `${operationId}:raw`, "preparation-provider-return", turn);
-                    if (turn.isError || turn.failure || !adapter.sessionId())
+                    const payload = preparationTurnPayload(turn);
+                    payload.text = normalizeSnapshotPaths(payload.text);
+                    if ((turn.isError && !payload.formatErrors.length) || turn.failure || !adapter.sessionId())
                         throw new Error(`Preparation provider unavailable: ${turn.text}`);
                     if (captureBuildSource(workspace).contentDigest !== before.contentDigest)
                         throw new Error("Source changed during preparation; retained dispatch requires reconciliation");
-                    return { text: turn.text, graphReceiptRefs: turn.graphReceiptRefs, sessionId: adapter.sessionId(), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
+                    return { text: payload.text, graphReceiptRefs: turn.graphReceiptRefs, sessionId: adapter.sessionId(), workspacePaths: mapSnapshotWorkingDirectories(payload.text, snapshot.path), usage: { inputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.inputTokens : turn.inputTokens, outputTokens: turn.usage?.scope === "turn-delta" ? turn.usage.outputTokens : turn.outputTokens, costUsd: turn.costAuthoritative ? turn.costUsd : undefined } };
                 }
                 finally {
                     try {
@@ -208,7 +268,7 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
         catch {
             await deliverVerificationContract(result.contract, store, builder, workspace, projectDir, renderBuildWorkContext(ticket, effective.checklist));
         }
-        return `${renderVerificationContract(result.contract)}\n${COVERAGE_INSTRUCTIONS}\nCoverage binding: ${JSON.stringify({ phase: "builder", runId, workId, revision: result.contract.revision, contractDigest: result.contract.contentDigest })}`;
+        return `${renderVerificationContract(result.contract)}\n${BUILDER_WORK_COVERAGE_INSTRUCTIONS}`;
     }
     finally {
         db.close();

package/dist/qaBuilderCoverage.d.ts

@@ -1,5 +1,6 @@
 import type { BuilderAdapter, TurnResult } from "./adapters/types.js";
 import { WorkflowDb } from "./workflowDb.js";
+import { type HostBuilderToolObservation } from "./qaBuilderEvidence.js";
 /** Claims are collected after source capture so the provider can name the actual completed source. */
-export declare function collectBuilderContractCoverage(projectDir: string, runId: string, workId: string, workspace: string, adapter: BuilderAdapter, operationId: string, instruction: string, implementation: TurnResult): Promise<void>;
+export declare function collectBuilderContractCoverage(projectDir: string, runId: string, workId: string, workspace: string, adapter: BuilderAdapter, operationId: string, instruction: string, implementation: TurnResult, hostObservations?: HostBuilderToolObservation[], initialSourceDigest?: string): Promise<void>;
 export declare function assertBuilderContractCoverage(db: WorkflowDb, runId: string, workId: string, operationId: string, sourceDigest: string): void;

package/dist/qaBuilderCoverage.js

@@ -2,14 +2,16 @@ import { dispatchWithGraphAccess, withGraphSessionAccess } from "./graph/session
 import { WorkflowDb } from "./workflowDb.js";
 import { actualContractSession, assertContractReceipt } from "./qaContractDelivery.js";
 import { captureBuildSource } from "./buildAssignment.js";
-import { COVERAGE_INSTRUCTIONS, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
+import { COVERAGE_INSTRUCTIONS, bindCoverageHostFields, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
 import { contractDigest } from "./qaVerificationContract.js";
 import { OperationDeadline } from "./util/deadline.js";
+import { hostTestSequenceEvidence } from "./qaBuilderEvidence.js";
+import { qaHostGraphFact } from "./qaHostFacts.js";
 /** Claims are collected after source capture so the provider can name the actual completed source. */
-export async function collectBuilderContractCoverage(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation) {
-    return withGraphSessionAccess(projectDir, adapter, () => collectBuilderContractCoverageOwned(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation));
+export async function collectBuilderContractCoverage(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation, hostObservations = [], initialSourceDigest) {
+    return withGraphSessionAccess(projectDir, adapter, () => collectBuilderContractCoverageOwned(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation, hostObservations, initialSourceDigest));
 }
-async function collectBuilderContractCoverageOwned(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation) {
+async function collectBuilderContractCoverageOwned(projectDir, runId, workId, workspace, adapter, operationId, instruction, implementation, hostObservations, initialSourceDigest) {
     const db = new WorkflowDb(projectDir);
     try {
         const store = db.qaPreparationStore();
@@ -19,7 +21,7 @@ async function collectBuilderContractCoverageOwned(projectDir, runId, workId, wo
         const session = actualContractSession(adapter, workspace, projectDir);
         const contract = assertContractReceipt(store, runId, workId, admission.requirementsDigest, session, adapter);
         const source = captureBuildSource(workspace);
-        const binding = { phase: "builder", sourceDigest: source.digest, inputBasisDigest: contractDigest("builder-input-basis", { operationId, instruction, contractDigest: contract.contentDigest }), attemptId: operationId, sessionId: session.sessionId };
+        let binding = { phase: "builder", sourceDigest: source.digest, inputBasisDigest: contractDigest("builder-input-basis", { operationId, instruction, contractDigest: contract.contentDigest }), attemptId: operationId, sessionId: session.sessionId };
         const eventId = `builder-coverage:${operationId}`;
         const existing = db.operation(eventId);
         if (existing) {
@@ -42,9 +44,19 @@ async function collectBuilderContractCoverageOwned(projectDir, runId, workId, wo
             db.updateOperation(eventId, "uncertain", { result: { responseDigest } });
             if (response.isError || response.failure)
                 throw new Error("Builder coverage provider failed; retained response requires reconciliation");
-            if (JSON.stringify(actualContractSession(adapter, workspace, projectDir)) !== JSON.stringify(session) || captureBuildSource(workspace).digest !== source.digest)
+            const afterSession = actualContractSession(adapter, workspace, projectDir);
+            const sameScopedSession = afterSession.provider === session.provider
+                && afterSession.workspace === session.workspace
+                && afterSession.configRoot === session.configRoot
+                && (afterSession.sessionId === session.sessionId || afterSession.compactionSequence > session.compactionSequence);
+            if (!sameScopedSession || captureBuildSource(workspace).digest !== source.digest)
                 throw new Error("Builder coverage changed session or product source");
-            const coverage = parseContractCoverage(response.text);
+            // A provider may compact while producing this response-only evidence.
+            // Bind the retained coverage to the host-observed post-compaction session
+            // while continuing to reject unscoped session changes and source edits.
+            binding = { ...binding, sessionId: afterSession.sessionId };
+            const coverage = bindCoverageHostFields(parseContractCoverage(response.text), contract, binding);
+            bindHostOwnedBuilderFacts(db, coverage, contract, hostObservations, initialSourceDigest, source.digest, workId, projectDir);
             const errors = validateContractCoverage(contract, coverage, binding, false);
             if (errors.length)
                 throw new Error(`Builder coverage invalid: ${errors.join("; ")}`);
@@ -59,6 +71,45 @@ async function collectBuilderContractCoverageOwned(projectDir, runId, workId, wo
         db.close();
     }
 }
+function checkText(check) {
+    return JSON.stringify(check);
+}
+function bindHostOwnedBuilderFacts(db, coverage, contract, observations, _initialSourceDigest, finalSourceDigest, workId, projectDir) {
+    const graphFact = qaHostGraphFact(projectDir);
+    const graphDisabled = /"enabled":false/.test(graphFact);
+    for (const row of coverage.checks ?? []) {
+        const check = contract.checks.find(candidate => candidate.id === row.checkId);
+        if (!check)
+            continue;
+        const text = checkText(check);
+        if (check.timing === "preimplementation" && row.outcome === "not-run") {
+            const baseline = contract.baseline.find(observation => observation.checkId === check.id && observation.status === "passed");
+            if (baseline) {
+                row.outcome = "passed";
+                row.evidence = [...(row.evidence ?? []), { procedure: "Rafi retained preimplementation baseline observation", cwd: ".", runtime: "rafi host", sourceDigest: baseline.sourceDigest, reference: baseline.evidenceDigest }];
+            }
+        }
+        if (graphDisabled && /graph/i.test(text) && /disabled|not.?adopt|no graph/i.test(text)) {
+            const factDigest = db.putEvidence("qa", graphFact);
+            if (row.outcome === "not-run")
+                row.outcome = "passed";
+            if (!row.evidence?.some(evidence => evidence.reference === `host-graph-fact:${factDigest}`))
+                row.evidence = [...(row.evidence ?? []), { procedure: "Rafi host-owned graph configuration observation", cwd: ".", runtime: "rafi host", sourceDigest: finalSourceDigest, reference: `host-graph-fact:${factDigest}` }];
+        }
+        if (row.outcome !== "passed")
+            continue;
+        const historical = /red|test.?first|ordering|historical/i.test(text);
+        if (!historical)
+            continue;
+        const testPath = check.verification.find(method => method.kind === "command" && method.argv?.includes("--test"))?.argv?.at(-1);
+        const sequence = hostTestSequenceEvidence(observations, finalSourceDigest, testPath);
+        if (!sequence)
+            continue;
+        const evidence = JSON.stringify({ version: 1, kind: "host-builder-test-sequence", workId, checkId: row.checkId, sequence });
+        const evidenceDigest = db.putEvidence("qa", evidence);
+        row.evidence = [...(row.evidence ?? []), { procedure: "Rafi host-observed test sequence", cwd: ".", runtime: "provider tool lifecycle plus host source capture", sourceDigest: finalSourceDigest, reference: `host-test-sequence:${evidenceDigest}` }];
+    }
+}
 export function assertBuilderContractCoverage(db, runId, workId, operationId, sourceDigest) {
     const store = db.qaPreparationStore();
     if (store.policy(runId)?.mode !== "enforce")

package/dist/qaBuilderEvidence.d.ts

@@ -0,0 +1,18 @@
+import type { BuilderAdapter } from "./adapters/types.js";
+export interface HostBuilderToolObservation {
+    kind: "node-test" | "npm-test";
+    startedAt: string;
+    completedAt: string;
+    outcome: string;
+    exitCode?: number;
+    outputDigest?: string;
+    sourceDigest: string;
+    testPath?: string;
+}
+/**
+ * Observe only bounded test-command metadata while the provider is working.
+ * The provider remains subject to its normal shell policy; this is a host-side
+ * observation of what actually completed, not an execution or permission grant.
+ */
+export declare function observeHostBuilderTests(adapter: BuilderAdapter, workspace: string, observations: HostBuilderToolObservation[]): () => void;
+export declare function hostTestSequenceEvidence(observations: HostBuilderToolObservation[], finalSourceDigest: string, testPath?: string): HostBuilderToolObservation[] | undefined;

package/dist/qaBuilderEvidence.js

@@ -0,0 +1,60 @@
+import { captureBuildSource } from "./buildAssignment.js";
+function commandDetails(input) {
+    const command = typeof input?.command === "string"
+        ? input.command
+        : undefined;
+    if (!command)
+        return undefined;
+    const nodeTest = /\bnode\s+--test(?:\s+([^\s;&|>]+))?/.exec(command);
+    if (nodeTest)
+        return { kind: "node-test", ...(nodeTest[1] ? { testPath: nodeTest[1] } : {}) };
+    if (/\bnpm\s+test\b/.test(command))
+        return { kind: "npm-test" };
+    return undefined;
+}
+/**
+ * Observe only bounded test-command metadata while the provider is working.
+ * The provider remains subject to its normal shell policy; this is a host-side
+ * observation of what actually completed, not an execution or permission grant.
+ */
+export function observeHostBuilderTests(adapter, workspace, observations) {
+    const open = new Map();
+    const stop = adapter.observeEvents?.((event) => {
+        if (event.kind !== "tool")
+            return;
+        const details = commandDetails(event.input);
+        if (event.lifecycle === "started" && details && event.callId) {
+            open.set(event.callId, { ...details, startedAt: event.observedAt ?? new Date().toISOString() });
+            return;
+        }
+        if (event.lifecycle !== "completed" || !event.callId || !event.completionKnown)
+            return;
+        const prior = open.get(event.callId);
+        if (!prior)
+            return;
+        open.delete(event.callId);
+        if (observations.length >= 40)
+            return;
+        observations.push({
+            kind: prior.kind,
+            startedAt: prior.startedAt,
+            completedAt: event.observedAt ?? new Date().toISOString(),
+            // Some adapters label every finished tool call "completed" even when
+            // the process exited non-zero. Exit status is the host-owned authority
+            // for the red/green distinction whenever it is available.
+            outcome: event.exitCode !== undefined ? event.exitCode === 0 ? "completed" : "failed" : event.status ?? "completed",
+            ...(event.exitCode === undefined ? {} : { exitCode: event.exitCode }),
+            ...(event.outputDigest && /^[a-f0-9]{64}$/.test(event.outputDigest) ? { outputDigest: event.outputDigest } : {}),
+            sourceDigest: captureBuildSource(workspace).digest,
+            ...(prior.testPath ? { testPath: prior.testPath } : {}),
+        });
+    }) ?? (() => { });
+    return () => { stop(); open.clear(); };
+}
+export function hostTestSequenceEvidence(observations, finalSourceDigest, testPath) {
+    const relevant = observations.filter(observation => (observation.kind === "node-test" || observation.kind === "npm-test") && (!testPath || observation.testPath === testPath));
+    const red = relevant.find(observation => observation.outcome !== "completed" && observation.outcome !== "denied");
+    const redIndex = red ? relevant.indexOf(red) : -1;
+    const green = red ? relevant.slice(redIndex + 1).find(observation => observation.sourceDigest === finalSourceDigest && observation.outcome === "completed" && observation.sourceDigest !== red.sourceDigest) : undefined;
+    return red && green ? [red, green] : undefined;
+}

package/dist/qaContractCoverage.d.ts

@@ -1,6 +1,17 @@
 import type { QaContractCoverageV1, QaVerificationContractV1 } from "rafi-spec";
-export declare const COVERAGE_INSTRUCTIONS = "Return RAFI_QA_COVERAGE_START, one QaContractCoverageV1 JSON object, RAFI_QA_COVERAGE_END before the final status marker. Include every check ID with independently evaluated applicability, predicate evidence, outcome (passed/failed/blocked/not-run), and concrete procedure/cwd/runtime/sourceDigest/reference evidence. Missing, blocked, not-run, unresolved applicability, or failed mandatory coverage cannot authorize normal completion. Builder coverage is a claim; final QA independently verifies it.";
+export declare const COVERAGE_INSTRUCTIONS: string;
+export declare const BUILDER_WORK_COVERAGE_INSTRUCTIONS = "Carry out the applicable contract checks and report your work and evidence honestly in your normal final response. When a check requires historical ordering, retain bounded output for each required step and an explicit ordering record while performing it; a later passing test cannot prove an earlier failing step. Do not emit RAFI_QA_COVERAGE JSON during this implementation turn or stop for coverage binding values. After the implementation turn, Rafi will capture the completed source and request a separate response-only coverage record with the exact host-owned bindings.";
 export declare function parseContractCoverage(text: string): QaContractCoverageV1;
+/** Source identity is host-owned; providers may copy a stale Builder digest. */
+export declare function bindCoverageSourceDigest(coverage: QaContractCoverageV1, sourceDigest: string): QaContractCoverageV1;
+/** All coverage identity fields are host-owned; provider output supplies only claims and evidence text. */
+export declare function bindCoverageHostFields(coverage: QaContractCoverageV1, contract: QaVerificationContractV1, binding: {
+    phase: "builder" | "qa";
+    sourceDigest: string;
+    inputBasisDigest: string;
+    attemptId: string;
+    sessionId: string;
+}): QaContractCoverageV1;
 export declare function validateContractCoverage(contract: QaVerificationContractV1, coverage: QaContractCoverageV1, binding: {
     phase: "builder" | "qa";
     sourceDigest: string;

package/dist/qaContractCoverage.js

@@ -2,8 +2,40 @@ import { Ajv } from "ajv";
 import { qaContractCoverageV1Schema } from "rafi-spec";
 const coverageSchema = new Ajv({ allErrors: true }).compile(qaContractCoverageV1Schema);
 import { parsePreparationArtifact } from "./qaVerificationContract.js";
-export const COVERAGE_INSTRUCTIONS = `Return RAFI_QA_COVERAGE_START, one QaContractCoverageV1 JSON object, RAFI_QA_COVERAGE_END before the final status marker. Include every check ID with independently evaluated applicability, predicate evidence, outcome (passed/failed/blocked/not-run), and concrete procedure/cwd/runtime/sourceDigest/reference evidence. Missing, blocked, not-run, unresolved applicability, or failed mandatory coverage cannot authorize normal completion. Builder coverage is a claim; final QA independently verifies it.`;
+export const COVERAGE_INSTRUCTIONS = `Return RAFI_QA_COVERAGE_START, one QaContractCoverageV1 JSON object, RAFI_QA_COVERAGE_END before the final status marker. The exact schema is ${JSON.stringify(qaContractCoverageV1Schema)}. Put every binding field at the TOP LEVEL, not inside a binding object, and copy the host-supplied binding values exactly. For each check use checkId (not id), applicability as applicable/not-applicable/unresolved, predicateEvidence as an array of strings, outcome as passed/failed/blocked/not-run, and evidence as an array of objects with procedure, cwd, runtime, sourceDigest and reference. For postimplementation evidence sourceDigest is the exact host-supplied sourceDigest, not an individual file hash. Unconditional checks cannot be marked not-applicable or unresolved; for an absence or non-impact check, mark it applicable and provide bounded inspection evidence showing that the absent change or impact was assessed. For independent QA coverage of an applicable passed preimplementation-only check, inspect its matching passed contract.baseline observation and set at least one evidence reference to that observation's exact evidenceDigest; the historical observation is bound to its original source, not the current source. Assess its relevance rather than inventing or claiming a new baseline. Host-owned checks whose applicability decisionOwner is host are the exception to provider execution: include the check truthfully as applicable/not-run with evidence that the host-owned comparison is pending, and do not block or fail QA over it; Rafi will execute the comparison and replace that row before accepting the pass. Before emitting qa_pass, run every other applicable mandatory check that is not backed by a passed retained baseline; do not leave such a provider-owned check as not-run merely because an earlier turn omitted it. If an exact required command is blocked by the provider shell policy, use a semantically equivalent permitted read-only procedure, record the substitution and limitation truthfully, and assess the same predicate; do not mark the check blocked merely because the literal command syntax was denied. If a required command is permitted and read-only, run it now and retain its bounded result. Do not add unsupported fields. Include every check with truthful applicability and concrete evidence. Missing, blocked, not-run, unresolved applicability, or failed provider-owned mandatory coverage cannot authorize normal completion. Builder coverage is a claim; final QA independently verifies it.`;
+// The source and attempt binding do not exist until the implementation turn has finished.
+export const BUILDER_WORK_COVERAGE_INSTRUCTIONS = `Carry out the applicable contract checks and report your work and evidence honestly in your normal final response. When a check requires historical ordering, retain bounded output for each required step and an explicit ordering record while performing it; a later passing test cannot prove an earlier failing step. Do not emit RAFI_QA_COVERAGE JSON during this implementation turn or stop for coverage binding values. After the implementation turn, Rafi will capture the completed source and request a separate response-only coverage record with the exact host-owned bindings.`;
 export function parseContractCoverage(text) { return parsePreparationArtifact(text, "RAFI_QA_COVERAGE"); }
+/** Source identity is host-owned; providers may copy a stale Builder digest. */
+export function bindCoverageSourceDigest(coverage, sourceDigest) {
+    const copy = structuredClone(coverage);
+    for (const check of copy.checks ?? [])
+        for (const evidence of check.evidence ?? [])
+            evidence.sourceDigest = sourceDigest;
+    return copy;
+}
+/** All coverage identity fields are host-owned; provider output supplies only claims and evidence text. */
+export function bindCoverageHostFields(coverage, contract, binding) {
+    const copy = bindCoverageSourceDigest(coverage, binding.sourceDigest);
+    // Optional schema fields may be emitted as JSON null by providers. Null is
+    // not a meaningful limitation, so omit only that representation variant;
+    // non-string values elsewhere remain validation errors.
+    for (const check of copy.checks ?? [])
+        for (const evidence of check.evidence ?? [])
+            if (evidence.limitation === null)
+                delete evidence.limitation;
+    copy.version = 1;
+    copy.runId = contract.runId;
+    copy.workId = contract.workId;
+    copy.revision = contract.revision;
+    copy.contractDigest = contract.contentDigest;
+    copy.phase = binding.phase;
+    copy.sourceDigest = binding.sourceDigest;
+    copy.inputBasisDigest = binding.inputBasisDigest;
+    copy.attemptId = binding.attemptId;
+    copy.sessionId = binding.sessionId;
+    return copy;
+}
 export function validateContractCoverage(contract, coverage, binding, requirePass = true) {
     if (!coverageSchema(coverage))
         return (coverageSchema.errors ?? []).map(error => `${error.instancePath} ${error.message}`);
@@ -32,7 +64,7 @@ export function validateContractCoverage(contract, coverage, binding, requirePas
         if (check.applicability.kind === "conditional" && row.applicability === "applicable" && !row.predicateEvidence?.length)
             issues.push(`Conditional applicability requires predicate evidence ${row.checkId}`);
         if (requirePass && check.obligation === "mandatory" && (row.applicability === "unresolved" || row.applicability === "applicable" && row.outcome !== "passed"))
-            issues.push(`Mandatory check incomplete ${row.checkId}`);
+            issues.push(`Mandatory check incomplete ${row.checkId}: run its permitted verification now and resubmit passed evidence, or report a truthful blocked result for host recovery`);
         if (!Array.isArray(row.evidence))
             issues.push(`Missing evidence array ${row.checkId}`);
         if (row.outcome === "passed" && row.applicability === "applicable") {

package/dist/qaContractDelivery.d.ts

@@ -1,4 +1,4 @@
-import type { QaVerificationContractV1, QaContractDeliveryReceiptV1 } from "rafi-spec";
+import { type QaVerificationContractV1, type QaContractDeliveryReceiptV1 } from "rafi-spec";
 import type { BuilderAdapter } from "./adapters/types.js";
 import type { QaPreparationStore } from "./qaPreparationStore.js";
 export interface ContractSessionBinding {
@@ -16,7 +16,7 @@ export declare function materializeContract(contract: QaVerificationContractV1,
     resourceDigest: string;
 };
 /** Complete retained review inputs, accessible inside the confined QA snapshot. */
-export declare function finalReviewContractContext(contract: QaVerificationContractV1, store: QaPreparationStore, workspace: string, builderClaims?: unknown[]): string;
+export declare function finalReviewContractContext(contract: QaVerificationContractV1, store: QaPreparationStore, workspace: string, builderClaims?: unknown[], commandObservations?: unknown[]): string;
 export declare function deliverVerificationContract(contract: QaVerificationContractV1, store: QaPreparationStore, adapter: BuilderAdapter, workspace: string, configRoot: string, context: string): Promise<QaContractDeliveryReceiptV1>;
 /** Byte bounded, lossless Unicode transport. Concatenation reconstructs the exact original input. */
 export declare function segmentContractTransport(content: string, maximumBytes?: number): string[];