opencode-workflow-guard 1.9.1 → 1.9.3

package/docs/installation.md

@@ -100,7 +100,7 @@ When the root session reaches idle, the checkpoint records the resulting workspa
 
 With the optional TUI companion installed, open the command palette and choose **Workflow Guard: Project Options** (or run `/guard-options`) to toggle recovery checkpoints, project memory, learner mode, Ralph mode, or the title-settle workaround for the current project. The command writes the existing Workflow Guard project config location, defaulting to `.opencode/workflow-guard.json`; restart OpenCode after changing a setting so the server plugin can expose the matching tools.
 
-The title-settle workaround is off by default. When enabled with `titleSettleWorkaround: true`, Workflow Guard briefly waits for OpenCode's asynchronous native title generation before sending an automatic continuation for unfinished root-session work. The wait is bounded, applies only when that session owns unfinished todos, and never changes the title or provider/model parameters itself.
+The title-settle workaround is on by default because Workflow Guard's automatic continuation can race OpenCode's asynchronous native title generation. Workflow Guard briefly waits for native title generation before sending an automatic continuation for unfinished root-session work; set `titleSettleWorkaround: false` to opt out. The wait is bounded, applies only when that session owns unfinished todos, and never changes the title or provider/model parameters itself.
 
 Ralph mode is also off by default, including under the `autonomous` profile. Enable it explicitly with `ralphMode: true`; `ralphMaxIterations` sets its positive integer continuation budget from 1 through 100 (default 10; invalid values use the default). Ralph only continues a root session while that session already owns unfinished native todos. It does not create, prioritize, select, sequence, or delegate work, and every resumed run remains subject to the normal guardrails. Genuine user input stops an active Ralph run instead of resetting its budget. Reaching the budget with unfinished work reports `budget_exhausted`; completion is reported only when owned todos are actually finished. A `blocked` outcome is reserved for a demonstrable guard state and is never inferred merely from repeated idle events. `guard_status` exposes the effective Ralph configuration and current calling-session outcome.
 

package/docs/policies.md

@@ -83,7 +83,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - Verification (`WORKFLOW_GUARD_VERIFY` env, project `verifyCommand`, or auto-detected test/typecheck runner across ecosystems: `package.json` (`npm test`, `npm run typecheck`, `npm run check`, `npm run build`), `Cargo.toml` (`cargo test`), `go.mod` (`go test ./...`), `pytest.ini`/`pyproject.toml` (`pytest`), or `deno.json` (`deno test`)) executes in an isolated environment with scrubbed credentials, output caps, token-efficient stdout/stderr snipping, and strict timeout protection. Environment configuration takes precedence over project configuration.
 - Project `postEditValidators` can run faster targeted checks after a direct file edit actually changes the target. Each entry accepts a workspace-relative glob `pattern` (`*`, `**`, and `?` wildcards; brace expansion and character classes are not supported), a non-empty `command`, and an optional positive `timeoutMs`; invalid entries are reported as advisory feedback rather than silently ignored. Matching commands run from the workspace root with the same scrubbed verification environment. Validator failures and timeouts are appended to the edit result as advisory feedback and do not replace the blocking whole-project finalization verification. Multi-file `apply_patch` calls validate every changed target.
 - With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list; subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
-- Automatic continuation remains synthetic. With the opt-in project setting `titleSettleWorkaround: true`, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent; the bounded wait never rewrites titles or provider/model parameters.
+- Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent; set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider/model parameters.
 - **Git State & Snapshot Binding:** Verification evidence records the current git commit hash (`git rev-parse HEAD`) and working tree status. If unverified edits or index modifications occur after verification, fresh verification is enforced.
 - **Durable Disk Cache:** Passing verification results are cached to `~/.local/state/opencode/workflow-guard/last-verify.json`, allowing session restarts and multi-agent handoffs to retain valid verification evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it, so a passing run in one project can never satisfy finalization in another.
 - If verification fails, finalization is blocked with a structured summary of error markers, stack traces, and failure output.

package/docs/superpowers/plans/2026-08-28-title-settle-default.md

