opencode-workflow-guard 1.1.5 → 1.3.0

package/README.md

@@ -38,11 +38,13 @@ npm run test:all     # Run full verification suite (typecheck + unit + live e2e)
 ```
 opencode-workflow-guard/
 ├── src/                       # Production plugin sources
-│   ├── workflow-guard.ts      # Core server hooks & 23 deterministic policies
-│   └── workflow-guard-ui.ts   # TUI companion prompt badge
+│   ├── workflow-guard.ts      # Server plugin entrypoint (hook orchestrator & public exports)
+│   ├── workflow-guard-ui.ts   # TUI companion prompt badge
+│   ├── policies/              # Per-policy implementations (task gate, git, secrets, shell-safety, ...)
+│   └── lib/                   # Engine services (state, verify, audit, review, worktree, utils, types)
 ├── test/                      # Test suites
 │   ├── test.mts               # 320+ in-memory unit & adversarial tests
-│   └── test-e2e.mts           # Live runtime OpenCode loader tests
+│   └── test-e2e.mts           # npm tarball resolution + live runtime OpenCode loader tests
 ├── docs/                      # In-depth documentation & guides
 │   ├── installation.md        # Full setup options, worktrees & permissions
 │   ├── policies.md            # Detailed 23-policy reference & overrides
@@ -77,6 +79,7 @@ opencode-workflow-guard/
 | **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`. |
