opencode-workflow-guard 1.8.0 → 1.8.1
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.
- package/README.md +7 -67
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# OpenCode Workflow Guard
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/opencode-workflow-guard)
|
|
4
4
|
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
[](test/test.mts)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Deterministic policy and enforcement layer for OpenCode. Workflow Guard enforces workflow and safety invariants through **hard plugin hooks**, not prompt instructions that LLMs can ignore.
|
|
8
|
+
|
|
9
|
+
Workflow Guard is deliberately **not an agent harness**: it can constrain actions, record and explain decisions, and supply bounded context, but it does not plan, prioritize, delegate, or autonomously sequence the agent's work. Bounded continuation may resume an existing session with unfinished owned todos; it never chooses the next task or creates new work.
|
|
8
10
|
|
|
9
11
|
---
|
|
10
12
|
|
|
@@ -21,7 +23,9 @@ opencode plugin "opencode-workflow-guard@$VERSION" --global --force
|
|
|
21
23
|
|
|
22
24
|
*Requires OpenCode >= 1.18.* OpenCode detects the package's server and TUI targets and updates both global configs. Use the same command after a release to upgrade; the explicit version gives OpenCode a fresh package-cache key. Restart OpenCode after installation. See [docs/installation.md](docs/installation.md) for details and links to the OpenCode plugin documentation.
|
|
23
25
|
|
|
24
|
-
For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. Do not place the TUI module under the server `plugins/` directory.
|
|
26
|
+
For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. The companion shows a `Workflow Guard` shield in the prompt bar and reflects blocked state without changing agent behavior. Do not place the TUI module under the server `plugins/` directory.
|
|
27
|
+
|
|
28
|
+
|
|
25
29
|
|
|
26
30
|
### 2. Verification
|
|
27
31
|
|
|
@@ -61,70 +65,6 @@ For complete policy specifications and override rules, see [docs/policies.md](do
|
|
|
61
65
|
|
|
62
66
|
---
|
|
63
67
|
|
|
64
|
-
## Custom Tools Registered in OpenCode
|
|
65
|
-
|
|
66
|
-
| Tool | Purpose |
|
|
67
|
-
|---|---|
|
|
68
|
-
| `guard_next_tasks` | Load `TODO.md`, or fall back to repository roadmap/plan/task Markdown when deciding what to work on next |
|
|
69
|
-
| `guard_status` | Inspect active guardrails, current branch protection, and verification/review status |
|
|
70
|
-
| `guard_why` | Simulate and explain whether a specific tool call or command would be blocked |
|
|
71
|
-
| `guard_audit` | View recent audit log entries recorded in `workflow-guard.jsonl` |
|
|
72
|
-
| `guard_review_rubric` | Generate the 5-axis secondary review rubric for the current branch diff |
|
|
73
|
-
| `record_review` | Record a secondary reviewer subagent's verdict evaluated against the review rubric |
|
|
74
|
-
| `guard_review_followups` | List durable local P2/P3 review findings that remain open across sessions |
|
|
75
|
-
| `guard_review_followup_resolve` | Resolve a durable review finding after its underlying issue is fixed and verified |
|
|
76
|
-
| `guard_worktree_create` | Create an isolated git worktree directory for concurrent subagent execution |
|
|
77
|
-
| `guard_worktree_cleanup` | Snapshot-commit remaining changes and remove an isolated worktree directory |
|
|
78
|
-
| `learning_profile` | Inspect the evidence-based local learner profile (when learning mode is enabled) |
|
|
79
|
-
| `learning_checkpoint` | Rank high-value Socratic opportunities while respecting the session intervention budget |
|
|
80
|
-
| `learning_record` | Persist concise evidence observed during a real learning interaction |
|
|
81
|
-
| `project_memory_search` | Search current durable project knowledge in the local index |
|
|
82
|
-
| `project_memory_record` | Record a durable fact, decision, constraint, or lesson with provenance |
|
|
83
|
-
| `project_memory_export` | Explicitly promote selected records to repo-local human-readable JSONL |
|
|
84
|
-
| `project_memory_import` | Import promoted repo-local knowledge into the local index |
|
|
85
|
-
|
|
86
|
-
### Experimental Socratic Learning
|
|
87
|
-
|
|
88
|
-
Learning mode is opt-in and advisory: it never blocks tool calls or weakens deterministic guardrails. Enable it with `learning: true` in `.opencode/workflow-guard.json[c]` or through `/guard-options`; `WORKFLOW_GUARD_LEARNING=1` in the user environment also enables it regardless of project configuration. `maxLearningInterventions` defaults to 3 per session and can be set to `0` to suppress checkpoints.
|
|
89
|
-
|
|
90
|
-
The learner profile is global to the local user and follows the XDG data convention: `$XDG_DATA_HOME/opencode/workflow-guard/learner-profile.json`, or `~/.local/share/opencode/workflow-guard/learner-profile.json` when `XDG_DATA_HOME` is unset. It stores distilled concept evidence, session/project provenance, and progression (`exposed` through `critique`), not conversation transcripts or numeric grades. Unobserved concepts remain unknown rather than being labeled knowledge gaps. Back up or delete this file independently from project repositories as desired.
|
|
91
|
-
|
|
92
|
-
### Project Memory
|
|
93
|
-
|
|
94
|
-
Project memory keeps durable working knowledge between sessions without treating conversation history as project truth. It is enabled by default and can be disabled with `projectMemory: false` or through `/guard-options`. Facts, decisions, constraints, and lessons are stored in a local SQLite/FTS5 index under `$XDG_DATA_HOME/opencode/workflow-guard/project-memory/`, or `~/.local/share/opencode/workflow-guard/project-memory/` when `XDG_DATA_HOME` is unset. Git repositories are identified from their common Git directory, so linked worktrees share the same local project index.
|
|
95
|
-
|
|
96
|
-
The local index is private working memory. Nothing from it is committed automatically. `project_memory_export` promotes only the explicitly selected current record IDs to `.opencode/memory/project-memory.jsonl`, a human-readable portable representation that another clone can import. The plugin adds `.opencode/memory/` to the clone-local `.git/info/exclude` by default; teams that deliberately want to version promoted knowledge can remove that exclusion or force-add the JSONL file. SQLite databases themselves should not be committed.
|
|
97
|
-
|
|
98
|
-
Memory is supporting context, not authority. Superseded records are excluded from normal retrieval, recording and plugin imports reject content recognized by Workflow Guard's secret detector, and compaction injects at most eight recent current local records. Portable repository records are never injected automatically; they are available through explicit memory search after import. A local record tied to repository paths and a Git commit is omitted from compaction when those paths have committed, staged, or unstaged changes after that commit. Always prefer current repository state when it conflicts with historical memory.
|
|
99
|
-
|
|
100
|
-
---
|
|
101
|
-
|
|
102
|
-
## Repository Tree
|
|
103
|
-
|
|
104
|
-
```
|
|
105
|
-
opencode-workflow-guard/
|
|
106
|
-
├── src/ # Production plugin sources
|
|
107
|
-
│ ├── workflow-guard.ts # Server plugin entrypoint (hook orchestrator & public exports)
|
|
108
|
-
│ ├── workflow-guard-ui.ts # Optional TUI companion prompt badge
|
|
109
|
-
│ ├── policies/ # Modular policy implementations (task gate, git, secrets, boundary, ...)
|
|
110
|
-
│ └── lib/ # Engine services (state, verify, audit, review, worktree, utils, types)
|
|
111
|
-
├── test/ # Test suites
|
|
112
|
-
│ ├── test.mts # 415+ in-memory unit & adversarial tests
|
|
113
|
-
│ └── test-e2e.mts # npm tarball resolution + live runtime OpenCode loader tests
|
|
114
|
-
├── docs/ # In-depth documentation & guides
|
|
115
|
-
│ ├── policies.md # Complete 24-policy reference & overrides
|
|
116
|
-
│ ├── installation.md # Setup options, worktrees & permissions
|
|
117
|
-
│ ├── troubleshooting.md # Error diagnosis & bypass explanations
|
|
118
|
-
│ └── testing.md # Test architecture & coverage matrix
|
|
119
|
-
├── .changeset/ # Fragment-based versioning & release changelogs
|
|
120
|
-
├── ACKNOWLEDGEMENTS.md # Open-source community credits & inspirations
|
|
121
|
-
├── CONTRIBUTING.md # Development guide, test patterns & PR rules
|
|
122
|
-
├── CHANGELOG.md # Version history
|
|
123
|
-
└── SECURITY.md # Vulnerability disclosure policy
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
---
|
|
127
|
-
|
|
128
68
|
## License
|
|
129
69
|
|
|
130
70
|
[MIT](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "opencode-workflow-guard",
|
|
3
|
-
"version": "1.8.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.8.1",
|
|
4
|
+
"description": "Deterministic workflow and safety policy enforcement for OpenCode",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "src/workflow-guard.ts",
|