ai-foreman 1.7.27 → 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.d.ts

@@ -5,7 +5,7 @@ import type { AgentRoleDefaultsV1 } from "rafi-spec";
 import type { BranchPlan } from "../branch/types.js";
 import { type DeliveryConfig, type DeliveryStack } from "../tickets/delivery.js";
 import type { QaNonconvergenceContext, QaNonconvergenceDecision, QaReportRecoveryHandler } from "../qaReview.js";
-import { RunObserver } from "../observability.js";
+import { RunObserver, type ObservabilityMode } from "../observability.js";
 export declare function formatStartResumeCommand(executable: "ai-foreman", projectDir: string, steps: number, sessionId: string): string;
 export declare function formatResumeGuidance(executable: "rafi" | "ai-foreman", projectDir: string, steps: number, sessionId?: string, run?: {
     runId: string;
@@ -22,6 +22,7 @@ export declare function formatResumeGuidance(executable: "rafi" | "ai-foreman",
 export declare function savedStartArguments(command: Command, projectDir: string, opts: Record<string, unknown>): string[];
 /** Pure validation shared by interactive start and persisted preparation. */
 export declare function validateStartOptions(opts: Record<string, any>, requireCount: boolean): void;
+export declare function resolveAuditLoggingMode(cli: unknown, configured: unknown, environment?: string | undefined): ObservabilityMode;
 /** Preserve the distinction between a staged handoff and an unattempted acceptance. */
 export declare function recordHandoffAcceptanceNotAttempted(projectDir: string, runId: string, role: "builder" | "qa", generation: number, stage: string, detail: string): void;
 /** Default start selection is deliberately the same eligibility model users see in the ticket queue. */

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";
@@ -426,6 +426,20 @@ export function validateStartOptions(opts, requireCount) {
         throw new Error("Preparation launch requires both run and token");
     if (opts.launchToken && !opts.preparationRun && !opts.recoverRun)
         throw new Error("Launch token requires a preparation or recovery run");
+    if (opts.auditLogging !== undefined && !["off", "summary", "trace"].includes(String(opts.auditLogging)))
+        throw new Error("--audit-logging must be off, summary, or trace");
+}
+export function resolveAuditLoggingMode(cli, configured, environment = process.env.RAFI_AUDIT_LOGGING) {
+    const value = cli ?? configured ?? environment ?? "summary";
+    if (!["off", "summary", "trace"].includes(String(value)))
+        throw new Error("audit logging must be off, summary, or trace");
+    return String(value);
+}
+function configuredAuditLoggingMode(path) {
+    if (!existsSync(path))
+        return undefined;
+    const raw = parseYaml(readFileSync(path, "utf8"));
+    return raw?.observability?.mode === undefined ? undefined : resolveAuditLoggingMode(undefined, raw.observability.mode, undefined);
 }
 /** A current waiver is an already-recorded decision: surface it, never demand a second start-time approval. */
 function warnRiskPlanWaivers(projectDir, ticketIds) {
@@ -545,6 +559,7 @@ export function buildStartCommand(options = {}) {
         .option("--base <ref>", "base ref for root ticket branches (default: current branch or HEAD)")
         .option("--branch-prefix <prefix>", "branch name prefix for ticket branches")
         .option("--show-session-cost", "show authoritative cost or trustworthy cumulative session tokens for Builder and QA")
+        .option("--audit-logging <mode>", "host-owned audit logging (off | summary | trace)", "summary")
         .option("--hide-session-cost", "hide session cost/token usage for Builder and QA")
         .option("--auto-compact-threshold <percent>", "initial Builder context compaction threshold (1-99)")
         .option("--max-branch-depth <n>", "maximum selected branch stack depth", "5")
@@ -676,7 +691,20 @@ export function buildStartCommand(options = {}) {
             const readinessOwner = { project: cwd, runId: supervisedInvocationId, authority: localBuildAuthority(cwd) };
             const autoApprovePlanUpdates = recoveryRecord
                 ? 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)))
@@ -934,6 +962,8 @@ export function buildStartCommand(options = {}) {
                 ? recoveryExecutionTickets(recoveryRecord, requestedTicketIds, Boolean(opts.recoveryMode))
                 : selectedNewTicket ? [selectedNewTicket] : undefined;
             const config = loadConfig(join(cwd, "foreman.yaml"));
+            const auditLogging = resolveAuditLoggingMode(command.getOptionValueSource("auditLogging") === "cli" ? opts.auditLogging : undefined, configuredAuditLoggingMode(join(cwd, "foreman.yaml")));
+            const observabilityConfig = { ...config.observability, mode: auditLogging, enabled: auditLogging !== "off" };
             const stamp = new Date().toISOString().replace(/[:.]/g, "-");
             const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
             const log = new Log(logPath);
@@ -948,9 +978,9 @@ export function buildStartCommand(options = {}) {
                 console.error(`rafi: warning: ${qaResolution.deprecationWarning}`);
             const invocationRunId = supervisedInvocationId;
             let observabilityStore;
-            if (config.observability.enabled) {
+            if (observabilityConfig.enabled) {
                 try {
-                    observabilityStore = new ObservabilityStore(cwd, { config: config.observability });
+                    observabilityStore = new ObservabilityStore(cwd, { config: observabilityConfig });
                 }
                 catch (error) {
                     console.error(`rafi: observability unavailable; build will continue: ${String(error).replace(/\s+/g, " ").slice(0, 300)}`);
@@ -2384,7 +2414,7 @@ export function buildStartCommand(options = {}) {
                 observabilityStore?.enforceLimits();
                 observabilityStore?.maintainLogs(cwd);
                 observabilityStore?.close();
-                pruneRecoveryTelemetryAtCompletion(cwd, config.observability.detail_retention_days);
+                pruneRecoveryTelemetryAtCompletion(cwd, observabilityConfig.detail_retention_days);
                 activeObserver = undefined;
                 process.off("exit", finishObservationOnExit);
                 console.log("foreman: branch run summary");
@@ -2831,7 +2861,7 @@ export function buildStartCommand(options = {}) {
                 observabilityStore?.enforceLimits();
                 observabilityStore?.maintainLogs(cwd);
                 observabilityStore?.close();
-                pruneRecoveryTelemetryAtCompletion(cwd, config.observability.detail_retention_days);
+                pruneRecoveryTelemetryAtCompletion(cwd, observabilityConfig.detail_retention_days);
                 activeObserver = undefined;
                 process.off("exit", finishObservationOnExit);
                 console.log(`\n${accent("foreman:")} ${result.completed}/${result.requested} step(s) completed`);

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/config.js

@@ -84,9 +84,16 @@ export function loadConfig(path = "foreman.yaml") {
             ...(raw.notifications ?? {}),
         },
         qa: { ...DEFAULT_CONFIG.qa, ...(raw.qa ?? {}) },
-        observability: { ...DEFAULT_CONFIG.observability, ...(raw.observability ?? {}) },
+        observability: normalizeObservabilityConfig({ ...DEFAULT_CONFIG.observability, ...(raw.observability ?? {}) }),
     };
 }
+function normalizeObservabilityConfig(config) {
+    if (config.enabled === false)
+        return { ...config, mode: "off" };
+    if (config.mode === "off")
+        return { ...config, enabled: false };
+    return config;
+}
 function validateConfig(raw, path) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error(`${path}: expected a YAML object`);
@@ -123,17 +130,19 @@ function validateObservability(value, path) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error(`${path}: observability must be an object`);
     const input = value;
-    const keys = ["enabled", "sample_interval_seconds", "detail_retention_days", "log_retention_days", "detail_soft_limit_mb", "detail_hard_limit_mb", "log_limit_mb"];
+    const keys = ["enabled", "mode", "sample_interval_seconds", "detail_retention_days", "log_retention_days", "detail_soft_limit_mb", "detail_hard_limit_mb", "log_limit_mb"];
     for (const key of Object.keys(input))
         if (!keys.includes(key))
             throw new Error(`${path}: unknown observability setting ${key}`);
     if (input.enabled !== undefined && typeof input.enabled !== "boolean")
         throw new Error(`${path}: observability.enabled must be a boolean`);
-    for (const key of keys.filter((key) => key !== "enabled")) {
+    if (input.mode !== undefined && !["off", "summary", "trace"].includes(String(input.mode)))
+        throw new Error(`${path}: observability.mode must be off, summary, or trace`);
+    for (const key of keys.filter((key) => key !== "enabled" && key !== "mode")) {
         if (input[key] !== undefined && (!Number.isInteger(input[key]) || Number(input[key]) <= 0))
             throw new Error(`${path}: observability.${key} must be a positive integer`);
     }
-    const merged = { ...DEFAULT_OBSERVABILITY_CONFIG, ...input };
+    const merged = { ...DEFAULT_OBSERVABILITY_CONFIG, ...input, ...(input.enabled === false && input.mode === undefined ? { mode: "off" } : {}), ...(input.mode === "off" && input.enabled === undefined ? { enabled: false } : {}) };
     if (merged.detail_soft_limit_mb >= merged.detail_hard_limit_mb)
         throw new Error(`${path}: observability.detail_soft_limit_mb must be less than detail_hard_limit_mb`);
 }

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;