opencode-workflow-guard 1.18.1 → 1.19.0

package/README.md

@@ -43,9 +43,9 @@ WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run policy probes with Ope
 
 ## Core Guardrails Overview
 
-The plugin enforces **26 deterministic policy rules** across four main pillars:
+The plugin enforces **27 deterministic policy rules** across four main pillars:
 
-* **Branch & History Protection:** Enforces feature-branch workflows and blocks edits and commits on `main`/`master`. Direct and forced pushes to protected branches are hard-blocked. The guard checks mergeability before PR creation, requires secondary review approval bound to the reviewed worktree content, and requires a PR changelog or changeset.
+* **Branch & History Protection:** Enforces feature-branch workflows and blocks edits and commits on `main`/`master`. Direct and forced pushes to protected branches are hard-blocked. The guard checks mergeability before PR creation, requires secondary review approval bound to the reviewed worktree content, and requires a PR changelog or changeset. An opt-in dogfood gate can additionally require a recorded run of the change on real hardware before a PR opens.
 * **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks, which subagents inherit. A task can be marked completed only after its own recorded work. Review and investigation tasks use an audited `[read-only]` marker instead. The guard also blocks concurrent direct edits to the same canonical file across sessions. It requires a same-session fresh read before `edit`/`write` can replace an existing file. Silent task deletion is blocked, and task completion requires fresh test verification evidence. Completion claims and sweeping repository claims are journaled against their evidence. Repeated failures force a live-documentation lookup instead of a guess from training data.
 * **Secrets & Workspace Confinement:** Confines edit tools and recognized shell/git mutations to the workspace root, including symlink and `../` escape checks. Agent subshells have sensitive environment variables scrubbed, and `.env` reads return a safe schema mask. Arbitrary executables are not OS-sandboxed. Use containers or filesystem isolation when hard confinement is required.
 * **Destructive CLI & Environment Safety:** Intercepts destructive cloud, database, and infrastructure commands. Stops script laundering and interpreter evasion, blocks TTY hangs such as `vim`, `nano`, and `sudo`, and guards against dangerous package manager flags.
@@ -59,7 +59,7 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 Enforcement is only half the surface. The plugin also registers first-class agent tools under the same names on OpenCode 1.x and 2.x, so disciplined workflow is the path of least resistance:
 
 * **Task Planning:** `guard_next_tasks` surfaces durable repository planning context at session start or during planning. It reads `TODO.md`, `ROADMAP.md`, `PLAN.md`, `TASKS.md`, `BACKLOG.md`, their `docs/` counterparts, and plans under `docs/plans/`. `guard_status` reports active guardrails, branch protection, mutation counts, outstanding verification and review gates, a read-only git-hygiene snapshot, and the loaded `pluginVersion`.
-* **Review & Verification:** before PR creation, a secondary reviewer subagent evaluates the diff against `guard_review_rubric`. The rubric covers five axes: test integrity, task completeness, cleanliness, security, and platform. The reviewer records its verdict with `record_review`, and approvals bind to the reviewed worktree content.
+* **Review & Verification:** before PR creation, a secondary reviewer subagent evaluates the diff against `guard_review_rubric`. The rubric covers five axes: test integrity, task completeness, cleanliness, security, and platform. The reviewer records its verdict with `record_review`, and approvals bind to the reviewed worktree content. An opt-in dogfood gate adds a recorded end-to-end run on real hardware with `record_dogfood`.
 * **Worktree Isolation:** `guard_worktree_create` and `guard_worktree_cleanup` give parallel subagents isolated linked worktrees, so concurrent mutations never collide.
 * **Technical Debt:** `guard_review_followups` lists open P2/P3 durable review follow-ups. `guard_review_followup_resolve` closes one after the underlying issue is fixed and verified.
 * **Policy Simulation:** `guard_why` returns the structured policy decision for a tool call or command without performing it. `guard_audit` shows recent audited policy entries.
@@ -74,7 +74,7 @@ The context modules are project memory, Socratic learning, and recovery checkpoi
 
 | Guide | Description |
 |---|---|
-| [**Policy Reference**](docs/policies.md) | Specification of all 26 enforced policies, invariants, and the proactive tool surface (`guard_*`, `project_memory_*`, `learning_*`) |
+| [**Policy Reference**](docs/policies.md) | Specification of all 27 enforced policies, invariants, and the proactive tool surface (`guard_*`, `project_memory_*`, `learning_*`) |
 | [**Installation & Configuration**](docs/installation.md) | Setup options, global and local install, worktree isolation, and project configuration |
 | [**Static Policy Posture**](docs/policy-posture.md) | How the guard emits host-level policies for invariants a repository cannot lift. Covers both host envelopes (`experimental.policies` on 2.0.x, top-level `policies` on 2.1.x), precedence, and residual risk |
 | [**Managed Deployment**](docs/managed-deployment.md) | Administrator-managed OpenCode policy, platform locations, and startup diagnostics |

package/docs/installation.md