+| **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`. |
 
 👉 **For complete policy specifications and override rules, see [docs/policies.md](docs/policies.md).**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.1.5",
+  "version": "1.3.0",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",

package/src/lib/audit.ts

@@ -0,0 +1,110 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AuditEntry, VerifyResult } from "./types.ts";
+import { asRecord } from "./utils.ts";
+
+const AUDIT_DIR = join(
+	process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"),
+	"opencode",
+	"workflow-guard",
+);
+const AUDIT_FILE = join(AUDIT_DIR, "workflow-guard.jsonl");
+const VERIFY_CACHE_FILE = join(AUDIT_DIR, "last-verify.json");
+
+export function getAuditFilePath(): string {
+	return AUDIT_FILE;
+}
+
+export function getVerifyCacheFilePath(): string {
+	return VERIFY_CACHE_FILE;
+}
+
+/**
+ * Persists passing verification evidence to disk so session restarts
+ * or multi-agent handoffs retain valid verification state.
+ */
+export function persistVerifyCache(verifyData: NonNullable<VerifyResult>): void {
+	try {
+		mkdirSync(AUDIT_DIR, { recursive: true });
+		writeFileSync(VERIFY_CACHE_FILE, JSON.stringify(verifyData, null, 2), "utf8");
+	} catch {}
+}
+
+/**
+ * Loads durable verification evidence from disk if present and fresh.
+ */
+export function loadVerifyCache(): VerifyResult | undefined {
+	try {
+		if (!existsSync(VERIFY_CACHE_FILE)) return undefined;
+		const raw = readFileSync(VERIFY_CACHE_FILE, "utf8");
+		const data = JSON.parse(raw);
+		if (data && typeof data.command === "string" && typeof data.timestamp === "number") {
+			return data;
+		}
+	} catch {}
+	return undefined;
+}
+
+export function getRecentAuditEntries(limit = 10): AuditEntry[] {
+	try {
+		if (!existsSync(AUDIT_FILE)) return [];
+		const lines = readFileSync(AUDIT_FILE, "utf8").trim().split("\n");
+		const entries: AuditEntry[] = [];
+		for (let i = lines.length - 1; i >= 0 && entries.length < limit; i--) {
+			const line = lines[i]?.trim();
+			if (line) {
+				try {
+					entries.push(JSON.parse(line));
+				} catch {}
+			}
+		}
+		return entries;
+	} catch {
+		return [];
+	}
+}
+
+export function audit(entry: AuditEntry): void {
+	try {
+		mkdirSync(AUDIT_DIR, { recursive: true });
+		appendFileSync(AUDIT_FILE, JSON.stringify(entry) + "\n", "utf8");
+	} catch {
+		// Logging must never break the guard.
+	}
+}
+
+export function logDecision(
+	tool: string,
+	input: unknown,
+	context: { sessionID?: string } | undefined,
+	reason: string | undefined,
+	evidence?: AuditEntry["evidence"],
+): void {
+	audit({
+		ts: new Date().toISOString(),
+		sessionID: context?.sessionID,
+		tool,
+		decision: reason ? "block" : "allow",
+		reason,
+		input: summarizeInput(input),
+		evidence,
+	});
+}
+
+export function summarizeInput(input: unknown): unknown {
+	const record = asRecord(input);
+	if (!record) return typeof input === "string" ? input.slice(0, 200) : input;
+	if (typeof record.response === "string") {
+		return {
+			sessionID: record.sessionID,
+			permissionID: record.permissionID,
+			response: record.response,
+		};
+	}
+	if (typeof record.command === "string") return { command: record.command.slice(0, 200) };
+	if (typeof record.filePath === "string") return { filePath: record.filePath };
+	if (typeof record.path === "string") return { path: record.path };
+	if (typeof record.patchText === "string") return { patchText: record.patchText.slice(0, 200) };
+	return { keys: Object.keys(record) };
+}

package/src/lib/review.ts

@@ -0,0 +1,45 @@
+import {
+	recordReviewResult,
+	getLastReviewResult,
+	resetReviewState,
+	lastReview,
+	sessionReviews,
+} from "./state.ts";
+
+export { recordReviewResult, getLastReviewResult, resetReviewState, lastReview, sessionReviews };
+
+export function buildReviewRubric(diffText: string, taskPrompt?: string): string {
+	return [
+		"# Secondary Review Agent Quality Gate",
+		"",
+		"Evaluate this code change independently with fresh context across these 5 core axes:",
+		"",
+		"### 1. Test Integrity & Truthfulness (CRITICAL)",
+		"- Are test assertions testing real behavioral outcomes rather than trivial passes (e.g. `expect(true).toBe(true)`)?",
+		"- Were existing tests disabled, bypassed, or weakened?",
+		"- Are edge cases and error paths covered?",
+		"",
+		"### 2. Task Completeness & Intent Alignment",
+		"- Does the implementation genuinely satisfy the user request without shortcut stubs (`// TODO`, `throw new Error('not implemented')`)?",
+		"- Does it introduce regressions in surrounding code?",
+		"",
+		"### 3. Code Cleanliness & Hygiene",
+		"- Is there any orphaned dead code, commented-out code blocks, or temporary debugging logs?",
+		"- Is the logic straightforward and free of unnecessary cognitive complexity?",
+		"",
+		"### 4. Security & Safety Boundaries",
+		"- Are there any hardcoded secrets, unprotected tokens, or unvalidated user inputs?",
+		"- Does the code respect workspace confinement and safe environment practices?",
+		"",
+		"### 5. Platform & Architecture Fit (GitHub & Azure DevOps)",
+		"- Does the change fit established repository patterns and CI/CD pipelines?",
+		"",
+		taskPrompt ? `### User Request / Context:\n${taskPrompt}\n` : "",
+		"### Code Diff Under Review:",
+		"```diff",
+		diffText.slice(0, 30_000),
+		"```",
+		"",
+		"Provide your verdict: `[APPROVE]` or `[REQUEST_CHANGES]` with concise, actionable findings.",
+	].join("\n");
+}

package/src/lib/state.ts