@@ -0,0 +1,122 @@
+# Title Settle Default Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make Workflow Guard's title-settle behavior enabled by default while preserving `titleSettleWorkaround: false` as an explicit opt-out.
+
+**Architecture:** Treat the missing setting consistently as enabled at both consumers: the continuation server hook and TUI project-option reader. Keep the existing bounded title-settle implementation unchanged; only its effective default changes.
+
+**Tech Stack:** TypeScript, OpenCode TUI plugin API, Node test harness, jsonc-parser.
+
+---
+
+### Task 1: Lock Down Default And Opt-Out Semantics
+
+**Files:**
+- Modify: `test/test.mts:1140-1155,2835-2860`
+
+- [ ] **Step 1: Change the TUI regression to expect title settling on without configuration**
+
+Before selecting the title-settle option, assert the missing setting reads as enabled. Then select its option callback and assert the persisted effective value becomes false:
+
+```ts
+registeredTuiCommands.find((command) => command.name === "workflow-guard.project-options")?.run?.();
+check("title settle workaround project option defaults on", readProjectOption(tuiCommandOptionsDir, "titleSettleWorkaround") === true);
+tuiDialogSelectProps?.options?.find((option: any) => option.value === "titleSettleWorkaround")?.onSelect?.(fakeTuiApi.ui.dialog);
+check("tui project-options command can disable title settle workaround", readProjectOption(tuiCommandOptionsDir, "titleSettleWorkaround") === false);
+```
+
+- [ ] **Step 2: Change continuation regressions to cover default-on and explicit opt-out**
+
+Use the existing title-settle continuation fixture around line 2844. Remove the requirement to write `{ titleSettleWorkaround: true }` for the positive case, and add a sibling case/fixture with `{ titleSettleWorkaround: false }` proving continuation does not wait for title settling when explicitly disabled. Preserve the existing assertions that title generation remains native and the wait remains bounded.
+
+- [ ] **Step 3: Run the unit harness to verify the new expectations fail**
+
+Run: `npm test`
+
+Expected: the new default-on assertions fail against current production code while unrelated checks remain green.
+
+### Task 2: Implement Enabled-Unless-False Semantics
+
+**Files:**
+- Modify: `src/workflow-guard-ui.ts:36-43`
+- Modify: `src/workflow-guard.ts:672`
+
+- [ ] **Step 1: Make the TUI reader default title settling to enabled**
+
+Update `readProjectOption` so both project memory and title settling are enabled unless explicitly false, while the other opt-in settings remain enabled only by explicit true:
+
+```ts
+const enabledByDefault = option === "projectMemory" || option === "titleSettleWorkaround";
+if (!existsSync(path)) return enabledByDefault;
+// parse existing config as before
+return enabledByDefault ? config?.[option] !== false : config?.[option] === true;
+```
+
+- [ ] **Step 2: Make continuation use the same effective default**
+
+Change the title-settle gate in `src/workflow-guard.ts` from:
+
+```ts
+const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround === true;
+```
+
+to:
+
+```ts
+const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround !== false;
+```
+
+- [ ] **Step 3: Run the unit harness**
+
+Run: `npm test`
+
+Expected: all checks pass, including default-enabled and explicit-false regressions.
+
+### Task 3: Document The New Default
+
+**Files:**
+- Modify: `docs/installation.md:103`
+- Modify: `docs/policies.md:86`
+- Modify: `.changeset/fix-project-option-toggles.md`
+
+- [ ] **Step 1: Update installation guidance**
+
+Replace the statement that title settling is off by default with text stating that it is on by default because Workflow Guard's automatic continuation can race OpenCode title generation, and that projects may opt out with `titleSettleWorkaround: false`.
+
+- [ ] **Step 2: Update policy documentation**
+
+Describe title settling as the default continuation behavior rather than opt-in behavior. Retain the guarantees that the wait is bounded and does not rewrite titles or provider/model parameters.
+
+- [ ] **Step 3: Expand the existing patch changeset**
+
+Make `.changeset/fix-project-option-toggles.md` mention both user-visible changes: functioning TUI toggles and title settling enabled by default with explicit opt-out.
+
+### Task 4: Verify The Final Tree
+
+**Files:**
+- Verify only
+
+- [ ] **Step 1: Run type checking**
+
+Run: `npm run typecheck`
+
+Expected: exit 0 with no TypeScript errors.
+
+- [ ] **Step 2: Run the full unit/adversarial harness**
+
+Run: `npm test`
+
+Expected: all checks pass with 0 failures.
+
+- [ ] **Step 3: Run packaged installation verification**
+
+Run: `npm run test:install`
+
+Expected: all non-model-driven installation/runtime checks pass with 0 failures.
+
+- [ ] **Step 4: Check the diff**
+
+Run: `git diff --check`
+
+Expected: exit 0 with no whitespace errors.