@@ -245,6 +245,29 @@ For stricter environments, set `requireSubagentReview: true` in `.opencode/workf
 
 ---
 
+## Pre-Deployment Dogfood Gate
+
+Policy 27 gates PR creation on a recorded run of the change on real hardware. It is **off by default**, because a gate is only meaningful once a repository has a runner that can produce a real run. Enable it after that runner exists:
+
+```json
+{
+  "requireDogfood": true,
+  "dogfoodDeployMatrix": ["bluefin", "windows-ci"]
+}
+```
+
+`WORKFLOW_GUARD_REQUIRE_DOGFOOD=1` enables the gate for any project, and `WORKFLOW_GUARD_REQUIRE_DOGFOOD=0` disables it even when project config enables it. `WORKFLOW_GUARD_DOGFOOD_DEPLOY_MATRIX` (comma-separated) overrides the matrix.
+
+The guard supplies the gate, the evidence record, and the recursion refusal. It does not spawn the actor session; the plugin may constrain, record, and explain, but it does not delegate. A repository supplies the runner, the frozen scenario bank, and the taxonomy, then records the outcome with `record_dogfood`.
+
+A recorded run binds to the commit hash and tracked-content worktree fingerprint of the directory it covered, exactly like review evidence. Commit every tracked change and run the scenario afterwards, so one pass satisfies both the review and dogfood gates. Only a `pass` verdict is durable, and only the newest record per workspace and host is kept. A `hold` stays diagnosable in memory with its taxonomy class and never becomes evidence. Recording a `hold` also discards that host's cached passes, so a process restart cannot re-open the gate on an older green run.
+
+Records accumulate, so a multi-host deploy matrix keeps one pass per host. Only the newest record per host counts. A newer `hold` on a host therefore reopens the gate even when that host passed earlier, so a later regression cannot hide behind an older green run. Retention and hold eviction are scoped to the workspace, so one repository's runs never touch another's evidence.
+
+The runner sets `WORKFLOW_GUARD_DOGFOOD_ACTOR=1` and `WORKFLOW_GUARD_DOGFOOD_DEPTH` on the session it spawns. That session runs the full plugin with every policy intact, and the marker only refuses `record_dogfood`, so a tested session cannot certify its own run.
+
+---
+
 ## Live-Documentation Research Floor
 
 Policy 25 is enabled by default. A session that accumulates failed tool calls with no live-documentation lookup since gets its next mutating or shell call blocked. The block holds until the agent consults a current source. Only non-research failures count, so a failed `websearch` never deepens the block. Reads, greps, and research tools are never gated.

package/docs/policies.md

@@ -142,6 +142,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
   - Active Git branch name and protected branch status.
   - Test verification status (passed/failed, test command, and commit hash).
   - Secondary review verdicts (reviewer name and approval status).
+  - Dogfood evidence state when Policy 27 is enabled, naming the deploy-matrix hosts still missing a passing run.
   - Uncommitted mutation counts.
 - Compacted project-memory context points back to `project_memory_search` for deeper historical retrieval instead of attempting to embed the full durable store.
 - Preserves policy-relevant context across session compactions without assigning, prioritizing, or sequencing tasks for the model.
@@ -203,6 +204,17 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - Uses the `experimental.text.complete` hook to compare a sweeping claim against this session's read coverage (`sessionReadFileCount`: distinct files read or authored). A sweeping claim backed by fewer than 2 touched files is journaled to the audit trail (`Sweeping claim '<phrase>' with N file(s) read`) and logged at info level.
 - **Observability, not gating**, matching Policy 24. The response is never blocked or rewritten, because a grep-heavy investigation can legitimately support "no other callers" while touching few files. Prior art covers the EPISTEMIC LEDGER "bare assertion" (arXiv 2602.07549) and the agent-control-tower false-completion study. Both find that more context does not fix overclaiming, and that the check belongs in the system, not in self-report.
 
+### 27. Pre-Deployment Dogfood Evidence (opt-in)
+- Gates PR creation on a recorded run of the change on real hardware. Off by default: a repository enables it with `.opencode/workflow-guard.json` (`requireDogfood: true`) or `WORKFLOW_GUARD_REQUIRE_DOGFOOD=1`, and disables it with `WORKFLOW_GUARD_REQUIRE_DOGFOOD=0`.
+- The guard owns the gate, the evidence record, and the recursion refusal. It does not spawn the actor session, because the plugin's scope excludes planning and delegation. A repository supplies its own runner, scenario bank, and frozen taxonomy, then records the outcome with `record_dogfood`.
+- **Evidence, not a receipt.** A run is recorded as `dogfood` evidence bound to the same subject as review evidence: workspace, commit hash, and tracked-content worktree fingerprint. Any tracked edit or new commit after the run makes the evidence stale, so the gate asks for a re-run rather than trusting a stale pass. No pre-commit layer is involved.
+- **A HOLD is never durable.** A `hold` verdict stays in memory so its taxonomy class is diagnosable, and it is never written to the disk cache. Only a `pass` is cached, so a failed run can never later read as evidence. Recording a HOLD also drops that host's cached passes, because otherwise a process restart would drop the in-memory HOLD and serve the older green run. The cache keeps only the newest record per workspace and host, so a HOLD leaves no record behind for its key and a later PASS on another host cannot resurrect the evicted one.
+- **A pass must be complete.** `record_dogfood` refuses a `pass` verdict when any check row is not `pass`, and refuses a record with no check rows at all. A skipped check is a HOLD by the design's own rule, so accepting it would let the gate pass by omission. An empty check list asserts nothing, so it is refused rather than read as a trivially complete pass. A HOLD must name a taxonomy class.
+- **Deploy matrix.** `dogfoodDeployMatrix` (or `WORKFLOW_GUARD_DOGFOOD_DEPLOY_MATRIX`, comma-separated) lists the host labels that each need a passing record. Unset means the recorded host alone satisfies the gate. Records accumulate rather than replacing each other, so one host's pass never overwrites another's. Only the newest record per host counts, which means a newer HOLD on a host reopens the gate even if that host passed earlier. Retention and HOLD eviction are keyed on workspace plus host, never globally, so repeated runs on a busy host cannot evict another host's only pass and a run in one repository never touches another's evidence. A host outside the matrix cannot block the gate, so its HOLD is never reported as the blocking cause. The disk cache keeps only the newest record per workspace and host, so a HOLD leaves no durable record for its key and a later PASS on a different host cannot resurrect an evicted pass.
+- **Recursion by refusal, not absence.** The runner sets `WORKFLOW_GUARD_DOGFOOD_ACTOR=1` and `WORKFLOW_GUARD_DOGFOOD_DEPTH` on the session it spawns. Every policy still applies in that session, and the plugin is present and enforcing. The marker only refuses `record_dogfood`, so the tested session cannot certify itself. An unparseable marker fails closed to a non-zero depth.
+- Freshness is content-scoped like the review gate, so a nested run in a linked worktree can inherit the binding for identical tracked content. A record for unrelated content never satisfies the gate.
+- `guard_status` reports `lastDogfood` and adds `dogfood` to `outstandingRequirements` when the gate is unsatisfied, naming the matrix hosts still missing a passing run.
+
 ### Tool Description Honesty & Cross-Model Adherence
 - Via the `tool.definition` hook, the guard enriches tool descriptions to keep them honest and proactive across all model families. The families are OpenAI, Gemini, Claude, and open-weights models:
   - `todowrite`: Explains its replacement-list lifecycle, finalization verification gate, and directs models to `guard_next_tasks` for roadmap discovery and `guard_status` for gate checks.
@@ -246,6 +258,14 @@ Besides enforcement hooks, the guard registers companion tools in OpenCode:
 - **Durable Lower-Priority Follow-ups:** Accepted review summaries containing a P2 or P3 finding are persisted in the project's local Workflow Guard SQLite database. Open findings are included in compacted agent context. They remain open across sessions until explicitly resolved with `guard_review_followup_resolve`, and they are not silently discarded with the review session.
 - **Privacy-Safe Local Telemetry:** Guard decisions remain in the local audit JSONL. Tool after-hook observations add `callID` and duration records for local diagnosis and performance analysis. The current hook API does not distinguish success from every failure path, so these records do not claim a success outcome. Command and patch bodies are never written to the journal. Only their byte count and SHA-256 fingerprint are retained for correlation.
 
+### `record_dogfood`
+- Records a pre-deployment dogfood run for Policy 27: `record_dogfood(scenarioId, scenarioSha256, taxonomySha256, verdict, checks, hostLabel, ...)`.
+- `checks` is a JSON array of `{id, status, expected, observed, detail}` rows. `expected` sits beside `observed` so a HOLD is diagnosable from the record alone, without re-running the scenario.
+- The verdict binds to the recording session's resolved directory, or to an explicit `directory`. It is refused, loudly and without recording, when no tracked-content fingerprint can be computed for that directory.
+- A `pass` requires every check to be `pass`, and a `hold` must name a taxonomy class. A record with no check rows is refused: an empty list asserts nothing about the run. Every refusal is journaled under `record_dogfood.verdict` with `decision: "block"`.
+- A session carrying `WORKFLOW_GUARD_DOGFOOD_ACTOR=1` or a non-zero `WORKFLOW_GUARD_DOGFOOD_DEPTH` is refused. The tested session cannot certify its own run.
+- The recorded digest pair is part of the evidence source, so replaying a passing run onto a different scenario or taxonomy changes the evidence id.
+
 ---
 
 ## Overrides ("Unless Otherwise Specified")

package/docs/testing.md

@@ -57,4 +57,5 @@ npm run test:all
 | **V2 Todo Capability** | Verifies the `todowrite` registry probe (`available` / `unavailable` / `unknown`), that an empty history gates only when planning is possible, the once-per-session fail-open warning and audit record, and `todoCapability` in `guard_status`. |
 | **Per-Task Completion Evidence** | Verifies a task cannot move to `completed` without a mutation in its own window, that one mutation cannot vouch for several completions, that staggered windows reject a claim whose window saw no work, that mutations before a task became active never count, that `[read-only]` completes freely and is journaled, that the marker can be appended to an already-planned task without tripping the no-silent-deletion rule, that duplicate content cannot hide a new completion, and that `guard_why` reports the same verdict while moving no window. |
 | **Static Policy Posture** | Verifies the emitted posture is deny-only, emits both host envelopes (`experimental.policies`/`permission` for 2.0.x, top-level `policies`/`tool.use` for 2.1.x), requires both to reach the same verdict for every probed resource, and matches the intended commands under a replica of the host's whole-string glob matcher, including the compound-command evasion it does not cover. |
+| **Dogfood Gate (Policy 27)** | Verifies the gate stays off until a repository opts in, that PR creation is blocked without fresh evidence and allowed with it, that a tracked edit and a new commit each invalidate the record with a named cause, that a HOLD is never durable and removes that host's cached pass so a restart cannot re-satisfy the gate, that a same-millisecond HOLD and PASS resolve to the HOLD in the durable cache so a restart stays unsatisfied, that a later pass on another host cannot resurrect an evicted one, that a HOLD in a cold process or in another workspace leaves unrelated hosts' passes intact, that an out-of-matrix HOLD is not reported as the blocking cause, that a `pass` is refused when any check is skipped or the check list is empty, that a HOLD must name a taxonomy class, that an actor session cannot record its own verdict, that the deploy matrix needs one fresh pass per host, that a newer HOLD on a host reopens the gate, that the PR audit names every covered host, and that per-host retention cannot evict another host's pass. |
 | **Modular Exports & Shape** | Verifies V1 `PluginModule` `{ id, server }` structure, modular policy imports, and `output.args` hook contract. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",
@@ -50,7 +50,7 @@
     "prepublishOnly": "npm run typecheck"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.19.3",
+    "@opencode-ai/plugin": "1.19.4",
     "@opencode/ai": "2.2.0",
     "@opencode/plugin": "2.2.0",
     "@opentui/solid": "0.7.0",

package/src/lib/audit.ts

@@ -1,9 +1,9 @@
-import { appendFileSync, chmodSync, existsSync, mkdirSync, openSync, readSync, closeSync, renameSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, openSync, readSync, closeSync, renameSync, statSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { Database, type SqliteDatabase } from "./sqlite.ts";
-import type { AuditEntry, PolicyDecision, VerifyResult, ReviewResult } from "./types.ts";
+import type { AuditEntry, PolicyDecision, VerifyResult, ReviewResult, DogfoodResult } from "./types.ts";
 import { asRecord } from "./utils.ts";
 
 const AUDIT_DIR = join(
@@ -15,6 +15,7 @@ const AUDIT_FILE = join(AUDIT_DIR, "workflow-guard.jsonl");
 const VERIFY_CACHE_FILE = join(AUDIT_DIR, "last-verify.json");
 const VERIFY_HISTORY_FILE = join(AUDIT_DIR, "verify-history.jsonl");
 const REVIEW_CACHE_FILE = join(AUDIT_DIR, "last-review.json");
+const DOGFOOD_CACHE_FILE = join(AUDIT_DIR, "last-dogfood.json");
 const MAX_AUDIT_BYTES = 4 * 1024 * 1024;
 const RETAIN_AUDIT_BYTES = 2 * 1024 * 1024;
 const MAX_VERIFY_HISTORY_BYTES = 1024 * 1024;
@@ -67,6 +68,10 @@ export function getReviewCacheFilePath(): string {
 	return REVIEW_CACHE_FILE;
 }
 
+export function getDogfoodCacheFilePath(): string {
+	return DOGFOOD_CACHE_FILE;
+}
+
 function appendBoundedJsonlUnlocked(path: string, value: unknown, maxBytes: number, retainBytes: number): void {
 	appendFileSync(path, JSON.stringify(value) + "\n", { encoding: "utf8", mode: 0o600 });
 	chmodSync(path, 0o600);
@@ -188,6 +193,51 @@ export function loadReviewCache(): ReviewResult | undefined {
 	return undefined;
 }
 
+/**
+ * Persists the passing dogfood records. Only passes are durable: a HOLD stays
+ * in memory so the taxonomy is diagnosable without a failed run later reading
+ * as evidence. Records are kept as an array, because a deploy matrix needs one
+ * pass per host.
+ *
+ * Never throws: a cache write must not break a tool call. A failure returns
+ * false so the caller can journal it, because a failed HOLD eviction would
+ * otherwise leave a stale pass that re-opens the gate after a restart.
+ */
+export function persistDogfoodCache(dogfoodData: DogfoodResult[]): boolean {
+	try {
+		// An empty list means no passing evidence remains, so the file is
+		// removed rather than left as an empty array. A hold on the only host
+		// must leave no durable evidence behind.
+		if (dogfoodData.length === 0) {
+			if (existsSync(DOGFOOD_CACHE_FILE)) unlinkSync(DOGFOOD_CACHE_FILE);
+			return true;
+		}
+		mkdirSync(AUDIT_DIR, { recursive: true });
+		writeFileSync(DOGFOOD_CACHE_FILE, JSON.stringify(dogfoodData, null, 2), { encoding: "utf8", mode: 0o600 });
+		chmodSync(DOGFOOD_CACHE_FILE, 0o600);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Loads durable passing dogfood records from disk. A cache written by an older
+ * single-record format is read as a one-element list rather than discarded.
+ */
+export function loadDogfoodCache(): DogfoodResult[] {
+	try {
+		if (!existsSync(DOGFOOD_CACHE_FILE)) return [];
+		const raw = readFileSync(DOGFOOD_CACHE_FILE, "utf8");
+		const data = JSON.parse(raw);
+		const candidates = Array.isArray(data) ? data : [data];
+		return candidates.filter((entry): entry is DogfoodResult =>
+			Boolean(entry) && typeof entry.scenarioId === "string" && typeof entry.timestamp === "number" && entry.verdict === "pass",
+		);
+	} catch {}
+	return [];
+}
+
 /**
  * Reads recent audit entries from the end of the JSONL audit log with a bounded
  * buffer window to prevent memory spikes on long-lived installations.

package/src/lib/custom-tools.ts

@@ -1,7 +1,7 @@
 import { tool } from "@opencode-ai/plugin";
 import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
-import type { AuditEntry, LearningEvidenceKind } from "./types.ts";
+import type { AuditEntry, DogfoodCheck, DogfoodResult, LearningEvidenceKind } from "./types.ts";
 import type { ProjectMemoryStore } from "./project-memory.ts";
 import {
 	exportProjectKnowledge,
@@ -13,22 +13,26 @@ import {
 	searchProjectMemory,
 } from "./project-memory.ts";
 import { loadLearnerProfile, recordLearningEvidence, selectLearningOpportunity, updateLearnerProfile } from "./learning.ts";
-import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidence.ts";
+import { isEvidenceFresh, dogfoodEvidence, reviewEvidence, verificationEvidence } from "./evidence.ts";
 import {
 	getLearningInterventionBudget,
 	getOperationProfile,
 	getProjectConfig,
 	getRalphMaxIterations,
+	getLastDogfoodResultForWorkspace,
+	getDogfoodDeployMatrix,
 	getLastReviewResultForWorkspace,
 	getLastVerifyResultForWorkspace,
 	getWorkspaceMutationCount,
 	getWorkspaceMutationTimestamp,
 	getWorkspaceRoot,
+	isDogfoodActor,
 	isDocumentationRequired,
 	isRecoveryCheckpointsEnabled,
 	isRalphModeEnabled,
 	isReviewRequired,
 	isSubagentReviewRequired,
+	recordDogfoodResult,
 	recordMutation,
 	recordReviewResult,
 	resolveEffectiveWorkspace,
@@ -39,6 +43,7 @@ import { getRalphOutcome } from "../policies/continuation.ts";
 import { todoEvidenceReport } from "../policies/todo.ts";
 import { findGitRoot, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { detectVerifyCommand, getCurrentGitCommitHash, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
+import { evaluateDogfoodGate } from "./dogfood.ts";
 import { buildReviewRubric } from "./review.ts";
 import { createGitWorktree, cleanupGitWorktree, validateHostWorktreeDirectory } from "./worktree.ts";
 import type { HostWorktreePort } from "./host-worktree.ts";
@@ -73,6 +78,12 @@ export function buildWorkflowGuardSystemGuidance(options: {
 	projectMemoryEnabled?: boolean;
 	learningEnabled?: boolean;
 	recoveryCheckpointsEnabled?: boolean;
+	/**
+	 * Whether this repository's PR preflight also requires dogfood evidence.
+	 * Reported only when the gate is enabled, so an unopted repository never
+	 * advertises a requirement it does not have.
+	 */
+	dogfoodRequired?: boolean;
 	isReadOnly?: boolean;
 }): string {
 	const sections: string[] = [
@@ -106,6 +117,12 @@ export function buildWorkflowGuardSystemGuidance(options: {
 		);
 	}
 
+	if (options.dogfoodRequired && !options.isReadOnly) {
+		sections.push(
+			"- Dogfood Gate: This repository requires a recorded end-to-end run on real hardware before a PR opens. Run the repository's dogfood runner for the change, then record the observed checks with `record_dogfood`. Commit first: the evidence binds to the commit and tracked worktree content, so a later tracked edit or commit makes it stale.",
+		);
+	}
+
 	if (options.recoveryCheckpointsEnabled) {
 		sections.push(
 			"- Recovery: If workspace state needs rollback to the pre-run checkpoint, use `guard_recovery_restore`.",
@@ -272,9 +289,16 @@ export function createCustomTools(options: {
 				// while any tracked edit or new commit does.
 				const reviewFresh = Boolean(lastR && reviewEvidenceRecord && lastR.passed && isEvidenceFresh(reviewEvidenceRecord, { ...subject, worktreeFingerprint: getTrackedWorktreeFingerprint(root), sessionID: lastR.targetSessionID }, 0));
 				const documentationRequired = isDocumentationRequired(root);
+				// Dogfood is evaluated through the same helper the PR preflight
+				// uses, so the two can never disagree about the gate.
+				const dogfoodGate = evaluateDogfoodGate(root);
+				const lastD = dogfoodGate.matched ?? getLastDogfoodResultForWorkspace(root);
+				const lastDogfoodEvidence = lastD ? dogfoodEvidence(lastD) : undefined;
+				const dogfoodFresh = Boolean(dogfoodGate.required && dogfoodGate.missingHosts.length === 0);
 				const outstandingRequirements = [
 					...(verifyCommand && !verifyFresh ? ["verification"] : []),
 					...(reviewRequired && !reviewFresh ? ["review"] : []),
+					...(dogfoodGate.required && !dogfoodFresh ? ["dogfood"] : []),
 					...(documentationRequired && !branchHasDocumentationChange(root) ? ["documentation"] : []),
 				];
 				const recommendedActions: string[] = [];
@@ -284,6 +308,9 @@ export function createCustomTools(options: {
 				if (outstandingRequirements.includes("review")) {
 					recommendedActions.push("Call guard_review_rubric to retrieve the 5-axis review rubric, then spawn a secondary reviewer subagent via task to evaluate changes and record verdict with record_review.");
 				}
+				if (outstandingRequirements.includes("dogfood")) {
+					recommendedActions.push(`Run the repository's dogfood runner for this change, then record the result with record_dogfood.${dogfoodGate.missingHosts.length > 0 ? ` Hosts still missing a passing run: ${dogfoodGate.missingHosts.join(", ")}.` : ""}`);
+				}
 				if (outstandingRequirements.includes("documentation")) {
 					recommendedActions.push("Update documentation files (e.g. README.md, docs/) to satisfy the documentation gate before opening a PR.");
 				}
