ai-foreman 1.7.28 → 2.0.0

package/dist/qaReviewEvidence.d.ts

@@ -1,6 +1,10 @@
 import type { RunSpanV1 } from "rafi-spec";
-/** Explicit authorization is scoped to one nonempty ticket ID. */
-export declare function qaCommandOutputExcerptsAllowed(workId: string, configuredTicket?: string | undefined): boolean;
-/** Excerpts are opt-in; command text is never forwarded. */
+/**
+ * Bounded, adapter-redacted output excerpts are host-retained evidence and are
+ * delivered to independent QA by default. RAFI_QA_COMMAND_OUTPUT_EXCERPTS=0
+ * (or off/false) disables them; a ticket ID limits them to that ticket.
+ */
+export declare function qaCommandOutputExcerptsAllowed(workId: string, configured?: string | undefined): boolean;
+/** Command text is never forwarded; excerpts are bounded and may be truncated. */
 export declare function selectQaCommandObservations(spans: RunSpanV1[], runId: string, workId: string, includeOutputExcerpts?: boolean): unknown[];
 export declare function retainedQaCommandObservations(projectDir: string, runId: string, workId: string, includeOutputExcerpts?: boolean): unknown[];

package/dist/qaReviewEvidence.js

@@ -1,9 +1,20 @@
 import { ObservabilityReader } from "./observability.js";
