opencode-workflow-guard 1.18.0 → 1.19.0

package/src/lib/dogfood.ts

@@ -0,0 +1,147 @@
+import { dogfoodEvidence } from "./evidence.ts";
+import { getDogfoodDeployMatrix, getDogfoodRecordsForWorkspace, isDogfoodRequired } from "./state.ts";
+import { getCurrentGitCommitHash, getTrackedWorktreeFingerprint } from "./verify.ts";
+import type { DogfoodResult } from "./types.ts";
+
+export interface DogfoodGateResult {
+	required: boolean;
+	/** Matrix hosts still missing a fresh passing record. */
+	missingHosts: string[];
+	/** The record that satisfied the gate, when one did. */
+	matched?: DogfoodResult;
+	/** Every record counted toward the gate, one per host. */
+	matchedRecords?: DogfoodResult[];
+	/** Why the gate is unsatisfied, cause-attributed. */
+	reason?: string;
+	/** Evidence id of the matched record, for audit correlation. */
+	evidenceId?: string;
+}
+
+/**
+ * Why one record cannot count for this worktree, or undefined when it can.
+ *
+ * Each cause is named separately because they have different remedies. A
+ * missing fingerprint is an environment problem, a fingerprint mismatch is a
+ * stale run, and a commit mismatch is an unrecorded commit. Collapsing them
+ * into one message sends the agent looking for the wrong fix.
+ */
+function stalenessReason(record: DogfoodResult, commitHash: string | undefined, fingerprint: string | undefined): string | undefined {
+	if (!fingerprint) {
+		return "Worktree fingerprint could not be computed (git unavailable or worktree unreadable), so dogfood evidence cannot be bound to this worktree; resolve worktree readability and re-run the dogfood scenario.";
+	}
+	if (!record.worktreeFingerprint) {
+		return `The recorded dogfood run ('${record.scenarioId}') has no worktree fingerprint binding (recorded against an unreadable worktree); re-run the dogfood scenario and record it with record_dogfood.`;
+	}
+	if (record.worktreeFingerprint !== fingerprint) {
+		return `The recorded dogfood run ('${record.scenarioId}' on '${record.host.label}') does not match the current worktree contents (tracked content changed after the run); re-run the dogfood scenario and record it with record_dogfood.`;
+	}
+	if (record.commitHash && commitHash && record.commitHash !== commitHash) {
+		return `The recorded dogfood run ('${record.scenarioId}' on '${record.host.label}') is bound to commit ${record.commitHash.slice(0, 12)} but this worktree is at commit ${commitHash.slice(0, 12)}; re-run the dogfood scenario at the current commit and record it with record_dogfood.`;
+	}
+	return undefined;
+}
+
+/**
+ * Judges the dogfood gate for one worktree.
+ *
+ * Shared by PR preflight and `guard_status` so the two can never disagree about
+ * whether the gate is satisfied. Freshness is content-scoped, matching review:
+ * a record covers the tracked tree it ran against, so untracked scratch
+ * cleanup cannot invalidate it while any tracked edit or new commit does.
+ */
+export function evaluateDogfoodGate(root: string): DogfoodGateResult {
+	if (!isDogfoodRequired(root)) return { required: false, missingHosts: [] };
+	const matrix = getDogfoodDeployMatrix(root);
+	const records = getDogfoodRecordsForWorkspace(root);
+	const commitHash = getCurrentGitCommitHash(root);
+	const fingerprint = getTrackedWorktreeFingerprint(root);
+
+	if (records.length === 0) {
+		return {
+			required: true,
+			missingHosts: matrix.length > 0 ? matrix : ["this host"],
+			reason: "Passing dogfood evidence is required (requireDogfood); run the dogfood runner and record the result with record_dogfood.",
+		};
+	}
+
+	// Only the newest record per host can count. An older pass is superseded by
+	// a newer run of the same host, including a newer HOLD, so a stale pass
+	// cannot hide a regression the same host later found. A same-millisecond
+	// tie resolves to the HOLD regardless of arrival order: re-running is cheap,
+	// and trusting a stale pass is the failure that matters.
+	const newestPerHost = new Map<string, DogfoodResult>();
+	for (const record of records) {
+		const seen = newestPerHost.get(record.host.label);
+		if (!seen || record.timestamp > seen.timestamp) {
+			newestPerHost.set(record.host.label, record);
+		} else if (record.timestamp === seen.timestamp && seen.verdict === "pass" && record.verdict === "hold") {
+			newestPerHost.set(record.host.label, record);
+		}
+	}
+
+	const unmatched: string[] = [];
+	const held: DogfoodResult[] = [];
+	const stale: Array<{ record: DogfoodResult; reason: string }> = [];
+	const matchedRecords: DogfoodResult[] = [];
+	for (const [host, record] of newestPerHost) {
+		// A host outside the deploy matrix cannot block the gate, so its HOLD or
+		// staleness must not be reported as the reason: that would name the wrong
+		// remedy. Only in-scope hosts collect their cause.
+		const inScope = matrix.length === 0 || matrix.includes(host);
+		if (record.verdict !== "pass") {
+			if (inScope) {
+				held.push(record);
+				unmatched.push(host);
+			}
+			continue;
+		}
+		const reason = stalenessReason(record, commitHash, fingerprint);
+		if (reason) {
+			if (inScope) {
+				stale.push({ record, reason });
+				unmatched.push(host);
+			}
+			continue;
+		}
+		if (!inScope) continue;
+		matchedRecords.push(record);
+	}
+
+	if (matrix.length > 0) {
+		for (const host of matrix) if (!newestPerHost.has(host)) unmatched.push(host);
+	}
+
+	if (unmatched.length > 0) {
+		const missingHosts = [...new Set(unmatched)];
+		// A HOLD is more actionable than a matrix gap, so name it first.
+		if (held.length > 0) {
+			const first = held[0];
+			return {
+				required: true,
+				missingHosts,
+				reason: `The most recent dogfood run for host '${first.host.label}' ('${first.scenarioId}') returned HOLD${first.taxonomyClass ? ` with class '${first.taxonomyClass}'` : ""}; fix the finding and re-run before opening a PR.`,
+			};
+		}
+		if (stale.length > 0) {
+			return { required: true, missingHosts, reason: stale[0].reason };
+		}
+		const outsideMatrix = [...newestPerHost.keys()].filter((host) => !matrix.includes(host));
+		if (matrix.length > 0 && matchedRecords.length === 0 && outsideMatrix.length > 0) {
+			return {
+				required: true,
+				missingHosts,
+				reason: `Dogfood evidence was recorded for host(s) ${outsideMatrix.join(", ")}, which are not in the deploy matrix (${matrix.join(", ")}); run the dogfood scenario on each matrix host and record each result.`,
+			};
+		}
+		return {
+			required: true,
+			missingHosts,
+			reason: `Dogfood evidence is missing for host(s) ${missingHosts.join(", ")} in the deploy matrix (${matrix.join(", ")}); run the dogfood scenario on each and record each result with record_dogfood.`,
+		};
+	}
+
+	// Satisfied. Report the newest contributing record, and keep the per-host
+	// set so the caller can journal every host that was actually covered.
+	const newest = matchedRecords.reduce<DogfoodResult | undefined>((best, record) => !best || record.timestamp > best.timestamp ? record : best, undefined);
+	return { required: true, missingHosts: [], matched: newest, matchedRecords, evidenceId: newest ? dogfoodEvidence(newest).id : undefined };
+}