@@ -297,7 +324,7 @@ export function createCustomTools(options: {
 				}
 				const ralphOutcome = runWithRuntimeState(root, client, () => getRalphOutcome(toolContext.sessionID));
 				const taskEvidence = await runWithRuntimeState(root, client, () => todoEvidenceReport(toolContext.sessionID));
-				return JSON.stringify({ pluginVersion: loadedPluginVersion() ?? null, qualifiedHostVersion: qualifiedHostVersion() ?? null, hostVersion: hostVersion?.() ?? null, workspaceRoot: root, branch, onProtectedBranch: isProtected, todoCapability: todoCapability ? todoCapability() : "available", taskEvidence, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, requireSubagentReview: isSubagentReviewRequired(root), recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) }, gitHygiene: gitHygieneSnapshot(root) ?? null }, null, 2);
+				return JSON.stringify({ pluginVersion: loadedPluginVersion() ?? null, qualifiedHostVersion: qualifiedHostVersion() ?? null, hostVersion: hostVersion?.() ?? null, workspaceRoot: root, branch, onProtectedBranch: isProtected, todoCapability: todoCapability ? todoCapability() : "available", taskEvidence, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, lastDogfood: lastD && lastDogfoodEvidence ? { scenarioId: lastD.scenarioId, verdict: lastD.verdict, host: lastD.host.label, taxonomyClass: lastD.taxonomyClass ?? null, runCount: lastD.runCount, fresh: dogfoodGate.required ? dogfoodFresh : null, evidenceId: lastDogfoodEvidence.id, missingHosts: dogfoodGate.missingHosts, coveredHosts: (dogfoodGate.matchedRecords ?? []).map((record) => record.host.label) } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, requireSubagentReview: isSubagentReviewRequired(root), requireDogfood: dogfoodGate.required, dogfoodDeployMatrix: dogfoodGate.required ? getDogfoodDeployMatrix(root) : [], recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) }, gitHygiene: gitHygieneSnapshot(root) ?? null }, null, 2);
 			},
 		}),
 		guard_audit: tool({ description: "View recent audit entries recorded by opencode-workflow-guard. Use to diagnose policy decisions, blocked commands, or outcome telemetry.", args: { limit: tool.schema.number().optional().describe("Maximum entries to return (default 10)") }, execute: async (args) => JSON.stringify(getRecentAuditEntries(typeof args?.limit === "number" ? Math.min(args.limit, 50) : 10), null, 2) }),