@@ -0,0 +1,210 @@
+import { realpathSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { persistVerifyCache } from "./audit.ts";
+import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary } from "./verify.ts";
+import type {
+	TodoSdkClient,
+	ProjectConfig,
+	VerifyResult,
+	ReviewResult,
+} from "./types.ts";
+
+export let workspaceRoot = process.cwd();
+export let workspaceRootReal = workspaceRoot;
+interface RuntimeState {
+	workspaceRoot: string;
+	workspaceRootReal: string;
+	sdkClient: TodoSdkClient | undefined;
+	projectConfig: ProjectConfig;
+}
+const runtimeState = new AsyncLocalStorage<RuntimeState>();
+
+try {
+	workspaceRootReal = realpathSync(workspaceRoot);
+} catch {}
+
+export function setWorkspaceRoot(root: string): void {
+	workspaceRoot = root;
+	try {
+		workspaceRootReal = realpathSync(root);
+	} catch {
+		workspaceRootReal = root;
+	}
+}
+
+export function getWorkspaceRoot(): string {
+	return runtimeState.getStore()?.workspaceRoot ?? workspaceRoot;
+}
+
+export function getWorkspaceRootReal(): string {
+	return runtimeState.getStore()?.workspaceRootReal ?? workspaceRootReal;
+}
+
+export let sdkClient: TodoSdkClient | undefined;
+
+export function setSdkClient(client: unknown): void {
+	sdkClient = client as TodoSdkClient | undefined;
+}
+
+export function getSdkClient(): TodoSdkClient | undefined {
+	return runtimeState.getStore()?.sdkClient ?? sdkClient;
+}
+
+export function runWithRuntimeState<T>(root: string, client: unknown, fn: () => T): T {
+	let realRoot = root;
+	try {
+		realRoot = realpathSync(root);
+	} catch {}
+	return runtimeState.run(
+		{
+			workspaceRoot: root,
+			workspaceRootReal: realRoot,
+			sdkClient: client as TodoSdkClient | undefined,
+			projectConfig: loadProjectConfig(root),
+		},
+		fn,
+	);
+}
+
+export let lastMutationTimestamp = 0;
+export let mutationCount = 0;
+export const sessionMutationTimestamps = new Map<string, number>();
+export const sessionMutationCounts = new Map<string, number>();
+
+export let lastVerify: VerifyResult | undefined;
+export const sessionVerifyResults = new Map<string, NonNullable<VerifyResult>>();
+
+export let lastReview: ReviewResult | undefined;
+export const sessionReviews = new Map<string, ReviewResult>();
+
+export function recordMutation(sessionID?: string): void {
+	lastMutationTimestamp = Date.now();
+	mutationCount++;
+	if (sessionID) {
+		sessionMutationTimestamps.set(sessionID, lastMutationTimestamp);
+		sessionMutationCounts.set(sessionID, (sessionMutationCounts.get(sessionID) ?? 0) + 1);
+		sessionVerifyResults.delete(sessionID);
+	}
+	if (sessionID) sessionReviews.delete(sessionID);
+	if (!lastReview?.targetSessionID || lastReview.targetSessionID === sessionID) {
+		lastReview = undefined;
+	}
+}
+
+export function getMutationCount(sessionID?: string): number {
+	if (sessionID && sessionMutationCounts.has(sessionID)) {
+		return sessionMutationCounts.get(sessionID) ?? 0;
+	}
+	return mutationCount;
+}
+
+export function getLastMutationTimestamp(): number {
+	return lastMutationTimestamp;
+}
+
+export function getLastVerifyResult(): typeof lastVerify {
+	return lastVerify;
+}
+
+export function recordVerifyResult(
+	command: string,
+	result: { passed: boolean; output: string; durationMs?: number },
+	sessionID?: string,
+	root = getWorkspaceRoot(),
+): void {
+	lastVerify = {
+		command,
+		passed: result.passed,
+		output: snipVerifyOutput(result.output, result.passed),
+		timestamp: Date.now(),
+		durationMs: result.durationMs,
+		commitHash: getCurrentGitCommitHash(root),
+		gitStatus: getGitStatusSummary(root),
+		workspaceRoot: resolve(root),
+	};
+	if (sessionID && lastVerify) sessionVerifyResults.set(sessionID, lastVerify);
+	if (lastVerify.passed) {
+		persistVerifyCache(lastVerify);
+	}
+}
+
+export function setLastVerifyResult(result: NonNullable<VerifyResult>): void {
+	lastVerify = result;
+}
+
+export function resetVerifyState(): void {
+	lastMutationTimestamp = 0;
+	mutationCount = 0;
+	lastVerify = undefined;
+	sessionMutationTimestamps.clear();
+	sessionMutationCounts.clear();
+	sessionVerifyResults.clear();
+}
+
+export function recordReviewResult(
+	reviewer: string,
+	summary: string,
+	passed: boolean,
+	targetSessionID?: string,
+	workspace?: string,
+): void {
+	lastReview = {
+		reviewer,
+		summary: summary.slice(-4000),
+		passed,
+		timestamp: Date.now(),
+		targetSessionID,
+		workspace,
+	};
+	if (targetSessionID) sessionReviews.set(targetSessionID, lastReview);
+}
+
+export function getLastReviewResult(): typeof lastReview {
+	return lastReview;
+}
+
+export function resetReviewState(): void {
+	lastReview = undefined;
+	sessionReviews.clear();
+}
+
+export let cachedProjectConfig: ProjectConfig | undefined;
+
+export function loadProjectConfig(root: string): ProjectConfig {
+	const candidates = [
+		join(root, ".opencode", "workflow-guard.json"),
+		join(root, ".opencode", "workflow-guard.jsonc"),
+		join(root, "workflow-guard.json"),
+		join(root, "workflow-guard.jsonc"),
+	];
+	for (const candidate of candidates) {
+		try {
+			const raw = readFileSync(candidate, "utf8");
+			return JSON.parse(raw);
+		} catch {}
+	}
+	return {};
+}
+
+export function reloadProjectConfig(root: string): void {
+	cachedProjectConfig = loadProjectConfig(root);
+}
+
+export function getProjectConfig(root: string): ProjectConfig {
+	const active = runtimeState.getStore();
+	if (active?.workspaceRoot === root) return active.projectConfig;
+	return cachedProjectConfig ?? loadProjectConfig(root);
+}
+
+export function isReviewRequired(root: string): boolean {
+	if (process.env.WORKFLOW_GUARD_REQUIRE_REVIEW === "1") return true;
+	const cfg = getProjectConfig(root);
+	return cfg.requireReview === true;
+}
+
+export function isDocumentationRequired(root: string): boolean {
+	if (process.env.WORKFLOW_GUARD_REQUIRE_DOCS === "1") return true;
+	const cfg = getProjectConfig(root);
+	return cfg.requireDocumentation === true;
+}