package/docs/superpowers/specs/2026-08-28-title-settle-default-design.md

@@ -0,0 +1,25 @@
+# Title Settle Default Design
+
+## Context
+
+Workflow Guard can automatically continue a root session that still owns unfinished todos. That synthetic continuation can race OpenCode's asynchronous native session-title generation. The existing `titleSettleWorkaround` behavior avoids the race by briefly waiting for native title generation, but it currently requires explicit opt-in even though Workflow Guard's continuation behavior creates the need for the workaround.
+
+## Decision
+
+Enable the title-settle behavior by default. A missing `titleSettleWorkaround` setting means enabled; `titleSettleWorkaround: false` remains an explicit project-level opt-out.
+
+The server and TUI must expose the same effective semantics. The project-options menu therefore renders Title settle workaround as On when the setting is absent, and selecting it persists `false`. Selecting it again persists `true`.
+
+No configuration migration is required. Existing projects that do not mention the setting acquire the safer default automatically, while projects already configured with `false` retain their behavior.
+
+## Scope
+
+- Change effective server behavior from `=== true` to enabled unless explicitly false.
+- Change the TUI project-option reader to report the same enabled-by-default value.
+- Preserve all existing bounded-wait, ownership, title, provider, and model behavior.
+- Update installation and policy documentation to describe the default and opt-out.
+- Update regression coverage for default-enabled behavior and explicit-false opt-out.
+
+## Verification
+
+Regression tests must prove that an unconfigured project uses title settling, explicit `false` bypasses title settling, and the TUI reports/toggles the same effective state. The repository typecheck, unit harness, and packaged-install test must remain green.

package/package.json

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

package/src/workflow-guard-ui.ts

@@ -35,11 +35,12 @@ type ProjectToggle = "recoveryCheckpoints" | "projectMemory" | "learning" | "tit
 
 export function readProjectOption(root: string, option: ProjectToggle): boolean {
 	const path = projectConfigPath(root);
-	if (!existsSync(path)) return option === "projectMemory";
+	const enabledByDefault = option === "projectMemory" || option === "titleSettleWorkaround";
+	if (!existsSync(path)) return enabledByDefault;
 	const errors: ParseError[] = [];
 	const config = parse(readFileSync(path, "utf8"), errors, { allowTrailingComma: true });
 	if (errors.length > 0) throw new Error(`Invalid Workflow Guard project config: ${path}`);
-	return option === "projectMemory" ? config?.projectMemory !== false : config?.[option] === true;
+	return enabledByDefault ? config?.[option] !== false : config?.[option] === true;
 }
 
 function writeProjectOption(root: string, option: ProjectToggle, enabled: boolean): string {
@@ -89,23 +90,22 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 				const learning = readProjectOption(root, "learning");
 				const titleSettle = readProjectOption(root, "titleSettleWorkaround");
 				const ralphMode = readProjectOption(root, "ralphMode");
+				const toggle = (key: ProjectToggle) => {
+					const enabled = !readProjectOption(root, key);
+					const path = writeProjectOption(root, key, enabled);
+					api.ui.dialog.clear();
+					api.ui.toast({ variant: "success", title: "Workflow Guard", message: `Saved ${key} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.` });
+				};
 				api.ui.dialog.replace(() => api.ui.DialogSelect({
 					title: "Workflow Guard Project Options",
 					current: undefined,
 					options: [
-						{ title: `Recovery checkpoints: ${recovery ? "On" : "Off"}`, value: "recoveryCheckpoints", description: "Toggle durable pre-run Git checkpoints" },
-						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory" },
-						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools" },
-						{ title: `Title settle workaround: ${titleSettle ? "On" : "Off"}`, value: "titleSettleWorkaround", description: "Delay automatic continuation while OpenCode generates a session title" },
-						{ title: `Ralph mode: ${ralphMode ? "On" : "Off"}`, value: "ralphMode", description: "Opt into bounded autonomous continuation of already-owned todos" },
+						{ title: `Recovery checkpoints: ${recovery ? "On" : "Off"}`, value: "recoveryCheckpoints", description: "Toggle durable pre-run Git checkpoints", onSelect: () => toggle("recoveryCheckpoints") },
+						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory", onSelect: () => toggle("projectMemory") },
+						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools", onSelect: () => toggle("learning") },
+						{ title: `Title settle workaround: ${titleSettle ? "On" : "Off"}`, value: "titleSettleWorkaround", description: "Delay automatic continuation while OpenCode generates a session title", onSelect: () => toggle("titleSettleWorkaround") },
+						{ title: `Ralph mode: ${ralphMode ? "On" : "Off"}`, value: "ralphMode", description: "Opt into bounded autonomous continuation of already-owned todos", onSelect: () => toggle("ralphMode") },
 					],
-					onSelect: (option) => {
-						const key = option.value as ProjectToggle;
-						const enabled = !readProjectOption(root, key);
-						const path = writeProjectOption(root, key, enabled);
-						api.ui.dialog.clear();
-						api.ui.toast({ variant: "success", title: "Workflow Guard", message: `Saved ${key} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.` });
-					},
 				}));
 			},
 		}],