-/** Explicit authorization is scoped to one nonempty ticket ID. */
-export function qaCommandOutputExcerptsAllowed(workId, configuredTicket = process.env.RAFI_QA_COMMAND_OUTPUT_EXCERPTS) {
-    return workId.length > 0 && configuredTicket === workId;
+/**
+ * Bounded, adapter-redacted output excerpts are host-retained evidence and are
+ * delivered to independent QA by default. RAFI_QA_COMMAND_OUTPUT_EXCERPTS=0
+ * (or off/false) disables them; a ticket ID limits them to that ticket.
+ */
+export function qaCommandOutputExcerptsAllowed(workId, configured = process.env.RAFI_QA_COMMAND_OUTPUT_EXCERPTS) {
+    if (!workId)
+        return false;
+    const value = configured?.trim();
+    if (!value || ["1", "on", "true"].includes(value.toLowerCase()))
+        return true;
+    if (["0", "off", "false"].includes(value.toLowerCase()))
+        return false;
+    return value === workId;
 }
-/** Excerpts are opt-in; command text is never forwarded. */
+/** Command text is never forwarded; excerpts are bounded and may be truncated. */
 export function selectQaCommandObservations(spans, runId, workId, includeOutputExcerpts = false) {
     const turns = new Set(spans.filter(span => span.runId === runId && span.kind === "provider_turn" && span.role === "builder" && span.ticketId === workId).map(span => span.spanId));
     return spans.filter(span => span.runId === runId && span.kind === "tool" && span.role === "builder" && span.parentSpanId && turns.has(span.parentSpanId) && span.completionKnown && span.endedAt)

package/dist/qaRuntime.js

@@ -13,7 +13,7 @@ export function describeQaRuntimeHandle(adapter, metadata, handoffReceipt) {
     // need the machine owner's authentication settings; Codex does not receive
     // that SDK option.
     const settingsSources = adapter.agent === "claude" ? "user" : "none";
-    const confinementPolicy = { sandboxMode: "read-only", settingsSources, permissions: readOnlyPermissionConfig(), dependencyProjection: "read-only-symlink", scratch: "sibling-temp-directory" };
+    const confinementPolicy = { sandboxMode: "read-only", settingsSources, permissions: readOnlyPermissionConfig(), dependencyProjection: "read-only-symlink", scratch: adapter.agent === "claude" ? "adapter-owned-private-temp-directory" : "sibling-temp-directory" };
     const confinementBase = {
         version: 2, sourceMode: "read-only", scratchMode: "isolated",
         settingsSources, networkMode: "provider-required",

package/dist/qaSnapshot.js

@@ -51,11 +51,14 @@ export function createDisposableQaSnapshot(builderWorktree, options = {}) {
     const frozenState = captureFrozenQaSource(source);
     const tempRoot = mkdtempSync(join(tmpdir(), "rafi-qa-"));
     const review = join(tempRoot, "review");
-    cloneRepositorySync(root, review, frozenState.head);
+    if (frozenState.head === "unavailable")
+        initializeUncommittedReviewSync(review);
+    else
+        cloneRepositorySync(root, review, frozenState.head);
     try {
         applyFrozenSync(review, frozenState);
         if (options.projectDependencies !== false)
-            projectDependencyTrees(root, review);
+            projectDependencyTrees(root, review, frozenState.head === "unavailable");
         mkdirSync(join(tempRoot, "scratch"), { mode: 0o700 });
         const manifest = manifestFromFrozen(frozenState);
         const snapshot = {
@@ -81,9 +84,12 @@ export async function createDisposableQaSnapshotAsync(builderWorktree, progress
     const review = join(tempRoot, "review");
     try {
         progress("preparing disposable QA snapshot", "creating independent review repository");
-        await cloneRepositoryAsync(root, review, frozenState.head);
+        if (frozenState.head === "unavailable")
+            await initializeUncommittedReviewAsync(review);
+        else
+            await cloneRepositoryAsync(root, review, frozenState.head);
         await applyFrozenAsync(review, frozenState, progress);
-        projectDependencyTrees(root, review);
+        projectDependencyTrees(root, review, frozenState.head === "unavailable");
         await mkdir(join(tempRoot, "scratch"), { mode: 0o700 });
         const manifest = manifestFromFrozen(frozenState);
         const snapshot = {
@@ -106,11 +112,11 @@ export async function createDisposableQaSnapshotAsync(builderWorktree, progress
 }
 export function frozenQaStateManifest(state) { return manifestFromFrozen(state); }
 export function changeManifest(worktree) {
-    const diff = gitBuffer(resolve(worktree), ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    const diff = hasHeadSync(worktree) ? gitBuffer(resolve(worktree), ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
     return { diffDigest: hash(diff), untracked: untrackedPaths(worktree).map((path) => describeUntrackedSync(worktree, path)) };
 }
 export async function changeManifestAsync(worktree, progress = () => { }, state = "checking QA file changes") {
-    const diff = await runGit(worktree, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    const diff = (await hasHeadAsync(worktree)) ? await runGit(worktree, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
     const paths = await untrackedPathsAsync(worktree);
     const untracked = [];
     for (let index = 0; index < paths.length; index++) {
@@ -162,14 +168,14 @@ export function prospectiveGitTreeMatches(worktree, expectedTree, allowedPaths =
     throw new Error(`git diff could not compare QA finalization trees (exit ${result.status ?? "unknown"})`);
 }
 function captureOnce(cwd) {
-    const head = gitText(cwd, ["rev-parse", "HEAD"]);
+    const head = hasHeadSync(cwd) ? gitText(cwd, ["rev-parse", "HEAD"]) : "unavailable";
     const repository = captureRepositoryMetadataSync(cwd);
     const status = gitBuffer(cwd, ["status", "--porcelain=v2", "-z", "--untracked-files=all", ...PRODUCT_PATHSPEC]);
-    const combinedDiff = gitBuffer(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
-    const stagedDiff = gitBuffer(cwd, ["diff", "--cached", "--binary", ...PRODUCT_PATHSPEC]);
-    const unstagedDiff = gitBuffer(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]);
-    const stagedNames = gitBuffer(cwd, ["diff", "--cached", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
-    const unstagedNames = gitBuffer(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
+    const combinedDiff = head === "unavailable" ? Buffer.alloc(0) : gitBuffer(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    const stagedDiff = gitBuffer(cwd, ["diff", "--cached", "--binary", ...(head === "unavailable" ? ["--root"] : []), ...PRODUCT_PATHSPEC]);
+    const unstagedDiff = head === "unavailable" ? Buffer.alloc(0) : gitBuffer(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]);
+    const stagedNames = gitBuffer(cwd, ["diff", "--cached", "--name-status", "-z", ...(head === "unavailable" ? ["--root"] : []), ...PRODUCT_PATHSPEC]);
+    const unstagedNames = head === "unavailable" ? Buffer.alloc(0) : gitBuffer(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
     const untrackedNames = gitBuffer(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]);
     const untracked = untrackedPathsFrom(untrackedNames).map((path) => captureUntrackedSync(cwd, path));
     const pathInventory = enrichTrackedPathInventorySync(cwd, buildPathInventory(stagedNames, unstagedNames, untracked));
@@ -183,14 +189,15 @@ async function captureOnceAsync(cwd, progress) {
     // observe a different index/worktree generation and manufacture a state
     // that never existed. The enclosing double-capture supplies the stability
     // fence across the complete sequence.
-    const headBytes = await runGit(cwd, ["rev-parse", "HEAD"]);
+    const headAvailable = await hasHeadAsync(cwd);
+    const headBytes = headAvailable ? await runGit(cwd, ["rev-parse", "HEAD"]) : Buffer.from("unavailable");
     const repository = await captureRepositoryMetadataAsync(cwd);
     const status = await runGit(cwd, ["status", "--porcelain=v2", "-z", "--untracked-files=all", ...PRODUCT_PATHSPEC]);
-    const combinedDiff = await runGit(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
-    const stagedDiff = await runGit(cwd, ["diff", "--cached", "--binary", ...PRODUCT_PATHSPEC]);
-    const unstagedDiff = await runGit(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]);
-    const stagedNames = await runGit(cwd, ["diff", "--cached", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
-    const unstagedNames = await runGit(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
+    const combinedDiff = headAvailable ? await runGit(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
+    const stagedDiff = await runGit(cwd, ["diff", "--cached", "--binary", ...(headAvailable ? [] : ["--root"]), ...PRODUCT_PATHSPEC]);
+    const unstagedDiff = headAvailable ? await runGit(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
+    const stagedNames = await runGit(cwd, ["diff", "--cached", "--name-status", "-z", ...(headAvailable ? [] : ["--root"]), ...PRODUCT_PATHSPEC]);
+    const unstagedNames = headAvailable ? await runGit(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]) : Buffer.alloc(0);
     const untrackedNames = await runGit(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]);
     const paths = untrackedPathsFrom(untrackedNames);
     const untracked = [];
@@ -303,7 +310,13 @@ function describeUntrackedSync(worktree, path) {
 function untrackedPaths(worktree) { return untrackedPathsFrom(gitBuffer(resolve(worktree), ["ls-files", "--others", "--exclude-standard", "-z"])); }
 async function untrackedPathsAsync(worktree) { return untrackedPathsFrom(await runGit(worktree, ["ls-files", "--others", "--exclude-standard", "-z"])); }
 function untrackedPathsFrom(raw) { return raw.toString().split("\0").filter((path) => path && isQaProductPath(path)).sort(); }
-function isQaProductPath(path) { return path !== ".foreman" && !path.startsWith(".foreman/") && path !== ".rafi" && !path.startsWith(".rafi/"); }
+function isQaProductPath(path) {
+    return path !== ".git" && !path.startsWith(".git/")
+        && path !== ".foreman" && !path.startsWith(".foreman/")
+        && path !== ".rafi" && !path.startsWith(".rafi/")
+        && path !== "node_modules" && !path.startsWith("node_modules/")
+        && path !== "vendor" && !path.startsWith("vendor/");
+}
 function renderSummary(staged, unstaged, untracked) {
     const normalize = (value) => value.toString().split("\0").filter(Boolean).filter(isQaProductPath).sort().join("\n") || "(none)";
     return `tracked/staged:\n${normalize(staged)}\ntracked/unstaged:\n${normalize(unstaged)}\nuntracked:\n${normalize(untracked)}`;
@@ -454,6 +467,16 @@ function manifestDifference(before, after) {
             changes.push(path);
     return changes;
 }
+function initializeUncommittedReviewSync(review) {
+    mkdirSync(review, { recursive: true });
+    const initialized = spawnSync("git", ["init", "-q", review], { encoding: "utf8" });
+    if (initialized.status !== 0)
+        throw new Error(`cannot initialize independent QA repository: ${initialized.stderr.trim()}`);
+}
+async function initializeUncommittedReviewAsync(review) {
+    await mkdir(review, { recursive: true });
+    await runGit(dirname(review), ["init", "-q", review]);
+}
 function cloneRepositorySync(root, review, head) {
     const cloned = spawnSync("git", ["clone", "--no-local", "--no-hardlinks", "--no-checkout", "--quiet", root, review], { encoding: "utf8" });
     if (cloned.status !== 0) {
@@ -475,7 +498,7 @@ async function cloneRepositoryAsync(root, review, head) {
  * Project the existing trees without copying or permitting writes so validation
  * commands in the independent clone can resolve the same installed toolchain.
  */
-function projectDependencyTrees(sourceRoot, reviewRoot) {
+function projectDependencyTrees(sourceRoot, reviewRoot, uncommitted = false) {
     const parents = ["", ...readdirSync(sourceRoot, { withFileTypes: true })
             .filter((entry) => entry.isDirectory() && entry.name !== ".git" && entry.name !== "node_modules")
             .flatMap((entry) => {
@@ -491,11 +514,38 @@ function projectDependencyTrees(sourceRoot, reviewRoot) {
         if (!existsSync(source) || existsSync(target) || !lstatSync(source).isDirectory())
             continue;
         const relativeTarget = parent ? `${parent.replaceAll("\\", "/")}/node_modules` : "node_modules";
-        if (spawnSync("git", ["-C", reviewRoot, "check-ignore", "-q", "--", relativeTarget]).status !== 0)
+        if (!uncommitted && spawnSync("git", ["-C", reviewRoot, "check-ignore", "-q", "--", relativeTarget]).status !== 0)
             continue;
         mkdirSync(dirname(target), { recursive: true });
         symlinkSync(source, target, "dir");
     }
+    if (!uncommitted)
+        return;
+    for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || [".git", ".rafi", ".foreman", "node_modules"].includes(entry.name))
+            continue;
+        const source = join(sourceRoot, entry.name);
+        const target = join(reviewRoot, entry.name);
+        if (existsSync(target))
+            continue;
+        const ignored = spawnSync("git", ["-C", sourceRoot, "check-ignore", "-q", "--", entry.name]).status === 0;
+        if (!ignored)
+            continue;
+        symlinkSync(source, target, "dir");
+    }
+}
+function hasHeadSync(cwd) {
+    const result = spawnSync("git", ["-C", resolve(cwd), "rev-parse", "--verify", "HEAD"], { stdio: "ignore" });
+    return result.status === 0;
+}
+async function hasHeadAsync(cwd) {
+    try {
+        await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 function captureRepositoryMetadataSync(cwd) {
     const topLevel = gitText(cwd, ["rev-parse", "--show-toplevel"]);

package/dist/qaStructuredResponse.d.ts

@@ -0,0 +1,10 @@
+import { type QaResponseContract } from "rafi-spec";
+import type { TurnResult } from "./adapters/types.js";
+import type { StepStatus } from "./foreman.js";
+import { type BuilderQaRemediationContract, type QaFindingRefV2 } from "rafi-spec";
+export declare function qaStructuredResponse(turn: TurnResult): QaResponseContract;
+export declare function qaStructuredStatus(turn: TurnResult): StepStatus;
+export declare function remediationStructuredResponse(turn: TurnResult, expected: {
+    handoffId?: string;
+    findings?: QaFindingRefV2[];
+}): BuilderQaRemediationContract;

package/dist/qaStructuredResponse.js

@@ -0,0 +1,57 @@
+import { qaVerdictOutput, validateQaFailureReport, validateBuilderQaRemediationReport } from "rafi-spec";
+import { operationResponse } from "./structuredOperation.js";
+import { remediationOutput, validateBuilderFindingCoverage } from "rafi-spec";
+export function qaStructuredResponse(turn) {
+    try {
+        const response = operationResponse(turn, qaVerdictOutput);
+        if (response.result.kind === "blocked")
+            return { valid: true, errors: [], status: "blocked", fields: { reason: response.result.reason } };
+        if (response.result.kind === "needs-input")
+            return { valid: true, errors: [], status: "needs_input", fields: { question: response.result.question, choices: response.result.choices.join("|") } };
+        if (response.result.kind !== "completed")
+            throw new Error("Unconsumed QA intermediate result");
+        const payload = response.result.payload;
+        if (payload.kind === "failed") {
+            const validation = validateQaFailureReport(payload.report);
+            if (!validation.valid)
+                throw new Error(validation.errors.join("; "));
+        }
+        return payload.kind === "passed" ? { valid: true, errors: [], status: "qa_pass", fields: { summary: response.result.summary } }
+            : { valid: true, errors: [], status: "qa_fail", fields: { issues: response.result.summary }, report: payload.report, rawReportJson: JSON.stringify(payload.report) };
+    }
+    catch (error) {
+        return { valid: false, errors: [String(error)], status: "unknown", fields: {} };
+    }
+}
+export function qaStructuredStatus(turn) {
+    const contract = qaStructuredResponse(turn);
+    return { kind: contract.status, ...contract.fields, choices: contract.fields.choices?.split("|"), error: contract.errors.join("; ") || undefined };
+}
+export function remediationStructuredResponse(turn, expected) {
+    try {
+        const { result } = operationResponse(turn, remediationOutput);
+        if (result.kind === "blocked")
+            return { valid: true, errors: [], status: "blocked", fields: { reason: result.reason } };
+        if (result.kind === "needs-input")
+            return { valid: true, errors: [], status: "needs_input", fields: { question: result.question } };
+        if (result.kind !== "completed")
+            throw new Error("Unconsumed remediation intermediate result");
+        const { report, status, reason } = result.payload;
+        const validation = validateBuilderQaRemediationReport(report);
+        if (!validation.valid)
+            throw new Error(validation.errors.join("; "));
+        const errors = expected.findings ? validateBuilderFindingCoverage(report, expected.findings) : [];
+        if (expected.handoffId && report.handoff_id !== expected.handoffId)
+            errors.push("Remediation handoff identity mismatch");
+        const blocked = report.findings.some(finding => finding.disposition === "blocked");
+        if (blocked !== (status === "blocked") || status === "blocked" && !reason || status === "done" && reason !== null)
+            errors.push("Contradictory remediation outcome");
+        for (const finding of report.findings)
+            if (Boolean(finding.blocker) !== (finding.disposition === "blocked"))
+                errors.push(`Invalid blocker for ${finding.finding_key}`);
+        return { valid: !errors.length, errors, status, fields: status === "blocked" ? { reason: reason } : { summary: result.summary }, report, rawReportJson: JSON.stringify(report) };
+    }
+    catch (error) {
+        return { valid: false, errors: [String(error)], status: "unknown", fields: {} };
+    }
+}

package/dist/qaTimeline.js

@@ -1,6 +1,6 @@
 import { decisionBelongsToWork } from "./buildInterventions.js";
 import { evidenceRecord } from "./qaEvidenceReader.js";
-import { parseQaResponseContract } from "rafi-spec";
+import { describeLegacyQaTranscript } from "./legacyCommunicationDisplay.js";
 /** All counters are scoped rows. A changed digest is never a code-change explanation. */
 export function buildQaTimeline(snapshot, workId) {
     const scoped = (table) => (snapshot.rows[table] ?? []).filter(row => row.ticket_id === workId);
@@ -25,8 +25,10 @@ export function buildQaTimeline(snapshot, workId) {
         if (/correction|repair/.test(slot))
             counters.corrections++;
         const bytes = typeof receipt?.cleanedResponseDigest === "string" ? snapshot.blobs.get(receipt.cleanedResponseDigest) : undefined;
-        const contract = bytes ? parseQaResponseContract(bytes.toString("utf8")) : undefined;
-        const classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
+        const contract = bytes ? describeLegacyQaTranscript(bytes.toString("utf8")) : undefined;
+        let classification = contract ? contract.valid ? contract.status : "malformed" : "unavailable";
+        if (typeof receipt?.structuredResponseDigest === "string")
+            classification = "unavailable";
         if (slot === "initial" && classification === "malformed")
             counters.malformedResponses++;
         if (slot === "initial" && classification === "blocked")

package/dist/qaToolRecovery.d.ts

@@ -0,0 +1,12 @@
+import type { BuilderEvent } from "./adapters/types.js";
+export type QaUnresolvedToolDecision = {
+    action: "none";
+} | {
+    action: "retry";
+    detail: string;
+} | {
+    action: "pause";
+    detail: string;
+};
+export declare function recordQaUnresolvedTools(projectDir: string, runId: string, ticketId: string, events: BuilderEvent[]): void;
+export declare function qaUnresolvedToolDecision(projectDir: string, runId: string, ticketId: string, events: BuilderEvent[]): QaUnresolvedToolDecision;

package/dist/qaToolRecovery.js

@@ -0,0 +1,44 @@
+import { WorkflowDb } from "./workflowDb.js";
+function unresolvedTools(events) {
+    const latest = new Map();
+    for (const event of events)
+        if (event.kind === "tool" && event.callId && event.lifecycle === "completed")
+            latest.set(event.callId, event);
+    return [...latest.values()].filter(event => event.completionKnown === false).map(event => ({ callId: event.callId, digest: event.outputDigest, name: event.name }));
+}
+export function recordQaUnresolvedTools(projectDir, runId, ticketId, events) {
+    const unresolved = unresolvedTools(events);
+    if (!unresolved.length)
+        return;
+    const db = new WorkflowDb(projectDir);
+    try {
+        const prior = db.continuityEvents(runId).filter(event => event.kind === "qa-unresolved-tool-result" && event.payload.ticketId === ticketId);
+        const known = new Set(prior.map(event => JSON.stringify(event.payload)));
+        const head = db.qaTicketHead(runId, ticketId);
+        for (const item of unresolved) {
+            const payload = { ticketId, callId: item.callId, toolName: item.name, outputDigest: item.digest ?? null };
+            if (!known.has(JSON.stringify(payload)))
+                db.appendContinuityEvent({ runId, role: "qa", kind: "qa-unresolved-tool-result", payload, authoritativeStateRevision: head.revision });
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+export function qaUnresolvedToolDecision(projectDir, runId, ticketId, events) {
+    const unresolved = unresolvedTools(events);
+    if (!unresolved.length)
+        return { action: "none" };
+    const db = new WorkflowDb(projectDir);
+    try {
+        const records = db.continuityEvents(runId).filter(event => event.kind === "qa-unresolved-tool-result" && event.payload.ticketId === ticketId);
+        const priorKeys = new Set(records.map(event => { const payload = event.payload; return payload.outputDigest ?? payload.toolName; }));
+        const repeated = unresolved.find(item => priorKeys.has(item.digest ?? item.name));
+        if (repeated)
+            return { action: "pause", detail: `QA tool result remains unresolved after one controlled recovery (${repeated.name}, ${repeated.digest ?? repeated.name}); no provider action was replayed` };
+        return { action: "retry", detail: `QA observed an unresolved ${unresolved[0].name} result; starting one fresh review without replaying the uncertain tool action` };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/qaVerificationContract.d.ts

@@ -10,6 +10,8 @@ export declare function allocateStableCheckIds(candidate: QaContractCandidateV1)
 export declare function inventoryDigest(requirements: RequirementRef[]): string;
 /** Derive a missing baseline binding only from an explicit, unique check prerequisite reference. */
 export declare function bindUniqueBaselineCheckIds(candidate: QaContractCandidateV1): QaContractCandidateV1;
+/** Ensure the host-owned scope invariant survives providers that omit or rename it. */
+export declare function ensureHostScopeCheck(candidate: QaContractCandidateV1, baselineId: string): QaContractCandidateV1;
 /**
  * The host owns the before/after path comparison. Providers may still draft a
  * check that asks them to enumerate every changed file, which turns host
@@ -18,9 +20,8 @@ export declare function bindUniqueBaselineCheckIds(candidate: QaContractCandidat
  */
 export declare function rewriteProviderHostScopeChecks(candidate: QaContractCandidateV1, baselineId: string): QaContractCandidateV1;
 export declare function authoritativeInventory(ticket: TicketDef, checklist: string[], inputs: ContractInputRef[]): RequirementRef[];
-export declare function parsePreparationArtifact<T>(text: string, tag: string, maximum?: number): T;
 /** Capture safe absolute snapshot paths before the disposable snapshot is removed. */
-export declare function mapSnapshotWorkingDirectories(text: string, snapshotPath: string): Record<string, string>;
+export declare function mapSnapshotWorkingDirectories(text: Partial<QaContractCandidateV1>, snapshotPath: string): Record<string, string>;
 /** Providers sometimes repeat an absolute disposable-snapshot path from an earlier
  * conversation.  That path is host-owned and must not enter the durable contract;
  * normalize only the bounded QA snapshot naming convention to stable relative

package/dist/qaVerificationContract.js

@@ -113,8 +113,12 @@ export function inventoryDigest(requirements) { return contractDigest("qa-requir
 /** Derive a missing baseline binding only from an explicit, unique check prerequisite reference. */
 export function bindUniqueBaselineCheckIds(candidate) {
     const draft = structuredClone(candidate);
+    const proposedIds = new Set(draft.checks.map(check => check.id));
     for (const observation of draft.baseline) {
-        if (observation.checkId)
+        // A correction may copy a stable check ID from an earlier draft. Repair
+        // that stale binding from the observation's unique prerequisite instead
+        // of sending it through stable-ID allocation as if it were current.
+        if (observation.checkId && proposedIds.has(observation.checkId))
             continue;
         const matches = draft.checks.filter(check => check.prerequisiteRefs.includes(observation.id));
         if (matches.length === 1)
@@ -122,6 +126,38 @@ export function bindUniqueBaselineCheckIds(candidate) {
     }
     return draft;
 }
+/** Ensure the host-owned scope invariant survives providers that omit or rename it. */
+export function ensureHostScopeCheck(candidate, baselineId) {
+    const copy = structuredClone(candidate);
+    const hasHostScope = copy.checks.some(check => check.hostKind === "source-scope");
+    if (hasHostScope)
+        return copy;
+    // Every contract check must trace to at least one authoritative requirement.
+    // The host scope invariant is cross-cutting rather than provider-authored, so
+    // bind it to the first approved requirement when a provider omitted the
+    // invariant entirely. This keeps the invariant structurally valid without
+    // inventing a new requirement outside the authoritative inventory.
+    const scopeRequirement = copy.requirements[0]?.id;
+    if (!scopeRequirement)
+        throw new Error("Cannot add host scope check without an authoritative requirement");
+    let hostId = "host-scope";
+    while (copy.checks.some(check => check.id === hostId))
+        hostId += "-host";
+    copy.checks.push({
+        id: hostId, hostKind: "source-scope",
+        requirementRefs: [scopeRequirement],
+        origin: "invariant",
+        expectedBehavior: "Rafi compares the final product paths with the host-captured preimplementation baseline and rejects unauthorized product changes.",
+        obligation: "mandatory",
+        timing: "postimplementation",
+        applicability: { kind: "unconditional", decisionOwner: "host", requiredEvidence: [baselineId] },
+        verification: [{ kind: "procedure", steps: ["Rafi performs the host-owned before/after product-path comparison, excluding approved bookkeeping and bounded evidence paths."], cwd: ".", fixtures: [], runtime: "Rafi host", timeoutMs: 30_000, expectedOutcome: "Only approved product changes are present; unauthorized, destructive, protected, or requirement-relevant changes are rejected." }],
+        expectedEvidence: ["Rafi host-owned postimplementation scope comparison bound to the retained preimplementation baseline."],
+        prerequisiteRefs: [baselineId],
+        dependsOnChecks: [],
+    });
+    return copy;
+}
 /**
  * The host owns the before/after path comparison. Providers may still draft a
  * check that asks them to enumerate every changed file, which turns host
@@ -135,7 +171,8 @@ export function rewriteProviderHostScopeChecks(candidate, baselineId) {
         return /\b(?:complete|full|all|every)\s+(?:changed|modified|touched)[ -](?:path|paths|file|files)\b/.test(text)
             || /\b(?:changed|modified|touched)[ -](?:path|paths|file|files)\s+(?:inventory|list|manifest)\b/.test(text)
             || /\bunchanged[- ]files?\s+(?:comparison|check|verification)\b/.test(text)
-            || /\bpath\s+manifest\b.{0,80}\b(?:compare|comparison|unchanged|scope)\b/.test(text);
+            || /\bpath\s+manifest\b.{0,80}\b(?:compare|comparison|unchanged|scope)\b/.test(text)
+            || (check.applicability.decisionOwner === "host" && /scope.{0,80}comparison|comparison.{0,80}scope|product paths?.{0,100}baseline/.test(text));
     };
     const matches = draft.checks.filter(hostScope);
     if (!matches.length)
@@ -179,42 +216,13 @@ export function authoritativeInventory(ticket, checklist, inputs) {
     }
     return result;
 }
-export function parsePreparationArtifact(text, tag, maximum = 2 * 1024 * 1024) {
-    if (Buffer.byteLength(text) > maximum)
-        throw new Error("QA preparation response exceeds size limit");
-    const start = `${tag}_START`, end = `${tag}_END`;
-    // Marker names can appear inline in provider prose or in a quoted repair
-    // instruction. Only a standalone marker line is an envelope boundary.
-    // This keeps the parser strict about malformed envelopes without treating
-    // explanatory text as a second/truncated artifact.
-    const markerOffsets = (marker) => {
-        const offsets = [];
-        const pattern = new RegExp(`^[ \\t]*${marker}[ \\t]*$`, "gm");
-        for (let match = pattern.exec(text); match; match = pattern.exec(text))
-            offsets.push(match.index);
-        return offsets;
-    };
-    const starts = markerOffsets(start), ends = markerOffsets(end);
-    if (!starts.length || starts.length !== ends.length)
-        throw new Error(`Expected exactly one ${tag} artifact`);
-    const artifacts = starts.map((at, index) => {
-        const from = at + start.length, to = ends[index];
-        if (to < from)
-            throw new Error("Malformed preparation artifact envelope");
-        return text.slice(from, to).trim();
-    });
-    if (artifacts.length > 1) {
-        const normalized = artifacts.map(artifact => canonicalContractJson(JSON.parse(artifact)));
-        if (normalized.some(artifact => artifact !== normalized[0]))
-            throw new Error(`Expected exactly one unambiguous ${tag} artifact`);
-    }
-    return JSON.parse(artifacts[0]);
-}
 /** Capture safe absolute snapshot paths before the disposable snapshot is removed. */
 export function mapSnapshotWorkingDirectories(text, snapshotPath) {
     const result = {};
     try {
-        const draft = parsePreparationArtifact(text, "RAFI_QA_CANDIDATE");
+        if (typeof text === "string")
+            throw new Error("Snapshot mappings require validated native draft fields");
+        const draft = text;
         const root = realpathSync(snapshotPath);
         for (const check of draft.checks ?? [])
             for (const method of check.verification ?? []) {
@@ -228,6 +236,17 @@ export function mapSnapshotWorkingDirectories(text, snapshotPath) {
                 }
                 catch { /* Missing or inaccessible paths remain invalid. */ }
             }
+        for (const evidence of draft.preparationEvidence ?? [])
+            for (const reference of evidence.references ?? []) {
+                if (!isAbsolute(reference.path))
+                    continue;
+                try {
+                    const target = realpathSync(reference.path), path = relative(root, target);
+                    if (path && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path) && statSync(target).isFile())
+                        result[reference.path] = path;
+                }
+                catch { /* Unreadable/outside references are rejected during binding. */ }
+            }
     }
     catch { /* Parsing and validation report malformed provider responses. */ }
     return result;
@@ -275,6 +294,11 @@ export function validateCandidate(candidate, inventory, resolveEquivalent) {
     for (const req of candidate.requirements) {
         if (!inputs.has(req.inputRef) || !req.statement?.trim() || req.digest !== contractDigest("statement", req.statement))
             issues.push(`Invalid source/statement ${req.id}`);
+        if (req.verificationIntent !== undefined && req.verificationIntentDigest !== contractDigest("verification-intent-v2", req.verificationIntent)) {
+            issues.push(`Invalid V2 verification intent ${req.id}`);
+        }
+        if (req.verificationIntent === undefined && req.verificationIntentDigest !== undefined)
+            issues.push(`Unexpected V2 verification intent digest ${req.id}`);
         if (req.conflict)
             issues.push(`Unresolved requirement conflict ${req.id}`);
         if (req.authority === "proposed" && req.obligation === "mandatory")

package/dist/readinessGate.js

@@ -1,3 +1,4 @@
+import { parseHostIpc } from "rafi-spec";
 /** Trusted bootstrap: registration and durable authorization precede all provider work. */
 import { WorkflowDb } from "./workflowDb.js";
 import { spawn } from "node:child_process";
@@ -21,7 +22,7 @@ try {
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => finish(new Error("Readiness authorization timed out")), 10_000);
         const disconnect = () => finish(new Error("Readiness owner disconnected"));
-        const message = (value) => { if (value === "rafi-probe-authorized")
+        const message = (value) => { const ack = parseHostIpc(value); if (ack?.kind === "rafi-probe-authorized" && ack.id === id && ack.pid === process.pid)
             finish(); };
         function finish(error) {
             clearTimeout(timer);
@@ -34,7 +35,7 @@ try {
         }
         process.on("message", message);
         process.once("disconnect", disconnect);
-        process.send({ kind: "rafi-probe-registered", id });
+        process.send({ version: 1, kind: "rafi-probe-registered", id, pid: process.pid });
         if (disconnected)
             disconnect();
     });
@@ -47,11 +48,11 @@ try {
         stdio: [windows ? "pipe" : "ignore", "inherit", "inherit"],
     });
     child.on("error", (error) => {
-        process.send?.({ kind: "rafi-probe-spawn-error", code: error.code, message: error.message });
+        process.send?.({ version: 1, kind: "rafi-probe-spawn-error", id, pid: process.pid, code: error.code ?? null, message: error.message.slice(0, 8192) });
         console.error(error.message);
         process.exitCode = 127;
     });
-    const done = new Promise(resolve => { child.once("exit", (code, signal) => { process.send?.({ kind: "rafi-probe-result", exitCode: code, signal }); process.exitCode = code ?? 1; resolve(); }); child.once("error", () => resolve()); });
+    const done = new Promise(resolve => { child.once("exit", (code, signal) => { process.send?.({ version: 1, kind: "rafi-probe-result", id, pid: process.pid, exitCode: code, signal }); process.exitCode = code ?? 1; resolve(); }); child.once("error", () => resolve()); });
     if (windows) {
         try {
             if (!child.pid)