opencode-workflow-guard 1.10.0 → 1.11.0

package/README.md

@@ -42,7 +42,7 @@ WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run policy probes with Ope
 
 The plugin enforces **24 deterministic policy rules** across four main pillars:
 
-* **Branch & History Protection:** Enforces feature-branch workflows (blocks edits/commits on `main`/`master`), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, and requires PR changelogs / changesets.
+* **Branch & History Protection:** Enforces feature-branch workflows (blocks edits/commits on `main`/`master`), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, enforces secondary review approval before PR creation by default, and requires PR changelogs / changesets.
 * **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks with subagent inheritance, blocks concurrent direct edits to the same canonical file across sessions, requires same-session fresh reads before `edit`/`write` can replace existing files, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
 * **Secrets & Workspace Confinement:** Confines edit tools and recognized shell/git mutations within the workspace root (including symlink and `../` escape checks), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks. Arbitrary executables are not OS-sandboxed; use containers or filesystem isolation when hard confinement is required.
 * **Destructive CLI & Environment Safety:** Intercepts destructive cloud/database/infrastructure commands, stops script laundering and interpreter evasion, blocks TTY hangs (`vim`, `nano`, `sudo`), and guards against dangerous package manager flags.

package/docs/installation.md

@@ -108,6 +108,22 @@ OpenCode's model/provider request timeout is separate from Workflow Guard. In Op
 
 ---
 
+## Secondary Review Requirement
+
+Workflow Guard enforces secondary review approval (`requireReview`) by default during PR creation (`gh pr create` and `az repos pr create`). Before a pull request can be opened, an agent must invoke a secondary review subagent and record passing review approval using `record_review` evaluated against `guard_review_rubric`.
+
+To opt out of the PR secondary review gate for a project, set `requireReview: false` in `.opencode/workflow-guard.json`:
+
+```json
+{
+  "requireReview": false
+}
+```
+
+Or set `WORKFLOW_GUARD_REQUIRE_REVIEW=0` in your environment. Conversely, `WORKFLOW_GUARD_REQUIRE_REVIEW=1` enforces the review gate regardless of repository configuration.
+
+---
+
 ## Recommended Companion Configuration
 
 For defense in depth, pair `opencode-workflow-guard` with OpenCode's native permission rules in `opencode.json` (see [OpenCode Permissions](https://opencode.ai/docs/permissions/)):

package/docs/policies.md

@@ -181,7 +181,7 @@ Besides enforcement hooks, the guard registers companion tools in OpenCode:
 
 ### Inspection Tools
 - `guard_status`, `guard_audit`, `guard_why`, `guard_review_rubric`, `record_review`, `guard_review_followups`, and `guard_review_followup_resolve` provide runtime introspection of guardrail state, audit entries, block explanations, reviewer rubric definitions, reviewer decisions, and durable local review debt. `guard_status` also exposes the effective Ralph opt-in, iteration budget, and calling-session outcome when applicable.
-- **Priority-Ranked Review Gate:** `guard_review_rubric` includes P0-P3 severity tiers. When recording reviews via `record_review`, approvals that include active P0 (blocker) or P1 (major defect) issues are rejected until blockers are resolved.
+- **Priority-Ranked Review Gate:** Secondary review approval (`requireReview`) is enforced by default during PR preflight (`gh pr create` / `az repos pr create`). Before creating a pull request, a secondary reviewer subagent must evaluate the changes using `guard_review_rubric` and record approval with `record_review`. Approvals that include active P0 (blocker) or P1 (major defect) issues are rejected until blockers are resolved. Projects can opt out via `.opencode/workflow-guard.json` (`{ "requireReview": false }`) or environment variable `WORKFLOW_GUARD_REQUIRE_REVIEW=0`. Conversely, `WORKFLOW_GUARD_REQUIRE_REVIEW=1` forces the review requirement regardless of project config.
 - **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 and remain open across sessions until explicitly resolved with `guard_review_followup_resolve`; 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/state.ts

