opencode-workflow-guard 1.11.0 → 1.12.0

package/docs/policies.md

@@ -108,11 +108,13 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 
 ### 15. Compaction State & Policy Context Preservation
 - Integrates with OpenCode's `experimental.session.compacting` hook to inject bounded active policy state into `output.context` before context summarization:
+  - Caps injected continuity context at 8,000 characters, preserving operational guard state first and filling the remaining budget with active tasks, review follow-ups, and fresh local project memory.
   - Active `todowrite` tasks with status badges and subagent hierarchy attribution.
   - Active Git branch name and protected branch status.
   - Test verification status (passed/failed, test command, and commit hash).
   - Secondary review verdicts (reviewer name and approval status).
   - Uncommitted mutation counts.
+- Compacted project-memory context points back to `project_memory_search` for deeper historical retrieval instead of attempting to embed the full durable store.
 - Preserves policy-relevant context across session compactions without assigning, prioritizing, or sequencing tasks for the model.
 
 ### 16. TUI Visual Feedback & Static Status Badge
@@ -155,8 +157,13 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - Mismatches (failing verification, stale evidence due to mutations after the verify run, or no evidence at all) are journaled to the audit trail and logged at info level. This is **observability, not gating**: the response is never blocked, but a confident wrap-up cannot silently contradict a failing or absent verification state.
 - Uses the `experimental.text.complete` hook; claim detection is a conservative phrase heuristic to avoid false positives on casual wording.
 
-### Tool Description Honesty
-- Via the `tool.definition` hook, the guard enriches the `todowrite` tool's description with its replacement-list lifecycle and finalization gates (including verification evidence required after the last mutation), so the model is not surprised by preventable lifecycle blocks. Other tools are untouched, and the enrichment is idempotent.
+### Tool Description Honesty & Cross-Model Adherence
+- Via the `tool.definition` hook, the guard enriches tool descriptions to keep them honest and proactive across all model families (OpenAI, Gemini, Claude, and open-weights models):
+  - `todowrite`: Explains its replacement-list lifecycle, finalization verification gate, and directs models to `guard_next_tasks` for roadmap discovery and `guard_status` for gate checks.
+  - Mutating tools (`edit`, `write`, `apply_patch`): States preconditions (active todo, feature branch, prior read).
+  - `task`: Guides orchestrator agents to isolate parallel mutations with `guard_worktree_create` and conduct secondary reviews via `guard_review_rubric` and `record_review`.
+- Via the `experimental.chat.system.transform` hook, the guard provides concise operational guidelines in the system prompt detailing available guard tools (`guard_next_tasks`, `guard_status`, `guard_review_rubric`, `guard_worktree_create`, `project_memory_*`, `learning_*`, `guard_why`), heavily encouraging open models and Gemini/Claude to proactively use workflow discipline features throughout development.
+- Companion tools feature proactive action triggers ("Proactively call...", "Recommended at session start..."), and `guard_status` returns actionable `recommendedActions` directing models to the exact next step.
 
 ---
 

package/package.json

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

package/src/lib/custom-tools.ts

@@ -53,6 +53,51 @@ export function extractReviewFollowups(summary: string): Array<{ severity: "P2"
 		.map((finding) => ({ severity: finding.severity, summary: finding.line }));
 }
 