package/src/lib/evidence.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { ToolOutcome } from "./tool-outcomes.ts";
-import type { EvidenceRecord, EvidenceSubject, PolicyDecision, ReviewResult, VerifyResult } from "./types.ts";
+import type { DogfoodResult, EvidenceRecord, EvidenceSubject, PolicyDecision, ReviewResult, VerifyResult } from "./types.ts";
 import { isSameGitRepo } from "./project-config.ts";
 
 function evidenceId(kind: EvidenceRecord["kind"], observedAt: number, subject: EvidenceRecord["subject"], source: Record<string, unknown>): string {
@@ -19,6 +19,24 @@ export function reviewEvidence(result: ReviewResult): EvidenceRecord {
 	return { id: evidenceId("review", result.timestamp, subject, source), kind: "review", confidence: "attestation", observedAt: result.timestamp, subject, source };
 }
 
+export function dogfoodEvidence(result: DogfoodResult): EvidenceRecord {
+	const subject = { workspace: result.workspace, commitHash: result.commitHash, worktreeFingerprint: result.worktreeFingerprint, sessionID: result.sessionID, actor: result.host.label };
+	// The digest pair is part of the source, so replaying a passing run onto a
+	// different scenario or taxonomy changes the evidence id.
+	const source = {
+		verdict: result.verdict,
+		scenarioId: result.scenarioId,
+		scenarioSha256: result.scenarioSha256,
+		taxonomySha256: result.taxonomySha256,
+		taxonomyClass: result.taxonomyClass,
+		checks: result.checks,
+		runCount: result.runCount,
+		host: result.host,
+		gitStatus: result.gitStatus,
+	};
+	return { id: evidenceId("dogfood", result.timestamp, subject, source), kind: "dogfood", confidence: "attestation", observedAt: result.timestamp, subject, source };
+}
+
 export function toolOutcomeEvidence(outcome: ToolOutcome, observedAt: number, workspace?: string): EvidenceRecord {
 	const subject = { workspace, sessionID: outcome.sessionID, callID: outcome.callID };
 	const source = { tool: outcome.tool, status: outcome.status, durationMs: outcome.durationMs, repeatedFailureCount: outcome.repeatedFailureCount };

package/src/lib/guard-dispatcher.ts

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { audit, loadVerifyCache } from "./audit.ts";
 import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidence.ts";
 import { findGitRoot, isSameGitRepo, projectRootKey } from "./project-config.ts";
+import { evaluateDogfoodGate } from "./dogfood.ts";
 import {
 	getLastReviewResultForWorkspace,
 	getLiveControlPlaneRoots,
@@ -153,6 +154,17 @@ function logBlock(message: string, simulate = false): void {
 	} catch {}
 }
 
+/**
+ * Render a verification timeout limit for the block reason.
+ *
+ * Sub-second limits are exercised by tests, and a bare `Math.round(ms/1000)`
+ * reports those as "0s", which reads as no limit at all.
+ */
+function formatTimeoutLimit(timeoutMs: number | undefined): string {
+	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) return "the verification timeout";
+	return timeoutMs < 1000 ? `${timeoutMs}ms` : `${Math.round(timeoutMs / 1000)}s`;
+}
+
 export async function guardToolCallImpl(
 	toolName: string,
 	input: unknown,
@@ -256,10 +268,20 @@ export async function guardToolCallImpl(
 						const result = await runVerify(command, currentRoot, resolveVerifyTimeoutMs(currentRoot));
 						recordVerifyResult(command, result, sessionID, currentRoot);
 						if (!result.passed) {
-							const tail = snipVerifyOutput(result.output, result.passed).slice(-500);
-							const reason = `Blocked todowrite: all tasks marked done but verification is failing (${command}). Fix the failure before finishing; output tail: ${tail}`;
+							// A timeout is not a failing test. Both block
+							// finalization, but naming a failure sends the
+							// agent chasing an assertion that never ran, and
+							// the remedy is a longer limit rather than a code
+							// change. The tail is snipped as passing output on
+							// that path, because snipVerifyOutput labels a
+							// failing run with a "Verification Failed" header
+							// that would restate the misattribution.
+							const tail = snipVerifyOutput(result.output, result.timedOut === true).slice(-500);
+							const reason = result.timedOut
+								? `Blocked todowrite: verification did not finish within ${formatTimeoutLimit(result.timeoutMs)} so the result is unknown rather than failing (${command}). Raise the limit in the project .opencode/workflow-guard.json (verifyTimeoutMs) or with WORKFLOW_GUARD_VERIFY_TIMEOUT_MS, then complete the tasks again; output tail: ${tail}`
+								: `Blocked todowrite: all tasks marked done but verification is failing (${command}). Fix the failure before finishing; output tail: ${tail}`;
 							logPolicyBlock(`[workflow-guard] ${reason}`);
-							return block("verification", "verification_failed", reason);
+							return block("verification", result.timedOut ? "verification_timed_out" : "verification_failed", reason);
 						}
 					}
 				}
@@ -665,6 +687,35 @@ export async function guardToolCallImpl(
 				}
 			}
 			if (isDocumentationRequired(prRoot) && !branchHasDocumentationChange(prRoot)) preflightFailures.push("Documentation update is required (Policy 21); update README.md or relevant documentation in docs/.");
