ai-foreman 1.7.26 → 1.7.27

package/dist/qaPreparationPolicy.js

@@ -9,10 +9,34 @@ export const DEPTH_OBLIGATIONS = [
     ["approach-proposal", "independent-challenge", "coordinated-verification"],
 ];
 export function depthObligations(level) { return DEPTH_OBLIGATIONS.slice(0, level).flat(); }
-export function resolveQaPreparationConfig(value) {
-    const defaults = { mode: "legacy", policyVersion: QA_PREPARATION_POLICY_VERSION, wallTimeMs: [300_000, 600_000, 1_200_000, 1_800_000, 2_700_000] };
-    if (value === undefined)
-        return defaults;
+/** Resolve public boolean configuration while temporarily accepting old mode objects. */
+export function resolveQaPreparationConfig(value, shadow = false, wallTimeMs) {
+    // Preparation may require several fresh provider conversations (draft,
+    // independent assessment, challenge, and bounded repairs). Keep this
+    // ceiling separate from provider turn deadlines and give the logical
+    // workflow enough time to reconcile retained work without replaying an
+    // uncertain dispatch.
+    const defaults = { mode: "legacy", policyVersion: QA_PREPARATION_POLICY_VERSION, wallTimeMs: [600_000, 1_200_000, 2_400_000, 3_600_000, 5_400_000] };
+    const resolveWallTime = (candidate) => {
+        if (candidate === undefined)
+            return undefined;
+        if (!Array.isArray(candidate) || candidate.length !== 5 || candidate.some((v, i) => !Number.isSafeInteger(v) || v < defaults.wallTimeMs[i]))
+            throw new Error("QA preparation ceilings must specify five integer limits at least as large as policy defaults");
+        return candidate;
+    };
+    const publicWallTime = resolveWallTime(wallTimeMs);
+    if (value === undefined) {
+        if (shadow)
+            throw new Error("qa_preparation_shadow requires qa_preparation: true");
+        return { ...defaults, ...(publicWallTime ? { wallTimeMs: publicWallTime } : {}) };
+    }
+    if (typeof value === "boolean") {
+        if (shadow && !value)
+            throw new Error("qa_preparation_shadow requires qa_preparation: true");
+        return { ...defaults, ...(publicWallTime ? { wallTimeMs: publicWallTime } : {}), mode: !value ? "legacy" : shadow ? "shadow" : "enforce" };
+    }
+    if (shadow)
+        throw new Error("qa_preparation_shadow cannot be combined with legacy qa_preparation object configuration");
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("qa_preparation must be an object");
     const raw = value;
@@ -22,9 +46,10 @@ export function resolveQaPreparationConfig(value) {
         throw new Error("qa_preparation.mode must be legacy, shadow, or enforce");
     if (raw.policyVersion !== undefined && raw.policyVersion !== defaults.policyVersion)
         throw new Error("Unsupported QA preparation policy version");
-    if (raw.wallTimeMs !== undefined && (!Array.isArray(raw.wallTimeMs) || raw.wallTimeMs.length !== 5 || raw.wallTimeMs.some((v, i) => !Number.isSafeInteger(v) || v < defaults.wallTimeMs[i])))
-        throw new Error("QA preparation ceilings must specify five integer limits at least as large as policy defaults");
-    return { ...defaults, mode: raw.mode, ...(raw.wallTimeMs ? { wallTimeMs: raw.wallTimeMs } : {}) };
+    if (wallTimeMs !== undefined)
+        throw new Error("qa_preparation_wall_time_ms cannot be combined with legacy qa_preparation object configuration");
+    const legacyWallTime = resolveWallTime(raw.wallTimeMs);
+    return { ...defaults, mode: raw.mode, ...(legacyWallTime ? { wallTimeMs: legacyWallTime } : {}) };
 }
 export function validateDepthDecision(value, predecessor) {
     if (!validateDecision(value))
@@ -36,8 +61,13 @@ export function validateDepthDecision(value, predecessor) {
         issues.push("Invalid planner timestamp");
     if (decision.level === 1 && (!decision.lowRisk || decision.riskFactors.length))
         issues.push("Focused requires explicit low-risk assessment and no consequential risks");
-    const effectiveMinimum = decision.level === 1 && decision.lowRisk && !decision.riskFactors.length ? 1 : minimum;
-    if (decision.minimumLevel !== effectiveMinimum || decision.level < effectiveMinimum)
+    // The minimum describes the risk floor, not the level the planner selected.
+    // A planner may choose extra preparation while recognizing that Focused is sufficient.
+    const effectiveMinimum = decision.lowRisk && !decision.riskFactors.length ? 1 : minimum;
+    // Older plans described Standard as the minimum when selecting it, even with
+    // low-risk evidence. Continue accepting those conservative recorded plans.
+    const legacyStandardMinimum = effectiveMinimum === 1 && decision.level >= 2 && decision.minimumLevel === 2;
+    if ((!legacyStandardMinimum && decision.minimumLevel !== effectiveMinimum) || decision.level < effectiveMinimum)
         issues.push(`Planner decision is below or misstates host minimum ${effectiveMinimum}`);
     if (decision.riskFactors.some(risk => !decision.minimumReasons.includes(risk.category)))
         issues.push("Minimum reasons must enumerate evidenced risk categories");

package/dist/qaRecovery.d.ts

@@ -86,6 +86,13 @@ export interface QaRecoveryPacketInput {
     }>;
     reportJson?: string;
 }
+/**
+ * Keeps an unresolved packet auditable without making a successor reread every
+ * failed attempt.  Sealed history remains in the packet and in its digest
+ * lineage; only the current review/source closure and this digest-indexed
+ * history manifest are required for recovery.
+ */
+export declare function canonicalizeQaRecoveryRequirements(packet: QaRecoveryPacket): QaRecoveryPacket;
 export declare function loadQaRecoveryPacket(directory: string): QaRecoveryPacket;
 export declare function inspectLegacyQaRecoveryPacket(directory: string): {
     directory: string;

package/dist/qaRecovery.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { chmodSync, closeSync, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, readdirSync, realpathSync, renameSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { parseQaFailureReport } from "rafi-spec";
+import { parseProviderContract, parseQaFailureReport, qaRecoveryAcknowledgementV1Schema } from "rafi-spec";
 import { calculateFrozenQaStateDigest, captureFrozenQaSource } from "./qaSnapshot.js";
 import { WorkflowDb } from "./workflowDb.js";
 export const QA_RECOVERY_ROOT = ".foreman/qa-report-recovery";
@@ -17,6 +17,69 @@ export class LegacyQaRecoveryPacketError extends Error {
         this.name = "LegacyQaRecoveryPacketError";
     }
 }
+/**
+ * Keeps an unresolved packet auditable without making a successor reread every
+ * failed attempt.  Sealed history remains in the packet and in its digest
+ * lineage; only the current review/source closure and this digest-indexed
+ * history manifest are required for recovery.
+ */
+export function canonicalizeQaRecoveryRequirements(packet) {
+    const loaded = loadQaRecoveryPacket(packet.directory);
+    if (loaded.manifest.packetDigest !== packet.manifest.packetDigest)
+        throw new Error("cannot canonicalize a stale QA recovery packet revision");
+    // Ordinary first-attempt packets stay byte-for-byte on their established
+    // publication path.  The bundle is introduced only once retry/turn history
+    // would otherwise make the next successor inspect an accumulating archive.
+    const hasBundle = loaded.manifest.resources.some((resource) => resource.path.startsWith("canonical-recovery-bundle/"));
+    const hasRetryHistory = loaded.manifest.resources.some((resource) => /^(?:reviews\/|turns\/|prompts\/|qa-responses\/|validation\/|recovery-history\/)/.test(resource.path));
+    if (!hasBundle && !hasRetryHistory)
+        return loaded;
+    const currentSourcePrefix = currentReviewedStatePrefix(loaded);
+    const currentReviewPrefix = `reviews/r${loaded.manifest.reviewAttempt}/context/`;
+    const currentTransition = `review-transitions/${loaded.manifest.reviewAttemptId}.json`;
+    const baseContext = new Set([
+        "ticket", "qa-review-prompt", "report-schema", "builder-result", "builder-response-history",
+        "original-host-prompt", "original-provider-prompt", "original-raw-response", "original-cleaned-response",
+        "original-validation", "tool-events", "continuity", "settings", "context-usage",
+        "uncertain-turn-instruction", "uncertain-turn-detail", "review-binding",
+    ]);
+    const isCurrent = (resource) => {
+        if (resource.path === "report.json")
+            return true;
+        if (resource.path.startsWith(`${currentSourcePrefix}/`) || resource.path.startsWith(currentReviewPrefix))
+            return true;
+        if (resource.path === currentTransition)
+            return true;
+        const context = /^context\/([^./]+)\.(?:json|txt)$/.exec(resource.path)?.[1];
+        return Boolean(context && baseContext.has(context));
+    };
+    const history = loaded.manifest.resources
+        .filter((resource) => !resource.path.startsWith("canonical-recovery-bundle/") && !isCurrent(resource))
+        .map(({ path, digest, bytes, mediaType, purpose, integrityPolicy }) => ({ path, digest, bytes, mediaType, purpose, integrityPolicy }));
+    const current = loaded.manifest.resources
+        .filter((resource) => !resource.path.startsWith("canonical-recovery-bundle/") && isCurrent(resource))
+        .map(({ path, digest, bytes, mediaType, purpose }) => ({ path, digest, bytes, mediaType, purpose }));
+    const bundleBytes = encodeValue({
+        version: 1,
+        purpose: "Bounded canonical QA recovery closure; all omitted records remain sealed packet history and are verified by the packet digest and revision lineage",
+        runId: loaded.manifest.runId, ticketId: loaded.manifest.ticketId,
+        reviewAttempt: loaded.manifest.reviewAttempt, reviewAttemptId: loaded.manifest.reviewAttemptId,
+        reviewedStateDigest: loaded.manifest.reviewedStateDigest,
+        currentRequiredResources: current,
+        retainedHistory: history,
+    }, false);
+    const priorBundle = loaded.manifest.resources.filter((resource) => resource.path.startsWith("canonical-recovery-bundle/")).at(-1);
+    const unchanged = priorBundle && priorBundle.digest === hash(bundleBytes)
+        && loaded.manifest.resources.every((resource) => resource.requiredForRecovery === (isCurrent(resource) || resource.path === priorBundle.path));
+    if (unchanged)
+        return loaded;
+    const bundle = storeSealed(loaded.directory, `canonical-recovery-bundle/r${loaded.manifest.revision + 1}.json`, bundleBytes, "Canonical current recovery closure and digest-indexed sealed history", "application/json", true);
+    const resources = loaded.manifest.resources
+        .map((resource) => ({ ...resource, requiredForRecovery: isCurrent(resource) }))
+        .concat(bundle)
+        .sort(resourceOrder);
+    return revise(loaded, { resources });
+}
 export function loadQaRecoveryPacket(directory) {
     const root = resolve(directory);
     const manifestPath = join(root, "manifest.json");
@@ -446,6 +509,15 @@ export function validateQaRecoveryAcknowledgement(text, packet, options = {}) {
     const errors = [];
     if (lines[0] !== expected)
         errors.push("missing or malformed exact recovery-packet acknowledgement");
+    const acknowledgement = /^RAFI_QA_RECOVERY_ACK packet="([a-f0-9]{64})" reviewed_state="([a-f0-9]{64})" required_resources_read="(all)"$/.exec(lines[0] ?? "");
+    if (acknowledgement) {
+        try {
+            parseProviderContract(qaRecoveryAcknowledgementV1Schema, { packet: acknowledgement[1], reviewed_state: acknowledgement[2], required_resources_read: acknowledgement[3] }, "RAFI_QA_RECOVERY_ACK");
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
     if (options.continuityAlreadyValidated) {
         if (lines.length !== 1)
             errors.push("recovery acknowledgement must not contain additional text");

package/dist/qaReview.js

@@ -1,9 +1,11 @@
 import { withGraphDerivedAccess } from "./graph/derived.js";
 import { dispatchWithGraphAccess } from "./graph/session.js";
 import { finalQaRoleInstructions, resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
-import { COVERAGE_INSTRUCTIONS, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
+import { COVERAGE_INSTRUCTIONS, bindCoverageHostFields, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
 import { contractDigest, renderVerificationContract } from "./qaVerificationContract.js";
 import { finalReviewContractContext } from "./qaContractDelivery.js";
+import { qaCommandOutputExcerptsAllowed, retainedQaCommandObservations } from "./qaReviewEvidence.js";
+import { qaHostGraphFact } from "./qaHostFacts.js";
 import { graphContext, parseGraphRequest, prepareGraphInstruction, sendGraphTurn } from "./graph/turn.js";
 import { BuildControlBoundary } from "./buildInterventions.js";
 import { formatRecoveryCommand } from "./recoveryGuidance.js";
@@ -229,7 +231,10 @@ async function runIsolatedQaOwned(opts) {
     const maxBuilderFixes = Math.min(opts.maxCycles, durableLimit);
     let automaticFixes = persistedQaFixCount(opts);
     let reviewAttempt = Math.max(opts.state.reviews, ...durableReviews.map((item) => item.reviewNumber), 0);
-    let remediationGeneration = Math.max(opts.state.remediationGeneration ?? 0, durableRemediationGeneration, ...durableReviews.map((item) => item.remediationGeneration), ...durableRemediations.map((item) => item.generation), 0);
+    // Remediation generations are scoped to a ticket head.  The surrounding
+    // build state is shared across tickets, so using its counter here can leak
+    // T-001's fixes into T-002 and make a valid review fail binding validation.
+    let remediationGeneration = Math.max(durableRemediationGeneration, ...durableReviews.map((item) => item.remediationGeneration), ...durableRemediations.map((item) => item.generation), 0);
     const resumedHeadDb = new WorkflowDb(opts.recovery.projectDir);
     resumedHeadDb.reconcileInstructionDeliveries(opts.recovery.runId, opts.ticket.id);
     opts.qaRemediationAuthorization ??= resumedHeadDb.consumeInstructionControls(opts.recovery.runId, opts.ticket.id, "attempts");
@@ -549,6 +554,10 @@ function deliverQaFailureOrLegacyFix(opts, request, causingAttemptId) {
             const reportDigest = request.reportDigest;
             if (!attempt)
                 throw new Error(`QA failure delivery is missing review attempt ${causingAttemptId}`);
+            const admission = headDb.assertAdmittedWork(opts.recovery.runId, opts.ticket.id);
+            const preparation = headDb.qaPreparationStore();
+            const contractHead = preparation.head(opts.recovery.runId, opts.ticket.id, admission.requirementsDigest);
+            const contract = contractHead.state === "ready" && contractHead.digest ? preparation.contract(contractHead.digest) : undefined;
             const input = {
                 projectDir: opts.recovery.projectDir,
                 runId: opts.recovery.runId,
@@ -560,6 +569,7 @@ function deliverQaFailureOrLegacyFix(opts, request, causingAttemptId) {
                 reviewNumber: attempt.reviewNumber,
                 reviewedSourceStateDigest: attempt.sourceDigest,
                 reviewBasisDigest: headDb.qaTicketHead(opts.recovery.runId, opts.ticket.id).reviewBasisDigest ?? "",
+                ...(contract ? { contractDigest: contract.contentDigest } : {}),
                 remediationGeneration: attempt.remediationGeneration,
                 latestBuilderResult: request.latestBuilderResult,
                 history: request.history,
@@ -980,7 +990,14 @@ async function oneReview(opts, identity) {
                 return pauseQaReview(opts, "invalid-pass-contract", `invalid QA pass response: ${contract.errors.join("; ")}`, reviewedSnapshot.frozenState);
             if (missingPrerequisites.length)
                 return pauseQaReview(opts, "verification-not-run", "Required verification remains not_run; prerequisite recovery and fresh QA required", reviewedSnapshot.frozenState);
-            const certificate = finishV2Pass(opts, qa, status.summary ?? "qa_pass");
+            let certificate;
+            try {
+                certificate = finishV2Pass(opts, qa, status.summary ?? "qa_pass");
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                return retryFreshQaReview(opts, "invalid-qa-coverage", `QA pass evidence was not parseable or complete: ${detail}`, reviewedSnapshot.frozenState);
+            }
             markQaRecoveryResolved(opts);
             durableReviewFinished = true;
             opts.evidence?.({ cycle, reviewAttempt: activeBinding.reviewNumber, remediationGeneration, attemptId: activeBinding.reviewAttemptId, outcome: "passed", detail: status.summary ?? "qa_pass", durationMs: Math.max(0, performance.now() - started) });
@@ -1034,7 +1051,14 @@ async function oneReview(opts, identity) {
                 if (contract.valid && contract.status === "qa_pass") {
                     if (missingPrerequisites.length)
                         return pauseQaReview(opts, "verification-not-run", "Required verification remains not_run; prerequisite recovery and fresh QA required", reviewedSnapshot.frozenState);
-                    const certificate = finishV2Pass(opts, qa, contract.fields.summary ?? "qa_pass");
+                    let certificate;
+                    try {
+                        certificate = finishV2Pass(opts, qa, contract.fields.summary ?? "qa_pass");
+                    }
+                    catch (error) {
+                        const detail = error instanceof Error ? error.message : String(error);
+                        return retryFreshQaReview(opts, "invalid-qa-coverage", `Recovered QA pass evidence was not parseable or complete: ${detail}`, reviewedSnapshot.frozenState);
+                    }
                     markQaRecoveryResolved(opts);
                     durableReviewFinished = true;
                     opts.evidence?.({ cycle, reviewAttempt: activeBinding.reviewNumber, remediationGeneration, attemptId: activeBinding.reviewAttemptId, outcome: "passed", detail: contract.fields.summary ?? "qa_pass", durationMs: Math.max(0, performance.now() - started) });
@@ -1577,7 +1601,7 @@ function validateBoundaryReceipt(receipt, packet, successorHandle) {
         receiptDb.close();
     }
     const byLabel = new Map(receipt.resources.map((resource) => [resource.label, resource]));
-    for (const expected of packet.manifest.resources) {
+    for (const expected of packet.manifest.resources.filter((resource) => resource.requiredForRecovery)) {
         const actual = byLabel.get(expected.path);
         if (!actual || actual.authoritative !== true || actual.digest !== expected.digest || actual.path !== expected.path || actual.purpose !== expected.purpose
             || actual.bytes !== expected.bytes || actual.mediaType !== expected.mediaType || actual.requiredForRecovery !== expected.requiredForRecovery) {
@@ -1635,7 +1659,9 @@ function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle,
                 return operation.kind === "builder-coverage" && operation.status === "confirmed" && intent.workId === opts.ticket.id && intent.contractDigest === contract.contentDigest && result?.binding?.sourceDigest === source.digest && result.coverageDigest
                     ? [{ operationId: operation.idempotencyKey, digest: result.coverageDigest, coverage: preparationStore.artifact(result.coverageDigest, "builder-coverage") }] : [];
             });
-            instruction += finalReviewContractContext(contract, preparationStore, reviewedSnapshotPath, builderClaims);
+            const commandObservations = retainedQaCommandObservations(opts.recovery.projectDir, opts.recovery.runId, opts.ticket.id, qaCommandOutputExcerptsAllowed(opts.ticket.id));
+            instruction += `\n${qaHostGraphFact(opts.recovery.projectDir)}\n`;
+            instruction += finalReviewContractContext(contract, preparationStore, reviewedSnapshotPath, builderClaims, commandObservations);
             instruction += `\n${renderVerificationContract(contract)}\n${COVERAGE_INSTRUCTIONS}\nCoverage binding: ${JSON.stringify({ phase: "qa", runId: opts.recovery.runId, workId: opts.ticket.id, contractDigest: contract.contentDigest, revision: contract.revision, sourceDigest: source.digest, attemptId: attempt.attemptId, sessionId: handle.sessionIdentity().sessionId })}`;
         }
         const originalInstruction = instruction;
@@ -1963,8 +1989,9 @@ function finishV2Pass(opts, adapter, detail) {
                 if (!contractHead.digest || contractHead.state !== "ready")
                     throw new Error("Final coverage requires the current ready contract");
                 const contract = db.qaPreparationStore().contract(contractHead.digest);
-                const coverage = parseContractCoverage(binding.lastResponse ?? "");
-                const errors = validateContractCoverage(contract, coverage, { phase: "qa", sourceDigest: binding.sourceStateDigest, inputBasisDigest: binding.reviewBasisDigest, attemptId: binding.reviewAttemptId, sessionId: binding.sessionRef.sessionId });
+                const coverageBinding = { phase: "qa", sourceDigest: binding.sourceStateDigest, inputBasisDigest: binding.reviewBasisDigest, attemptId: binding.reviewAttemptId, sessionId: binding.sessionRef.sessionId };
+                const coverage = bindCoverageHostFields(parseContractCoverage(binding.lastResponse ?? ""), contract, coverageBinding);
+                const errors = validateContractCoverage(contract, coverage, coverageBinding);
                 if (errors.length)
                     throw new Error(`Final QA coverage incomplete: ${errors.join("; ")}`);
                 const coverageDigest = db.qaPreparationStore().putArtifact("final-coverage", coverage);

package/dist/qaReviewEvidence.d.ts

@@ -0,0 +1,6 @@
+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. */
+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

@@ -0,0 +1,37 @@
+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;
+}
+/** Excerpts are opt-in; command text is never forwarded. */
+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)
+        .flatMap(span => {
+        const attributes = span.attributes ?? {};
+        const input = attributes.input;
+        const command = typeof input?.command === "string" ? input.command : "";
+        const kind = /\bqa-rehearse-rollback\b/.test(command) ? "rollback-rehearsal" : /\bnpm\s+test\b|\bnode\s+--test\b/.test(command) ? "test" : undefined;
+        if (!kind)
+            return [];
+        const outcome = ["completed", "failed", "cancelled", "timed_out"].includes(span.outcome ?? "") ? span.outcome : "unknown";
+        const exitCode = typeof attributes.exitCode === "number" && Number.isSafeInteger(attributes.exitCode) ? attributes.exitCode : undefined;
+        const outputDigest = typeof attributes.outputDigest === "string" && /^[a-f0-9]{64}$/.test(attributes.outputDigest) ? attributes.outputDigest : undefined;
+        const outputExcerpt = includeOutputExcerpts && typeof attributes.outputSummary === "string" ? attributes.outputSummary.slice(0, 1000) : undefined;
+        return [{ spanId: span.spanId, providerTurnId: span.providerTurnId, startedAt: span.startedAt, endedAt: span.endedAt, kind, outcome, exitCode, outputDigest, ...(outputExcerpt === undefined ? {} : { outputExcerpt, excerptMayBeTruncated: true }) }];
+    }).slice(-40);
+}
+export function retainedQaCommandObservations(projectDir, runId, workId, includeOutputExcerpts = false) {
+    try {
+        const reader = new ObservabilityReader(projectDir);
+        try {
+            return selectQaCommandObservations(reader.spans(runId), runId, workId, includeOutputExcerpts);
+        }
+        finally {
+            reader.close();
+        }
+    }
+    catch {
+        return [];
+    } // Diagnostics are optional; never prevent independent review.
+}

package/dist/qaRollbackRehearsal.d.ts

@@ -0,0 +1,2 @@
+/** Rehearse the current uncommitted product changes against HEAD, never the source Git index. */
+export declare function rehearseRollback(projectDir: string): string;

package/dist/qaRollbackRehearsal.js

@@ -0,0 +1,78 @@
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { captureFrozenQaSource, createDisposableQaSnapshot } from "./qaSnapshot.js";
+import { canonicalToolPath, isWithinProject } from "./permissions/shellForms.js";
+/** Rehearse the current uncommitted product changes against HEAD, never the source Git index. */
+export function rehearseRollback(projectDir) {
+    const unsafeGitEnvironment = Object.keys(process.env).filter(key => /^GIT_(?:DIR|WORK_TREE|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|COMMON_DIR|EXEC_PATH|TEMPLATE_DIR|SHALLOW_FILE|QUARANTINE_PATH|NAMESPACE)$/.test(key));
+    if (unsafeGitEnvironment.length)
+        throw new Error(`Rollback rehearsal cannot use Git repository overrides: ${unsafeGitEnvironment.join(", ")}`);
+    // Provider sandboxes may inject Git configuration. Never apply those
+    // settings to the independent clone, and restore the caller's environment.
+    const configKeys = Object.keys(process.env).filter(key => /^GIT_CONFIG(?:$|_)/.test(key));
+    const savedConfig = new Map(configKeys.map(key => [key, process.env[key]]));
+    for (const key of configKeys)
+        delete process.env[key];
+    process.env.GIT_CONFIG_NOSYSTEM = "1";
+    process.env.GIT_CONFIG_GLOBAL = "/dev/null";
+    try {
+        return rehearseWithCleanGitConfig(projectDir);
+    }
+    finally {
+        for (const key of Object.keys(process.env).filter(key => /^GIT_CONFIG(?:$|_)/.test(key)))
+            delete process.env[key];
+        for (const [key, value] of savedConfig)
+            if (value !== undefined)
+                process.env[key] = value;
+    }
+}
+function rehearseWithCleanGitConfig(projectDir) {
+    const topLevel = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: projectDir, encoding: "utf8", timeout: 30_000 });
+    if (topLevel.error || topLevel.status !== 0)
+        throw new Error("Rollback rehearsal requires a Git project");
+    if (canonicalToolPath(projectDir) !== canonicalToolPath(topLevel.stdout.trim()))
+        throw new Error("Run rollback rehearsal from the Git project root");
+    if (isWithinProject(projectDir, tmpdir()))
+        throw new Error("Rollback rehearsal requires a temporary directory outside the source project");
+    const snapshot = createDisposableQaSnapshot(projectDir, { projectDependencies: false });
+    const output = [];
+    const childEnv = { ...process.env, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_TERMINAL_PROMPT: "0", npm_config_offline: "true", npm_config_update_notifier: "false", npm_config_audit: "false", npm_config_fund: "false" };
+    // Inherited node:test context otherwise makes a nested test runner silently
+    // skip all test files while returning success.
+    delete childEnv.NODE_TEST_CONTEXT;
+    const run = (program, args) => {
+        const result = spawnSync(program, args, {
+            cwd: snapshot.path, encoding: "utf8", timeout: 300_000, maxBuffer: 8 * 1024 * 1024,
+            env: childEnv,
+        });
+        if (!args.includes("--stage"))
+            output.push(`$ ${[program, ...args].join(" ")}\n${result.stdout ?? ""}${result.stderr ?? ""}`);
+        if (result.error || result.status !== 0)
+            throw new Error(`Rollback rehearsal failed: ${program} ${args.join(" ")} (${result.error?.message ?? `exit ${result.status}`})\n${output.join("\n")}`);
+        return result.stdout;
+    };
+    try {
+        const source = snapshot.frozenState;
+        if (source.untracked.some(item => item.kind === "symlink"))
+            throw new Error("Rollback rehearsal cannot run with untracked symbolic links");
+        run("git", ["-c", "core.hooksPath=/dev/null", "add", "-A", "--", ".", ":(exclude).foreman/**", ":(exclude).rafi/**"]);
+        const entries = run("git", ["ls-files", "--stage", "-z"]);
+        if (entries.split("\0").some(entry => entry.startsWith("120000 ")))
+            throw new Error("Rollback rehearsal cannot run with tracked symbolic links");
+        const changed = run("git", ["diff", "--cached", "--name-only"]);
+        if (!changed.trim())
+            throw new Error("Rollback rehearsal requires uncommitted product changes relative to HEAD");
+        run("git", ["-c", "core.hooksPath=/dev/null", "-c", "user.name=Rafi rehearsal", "-c", "user.email=rafi-rehearsal@example.invalid", "-c", "commit.gpgsign=false", "commit", "-m", "Temporary rollback rehearsal"]);
+        run("npm", ["test"]);
+        run("git", ["-c", "core.hooksPath=/dev/null", "-c", "user.name=Rafi rehearsal", "-c", "user.email=rafi-rehearsal@example.invalid", "-c", "commit.gpgsign=false", "revert", "--no-edit", "HEAD"]);
+        run("npm", ["test"]);
+        run("git", ["diff", "--exit-code", source.head]);
+        const after = captureFrozenQaSource(projectDir);
+        if (after.digest !== source.digest)
+            throw new Error("Source project changed during rollback rehearsal; inspect it before continuing");
+        return `Rollback rehearsal passed in an independent temporary repository. Verification: npm test before revert exited 0; git revert exited 0; npm test after revert exited 0; git diff --exit-code against captured HEAD exited 0. Its tracked files match the captured HEAD baseline: ${source.head}. The synthetic commit contains all uncommitted product changes, not necessarily only one ticket. Source digest: ${source.digest}.\n${output.join("\n")}`;
+    }
+    finally {
+        snapshot.remove();
+    }
+}

package/dist/qaSnapshot.d.ts

@@ -80,7 +80,9 @@ export declare function captureFrozenQaSource(worktree: string): FrozenQaSourceS
 export declare function captureFrozenQaSourceAsync(worktree: string, progress?: QaSnapshotProgress): Promise<FrozenQaSourceState>;
 export declare function captureStableFrozenQaSource(read: (attempt: number, pass: 1 | 2) => FrozenQaSourceState, now?: Date): FrozenQaSourceState;
 export declare function captureStableFrozenQaSourceAsync(read: (attempt: number, pass: 1 | 2) => Promise<FrozenQaSourceState>, now?: Date): Promise<FrozenQaSourceState>;
-export declare function createDisposableQaSnapshot(builderWorktree: string): DisposableQaSnapshot;
+export declare function createDisposableQaSnapshot(builderWorktree: string, options?: {
+    projectDependencies?: boolean;
+}): DisposableQaSnapshot;
 export declare function createDisposableQaSnapshotAsync(builderWorktree: string, progress?: QaSnapshotProgress): Promise<AsyncDisposableQaSnapshot>;
 export declare function frozenQaStateManifest(state: FrozenQaSourceState): QaChangeManifest;
 export declare function changeManifest(worktree: string): QaChangeManifest;

package/dist/qaSnapshot.js

@@ -45,7 +45,7 @@ export async function captureStableFrozenQaSourceAsync(read, now = new Date()) {
     }
     throw new QaSourceInstabilityError(MAX_CAPTURE_ATTEMPTS);
 }
-export function createDisposableQaSnapshot(builderWorktree) {
+export function createDisposableQaSnapshot(builderWorktree, options = {}) {
     const source = resolve(builderWorktree);
     const root = gitText(source, ["rev-parse", "--show-toplevel"]);
     const frozenState = captureFrozenQaSource(source);
@@ -54,7 +54,8 @@ export function createDisposableQaSnapshot(builderWorktree) {
     cloneRepositorySync(root, review, frozenState.head);
     try {
         applyFrozenSync(review, frozenState);
-        projectDependencyTrees(root, review);
+        if (options.projectDependencies !== false)
+            projectDependencyTrees(root, review);
         mkdirSync(join(tempRoot, "scratch"), { mode: 0o700 });
         const manifest = manifestFromFrozen(frozenState);
         const snapshot = {

package/dist/qaVerificationContract.d.ts

@@ -8,8 +8,17 @@ export declare function draftDigest(candidate: QaContractCandidateV1): string;
 /** Allocate identities from meaning, replacing proposed agent IDs throughout the draft. */
 export declare function allocateStableCheckIds(candidate: QaContractCandidateV1): 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;
 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>;
+/** 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
+ * locations before parsing the provider draft. */
+export declare function normalizeSnapshotPaths(text: string): string;
 export declare function validateCandidate(candidate: QaContractCandidateV1, inventory: RequirementRef[], resolveEquivalent?: EquivalentAuthorityResolver): string[];
 export declare function validateAssessment(candidate: QaContractCandidateV1, assessment: QaSemanticAssessmentV1, authorSessionId: string): string[];
 export declare function assembleContract(candidate: QaContractCandidateV1, inventory: RequirementRef[], assessment: QaSemanticAssessmentV1, authorSessionId: string, challenge?: QaChallengeReceiptV1, resolveEquivalent?: EquivalentAuthorityResolver): QaVerificationContractV1;