package/src/lib/types.ts

@@ -0,0 +1,75 @@
+export interface TodoItem {
+	content?: unknown;
+	status?: unknown;
+}
+
+export interface TodoSdkClient {
+	session?: {
+		todo?: (opts: { path: { id: string } }) => Promise<{ data?: unknown }>;
+		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown } }>;
+	};
+	tui?: {
+		showToast?: (opts: { body: { title?: string; message: string; variant?: string } }) => Promise<unknown>;
+	};
+	lsp?: {
+		status?: () => Promise<{ data?: unknown }>;
+	};
+}
+
+export interface ProjectConfig {
+	protectedBranches?: string[];
+	verifyCommand?: string;
+	requireReview?: boolean;
+	requireDocumentation?: boolean;
+}
+
+export interface VerifyResult {
+	passed: boolean;
+	command: string;
+	output: string;
+	timestamp: number;
+	durationMs?: number;
+	commitHash?: string;
+	gitStatus?: string;
+	workspaceRoot?: string;
+}
+
+export interface ReviewResult {
+	passed: boolean;
+	reviewer: string;
+	summary: string;
+	timestamp: number;
+	targetSessionID?: string;
+	workspace?: string;
+}
+
+export interface AuditEntry {
+	ts: string;
+	sessionID?: string;
+	tool: string;
+	decision: "allow" | "block";
+	reason?: string;
+	input?: unknown;
+	evidence?: {
+		mutation?: boolean;
+		targetPath?: string;
+		verification?: {
+			command: string;
+			passed: boolean;
+			fresh: boolean;
+			durationMs?: number;
+		};
+		allowLive?: boolean;
+	};
+}
+
+export interface GitInvocation {
+	repoDir: string;
+	rest: string;
+}
+
+export interface ShellMutation {
+	kind: "redirect" | "command";
+	target?: string;
+	what: string;
+}

package/src/lib/utils.ts