+			// Dogfood gate (pre-deployment evidence), off by default. The
+			// evaluation lives in lib/dogfood.ts so preflight and guard_status
+			// cannot disagree about whether the gate is satisfied.
+			const dogfoodGate = evaluateDogfoodGate(prRoot);
+			if (dogfoodGate.matched && !context?.simulate) {
+				audit({
+					ts: new Date().toISOString(),
+					sessionID: context?.sessionID,
+					tool: "pr-preflight.dogfood-binding",
+					decision: "allow",
+					phase: "event",
+					reason: "dogfood_evidence_matched",
+					evidence: {
+						evidenceId: dogfoodGate.evidenceId,
+						dogfoodScenarioId: dogfoodGate.matched.scenarioId,
+						dogfoodHost: dogfoodGate.matched.host.label,
+						// Journal every host the matrix required, not just the
+						// newest one. A single-host entry would understate a
+						// multi-host pass and mislead an auditor later.
+						dogfoodCoveredHosts: (dogfoodGate.matchedRecords ?? []).map((record) => record.host.label),
+						binding: {
+							workspace: projectRootKey(prRoot),
+							commitHash: getCurrentGitCommitHash(prRoot),
+							worktreeFingerprint: getTrackedWorktreeFingerprint(prRoot)?.slice(0, 16),
+						},
+					},
+				});
+			}
+			if (dogfoodGate.missingHosts.length > 0 && dogfoodGate.reason) preflightFailures.push(dogfoodGate.reason);
 			const branchChangelog = branchHasChangelogChange(prRoot);
 			let shellCwdKnown = true;
 			const prSegments: Array<{ segment: string; invocationRoot: string | null }> = [];

