opencode-workflow-guard 1.3.3 → 1.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +52 -59
  2. package/package.json +1 -1
  3. package/src/workflow-guard-ui.ts +2 -2
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # opencode-workflow-guard
2
2
 
3
- OpenCode plugin enforcing workflow discipline, agent focus, and deterministic safety boundaries through **hard plugin hooks** — not prompt instructions that LLMs can ignore.
3
+ [![npm](https://img.shields.io/npm/v/opencode-workflow-guard.svg)](https://www.npmjs.com/package/opencode-workflow-guard)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![Tests](https://img.shields.io/badge/tests-415%2B%20passing-brightgreen.svg)](test/test.mts)
4
6
 
5
- Integrates with OpenCode's native todo system (`todowrite`), prevents accidental destructive actions, gates protected branches, enforces testing evidence before task finalization, and stops secret leakage.
7
+ OpenCode plugin enforcing workflow discipline, agent focus, and deterministic safety boundaries through **hard plugin hooks**, not prompt instructions that LLMs can ignore.
6
8
 
7
9
  ---
8
10
 
@@ -21,33 +23,73 @@ Add to your project's `opencode.json` or global `~/.config/opencode/opencode.jso
21
23
  }
22
24
  ```
23
25
 
24
- *Requires OpenCode >= 1.18.* See [docs/installation.md](docs/installation.md) for local manual installation and TUI companion badge setup.
26
+ *Requires OpenCode >= 1.18.* See [docs/installation.md](docs/installation.md) for full setup options and TUI companion badge configuration.
25
27
 
26
28
  ### 2. Verification
27
29
 
28
30
  ```bash
29
31
  npm run typecheck # Strict TypeScript check (0 errors)
30
- npm test # Run 400+ unit and adversarial tests
32
+ npm test # Run 415+ unit and adversarial tests
31
33
  npm run test:all # Run full verification suite (typecheck + unit + live e2e)
32
34
  ```
33
35
 
34
36
  ---
35
37
 
36
- ## Repository Structure
38
+ ## Core Guardrails Overview
39
+
40
+ The plugin enforces **24 deterministic policy rules** across four main pillars:
41
+
42
+ * **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.
43
+ * **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks with subagent inheritance, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
44
+ * **Secrets & Workspace Confinement:** Confines all edits, shell redirects, and git operations within the workspace root (symlink & `../` escape safe), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks.
45
+ * **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.
46
+
47
+ For complete policy specifications and override rules, see [docs/policies.md](docs/policies.md).
48
+
49
+ ---
50
+
51
+ ## Documentation Index
52
+
53
+ | Guide | Description |
54
+ |---|---|
55
+ | [**Policy Reference**](docs/policies.md) | Comprehensive specification of all 24 enforced policies, invariants, and override semantics |
56
+ | [**Installation & Configuration**](docs/installation.md) | Setup options, global vs. local install, worktree isolation, and project configuration |
57
+ | [**Troubleshooting**](docs/troubleshooting.md) | Diagnosing policy blocks, common false positives, and emergency override procedures |
58
+ | [**Testing Architecture**](docs/testing.md) | Test harness design, adversarial regression matrix, and CI verification |
59
+ | [**Contributing Guide**](CONTRIBUTING.md) | Development workflow, coding conventions, test requirements, and changeset PR rules |
60
+ | [**Security Policy**](SECURITY.md) | Vulnerability disclosure policy and threat model |
61
+
62
+ ---
63
+
64
+ ## Custom Tools Registered in OpenCode
65
+
66
+ | Tool | Purpose |
67
+ |---|---|
68
+ | `guard_status` | Inspect active guardrails, current branch protection, and verification/review status |
69
+ | `guard_why` | Simulate and explain whether a specific tool call or command would be blocked |
70
+ | `guard_audit` | View recent audit log entries recorded in `workflow-guard.jsonl` |
71
+ | `guard_review_rubric` | Generate the 5-axis secondary review rubric for the current branch diff |
72
+ | `record_review` | Record a secondary reviewer subagent's verdict evaluated against the review rubric |
73
+ | `guard_worktree_create` | Create an isolated git worktree directory for concurrent subagent execution |
74
+ | `guard_worktree_cleanup` | Snapshot-commit remaining changes and remove an isolated worktree directory |
75
+
76
+ ---
77
+
78
+ ## Repository Tree
37
79
 
38
80
  ```
39
81
  opencode-workflow-guard/
40
82
  ├── src/ # Production plugin sources
41
83
  │ ├── workflow-guard.ts # Server plugin entrypoint (hook orchestrator & public exports)
42
- │ ├── workflow-guard-ui.ts # TUI companion prompt badge
43
- │ ├── policies/ # Per-policy implementations (task gate, git, secrets, shell-safety, ...)
84
+ │ ├── workflow-guard-ui.ts # Optional TUI companion prompt badge
85
+ │ ├── policies/ # Modular policy implementations (task gate, git, secrets, boundary, ...)
44
86
  │ └── lib/ # Engine services (state, verify, audit, review, worktree, utils, types)
45
87
  ├── test/ # Test suites
46
- │ ├── test.mts # 400+ in-memory unit & adversarial tests
88
+ │ ├── test.mts # 415+ in-memory unit & adversarial tests
47
89
  │ └── test-e2e.mts # npm tarball resolution + live runtime OpenCode loader tests
48
90
  ├── docs/ # In-depth documentation & guides
49
- │ ├── installation.md # Full setup options, worktrees & permissions
50
- │ ├── policies.md # Detailed 24-policy reference & overrides
91
+ │ ├── policies.md # Complete 24-policy reference & overrides
92
+ │ ├── installation.md # Setup options, worktrees & permissions
51
93
  │ ├── troubleshooting.md # Error diagnosis & bypass explanations
52
94
  │ └── testing.md # Test architecture & coverage matrix
53
95
  ├── .changeset/ # Fragment-based versioning & release changelogs
@@ -59,55 +101,6 @@ opencode-workflow-guard/
59
101
 
60
102
  ---
61
103
 
62
- ## Summary of Enforced Policies
63
-
64
- | # | Policy Group | Summary |
65
- |---|---|---|
66
- | **1** | **Task Gate & Lifecycle** | Gates file mutations on active `todowrite` tasks. Prevents silent task deletion; allows flexible completion order. |
67
- | **2 & 7** | **Branch Protection** | Blocks direct edits & commits on `main`/`master`. Hard-blocks `git push ... main` and forced refspecs. |
68
- | **3** | **PR Changelog & Changesets** | Requires PRs to include changesets (`.changeset/*.md`), `CHANGELOG.md` updates, or a `Changelog:` body section. |
69
- | **4 & 9** | **Destructive CLI & Laundering** | Blocks destructive infrastructure, database, and system mutations unless overridden by user environment (`WORKFLOW_GUARD_ALLOW_LIVE=1`). Scans script payloads for smuggled commands. |
70
- | **5** | **MCP Mutation Guard** | Blocks mutating GitHub & Azure DevOps MCP tools while allowing read-only inspection tools. |
71
- | **6** | **Settings Tamper Guard** | Blocks agent modification of `opencode.json`, `.opencode/*`, or the guard's own plugin files. |
72
- | **8** | **Workspace Boundary Guard** | Confines file mutations and shell redirects strictly within the project workspace root (symlink & `../` escape safe). |
73
- | **10** | **Evidence-Based Verification** | Runs test verification before final task completion. Binds freshness to git state with token-efficient output snipping. |
74
- | **11, 12, 17** | **Secret Protection & Masking** | Scans file payloads for API keys, scrubs sensitive env vars in agent subshells, and provides safe redacted `.env` variable schema masks (`KEY=********`). |
75
- | **13 & 14** | **Audit Trail & Attribution** | Durable JSONL audit logging (`~/.local/state/opencode/workflow-guard/workflow-guard.jsonl`) with subagent hierarchy breadcrumbs. |
76
- | **15 & 16** | **Compaction & TUI Feedback** | Preserves active task plans across context compactions; emits real-time TUI warning toasts and native desktop alerts. |
77
- | **18** | **Interpreter Inline Evasion** | Scans inline scripts (`python -c`, `node -e`, `base64 | sh`) for smuggled live commands or config tampering. |
78
- | **19 & 20** | **Pre-Flight Conflicts & Freshness** | Verifies clean `git merge-tree` mergeability and checks local base branch freshness before opening PRs. |
79
- | **21** | **Documentation Synchronization** | Verifies documentation is updated when introducing new public features or policies. |
80
- | **22** | **TTY Hang Guard** | Blocks interactive editors (`vim`, `nano`), pagers (`less`), and commands missing non-interactive flags (`npm init` without `-y`). |
81
- | **23** | **Package Supply-Chain Hygiene** | Blocks destructive `npm audit fix --force`, global unversioned installs (`npm i -g`), and direct CLI `npm publish`. |
82
- | **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`. |
83
-
84
- 👉 **For complete policy specifications and override rules, see [docs/policies.md](docs/policies.md).**
85
-
86
- ---
87
-
88
- ## Custom Tools Registered in OpenCode
89
-
90
- * `guard_status`: Inspect active guardrails, current branch protection, and verification/review status.
91
- * `guard_audit`: View recent audit log entries recorded in `workflow-guard.jsonl`.
92
- * `guard_why`: Simulate and explain whether a specific tool call or command would be blocked.
93
- * `record_review`: Record secondary reviewer subagent approval or critique across the 5 core review axes.
94
- * `guard_worktree_create`: Create an isolated git worktree (with shared `node_modules` symlink) for concurrent subagent execution; rejects invalid and protected branch names.
95
- * `guard_worktree_cleanup`: Snapshot-commit remaining changes and remove an isolated worktree directory.
96
-
97
- ---
98
-
99
- ## Documentation & Community
100
-
101
- * [Installation Guide](docs/installation.md)
102
- * [Policies & Overrides Reference](docs/policies.md)
103
- * [Troubleshooting Guide](docs/troubleshooting.md)
104
- * [Testing Guide](docs/testing.md)
105
- * [Contributing Guide](CONTRIBUTING.md)
106
- * [Acknowledgements & Ecosystem Credits](ACKNOWLEDGEMENTS.md)
107
- * [Security Policy](SECURITY.md)
108
-
109
- ---
110
-
111
104
  ## License
112
105
 
113
106
  [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-workflow-guard",
3
- "version": "1.3.3",
3
+ "version": "1.3.4",
4
4
  "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/workflow-guard-ui.ts CHANGED
@@ -24,7 +24,7 @@ function text(props: Record<string, unknown>, children: Child[]) {
24
24
  return element("text", props, children);
25
25
  }
26
26
 
27
- const BADGE_ACTIVE = "🛡️ [Workflow Guard: Active]";
27
+ const BADGE_ACTIVE = "[Workflow Guard: Active]";
28
28
  let lastBlockedReason: string | undefined;
29
29
  const sessionBlockedReasons = new Map<string, string>();
30
30
  const badgeNodes = new Map<string, unknown>();
@@ -45,7 +45,7 @@ export function formatBadge(sessionID?: string): { text: string; isBlocked: bool
45
45
  }
46
46
  const cleanReason = reason.replace(/^\[workflow-guard\]\s*/, "").replace(/^Blocked:\s*/, "");
47
47
  const shortReason = cleanReason.length > 30 ? cleanReason.slice(0, 27) + "..." : cleanReason;
48
- return { text: `🛡️ [Workflow Guard: Blocked: ${shortReason}]`, isBlocked: true };
48
+ return { text: `[Workflow Guard: Blocked: ${shortReason}]`, isBlocked: true };
49
49
  }
50
50
 
51
51
  export const WorkflowGuardTui: TuiPlugin = async (api) => {