opencode-workflow-guard 1.2.1 → 1.3.0

package/README.md

@@ -79,6 +79,7 @@ opencode-workflow-guard/
 | **21** | **Documentation Synchronization** | Verifies documentation is updated when introducing new public features or policies. |
 | **22** | **TTY Hang Guard** | Blocks interactive editors (`vim`, `nano`), pagers (`less`), and commands missing non-interactive flags (`npm init` without `-y`). |
 | **23** | **Package Supply-Chain Hygiene** | Blocks destructive `npm audit fix --force`, global unversioned installs (`npm i -g`), and direct CLI `npm publish`. |
+| **24** | **Completion Claims vs Evidence** | When the final response asserts completion/passing tests, the claim is compared against recorded verification evidence; failing, stale, or missing evidence is journaled (observability, never blocks). Also enriches `todowrite`'s tool description with the finalization-gate note via `tool.definition`. |
 
 👉 **For complete policy specifications and override rules, see [docs/policies.md](docs/policies.md).**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",

package/src/policies/completion.ts

@@ -0,0 +1,90 @@
+import { sessionVerifyResults, lastVerify, sessionMutationTimestamps, lastMutationTimestamp } from "../lib/state.ts";
+import type { VerifyResult } from "../lib/types.ts";
+
+/**
+ * Claims-vs-evidence check (Policy 24): when the assistant's final text
+ * asserts that work is complete or that tests pass, compare the claim against
+ * recorded verification evidence. This is observability, not gating - the
+ * hook audits mismatches so a confident wrap-up cannot silently contradict a
+ * failing or stale verification state.
+ *
+ * Heuristic by design: natural-language claims are matched on explicit
+ * completion/verification phrases. Only high-signal assertions
+ * ("all tests pass", "done", "verified", "green build") count; casual usage
+ * of the same words ("testing the fix", "it passed earlier") should not trip
+ * the detector on multi-sentence responses without assertion framing.
+ */
+
+const COMPLETION_CLAIM_RE =
+	/\b(?:all\s+(?:tests?|checks?)\s+(?:pass(?:es|ed|ing)?|green|succeed(?:ed|ing)?)|tests?\s+(?:are\s+)?(?:all\s+)?(?:pass(?:ing|ed)?|green)|build\s+(?:is\s+)?green|(?:successfully\s+)?verif(?:ied|ication\s+(?:passed|succeeded|is\s+clean))|(?:work|task|implementation)\s+is\s+(?:complete|done|finished)|everything\s+(?:is\s+)?(?:done|complete|works)|(?:all|every)\s+(?:task|item)s?\s+(?:is|are)\s+(?:done|complete(?:d)?))\b/i;
+
+const VERIFICATION_FRESH_WINDOW_MS = 120_000;
+
+export interface CompletionClaimCheck {
+	claimsCompletion: boolean;
+	claim?: string;
+	evidenceState?: "fresh-pass" | "stale-pass" | "failing" | "missing";
+	reason?: string;
+}
+
+export function checkCompletionClaims(
+	text: string,
+	context?: { sessionID?: string },
+): CompletionClaimCheck {
+	if (!text) return { claimsCompletion: false };
+
+	const match = text.match(COMPLETION_CLAIM_RE);
+	if (!match) return { claimsCompletion: false };
+
+	// Session-scoped evidence wins when the session has its own entry OR has
+	// recorded mutations (evidence was invalidated); otherwise fall back to the
+	// most recent global result.
+	const sessionHadEvidence =
+		context?.sessionID !== undefined &&
+		(sessionVerifyResults.has(context.sessionID) ||
+			(sessionMutationTimestamps.get(context.sessionID) ?? 0) > 0);
+	const verifyResult: VerifyResult | undefined = context?.sessionID
+		? (sessionVerifyResults.get(context.sessionID) ??
+			(sessionHadEvidence ? undefined : lastVerify))
+		: lastVerify;
+
+	let evidenceState: CompletionClaimCheck["evidenceState"];
+	const mutationTimestamp = context?.sessionID
+		? (sessionMutationTimestamps.get(context.sessionID) ?? 0)
+		: lastMutationTimestamp;
+	if (!verifyResult) {
+		// A session-scoped lookup that was invalidated by a later mutation is
+		// stale, not merely missing - the agent verified and then changed code.
+		evidenceState =
+			context?.sessionID && mutationTimestamp > 0 ? "stale-pass" : "missing";
+	} else if (!verifyResult.passed) {
+		evidenceState = "failing";
+	} else if (
+		verifyResult.timestamp < mutationTimestamp ||
+		Date.now() - verifyResult.timestamp > VERIFICATION_FRESH_WINDOW_MS
+	) {
+		evidenceState = "stale-pass";
+	} else {
+		evidenceState = "fresh-pass";
+	}
+
+	if (evidenceState === "fresh-pass") {
+		return { claimsCompletion: true, claim: match[0], evidenceState };
+	}
+
+	const reasonByState = {
+		missing:
+			"the response asserts completion/verification, but no verification evidence has been recorded in this session.",
+		failing: `the response asserts completion, but the latest verification (${verifyResult?.command}) FAILED.`,
+		"stale-pass":
+			"the response asserts completion, but the last passing verification is stale - mutations were recorded after it.",
+		"fresh-pass": "",
+	} as const;
+
+	return {
+		claimsCompletion: true,
+		claim: match[0],
+		evidenceState,
+		reason: reasonByState[evidenceState],
+	};
+}

package/src/workflow-guard.ts