package/src/workflow-guard.ts

@@ -669,7 +669,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					if (recoveryRun !== undefined) {
 						finalizeRecoveryCheckpoint(effectiveRoot, sessionID, recoveryRun);
 					}
-					const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround === true;
+					const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround !== false;
 					await runWithRuntimeState(effectiveRoot, ctx.client, () => continueUnfinishedSession(sessionID, settleTitle));
 				}
 			}

package/test/test.mts

@@ -1139,20 +1139,21 @@ check("tui plugin registers session_prompt_right slot", typeof registeredSlots.s
 check("tui plugin registers home_prompt_right slot", typeof registeredSlots.home_prompt_right === "function");
 check("tui plugin registers project-options command through keymap", registeredTuiCommands.some((command) => command.name === "workflow-guard.project-options"));
 registeredTuiCommands.find((command) => command.name === "workflow-guard.project-options")?.run?.();
-tuiDialogSelectProps?.onSelect?.({ value: "recoveryCheckpoints" });
+tuiDialogSelectProps?.options?.find((option: any) => option.value === "recoveryCheckpoints")?.onSelect?.(fakeTuiApi.ui.dialog);
 check("tui project-options command persists selected recovery setting", readRecoveryCheckpointsOption(tuiCommandOptionsDir) === true);
 registeredTuiCommands.find((command) => command.name === "workflow-guard.project-options")?.run?.();
-tuiDialogSelectProps?.onSelect?.({ value: "projectMemory" });
+tuiDialogSelectProps?.options?.find((option: any) => option.value === "projectMemory")?.onSelect?.(fakeTuiApi.ui.dialog);
 check("tui project-options command can disable project memory", readProjectOption(tuiCommandOptionsDir, "projectMemory") === false);
 registeredTuiCommands.find((command) => command.name === "workflow-guard.project-options")?.run?.();
-tuiDialogSelectProps?.onSelect?.({ value: "learning" });
+tuiDialogSelectProps?.options?.find((option: any) => option.value === "learning")?.onSelect?.(fakeTuiApi.ui.dialog);
 check("tui project-options command can enable learner mode", readProjectOption(tuiCommandOptionsDir, "learning") === true);
 registeredTuiCommands.find((command) => command.name === "workflow-guard.project-options")?.run?.();
-tuiDialogSelectProps?.onSelect?.({ value: "titleSettleWorkaround" });
-check("tui project-options command can enable title settle workaround", readProjectOption(tuiCommandOptionsDir, "titleSettleWorkaround") === true);
+check("title settle workaround project option defaults on", readProjectOption(tuiCommandOptionsDir, "titleSettleWorkaround") === true);
+tuiDialogSelectProps?.options?.find((option: any) => option.value === "titleSettleWorkaround")?.onSelect?.(fakeTuiApi.ui.dialog);
+check("tui project-options command can disable title settle workaround", readProjectOption(tuiCommandOptionsDir, "titleSettleWorkaround") === false);
 registeredTuiCommands.find((command) => command.name === "workflow-guard.project-options")?.run?.();
 check("ralph mode project option defaults off", readProjectOption(tuiCommandOptionsDir, "ralphMode") === false);
-tuiDialogSelectProps?.onSelect?.({ value: "ralphMode" });
+tuiDialogSelectProps?.options?.find((option: any) => option.value === "ralphMode")?.onSelect?.(fakeTuiApi.ui.dialog);
 check("tui project-options command can enable ralph mode", readProjectOption(tuiCommandOptionsDir, "ralphMode") === true);
 rmSync(tuiCommandOptionsDir, { recursive: true, force: true });
 const tuiOptionsDir = mkdtempSync(join(tmpdir(), "wg-tui-options-"));
@@ -2841,7 +2842,6 @@ const continuationClient = {
 };
 const continuationRoot = mkdtempSync(join(tmpdir(), "wg-title-settle-"));
 mkdirSync(join(continuationRoot, ".opencode"));
-writeFileSync(join(continuationRoot, ".opencode", "workflow-guard.json"), JSON.stringify({ titleSettleWorkaround: true }));
 const continuationPlugin = await WorkflowGuard({ directory: continuationRoot, worktree: continuationRoot, client: continuationClient as any } as any);
 todo("s-resume", item("finish work", "pending"));
 await continuationPlugin.event?.({ event: { type: "session.idle", properties: { sessionID: "s-resume" } } } as any);
@@ -2849,20 +2849,22 @@ check("session idle auto-continues unfinished owned todos", continuationPrompts.
 check("automatic continuation remains synthetic", continuationParts.get("s-resume")?.every((part) => part.synthetic === true) === true);
 check("title settle workaround waits for OpenCode's native generated title before continuing", continuationTitleReads.get("s-resume") === 2 && continuationTitles.get("s-resume") === "Native generated title");
 
-let defaultOffTitleReads = 0;
-let defaultOffPrompts = 0;
-const defaultOffRoot = mkdtempSync(join(tmpdir(), "wg-title-settle-off-"));
-const defaultOffPlugin = await WorkflowGuard({ directory: defaultOffRoot, worktree: defaultOffRoot, client: {
+let optOutTitleReads = 0;
+let optOutPrompts = 0;
+const optOutRoot = mkdtempSync(join(tmpdir(), "wg-title-settle-off-"));
+mkdirSync(join(optOutRoot, ".opencode"));
+writeFileSync(join(optOutRoot, ".opencode", "workflow-guard.json"), JSON.stringify({ titleSettleWorkaround: false }));
+const optOutPlugin = await WorkflowGuard({ directory: optOutRoot, worktree: optOutRoot, client: {
 	session: {
 		todo: async ({ path }: { path: { id: string } }) => ({ data: fakeTodos.get(path.id) ?? [] }),
-		get: async () => { defaultOffTitleReads++; return { data: { title: "New session - 2026-08-27T12:00:00.000Z" } }; },
-		promptAsync: async () => { defaultOffPrompts++; },
+		get: async () => { optOutTitleReads++; return { data: { title: "New session - 2026-08-27T12:00:00.000Z" } }; },
+		promptAsync: async () => { optOutPrompts++; },
 	},
 } as any } as any);
-todo("s-resume-default-off", item("finish without title wait", "pending"));
-await defaultOffPlugin.event?.({ event: { type: "session.idle", properties: { sessionID: "s-resume-default-off" } } } as any);
-check("title settle workaround defaults off without suppressing continuation", defaultOffTitleReads === 0 && defaultOffPrompts === 1);
-rmSync(defaultOffRoot, { recursive: true, force: true });
+todo("s-resume-opt-out", item("finish without title wait", "pending"));
+await optOutPlugin.event?.({ event: { type: "session.idle", properties: { sessionID: "s-resume-opt-out" } } } as any);
+check("title settle workaround explicit false skips title wait without suppressing continuation", optOutTitleReads === 0 && optOutPrompts === 1);
+rmSync(optOutRoot, { recursive: true, force: true });
 
 todo("s-resume-done", item("finished", "completed"));
 await continuationPlugin.event?.({ event: { type: "session.idle", properties: { sessionID: "s-resume-done" } } } as any);