+export function buildWorkflowGuardSystemGuidance(options: {
+	projectMemoryEnabled?: boolean;
+	learningEnabled?: boolean;
+	recoveryCheckpointsEnabled?: boolean;
+	isReadOnly?: boolean;
+}): string {
+	const sections: string[] = [
+		"## Workflow Guard & Operational Tools",
+		"Workflow Guard enforces safe engineering discipline and provides proactive workflow tools:",
+		"- Task Planning: Proactively call `guard_next_tasks` at session start or when planning work to discover repository roadmap, plan, and TODO items. Check `guard_status` to inspect branch protection, mutation count, and outstanding verification/review gates.",
+	];
+
+	if (!options.isReadOnly) {
+		sections.push(
+			"- Review & Verification: Before completing tasks or creating PRs, run tests to produce fresh verification evidence, retrieve the review rubric via `guard_review_rubric` (5 core axes: test integrity, task completeness, cleanliness, security, platform), and spawn a reviewer subagent via `task` that records its verdict with `record_review`.",
+			"- Worktree Isolation: When orchestrating parallel subagent tasks with `task`, call `guard_worktree_create` to prevent concurrent file conflicts, and `guard_worktree_cleanup` when finished.",
+		);
+	}
+
+	sections.push(
+		"- Technical Debt: Inspect open P2/P3 review follow-ups with `guard_review_followups` during planning; resolve fixed items with `guard_review_followup_resolve`.",
+		"- Policy Simulation: If uncertain whether a command or file edit is permitted, simulate it with `guard_why`.",
+	);
+
+	if (options.projectMemoryEnabled) {
+		sections.push(
+			"- Project Memory: Proactively call `project_memory_search` before architectural changes or complex implementations. Record durable lessons, architectural decisions, and repo constraints with `project_memory_record`.",
+		);
+	}
+
+	if (options.learningEnabled) {
+		sections.push(
+			"- Socratic Learning: When facing non-trivial architectural trade-offs, design choices, or debugging breakthroughs, call `learning_checkpoint`. If selected (intervene: true), ask one concise question via `question` before proceeding, and capture observed understanding with `learning_record`.",
+		);
+	}
+
+	if (options.recoveryCheckpointsEnabled) {
+		sections.push(
+			"- Recovery: If workspace state needs rollback to the pre-run checkpoint, use `guard_recovery_restore`.",
+		);
+	}
+
+	return sections.join("\n");
+}
+
 export function createCustomTools(options: {
 	effectiveRoot: string;
 	projectMemoryEnabled: boolean;
@@ -80,7 +125,7 @@ export function createCustomTools(options: {
 			}),
 		} : {}),
 		guard_next_tasks: tool({
-			description: "Load durable repository task context when deciding what to work on next. Prefers TODO.md; if absent, discovers conventional roadmap, plan, tasks, backlog, and docs/plans Markdown files.",
+			description: "Load durable repository task context when deciding what to work on next or planning upcoming steps. Proactively call at session start or during planning to discover roadmap, plan, tasks, backlog, and TODO.md files.",
 			args: {},
 			execute: async () => {
 				const sources = discoverPlanningSources(effectiveRoot);
@@ -89,12 +134,12 @@ export function createCustomTools(options: {
 		}),
 		...(projectMemoryEnabled ? {
 			project_memory_search: tool({
-				description: "Search current durable knowledge for this project. Returns concise typed records with provenance; superseded records are excluded.",
+				description: "Search current durable knowledge for this project, including past architectural decisions, constraints, and conventions. Proactively call before starting complex architectural changes, refactors, or new feature implementations.",
 				args: { query: tool.schema.string() },
 				execute: async (args) => projectMemory ? JSON.stringify(args.query.length <= 500 ? searchProjectMemory(projectMemory, args.query, 8) : [], null, 2) : "[workflow-guard] Project memory unavailable; core guard enforcement remains active.",
 			}),
 			project_memory_record: tool({
-				description: "Record a durable project fact, decision, constraint, or lesson when it will matter in future sessions. Do not record transient tool output, secrets, or speculative hypotheses.",
+				description: "Record a durable project fact, decision, constraint, or lesson when it will matter in future sessions. Proactively call after making important architectural choices, discovering tricky repo constraints, or establishing new patterns.",
 				args: { kind: tool.schema.string().describe("fact, decision, constraint, or lesson"), content: tool.schema.string(), paths: tool.schema.array(tool.schema.string()), supersedes: tool.schema.string().optional() },
 				execute: async (args, toolContext) => {
 					if (!projectMemory) return "[workflow-guard] Project memory unavailable; core guard enforcement remains active.";
@@ -105,7 +150,7 @@ export function createCustomTools(options: {
 				},
 			}),
 			project_memory_export: tool({
-				description: "Explicitly promote selected durable project-memory records to the human-readable repo-local .opencode/memory/project-memory.jsonl file. Nothing is exported automatically.",
+				description: "Explicitly promote selected durable project-memory records to the human-readable repo-local .opencode/memory/project-memory.jsonl file. Call when durable knowledge should be committed and shared with the team.",
 				args: { ids: tool.schema.array(tool.schema.string()) },
 				execute: async (args) => {
 					if (!projectMemory) return "[workflow-guard] Project memory unavailable; core guard enforcement remains active.";
@@ -114,12 +159,12 @@ export function createCustomTools(options: {
 					return `[workflow-guard] Exported ${count} project-memory record(s) to .opencode/memory/project-memory.jsonl.`;
 				},
 			}),
-			project_memory_import: tool({ description: "Import the fixed repo-local .opencode/memory/project-memory.jsonl file into this project's local working-memory index.", args: {}, execute: async () => projectMemory ? `[workflow-guard] Imported ${importProjectKnowledge(projectMemory, portableMemoryPath, (content) => secretIn(content) !== undefined)} new project-memory record(s).` : "[workflow-guard] Project memory unavailable; core guard enforcement remains active." }),
+			project_memory_import: tool({ description: "Import the repo-local .opencode/memory/project-memory.jsonl file into this project's local working-memory index. Call to synchronize local project memory with shared repository records.", args: {}, execute: async () => projectMemory ? `[workflow-guard] Imported ${importProjectKnowledge(projectMemory, portableMemoryPath, (content) => secretIn(content) !== undefined)} new project-memory record(s).` : "[workflow-guard] Project memory unavailable; core guard enforcement remains active." }),
 		} : {}),
 		...(learningEnabled ? {
-			learning_profile: tool({ description: "Inspect the local evidence-based learner profile so teaching can build on demonstrated knowledge without assuming unobserved concepts are gaps.", args: {}, execute: async () => JSON.stringify(loadLearnerProfile(), null, 2) }),
+			learning_profile: tool({ description: "Inspect the local evidence-based learner profile so explanations and teaching can build on demonstrated knowledge without assuming unobserved concepts are gaps.", args: {}, execute: async () => JSON.stringify(loadLearnerProfile(), null, 2) }),
 			learning_checkpoint: tool({
-				description: "At a high-value design decision, debugging moment, or important new concept, rank candidate Socratic learning opportunities. If one is selected, ask one concise question before continuing the work; do not turn routine syntax into a lesson.",
+				description: "At a high-value design decision, debugging moment, or important new concept, rank candidate Socratic learning opportunities. Proactively call when encountering non-trivial architectural trade-offs, design choices, or tricky bugs. If selected (intervene: true), ask one concise question via question before continuing; do not turn routine syntax into a lesson.",
 				args: { opportunities: tool.schema.array(tool.schema.object({ type: tool.schema.string().describe("design, debugging, or new-concept"), concept: tool.schema.string().describe("Transferable engineering concept"), relevance: tool.schema.number().describe("Current-task relevance from 0 to 1"), consequence: tool.schema.number().describe("Decision consequence from 0 to 1") })) },
 				execute: async (args, toolContext) => {
 					const valid = args.opportunities.slice(0, 20).filter((candidate): candidate is typeof candidate & { type: "design" | "debugging" | "new-concept" } => (candidate.type === "design" || candidate.type === "debugging" || candidate.type === "new-concept") && candidate.concept.length > 0 && candidate.concept.length <= 100 && candidate.relevance >= 0 && candidate.relevance <= 1 && candidate.consequence >= 0 && candidate.consequence <= 1);
@@ -131,7 +176,7 @@ export function createCustomTools(options: {
 				},
 			}),
 			learning_record: tool({
-				description: "Record concise evidence from a real Socratic interaction after observing the learner's reasoning. Record what was demonstrated, not a grade or an inferred deficit.",
+				description: "Record concise evidence from a real Socratic interaction after observing the learner's reasoning and response to a learning checkpoint question. Record what was demonstrated, not a grade or an inferred deficit.",
 				args: { concept: tool.schema.string(), kind: tool.schema.string().describe("exposed, developing, demonstrated, independent, critique, or needs-reinforcement"), summary: tool.schema.string().describe("Short factual description of observed reasoning") },
 				execute: async (args, toolContext) => {
 					const validKinds = new Set(["exposed", "developing", "demonstrated", "independent", "critique", "needs-reinforcement"]);
@@ -151,7 +196,7 @@ export function createCustomTools(options: {
 			}),
 		} : {}),
 		guard_status: tool({
-			description: "Inspect active guardrails, current branch protection, and verification/review status.", args: {},
+			description: "Inspect active guardrails, current branch protection, mutation count, outstanding verification/review requirements, and ralph status. Proactively call at session start and before completing tasks or creating PRs.", args: {},
 			execute: async (_args, toolContext) => {
 				const root = effectiveRoot; const branch = currentGitBranch(root) ?? "unknown"; const isProtected = onProtectedBranch(root); const lastV = getLastVerifyResultForWorkspace(root); const lastR = getLastReviewResultForWorkspace(root); const lastMut = getWorkspaceMutationTimestamp(root); const cfg = loadProjectConfig(root);
 				const subject = { workspace: projectRootKey(root), commitHash: getCurrentGitCommitHash(root), worktreeFingerprint: getGitWorktreeFingerprint(root) };
@@ -167,14 +212,32 @@ export function createCustomTools(options: {
 					...(reviewRequired && !reviewFresh ? ["review"] : []),
 					...(documentationRequired && !branchHasDocumentationChange(root) ? ["documentation"] : []),
 				];
+				const recommendedActions: string[] = [];
+				if (outstandingRequirements.includes("verification")) {
+					recommendedActions.push(verifyCommand ? `Execute test verification command '${verifyCommand}' to produce fresh verification evidence.` : "Run project tests to establish fresh verification evidence.");
+				}
+				if (outstandingRequirements.includes("review")) {
+					recommendedActions.push("Call guard_review_rubric to retrieve the 5-axis review rubric, then spawn a secondary reviewer subagent via task to evaluate changes and record verdict with record_review.");
+				}
+				if (outstandingRequirements.includes("documentation")) {
+					recommendedActions.push("Update documentation files (e.g. README.md, docs/) to satisfy the documentation gate before opening a PR.");
+				}
+				let openFollowupsCount = 0;
+				try { openFollowupsCount = followupStore ? listReviewFollowups(followupStore, "open", 10).length : 0; } catch {}
+				if (openFollowupsCount > 0) {
+					recommendedActions.push(`Inspect ${openFollowupsCount} open P2/P3 review follow-up(s) with guard_review_followups and resolve with guard_review_followup_resolve once addressed.`);
+				}
+				if (recommendedActions.length === 0) {
+					recommendedActions.push("All operational requirements are satisfied for task finalization and PR creation.");
+				}
 				const ralphOutcome = runWithRuntimeState(root, client, () => getRalphOutcome(toolContext.sessionID));
-				return JSON.stringify({ workspaceRoot: root, branch, onProtectedBranch: isProtected, outstandingRequirements, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) } }, null, 2);
+				return JSON.stringify({ workspaceRoot: root, branch, onProtectedBranch: isProtected, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) } }, null, 2);
 			},
 		}),
-		guard_audit: tool({ description: "View recent audit entries recorded by opencode-workflow-guard.", args: { limit: tool.schema.number().optional().describe("Maximum entries to return (default 10)") }, execute: async (args) => JSON.stringify(getRecentAuditEntries(typeof args?.limit === "number" ? Math.min(args.limit, 50) : 10), null, 2) }),
-		guard_why: tool({ description: "Simulate and return the structured policy decision for a specific tool call or command.", args: { tool: tool.schema.string().describe("Tool name (e.g. bash, edit, write, read, apply_patch)"), input: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe("Tool input arguments") }, execute: async (args, toolContext) => JSON.stringify(await runWithRuntimeState(effectiveRoot, client, () => guardToolCallImpl(args.tool, args.input ?? {}, { sessionID: toolContext.sessionID, worktree: toolContext.worktree, directory: toolContext.directory, simulate: true })), null, 2) }),
+		guard_audit: tool({ description: "View recent audit entries recorded by opencode-workflow-guard. Use to diagnose policy decisions, blocked commands, or outcome telemetry.", args: { limit: tool.schema.number().optional().describe("Maximum entries to return (default 10)") }, execute: async (args) => JSON.stringify(getRecentAuditEntries(typeof args?.limit === "number" ? Math.min(args.limit, 50) : 10), null, 2) }),
+		guard_why: tool({ description: "Simulate and return the structured policy decision for a specific tool call or command. Proactively use before executing questionable or complex commands to check if they would be blocked by guard policies.", args: { tool: tool.schema.string().describe("Tool name (e.g. bash, edit, write, read, apply_patch)"), input: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe("Tool input arguments") }, execute: async (args, toolContext) => JSON.stringify(await runWithRuntimeState(effectiveRoot, client, () => guardToolCallImpl(args.tool, args.input ?? {}, { sessionID: toolContext.sessionID, worktree: toolContext.worktree, directory: toolContext.directory, simulate: true })), null, 2) }),
 		record_review: tool({
-			description: "Record a secondary reviewer agent's approval or critique of the current changes. The summary must reference the 5 core review axes from guard_review_rubric.",
+			description: "Record a secondary reviewer agent's approval or critique of the current changes. The summary must reference the 5 core review axes from guard_review_rubric (test integrity, task completeness, cleanliness, security, platform).",
 			args: { reviewer: tool.schema.string().describe("Identifier/name of the reviewer subagent"), summary: tool.schema.string().describe("Review findings summary across the 5 core review axes"), passed: tool.schema.boolean().describe("True if change is approved, false if changes requested") },
 			execute: async (args, toolContext) => {
 				const auditVerdict = (verdict: "approved" | "changes_requested" | "rejected", reason: string) => audit({ ts: new Date().toISOString(), sessionID: toolContext.sessionID, tool: "record_review.verdict", decision: verdict === "rejected" ? "block" : "allow", phase: "event", reason, evidence: { reviewVerdict: verdict } });
@@ -190,10 +253,10 @@ export function createCustomTools(options: {
 				return args.passed ? `[workflow-guard] Review recorded as APPROVED by ${args.reviewer}.` : `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}.`;
 			},
 		}),
-		guard_review_followups: tool({ description: "List durable local P2/P3 review follow-ups for this project. Open findings are technical debt that should be addressed rather than indefinitely deferred.", args: {}, execute: async () => JSON.stringify(followupStore ? listReviewFollowups(followupStore) : [], null, 2) }),
+		guard_review_followups: tool({ description: "List durable local P2/P3 review follow-ups (technical debt) for this project. Proactively check during planning or before final verification to address open findings.", args: {}, execute: async () => JSON.stringify(followupStore ? listReviewFollowups(followupStore) : [], null, 2) }),
 		guard_review_followup_resolve: tool({ description: "Resolve a durable local review follow-up after the underlying issue has been fixed and verified.", args: { id: tool.schema.string() }, execute: async (args) => followupStore && resolveReviewFollowup(followupStore, args.id) ? `[workflow-guard] Review follow-up ${args.id} resolved.` : `[workflow-guard] Review follow-up ${args.id} was not open or was not found.` }),
 		guard_review_rubric: tool({
-			description: "Get the secondary-review rubric for the current branch diff. The orchestrator calls this, spawns a reviewer subagent with the rubric as the prompt, then the reviewer records its verdict via record_review.", args: { base: tool.schema.string().optional().describe("Base ref to diff against (default: origin/main, origin/master, main)") },
+			description: "Get the secondary-review rubric for the current branch diff across 5 core review axes (test integrity, task completeness, cleanliness, security, platform). The orchestrator should call this before finalizing work or creating a PR, then spawn a reviewer subagent with the rubric as the prompt, which records its verdict via record_review.", args: { base: tool.schema.string().optional().describe("Base ref to diff against (default: origin/main, origin/master, main)") },
 			execute: async (args) => {
 				const sanitizedBase = typeof args.base === "string" && !args.base.startsWith("-") && !/[\s;'"\0]/.test(args.base) ? args.base : undefined;
 				const bases = sanitizedBase ? [sanitizedBase] : ["origin/main", "origin/master", "main", "master"];
@@ -204,7 +267,7 @@ export function createCustomTools(options: {
 			},
 		}),
 		guard_worktree_create: tool({
-			description: "Create an isolated git worktree directory for concurrent subagent execution.", args: { branch: tool.schema.string().describe("Branch name for the isolated worktree (e.g. 'feat/subagent-task')"), baseBranch: tool.schema.string().optional().describe("Base branch to branch off of (defaults to HEAD)") },
+			description: "Create an isolated git worktree directory for concurrent subagent execution. Proactively call when launching parallel tasks/subagents to prevent file collision and maintain branch isolation.", args: { branch: tool.schema.string().describe("Branch name for the isolated worktree (e.g. 'feat/subagent-task')"), baseBranch: tool.schema.string().optional().describe("Base branch to branch off of (defaults to HEAD)") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree creation with no active todo item. Break the request down with todowrite first, then create worktrees.";
 				const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot; const res = createGitWorktree(args.branch, args.baseBranch ?? "HEAD", toolRoot); if (!res.success) return `[workflow-guard] Failed to create worktree: ${res.error}`;
@@ -212,7 +275,7 @@ export function createCustomTools(options: {
 			},
 		}),
 		guard_worktree_cleanup: tool({
-			description: "Commit a final snapshot and remove an isolated git worktree directory.", args: { worktreePath: tool.schema.string().describe("Path of the worktree directory to clean up") },
+			description: "Commit a final snapshot and remove an isolated git worktree directory. Call to clean up worktrees created with guard_worktree_create after subagent tasks complete.", args: { worktreePath: tool.schema.string().describe("Path of the worktree directory to clean up") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree cleanup with no active todo item. Break the request down with todowrite first, then clean up worktrees.";
 				const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot; const res = cleanupGitWorktree(args.worktreePath, toolRoot); if (!res.success) return `[workflow-guard] Failed to clean up worktree: ${res.error}`;

package/src/policies/continuation.ts

@@ -97,7 +97,7 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 					messageID,
 					parts: [{
 						type: "text",
-						text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run.`,
+						text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run. Check guard_status for outstanding verification/review requirements, and guard_review_rubric before final completion.`,
 						synthetic: true,
 					}],
 				},

package/src/workflow-guard.ts

@@ -18,10 +18,10 @@ import { beginReadObservation, clearReadFingerprints, recordSuccessfulRead, stal
 import { ToolInvocationLifecycle } from "./lib/tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./lib/tool-outcomes.ts";
 import { guardToolCallImpl, isReadOnlyRole } from "./lib/guard-dispatcher.ts";
-import { createCustomTools } from "./lib/custom-tools.ts";
+import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 import type { PolicyDecision, TodoSdkClient } from "./lib/types.ts";
 export { isReadOnlyRole } from "./lib/guard-dispatcher.ts";
-export { extractReviewFollowups } from "./lib/custom-tools.ts";
+export { extractReviewFollowups, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 export type {
@@ -345,6 +345,24 @@ async function emitBlockFeedback(message: string): Promise<void> {
 	await showBlockToast(message);
 }
 
+export function buildCompactionContext(operationalState: string, priorityBlocks: string[], maxChars = 8_000): string {
+	if (!Number.isFinite(maxChars) || maxChars < 0 || !Number.isInteger(maxChars)) {
+		throw new RangeError("maxChars must be a non-negative finite integer");
+	}
+	const truncate = (value: string, limit: number): string => {
+		let end = Math.min(value.length, limit);
+		if (end > 0 && end < value.length && /[\uD800-\uDBFF]/.test(value[end - 1])) end -= 1;
+		return value.slice(0, end);
+	};
+	let context = truncate(operationalState, maxChars);
+	for (const block of priorityBlocks) {
+		const remaining = maxChars - context.length - 2;
+		if (remaining <= 0) break;
+		context += `\n\n${truncate(block, remaining)}`;
+	}
+	return context;
+}
+
 export const WorkflowGuard: Plugin = async (ctx) => {
 	// Honor worktree if present (e.g. opencode worktrees or devcontainers)
 	// so worktree plugins cannot punch through boundary gates. When the host
@@ -416,7 +434,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					await emitBlockFeedback(reason);
 					const failureCount = input.sessionID ? toolOutcomes.getFailureCount(input.sessionID) : 0;
 					const circuitBreakerSuffix = failureCount >= 2
-						? "\n\n[Workflow Guard Circuit Breaker: Repeated failures detected in this session. Stop attempting alternative workarounds or shell laundering. Address the required step above directly.]"
+						? "\n\n[Workflow Guard Circuit Breaker: Repeated failures detected in this session. Stop attempting alternative workarounds or shell laundering. Address the required step above directly, or inspect policy details with guard_status or guard_why.]"
 						: "";
 					throw new Error(`[workflow-guard] ${reason}${circuitBreakerSuffix}`);
 				}
@@ -484,7 +502,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					: getLastReviewResult();
 				const mutationCountVal = sessionID ? sessionMutationCount : getMutationCount();
 
-				const contextBlocks: string[] = [];
+				const priorityContextBlocks: string[] = [];
 
 				if (active && active.length > 0) {
 					const lines = active.slice(0, 20).map(
@@ -497,7 +515,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 						: sessionID
 							? ` (Session: ${sessionID})`
 							: "";
-					contextBlocks.push(
+					priorityContextBlocks.push(
 						`## Active Tasks${attribution}\n` +
 							lines.join("\n") +
 							"\nComplete tasks efficiently - mark finished items as completed and address remaining ones.",
@@ -523,9 +541,9 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				try { openFollowups = followupStore ? listReviewFollowups(followupStore, "open", 8) : []; } catch {}
 				if (openFollowups.length > 0) {
 					stateLines.push(`- Open Review Follow-ups: ${openFollowups.length} local P2/P3 item(s)`);
-					contextBlocks.push(`## Review Follow-ups\n${openFollowups.map((item) => `- [${item.severity}:${item.id.slice(0, 8)}] ${item.summary.slice(0, 300)}`).join("\n")}\nTreat these as durable technical debt: address relevant items when practical and resolve them explicitly after verification.`);
+					priorityContextBlocks.push(`## Review Follow-ups\n${openFollowups.map((item) => `- [${item.severity}:${item.id.slice(0, 8)}] ${item.summary.slice(0, 300)}`).join("\n")}\nTreat these as durable technical debt: address relevant items when practical and resolve them explicitly after verification.`);
 				}
-				contextBlocks.push(stateLines.join("\n"));
+				const operationalState = stateLines.join("\n");
 				let projectKnowledge: ReturnType<typeof getRecentProjectMemory> = [];
 				try {
 					const candidates = (projectMemory ? getRecentProjectMemory(projectMemory, 8) : [])
@@ -535,11 +553,11 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				} catch {}
 				if (projectKnowledge.length > 0) {
 					const lines = projectKnowledge.map((memory) => `- [${memory.kind}:${memory.id.slice(0, 8)}] ${memory.content.slice(0, 300)}`);
-					contextBlocks.push(`## Project Memory\n${lines.join("\n")}\nTreat these as historical project knowledge; verify against current repository state when relevant files have changed.`);
+					priorityContextBlocks.push(`## Project Memory\nUse project_memory_search when deeper historical context is needed. Treat these as historical project knowledge; verify against current repository state when relevant files have changed.\n${lines.join("\n")}`);
 				}
 
 				if (Array.isArray(output?.context)) {
-					output.context.push(contextBlocks.join("\n\n"));
+					output.context.push(buildCompactionContext(operationalState, priorityContextBlocks));
 				}
 			} catch {}
 		},
@@ -611,13 +629,14 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 		// Keep tool descriptions honest: todowrite's description reflects lifecycle
 		// and finalization gates so the model is not surprised by preventable blocks.
 		// Similarly, mutating tools reflect their active-todo, feature-branch, and prior-read requirements.
+		// Subagent orchestration tools reflect worktree isolation and review expectations.
 		"tool.definition": async (input, output) => {
 			if (input.toolID === "todowrite") {
 				const description = typeof output.description === "string" ? output.description : "";
 				if (description.includes("verification evidence")) return;
 				output.description =
 					description +
-					"\n\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
+					"\n\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
 				return;
 			}
 			if (EDIT_TOOL_NAMES.has(input.toolID)) {
@@ -628,6 +647,30 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					"\n\nWorkflow Guard requirement: Modifications require an active task in todowrite (status pending or in_progress), a feature branch (edits on main/master are blocked), and a prior read of existing files in the current session.";
 				return;
 			}
+			if (input.toolID === "task") {
+				const description = typeof output.description === "string" ? output.description : "";
+				if (description.includes("Workflow Guard subagent guidance")) return;
+				output.description =
+					description +
+					"\n\nWorkflow Guard subagent guidance: When spawning parallel worker subagents, use guard_worktree_create to isolate file mutations in separate worktrees. When conducting code reviews before task completion or PR creation, fetch the rubric with guard_review_rubric and provide it to a reviewer subagent to evaluate and record via record_review.";
+				return;
+			}
+		},
+
+		"experimental.chat.system.transform": async (input, output) => {
+			try {
+				if (!Array.isArray(output?.system)) return;
+				const existing = output.system.join("\n");
+				if (existing.includes("## Workflow Guard & Operational Tools")) return;
+				const isReadOnly = (input as { agent?: string })?.agent ? isReadOnlyRole((input as { agent?: string }).agent!) : false;
+				const guidance = buildWorkflowGuardSystemGuidance({
+					projectMemoryEnabled,
+					learningEnabled,
+					recoveryCheckpointsEnabled: isRecoveryCheckpointsEnabled(effectiveRoot),
+					isReadOnly,
+				});
+				output.system.push(guidance);
+			} catch {}
 		},
 
 		"chat.message": async (input) => {

package/test/test.mts

@@ -12,6 +12,7 @@ import {
 	setWorkspaceRoot,
 	setSdkClient,
 	WorkflowGuard,
+	buildCompactionContext,
 	detectVerifyCommand,
 	runVerify,
 	getCleanEnv,
@@ -565,6 +566,13 @@ check("multi-target tee with an outside path is blocked", blocked(await call("ba
 check("tee --append within workspace is allowed with todos", !(await call("bash", { command: "echo x | tee --append src/a.ts" }, { sessionID: "s-active" })));
 
 console.log("- Compaction focus preservation & TUI toast -");
+const boundedCompaction = buildCompactionContext("## Operational Guard State\n- critical", ["## Active Tasks\n" + "a".repeat(10_000), "## Project Memory\nshould-not-fit"], 500);
+check("compaction packer enforces its total context budget", boundedCompaction.length === 500);
+check("compaction packer preserves mandatory operational state before optional context", boundedCompaction.startsWith("## Operational Guard State\n- critical") && !boundedCompaction.includes("should-not-fit"));
+check("compaction packer preserves the largest valid Unicode prefix", buildCompactionContext("critical \u{1F680}state", [], 10) === "critical ");
+let invalidCompactionBudgetRejected = false;
+try { buildCompactionContext("critical", [], Number.NaN); } catch (error) { invalidCompactionBudgetRejected = error instanceof RangeError; }
+check("compaction packer rejects invalid public budgets", invalidCompactionBudgetRejected);
 let toasts: unknown[] = [];
 const toastClient = {
 	session: fakeClient.session,
@@ -588,6 +596,8 @@ if (typeof compactFn === "function") {
 	await compactFn({ sessionID: "s-active" } as any, compactOutput as any);
 }
 check("compaction hook injects active tasks into output.context", compactOutput.context.length > 0 && (compactOutput.context[0]?.includes("Active Tasks") ?? false));
+check("compaction hook keeps injected continuity context bounded", compactOutput.context.every((context) => context.length <= 8000));
+check("compaction hook preserves operational guard state within its budget", compactOutput.context.some((context) => context.includes("## Operational Guard State") && context.includes("Git Branch:")));
 
 // Blocked tool call emits one in-app warning via tui.showToast.
 toasts = [];
@@ -1899,6 +1909,10 @@ check("guard_status exposes subject-bound evidence references", parsedStatus.las
 check("guard_status exposes effective operation profile without TUI state", parsedStatus.projectConfig.profile === "interactive" && typeof parsedStatus.projectConfig.recoveryCheckpoints === "boolean");
 check("guard_status exposes disabled-by-default Ralph accountability state", parsedStatus.ralph?.enabled === false && parsedStatus.ralph?.maxIterations === 10 && parsedStatus.ralph?.outcome === null);
 check("guard_status exposes bounded outstanding requirements", Array.isArray(parsedStatus.outstandingRequirements) && parsedStatus.outstandingRequirements.every((requirement: unknown) => ["verification", "review", "documentation"].includes(String(requirement))));
+check("guard_status exposes actionable recommended actions", Array.isArray(parsedStatus.recommendedActions) && parsedStatus.recommendedActions.length > 0);
+check("guard_next_tasks description includes proactive trigger", Boolean(customPlugin.tool?.guard_next_tasks?.description.includes("Proactively call")));
+check("project_memory_search description includes proactive trigger", Boolean(customPlugin.tool?.project_memory_search?.description?.includes("Proactively call")));
+check("guard_review_rubric description includes orchestrator trigger", Boolean(customPlugin.tool?.guard_review_rubric?.description?.includes("orchestrator should call")));
 
 const requirementsRoot = mkdtempSync(join(tmpdir(), "wg-status-requirements-"));
 mkdirSync(join(requirementsRoot, ".opencode"), { recursive: true });
@@ -3208,6 +3222,26 @@ const editIdemDef = { description: editDef.description, parameters: {} };
 await defPlugin["tool.definition"]?.({ toolID: "edit" } as any, editIdemDef);
 check("tool.definition edit enrichment is idempotent", editIdemDef.description === editDef.description);
 
+const taskDef = { description: "Launch subagents.", parameters: {} };
+await defPlugin["tool.definition"]?.({ toolID: "task" } as any, taskDef);
+check("tool.definition enriches task tool with subagent and review guidance", taskDef.description.includes("Workflow Guard subagent guidance") && taskDef.description.includes("guard_worktree_create") && taskDef.description.includes("guard_review_rubric"));
+const taskIdemDef = { description: taskDef.description, parameters: {} };
+await defPlugin["tool.definition"]?.({ toolID: "task" } as any, taskIdemDef);
+check("tool.definition task enrichment is idempotent", taskIdemDef.description === taskDef.description);
+check("tool.definition todowrite enriches with planning and status guidance", todoDef.description.includes("guard_next_tasks") && todoDef.description.includes("guard_status"));
+
+// experimental.chat.system.transform provides cross-model workflow guidance
+const systemOutput = { system: ["Base system prompt"] };
+await defPlugin["experimental.chat.system.transform"]?.({ model: { id: "gemini-flash" } as any }, systemOutput);
+check("experimental.chat.system.transform adds workflow guard guidance", systemOutput.system.length === 2 && systemOutput.system[1].includes("## Workflow Guard & Operational Tools") && systemOutput.system[1].includes("guard_next_tasks") && systemOutput.system[1].includes("guard_review_rubric"));
+const systemOutputIdem = { system: [...systemOutput.system] };
+await defPlugin["experimental.chat.system.transform"]?.({ model: { id: "gemini-flash" } as any }, systemOutputIdem);
+check("experimental.chat.system.transform is idempotent", systemOutputIdem.system.length === 2);
+
+const readOnlySystemOutput = { system: ["Base system prompt"] };
+await defPlugin["experimental.chat.system.transform"]?.({ agent: "reviewer", model: { id: "claude-sonnet" } as any } as any, readOnlySystemOutput);
+check("experimental.chat.system.transform respects read-only roles", !readOnlySystemOutput.system[1].includes("spawn a reviewer subagent"));
+
 // Socratic learning engine: evidence is explicit and interventions favor
 // relevant gaps without repeatedly interrupting demonstrated knowledge.
 const learner = createLearnerProfile();
@@ -3287,6 +3321,7 @@ const learningPlugin = await WorkflowGuard({ directory: root, worktree: root, cl
 check("learning mode registers profile tool when explicitly enabled", !!learningPlugin.tool?.learning_profile);
 check("learning mode registers adaptive checkpoint tool", !!learningPlugin.tool?.learning_checkpoint);
 check("learning mode registers evidence recorder", !!learningPlugin.tool?.learning_record);
+check("learning_checkpoint description includes proactive trigger", Boolean(learningPlugin.tool?.learning_checkpoint?.description?.includes("Proactively call")));
 const checkpointResult = JSON.parse(await (learningPlugin.tool as any).learning_checkpoint.execute({
 	opportunities: [{ type: "design", concept: "application-state", relevance: 1, consequence: 0.9 }],
 }, { sessionID: "s-learning-tools" }));