@@ -9,6 +9,7 @@
  */
 
 import { tool, type Plugin, type PluginModule } from "@opencode-ai/plugin";
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -212,6 +213,10 @@ import {
 	sendDesktopNotification,
 } from "./policies/shell-safety.ts";
 
+import { checkCompletionClaims } from "./policies/completion.ts";
+
+export { checkCompletionClaims };
+
 export { checkInteractiveTtyCommand, checkPackageHygiene, sendDesktopNotification };
 
 const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
@@ -547,9 +552,11 @@ async function guardToolCallImpl(
 		// Workspace boundary check for external git repo targets
 		for (const invocation of gitInvocations) {
 			const normalizedInvocation = `git ${invocation.rest}`;
+			// The workspace boundary has no allow-live override (same invariant as
+			// file redirects/mv): an external repository write is out of bounds even
+			// with WORKFLOW_GUARD_ALLOW_LIVE=1.
 			if (
 				isPathOutsideWorkspace(invocation.repoDir, currentRoot) &&
-				!allowLive &&
 				(GIT_WRITE_RE.test(normalizedInvocation) || /\bgit\s+push\b/.test(normalizedInvocation))
 			) {
 				logBlock(`[workflow-guard] blocked git mutation on repository outside workspace: ${invocation.repoDir}`);
@@ -929,7 +936,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 			}),
 			record_review: tool({
 				description:
-					"Record a secondary reviewer agent's approval or critique of the current changes.",
+					"Record a secondary reviewer agent's approval or critique of the current changes. The summary must reference the 5 core review axes from guard_review_rubric.",
 				args: {
 					reviewer: tool.schema
 						.string()
@@ -946,6 +953,24 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					if (!parentSessionID) {
 						return "[workflow-guard] Review rejected: record_review must be called from a secondary/subagent session.";
 					}
+					// The rubric is the contract: a recorded review must demonstrate it
+					// was evaluated against the 5 axes, not just assert a verdict.
+					const axesRefs = [
+						"test integrity",
+						"task completeness",
+						"cleanliness",
+						"security",
+						"platform",
+					];
+					const summaryLower = args.summary.toLowerCase();
+					const referenced = axesRefs.filter((axis) => summaryLower.includes(axis));
+					if (referenced.length < 3) {
+						return (
+							`[workflow-guard] Review rejected: summary must reference the review axes ` +
+							`(found ${referenced.length}/5). Call guard_review_rubric to get the rubric, ` +
+							`evaluate each axis, and include findings per axis in the summary.`
+						);
+					}
 					recordReviewResult(
 						args.reviewer,
 						args.summary,
@@ -958,6 +983,42 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 						: `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}.`;
 				},
 			}),
+			guard_review_rubric: tool({
+				description:
+					"Get the secondary-review rubric for the current branch diff. The orchestrator calls this, spawns a reviewer subagent with the rubric as the prompt, then the reviewer records its verdict via record_review.",
+				args: {
+					base: tool.schema
+						.string()
+						.optional()
+						.describe("Base ref to diff against (default: origin/main, origin/master, main)"),
+				},
+				execute: async (args) => {
+					const bases = args.base
+						? [args.base]
+						: ["origin/main", "origin/master", "main", "master"];
+					let diffText = "";
+					for (const base of bases) {
+						const res = spawnSync(
+							"git",
+							["diff", `${base}...HEAD`],
+							{ cwd: getWorkspaceRoot(), encoding: "utf8", timeout: 10_000 },
+						);
+						if (res.status === 0 && res.stdout.trim()) {
+							diffText = res.stdout;
+							break;
+						}
+					}
+					if (!diffText) {
+						const last = spawnSync("git", ["diff", "HEAD~1"], {
+							cwd: getWorkspaceRoot(),
+							encoding: "utf8",
+							timeout: 10_000,
+						});
+						diffText = last.status === 0 ? last.stdout : "(no diff available)";
+					}
+					return buildReviewRubric(diffText);
+				},
+			}),
 			guard_worktree_create: tool({
 				description:
 					"Create an isolated git worktree directory for concurrent subagent execution.",
@@ -1142,6 +1203,40 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 			});
 		},
 
+		// Policy 24 (observability): claims-vs-evidence. When the assistant's final
+		// text asserts completion or passing verification, compare the claim against
+		// recorded verification evidence. A mismatch is journaled (not blocked) so
+		// confident wrap-ups cannot silently contradict failing or stale state.
+		"experimental.text.complete": async (input, output) => {
+			try {
+				const sessionID = input.sessionID;
+				const text = typeof output.text === "string" ? output.text : "";
+				const check = checkCompletionClaims(text, { sessionID });
+				if (check.claimsCompletion && check.evidenceState && check.evidenceState !== "fresh-pass") {
+					logBlock(`[workflow-guard] completion claim mismatch: ${check.reason}`);
+					audit({
+						ts: new Date().toISOString(),
+						sessionID,
+						tool: "experimental.text.complete",
+						decision: "allow",
+						reason: `Completion claim '${check.claim}' has ${check.evidenceState} verification evidence`,
+						input: { claim: check.claim, evidenceState: check.evidenceState },
+					});
+				}
+			} catch {}
+		},
+
+		// Keep tool descriptions honest: todowrite's description reflects the
+		// finalization gates so the model is not surprised by verification blocks.
+		"tool.definition": async (input, output) => {
+			if (input.toolID !== "todowrite") return;
+			const description = typeof output.description === "string" ? output.description : "";
+			if (description.includes("verification evidence")) return;
+			output.description =
+				description +
+				"\n\nNote: marking every task completed triggers the workflow guard's finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
+		},
+
 		event: async ({
 			event,
 		}: { event: { type?: string; properties?: unknown } }) => {