ai-foreman 1.7.20 → 1.7.21

package/dist/qaFailureDelivery.js

@@ -1,3 +1,10 @@
+import { dispatchWithGraphAccess } from "./graph/session.js";
+import { currentGraphDerivedAccess, inheritGraphDerivedAccess, withGraphDerivedAccess } from "./graph/derived.js";
+import { collectBuilderContractCoverage, assertBuilderContractCoverage } from "./qaBuilderCoverage.js";
+import { queueGraphMaintenance, maintainGraphTask } from "./graph/boundary.js";
+import { ensureBuilderContract } from "./qaBuildGate.js";
+import { actualContractSession, assertContractReceipt } from "./qaContractDelivery.js";
+import { graphContext, parseGraphRequest, prepareGraphInstruction, sendGraphTurn } from "./graph/turn.js";
 import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { reportOccurrenceId } from "./qaHandbackMigration.js";
@@ -13,6 +20,16 @@ export class QaFailureDeliveryService {
         this.faults = faults;
     }
     async deliver(input, controller) {
+        const inherited = currentGraphDerivedAccess();
+        const grants = inherited ? [...(Array.isArray(inherited) ? inherited : [inherited])] : [];
+        try {
+            return await withGraphDerivedAccess(grants, () => this.deliverOwned(input, controller));
+        }
+        finally {
+            inheritGraphDerivedAccess(grants);
+        }
+    }
+    async deliverOwned(input, controller) {
         const began = performance.now();
         const handoffId = qaDigest("qa-failure-handoff", { runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, remediationGeneration: input.remediationGeneration + 1 });
         const operationId = qaDigest("builder-remediation-operation", { runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, handoffId, remediationGeneration: input.remediationGeneration + 1 });
@@ -105,7 +122,7 @@ export class QaFailureDeliveryService {
             return this.drift(input, "source-drift-before-delivery", preBoundary.digest);
         const findingRefs = createQaFindingRefs({ runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, rawFindingIds: input.report.findings.map(f => f.id) });
         const handoff = this.buildHandoff(input, preBoundary, findingRefs);
-        const instruction = renderQaFailureHandoff(handoff) + (input.operatorAnswer ? `\nAuthorized operator answer (${input.operatorAnswer.decisionId}): ${JSON.stringify(input.operatorAnswer.answer)}` : "");
+        let instruction = renderQaFailureHandoff(handoff) + (input.operatorAnswer ? `\nAuthorized operator answer (${input.operatorAnswer.decisionId}): ${JSON.stringify(input.operatorAnswer.answer)}` : "");
         enforceMandatoryPromptLimit(Buffer.from(instruction));
         const operationId = qaDigest("builder-remediation-operation", { runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, handoffId, remediationGeneration: input.remediationGeneration + 1 });
         const prepareDb = new WorkflowDb(input.projectDir);
@@ -136,6 +153,7 @@ export class QaFailureDeliveryService {
             builder = await phase("before-dispatch-readiness", () => controller.beforeTurn(builder, instruction, input.builderWorktree));
             controller.setAdapter?.(builder);
         }
+        instruction += "\n" + await ensureBuilderContract(input.projectDir, input.runId, input.ticket.id, input.builderWorktree, builder);
         const preDispatch = await phase("source-before-dispatch", () => captureFrozenQaSourceAsync(input.builderWorktree));
         if (preDispatch.digest !== input.reviewedSourceStateDigest)
             return this.drift(input, "source-drift-before-dispatch", preDispatch.digest, handoffId);
@@ -148,15 +166,27 @@ export class QaFailureDeliveryService {
         }
         // Byte counts are not token counts. This deliberately conservative bound also
         // reserves wrapper instructions, response and continuity against known capacity.
+        const graphDeliveryContext = graphContext(input.projectDir, input.builderWorktree, "remediation", instruction, { operationId: `graph-delivery:${operationId}`, logicalTaskId: operationId, sourceRef: preDispatch.digest, runId: input.runId, workId: input.ticket.id, qualifies: input.report.findings.some(f => f.locations.length > 1) });
+        let graphPrepared = await prepareGraphInstruction(instruction, graphDeliveryContext);
         const usage = await builder.contextUsage?.();
+        if (usage?.maximum && Buffer.byteLength(graphPrepared.instruction) + 16_384 > usage.maximum - usage.used)
+            graphPrepared = { instruction, bytes: 0 };
+        instruction = graphPrepared.instruction;
         if (usage?.maximum && Buffer.byteLength(instruction) + 16_384 > usage.maximum - usage.used)
             return { ok: false, outcome: "response-invalid", detail: "QA handback capacity error: mandatory requirements/findings and response reserve exceed available model context", handoffId, operationId };
         const db = new WorkflowDb(input.projectDir);
         let intent;
         let record;
+        let guidanceIds = [];
         try {
             intent = db.atomic(() => {
                 const head = validateReviewBinding(db, input);
+                const admission = db.assertAdmittedWork(input.runId, input.ticket.id);
+                if (db.qaPreparationStore().policy(input.runId)?.mode === "enforce")
+                    assertContractReceipt(db.qaPreparationStore(), input.runId, input.ticket.id, admission.requirementsDigest, actualContractSession(builder, input.builderWorktree, input.projectDir), builder);
+                const guidance = db.reserveGuidance(input.runId, input.ticket.id, "builder", operationId, preDispatch.digest, instruction);
+                instruction = guidance.text;
+                guidanceIds = guidance.ids;
                 const policy = db.autonomyPolicy(input.runId);
                 const maximum = Math.min(input.maxRemediationOperations ?? 3, policy?.rules["qa.nonconvergence"].max_attempts ?? policy?.limits.builderQaFixesPerTicket ?? 3);
                 db.reserveQaRemediation(input.runId, input.ticket.id, input.reviewAttemptId, operationId, maximum, input.authorizationId);
@@ -172,8 +202,40 @@ export class QaFailureDeliveryService {
             db.close();
         }
         this.faults.afterIntent?.();
-        let response = await phase("initial-work-and-validation", () => this.dispatch(input, builder, record, instruction));
-        let outcome = this.classify(response);
+        let response;
+        let graphSequence = 0;
+        const exchangeResult = await phase("initial-work-and-validation", () => sendGraphTurn(builder, instruction, graphDeliveryContext, { handback: true, logicalActionId: operationId }, async (prompt) => {
+            if (graphSequence > 0) {
+                const nextDb = new WorkflowDb(input.projectDir);
+                try {
+                    const head = nextDb.qaTicketHead(input.runId, input.ticket.id);
+                    const active = nextDb.qaRemediationAttempt(operationId);
+                    if (head.revision !== intent.expectedRevision || head.state !== "remediation-intended" || active?.status !== "started" || active.reviewAttemptId !== input.reviewAttemptId)
+                        throw new Error("Graph continuation lost its remediation authority");
+                    record = this.turnIntent(nextDb, operationId, occurrence, session, prompt, graphSequence, "graph-continuation");
+                }
+                finally {
+                    nextDb.close();
+                }
+            }
+            graphSequence++;
+            response = await this.dispatch(input, builder, record, prompt);
+            if (!response.turn)
+                return { text: response.detail ?? "Remediation dispatch uncertain", isError: true, costUsd: 0, numTurns: 0 };
+            if (response.record.validationErrors?.length)
+                return { ...response.turn, isError: true };
+            return response.turn;
+        }, { ...graphPrepared, instruction }));
+        const guidanceDb = new WorkflowDb(input.projectDir);
+        try {
+            guidanceDb.finishGuidance(guidanceIds, "builder", { submitted: response.record.status === "completed" && response.record.providerTurnId ? true : undefined, receipt: response.record.providerTurnId ? response.record : undefined });
+        }
+        finally {
+            guidanceDb.close();
+        }
+        let outcome = exchangeResult.isError ? "delivery-uncertain" : this.classify(response);
+        if (exchangeResult.isError)
+            response.detail = exchangeResult.text;
         if (outcome === "response-invalid" && response.record.sourceCapture === "captured") {
             const correction = [
                 "Builder QA remediation response correction only. Do not inspect files, run tools, edit source, or perform additional remediation.",
@@ -186,7 +248,7 @@ export class QaFailureDeliveryService {
             enforceMandatoryPromptLimit(Buffer.from(correction));
             const repairDb = new WorkflowDb(input.projectDir);
             try {
-                record = this.turnIntent(repairDb, operationId, occurrence, session, correction, 1);
+                record = this.turnIntent(repairDb, operationId, occurrence, session, correction, graphSequence, "response-repair");
             }
             finally {
                 repairDb.close();
@@ -195,6 +257,15 @@ export class QaFailureDeliveryService {
             response = await phase("response-repair-and-validation", () => this.dispatch(input, builder, record, correction, before));
             outcome = this.classify(response);
         }
+        if (outcome === "remediation-reported" && response.turn) {
+            try {
+                await collectBuilderContractCoverage(input.projectDir, input.runId, input.ticket.id, input.builderWorktree, builder, operationId, instruction, response.turn);
+            }
+            catch (error) {
+                outcome = "response-invalid";
+                response.detail = String(error);
+            }
+        }
         if (outcome === "remediation-reported" || outcome === "blocked" || outcome === "needs-input") {
             if (!response.turn?.continuityErrors?.length) {
                 try {
@@ -220,6 +291,8 @@ export class QaFailureDeliveryService {
             const summaryDigest = finishDb.putEvidence("qa", Buffer.from(response.contract?.report?.summary ?? detail));
             finishDb.atomic(() => {
                 this.faults.beforeOutcomeCommit?.();
+                if (outcome === "remediation-reported")
+                    assertBuilderContractCoverage(finishDb, input.runId, input.ticket.id, operationId, response.record.postSourceDigest);
                 finishDb.commitQaRemediationOutcome({ recoveryAttemptId: intent.recoveryId, remediationAttemptId: operationId, outcome: outcome === "remediation-reported" ? "succeeded" : outcome === "delivery-uncertain" ? "uncertain" : "failed", detail, responseDigest: response.record.rawResponseDigest, summaryDigest, expectedRevision: intent.expectedRevision,
                     ...(outcome === "remediation-reported" ? { receipt: { version: 3, operationId, runId: input.runId, ticketId: input.ticket.id, reportDigest: input.reportDigest, reportOccurrenceId: occurrence, turnRecordId: response.record.turnRecordId, sourceStateDigest: input.reviewedSourceStateDigest, requestDigest, responseDigest: response.record.rawResponseDigest, summaryDigest, providerTurnId: response.record.providerTurnId, completedAt: receipt.completedAt } } : {}) });
                 const state = outcome === "remediation-reported" ? "remediation-reported" : outcome === "blocked" || outcome === "needs-input" ? "builder-blocked" : outcome === "source-drift" ? "response-invalid" : outcome;
@@ -243,16 +316,33 @@ export class QaFailureDeliveryService {
         finally {
             finishDb.close();
         }
+        if (outcome === "remediation-reported" && response.turn) {
+            try {
+                queueGraphMaintenance(input.projectDir, input.builderWorktree, operationId, response.turn.text, response.record.postSourceDigest !== preDispatch.digest);
+                await maintainGraphTask(input.projectDir, input.builderWorktree, operationId, builder);
+            }
+            catch (error) {
+                console.error(`rafi graph: optional maintenance failed after accepted handback: ${String(error)}`);
+            }
+        }
         return { ok: outcome === "remediation-reported", outcome, detail, response: response.turn?.text, summary: response.contract?.report?.summary, providerTurnId: response.record.providerTurnId, handoffId, operationId, turnRecordId: response.record.turnRecordId };
     }
-    turnIntent(db, operationId, occurrence, session, prompt, index) {
-        const turn = { version: 3, turnRecordId: qaDigest("qa-delivery-turn-v3", { operationId, index }), operationId, reportOccurrenceId: occurrence, turnIndex: index, kind: index ? "response-repair" : "remediation", ...(index ? { parentTurnRecordId: qaDigest("qa-delivery-turn-v3", { operationId, index: 0 }) } : {}), status: "intended", intendedSession: session, hostInstructionDigest: db.putEvidence("handoff", Buffer.from(prompt)), hostInstructionBytes: Buffer.byteLength(prompt), providerInstructionAvailability: "unavailable", sourceCapture: "pending", startedAt: new Date().toISOString() };
+    turnIntent(db, operationId, occurrence, session, prompt, index, kind = index ? "response-repair" : "remediation") {
+        const turn = { version: 4, turnRecordId: qaDigest("qa-delivery-turn-v4", { operationId, index }), operationId, reportOccurrenceId: occurrence, turnIndex: index, kind, ...(index ? { parentTurnRecordId: qaDigest("qa-delivery-turn-v4", { operationId, index: 0 }) } : {}), status: "intended", intendedSession: session, hostInstructionDigest: db.putEvidence("handoff", Buffer.from(prompt)), hostInstructionBytes: Buffer.byteLength(prompt), providerInstructionAvailability: "unavailable", sourceCapture: "pending", startedAt: new Date().toISOString() };
         if (db.qaDeliveryTurns(operationId).some(t => t.turnIndex === index))
             throw new Error("Delivery turn already intended; reconcile without redispatch");
         db.recordQaDeliveryTurn(turn);
         return turn;
     }
     async dispatch(input, builder, record, prompt, responseOnlySourceDigest) {
+        let result;
+        await dispatchWithGraphAccess(input.projectDir, builder, prompt, undefined, async () => {
+            result = await this.dispatchOwned(input, builder, record, prompt, responseOnlySourceDigest);
+            return result.turn ?? { text: result.detail ?? "Dispatch failed", isError: true, costUsd: 0, numTurns: 0 };
+        });
+        return result;
+    }
+    async dispatchOwned(input, builder, record, prompt, responseOnlySourceDigest) {
         const events = [];
         let unsubscribe;
         let turn, error;
@@ -263,10 +353,10 @@ export class QaFailureDeliveryService {
             if (stableBuilderSessionIdentity(validateBuilderSession(builder, input)) !== stableBuilderSessionIdentity(record.intendedSession))
                 throw new Error("Builder session identity changed before dispatch");
             unsubscribe = builder.observeEvents(event => { events.push(event); });
-            turn = await withActivityPhase(record.turnIndex ? "correcting Builder QA remediation response" : "delivering source-bound QA failure handoff to Builder", () => builder.sendTurn(prompt, { handback: true, responseOnly: Boolean(record.turnIndex) }));
+            turn = await withActivityPhase(record.kind === "response-repair" ? "correcting Builder QA remediation response" : "delivering source-bound QA failure handoff to Builder", () => builder.sendTurn(prompt, { handback: true, responseOnly: record.kind === "response-repair" }));
         }
         catch (caught) {
-            error = `Builder ${record.turnIndex ? "correction " : ""}dispatch uncertain: ${String(caught)}`;
+            error = `Builder ${record.kind === "response-repair" ? "correction " : ""}dispatch uncertain: ${String(caught)}`;
         }
         finally {
             unsubscribe?.();
@@ -332,13 +422,20 @@ export class QaFailureDeliveryService {
                 errors.push(`Post-dispatch source capture failed: ${String(caught)}`);
             }
             record.captureElapsedMs = performance.now() - captureStart;
-            if (record.turnIndex) {
+            if (record.kind === "response-repair") {
                 record.responseOnlyViolations = record.toolCount ? ["Builder used tools during response correction"] : [];
                 record.responseOnlySourceChanged = Boolean(record.postSourceDigest && record.postSourceDigest !== responseOnlySourceDigest);
                 if (record.responseOnlySourceChanged)
                     record.responseOnlyViolations.push(`source changed during response correction (${responseOnlySourceDigest} -> ${record.postSourceDigest})`);
             }
-            const contract = turn ? parseBuilderQaRemediationContract(turn.cleanedResponse ?? turn.text, { handoffId: qaDigest("qa-failure-handoff", { runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, remediationGeneration: input.remediationGeneration + 1 }), findings: createQaFindingRefs({ runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, rawFindingIds: input.report.findings.map(f => f.id) }) }) : undefined;
+            let graphRequest = false;
+            try {
+                graphRequest = Boolean(turn && parseGraphRequest(turn.cleanedResponse ?? turn.text));
+            }
+            catch (caught) {
+                errors.push(String(caught));
+            }
+            const contract = turn && !graphRequest ? parseBuilderQaRemediationContract(turn.cleanedResponse ?? turn.text, { handoffId: qaDigest("qa-failure-handoff", { runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, remediationGeneration: input.remediationGeneration + 1 }), findings: createQaFindingRefs({ runId: input.runId, ticketId: input.ticket.id, reviewAttemptId: input.reviewAttemptId, reportDigest: input.reportDigest, rawFindingIds: input.report.findings.map(f => f.id) }) }) : undefined;
             record.parserErrors = [...(contract?.errors ?? []), ...(turn?.continuityErrors ?? [])];
             record.validationErrors = errors;
             if (contract?.report)

package/dist/qaHandbackMigration.d.ts

@@ -1,5 +1,5 @@
 import type Database from "better-sqlite3";
-export declare const HANDBACK_SCHEMA_VERSION = 3;
+export declare const HANDBACK_SCHEMA_VERSION = 4;
 /** Review numbers are durably unique within a run/ticket, including before V3. */
 export declare function reportOccurrenceId(runId: string, ticketId: string, reviewNumber: number): string;
 export declare function registerHandbackWriter(db: Database.Database): void;

package/dist/qaHandbackMigration.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { hostname } from "node:os";
 import { qaDigest } from "./qaProtocolV2.js";
-export const HANDBACK_SCHEMA_VERSION = 3;
+export const HANDBACK_SCHEMA_VERSION = 4;
 const migration = "003_qa_report_occurrences_and_turns";
 /** Review numbers are durably unique within a run/ticket, including before V3. */
 export function reportOccurrenceId(runId, ticketId, reviewNumber) {
@@ -11,7 +11,7 @@ export function registerHandbackWriter(db) {
     const version = db.pragma("user_version", { simple: true });
     if (version > HANDBACK_SCHEMA_VERSION)
         throw new Error(`Recovery database schema ${version} requires a newer Rafi writer`);
-    db.function("rafi_writer_protocol", () => HANDBACK_SCHEMA_VERSION);
+    db.function("rafi_writer_protocol", () => version >= 4 ? 4 : 3);
 }
 /** No provider work or file I/O occurs inside this migration transaction. */
 export function migrateQaHandback(db, faults) {
@@ -138,7 +138,7 @@ export function migrateQaHandback(db, faults) {
                 for (const action of ["INSERT", "UPDATE", "DELETE"]) {
                     db.exec(`CREATE TRIGGER handback_v3_${name}_${action} BEFORE ${action} ON "${name}" BEGIN SELECT CASE WHEN rafi_writer_protocol() != 3 THEN RAISE(ABORT,'incompatible Rafi writer') END; END;`);
                 }
-            db.pragma(`user_version = ${HANDBACK_SCHEMA_VERSION}`);
+            db.pragma("user_version = 3");
         }).immediate();
     }
     finally {

package/dist/qaPreparation.d.ts

@@ -0,0 +1,26 @@
+import type { QaContractCandidateV1, RequirementRef, QaVerificationContractV1 } from "rafi-spec";
+import type { QaPreparationStore, LogicalPreparationBudget } from "./qaPreparationStore.js";
+export interface PreparationProviderResult {
+    operationId?: string;
+    text: string;
+    sessionId: string;
+    graphReceiptRefs?: string[];
+    usage?: Partial<LogicalPreparationBudget["usage"]>;
+}
+export interface PreparationDependencies {
+    store: QaPreparationStore;
+    now(): number;
+    /** Each dispatch is a fresh, confined conversation, with a persisted reservation. */
+    dispatch(phase: "planner" | "prepare" | "assess" | "challenge" | "repair", instruction: string, operationId: string, remainingMs: number): Promise<PreparationProviderResult>;
+    inputsCurrent(candidate: QaContractCandidateV1): boolean;
+    normalizeDraft?(draft: QaContractCandidateV1, response: PreparationProviderResult): QaContractCandidateV1;
+}
+export type PreparationOutcome = {
+    status: "ready";
+    contract: QaVerificationContractV1;
+} | {
+    status: "incomplete" | "blocked" | "uncertain";
+    detail: string;
+    nextAction: string;
+};
+export declare function prepareVerificationContract(initial: QaContractCandidateV1, inventory: RequirementRef[], deps: PreparationDependencies): Promise<PreparationOutcome>;

package/dist/qaPreparation.js

@@ -0,0 +1,150 @@
+import { QA_RISK_MINIMUMS, qaContractCandidateV1Schema, qaSemanticAssessmentV1Schema, qaChallengeReceiptV1Schema, qaPreparationDepthDecisionV1Schema } from "rafi-spec";
+import { randomUUID } from "node:crypto";
+import { depthObligations, validateDepthDecision } from "./qaPreparationPolicy.js";
+import { canonicalContractJson, assembleContract, draftDigest, inventoryDigest, parsePreparationArtifact, validateCandidate } from "./qaVerificationContract.js";
+export async function prepareVerificationContract(initial, inventory, deps) {
+    const store = deps.store;
+    const head = store.head(initial.runId, initial.workId, initial.admissionDigest);
+    if (head.state === "ready" && head.digest) {
+        const contract = store.contract(head.digest);
+        if (deps.inputsCurrent(contract))
+            return { status: "ready", contract };
+        store.setState(initial.runId, initial.workId, initial.admissionDigest, "amendment-required", "Relevant authoritative inputs changed", head.generation);
+        return { status: "blocked", detail: "Contract amendment required", nextAction: "Reconcile changed inputs and retained evidence before publishing a successor" };
+    }
+    const decisionIssues = initial.depthDecision ? validateDepthDecision(initial.depthDecision) : ["Missing planner depth assessment"];
+    // Missing decisions begin with Standard's ceiling, never the synthetic Low placeholder.
+    const budget = store.ensureBudget(initial.runId, initial.workId, initial.admissionDigest, decisionIssues.length ? 2 : initial.depthDecision.level, deps.now());
+    const unresolvedDispatch = budget.reservations.find(item => !item.resultDigest);
+    if (unresolvedDispatch)
+        return { status: "uncertain", detail: head.detail ?? `Uncertain preparation dispatch ${unresolvedDispatch.operationId}`, nextAction: "Reconcile retained provider receipt before retrying" };
+    const retained = store.progress(budget, "draft");
+    const priorAssessment = store.progress(budget, "assessment");
+    const priorChallenge = store.progress(budget, "challenge");
+    const targetedConcerns = [...(priorAssessment?.concerns ?? []), ...(priorChallenge?.concerns ?? []), ...(priorChallenge?.approachConcerns ?? [])].filter(concern => concern.material);
+    const retainedDepth = store.progress(budget, "depth-decision");
+    store.retainProgress(budget, "inventory", inventory);
+    let candidate = retained ? structuredClone(retained.candidate) : structuredClone(initial);
+    if (retainedDepth)
+        candidate.depthDecision = retainedDepth;
+    if (retained && canonicalContractJson(candidate.inputs) !== canonicalContractJson(initial.inputs))
+        return { status: "blocked", detail: "Retained draft inputs changed", nextAction: "Reconcile authoritative input changes" };
+    const run = async (phase, kind, instruction, resultId) => {
+        const operationId = `qa-preparation:${randomUUID()}`;
+        store.setState(initial.runId, initial.workId, initial.admissionDigest, ["assess", "challenge"].includes(phase) ? "validating" : "preparing", `Read-only ${phase} operation intended`, store.head(initial.runId, initial.workId, initial.admissionDigest).generation);
+        store.reserve(budget, operationId, kind, { phase, instruction, inputDigest: inventoryDigest(inventory) }, deps.now(), resultId);
+        const current = store.budget(initial.runId, initial.workId, initial.admissionDigest);
+        const dispatchedAt = deps.now();
+        const result = await deps.dispatch(phase, instruction, operationId, Math.max(1, current.deadlineMs - deps.now()));
+        store.retainResult(budget, operationId, result, result.usage);
+        store.metric(initial.runId, initial.workId, initial.admissionDigest, `metric:preparation-operation:${operationId}`, kind === "repair" ? "format-repair" : "phase-observation", { phase: phase === "planner" ? "planning" : phase === "challenge" ? "challenge" : phase === "repair" ? "repair" : "preparation", durationMs: Math.max(0, deps.now() - dispatchedAt), costUsd: result.usage?.costUsd ?? null, inputTokens: result.usage?.inputTokens ?? null, outputTokens: result.usage?.outputTokens ?? null });
+        if (deps.now() >= current.deadlineMs)
+            throw new Error("Preparation deadline expired; partial evidence retained");
+        return { ...result, operationId };
+    };
+    const parsed = async (result, tag) => {
+        let response = result;
+        for (let repair = 0;; repair++) {
+            try {
+                return parsePreparationArtifact(response.text, tag);
+            }
+            catch (error) {
+                if (repair >= 2)
+                    throw error;
+                response = await run("repair", "repair", `Format-only repair; no investigation, tools, or scope changes. Return the exact retained result as one ${tag}_START JSON ${tag}_END envelope.\nRetained response:\n${response.text}`, result.operationId ?? result.sessionId);
+            }
+        }
+    };
+    try {
+        if (!retained && !retainedDepth && decisionIssues.length) {
+            const response = await run("planner", "planning", `Read-only depth assessment of admitted scope. Select Standard or higher unless explicit Focused low-risk evidence is established. Return RAFI_QA_DEPTH_START/END with QaPreparationDepthDecisionV1. Schema: ${JSON.stringify(qaPreparationDepthDecisionV1Schema)}. Policy qa-preparation-v1. Host minimums: interactions/compatibility/state/external dependencies=3; authorization/security/data/migration/concurrency/recovery/deployment=4; unresolved architectural uncertainty=5.\n${JSON.stringify(initial)}`);
+            candidate.depthDecision = await parsed(response, "RAFI_QA_DEPTH");
+            candidate.depthDecision.plannerOperationId = response.operationId;
+            candidate.depthDecision.plannerIdentity = response.sessionId;
+            const issues = validateDepthDecision(candidate.depthDecision);
+            if (issues.length)
+                throw new Error(`depth-decision-incomplete: ${issues.join("; ")}`);
+            store.reviseDepth(budget, candidate.depthDecision);
+        }
+        else
+            store.reviseDepth(budget, candidate.depthDecision);
+        store.retainProgress(budget, "depth-decision", candidate.depthDecision);
+        let authorSessionId = retained?.authorSessionId ?? "";
+        for (let pass = 0; pass < (candidate.depthDecision.level <= 2 ? 2 : 3) && (!retained || targetedConcerns.length > 0 || validateCandidate(candidate, inventory, store.equivalentResolver()).length > 0); pass++) {
+            const response = await run("prepare", "investigation", `QA preparation only. Inspect relevant source/tests; do not implement, install dependencies, or expand admitted product scope. Return RAFI_QA_CANDIDATE_START/END with a complete QaContractCandidateV1. Schema: ${JSON.stringify(qaContractCandidateV1Schema)}. Preserve host identity, inputs, depth and every authoritative inventory requirement exactly. Supply concrete check methods/evidence, complete coverage and cited investigation for each obligation. No disposition or waiver can be agent-authored. If risks exceed selected depth, return a separate RAFI_QA_ESCALATION_START/END JSON block {"rationale":"...","riskFactors":[{"category":"...","rationale":"...","references":["..."]}]}; do not change the depth yourself.\nPreviously retained independent concerns requiring targeted investigation and concrete resolution: ${JSON.stringify(targetedConcerns)}\nRequired obligations: ${depthObligations(candidate.depthDecision.level).join(", ")}\nAuthoritative candidate/input inventory:\n${JSON.stringify(candidate)}`);
+            const draft = await parsed(response, "RAFI_QA_CANDIDATE");
+            if (draft.runId !== candidate.runId || draft.workId !== candidate.workId || draft.admissionDigest !== candidate.admissionDigest || draft.contractId !== candidate.contractId || draft.revision !== candidate.revision || draft.predecessorDigest !== candidate.predecessorDigest || draft.createdAt !== candidate.createdAt || canonicalContractJson(draft.depthDecision) !== canonicalContractJson(candidate.depthDecision) || canonicalContractJson(draft.inputs) !== canonicalContractJson(candidate.inputs))
+                throw new Error("Preparation changed host-owned identity/depth/input authority");
+            candidate = deps.normalizeDraft ? deps.normalizeDraft(draft, response) : draft;
+            authorSessionId = response.sessionId;
+            for (const evidence of candidate.preparationEvidence) {
+                evidence.operationId = response.operationId;
+                evidence.sessionId = response.sessionId;
+            }
+            if (response.text.includes("RAFI_QA_ESCALATION_START")) {
+                const request = parsePreparationArtifact(response.text, "RAFI_QA_ESCALATION");
+                if (!request.rationale?.trim() || !request.riskFactors?.length || request.riskFactors.some(risk => !(risk.category in QA_RISK_MINIMUMS) || !risk.references?.length))
+                    throw new Error("Incomplete risk escalation evidence");
+                const minimum = Math.max(candidate.depthDecision.level, ...request.riskFactors.map(risk => QA_RISK_MINIMUMS[risk.category]));
+                const revision = await run("planner", "escalation", `Revise only the QA depth for this admitted scope. Do not expand product scope. Host minimum ${minimum}; keep predecessorDecisionId ${candidate.depthDecision.decisionId}. Return RAFI_QA_DEPTH_START/END following ${JSON.stringify(qaPreparationDepthDecisionV1Schema)}. Previous decision: ${JSON.stringify(candidate.depthDecision)}; cited risk evidence: ${JSON.stringify(request)}`);
+                const decision = await parsed(revision, "RAFI_QA_DEPTH");
+                decision.plannerIdentity = revision.sessionId;
+                decision.plannerOperationId = revision.operationId;
+                const errors = validateDepthDecision(decision, candidate.depthDecision);
+                if (decision.level < minimum || request.riskFactors.some(risk => !decision.riskFactors.some(actual => actual.category === risk.category)))
+                    errors.push("Planner revision does not address evidenced risk minimum");
+                if (errors.length)
+                    throw new Error(`depth-decision-incomplete: ${errors.join("; ")}`);
+                candidate.depthDecision = decision;
+                store.reviseDepth(budget, decision);
+                store.retainProgress(budget, "depth-decision", decision);
+                continue;
+            }
+            const structural = validateCandidate(candidate, inventory, store.equivalentResolver());
+            if (!structural.length)
+                break;
+            candidate.unresolved.push({ reason: structural.join("; "), requirementIds: [], checkIds: [], material: true, owner: "qa", nextAction: "Targeted investigation to resolve contract validation gaps" });
+        }
+        store.retainProgress(budget, "draft", { candidate, authorSessionId });
+        const structural = validateCandidate(candidate, inventory, store.equivalentResolver());
+        if (structural.length)
+            throw new Error(`Contract incomplete: ${structural.join("; ")}`);
+        const binding = { draftPayloadDigest: draftDigest(candidate), inventoryDigest: inventoryDigest(candidate.requirements), policyVersion: candidate.depthDecision.policyVersion, authorSessionId };
+        const retainedAssessment = store.progress(budget, "assessment");
+        const assessmentResponse = retainedAssessment?.draftPayloadDigest === draftDigest(candidate) ? undefined : await run("assess", "assessment", `Independent semantic assessment in a fresh conversation. Assess each original requirement and selected-depth obligation; identify omissions, conflicts, practical verification gaps, accidental scope, and unsupported dispositions. Return RAFI_QA_ASSESSMENT_START/END with QaSemanticAssessmentV1 (schema: ${JSON.stringify(qaSemanticAssessmentV1Schema)}) and specific material concerns (empty only when resolved). Bind exactly ${JSON.stringify(binding)}.\nPrior independent concerns requiring concrete resolution evidence: ${JSON.stringify(targetedConcerns)}\nOriginal inventory:\n${JSON.stringify(inventory)}\nDraft:\n${JSON.stringify(candidate)}`);
+        const assessment = assessmentResponse ? await parsed(assessmentResponse, "RAFI_QA_ASSESSMENT") : retainedAssessment;
+        if (assessmentResponse) {
+            assessment.sessionId = assessmentResponse.sessionId;
+            assessment.operationId = assessmentResponse.operationId;
+        }
+        store.retainProgress(budget, "assessment", assessment);
+        let challenge = store.progress(budget, "challenge");
+        if (challenge?.draftPayloadDigest !== draftDigest(candidate))
+            challenge = undefined;
+        if (candidate.depthDecision.level === 5 && !challenge) {
+            const response = await run("challenge", "challenge", `Independent approach challenge, fresh assessor conversation. Planning only. Return RAFI_QA_CHALLENGE_START/END with QaChallengeReceiptV1 (schema: ${JSON.stringify(qaChallengeReceiptV1Schema)}): independently critique the author's retained approach-proposal evidence (do not author a replacement), independent contract conclusions and separate approachConcerns for scope, invariants, failure-boundaries, verification. Unresolved material concerns prevent readiness. Binding: ${JSON.stringify(binding)}. Previously retained concerns requiring concrete resolution: ${JSON.stringify(targetedConcerns)}.\n${JSON.stringify(candidate)}`);
+            challenge = await parsed(response, "RAFI_QA_CHALLENGE");
+            challenge.sessionId = response.sessionId;
+            challenge.operationId = response.operationId;
+            store.retainProgress(budget, "challenge", challenge);
+        }
+        const contract = assembleContract(candidate, inventory, assessment, authorSessionId, challenge, store.equivalentResolver());
+        store.putArtifact("semantic-assessment", assessment);
+        if (challenge)
+            store.putArtifact("approach-challenge", challenge);
+        if (!deps.inputsCurrent(candidate))
+            throw new Error("Authoritative preparation inputs changed before publication");
+        store.publish(contract, store.head(initial.runId, initial.workId, initial.admissionDigest).generation, deps.now());
+        store.event(initial.runId, initial.workId, `prepared:${contract.contentDigest}`, "preparation-ready", { contractDigest: contract.contentDigest, level: contract.depthDecision.level });
+        return { status: "ready", contract };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const current = store.budget(initial.runId, initial.workId, initial.admissionDigest);
+        const status = current.reservations.some(reservation => !reservation.resultDigest) ? "uncertain" : "incomplete";
+        store.setState(initial.runId, initial.workId, initial.admissionDigest, status, detail, store.head(initial.runId, initial.workId, initial.admissionDigest).generation);
+        store.metric(initial.runId, initial.workId, initial.admissionDigest, `metric:preparation-failure:${current.id}:${current.reservations.length}`, "preparation-failure", { status: "blocked" });
+        store.event(initial.runId, initial.workId, `preparation-failure:${current.id}:${current.reservations.length}`, "preparation-failure", { status, detail });
+        return { status, detail, nextAction: status === "uncertain" ? "Reconcile retained provider dispatch; do not replay uncertain work" : "Resolve remaining concerns or record authorized operational extension, then retry" };
+    }
+}

package/dist/qaPreparationInputs.d.ts

@@ -0,0 +1,8 @@
+import type { ContractInputRef, RequirementRef, StructuredPlanV1 } from "rafi-spec";
+import type { TicketDef } from "./tickets/ticketSchema.js";
+/** Resolve the admitted slice's exact approved plan revision, never a newer latest file. */
+export declare function admittedPlanInput(projectDir: string, ticket: TicketDef): {
+    input: ContractInputRef;
+    plan: StructuredPlanV1;
+    requirements: RequirementRef[];
+} | undefined;

package/dist/qaPreparationInputs.js

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loadRafiConfigObject } from "./tickets/setupConfig.js";
+import { canonicalJson } from "./qaProtocolV2.js";
+import { createHash } from "node:crypto";
+import { contractDigest } from "./qaVerificationContract.js";
+/** Resolve the admitted slice's exact approved plan revision, never a newer latest file. */
+export function admittedPlanInput(projectDir, ticket) {
+    if (!ticket.plan_ref)
+        return undefined;
+    const config = loadRafiConfigObject(projectDir);
+    const docsRoot = config?.docs?.root ?? "docs";
+    if (docsRoot.startsWith("/") || docsRoot.split(/[\\/]/).includes(".."))
+        throw new Error("Unsafe approved-plan document root");
+    const history = join(projectDir, docsRoot, "rafi-plans");
+    const files = [join(projectDir, docsRoot, "rafi-plan.json"), ...(existsSync(history) ? readdirSync(history).filter(name => name.endsWith(".json")).sort().reverse().slice(0, 1000).map(name => join(history, name)) : [])];
+    for (const path of files) {
+        if (!existsSync(path))
+            continue;
+        let plan;
+        try {
+            plan = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (plan.plan_id !== ticket.plan_ref.plan_id || plan.revision !== ticket.plan_ref.revision)
+            continue;
+        if (plan.content_digest !== createHash("sha256").update(canonicalJson({ ...plan, content_digest: "" })).digest("hex"))
+            throw new Error("Corrupt admitted approved-plan revision");
+        const slice = plan.slices.find(row => row.slice_ref === ticket.plan_ref.slice_ref);
+        if (!slice)
+            throw new Error("Admitted plan slice is absent from its exact approved revision");
+        const input = { id: "approved-plan", kind: "plan", reference: path, digest: plan.content_digest, authority: "approved-scope", revision: String(plan.revision), availability: "available" };
+        const requirements = [];
+        for (const [field, entries, location] of [["acceptance_criteria", plan.acceptance_criteria, ""], ["test_plan", plan.test_plan, ""], ["acceptance", slice.acceptance, `slices.${slice.slice_ref}.`], ["required_tests", slice.required_tests, `slices.${slice.slice_ref}.`]]) {
+            const occurrences = new Map();
+            entries.forEach((statement, index) => {
+                const fingerprint = contractDigest("plan-requirement", { field, statement }), occurrence = occurrences.get(fingerprint) ?? 0;
+                occurrences.set(fingerprint, occurrence + 1);
+                requirements.push({ id: `req-plan-${fingerprint.slice(0, 24)}-${occurrence}`, inputRef: input.id, locator: `${location}${field}[${index}]`, statement, digest: contractDigest("statement", statement), obligation: "mandatory", origin: "explicit", authority: "approved" });
+            });
+        }
+        return { input, plan, requirements };
+    }
+    throw new Error("Exact admitted approved-plan revision unavailable; restore its immutable artifact before preparation");
+}