@@ -218,9 +218,11 @@ export function getProjectConfig(root: string): ProjectConfig {
 }
 
 export function isReviewRequired(root: string): boolean {
-	if (process.env.WORKFLOW_GUARD_REQUIRE_REVIEW === "1") return true;
+	const env = process.env.WORKFLOW_GUARD_REQUIRE_REVIEW?.toLowerCase();
+	if (env === "0" || env === "false" || env === "off") return false;
+	if (env === "1" || env === "true" || env === "on") return true;
 	const cfg = getProjectConfig(root);
-	return cfg.requireReview === true;
+	return cfg.requireReview !== false;
 }
 
 export function isDocumentationRequired(root: string): boolean {

package/src/lib/tool-outcomes.ts

@@ -27,6 +27,7 @@ export class ToolOutcomeTracker {
 	private readonly terminalCalls = new Map<string, Set<string>>();
 	private readonly fallbackCalls = new Map<string, Set<string>>();
 	private readonly failures = new Map<string, { signature: string; count: number }>();
+	private readonly consecutiveFailures = new Map<string, number>();
 
 	record(part: ToolOutcomePart): ToolOutcome | undefined {
 		if (part.type !== "tool" || typeof part.sessionID !== "string" || typeof part.callID !== "string" || typeof part.tool !== "string") return undefined;
@@ -51,6 +52,7 @@ export class ToolOutcomeTracker {
 		const durationMs = typeof start === "number" && Number.isFinite(start) && typeof end === "number" && Number.isFinite(end) ? Math.max(0, end - start) : undefined;
 		if (status === "completed") {
 			this.failures.delete(part.sessionID);
+			this.consecutiveFailures.delete(part.sessionID);
 			return { sessionID: part.sessionID, callID: part.callID, tool: part.tool, status, durationMs };
 		}
 
@@ -59,6 +61,10 @@ export class ToolOutcomeTracker {
 		const previous = this.failures.get(part.sessionID);
 		const count = previous?.signature === signature ? previous.count + 1 : 1;
 		this.failures.set(part.sessionID, { signature, count });
+
+		const consecutive = (this.consecutiveFailures.get(part.sessionID) ?? 0) + 1;
+		this.consecutiveFailures.set(part.sessionID, consecutive);
+
 		return { sessionID: part.sessionID, callID: part.callID, tool: part.tool, status, durationMs, repeatedFailureCount: count };
 	}
 
@@ -75,11 +81,14 @@ export class ToolOutcomeTracker {
 	}
 
 	getFailureCount(sessionID: string): number {
-		return this.failures.get(sessionID)?.count ?? 0;
+		const consecutive = this.consecutiveFailures.get(sessionID) ?? 0;
+		const equivalent = this.failures.get(sessionID)?.count ?? 0;
+		return Math.max(consecutive, equivalent);
 	}
 
 	clearSession(sessionID: string): void {
 		this.failures.delete(sessionID);
+		this.consecutiveFailures.delete(sessionID);
 		this.terminalCalls.delete(sessionID);
 		this.fallbackCalls.delete(sessionID);
 	}

package/src/policies/boundary.ts

@@ -158,13 +158,9 @@ export function shellMutationIn(segment: string): ShellMutation | undefined {
 			what: `tee to '${teeTargets[0]!}'`,
 		};
 	}
-	const sedWords = shellWords(unwrapShellCommand(segment));
-	if (sedWords[0] === "sed" && sedWords.slice(1).some((word) => /^-(?:[a-zA-Z]*i|i\S*)$/.test(word) || /^--in-place(?:=.*)?$/.test(word))) {
-		const operands = sedWords.slice(1).filter((word) => !word.startsWith("-"));
-		const target = operands.at(-1);
-		if (!target) return undefined;
-		return { kind: "command", target, what: `sed -i on '${target}'` };
-	}
+	const simple = simpleFilesystemMutations(segment);
+	if (simple.length > 0) return simple[0];
+
 	const transfer = filesystemTransferInfo(segment);
 	if (transfer?.destination) {
 		return {
@@ -173,34 +169,45 @@ export function shellMutationIn(segment: string): ShellMutation | undefined {
 			what: `copy/move/link to '${transfer.destination}'`,
 		};
 	}
-	const fsMutationMatch = segment.match(
-		/\b(?:touch|mkdir|rm|unlink|rmdir|ln)\b[^|;&]*\s+["']?([^\s;&|"']+)["']?\s*$/,
-	);
-	if (fsMutationMatch?.[1] && !fsMutationMatch[1].startsWith("-")) {
-		return {
-			kind: "command",
-			target: fsMutationMatch[1],
-			what: `filesystem mutation of '${fsMutationMatch[1]}'`,
-		};
+	const words = shellWords(unwrapShellCommand(segment));
+	const command = words[0];
+	if (!command) return undefined;
+
+	if (command === "curl") {
+		for (let i = 1; i < words.length; i++) {
+			const w = words[i]!;
+			if ((w === "-o" || w === "--output") && i + 1 < words.length) {
+				return { kind: "command", target: words[i + 1]!, what: `curl output to '${words[i + 1]!}'` };
+			}
+			if (w.startsWith("--output=")) {
+				const target = w.slice("--output=".length);
+				return { kind: "command", target, what: `curl output to '${target}'` };
+			}
+		}
 	}
-	const copyMatch = segment.match(
-		/\b(?:cp|mv|rsync|install|cpio|scp|wget|curl)\b[^|;&]*?(-o\s+)?(["']?)([^\s;&|"']+)\2?\s*$/,
-	);
-	if (copyMatch?.[3] && /\b(?:cp|mv|rsync|install)\b/.test(segment)) {
-		return {
-			kind: "command",
-			target: copyMatch[3],
-			what: `copy/move to '${copyMatch[3]}'`,
-		};
+	if (command === "wget") {
+		for (let i = 1; i < words.length; i++) {
+			const w = words[i]!;
+			if ((w === "-O" || w === "--output-document") && i + 1 < words.length) {
+				return { kind: "command", target: words[i + 1]!, what: `wget output to '${words[i + 1]!}'` };
+			}
+			if (w.startsWith("--output-document=")) {
+				const target = w.slice("--output-document=".length);
+				return { kind: "command", target, what: `wget output to '${target}'` };
+			}
+		}
 	}
-	if (/\bgit\s+(?:apply|am)\b/.test(segment)) {
-		return { kind: "command", what: "git apply/am (patch via shell)" };
+	if (command === "git") {
+		const sub = words.slice(1).find((w) => !w.startsWith("-"));
+		if (sub === "apply" || sub === "am") {
+			return { kind: "command", what: "git apply/am (patch via shell)" };
+		}
 	}
 	return undefined;
 }
 
 const SIMPLE_MUTATION_COMMANDS = new Set(["touch", "mkdir", "rm", "unlink", "rmdir", "truncate", "chmod", "chown", "chgrp"]);
-const TRANSFER_COMMANDS = new Set(["cp", "mv", "ln"]);
+const TRANSFER_COMMANDS = new Set(["cp", "mv", "ln", "rsync", "install", "cpio", "scp"]);
 
 export function simpleFilesystemMutations(segment: string): ShellMutation[] {
 	const words = shellWords(unwrapShellCommand(segment));

package/test/test.mts

@@ -62,6 +62,7 @@ import {
 	checkLockfileSync,
 	branchHasDocumentationChange,
 	isDocumentationRequired,
+	isReviewRequired,
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
 	getSubagentMutationBudget,
@@ -241,6 +242,7 @@ check("allow git push origin feature/x", !(await shell("git push origin feature/
 check("allow push to main-backup (ref-like path)", !(await shell("git push origin main-backup")));
 
 console.log("- Policy 3: PR changelog (GitHub & Azure DevOps) -");
+process.env.WORKFLOW_GUARD_REQUIRE_REVIEW = "0";
 check("block gh pr create without changelog", blocked(await shell("gh pr create --title t --body 'no changes here'")));
 check("allow gh pr create with Changelog: body", !(await shell("gh pr create --title t --body 'Changelog: fixed stuff'")));
 check("allow gh pr create with Summary release information", !(await shell("gh pr create --title t --body '## Summary\n- Fix stale tool outcome tracking'")));
@@ -341,6 +343,8 @@ check("unrelated shell workdir cannot supply PR changelog evidence", blocked(awa
 spawnSync("git", ["worktree", "remove", "--force", changesetWorktree], { cwd: changesetRepo });
 rmSync(changesetRepo, { recursive: true, force: true });
 
+delete process.env.WORKFLOW_GUARD_REQUIRE_REVIEW;
+
 console.log("- Policy 4: destructive commands -");
 check("block kubectl delete", blocked(await shell("kubectl delete pod foo")));
 check("block helm uninstall", blocked(await shell("helm uninstall my-release")));
@@ -497,6 +501,9 @@ check("sed -i on opencode.json blocked (tamper)", blocked(await call("bash", { c
 check("git apply needs todos (patch via shell)", blocked(await call("bash", { command: "git apply patch.diff" }, { sessionID: "s-empty" })));
 check("git apply allowed with todos", !(await call("bash", { command: "git apply patch.diff" }, { sessionID: "s-active" })));
 check("non-mutating shell unaffected (ls, cat)", !(await call("bash", { command: "ls -la && cat file" }, { sessionID: "s-empty" })));
+check("inspection command with mutation keywords in grep argument is not blocked", !(await call("bash", { command: 'strings /bin/opencode | grep -E "install plugin and update config" -C 10' }, { sessionID: "s-empty" })));
+check("git log with mutation keywords in grep argument is not blocked", !(await call("bash", { command: 'git log --grep="rm old files"' }, { sessionID: "s-empty" })));
+check("grep searching for mutation command name is not blocked", !(await call("bash", { command: 'grep -rn "mkdir" src/' }, { sessionID: "s-empty" })));
 check("stderr redirect to /dev/null is not a file mutation", !(await call("bash", { command: "ls missing 2>/dev/null" }, { sessionID: "s-empty" })));
 check("touch outside workspace is blocked", blocked(await call("bash", { command: "touch /tmp/wg-outside-touch" }, { sessionID: "s-active" })));
 check("mkdir outside workspace is blocked", blocked(await call("bash", { command: "mkdir /tmp/wg-outside-dir" }, { sessionID: "s-active" })));
@@ -1112,6 +1119,12 @@ outcomeTracker.record({ type: "tool", sessionID: "s-tracker", callID: "success",
 check("successful tool outcomes reset equivalent failure tracking", outcomeTracker.record(failedPart("after-success", "same failure"))?.repeatedFailureCount === 1);
 outcomeTracker.record(failedPart("different", "different failure"));
 check("distinct failures reset equivalent failure tracking", outcomeTracker.record(failedPart("after-different", "same failure"))?.repeatedFailureCount === 1);
+const consecutiveTracker = new ToolOutcomeTracker();
+consecutiveTracker.record(failedPart("diverse-1", "failure A"));
+consecutiveTracker.record(failedPart("diverse-2", "failure B"));
+check("consecutive diverse failures track failure count for circuit breaker", consecutiveTracker.getFailureCount("s-tracker") === 2);
+consecutiveTracker.record({ type: "tool", sessionID: "s-tracker", callID: "diverse-success", tool: "bash", state: { status: "completed" } });
+check("successful tool outcome resets consecutive failure count", consecutiveTracker.getFailureCount("s-tracker") === 0);
 const boundedTracker = new ToolOutcomeTracker();
 for (let i = 0; i < 4096; i++) boundedTracker.record({ type: "tool", sessionID: "s-bounded", callID: `call-${i}`, tool: "bash", state: { status: "completed" } });
 check("terminal call deduplication remains stable within its bounded window", boundedTracker.record({ type: "tool", sessionID: "s-bounded", callID: "call-0", tool: "bash", state: { status: "completed" } }) === undefined);
@@ -1793,6 +1806,44 @@ setWorkspaceRoot(root);
 reloadProjectConfig(root);
 resetReviewState();
 
+// Default requireReview behavior: true by default, opt-out with config false or env 0
+const defaultReviewRepo = mkdtempSync(join(tmpdir(), "wg-default-review-"));
+mkdirSync(join(defaultReviewRepo, ".opencode"), { recursive: true });
+setWorkspaceRoot(defaultReviewRepo);
+reloadProjectConfig(defaultReviewRepo);
+check("requireReview defaults to true when unconfigured", isReviewRequired(defaultReviewRepo) === true);
+resetReviewState();
+check(
+	"PR creation blocked by default without recorded review in unconfigured repo",
+	blocked(await shell("gh pr create --title t --body 'Changelog: update'")),
+);
+writeFileSync(join(defaultReviewRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: false }));
+reloadProjectConfig(defaultReviewRepo);
+check("explicit requireReview: false disables review gate", isReviewRequired(defaultReviewRepo) === false);
+check(
+	"PR creation allowed when requireReview is explicitly false",
+	!(await shell("gh pr create --title t --body 'Changelog: update'")),
+);
+process.env.WORKFLOW_GUARD_REQUIRE_REVIEW = "1";
+check("WORKFLOW_GUARD_REQUIRE_REVIEW=1 forces review even when config is false", isReviewRequired(defaultReviewRepo) === true);
+check(
+	"PR creation blocked when WORKFLOW_GUARD_REQUIRE_REVIEW=1 overrides config false",
+	blocked(await shell("gh pr create --title t --body 'Changelog: update'")),
+);
+writeFileSync(join(defaultReviewRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: true }));
+reloadProjectConfig(defaultReviewRepo);
+process.env.WORKFLOW_GUARD_REQUIRE_REVIEW = "0";
+check("WORKFLOW_GUARD_REQUIRE_REVIEW=0 overrides config true", isReviewRequired(defaultReviewRepo) === false);
+check(
+	"PR creation allowed when WORKFLOW_GUARD_REQUIRE_REVIEW=0 overrides config true",
+	!(await shell("gh pr create --title t --body 'Changelog: update'")),
+);
+delete process.env.WORKFLOW_GUARD_REQUIRE_REVIEW;
+rmSync(defaultReviewRepo, { recursive: true, force: true });
+setWorkspaceRoot(root);
+reloadProjectConfig(root);
+resetReviewState();
+
 // 12. Custom Plugin Tools & Event Auditing
 console.log("- Custom Tools & Event Auditing -");
 const customPlugin = await (defaultExport?.server ?? WorkflowGuard)({
@@ -2182,6 +2233,7 @@ check(
 // Now update README.md or docs
 writeFileSync(join(docRepo, "README.md"), "# Updated Docs\n");
 spawnSync("git", ["commit", "-am", "docs: update README"], { cwd: docRepo });
+recordReviewResult("reviewer-agent", "LGTM - 5 axes verified", true, undefined, docRepo);
 check("branchHasDocumentationChange returns true once docs are modified", branchHasDocumentationChange(docRepo));
 check(
 	"gh pr create passes once documentation update is present",