opencode-workflow-guard 1.15.3 → 1.15.5

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm](https://img.shields.io/npm/v/opencode-workflow-guard.svg)](https://www.npmjs.com/package/opencode-workflow-guard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-415%2B%20passing-brightgreen.svg)](test/test.mts)
+[![Tests](https://img.shields.io/badge/tests-1100%2B%20passing-brightgreen.svg)](test/test.mts)
 
-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.
+Deterministic policy and enforcement layer for OpenCode. Workflow Guard enforces safe engineering discipline through **hard plugin hooks**, not prompt instructions that LLMs can ignore, and pairs enforcement with a proactive workflow-tool surface for planning, review, worktree isolation, technical debt, and policy simulation.
 
 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.
 
@@ -34,7 +34,7 @@ For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`.
 
 ```bash
 npm run typecheck    # Strict TypeScript check (0 errors)
-npm test             # Run 415+ unit and adversarial tests
+npm test             # Run 1100+ unit and adversarial tests
 npm run test:all     # Typecheck + unit + install/load checks
 WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run policy probes with OpenCode's most recently selected model
 ```
@@ -54,11 +54,27 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 
 ---
 
+## Proactive Workflow Tools
+
+Enforcement is only half the surface. The plugin also registers first-class agent tools (same tool names on OpenCode 1.x and 2.x) so disciplined workflow is the path of least resistance:
+
+* **Task Planning:** `guard_next_tasks` surfaces durable repository planning context (`TODO.md`, `ROADMAP.md`, `PLAN.md`, `TASKS.md`, `BACKLOG.md`, their `docs/` counterparts, and plans under `docs/plans/`) at session start or during planning; `guard_status` reports active guardrails, branch protection, mutation counts, outstanding verification/review gates, a read-only git-hygiene snapshot, and the loaded `pluginVersion`.
+* **Review & Verification:** before PR creation, a secondary reviewer subagent evaluates the diff against `guard_review_rubric` (five core axes: test integrity, task completeness, cleanliness, security, platform) and records its verdict with `record_review`; approvals are bound to the reviewed worktree content.
+* **Worktree Isolation:** `guard_worktree_create` and `guard_worktree_cleanup` give parallel subagents isolated linked worktrees so concurrent mutations never collide.
+* **Technical Debt:** `guard_review_followups` lists open P2/P3 durable review follow-ups; `guard_review_followup_resolve` closes them after the underlying issue is fixed and verified.
+* **Policy Simulation:** `guard_why` returns the structured policy decision for a tool call or command without performing it; `guard_audit` shows recent audited policy entries.
+* **Project Memory** (on by default): `project_memory_search`, `project_memory_record`, `project_memory_export`, and `project_memory_import` maintain durable facts, decisions, constraints, and lessons; secret content is rejected, and export promotes records to the repo-local `.opencode/memory/project-memory.jsonl`.
+* **Socratic Learning** (off by default): `learning_checkpoint`, `learning_profile`, and `learning_record` maintain a global evidence-based learner profile with a per-session intervention budget.
+
+The context modules — project memory, Socratic learning, and recovery checkpoints (`guard_recovery_restore`) — are independently gated and can be disabled without weakening policy enforcement; see [docs/installation.md](docs/installation.md). Full tool specifications live in [docs/policies.md](docs/policies.md#custom-tools).
+
+---
+
 ## Documentation Index
 
 | Guide | Description |
 |---|---|
-| [**Policy Reference**](docs/policies.md) | Comprehensive specification of all 24 enforced policies, invariants, and override semantics |
+| [**Policy Reference**](docs/policies.md) | Comprehensive specification of all 24 enforced policies, invariants, and the proactive tool surface (`guard_*`, `project_memory_*`, `learning_*`) |
 | [**Installation & Configuration**](docs/installation.md) | Setup options, global vs. local install, worktree isolation, and project configuration |
 | [**Managed Deployment**](docs/managed-deployment.md) | Administrator-managed OpenCode policy, platform locations, and startup diagnostics |
 | [**Troubleshooting**](docs/troubleshooting.md) | Diagnosing policy blocks, common false positives, and emergency override procedures |

package/docs/installation.md

@@ -206,7 +206,7 @@ Project memory is optional supporting context, enabled by default, and requires
 
 The plugin exposes `project_memory_search`, `project_memory_record`, `project_memory_export`, and `project_memory_import`. Recording is intended only for durable facts, decisions, constraints, and lessons; recognized secret content is rejected. Routine tool/test/verification output, transient errors and retries, successful operational telemetry, todos, and session progress belong in their existing operational stores rather than project memory.
 
-Project-memory maintenance runs opportunistically when a project index is opened, at most once per day. Superseded memories and resolved review follow-ups are retained for 90 days and then pruned; current memories are not expired just because they are old. Maintenance checkpoints and compacts the active SQLite database. When the project-memory directory exceeds 100 MB, least-recently-used inactive project databases are evicted toward about 80 MB when eligible databases exist. The current project's database is never selected for global eviction, and maintenance failures do not disable core guard enforcement.
+Project-memory maintenance runs opportunistically when a project index is opened, at most once per day. Superseded memories and resolved review follow-ups are retained for 90 days and then pruned; current memories are not expired just because they are old. Maintenance checkpoints and compacts the active SQLite database, and reaps coordination markers (`*.sqlite.active.*`) left behind by processes that died without closing their store; markers owned by live or unidentifiable processes are never removed. When the project-memory directory exceeds 100 MB, least-recently-used inactive project databases are evicted toward about 80 MB when eligible databases exist. The current project's database is never selected for global eviction, and maintenance failures do not disable core guard enforcement.
 
 Portable project knowledge lives at the fixed path `.opencode/memory/project-memory.jsonl`. Importing that file bootstraps the local index, but exporting is always explicit and accepts selected record IDs rather than dumping private working memory. The plugin adds `.opencode/memory/` to `.git/info/exclude` for the local clone. To share promoted knowledge through Git, deliberately remove that local exclusion or force-add the JSONL file after reviewing its contents. Do not commit the SQLite database.
 

package/package.json

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

package/src/lib/project-memory.ts

@@ -150,6 +150,21 @@ function databaseIsActive(path: string, directory: string): boolean {
 	return active;
 }
 
+function reapStaleActiveMarkers(directory: string): void {
+	const databaseNames = new Set(readdirSync(directory).filter((entry) => entry.endsWith(".sqlite")));
+	for (const name of readdirSync(directory)) {
+		const markerSeparator = name.lastIndexOf(".active.");
+		if (markerSeparator < 0) continue;
+		const databaseName = name.slice(0, markerSeparator);
+		if (!databaseNames.has(databaseName)) continue;
+		const pid = Number(name.slice(markerSeparator + ".active.".length).split(".", 1)[0]);
+		if (!Number.isInteger(pid) || pid <= 0) continue;
+		try { process.kill(pid, 0); } catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ESRCH") rmSync(join(directory, name), { force: true });
+		}
+	}
+}
+
 export function maintainProjectMemoryStorage(store: ProjectMemoryStore, directory = getProjectMemoryDir(), options: MaintenanceOptions = {}): void {
 	const now = options.now ?? Date.now();
 	const maintenanceMarker = `${store.path}.maintenance`;
@@ -173,6 +188,7 @@ export function maintainProjectMemoryStorage(store: ProjectMemoryStore, director
 		store.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
 		store.db.exec("PRAGMA optimize");
 		store.db.exec("VACUUM");
+		reapStaleActiveMarkers(directory);
 		try { utimesSync(store.path, now / 1000, now / 1000); } catch {}
 		writeFileSync(maintenanceMarker, "", { mode: 0o600 });
 		try { utimesSync(maintenanceMarker, now / 1000, now / 1000); } catch {}

package/test/test.mts

@@ -4878,6 +4878,29 @@ check("project memory retains newly superseded old records for the retention win
 memoryDb.db.prepare("UPDATE memories SET superseded_at = ? WHERE id = ?").run(retentionNow - 91 * 24 * 60 * 60 * 1000, oldCurrentMemory.id);
 maintainProjectMemoryStorage(memoryDb, memoryDir, { now: retentionNow + 1_000 });
 check("project memory maintenance is throttled to once per day", memoryDb.db.prepare("SELECT 1 FROM memories WHERE id = ?").get(oldCurrentMemory.id) !== undefined);
+const reapDeadChild = spawnSync(process.execPath, ["-e", "process.exit(0)"], { stdio: "ignore" });
+const staleMarkerDb = join(memoryDir, "stale-marker-project.sqlite");
+writeFileSync(staleMarkerDb, "x".repeat(64));
+const staleDeadMarker = `${staleMarkerDb}.active.${reapDeadChild.pid}.dead`;
+const staleLiveMarker = `${staleMarkerDb}.active.${process.pid}.live`;
+const staleOpaqueMarker = `${staleMarkerDb}.active.opaque`;
+const trickyProjectDb = join(memoryDir, "tricky.sqlite.active.55.sqlite");
+const trickyDeadMarker = `${trickyProjectDb}.active.${reapDeadChild.pid}.dead`;
+const trickyLiveMarker = `${trickyProjectDb}.active.${process.pid}.live`;
+writeFileSync(staleDeadMarker, "");
+writeFileSync(staleLiveMarker, "");
+writeFileSync(staleOpaqueMarker, "");
+writeFileSync(trickyProjectDb, "x".repeat(32));
+writeFileSync(trickyDeadMarker, "");
+writeFileSync(trickyLiveMarker, "");
+maintainProjectMemoryStorage(memoryDb, memoryDir, { force: true, now: retentionNow + 25 * 60 * 60 * 1000 });
+check("project memory reaps markers of dead owners during maintenance without storage pressure", !existsSync(staleDeadMarker) && existsSync(staleLiveMarker) && existsSync(staleOpaqueMarker));
+check("project memory reap never removes a database file or live marker for tricky names", existsSync(trickyProjectDb) && !existsSync(trickyDeadMarker) && existsSync(trickyLiveMarker));
+rmSync(staleLiveMarker, { force: true });
+rmSync(staleOpaqueMarker, { force: true });
+rmSync(staleMarkerDb, { force: true });
+rmSync(trickyLiveMarker, { force: true });
+rmSync(trickyProjectDb, { force: true });
 const privateFact = recordProjectMemory(memoryDb, { kind: "fact", content: "A transient local observation.", source: "agent" });
 const portableConstraint = recordProjectMemory(memoryDb, { kind: "constraint", content: "Project memory committed to Git must be human-readable.", source: "user" });
 const portablePath = join(root, ".opencode", "memory", "project-memory.jsonl");