opencode-workflow-guard 1.10.1 → 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.1",
+  "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/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")));
@@ -1802,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)({
@@ -2191,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",