ai-foreman 1.7.28 → 1.7.29

package/dist/qaEffectiveConfig.js

@@ -6,7 +6,12 @@ import { loadTicketSetupConfigWithDefaults, loadRafiConfigObject } from "./ticke
 import { resolveQaPreparationConfig } from "./qaPreparationPolicy.js";
 import { contractDigest } from "./qaVerificationContract.js";
 export const FINAL_QA_ROLE_SUFFIX = "You are an independent QA reviewer. Do not edit source, tickets, configuration, or project documentation. You may run tests and create only harmless ignored caches or coverage output.";
-export function finalQaRoleInstructions(rules) { return `${rules}\n\n${FINAL_QA_ROLE_SUFFIX}`; }
+export const QA_COMMAND_DISCIPLINE = [
+    "QA command discipline: issue one shell command per Bash call. Prefer the Read tool for source inspection and the configured project test command for verification.",
+    "Do not use shell sequencing or scaffolding such as ;, ||, redirects, command substitution, echo exit markers, temporary baseline copies, cp, cmp, or mkdir. Do not reconstruct or compare preimplementation files; Rafi owns baseline, path-scope, unchanged-file, and byte-identity comparisons.",
+    "If a command is denied by policy, do not retry the same denied command or wrap it in another compound command. Use a permitted equivalent that tests the same product behavior and record any limitation truthfully.",
+].join(" ");
+export function finalQaRoleInstructions(rules) { return `${rules}\n\n${QA_COMMAND_DISCIPLINE}\n\n${FINAL_QA_ROLE_SUFFIX}`; }
 export function loadQaPreparationPolicy(projectDir) {
     const config = loadRafiConfigObject(projectDir);
     return resolveQaPreparationConfig(config?.qa_preparation, config?.qa_preparation_shadow === true, config?.qa_preparation_wall_time_ms);

package/dist/qaPreparation.js

@@ -44,12 +44,26 @@ export function normalizeExpectedFutureAssessment(assessment, candidate) {
     const copy = structuredClone(assessment);
     const checks = new Map(candidate.checks.map(check => [check.id, check]));
     copy.concerns = copy.concerns.map(concern => {
+        // A provider can report a stale check identity copied into descriptive
+        // prose from an earlier draft.  The host has already validated the
+        // structured check/coverage/dependency references; when the assessor also
+        // says the referenced acceptance item is already covered, this is a
+        // non-material labeling defect rather than an unresolved contract gap.
+        // Keep the concern in the retained assessment, but do not block Builder.
+        const staleCoveredReference = /not in the declared check IDs or its dependsOnChecks/i.test(concern.reason)
+            && /reference can be removed|already covered/i.test(`${concern.reason} ${concern.nextAction}`)
+            && concern.checkIds.length > 0
+            && concern.checkIds.every(id => checks.has(id));
+        if (concern.material && staleCoveredReference)
+            return { ...concern, material: false };
         if (!concern.material || !concern.checkIds.length || !concern.checkIds.every(id => checks.get(id)?.timing === "postimplementation"))
             return concern;
         const expectedFutureAbsence = /\b(absent|missing|not (?:yet )?(?:implemented|present|available)|could not find|not found|does not exist|fails? with)\b/i.test(concern.reason)
             && /\b(?:before|pre[- ]?builder|not yet)\b/i.test(concern.reason)
             && /\b(?:implement|add|create|rerun|re-?run|builder|after implementation)\b/i.test(concern.nextAction);
-        return expectedFutureAbsence ? { ...concern, material: false } : concern;
+        const inventedSiblingAbsence = /\b(?:no|without|absen[ct]|missing)\s+(?:the\s+)?[a-z0-9_-]+\s+export\b|\b(?:sibling|other)\s+(?:feature|slice)\s+(?:absen[ct]|removed|present)\b/i.test(concern.reason)
+            && /\b(?:own|imports? only|no [a-z0-9_-]+ symbol|drop|remove)\b/i.test(concern.nextAction);
+        return expectedFutureAbsence || inventedSiblingAbsence ? { ...concern, material: false } : concern;
     });
     return copy;
 }
@@ -411,7 +425,7 @@ export async function prepareVerificationContract(initial, inventory, deps) {
                 normalized.assessedRequirementIds = [...fallback.assessedRequirementIds];
             return normalized;
         };
-        let 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. Treat Rafi-owned bookkeeping paths (.tickets, .rafi, generated docs/configuration, and agent instructions) as expected host changes. Scope concerns must be evaluated against approved product paths and ticket requirements; do not require an exact full-worktree status listing. Future Builder actions are not preparation failures: when an approved requirement specifies test-first ordering, a migration, rollback rehearsal, or other implementation-time sequence, represent it as a mandatory postimplementation check requiring retained Builder evidence. Do not mark the absence of that future evidence before Builder starts as a material concern, and do not demand that preparation reproduce historical order. Only report a material concern when the contract cannot state an actionable postimplementation check or when an already-required preimplementation fact is missing. Return RAFI_QA_ASSESSMENT_START/END with QaSemanticAssessmentV1 (schema: ${JSON.stringify(qaPreparationDepthDecisionV1Schema)}). The concerns field is an array of objects, never strings; every concern object must have exactly these six fields and no others: {reason:string, requirementIds:string[], checkIds:string[], material:boolean, owner:string, nextAction:string}. Do not use legacy fields such as severity, evidence, title, message, category, or resolution. Use concerns: [] only when all issues are resolved. assessedRequirementIds MUST contain every ID in this exact list, even when a requirement is host-owned or has no concern: ${JSON.stringify(candidate.requirements.map(requirement => requirement.id))}. Put every individually assessed required obligation label in assessedObligations, using the exact labels below; do not combine labels or claim to have assessed anything you did not assess. Required obligation labels: ${JSON.stringify(depthObligations(candidate.depthDecision.level))}. 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)}`);
+        let 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. Treat Rafi-owned bookkeeping paths (.tickets, .rafi, generated docs/configuration, and agent instructions) as expected host changes. Scope concerns must be evaluated against approved product paths and ticket requirements; do not require an exact full-worktree status listing. Future Builder actions are not preparation failures: when an approved requirement specifies test-first ordering, a migration, rollback rehearsal, or other implementation-time sequence, represent it as a mandatory postimplementation check requiring retained Builder evidence. Do not mark the absence of that future evidence before Builder starts as a material concern, and do not demand that preparation reproduce historical order. If a concern's only next action is to inspect, compare, run, or otherwise produce evidence for a check that is already declared with postimplementation timing, set that concern material:false; it is an actionable future check, not a preparation blocker. Only report a material concern when the contract cannot state an actionable postimplementation check or when an already-required preimplementation fact is missing. Return RAFI_QA_ASSESSMENT_START/END with QaSemanticAssessmentV1 (schema: ${JSON.stringify(qaPreparationDepthDecisionV1Schema)}). The concerns field is an array of objects, never strings; every concern object must have exactly these six fields and no others: {reason:string, requirementIds:string[], checkIds:string[], material:boolean, owner:string, nextAction:string}. Do not use legacy fields such as severity, evidence, title, message, category, or resolution. Use concerns: [] only when all issues are resolved. assessedRequirementIds MUST contain every ID in this exact list, even when a requirement is host-owned or has no concern: ${JSON.stringify(candidate.requirements.map(requirement => requirement.id))}. Put every individually assessed required obligation label in assessedObligations, using the exact labels below; do not combine labels or claim to have assessed anything you did not assess. Required obligation labels: ${JSON.stringify(depthObligations(candidate.depthDecision.level))}. 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)}`);
         let assessed = assessmentResponse
             ? await parsedContract(assessmentResponse, "RAFI_QA_ASSESSMENT", validateAssessmentContract, "QA semantic assessment", (value, response) => normalizeAssessment(value, response))
             : { value: retainedAssessment, response: undefined };