@@ -371,6 +398,130 @@ export function createCustomTools(options: {
 					: `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}. ${boundTo} ${recorderNote}`;
 			},
 		}),
+		record_dogfood: tool({
+			description: "Record the verdict of a dogfood run: a change exercised end to end on real hardware before deployment. The runner produces the checks and the transcript; this tool binds the result to the repository content it ran against. A HOLD records the taxonomy class so the failure is diagnosable. Actor sessions spawned by the runner cannot record their own verdict.",
+			args: {
+				scenarioId: tool.schema.string().describe("Scenario identifier the actor ran, for example 'permission-rule-reorder'"),
+				scenarioSha256: tool.schema.string().describe("SHA-256 of the scenario file the actor ran, so the evidence names the frozen input"),
+				taxonomySha256: tool.schema.string().describe("SHA-256 of the frozen taxonomy file the judge classified against"),
+				verdict: tool.schema.string().describe("'pass' when every deterministic check passed, otherwise 'hold'"),
+				checks: tool.schema.string().describe("JSON array of check rows: [{id, status: 'pass'|'hold'|'skip', expected, observed, detail}]"),
+				hostLabel: tool.schema.string().describe("Stable host label the deploy matrix is written against, for example 'bluefin'"),
+				taxonomyClass: tool.schema.string().optional().describe("Taxonomy class naming why a HOLD happened; omit on a pass"),
+				runCount: tool.schema.number().optional().describe("Number of runs behind this verdict (default 1); single runs are flaky"),
+				hostOs: tool.schema.string().optional().describe("Host OS reported by the run"),
+				hostArch: tool.schema.string().optional().describe("Host architecture reported by the run"),
+				opencodeVersion: tool.schema.string().optional().describe("OpenCode version the actor session ran under"),
+				actorModel: tool.schema.string().optional().describe("Model pin used for the actor session"),
+				judgeModel: tool.schema.string().optional().describe("Model pin used for the judge session"),
+				stagedTreeHash: tool.schema.string().optional().describe("Hash of the staged harness tree the actor exercised"),
+				directory: tool.schema.string().optional().describe("Repository directory the run covered. Pass it explicitly when the recorder session has no workspace binding."),
+			},
+			execute: async (args, toolContext) => {
+				const auditVerdict = (verdict: "pass" | "hold" | "rejected", reason: string, binding?: NonNullable<AuditEntry["evidence"]>["binding"]) => audit({ ts: new Date().toISOString(), sessionID: toolContext.sessionID, tool: "record_dogfood.verdict", decision: verdict === "rejected" ? "block" : "allow", phase: "event", reason, evidence: { dogfoodVerdict: verdict, ...(binding ? { binding } : {}) } });
+				// The tested session cannot certify itself. The marker is set by
+				// the runner on the actor it spawns, so this is a refusal, not an
+				// absence: the plugin is present and enforcing in that session.
+				if (isDogfoodActor()) {
+					auditVerdict("rejected", "dogfood_actor_self_certification", { recorderSessionID: toolContext?.sessionID });
+					return `[workflow-guard] Dogfood record rejected: this session is a dogfood actor (WORKFLOW_GUARD_DOGFOOD_ACTOR/DEPTH is set), and the tested session cannot certify itself. The parent runner session records the verdict from the checks it observed.`;
+				}
+				const verdict = args.verdict.trim().toLowerCase();
+				if (verdict !== "pass" && verdict !== "hold") {
+					auditVerdict("rejected", "invalid_dogfood_verdict");
+					return "[workflow-guard] Dogfood record rejected: verdict must be 'pass' or 'hold'.";
+				}
+				// Empty identifiers would make the record unattributable: a scenario
+				// id names the frozen input, and a host label is what the deploy
+				// matrix is written against.
+				if (!args.scenarioId.trim() || !args.hostLabel.trim()) {
+					auditVerdict("rejected", "dogfood_missing_identity");
+					return "[workflow-guard] Dogfood record rejected: scenarioId and hostLabel must both be non-empty, because they identify the frozen input and the host the deploy matrix names.";
+				}
+				let checks: DogfoodCheck[];
+				try {
+					const parsed = JSON.parse(args.checks);
+					if (!Array.isArray(parsed)) throw new Error("not-array");
+					checks = parsed;
+				} catch {
+					auditVerdict("rejected", "invalid_dogfood_checks");
+					return "[workflow-guard] Dogfood record rejected: checks must be a JSON array of {id, status, expected, observed, detail} rows.";
+				}
+				const invalidCheck = checks.find((check) => !check || typeof check.id !== "string" || !["pass", "hold", "skip"].includes(check.status));
+				if (invalidCheck) {
+					auditVerdict("rejected", "invalid_dogfood_check_row");
+					return "[workflow-guard] Dogfood record rejected: every check row needs a string 'id' and a 'status' of pass, hold, or skip.";
+				}
+				// A record with no checks is a claim, not an observation. Without
+				// this, an empty array would slip past the per-row checks below
+				// because `[].some(...)` is false, and a pass would mean nothing.
+				if (checks.length === 0) {
+					auditVerdict("rejected", "dogfood_without_checks");
+					return "[workflow-guard] Dogfood record rejected: at least one check row is required. A verdict with no observed checks carries no information about the run.";
+				}
+				// A pass is only credible when every check actually ran. A skipped
+				// check is a HOLD by the design's own rule, so accepting it here
+				// would let the gate pass by omission.
+				if (verdict === "pass" && checks.some((check) => check.status !== "pass")) {
+					auditVerdict("rejected", "dogfood_pass_with_nonpassing_check");
+					return "[workflow-guard] Dogfood record rejected: a 'pass' verdict requires every check to be 'pass'. A skipped or held check is a HOLD.";
+				}
+				if (verdict === "hold" && !args.taxonomyClass) {
+					auditVerdict("rejected", "dogfood_hold_without_taxonomy_class");
+					return "[workflow-guard] Dogfood record rejected: a HOLD must name its taxonomy class so the failure is diagnosable.";
+				}
+				const hostProvidesWorkspace = Boolean(toolContext?.worktree);
+				const sessionBinding = await resolveSessionBoundWorkspace(toolContext?.sessionID);
+				if (!args.directory && !sessionBinding && !hostProvidesWorkspace) {
+					auditVerdict("rejected", "dogfood_binding_unresolved", { recorderSessionID: toolContext?.sessionID });
+					return "[workflow-guard] Dogfood record rejected: the run's workspace could not be resolved from this call (no explicit 'directory', no session workspace binding, no per-call worktree). Call record_dogfood with 'directory' set to the repository the run exercised.";
+				}
+				const dogfoodWorkspace = await resolveCallWorkspace(toolContext, args.directory);
+				const bindingFingerprint = getTrackedWorktreeFingerprint(dogfoodWorkspace);
+				if (!bindingFingerprint) {
+					auditVerdict("rejected", "dogfood_workspace_unbindingable", { workspace: dogfoodWorkspace, recorderSessionID: toolContext.sessionID });
+					return `[workflow-guard] Dogfood record rejected: the verdict cannot be bound because no tracked-content fingerprint is available for '${dogfoodWorkspace}' (not a git repository, or git is unavailable). The verdict was NOT recorded. Call record_dogfood with 'directory' set to the run's worktree, or run it from a session rooted there.`;
+				}
+				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
+				const bindingCommitHash = getCurrentGitCommitHash(dogfoodWorkspace);
+				const binding = {
+					workspace: dogfoodWorkspace,
+					commitHash: bindingCommitHash,
+					worktreeFingerprint: bindingFingerprint.slice(0, 16),
+					recorderSessionID: toolContext.sessionID,
+					recorderRole: parentSessionID ? ("subagent" as const) : ("root" as const),
+					targetSessionID: parentSessionID ?? toolContext.sessionID,
+				};
+				const recorded = recordDogfoodResult({
+					verdict: verdict as DogfoodResult["verdict"],
+					scenarioId: args.scenarioId,
+					scenarioSha256: args.scenarioSha256,
+					taxonomySha256: args.taxonomySha256,
+					taxonomyClass: args.taxonomyClass,
+					checks,
+					runCount: typeof args.runCount === "number" && Number.isFinite(args.runCount) && args.runCount >= 1 ? Math.floor(args.runCount) : 1,
+					host: {
+						label: args.hostLabel,
+						os: args.hostOs,
+						arch: args.hostArch,
+						opencodeVersion: args.opencodeVersion,
+						actorModel: args.actorModel,
+						judgeModel: args.judgeModel,
+						stagedTreeHash: args.stagedTreeHash,
+					},
+					workspace: dogfoodWorkspace,
+				}, parentSessionID ?? toolContext.sessionID);
+				auditVerdict(recorded.verdict, recorded.verdict === "pass" ? "dogfood_passed" : "dogfood_held", binding);
+				const boundTo = `Bound to ${dogfoodWorkspace} (commit ${bindingCommitHash?.slice(0, 12) ?? "unversioned"}, tracked fingerprint ${bindingFingerprint.slice(0, 12)}).`;
+				const recordedNote = parentSessionID
+					? `Recorded for parent session ${parentSessionID}.`
+					: `Recorded by root session ${toolContext.sessionID}.`;
+				const passedChecks = checks.filter((check) => check.status === "pass").length;
+				return recorded.verdict === "pass"
+					? `[workflow-guard] Dogfood recorded as PASS for scenario '${recorded.scenarioId}' on host '${recorded.host.label}' (${passedChecks}/${checks.length} checks passed, ${recorded.runCount} run(s)). ${boundTo} ${recordedNote}`
+					: `[workflow-guard] Dogfood recorded as HOLD for scenario '${recorded.scenarioId}' on host '${recorded.host.label}' with class '${recorded.taxonomyClass}'. A HOLD is not durable evidence: fix the finding and re-run. ${boundTo} ${recordedNote}`;
+			},
+		}),
 		guard_review_followups: tool({ description: "List durable local P2/P3 review follow-ups (technical debt) for this project. Proactively check during planning or before final verification to address open findings.", args: {}, execute: async () => JSON.stringify(followupStore ? listReviewFollowups(followupStore) : [], null, 2) }),
 		guard_review_followup_resolve: tool({ description: "Resolve a durable local review follow-up after the underlying issue has been fixed and verified.", args: { id: tool.schema.string() }, execute: async (args) => followupStore && resolveReviewFollowup(followupStore, args.id) ? `[workflow-guard] Review follow-up ${args.id} resolved.` : `[workflow-guard] Review follow-up ${args.id} was not open or was not found.` }),
 		guard_review_rubric: tool({

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 };
+}