ai-foreman 1.7.28 → 1.7.29

package/dist/adapters/claude.js

@@ -749,7 +749,7 @@ export class ClaudeAdapter {
             const outputDigest = createHash("sha256").update(text).digest("hex");
             // Persist only correlation metadata. The result text can contain source
             // paths, command output, or credentials and must not enter lifecycle logs.
-            this.opts.onLifecycleTrace?.({ phase: "provider-tool-result", at: new Date().toISOString(), sessionId: this._sessionId, providerTurnId: this.activeProviderTurnId, toolCallId: callId, toolName: call?.name ?? "unidentified tool", classification: status, resultReason, isError: failed, outputDigest, rawOutputBytes: Buffer.byteLength(text) });
+            this.opts.onLifecycleTrace?.({ phase: "provider-tool-result", at: new Date().toISOString(), sessionId: this._sessionId, providerTurnId: this.activeProviderTurnId, toolCallId: callId, toolName: call?.name ?? "unidentified tool", classification: status, resultReason, isError: failed, outputDigest, rawOutputBytes: Buffer.byteLength(text), completionKnown: status !== "unknown" });
             if (status === "unknown") {
                 if (this.unknownToolResults.get(callId) === outputDigest)
                     continue;

package/dist/adapters/types.d.ts

@@ -287,6 +287,7 @@ export interface BuilderAdapterOptions {
         isError?: boolean;
         outputDigest?: string;
         rawOutputBytes?: number;
+        completionKnown?: boolean;
     }) => void;
 }
 export interface BuilderAdapter {

package/dist/buildApproval.d.ts

@@ -7,5 +7,20 @@ export declare function approvedBuildScope(projectDir: string, ticketIds?: reado
 export declare function requiresBuildApproval(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences?: Record<string, unknown>): boolean;
 /** Bind decisions to current files so an old answer cannot approve a changed scope. */
 export declare function buildScopeRevision(projectDir: string, consequences?: Record<string, unknown>): string;
+export interface PlanApprovalBinding {
+    planDigest: string;
+    ticketSetDigest: string;
+    ticketDefinitionsDigest: string;
+    scopeRevision: string;
+    workflowConsequenceDigest: string;
+}
+/** Compute the exact host-owned inputs covered by a recovery plan approval. */
+export declare function planApprovalBinding(projectDir: string, ticketIds: readonly string[], consequences?: Record<string, unknown>): PlanApprovalBinding;
+export declare function validatePlanApprovalBinding(projectDir: string, ticketIds: readonly string[], approval: PlanApprovalBinding, consequences?: Record<string, unknown>): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
 /** Reuse a decision only while its source and consequences remain unchanged. */
 export declare function createBuildApprovalGate(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences: Record<string, unknown> | undefined, requestApproval: () => Promise<void>): () => Promise<void>;

package/dist/buildApproval.js

@@ -125,6 +125,49 @@ export function buildScopeRevision(projectDir, consequences) {
     });
     return createHash("sha256").update(JSON.stringify([contents, consequences])).digest("hex");
 }