package/src/lib/state.ts

@@ -1,7 +1,7 @@
 import { existsSync, unlinkSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { audit, getReviewCacheFilePath, loadReviewCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
+import { audit, getDogfoodCacheFilePath, getReviewCacheFilePath, loadDogfoodCache, loadReviewCache, persistDogfoodCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
 import { findGitRoot, getCachedProjectConfig, isSameGitRepo, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
 import { normalizeLiveControlPlaneRoots } from "./live-control-plane.ts";
@@ -10,6 +10,7 @@ import type {
 	ProjectConfig,
 	VerifyResult,
 	ReviewResult,
+	DogfoodResult,
 } from "./types.ts";
 
 export let workspaceRoot = process.cwd();
@@ -454,6 +455,177 @@ export function resetReviewState(): void {
 	} catch {}
 }
 
+let dogfoodRecords: DogfoodResult[] = [];
+/**
+ * Retention per workspace and host. This bounds in-memory and merged history so
+ * one busy key cannot grow without limit. Only the newest record per key is ever
+ * durable, so this cap never decides what survives a restart.
+ */
+const MAX_DOGFOOD_RECORDS_PER_WORKSPACE_HOST = 3;
+
+/**
+ * Retention key. Workspace is part of the key because the durable cache is
+ * shared across repositories: keying on the host label alone would let a busy
+ * host in one repository evict another repository's record for the same label.
+ */
+function dogfoodRetentionKey(record: DogfoodResult): string {
+	return `${record.workspace ?? ""}\u0000${record.host.label}`;
+}
+
+function retainNewestPerWorkspaceHost(records: DogfoodResult[]): DogfoodResult[] {
+	const byKey = new Map<string, DogfoodResult[]>();
+	for (const record of records) {
+		const key = dogfoodRetentionKey(record);
+		byKey.set(key, [...(byKey.get(key) ?? []), record]);
+	}
+	return [...byKey.values()].flatMap((keyRecords) =>
+		keyRecords
+			.sort((left, right) => right.timestamp - left.timestamp)
+			.slice(0, MAX_DOGFOOD_RECORDS_PER_WORKSPACE_HOST),
+	);
+}
+
+/**
+ * Every dogfood record this process can see: memory plus the durable cache,
+ * deduplicated and retained. The eviction path and the read path must agree
+ * about which records exist, so both call this rather than the pieces.
+ */
+function mergedDogfoodRecords(): DogfoodResult[] {
+	return retainNewestPerWorkspaceHost(dedupeDogfoodRecords([...dogfoodRecords, ...loadDogfoodCache()]));
+}
+
+/**
+ * The records that may be durable, given everything currently known.
+ *
+ * One per workspace and host: the newest. Persisting an older pass would
+ * resurrect it after a restart even when a newer HOLD already superseded it,
+ * because the HOLD itself is never written to disk. Keeping only the newest
+ * record per key means a HOLD tombstones that key by leaving nothing behind.
+ */
+function durableDogfoodRecords(records: DogfoodResult[]): DogfoodResult[] {
+	const newest = new Map<string, DogfoodResult>();
+	for (const record of records) {
+		const key = dogfoodRetentionKey(record);
+		const seen = newest.get(key);
+		// A same-millisecond tie must resolve the same way the gate resolves it,
+		// to the HOLD. Otherwise a pass could be persisted alongside a HOLD that
+		// supersedes it, and a restart would serve the pass.
+		if (!seen || record.timestamp > seen.timestamp || (record.timestamp === seen.timestamp && record.verdict === "hold")) {
+			newest.set(key, record);
+		}
+	}
+	return [...newest.values()].filter((record) => record.verdict === "pass");
+}
+
+/**
+ * Records a dogfood run for a workspace.
+ *
+ * A HOLD is kept in memory so its taxonomy class stays diagnosable, and it is
+ * never persisted: caching a failed run would let a later preflight read it as
+ * evidence. A HOLD does evict that host's previously cached passes, because a
+ * restart would otherwise drop the in-memory HOLD and serve the older pass.
+ *
+ * Only the newest record per workspace and host is durable, but records for
+ * different hosts accumulate, because a deploy matrix needs one pass per host.
+ */
+export function recordDogfoodResult(result: Omit<DogfoodResult, "workspace" | "commitHash" | "gitStatus" | "worktreeFingerprint" | "timestamp"> & { workspace?: string }, targetSessionID?: string): DogfoodResult {
+	const root = projectRootKey(result.workspace ?? getWorkspaceRoot());
+	const stored: DogfoodResult = {
+		...result,
+		timestamp: Date.now(),
+		workspace: root,
+		commitHash: getCurrentGitCommitHash(root),
+		gitStatus: getGitStatusSummary(root),
+		// Bind to tracked content only, matching review: the dogfood run
+		// covered the change, and untracked scratch files are not part of it.
+		worktreeFingerprint: getTrackedWorktreeFingerprint(root),
+		sessionID: targetSessionID,
+	};
+	dogfoodRecords = retainNewestPerWorkspaceHost([stored, ...dogfoodRecords]);
+	// Only the newest record per workspace and host may be durable. A HOLD is
+	// never written, so it tombstones its key by leaving nothing behind. That
+	// also stops a later PASS for a different host from re-persisting a pass
+	// that a newer HOLD already superseded: after a restart the HOLD is gone,
+	// and that resurrected pass would re-open the gate on a held host.
+	//
+	// The durable set comes from merged state, never memory alone: in a cold
+	// process memory holds only the record just made, so using memory alone
+	// would delete every other host's cached pass.
+	const durable = durableDogfoodRecords(mergedDogfoodRecords());
+	// A failed write here is not cosmetic: after a HOLD it leaves the stale pass
+	// on disk, and a restart would serve it as evidence. Journal the failure so
+	// the durable state disagreeing with memory is visible.
+	if (!persistDogfoodCache(durable)) {
+		audit({
+			ts: new Date().toISOString(),
+			sessionID: targetSessionID,
+			tool: "dogfood.cache",
+			decision: "allow",
+			phase: "event",
+			reason: "dogfood_cache_write_failed",
+			evidence: { dogfoodVerdict: stored.verdict === "hold" ? "hold" : "pass", dogfoodHost: stored.host.label },
+		});
+	}
+	return stored;
+}
+
+/**
+ * Collapses records that describe the same run, so merging memory with disk
+ * does not double count. Retention and the durable cache both count records,
+ * so a duplicate would let itself evict a sibling host's only pass.
+ */
+function dedupeDogfoodRecords(records: DogfoodResult[]): DogfoodResult[] {
+	const seen = new Set<string>();
+	const unique: DogfoodResult[] = [];
+	for (const record of records) {
+		// Workspace is part of the identity: the cache is shared across
+		// repositories, so two runs of the same scenario on the same host label
+		// in different workspaces are distinct evidence. Verdict is part of it
+		// too, so a PASS and a HOLD recorded in the same millisecond stay
+		// distinct and the HOLD can win.
+		const identity = `${record.workspace ?? ""}\u0000${record.host.label}\u0000${record.scenarioId}\u0000${record.scenarioSha256}\u0000${record.taxonomyClass ?? ""}\u0000${record.verdict}\u0000${record.timestamp}\u0000${record.commitHash ?? ""}`;
+		if (seen.has(identity)) continue;
+		seen.add(identity);
+		unique.push(record);
+	}
+	return unique;
+}
+
+/**
+ * Candidate dogfood records for one worktree.
+ *
+ * Memory and disk are merged, so a pass recorded in a previous process is
+ * still a candidate next to one recorded now.
+ *
+ * Exact-worktree candidates win over same-repository ones, so a sibling
+ * worktree's run cannot displace this worktree's evidence. Same-repository
+ * candidates are returned when this worktree has none, which is what lets a
+ * run in a linked worktree satisfy the parent when the tracked content matches.
+ * Freshness is judged per record by the caller, never here.
+ */
+export function getDogfoodRecordsForWorkspace(root: string): DogfoodResult[] {
+	const workspace = projectRootKey(root);
+	const all = mergedDogfoodRecords().filter(
+		(result): result is DogfoodResult & { workspace: string } => result?.workspace != null,
+	);
+	const exact = all.filter((result) => projectRootKey(result.workspace) === workspace);
+	if (exact.length > 0) return exact;
+	return all.filter((result) => isSameGitRepo(result.workspace, root));
+}
+
+export function getLastDogfoodResultForWorkspace(root: string): DogfoodResult | undefined {
+	const records = getDogfoodRecordsForWorkspace(root);
+	return records.reduce<DogfoodResult | undefined>((best, result) => !best || result.timestamp > best.timestamp ? result : best, undefined);
+}
+
+export function resetDogfoodState(): void {
+	dogfoodRecords = [];
+	try {
+		const p = getDogfoodCacheFilePath();
+		if (existsSync(p)) unlinkSync(p);
+	} catch {}
+}
+
 export async function resolveEffectiveWorkspace(options: {
 	sessionID?: string;
 	directory?: string;
@@ -543,6 +715,54 @@ export function isDocumentationRequired(root: string): boolean {
 	return cfg.requireDocumentation === true;
 }
 
+/**
+ * Dogfood gate (pre-deployment evidence). Off by default, per the rule that
+ * every write path ships opt-in first: a repository opts in only once its
+ * runner exists, and an unset flag keeps today's PR behavior.
+ */
+export function isDogfoodRequired(root: string): boolean {
+	const env = process.env.WORKFLOW_GUARD_REQUIRE_DOGFOOD?.toLowerCase();
+	if (env === "0" || env === "false" || env === "off") return false;
+	if (env === "1" || env === "true" || env === "on") return true;
+	return getProjectConfig(root).requireDogfood === true;
+}
+
+/**
+ * Host labels that must each carry a passing dogfood record. Unset means the
+ * recorded host alone satisfies the gate, so a single-machine setup needs no
+ * matrix. Blank and duplicate labels are dropped; a non-array value is
+ * ignored rather than throwing, matching the other config readers.
+ */
+export function getDogfoodDeployMatrix(root: string): string[] {
+	const env = process.env.WORKFLOW_GUARD_DOGFOOD_DEPLOY_MATRIX;
+	const raw = env !== undefined && env.trim() !== "" ? env.split(",") : getProjectConfig(root).dogfoodDeployMatrix;
+	if (!Array.isArray(raw)) return [];
+	return [...new Set(raw.filter((value): value is string => typeof value === "string").map((value) => value.trim()).filter(Boolean))];
+}
+
+/**
+ * Dogfood recursion depth for this process. The runner sets
+ * `WORKFLOW_GUARD_DOGFOOD_DEPTH` on the actor it spawns, so the marker is
+ * inherited rather than handshaken. Unparseable or negative values fail
+ * closed to depth 1, because a corrupt marker must not read as a clean root.
+ */
+export function getDogfoodDepth(): number {
+	const env = process.env.WORKFLOW_GUARD_DOGFOOD_DEPTH;
+	if (env === undefined || env.trim() === "") return 0;
+	const parsed = Number(env.trim());
+	return Number.isInteger(parsed) && parsed >= 0 ? parsed : 1;
+}
+
+/**
+ * True when this process is a dogfood actor, that is, a session spawned by the
+ * runner to be tested. Every policy still applies; the marker only refuses
+ * self-certification and stops dogfood evidence from being persisted.
+ */
+export function isDogfoodActor(): boolean {
+	if (process.env.WORKFLOW_GUARD_DOGFOOD_ACTOR === "1") return true;
+	return getDogfoodDepth() > 0;
+}
+
 /**
  * Policy 25 (live-documentation research floor): enabled by default. The env
  * override mirrors `isReviewRequired`; project config can opt out. The floor

package/src/lib/types.ts

@@ -50,6 +50,19 @@ export interface ProjectConfig {
 	 */
 	requireSubagentReview?: boolean;
 	requireDocumentation?: boolean;
+	/**
+	 * Dogfood gate (pre-deployment evidence). Off by default: a repository
+	 * opts in once its runner exists. When true, PR preflight requires a fresh
+	 * passing dogfood record bound to the tree the PR would publish.
+	 */
+	requireDogfood?: boolean;
+	/**
+	 * Host labels that must each carry a fresh passing dogfood record before a
+	 * PR. Unset means the recorded host alone satisfies the gate. A matrix is
+	 * a configuration fact, not a code path: a Linux pass never vouches for
+	 * Windows.
+	 */
+	dogfoodDeployMatrix?: string[];
 	/**
 	 * Policy 25 (live-documentation research floor). Enabled by default: after
 	 * `liveDocFailureThreshold` failed tool calls with no live-documentation
@@ -120,9 +133,53 @@ export interface ReviewResult {
 
 export type EvidenceConfidence = "deterministic_observation" | "attestation" | "derived_state" | "agent_assertion";
 
+export type DogfoodVerdict = "pass" | "hold";
+
+/**
+ * One deterministic check row. `observed` is what the runner actually saw and
+ * `expected` is what the scenario declared, so a HOLD is diagnosable without
+ * re-running the scenario. `detail` carries the failing artifact excerpt.
+ */
+export interface DogfoodCheck {
+	id: string;
+	status: "pass" | "hold" | "skip";
+	expected?: string;
+	observed?: string;
+	detail?: string;
+}
+
+export interface DogfoodHost {
+	/** Stable per-machine label the deploy matrix is written against. */
+	label: string;
+	os?: string;
+	arch?: string;
+	opencodeVersion?: string;
+	actorModel?: string;
+	judgeModel?: string;
+	/** Hash of the staged harness tree the actor actually ran against. */
+	stagedTreeHash?: string;
+}
+
+export interface DogfoodResult {
+	verdict: DogfoodVerdict;
+	scenarioId: string;
+	scenarioSha256: string;
+	taxonomySha256: string;
+	taxonomyClass?: string;
+	checks: DogfoodCheck[];
+	runCount: number;
+	host: DogfoodHost;
+	timestamp: number;
+	workspace?: string;
+	commitHash?: string;
+	gitStatus?: string;
+	worktreeFingerprint?: string;
+	sessionID?: string;
+}
+
 export interface EvidenceRecord {
 	id: string;
-	kind: "verification" | "review" | "tool_outcome" | "policy_evaluation" | "lifecycle_state" | "agent_assertion";
+	kind: "verification" | "review" | "dogfood" | "tool_outcome" | "policy_evaluation" | "lifecycle_state" | "agent_assertion";
 	confidence: EvidenceConfidence;
 	observedAt: number;
 	subject: {
@@ -167,6 +224,12 @@ export interface AuditEntry {
 		};
 		allowLive?: boolean;
 		reviewVerdict?: "approved" | "changes_requested" | "rejected";
+		/** Dogfood verdicts: pass/hold are recorded, rejected is refused. */
+		dogfoodVerdict?: "pass" | "hold" | "rejected";
+		dogfoodScenarioId?: string;
+		dogfoodHost?: string;
+		/** Every host a satisfied deploy matrix covered, not just the newest. */
+		dogfoodCoveredHosts?: string[];
 		evidenceId?: string;
 		reviewer?: string;
 		reviewTimestamp?: number;

package/src/lib/v2-plugin.ts

@@ -41,7 +41,9 @@ import {
 	isLiveDocsRequired,
 	getLiveDocFailureThreshold,
 	getResearchToolPatterns,
+	isDogfoodRequired,
 } from "./state.ts";
+
 import {
 	openProjectMemory,
 	ensureProjectMemoryExcluded,
@@ -72,7 +74,7 @@ import { asRecord, showBlockToast, isSensitiveEnvKey } from "./utils.ts";
 import { loadedPluginVersion } from "./version.ts";
 import { clearContinuationState, continueUnfinishedSession, isGeneratedContinuationMessage, recordUserMessage } from "../policies/continuation.ts";
 import { createRecoveryCheckpoint, finalizeRecoveryCheckpoint, nextRecoveryRun } from "./checkpoint.ts";
-import { buildCompactionContext, guardToolCall } from "../workflow-guard.ts";
+import { buildCompactionContext, evaluateDogfoodGate, guardToolCall } from "../workflow-guard.ts";
 import { registerPluginInstance, releasePluginInstance } from "./plugin-instance.ts";
 import { claimToolCall, releaseToolCallClaim } from "./call-claims.ts";
 import { evaluatePermissionSeat } from "./permission-seat.ts";
@@ -459,6 +461,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 				projectMemoryEnabled,
 				learningEnabled,
 				recoveryCheckpointsEnabled: isRecoveryCheckpointsEnabled(effectiveRoot),
+				dogfoodRequired: isDogfoodRequired(effectiveRoot),
 				isReadOnly,
 			});
 			event.system.push({ type: "text", text: guidance });
@@ -518,6 +521,14 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 					`- Secondary Review: ${lastR.passed ? "APPROVED" : "CHANGES REQUESTED"} by ${lastR.reviewer}`,
 				);
 			}
+			const dogfoodCtxGate = evaluateDogfoodGate(effectiveRoot);
+			if (dogfoodCtxGate.required) {
+				stateLines.push(
+					dogfoodCtxGate.missingHosts.length === 0
+						? `- Dogfood Evidence: PASS on ${(dogfoodCtxGate.matchedRecords ?? []).map((record) => record.host.label).join(", ") || "recorded host"}`
+						: `- Dogfood Evidence: MISSING for ${dogfoodCtxGate.missingHosts.join(", ")} (required before PR creation)`,
+				);
+			}
 			let openFollowups: ReturnType<typeof listReviewFollowups> = [];
 			try { openFollowups = followupStore ? listReviewFollowups(followupStore, "open", 8) : []; } catch {}
 			if (openFollowups.length > 0) {