@@ -419,6 +433,11 @@ export async function prepareVerificationContract(initial, inventory, deps) {
         // session identity, but it cannot prove or safely author the builder's ID.
         assessed.value.authorSessionId = binding.authorSessionId;
         for (let repair = 0; assessmentResponse && repair < 3; repair++) {
+            // Apply host-owned current-branch applicability normalization before
+            // semantic validation. Otherwise an assessor's material sibling-absence
+            // concern is rejected before the host can downgrade that non-binding
+            // concern to an auditable, non-material observation.
+            assessed.value = normalizeExpectedFutureAssessment(assessed.value, candidate);
             const semanticIssues = validateAssessment(candidate, assessed.value, authorSessionId);
             if (!semanticIssues.length)
                 break;

package/dist/qaPreparationStore.js

@@ -9,7 +9,7 @@ export function migrateQaPreparation(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS qa_preparation_policy(run_id TEXT PRIMARY KEY REFERENCES workflow_runs(run_id),record_json TEXT NOT NULL);
     CREATE TABLE IF NOT EXISTS qa_preparation_budgets(id TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,admission_digest TEXT NOT NULL,record_json TEXT NOT NULL,UNIQUE(run_id,work_id,admission_digest));
-    CREATE TABLE IF NOT EXISTS qa_depth_decisions(decision_id TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,record_json TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS qa_depth_decisions(decision_id TEXT NOT NULL,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,admission_digest TEXT NOT NULL,record_json TEXT NOT NULL,PRIMARY KEY(decision_id,run_id,work_id,admission_digest));
     CREATE TABLE IF NOT EXISTS qa_preparation_attempts(operation_id TEXT PRIMARY KEY,budget_id TEXT NOT NULL REFERENCES qa_preparation_budgets(id),state TEXT NOT NULL,intent_json TEXT NOT NULL,result_json TEXT);
     CREATE TABLE IF NOT EXISTS qa_preparation_progress(budget_id TEXT NOT NULL REFERENCES qa_preparation_budgets(id),stage TEXT NOT NULL,digest TEXT NOT NULL,PRIMARY KEY(budget_id,stage));
     CREATE TABLE IF NOT EXISTS qa_verification_contracts(digest TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,admission_digest TEXT NOT NULL,revision INTEGER NOT NULL,record_json TEXT NOT NULL,UNIQUE(run_id,work_id,admission_digest,revision));
@@ -19,6 +19,7 @@ export function migrateQaPreparation(db) {
     CREATE TABLE IF NOT EXISTS qa_contract_artifacts(digest TEXT PRIMARY KEY,kind TEXT NOT NULL,record_json TEXT NOT NULL);
     CREATE TABLE IF NOT EXISTS qa_preparation_events(event_id TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,kind TEXT NOT NULL,record_json TEXT NOT NULL);
   `);
+    migrateQaDepthDecisions(db);
     for (const table of ["qa_preparation_policy", "qa_depth_decisions", "qa_verification_contracts", "qa_contract_check_history", "qa_contract_receipts", "qa_contract_artifacts", "qa_preparation_events"]) {
         for (const action of ["UPDATE", "DELETE"])
             db.exec(`CREATE TRIGGER IF NOT EXISTS preparation_immutable_${table}_${action} BEFORE ${action} ON ${table} BEGIN SELECT RAISE(ABORT,'Preparation authority and evidence are immutable'); END`);
@@ -33,6 +34,35 @@ export function migrateQaPreparation(db) {
             db.exec(`CREATE TRIGGER IF NOT EXISTS preparation_owner_${table}_${action} BEFORE ${action} ON ${table} BEGIN SELECT CASE WHEN rafi_qa_preparation_owner(${expression})<>1 THEN RAISE(ABORT,'Original preparation owner required') END; END`);
         }
 }
+/** Provider decision ids are scoped to the admitted preparation, not global. */
+function migrateQaDepthDecisions(db) {
+    const columns = db.prepare("PRAGMA table_info(qa_depth_decisions)").all();
+    if (!columns.length || columns.some(column => column.name === "admission_digest"))
+        return;
+    db.transaction(() => {
+        for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+            db.exec(`DROP TRIGGER IF EXISTS preparation_immutable_qa_depth_decisions_${action}`);
+            db.exec(`DROP TRIGGER IF EXISTS preparation_owner_qa_depth_decisions_${action}`);
+            db.exec(`DROP TRIGGER IF EXISTS preparation_lease_qa_depth_decisions_${action}`);
+        }
+        db.exec("CREATE TABLE qa_depth_decisions_scoped(decision_id TEXT NOT NULL,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),work_id TEXT NOT NULL,admission_digest TEXT NOT NULL,record_json TEXT NOT NULL,PRIMARY KEY(decision_id,run_id,work_id,admission_digest))");
+        db.exec("INSERT INTO qa_depth_decisions_scoped(decision_id,run_id,work_id,admission_digest,record_json) SELECT decision_id,run_id,work_id,COALESCE(NULLIF(json_extract(record_json,'$.admissionDigest'),''),'legacy:' || run_id || ':' || work_id),record_json FROM qa_depth_decisions");
+        db.exec("DROP TABLE qa_depth_decisions");
+        db.exec("ALTER TABLE qa_depth_decisions_scoped RENAME TO qa_depth_decisions");
+        for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+            const row = action === "DELETE" ? "OLD" : "NEW";
+            db.exec(`CREATE TRIGGER preparation_immutable_qa_depth_decisions_${action} BEFORE ${action} ON qa_depth_decisions BEGIN SELECT RAISE(ABORT,'Preparation authority and evidence are immutable'); END`);
+            const ownerRow = action === "DELETE" ? "OLD" : "NEW";
+            db.exec(`CREATE TRIGGER preparation_owner_qa_depth_decisions_${action} BEFORE ${action} ON qa_depth_decisions BEGIN SELECT CASE WHEN rafi_qa_preparation_owner(${ownerRow}.run_id)<>1 THEN RAISE(ABORT,'Original preparation owner required') END; END`);
+            const leaseRun = ownerRow;
+            db.exec(`CREATE TRIGGER preparation_lease_qa_depth_decisions_${action} BEFORE ${action} ON qa_depth_decisions
+        WHEN (EXISTS(SELECT 1 FROM build_admission) OR rafi_build_writer_run()<>'' OR EXISTS(SELECT 1 FROM build_runtime_runs WHERE run_id=${leaseRun}.run_id))
+        AND NOT EXISTS(SELECT 1 FROM build_admission WHERE json_extract(record_json,'$.token')=rafi_build_writer_token() AND (json_extract(record_json,'$.runId')=${leaseRun}.run_id OR EXISTS(SELECT 1 FROM build_child_runs WHERE child=${leaseRun}.run_id AND parent=json_extract(record_json,'$.runId'))))
+        AND NOT (NOT EXISTS(SELECT 1 FROM build_admission) AND EXISTS(SELECT 1 FROM project_lease WHERE owner=rafi_build_lease_owner() AND generation=rafi_build_lease_generation() AND run_id=${leaseRun}.run_id))
+        BEGIN SELECT RAISE(ABORT,'Preparation requires the original durable lease generation'); END`);
+        }
+    })();
+}
 /** Tagged enforcing authority also fences older callers that omit new fields. */
 export function migrateQaPreparationGuards(db) {
     const scopes = {
@@ -242,13 +272,11 @@ export class QaPreparationStore {
             current.level = decision.level;
             current.deadlineMs = Math.max(current.deadlineMs, current.startMs + current.policy.wallTimeMs[decision.level - 1]);
             this.saveBudget(current);
-            const prior = this.read("qa_depth_decisions", "decision_id", decision.decisionId);
-            const priorScope = this.db.prepare("SELECT run_id,work_id FROM qa_depth_decisions WHERE decision_id=?").get(decision.decisionId);
-            if (priorScope && (priorScope.run_id !== budget.runId || priorScope.work_id !== budget.workId))
-                throw new Error("Planner depth identity belongs to another admitted work");
+            const priorRow = this.db.prepare("SELECT record_json FROM qa_depth_decisions WHERE decision_id=? AND run_id=? AND work_id=? AND admission_digest=?").get(decision.decisionId, budget.runId, budget.workId, budget.admissionDigest);
+            const prior = priorRow ? this.decode(priorRow.record_json) : undefined;
             if (prior && this.protectedJson(prior) !== this.protectedJson(decision))
                 throw new Error("Conflicting planner depth identity");
-            this.db.prepare("INSERT INTO qa_depth_decisions VALUES(?,?,?,?) ON CONFLICT(decision_id) DO NOTHING").run(decision.decisionId, budget.runId, budget.workId, this.protectedJson(decision));
+            this.db.prepare("INSERT INTO qa_depth_decisions VALUES(?,?,?,?,?) ON CONFLICT(decision_id,run_id,work_id,admission_digest) DO NOTHING").run(decision.decisionId, budget.runId, budget.workId, budget.admissionDigest, this.protectedJson(decision));
         });
     }
     retainProgress(budget, stage, value) {

package/dist/qaReview.js

@@ -1,6 +1,6 @@
 import { withGraphDerivedAccess } from "./graph/derived.js";
 import { dispatchWithGraphAccess } from "./graph/session.js";
-import { finalQaRoleInstructions, resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
+import { finalQaRoleInstructions, QA_COMMAND_DISCIPLINE, resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
 import { COVERAGE_INSTRUCTIONS, bindCoverageHostFields, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
 import { contractDigest, renderVerificationContract } from "./qaVerificationContract.js";
 import { finalReviewContractContext } from "./qaContractDelivery.js";
@@ -26,7 +26,10 @@ import { canonicalSessionPath } from "./sessionIdentity.js";
 import { loadProjectAutonomyConfig, resolveAutonomyPolicy } from "./recoveryPolicy.js";
 import { appendQaRecoveryAttempt, appendQaRecoveryResource, appendQaRecoveryReviewedState, compareQaRecoveryReviewedState, createQaRecoveryPacket, ensureQaRecoveryExcluded, loadQaRecoveryPacket, materializeQaRecoveryContext, qaRecoveryInventory, qaReportDigest, renderQaRecoveryAcknowledgementInstruction, updateQaRecoveryPosition, updateQaRecoveryReviewIdentity, validateManualQaReport, validateQaRecoveryAcknowledgement, } from "./qaRecovery.js";
 import { canonicalJson, createQaFindingRefs, qaDigest } from "./qaProtocolV2.js";
-import { applyHostQaComparison, createHostQaComparison, findHostQaCheck } from "./hostQaComparison.js";
+import { createHostQaComparison, findHostQaCheck } from "./hostQaComparison.js";
+import { createHostGraphApplicability, findGraphQaChecks } from "./hostGraphApplicability.js";
+import { applyHostQaAugmentations } from "./hostQaAugmentation.js";
+import { qaUnresolvedToolDecision, recordQaUnresolvedTools } from "./qaToolRecovery.js";
 function ensureProtocolPausePacket(opts, head, stage, detail, frozenState) {
     const db = new WorkflowDb(opts.recovery.projectDir);
     try {
@@ -946,6 +949,13 @@ async function oneReview(opts, identity) {
                 responseProtocolError = `invalid QA response contract after blocker recovery: ${responseContract.errors.join("; ")}`;
             }
         }
+        const unresolvedDecision = qaUnresolvedToolDecision(opts.recovery.projectDir, opts.recovery.runId, opts.ticket.id, qaEvents);
+        if (unresolvedDecision.action !== "none") {
+            recordQaUnresolvedTools(opts.recovery.projectDir, opts.recovery.runId, opts.ticket.id, qaEvents);
+            if (unresolvedDecision.action === "retry")
+                return retryFreshQaReview(opts, "unresolved-provider-tool", unresolvedDecision.detail, (recoverySnapshot ?? snapshot).frozenState);
+            return pauseQaReview(opts, "unresolved-provider-tool", unresolvedDecision.detail, (recoverySnapshot ?? snapshot).frozenState);
+        }
         opts.state.reviews += 1;
         opts.state.sessionId = qa.sessionId();
         opts.state.sessionRef = qa.sessionRef?.();
@@ -1155,6 +1165,7 @@ export function buildQaReviewHandoff(ticket, builderSummary, diffDigest, validat
         `Project validation checklist: ${validationChecklist.join("; ")}`,
         `Prior authoritative QA/report and Builder-remediation history: ${history.length ? JSON.stringify(boundedQaHistory(history)) : "(none; perform a complete first review)"}`,
         `Failure report JSON Schema: ${JSON.stringify(qaFailureReportV1Schema)}`,
+        QA_COMMAND_DISCIPLINE,
         `A failing response must use exactly:\n${QA_FAILURE_REPORT_START}\n{...valid QaFailureReportV1 JSON...}\n${QA_FAILURE_REPORT_END}\nSTEP_STATUS: qa_fail | issues="short plain-text synopsis"`,
         "Be very thorough. Don't leave anything out. Make sure all required fields are added. Triple check your work to ensure nothing is left out and all required fields are added and populated correctly.",
         "Do not change source, configuration, documentation, tickets, or control files. Only ignored cache, coverage, and build output is allowed.",
@@ -2010,9 +2021,11 @@ function finishV2Pass(opts, adapter, detail) {
                 const hostComparison = findHostQaCheck(contract)
                     ? createHostQaComparison({ db, projectDir: binding.projectDir, worktree: opts.builderWorktree, runId: binding.runId, ticket: opts.ticket, contract, reviewAttemptId: binding.reviewAttemptId, reviewBasisDigest: binding.reviewBasisDigest })
                     : undefined;
-                const coverage = hostComparison
-                    ? applyHostQaComparison(providerCoverage, contract, hostComparison.result, hostComparison.resultDigest, binding.projectDir)
-                    : providerCoverage;
+                const hostGraph = findGraphQaChecks(contract).length
+                    ? createHostGraphApplicability({ projectDir: binding.projectDir, runId: binding.runId, ticketId: binding.ticketId, contract, reviewAttemptId: binding.reviewAttemptId, reviewBasisDigest: binding.reviewBasisDigest, sourceDigest: binding.sourceStateDigest, store: db.qaPreparationStore() })
+                    : undefined;
+                const commandObservations = retainedQaCommandObservations(opts.recovery.projectDir, opts.recovery.runId, opts.ticket.id, false);
+                const coverage = applyHostQaAugmentations({ coverage: providerCoverage, contract, projectDir: binding.projectDir, hostComparison, hostGraph, commandObservations });
                 const errors = validateContractCoverage(contract, coverage, coverageBinding);
                 if (errors.length)
                     throw new Error(`Final QA coverage incomplete: ${errors.join("; ")}`);

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

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,36 @@ 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.applicability.decisionOwner === "host"
+        && /scope comparison|product paths|preimplementation baseline/i.test(`${check.expectedBehavior} ${check.expectedEvidence.join(" ")} ${check.applicability.requiredEvidence.join(" ")}`));
+    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");
+    copy.checks.push({
+        id: "host-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 +169,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)

package/dist/supervisedStart.d.ts

@@ -1,5 +1,5 @@
 import { WorkflowDb } from "./workflowDb.js";
-import type { ResolvedAutonomyPolicy } from "rafi-spec";
+import { type ResolvedAutonomyPolicy } from "rafi-spec";
 /** Worker IPC is created by the parent; an environment flag alone cannot bypass supervision. */
 export declare function supervisedRunId(): string | undefined;
 /** Both ordinary and branch starts enter through this process boundary. */

package/dist/supervisedStart.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { hostname } from "node:os";
 import { DurableSupervisor } from "./supervisor.js";
 import { WorkflowDb } from "./workflowDb.js";
+import { stopCause } from "rafi-spec";
 import { processStartIdentity } from "./processIdentity.js";
 import { cancelOwnedRuntimeProbes } from "./runtimeReadiness.js";
 /** Worker IPC is created by the parent; an environment flag alone cannot bypass supervision. */
@@ -51,8 +52,9 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                     const owner = durable.supervisorState(runId);
                     if (owner?.workerGeneration !== Number(process.env.RAFI_BUILD_WORKER_GENERATION) || owner.workerPid !== process.pid)
                         return;
-                    durable.transition(runId, { status: "paused", checkpoint: "orphaned-worker", event: "supervisor_disconnected", payload: { workerPid: process.pid } });
-                    durable.putSupervisorState(runId, { ...owner, status: "stopping" });
+                    const cause = stopCause({ cause: "worker-disconnect", source: "worker", actor: "worker", runId, supervisorGeneration: owner.generation, workerGeneration: owner.workerGeneration, pid: process.pid, processStart: processStartIdentity(), checkpoint: "orphaned-worker", at: new Date().toISOString(), requested: false, detail: "Worker IPC disconnected before the supervisor acknowledged shutdown" });
+                    durable.transition(runId, { status: "paused", checkpoint: "orphaned-worker", event: "supervisor_disconnected", payload: { workerPid: process.pid, cause } });
+                    durable.putSupervisorState(runId, { ...owner, status: "stopping", stopCause: cause });
                 });
             }
             catch (error) {
@@ -156,9 +158,10 @@ export async function superviseStart(projectDir, runId, policy, selection) {
     db.ensureRun(runId, "build");
     db.freezeAutonomyPolicy(runId, policy);
     let exitCode = 2;
-    let stopRequestSource;
+    let stopRequestCause;
     const supervisor = new DurableSupervisor({ projectDir, runId, policy, admission: localBuildAuthority(projectDir),
         checkpoint: () => db.getRun(runId)?.checkpoint ?? "preparing",
+        onStopRequested: cause => { stopRequestCause = cause; },
         spawnWorker: generation => {
             let authority = localBuildAuthority(projectDir);
             if (db.buildAdmission()?.token !== authority.token) {
@@ -212,7 +215,7 @@ export async function superviseStart(projectDir, runId, policy, selection) {
             };
             const heartbeatTimeout = policy.runtimeDeadlines?.heartbeat_ms ?? 120_000;
             const watchdog = setInterval(() => { if (Date.now() - lastHeartbeat > heartbeatTimeout) {
-                stopRequestSource = "heartbeat-timeout";
+                stopRequestCause = stopCause({ cause: "heartbeat-timeout", source: "heartbeat", actor: "supervisor", runId, supervisorGeneration: generation, workerGeneration: generation, checkpoint: db.getRun(runId)?.checkpoint ?? "unknown", at: new Date().toISOString(), requested: true, detail: `worker heartbeat exceeded ${heartbeatTimeout}ms` });
                 stop();
             } }, Math.min(5_000, Math.max(25, heartbeatTimeout / 4)));
             watchdog.unref();
@@ -256,8 +259,15 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                     exitCode = code ?? 2;
                     try {
                         const exitState = db.getRun(runId);
+                        const exitCause = stopRequestCause ?? stopCause({ cause: "worker-exit", source: "worker", actor: "worker", runId, supervisorGeneration: generation, workerGeneration: generation, pid: child.pid, processStart: child.pid ? processStartIdentity(child.pid) : undefined, checkpoint: exitState?.checkpoint ?? "unknown", at: new Date().toISOString(), requested: false, detail: signal ? `worker exited from ${signal}` : `worker exited with code ${code ?? "unknown"}` });
                         if (exitState)
-                            db.transitionSupervisor(runId, generation, { checkpoint: exitState.checkpoint, event: "worker_exit", payload: { code, signal, stopRequested: stopping, source: stopRequestSource ?? "unknown", at: new Date().toISOString(), generation } });
+                            db.transitionSupervisor(runId, generation, { checkpoint: exitState.checkpoint, event: "worker_exit", payload: {
+                                    code, signal, stopRequested: stopping, cause: exitCause,
+                                    // Preserve the historical diagnostic field while consumers migrate
+                                    // to the closed StopCause contract.
+                                    source: exitCause.cause === "parent-sigterm" ? "parent-SIGTERM" : exitCause.cause === "user-sigint" ? "user-SIGINT" : exitCause.cause === "heartbeat-timeout" ? "heartbeat-timeout" : exitCause.cause,
+                                    at: new Date().toISOString(), generation,
+                                } });
                         // Durable records are authoritative even when the worker never sent IPC.
                         const deadline = Date.now() + 5000;
                         const owned = db.readinessProcesses(runId).filter(row => {
@@ -286,14 +296,36 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                             const workerQuiescent = await ownedGroupIsQuiescent(child.pid);
                             const preparationReconciled = canRestartPreparation(db, runId);
                             if (!stopping && readinessQuiescent && workerQuiescent && preparationReconciled) {
-                                db.transitionSupervisor(runId, generation, { status: "paused", checkpoint: "preparation-reconciled", event: "worker_preparation_reconciled", payload: { generation, signal, noImplementationAuthority: true } });
+                                const preparationCause = stopCause({
+                                    cause: "worker-exit", source: "worker", actor: "worker", runId,
+                                    supervisorGeneration: generation, workerGeneration: generation,
+                                    pid: child.pid, processStart: child.pid ? processStartIdentity(child.pid) : undefined,
+                                    checkpoint: "preparation-reconciled", at: new Date().toISOString(), requested: false,
+                                    detail: "Worker exited before acquiring implementation authority; owned process group is quiescent",
+                                });
+                                db.transitionSupervisor(runId, generation, { status: "paused", checkpoint: "preparation-reconciled", event: "worker_preparation_reconciled", payload: { generation, signal, noImplementationAuthority: true, cause: preparationCause } });
                                 resolve({ kind: "crashed", detail: "Preparation worker exited before acquiring implementation authority; owned process group is quiescent" });
                                 return;
                             }
                             // Process death does not establish that remote side effects stopped.
                             // Never replay an unacknowledged provider action automatically.
                             const uncertain = [...db.unresolvedRoleDispatches(runId, "builder"), ...db.unresolvedRoleDispatches(runId, "qa")];
-                            db.transitionSupervisor(runId, generation, { status: "paused", checkpoint: uncertain.length ? "uncertain-worker-dispatch" : "worker-interrupted", event: "worker_reconciliation_required", payload: { generation, signal, uncertainDispatches: uncertain.map(item => item.idempotencyKey), readinessWasActive, readinessQuiescent, workerQuiescent, preparationReconciled, readinessCleanup, readinessOwnershipVerified: [...readinessChildren.values()].every(value => value !== "unavailable") } });
+                            const reconciliationCause = stopCause({
+                                ...(stopRequestCause ?? { runId, supervisorGeneration: generation, workerGeneration: generation }),
+                                cause: "worker-reconciliation-required",
+                                source: "reconciliation",
+                                actor: "supervisor",
+                                runId,
+                                supervisorGeneration: generation,
+                                workerGeneration: generation,
+                                pid: child.pid,
+                                processStart: child.pid ? processStartIdentity(child.pid) : undefined,
+                                checkpoint: uncertain.length ? "uncertain-worker-dispatch" : "worker-interrupted",
+                                at: new Date().toISOString(),
+                                requested: false,
+                                detail: "Worker stopped before all owned work had a durable terminal outcome",
+                            });
+                            db.transitionSupervisor(runId, generation, { status: "paused", checkpoint: uncertain.length ? "uncertain-worker-dispatch" : "worker-interrupted", event: "worker_reconciliation_required", payload: { generation, signal, cause: reconciliationCause, uncertainDispatches: uncertain.map(item => item.idempotencyKey), readinessWasActive, readinessQuiescent, workerQuiescent, preparationReconciled, readinessCleanup, readinessOwnershipVerified: [...readinessChildren.values()].every(value => value !== "unavailable") } });
                             resolve({ kind: "waiting_for_human" });
                         }
                         else {
@@ -318,8 +350,8 @@ export async function superviseStart(projectDir, runId, policy, selection) {
             return { pid: child.pid, result, stop };
         },
     });
-    const stopInt = () => { stopRequestSource = "parent-SIGINT"; supervisor.requestStop(); };
-    const stopTerm = () => { stopRequestSource = "parent-SIGTERM"; supervisor.requestStop(); };
+    const stopInt = () => { supervisor.requestStop("user-sigint"); };
+    const stopTerm = () => { supervisor.requestStop("parent-sigterm"); };
     process.once("SIGINT", stopInt);
     process.once("SIGTERM", stopTerm);
     let supervisorCompleted = false;
@@ -331,12 +363,13 @@ export async function superviseStart(projectDir, runId, policy, selection) {
             const run = db.getRun(runId);
             if (!state || state.pid !== process.pid || state.status !== "running" || !run || ["completed", "cancelled", "superseded"].includes(run.status))
                 return;
-            db.putSupervisorState(runId, { ...state, status: "failed", pid: undefined, workerPid: undefined, heartbeatAt: new Date().toISOString() });
+            const cause = stopCause({ cause: "supervisor-process-exit", source: "supervisor", actor: "supervisor", runId, supervisorGeneration: state.generation, workerGeneration: state.workerGeneration, pid: process.pid, processStart: state.processStart, checkpoint: run.checkpoint, at: new Date().toISOString(), requested: false, detail: `supervisor exited with code ${code}` });
+            db.putSupervisorState(runId, { ...state, status: "failed", pid: undefined, workerPid: undefined, heartbeatAt: new Date().toISOString(), stopCause: cause });
             db.transitionSupervisor(runId, state.workerGeneration, {
                 status: "paused",
                 checkpoint: "supervisor-process-exit",
                 event: "supervisor_process_exit",
-                payload: { exitCode: code, lastCheckpoint: run.checkpoint, generation: state.generation },
+                payload: { exitCode: code, lastCheckpoint: run.checkpoint, generation: state.generation, cause },
             });
         }
         catch { /* Exit handlers must not mask the original process termination. */ }

package/dist/supervisor.d.ts

@@ -1,5 +1,5 @@
 import type { BuildAdmission } from "./buildAdmission.js";
-import type { ResolvedAutonomyPolicy, SupervisorState } from "rafi-spec";
+import { type ResolvedAutonomyPolicy, type StopCause, type StopCauseName, type SupervisorState } from "rafi-spec";
 export type WorkerOutcome = {
     kind: "completed";
 } | {
@@ -18,6 +18,19 @@ export interface SupervisorWorkerHandle {
     result: Promise<WorkerOutcome>;
     stop: () => Promise<void> | void;
 }
+/**
+ * Retry only the short synchronous persistence operation. The caller owns
+ * the retry budget and remains responsible for deciding whether ownership is
+ * safe after the budget is exhausted.
+ */
+export declare function persistWithBoundedRetry(persist: () => void, sleep: (milliseconds: number) => Promise<void>, attempts?: number): Promise<{
+    ok: true;
+    attempts: number;
+} | {
+    ok: false;
+    attempts: number;
+    error: unknown;
+}>;
 export interface DurableSupervisorOptions {
     projectDir: string;
     runId: string;
@@ -27,16 +40,19 @@ export interface DurableSupervisorOptions {
     checkpoint: () => string;
     sleep?: (milliseconds: number) => Promise<void>;
     now?: () => Date;
+    onStopRequested?: (cause: StopCause) => void;
+    heartbeatIntervalMs?: number;
 }
 /** Durable worker restart loop. The supervisor never owns the project's mutation lease. */
 export declare class DurableSupervisor {
     private readonly options;
     private stopRequested;
+    private requestedStopCause?;
     private active?;
     private readonly sleep;
     private readonly now;
     constructor(options: DurableSupervisorOptions);
-    requestStop(): void;
+    requestStop(cause?: StopCauseName): void;
     run(): Promise<WorkerOutcome>;
 }
 export declare function initialSupervisorState(): SupervisorState;