+/** Compute the exact host-owned inputs covered by a recovery plan approval. */
+export function planApprovalBinding(projectDir, ticketIds, consequences) {
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    const all = loadTickets(paths.tickets);
+    const selected = ticketIds.map(id => all.find(ticket => ticket.id === id));
+    if (selected.some(ticket => !ticket))
+        throw new Error("plan approval cannot bind a missing ticket definition");
+    const config = parse(readFileSync(join(projectDir, "rafi-config.yaml"), "utf8"));
+    const docsRoot = config.docs?.root ?? "docs";
+    const plan = JSON.parse(readFileSync(join(projectDir, docsRoot, "rafi-plan.json"), "utf8"));
+    const planDigest = createHash("sha256").update(canonical({ ...plan, content_digest: "" })).digest("hex");
+    const db = new WorkflowDb(projectDir);
+    try {
+        const approved = db.completedPlanApprovals().some(receipt => {
+            const decision = receipt.decisionReceipt;
+            return receipt.planId === plan.plan_id && receipt.revision === plan.revision
+                && receipt.digest === planDigest && decision?.planDigest === planDigest;
+        });
+        if (!approved)
+            throw new Error("current plan has no matching completed host approval");
+    }
+    finally {
+        db.close();
+    }
+    const ticketSetDigest = createHash("sha256").update(canonical([...ticketIds].sort())).digest("hex");
+    const ticketDefinitionsDigest = createHash("sha256").update(canonical(selected.map(ticket => material(ticket)).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))))).digest("hex");
+    const workflow = { build: config.tickets?.build ?? {}, consequences: consequences ?? {} };
+    const workflowConsequenceDigest = createHash("sha256").update(canonical(workflow)).digest("hex");
+    return { planDigest, ticketSetDigest, ticketDefinitionsDigest, scopeRevision: buildScopeRevision(projectDir, consequences), workflowConsequenceDigest };
+}
+export function validatePlanApprovalBinding(projectDir, ticketIds, approval, consequences) {
+    try {
+        const current = planApprovalBinding(projectDir, ticketIds, consequences);
+        for (const key of ["planDigest", "ticketSetDigest", "ticketDefinitionsDigest", "scopeRevision", "workflowConsequenceDigest"]) {
+            if (current[key] !== approval[key])
+                return { valid: false, reason: `${key} changed` };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return { valid: false, reason: `approval inputs unavailable: ${String(error)}` };
+    }
+}
 /** Reuse a decision only while its source and consequences remain unchanged. */
 export function createBuildApprovalGate(projectDir, ticketIds, explicitYes, consequences, requestApproval) {
     let approvedRevision;

package/dist/cli/start.js

@@ -11,7 +11,7 @@ import { captureFrozenQaSource } from "../qaSnapshot.js";
 import { finishStartAdmission, superviseStart, supervisedRunId } from "../supervisedStart.js";
 import { assertBuildAssignmentReconciled, isInterruptedBuilderRecovery, assertInterruptedSourceSnapshot } from "../buildAssignment.js";
 import { durableHumanDecision, HumanDecisionRequired, HumanDecisionCancelled, servicePendingHumanDecisions } from "../humanDecision.js";
-import { requiresBuildApproval, buildScopeRevision, createBuildApprovalGate } from "../buildApproval.js";
+import { requiresBuildApproval, buildScopeRevision, createBuildApprovalGate, validatePlanApprovalBinding } from "../buildApproval.js";
 import { Command, Option } from "commander";
 import { accent, error, sanitizeTerminalText, success, warning } from "../terminalStyle.js";
 import { resolve, join, relative } from "node:path";
@@ -693,6 +693,18 @@ export function buildStartCommand(options = {}) {
                 ? recoveryRecord.recoveryDecision?.planUpdateApproval === "auto"
                     && (recoveryRecord.recoveryDecision.planUpdateApprovalSource === "explicit-yes" || recoveryRecord.recoveryDecision.planUpdateApprovalSource === "explicit-choice")
                 : Boolean(opts.yes);
+            const recoveryTickets = recoveryRecord?.recoveryDecision?.executionTickets ?? recoveryRecord?.tickets ?? [];
+            // Empty-scope recovery is used by established/supervisor lifecycle
+            // recovery fixtures and has no ticket plan to bind. Ticket-bearing
+            // recovery remains fail-closed on an exact current-plan approval.
+            if (recoveryRecord && autoApprovePlanUpdates && recoveryTickets.length > 0) {
+                const decision = recoveryRecord.recoveryDecision;
+                if (!decision?.planApproval)
+                    fail("saved --yes approval has no exact plan binding; rerun rafi build:resume --yes to approve the current plan");
+                const approvalCheck = validatePlanApprovalBinding(cwd, recoveryTickets, decision.planApproval);
+                if (!approvalCheck.valid)
+                    fail(`saved --yes approval is stale (${approvalCheck.reason}); rerun rafi build:resume --yes before provider work`);
+            }
             if (opts.recoveryMode) {
                 const allowed = ["exact-session", "fresh-with-handoff", "fresh-recovery-only", "guided-recovery"];
                 if (!allowed.includes(String(opts.recoveryMode)))

package/dist/cli/tickets.d.ts

@@ -1,10 +1,17 @@
 import { Command } from "commander";
 import type { StructuredPlanV1 } from "rafi-spec";
 import { Log } from "../log.js";
+import { type StepStatus } from "../foreman.js";
 import type { EffortLevel } from "../adapters/types.js";
 import { type RoleBuilderOptions } from "../agentRun.js";
 import type { TicketsConfig } from "../tickets/config.js";
 import { type TicketPopulateRuntimeMode, type TicketSourceConfig, type TicketsSetupConfig } from "../tickets/setupConfig.js";
+/**
+ * Ticket Maker may append an explanatory note after its machine envelope.
+ * Preserve a schema-valid proposal before Foreman's strict generic marker
+ * repair path replaces the response with a status-only correction.
+ */
+export declare function acceptTicketPopulationCompletion(text: string): StepStatus | undefined;
 /** Commander preserves comma-delimited values as one argument; accept both documented forms. */
 export declare function normalizeRiskWaiverTicketIds(values: readonly string[] | undefined): string[];
 /** Record an explicit, definition-bound exception for existing risk tickets. */

package/dist/cli/tickets.js

@@ -7,7 +7,7 @@ import { riskNoteRepairProposalV1Schema, zodIssues } from "rafi-spec";
 import { select, text, confirm, isCancel, multiselect } from "@clack/prompts";
 import { loadConfig } from "../config.js";
 import { Log } from "../log.js";
-import { Foreman } from "../foreman.js";
+import { Foreman, parseStepStatus } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { cmdInit, cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdCancel, cmdDiscover, cmdAcceptFutureWork, cmdReorder, cmdRender, cmdValidate, cmdQueue, cmdStackQueue, cmdArchive, cmdReview, } from "../tickets/commands.js";
 import { loadDeliveryConfig } from "../tickets/delivery.js";
@@ -35,6 +35,21 @@ let nestedTicketCommandDepth = 0;
 class TicketInterviewCancelled extends Error {
 }
 function cancelTicketInterview() { throw new TicketInterviewCancelled("ticket interview cancelled"); }
+/**
+ * Ticket Maker may append an explanatory note after its machine envelope.
+ * Preserve a schema-valid proposal before Foreman's strict generic marker
+ * repair path replaces the response with a status-only correction.
+ */
+export function acceptTicketPopulationCompletion(text) {
+    try {
+        extractTicketPopulationProposal(text);
+    }
+    catch {
+        return undefined;
+    }
+    const status = parseStepStatus(text, { requireFinalLine: false });
+    return status.kind === "done" || status.kind === "plan_complete" ? status : undefined;
+}
 function fail(msg) {
     if (nestedTicketCommandDepth > 0)
         throw new Error(msg);
@@ -208,7 +223,7 @@ Output one JSON object between ${TICKET_POPULATION_PROPOSAL_START} and ${TICKET_
 {"version":1,"plan_id":"approved plan ID","revision":1,"tickets":[{"slice_ref":"slc_low","title":"...","area":"...","priority":"P1","size":"S","risk":"Low","summary":"...","acceptance":["..."],"required_tests":["..."],"likely_files":["..."],"documentation":{"required":false,"targets":[],"criteria":[]},"depends_on":[],"rollback":null,"notes":null},{"slice_ref":"slc_medium","title":"...","area":"...","priority":"P1","size":"S","risk":"Medium","summary":"...","acceptance":["..."],"required_tests":["..."],"likely_files":["..."],"documentation":{"required":false,"targets":[],"criteria":[]},"depends_on":["slc_low"],"rollback":"Disable the feature flag, restore the previous handler, and verify the affected error rate returns to baseline.","notes":null}],"retirements":["exact existing ticket ID"]}
 Triple-check that every approved slice appears exactly once.
 
-End with exactly one marker line as the final non-empty line:
+End with exactly one marker line as the final non-empty line; do not append notes or commentary after it:
 STEP_STATUS: done | summary="populated Foreman tickets from existing project ticket sources"
 or
 STEP_STATUS: blocked | reason="why ticket population cannot proceed"`;
@@ -1465,7 +1480,7 @@ export async function cmdPopulateCli(opts) {
         if (contextSources.length) {
             console.log(`foreman tickets: context sources ${contextSources.join(" ")}`);
         }
-        let turn = await foreman.runInstruction(buildPopulateInstruction(approvedPlan.path, contextSources, ticketsConfig.paths.progressDoc));
+        let turn = await foreman.runInstruction(buildPopulateInstruction(approvedPlan.path, contextSources, ticketsConfig.paths.progressDoc), { completion: acceptTicketPopulationCompletion });
         planningRecord = checkpointInterview(dir, planningRecord, { runtime: { runtime: roleBuilder.runtime, model: roleBuilder.model, sessionId: builder.sessionId() }, decisions: { ...planningRecord.decisions, proposalResponse: turn.result.text } });
         log.write("ticket-populate", {
             statusKind: turn.status.kind,

package/dist/foreman.d.ts

@@ -20,11 +20,18 @@ export interface StepStatus {
     branchDependency?: string;
     error?: string;
 }
+/**
+ * Workflow-specific completion is opt-in. Callers may preserve a valid
+ * structured response before the generic strict STEP_STATUS repair path runs.
+ */
+export type InstructionCompletion = (text: string) => StepStatus | undefined;
 /**
  * Pull the STEP_STATUS marker out of a turn's final text.
  * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
  */
-export declare function parseStepStatus(text: string): StepStatus;
+export declare function parseStepStatus(text: string, options?: {
+    requireFinalLine?: boolean;
+}): StepStatus;
 /** Heuristic: did a marker-less turn end by asking the human something? */
 export declare function looksLikeQuestion(text: string): boolean;
 export { MARKER_SPEC } from "./markers.js";
@@ -126,7 +133,9 @@ export declare class Foreman {
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
     sendPreflightFeedback(feedback: string): Promise<void>;
     /** Send one custom instruction through the same needs_input loop as a batch turn. */
-    runInstruction(instruction: string): Promise<{
+    runInstruction(instruction: string, options?: {
+        completion?: InstructionCompletion;
+    }): Promise<{
         result: TurnResult;
         status: StepStatus;
     }>;

package/dist/foreman.js

@@ -60,7 +60,7 @@ const QUESTION_HINTS = [
  * Pull the STEP_STATUS marker out of a turn's final text.
  * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
  */
-export function parseStepStatus(text) {
+export function parseStepStatus(text, options = {}) {
     const markerLines = text.split(/\r?\n/).filter((line) => /^\s*STEP_STATUS:/.test(line));
     const markerCount = markerLines.length;
     if (markerCount > 1) {
@@ -69,12 +69,14 @@ export function parseStepStatus(text) {
     const lines = text.trimEnd().split(/\r?\n/).filter((line) => line.trim().length > 0);
     const last = lines[lines.length - 1] ?? "";
     if (!last.includes("STEP_STATUS:")) {
-        if (markerCount === 1) {
+        if (markerCount === 1 && options.requireFinalLine !== false) {
             return { kind: "unknown", error: "STEP_STATUS marker was not the final non-empty line" };
         }
-        return { kind: "unknown" };
+        if (markerCount === 0)
+            return { kind: "unknown" };
     }
-    const match = last.match(/^STEP_STATUS:\s*(done|blocked|plan_complete|needs_input|qa_pass|qa_fail)\b\s*(?:\|\s*(.*))?$/i);
+    const marker = options.requireFinalLine === false ? markerLines[0]?.trim() ?? "" : last;
+    const match = marker.match(/^STEP_STATUS:\s*(done|blocked|plan_complete|needs_input|qa_pass|qa_fail)\b\s*(?:\|\s*(.*))?$/i);
     if (!match) {
         return { kind: "unknown", error: "malformed STEP_STATUS marker" };
     }
@@ -438,12 +440,12 @@ export class Foreman {
         this.builder = await this.builderFactory(this.projectDir);
         this.log.write("branch-session", { role: "builder", transition: "missing-session-fresh", continuityLost: true });
     }
-    async doTurnWith(adapter, instruction, mode = "builder") {
+    async doTurnWith(adapter, instruction, mode = "builder", completion) {
         return this.projectDir
-            ? withGraphSessionAccess(this.projectDir, adapter, () => this.doTurnWithOwned(adapter, instruction, mode))
-            : this.doTurnWithOwned(adapter, instruction, mode);
+            ? withGraphSessionAccess(this.projectDir, adapter, () => this.doTurnWithOwned(adapter, instruction, mode, completion))
+            : this.doTurnWithOwned(adapter, instruction, mode, completion);
     }
-    async doTurnWithOwned(adapter, instruction, mode = "builder") {
+    async doTurnWithOwned(adapter, instruction, mode = "builder", completion) {
         const ticket = mode === "builder" ? this.currentTicketId : undefined;
         const hostToolObservations = [];
         const scopedInstruction = (text) => !ticket || text.includes(`Ticket scope: ${ticket}.`) ? text
@@ -498,6 +500,11 @@ export class Foreman {
         let result = await send(instruction, turnPolicy);
         await this.observeBuilderNative(adapter);
         let status = parseStepStatus(result.text);
+        if (!result.isError && !result.failure) {
+            const completed = completion?.(result.text);
+            if (completed)
+                return { result, status: completed };
+        }
         if (ticket && validateBuildAssignment(ticket, status))
             return { result, status };
         if (result.isError || result.failure)
@@ -626,6 +633,11 @@ export class Foreman {
                 if (result.isError || result.failure)
                     return { result: { ...result, isError: true }, status: { kind: "blocked", reason: result.text } };
                 status = parseStepStatus(result.text);
+                if (completion) {
+                    const completed = completion(result.text);
+                    if (completed)
+                        return { result, status: completed };
+                }
                 if (ticket && validateBuildAssignment(ticket, status))
                     return { result, status };
             }
@@ -710,8 +722,8 @@ export class Foreman {
         this.preflightPlan = result.text;
     }
     /** Send one custom instruction through the same needs_input loop as a batch turn. */
-    async runInstruction(instruction) {
-        return this.doTurn(instruction);
+    async runInstruction(instruction, options = {}) {
+        return this.doTurnWith(this.builder, instruction, "builder", options.completion);
     }
     /** Ask an already-active role session to propose choices for its reported blocker. */
     async resolveBlocker(adapter, reason, mode = "builder") {

package/dist/hostGraphApplicability.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { QaContractCoverageV1, QaVerificationContractV1, QaContractCandidateV1 } from "rafi-spec";
+export declare const hostGraphApplicabilityV1Schema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    runId: z.ZodString;
+    ticketId: z.ZodString;
+    contractDigest: z.ZodString;
+    contractRevision: z.ZodNumber;
+    reviewAttemptId: z.ZodString;
+    reviewBasisDigest: z.ZodString;
+    sourceDigest: z.ZodString;
+    status: z.ZodEnum<{
+        unavailable: "unavailable";
+        disabled: "disabled";
+        unadopted: "unadopted";
+        "adopted-enabled": "adopted-enabled";
+    }>;
+    reason: z.ZodString;
+    observedAt: z.ZodString;
+}, z.core.$strip>;
+export type HostGraphApplicabilityV1 = z.infer<typeof hostGraphApplicabilityV1Schema>;
+export declare function isGraphQaCheck(check: QaVerificationContractV1["checks"][number]): boolean;
+export declare function findGraphQaChecks(contract: QaVerificationContractV1): QaVerificationContractV1["checks"];
+export declare function normalizeGraphQaChecks(candidate: QaContractCandidateV1): QaContractCandidateV1;
+export declare function createHostGraphApplicability(input: {
+    projectDir: string;
+    runId: string;
+    ticketId: string;
+    contract: QaVerificationContractV1;
+    reviewAttemptId: string;
+    reviewBasisDigest: string;
+    sourceDigest: string;
+    store: {
+        artifacts(kind: string): Array<{
+            digest: string;
+            value: unknown;
+        }>;
+        putArtifact(kind: string, value: unknown): string;
+    };
+}): {
+    result: HostGraphApplicabilityV1;
+    resultDigest: string;
+};
+export declare function applyHostGraphApplicability(coverage: QaContractCoverageV1, contract: QaVerificationContractV1, result: HostGraphApplicabilityV1, resultDigest: string, projectDir: string): QaContractCoverageV1;
+export declare function hostGraphApplicabilityDigestFromCoverage(coverage: QaContractCoverageV1, checkId: string): string | undefined;

package/dist/hostGraphApplicability.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { loadGraphConfig } from "./graph/config.js";
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const hostGraphApplicabilityV1Schema = z.object({
+    version: z.literal(1),
+    runId: z.string().min(1),
+    ticketId: z.string().min(1),
+    contractDigest: digest,
+    contractRevision: z.number().int().positive(),
+    reviewAttemptId: z.string().min(1),
+    reviewBasisDigest: digest,
+    sourceDigest: digest,
+    status: z.enum(["adopted-enabled", "disabled", "unadopted", "unavailable"]),
+    reason: z.string().max(2048),
+    observedAt: z.string().datetime(),
+});
+function graphText(check) {
+    return [check.expectedBehavior, ...check.expectedEvidence, ...check.applicability.requiredEvidence,
+        ...check.verification.flatMap(method => [method.expectedOutcome, ...(method.steps ?? []), ...(method.argv ?? [])])].join(" ");
+}
+export function isGraphQaCheck(check) {
+    return /\bgraphify(?:y)?\b|\brafi[- ]managed graph(?:ify)?\b|\bgraphify adoption\b|\bgraphify[- ](?:receipt|evidence|command)\b/i.test(graphText(check));
+}
+export function findGraphQaChecks(contract) {
+    return contract.checks.filter(isGraphQaCheck);
+}
+export function normalizeGraphQaChecks(candidate) {
+    const copy = structuredClone(candidate);
+    for (const check of copy.checks) {
+        if (!isGraphQaCheck(check))
+            continue;
+        check.origin = "invariant";
+        check.obligation = "mandatory";
+        check.timing = "postimplementation";
+        check.applicability = {
+            kind: "conditional",
+            predicate: "Rafi-managed Graphify is adopted and enabled for this project",
+            decisionOwner: "host",
+            requiredEvidence: ["Host-owned Graphify applicability observation"],
+        };
+    }
+    return copy;
+}
+export function createHostGraphApplicability(input) {
+    let status = "unavailable";
+    let reason = "Rafi-managed Graphify applicability could not be observed; Graphify is optional and direct source inspection remains authoritative.";
+    try {
+        const graph = loadGraphConfig(input.projectDir);
+        status = graph.enabled ? "adopted-enabled" : graph.reason === "disabled" ? "disabled" : "unadopted";
+        reason = graph.enabled
+            ? "Rafi-managed Graphify is explicitly adopted and enabled."
+            : `Rafi-managed Graphify is not required: ${graph.reason}.`;
+    }
+    catch (error) {
+        reason = `Rafi-managed Graphify applicability is unavailable (${error instanceof Error ? error.message.slice(0, 400) : String(error).slice(0, 400)}); direct source inspection remains authoritative.`;
+    }
+    const result = hostGraphApplicabilityV1Schema.parse({ version: 1, runId: input.runId, ticketId: input.ticketId, contractDigest: input.contract.contentDigest, contractRevision: input.contract.revision, reviewAttemptId: input.reviewAttemptId, reviewBasisDigest: input.reviewBasisDigest, sourceDigest: input.sourceDigest, status, reason, observedAt: new Date().toISOString() });
+    const existing = input.store.artifacts("host-graph-applicability").find(item => {
+        const parsed = hostGraphApplicabilityV1Schema.safeParse(item.value);
+        return parsed.success && JSON.stringify(parsed.data) === JSON.stringify(result);
+    });
+    return { result, resultDigest: existing?.digest ?? input.store.putArtifact("host-graph-applicability", result) };
+}
+export function applyHostGraphApplicability(coverage, contract, result, resultDigest, projectDir) {
+    const parsed = hostGraphApplicabilityV1Schema.parse(result);
+    if (parsed.contractDigest !== contract.contentDigest || parsed.contractRevision !== contract.revision || parsed.runId !== contract.runId || parsed.ticketId !== contract.workId || parsed.sourceDigest !== coverage.sourceDigest || parsed.reviewAttemptId !== coverage.attemptId || parsed.reviewBasisDigest !== coverage.inputBasisDigest)
+        throw new Error("Host Graphify applicability is not bound to the current contract, review, or source");
+    const checks = findGraphQaChecks(contract);
+    if (!checks.length)
+        return coverage;
+    const copy = structuredClone(coverage);
+    for (const check of checks) {
+        const index = copy.checks.findIndex(row => row.checkId === check.id);
+        if (parsed.status !== "adopted-enabled") {
+            const row = {
+                checkId: check.id,
+                applicability: "not-applicable",
+                predicateEvidence: [`Host-owned Graphify applicability: ${parsed.status}. ${parsed.reason}`],
+                outcome: "passed",
+                evidence: [{ procedure: "Rafi host-owned Graphify applicability observation", cwd: projectDir, runtime: "Rafi host", sourceDigest: parsed.sourceDigest, reference: `host-graph-applicability:${resultDigest}` }],
+            };
+            if (index < 0)
+                copy.checks.push(row);
+            else
+                copy.checks[index] = row;
+        }
+        else if (index >= 0) {
+            copy.checks[index].applicability = "applicable";
+            copy.checks[index].predicateEvidence = [...new Set([...(copy.checks[index].predicateEvidence ?? []), "Host-owned Graphify applicability: adopted-enabled."])];
+            copy.checks[index].evidence.push({ procedure: "Rafi host-owned Graphify applicability observation", cwd: projectDir, runtime: "Rafi host", sourceDigest: parsed.sourceDigest, reference: `host-graph-applicability:${resultDigest}` });
+        }
+    }
+    return copy;
+}
+export function hostGraphApplicabilityDigestFromCoverage(coverage, checkId) {
+    const reference = coverage.checks.find(row => row.checkId === checkId)?.evidence.find(item => item.reference.startsWith("host-graph-applicability:"))?.reference;
+    const value = reference?.slice("host-graph-applicability:".length);
+    return value && /^[a-f0-9]{64}$/.test(value) ? value : undefined;
+}

package/dist/hostQaAugmentation.d.ts

@@ -0,0 +1,18 @@
+import type { QaContractCoverageV1, QaVerificationContractV1 } from "rafi-spec";
+import { type HostQaComparisonV1 } from "./hostQaComparison.js";
+import { type HostGraphApplicabilityV1 } from "./hostGraphApplicability.js";
+/** Applies every host-owned coverage decision in one canonical order. */
+export declare function applyHostQaAugmentations(input: {
+    coverage: QaContractCoverageV1;
+    contract: QaVerificationContractV1;
+    projectDir: string;
+    hostComparison?: {
+        result: HostQaComparisonV1;
+        resultDigest: string;
+    };
+    hostGraph?: {
+        result: HostGraphApplicabilityV1;
+        resultDigest: string;
+    };
+    commandObservations?: unknown[];
+}): QaContractCoverageV1;

package/dist/hostQaAugmentation.js

@@ -0,0 +1,64 @@
+import { applyHostQaComparison } from "./hostQaComparison.js";
+import { applyHostGraphApplicability } from "./hostGraphApplicability.js";
+function commandObservationFor(check, observations) {
+    const command = check.verification.find(method => method.kind === "command");
+    const argv = command?.argv ?? [];
+    const kind = argv[0] === "npm" && argv[1] === "test" ? "npm-test" : argv[0] === "node" && argv[1] === "--test" ? "node-test" : undefined;
+    if (!kind)
+        return undefined;
+    return observations.find(observation => observation.kind === kind && observation.outcome === "completed" && observation.exitCode === 0 && typeof observation.spanId === "string");
+}
+function applyHostCommandObservations(coverage, contract, observations) {
+    const parsed = observations.filter((observation) => Boolean(observation && typeof observation === "object"));
+    const copy = structuredClone(coverage);
+    for (const check of contract.checks) {
+        const observation = commandObservationFor(check, parsed);
+        if (!observation)
+            continue;
+        const row = copy.checks.find(item => item.checkId === check.id);
+        if (!row || row.outcome === "failed")
+            continue;
+        row.outcome = "passed";
+        row.evidence = [...(row.evidence ?? []), {
+                procedure: "Rafi host-retained command observation",
+                cwd: ".",
+                runtime: "Rafi host",
+                sourceDigest: copy.sourceDigest,
+                reference: `host-command-span:${observation.spanId}`,
+            }];
+    }
+    return copy;
+}
+function applyBaselineAuthorities(coverage, contract) {
+    const copy = structuredClone(coverage);
+    for (const check of contract.checks) {
+        if (check.timing !== "preimplementation")
+            continue;
+        const baseline = contract.baseline.find(observation => observation.checkId === check.id && observation.status === "passed");
+        const row = copy.checks.find(item => item.checkId === check.id);
+        if (!baseline || !row || row.applicability !== "applicable" || row.outcome !== "passed")
+            continue;
+        if (row.evidence?.some(evidence => evidence.reference === baseline.evidenceDigest))
+            continue;
+        row.evidence = [...(row.evidence ?? []), {
+                procedure: "Rafi host-retained preimplementation baseline authority",
+                cwd: ".",
+                runtime: "Rafi host",
+                sourceDigest: copy.sourceDigest,
+                reference: baseline.evidenceDigest,
+            }];
+    }
+    return copy;
+}
+/** Applies every host-owned coverage decision in one canonical order. */
+export function applyHostQaAugmentations(input) {
+    let coverage = input.coverage;
+    coverage = applyBaselineAuthorities(coverage, input.contract);
+    if (input.commandObservations?.length)
+        coverage = applyHostCommandObservations(coverage, input.contract, input.commandObservations);
+    if (input.hostComparison)
+        coverage = applyHostQaComparison(coverage, input.contract, input.hostComparison.result, input.hostComparison.resultDigest, input.projectDir);
+    if (input.hostGraph)
+        coverage = applyHostGraphApplicability(coverage, input.contract, input.hostGraph.result, input.hostGraph.resultDigest, input.projectDir);
+    return coverage;
+}

package/dist/hostQaComparison.js

@@ -49,8 +49,9 @@ function isHostQaCheck(check) {
     const text = `${check.expectedBehavior} ${check.expectedEvidence.join(" ")} ${check.applicability.requiredEvidence.join(" ")}`;
     const hostScopeEvidence = check.applicability.requiredEvidence.some(evidence => /host[- ]owned.*scope comparison/i.test(evidence));
     const scopeSemantics = /scope/i.test(text) && /comparison/i.test(text) && /baseline|protected|approved scope|product changes/i.test(text);
+    const changedProductPaths = /changed product paths/i.test(text) && /host[- ]retained|baseline|bookkeeping|evidence exclusions/i.test(text);
     return !/documentation/i.test(text)
-        && (hostScopeEvidence || (check.applicability.decisionOwner === "host" && (/Rafi compares the final product paths/i.test(check.expectedBehavior) || scopeSemantics)));
+        && (hostScopeEvidence || changedProductPaths || (check.applicability.decisionOwner === "host" && (/Rafi compares the final product paths/i.test(check.expectedBehavior) || scopeSemantics)));
 }
 export function findHostQaCheck(contract) {
     return contract.checks.find(isHostQaCheck);

package/dist/qaBuildGate.js

@@ -14,7 +14,7 @@ import { WorkflowDb } from "./workflowDb.js";
 import { createRoleBuilder, readOnlyPermissionConfig } from "./agentRun.js";
 import { captureBuildSource, assertBuildAssignmentReconciled } from "./buildAssignment.js";
 import { createDisposableQaSnapshotAsync } from "./qaSnapshot.js";
-import { allocateStableCheckIds, authoritativeInventory, bindUniqueBaselineCheckIds, contractDigest, mapSnapshotWorkingDirectories, normalizeSnapshotPaths, renderVerificationContract, rewriteProviderHostScopeChecks } from "./qaVerificationContract.js";
+import { allocateStableCheckIds, authoritativeInventory, bindUniqueBaselineCheckIds, contractDigest, ensureHostScopeCheck, mapSnapshotWorkingDirectories, normalizeSnapshotPaths, renderVerificationContract, rewriteProviderHostScopeChecks } from "./qaVerificationContract.js";
 import { resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
 import { prepareVerificationContract } from "./qaPreparation.js";
 import { qaHostGraphFact } from "./qaHostFacts.js";
@@ -23,6 +23,7 @@ import { BUILDER_WORK_COVERAGE_INSTRUCTIONS } from "./qaContractCoverage.js";
 import { renderBuildWorkContext } from "./buildWorkContext.js";
 import { compareContractInputs } from "./qaContractFreshness.js";
 import { readBuildRuns } from "./buildRuns.js";
+import { normalizeGraphQaChecks } from "./hostGraphApplicability.js";
 /** A received response missing only continuity metadata is a bounded format defect. */
 export function preparationTurnPayload(turn) {
     const formatErrors = turn.continuityErrors ?? [];
@@ -129,7 +130,7 @@ async function ensureBuilderContractWithProvenance(projectDir, runId, workId, wo
             provider: builder.agent,
             store, now: Date.now, hostFacts: `${qaHostGraphFact(projectDir)}\n${deliveryFact}\nHost-owned baseline fact: Rafi captured the complete preimplementation per-file path manifest and will perform the exact unchanged-file and scope comparison. Its digest is ${preimplementationPathManifestDigest}. Do not require the provider to receive or reproduce the raw manifest; cite the retained host-preimplementation-source observation and assess the host comparison result instead. Do not author a provider-executed check for Rafi's host postimplementation path manifest, complete changed-path inventory, or unchanged-file comparison; Rafi performs that comparison outside the provider snapshot. Ordinary approved product paths, exports, and tests are not a material QA concern merely because the provider cannot prove whether they were present before implementation; Rafi owns that comparison. Do not reconstruct or disclose the full baseline. For current-branch additive tickets, a provider-authored or inferred request to test the branch with an already-completed sibling feature removed is not an applicable requirement when the approved scope says not to remove or reconstruct that sibling; verify the ticket's own behavior and tests against the shared baseline instead. Treat sibling-absence testing as binding only when the user explicitly approved that absence requirement. Escalate only an actual host-observed out-of-scope, destructive, protected-file, or requirement-relevant change.`,
             normalizeDraft: (draft, response) => {
-                const normalized = rewriteProviderHostScopeChecks(bindUniqueBaselineCheckIds(allocateStableCheckIds(draft)), hostBaseline.id);
+                const normalized = allocateStableCheckIds(bindUniqueBaselineCheckIds(rewriteProviderHostScopeChecks(normalizeGraphQaChecks(ensureHostScopeCheck(draft, hostBaseline.id)), hostBaseline.id)));
                 if (!normalized.baseline.some(observation => observation.id === hostBaseline.id))
                     normalized.baseline.unshift(structuredClone(hostBaseline));
                 for (const check of normalized.checks)

package/dist/qaContractCoverage.js

@@ -2,7 +2,7 @@ import { Ajv } from "ajv";
 import { qaContractCoverageV1Schema } from "rafi-spec";
 const coverageSchema = new Ajv({ allErrors: true }).compile(qaContractCoverageV1Schema);
 import { parsePreparationArtifact } from "./qaVerificationContract.js";
-export const COVERAGE_INSTRUCTIONS = `Return RAFI_QA_COVERAGE_START, one QaContractCoverageV1 JSON object, RAFI_QA_COVERAGE_END before the final status marker. The exact schema is ${JSON.stringify(qaContractCoverageV1Schema)}. Put every binding field at the TOP LEVEL, not inside a binding object, and copy the host-supplied binding values exactly. For each check use checkId (not id), applicability as applicable/not-applicable/unresolved, predicateEvidence as an array of strings, outcome as passed/failed/blocked/not-run, and evidence as an array of objects with procedure, cwd, runtime, sourceDigest and reference. For postimplementation evidence sourceDigest is the exact host-supplied sourceDigest, not an individual file hash. Unconditional checks cannot be marked not-applicable or unresolved; for an absence or non-impact check, mark it applicable and provide bounded inspection evidence showing that the absent change or impact was assessed. For independent QA coverage of an applicable passed preimplementation-only check, inspect its matching passed contract.baseline observation and set at least one evidence reference to that observation's exact evidenceDigest; the historical observation is bound to its original source, not the current source. Assess its relevance rather than inventing or claiming a new baseline. Host-owned checks whose applicability decisionOwner is host are the exception to provider execution: include the check truthfully as applicable/not-run with evidence that the host-owned comparison is pending, and do not block or fail QA over it; Rafi will execute the comparison and replace that row before accepting the pass. Before emitting qa_pass, run every other applicable mandatory check that is not backed by a passed retained baseline; do not leave such a provider-owned check as not-run merely because an earlier turn omitted it. If an exact required command is blocked by the provider shell policy, use a semantically equivalent permitted read-only procedure, record the substitution and limitation truthfully, and assess the same predicate; do not mark the check blocked merely because the literal command syntax was denied. If a required command is permitted and read-only, run it now and retain its bounded result. Do not add unsupported fields. Include every check with truthful applicability and concrete evidence. Missing, blocked, not-run, unresolved applicability, or failed provider-owned mandatory coverage cannot authorize normal completion. Builder coverage is a claim; final QA independently verifies it.`;
+export const COVERAGE_INSTRUCTIONS = `Return RAFI_QA_COVERAGE_START, one QaContractCoverageV1 JSON object, RAFI_QA_COVERAGE_END before the final status marker. The exact schema is ${JSON.stringify(qaContractCoverageV1Schema)}. Put every binding field at the TOP LEVEL, not inside a binding object, and copy the host-supplied binding values exactly. For each check use checkId (not id), applicability as applicable/not-applicable/unresolved, predicateEvidence as an array of strings, outcome as passed/failed/blocked/not-run, and evidence as an array of objects with procedure, cwd, runtime, sourceDigest and reference. For postimplementation evidence sourceDigest is the exact host-supplied sourceDigest, not an individual file hash. Unconditional checks cannot be marked not-applicable or unresolved; for an absence or non-impact check, mark it applicable and provide bounded inspection evidence showing that the absent change or impact was assessed. For independent QA coverage of an applicable passed preimplementation-only check, inspect its matching passed contract.baseline observation and set at least one evidence reference to that observation's exact evidenceDigest; the historical observation is bound to its original source, not the current source. Assess its relevance rather than inventing or claiming a new baseline. Graphify is optional evidence: do not install, refresh, scan, or claim Graphify execution unless the host says Rafi-managed Graphify is adopted and enabled. Host-owned Graphify applicability is authoritative; disabled, unadopted, or unavailable Graphify is not a QA blocker, while adopted-enabled Graphify is applicable and cannot be waived by provider output. Other host-owned checks whose applicability decisionOwner is host are the exception to provider execution: include the check truthfully as applicable/not-run with evidence that the host-owned comparison is pending, and do not block or fail QA over it; Rafi will execute the comparison and replace that row before accepting the pass. Before emitting qa_pass, run every other applicable mandatory check that is not backed by a passed retained baseline; do not leave such a provider-owned check as not-run merely because an earlier turn omitted it. If an exact required command is blocked by the provider shell policy, use a semantically equivalent permitted read-only procedure, record the substitution and limitation truthfully, and assess the same predicate; do not mark the check blocked merely because the literal command syntax was denied. If a required command is permitted and read-only, run it now and retain its bounded result. For command exit status, use the host-retained tool event's exitCode and bounded output when available; that is authoritative evidence, and you must not create an echo wrapper, compound command, or other shell scaffold solely to print a numeric status. Do not add unsupported fields. Include every check with truthful applicability and concrete evidence. Missing, blocked, not-run, unresolved applicability, or failed provider-owned mandatory coverage cannot authorize normal completion. Builder coverage is a claim; final QA independently verifies it.`;
 // The source and attempt binding do not exist until the implementation turn has finished.
 export const BUILDER_WORK_COVERAGE_INSTRUCTIONS = `Carry out the applicable contract checks and report your work and evidence honestly in your normal final response. When a check requires historical ordering, retain bounded output for each required step and an explicit ordering record while performing it; a later passing test cannot prove an earlier failing step. Do not emit RAFI_QA_COVERAGE JSON during this implementation turn or stop for coverage binding values. After the implementation turn, Rafi will capture the completed source and request a separate response-only coverage record with the exact host-owned bindings.`;
 export function parseContractCoverage(text) { return parsePreparationArtifact(text, "RAFI_QA_COVERAGE"); }
@@ -20,10 +20,15 @@ export function bindCoverageHostFields(coverage, contract, binding) {
     // Optional schema fields may be emitted as JSON null by providers. Null is
     // not a meaningful limitation, so omit only that representation variant;
     // non-string values elsewhere remain validation errors.
-    for (const check of copy.checks ?? [])
+    for (const check of copy.checks ?? []) {
+        // Some providers mirror the applicability token into outcome. Canonicalize
+        // that harmless representation mistake at the host boundary.
+        if (check.outcome === "not-applicable")
+            check.outcome = "not-run";
         for (const evidence of check.evidence ?? [])
             if (evidence.limitation === null)
                 delete evidence.limitation;
+    }
     copy.version = 1;
     copy.runId = contract.runId;
     copy.workId = contract.workId;
@@ -61,7 +66,11 @@ export function validateContractCoverage(contract, coverage, binding, requirePas
             issues.push(`Unconditional applicability cannot be waived ${row.checkId}`);
         if (row.applicability === "not-applicable" && !row.predicateEvidence?.length)
             issues.push(`Not-applicable requires predicate evidence ${row.checkId}`);
-        if (check.applicability.kind === "conditional" && row.applicability === "applicable" && !row.predicateEvidence?.length)
+        // Host-owned conditional predicates are resolved by the host augmentation
+        // after provider coverage is collected (for example Graphify adoption).
+        // Requiring provider predicate evidence here would make the host-owned,
+        // fail-open path block before the authoritative host observation exists.
+        if (check.applicability.kind === "conditional" && check.applicability.decisionOwner !== "host" && row.applicability === "applicable" && !row.predicateEvidence?.length)
             issues.push(`Conditional applicability requires predicate evidence ${row.checkId}`);
         if (requirePass && check.obligation === "mandatory" && (row.applicability === "unresolved" || row.applicability === "applicable" && row.outcome !== "passed"))
             issues.push(`Mandatory check incomplete ${row.checkId}: run its permitted verification now and resubmit passed evidence, or report a truthful blocked result for host recovery`);

package/dist/qaEffectiveConfig.d.ts

@@ -1,5 +1,6 @@
 import type { ResolvedAgentSettings } from "rafi-spec";
 export declare 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 declare const QA_COMMAND_DISCIPLINE: string;
 export declare function finalQaRoleInstructions(rules: string): string;
 export declare function loadQaPreparationPolicy(projectDir: string): import("special-agents").QaPreparationConfigV1;
 /** Resolve only explicit rule/skill content; never project secrets or mutable .rafi state. */