@@ -0,0 +1,179 @@
+import { getSdkClient } from "./state.ts";
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	return value as Record<string, unknown>;
+}
+
+export function extractCommands(input: unknown): string[] {
+	if (typeof input === "string") {
+		return [input];
+	}
+	const record = asRecord(input);
+	if (!record) {
+		return [];
+	}
+	const commands: string[] = [];
+	if (typeof record.command === "string") commands.push(record.command);
+	if (Array.isArray(record.commands)) {
+		for (const c of record.commands) {
+			if (typeof c === "string") commands.push(c);
+		}
+	}
+	return commands;
+}
+
+export function normalize(cmd: string): string {
+	return cmd.replace(/\s+/g, " ");
+}
+
+export function shellWords(command: string): string[] {
+	return (command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((word) =>
+		word.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, "$1$2"),
+	);
+}
+
+export function splitShellSegments(command: string): string[] {
+	const segments: string[] = [];
+	let current = "";
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	for (const char of command) {
+		if (escaped) {
+			current += char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\" && quote !== "'") {
+			current += char;
+			escaped = true;
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			if (!quote) quote = char;
+			else if (quote === char) quote = undefined;
+			current += char;
+			continue;
+		}
+		if (!quote && /[\n|;&]/.test(char)) {
+			if (current.trim()) segments.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	if (current.trim()) segments.push(current.trim());
+	return segments;
+}
+
+export function unwrapShellWords(command: string): string[] {
+	const words = shellWords(command.trim());
+	let i = 0;
+	while (i < words.length) {
+		if (words[i] === "command") {
+			i++;
+			continue;
+		}
+		if (words[i] === "sudo") {
+			i++;
+			const valueOptions = new Set([
+				"-u",
+				"--user",
+				"-g",
+				"--group",
+				"-h",
+				"--host",
+				"-p",
+				"--prompt",
+				"-C",
+				"--close-from",
+				"-R",
+				"--chroot",
+				"-D",
+				"--chdir",
+			]);
+			while (i < words.length && words[i]!.startsWith("-")) {
+				const option = words[i++]!;
+				if (valueOptions.has(option) && i < words.length) i++;
+			}
+			continue;
+		}
+		if (words[i] === "env") {
+			i++;
+			const valueOptions = new Set([
+				"-u",
+				"--unset",
+				"-C",
+				"--chdir",
+				"-S",
+				"--split-string",
+			]);
+			while (i < words.length) {
+				const word = words[i]!;
+				if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
+					i++;
+					continue;
+				}
+				if (!word.startsWith("-")) break;
+				i++;
+				if (valueOptions.has(word) && i < words.length) i++;
+			}
+			continue;
+		}
+		if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]!)) {
+			i++;
+			continue;
+		}
+		break;
+	}
+	return words.slice(i);
+}
+
+export function unwrapShellCommand(command: string): string {
+	return unwrapShellWords(command).join(" ");
+}
+
+export const SENSITIVE_ENV_KEYS = [
+	"GITHUB_TOKEN",
+	"GH_TOKEN",
+	"OPENAI_API_KEY",
+	"ANTHROPIC_API_KEY",
+	"OPENAI_KEY",
+	"KUBECONFIG",
+	"NPM_TOKEN",
+	"DOCKER_AUTH",
+	"GOOGLE_APPLICATION_CREDENTIALS",
+	"GCLOUD_AUTH",
+	"AZURE_CREDENTIALS",
+	"SLACK_TOKEN",
+];
+export const SENSITIVE_ENV_RE =
+	/^(AWS_|KUBE|OPENAI|ANTHROPIC|GH_|GITHUB_|GOOGLE_|GCP_|AZURE_|SLACK_|NPM_|DOCKER_|KUBECONFIG)/;
+
+export function getCleanEnv(): Record<string, string> {
+	const env: Record<string, string> = { ...(process.env as Record<string, string>) };
+	for (const key of SENSITIVE_ENV_KEYS) {
+		delete env[key];
+	}
+	for (const key of Object.keys(env)) {
+		if (SENSITIVE_ENV_RE.test(key)) {
+			delete env[key];
+		}
+	}
+	return env;
+}
+
+export async function showBlockToast(message: string): Promise<void> {
+	try {
+		const client = getSdkClient();
+		await client?.tui?.showToast?.({
+			body: {
+				title: "Workflow Guard Blocked",
+				message: message.slice(0, 180),
+				variant: "warning",
+			},
+		});
+	} catch {}
+}