opencode-workflow-guard 1.1.0

package/ACKNOWLEDGEMENTS.md

@@ -0,0 +1,23 @@
+# Acknowledgements & Ecosystem Inspirations
+
+`opencode-workflow-guard` is built on original, clean-room TypeScript code, but draws design inspiration, best practices, and workflow ideas from the broader [OpenCode](https://opencode.ai) community and ecosystem:
+
+## Community Projects & Inspirations
+
+* **[`opencode-shell-strategy`](https://github.com/JRedeker/opencode-shell-strategy)** by [@JRedeker](https://github.com/JRedeker)  
+  * Inspired the interactive TTY detection patterns in **Policy 22** (Non-Interactive Shell & TTY Hang Guard) to prevent subshell freezes on interactive prompts.
+
+* **[`envsitter-guard`](https://github.com/boxpositron/envsitter-guard)** by [@boxpositron](https://github.com/boxpositron)  
+  * Inspired the safe variable schema masking approach in **Policy 17** (Secret-File Read Block & Schema Masking) so agents can discover environment variable names without exposing live secret values.
+
+* **[`opencode-snip`](https://github.com/VincentHardouin/opencode-snip)** by [@VincentHardouin](https://github.com/VincentHardouin)  
+  * Inspired the token-efficient test output truncation and failure prioritization in **Policy 10** (Evidence-Based Verification).
+
+* **[`opencode-worktree`](https://github.com/kdcokenny/opencode-worktree)** by [@kdcokenny](https://github.com/kdcokenny)  
+  * Inspired the isolated-worktree development workflow behind the **`guard_worktree_create` / `guard_worktree_cleanup`** tools (snapshot-commit before removal, `node_modules` sharing, storage outside the repository), re-implemented here as native in-process tools with zero external dependencies.
+
+* **[`changesets`](https://github.com/changesets/changesets)** by the [Changesets Team](https://github.com/changesets/changesets)  
+  * For the fragment-based changelog and versioning model that prevents merge conflicts across parallel feature PRs.
+
+* **[OpenCode Team at Anomaly](https://github.com/anomalyco/opencode)**  
+  * For building the OpenCode terminal AI coding agent and its extensible plugin architecture (`@opencode-ai/plugin`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ultus-net
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# opencode-workflow-guard
+
+OpenCode plugin enforcing workflow discipline, agent focus, and deterministic safety boundaries through **hard plugin hooks** — not prompt instructions that LLMs can ignore.
+
+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.
+
+---
+
+## Quick Start
+
+### 1. Installation
+
+Add to your project's `opencode.json` or global `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-workflow-guard"
+  ]
+}
+```
+
+*Requires OpenCode >= 1.18.* See [docs/installation.md](docs/installation.md) for local manual installation and TUI companion badge setup.
+
+### 2. Verification
+
+```bash
+npm run typecheck    # Strict TypeScript check (0 errors)
+npm test             # Run 320+ unit and adversarial tests
+npm run test:all     # Run full verification suite (typecheck + unit + live e2e)
+```
+
+---
+
+## Repository Structure
+
+```
+opencode-workflow-guard/
+├── src/                       # Production plugin sources
+│   ├── workflow-guard.ts      # Core server hooks & 23 deterministic policies
+│   └── workflow-guard-ui.ts   # TUI companion prompt badge
+├── test/                      # Test suites
+│   ├── test.mts               # 320+ in-memory unit & adversarial tests
+│   └── test-e2e.mts           # Live runtime OpenCode loader tests
+├── docs/                      # In-depth documentation & guides
+│   ├── installation.md        # Full setup options, worktrees & permissions
+│   ├── policies.md            # Detailed 23-policy reference & overrides
+│   ├── troubleshooting.md     # Error diagnosis & bypass explanations
+│   └── testing.md             # Test architecture & coverage matrix
+├── .changeset/                # Fragment-based versioning & release changelogs
+├── ACKNOWLEDGEMENTS.md        # Open-source community credits & inspirations
+├── CONTRIBUTING.md            # Development guide, test patterns & PR rules
+├── CHANGELOG.md               # Version history
+└── SECURITY.md                # Vulnerability disclosure policy
+```
+
+---
+
+## Summary of Enforced Policies
+
+| # | Policy Group | Summary |
+|---|---|---|
+| **1** | **Task Gate & Lifecycle** | Gates file mutations on active `todowrite` tasks. Prevents silent task deletion; allows flexible completion order. |
+| **2 & 7** | **Branch Protection** | Blocks direct edits & commits on `main`/`master`. Hard-blocks `git push ... main` and forced refspecs. |
+| **3** | **PR Changelog & Changesets** | Requires PRs to include changesets (`.changeset/*.md`), `CHANGELOG.md` updates, or a `Changelog:` body section. |
+| **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. |
+| **5** | **MCP Mutation Guard** | Blocks mutating GitHub & Azure DevOps MCP tools while allowing read-only inspection tools. |
+| **6** | **Settings Tamper Guard** | Blocks agent modification of `opencode.json`, `.opencode/*`, or the guard's own plugin files. |
+| **8** | **Workspace Boundary Guard** | Confines file mutations and shell redirects strictly within the project workspace root (symlink & `../` escape safe). |
+| **10** | **Evidence-Based Verification** | Runs test verification before final task completion. Binds freshness to git state with token-efficient output snipping. |
+| **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=********`). |
+| **13 & 14** | **Audit Trail & Attribution** | Durable JSONL audit logging (`~/.local/state/opencode/workflow-guard/workflow-guard.jsonl`) with subagent hierarchy breadcrumbs. |
+| **15 & 16** | **Compaction & TUI Feedback** | Preserves active task plans across context compactions; emits real-time TUI warning toasts and native desktop alerts. |
+| **18** | **Interpreter Inline Evasion** | Scans inline scripts (`python -c`, `node -e`, `base64 | sh`) for smuggled live commands or config tampering. |
+| **19 & 20** | **Pre-Flight Conflicts & Freshness** | Verifies clean `git merge-tree` mergeability and checks local base branch freshness before opening PRs. |
+| **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`. |
+
+👉 **For complete policy specifications and override rules, see [docs/policies.md](docs/policies.md).**
+
+---
+
+## Custom Tools Registered in OpenCode
+
+* `guard_status`: Inspect active guardrails, current branch protection, and verification/review status.
+* `guard_audit`: View recent audit log entries recorded in `workflow-guard.jsonl`.
+* `guard_why`: Simulate and explain whether a specific tool call or command would be blocked.
+* `record_review`: Record secondary reviewer subagent approval or critique across the 5 core review axes.
+* `guard_worktree_create`: Create an isolated git worktree (with shared `node_modules` symlink) for concurrent subagent execution; rejects invalid and protected branch names.
+* `guard_worktree_cleanup`: Snapshot-commit remaining changes and remove an isolated worktree directory.
+
+---
+
+## Documentation & Community
+
+* [Installation Guide](docs/installation.md)
+* [Policies & Overrides Reference](docs/policies.md)
+* [Troubleshooting Guide](docs/troubleshooting.md)
+* [Testing Guide](docs/testing.md)
+* [Contributing Guide](CONTRIBUTING.md)
+* [Acknowledgements & Ecosystem Credits](ACKNOWLEDGEMENTS.md)
+* [Security Policy](SECURITY.md)
+
+---
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opencode-workflow-guard",
+  "version": "1.1.0",
+  "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/workflow-guard.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ultus-net/opencode-workflow-guard.git"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "ACKNOWLEDGEMENTS.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "guard",
+    "workflow"
+  ],
+  "scripts": {
+    "test": "node test/test.mts",
+    "test:install": "node test/test-e2e.mts",
+    "test:all": "npm run typecheck && npm test && npm run test:install",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc --noEmit -p tsconfig.json",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.18.21"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.1",
+    "@opentui/solid": "^0.5.6",
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  }
+}

package/src/workflow-guard-ui.ts

@@ -0,0 +1,48 @@
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
+import type { JSX } from "@opentui/solid";
+import { createElement, insert, setProp } from "@opentui/solid";
+
+type Child = JSX.Element | string | number | null | undefined | false;
+
+function element(
+	tag: string,
+	props: Record<string, unknown>,
+	children: Child[] = [],
+) {
+	const node = createElement(tag);
+	for (const [key, value] of Object.entries(props)) {
+		if (value !== undefined) setProp(node, key, value);
+	}
+	for (const child of children) {
+		if (child === null || child === undefined || child === false) continue;
+		insert(node, child);
+	}
+	return node as unknown as JSX.Element;
+}
+
+function text(props: Record<string, unknown>, children: Child[]) {
+	return element("text", props, children);
+}
+
+const BADGE = "🛡️ [Workflow Guard: Active]";
+
+export const WorkflowGuardTui: TuiPlugin = async (api) => {
+	api.slots.register({
+		order: 1,
+		slots: {
+			home_prompt_right() {
+				const theme = api.theme.current;
+				return text({ fg: theme.success }, [BADGE]);
+			},
+			session_prompt_right() {
+				const theme = api.theme.current;
+				return text({ fg: theme.success }, [BADGE]);
+			},
+		},
+	});
+};
+
+export default {
+	id: "workflow-guard-ui",
+	tui: WorkflowGuardTui,
+} satisfies TuiPluginModule;