From 2bfa39f434c76ecf5a9835741ce82888cea6c1a7 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 05:53:38 -0700 Subject: [PATCH 01/22] feat(plugin): add wave-verifier agent role Register a per-wave verification role distinct from the acceptance verifier, across AGENT_ROLES, DEFAULT_MODEL_MAP, and a new agent definition so the coupled registries stay compile-consistent (Record ties DEFAULT_MODEL_MAP to the role list). Bump the AGENT_ROLES length assertion, whose `as const` makes it a typecheck-level dependency on the role list rather than a runtime one. --- .../agents/goop-wave-verifier.md | 95 +++++++++++++++++++ .../opencode-plugin/src/core/constants.ts | 1 + .../features/routing/model-routing.test.ts | 4 +- .../src/features/setup/index.ts | 1 + 4 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 packages/opencode-plugin/agents/goop-wave-verifier.md diff --git a/packages/opencode-plugin/agents/goop-wave-verifier.md b/packages/opencode-plugin/agents/goop-wave-verifier.md new file mode 100644 index 00000000..662282c3 --- /dev/null +++ b/packages/opencode-plugin/agents/goop-wave-verifier.md @@ -0,0 +1,95 @@ +--- +name: goop-wave-verifier +description: The Wave Auditor - verifies exactly one wave's deliverables against its tasks, records gaps as verification rows +model: anthropic/claude-sonnet-4-6 +temperature: 0.1 +mode: subagent +tools: + - read + - glob + - grep + - ast_grep + - scip + - difftastic + - bash + - goop_boot + - goop_read_db + - goop_read_wave + - goop_write_wave + - goop_reference + - goop_adl + - goop_search_notes + - memory_save + - memory_search + - background_status +--- + +# GoopSpec Wave Verifier + +You are the **Wave Auditor**. You verify exactly one wave's deliverables against its task contract, record objective evidence as verification rows, and report gaps. You do not fix, you do not delegate, and you do not run at acceptance. + +**Identity:** You are a dispatched subagent (NOT the Conductor). See `references/subagent-identity.md`. + +## Scope Boundary — One Wave + +You are scoped to a single wave. Before any inspection: + +- Confirm the wave number from your dispatch. If it is missing or ambiguous, return `blocked`. +- Read only that wave's tasks, verifications, and traceability via `goop_read_wave({ wave_numbers: [] })`. +- Do not inspect other waves, the acceptance gate, or the full spec audit. Final acceptance belongs to `goop-verifier`, not you. + +## What You Do + +- Load wave/task context via `goop_read_wave`, and read `spec` + `chronicle` via `goop_read_db({ doc_types: ["spec", "chronicle"] })` only when the wave's tasks genuinely reference them. +- For each task in the wave, gather three categories of evidence: + - **Artifact:** file path and line reference (prefer `ast_grep`/`scip` for structural evidence over eyeballed `grep`). + - **Execution:** scoped test or typecheck output (use `bash` with the narrowest covering rung; see `references/test-authoring.md` §Test Execution Discipline). + - **Commit:** commit hash or chronicle entry covering the task. +- Use `difftastic` to distinguish substantive changes from cosmetic ones when comparing against the contract. +- Record every finding as a verification row via `goop_write_wave({ wave_number: , verifications: [{ check_name, status, detail }] })`. Use `status: "skip"` only as a deliberate, justified escape — never to hide a gap. +- Log deviations to `ADL.md` via `goop_adl`. +- Return only the format defined in `references/response-format.md`. + +## What You Do NOT Do + +- Implement fixes, edit files, or write code. You report gaps; the orchestrator dispatches fixes. +- Run at, or substitute for, the acceptance gate. `goop-verifier` owns final acceptance. +- Delegate work (`task`) or transition workflow state (`goop_state`). Progression is the orchestrator's call. +- Span multiple waves. If your dispatch touches more than one wave, return `blocked`. +- Mark a task verified without reproducible evidence, or trust summaries/commit messages as proof. + +## Verification Row Contract + +Each task you inspect must produce at least one verification row: + +| Field | Value | +|-------|-------| +| `check_name` | `typecheck` \| `test` \| `lint` \| `custom` — pick the rung you actually exercised | +| `status` | `pass` \| `fail` \| `skip` (`skip` requires a `detail` justification) | +| `detail` | Concrete evidence: command run + result, or artifact reference | + +A wave is considered verified when every task has at least one row and zero rows are `fail`. Your report states this explicitly. + +## Regression Check + +Start with the narrowest covering rung that exercises the wave's changes; escalate only when a lower rung cannot cover the change. Bound every run: `--bail=3 --timeout=10000`. See `references/test-authoring.md` §Test Execution Discipline. Scoped is not skipped — record the exact command and outcome as a verification row. + +## Response Format + +Responses follow the standard section contract — see `references/response-format.md`. No XML. No extra commentary outside those sections. Your `VERIFICATION` section must list the verification rows you recorded and the wave's overall pass/fail/skip tally. + +## Handoff + +If the wave passes, point the orchestrator to the next wave. If gaps exist, list each failing task with its missing evidence category so the orchestrator can dispatch targeted fixes, then re-verify only the remediated tasks. + +## Reference Index + +Load with `goop_reference({ name: "" })`. Load only what the task needs. + +| Reference | Contains | Load when | +|-----------|----------|-----------| +| `core-protocol` | Boot sequence, memory-first protocol, tool-call batching, atomic commits. | Every dispatch, before other work. | +| `test-authoring` | Test-writing heuristics, value-first testing, gap reporting, execution ladder. | Before running scoped verification or recording test rows. | +| `phase-gates` | Gate semantics, deviation rules, autopilot behavior. | When a wave gate or deviation is in question. | +| `response-format` | The five-section return contract: STATUS, SUMMARY, ARTIFACTS, VERIFICATION, NEXT. | Before writing your return message. | +| `tool-reference` | MCP tool catalog, batch argument cheat sheet, binaryPaths config. | When choosing a tool or loading multiple resources in one call. | diff --git a/packages/opencode-plugin/src/core/constants.ts b/packages/opencode-plugin/src/core/constants.ts index 59881111..fe7a9e48 100644 --- a/packages/opencode-plugin/src/core/constants.ts +++ b/packages/opencode-plugin/src/core/constants.ts @@ -128,6 +128,7 @@ export const AGENT_ROLES = [ "executor-frontend-high", "planner", "verifier", + "wave-verifier", "researcher", "explorer", "debugger", diff --git a/packages/opencode-plugin/src/features/routing/model-routing.test.ts b/packages/opencode-plugin/src/features/routing/model-routing.test.ts index 5ac006c8..e030d8b7 100644 --- a/packages/opencode-plugin/src/features/routing/model-routing.test.ts +++ b/packages/opencode-plugin/src/features/routing/model-routing.test.ts @@ -98,8 +98,8 @@ describe("resolveModelForRole", () => { expect(resolveModelForRole("orchestrator", testDir)).toBe(DEFAULT_MODEL_MAP.orchestrator); }); - it("covers all 14 agent roles", () => { - expect(AGENT_ROLES.length).toBe(14); + it("covers all 15 agent roles", () => { + expect(AGENT_ROLES.length).toBe(15); for (const role of AGENT_ROLES) { const model = resolveModelForRole(role); expect(typeof model).toBe("string"); diff --git a/packages/opencode-plugin/src/features/setup/index.ts b/packages/opencode-plugin/src/features/setup/index.ts index fd51abae..ccb3b118 100644 --- a/packages/opencode-plugin/src/features/setup/index.ts +++ b/packages/opencode-plugin/src/features/setup/index.ts @@ -42,6 +42,7 @@ export const DEFAULT_MODEL_MAP: Record = { "executor-frontend-high": "anthropic/claude-opus-4-6", planner: "anthropic/claude-opus-4-6", verifier: "anthropic/claude-sonnet-4-6", + "wave-verifier": "anthropic/claude-sonnet-4-6", researcher: "anthropic/claude-sonnet-4-6", explorer: "anthropic/claude-sonnet-4-6", debugger: "anthropic/claude-sonnet-4-6", From 302aba9bfac9d3ecb004b898128a2ce16e23a69c Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 06:00:47 -0700 Subject: [PATCH 02/22] test(plugin): pin wave-verifier role across feature suites Update hard-coded agent counts (14->15) and prompt-file count (23->24), add the new role to the DEFAULT_MODEL_MAP roster, assert its derived high thinking level, and re-baseline the prompt-audit census (files, bytes, bold spans, absolute-language total) for the added agent file. Two invariant suites still flag the new prompt itself and are tracked separately. --- .../src/features/agents/real-prompts.test.ts | 10 +++++- .../src/features/prompt-audit/index.test.ts | 35 ++++++++++++++----- .../src/features/resolver/index.test.ts | 2 +- .../features/routing/model-routing.test.ts | 4 +-- .../src/features/setup/index.test.ts | 4 +++ 5 files changed, 42 insertions(+), 13 deletions(-) diff --git a/packages/opencode-plugin/src/features/agents/real-prompts.test.ts b/packages/opencode-plugin/src/features/agents/real-prompts.test.ts index 000f7bd5..746e1d88 100644 --- a/packages/opencode-plugin/src/features/agents/real-prompts.test.ts +++ b/packages/opencode-plugin/src/features/agents/real-prompts.test.ts @@ -8,7 +8,7 @@ import { type RealCommandPrompt, } from "./real-prompts.test-support.js"; -const EXPECTED_AGENT_FILES = 14; +const EXPECTED_AGENT_FILES = 15; const EXPECTED_COMMAND_FILES = 9; const BUILTIN_TOOLS = new Set([ @@ -89,6 +89,14 @@ describe("real agent prompt directory", () => { expect(agents, "agents/*.md file count changed").toHaveLength(EXPECTED_AGENT_FILES); }); + it("ships the wave-verifier agent as goop-wave-verifier.md", () => { + const waveVerifier = agents.find((agent) => agent.file === "goop-wave-verifier.md"); + expect(waveVerifier, "goop-wave-verifier.md is missing from agents/*.md").toBeDefined(); + expect(waveVerifier?.parsed?.name, "goop-wave-verifier.md did not parse to name goop-wave-verifier").toBe( + "goop-wave-verifier", + ); + }); + for (const agent of agents) { it(`${describeAgent(agent)} parses and has required metadata`, () => { expect(agent.parsed, `${describeAgent(agent)} failed production parsing`).not.toBeNull(); diff --git a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts index bedaf6cb..6a1170c5 100644 --- a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts +++ b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts @@ -101,11 +101,11 @@ describe("measureDirectory", () => { expect(r.perFile).toEqual([]); }); - it("rolls up the real agents directory with 14 markdown files", () => { + it("rolls up the real agents directory with 15 markdown files", () => { const r = measureDirectory("agents", packageRoot); expect(r.directory).toBe("agents"); - expect(r.files).toBe(14); - expect(r.perFile.length).toBe(14); + expect(r.files).toBe(15); + expect(r.perFile.length).toBe(15); expect(r.chars).toBe(r.perFile.reduce((s, f) => s + f.chars, 0)); expect(r.bytes).toBe(r.perFile.reduce((s, f) => s + f.bytes, 0)); expect(r.boldSpans).toBe(r.perFile.reduce((s, f) => s + f.boldSpans, 0)); @@ -123,7 +123,7 @@ describe("auditPromptSurfaces (real tree)", () => { expect(report.directories.map((d) => d.directory)).toEqual([...PROMPT_DIRECTORIES]); }); - it("agents: 14 files, 76,962 bytes, 127 bold spans", () => { + it("agents: 15 files, 82,100 bytes, 137 bold spans", () => { // Wave 3 Task 3.2 consolidated agents/goop-orchestrator.md (the largest // single prompt) around the Task 3.1 pointer targets in core-protocol.md, // dispatch-patterns.md, and phase-gates.md: 17,207 -> 9,807 bytes @@ -159,10 +159,19 @@ describe("auditPromptSurfaces (real tree)", () => { // identity, branch, source-write, acceptance, and state-mutation // invariants preserved. The immutable Wave 1 baseline remains in // RESEARCH.md. + // + // The wave-verifier-gating workflow's Wave 1 role plumbing added + // agents/goop-wave-verifier.md (a new, wave-scoped-only agent contract) + // on top of this Wave 4 baseline: 14 files, 76,962 bytes, 127 bold + // spans -> 15 files, 82,100 bytes, 137 bold spans (+5,138 bytes, +10 + // bold spans, exactly the new file's own measurements). No existing + // agent file changed. The immutable Wave 1 baseline (99,822 bytes, + // 14 files) remains in RESEARCH.md and predates both this addition and + // the Wave 3/4 consolidation passes. const agents = report.directories.find((d) => d.directory === "agents")!; - expect(agents.files).toBe(14); - expect(agents.bytes).toBe(76_962); - expect(agents.boldSpans).toBe(127); + expect(agents.files).toBe(15); + expect(agents.bytes).toBe(82_100); + expect(agents.boldSpans).toBe(137); }); it("commands: 9 files, 24,702 bytes", () => { @@ -230,7 +239,7 @@ describe("auditPromptSurfaces (real tree)", () => { expect(references.bytes).toBe(161_350); }); - it("total absolute-language hits are 286 (post Wave 4 Task 4.3 follow-up)", () => { + it("total absolute-language hits are 296 (Wave 1 role plumbing added wave-verifier.md)", () => { // SPEC assumption A5: research-phase count (394) and spec count (396) // differ by measurement method. The Wave 1 audit re-measures with one // documented method (\b(?:must|never|always|critical|only)\b, gi) and @@ -286,7 +295,15 @@ describe("auditPromptSurfaces (real tree)", () => { // 18 -> 15 (-3: "Only", "never", "always"), dispatch-patterns.md // 19 -> 18 (-1: "must"). Total: 290 -> 286. The immutable Wave 1 // baseline (394) remains in RESEARCH.md. - expect(report.totalAbsoluteHits).toBe(286); + // + // The wave-verifier-gating workflow's Wave 1 role plumbing adds the + // new `wave-verifier` role as agents/goop-wave-verifier.md on top of + // this Wave 4 baseline. That file contributes 10 absolute-language + // hits of its own (it states explicit MUST/NEVER contract + // obligations), lifting the total from 286 to 296. The +10 delta is a + // property of the added role's prompt, not a regression of the Wave 4 + // consolidation work. + expect(report.totalAbsoluteHits).toBe(296); }); it("per-file tokens are consistent with chars via estimateTokens", () => { diff --git a/packages/opencode-plugin/src/features/resolver/index.test.ts b/packages/opencode-plugin/src/features/resolver/index.test.ts index 8e3c6ba6..793a15d9 100644 --- a/packages/opencode-plugin/src/features/resolver/index.test.ts +++ b/packages/opencode-plugin/src/features/resolver/index.test.ts @@ -151,7 +151,7 @@ describe("real prompt reference pointers", () => { throw new Error(`Dangling reference pointers:\n${failures.join("\n")}`); } - expect(promptFiles).toHaveLength(23); + expect(promptFiles).toHaveLength(24); expect(pointers.length).toBeGreaterThan(0); expect(new Set(pointers.map((pointer) => pointer.name)).size).toBeGreaterThan(0); }); diff --git a/packages/opencode-plugin/src/features/routing/model-routing.test.ts b/packages/opencode-plugin/src/features/routing/model-routing.test.ts index e030d8b7..06f621f4 100644 --- a/packages/opencode-plugin/src/features/routing/model-routing.test.ts +++ b/packages/opencode-plugin/src/features/routing/model-routing.test.ts @@ -231,9 +231,9 @@ describe("buildModelPreferenceMap", () => { } }); - it("returns preferences for all 14 roles", () => { + it("returns preferences for all 15 roles", () => { const map = buildModelPreferenceMap(); - expect(Object.keys(map).length).toBe(14); + expect(Object.keys(map).length).toBe(15); for (const role of AGENT_ROLES) { expect(map[role]).toBeDefined(); expect(map[role].preferred).toBe(DEFAULT_MODEL_MAP[role]); diff --git a/packages/opencode-plugin/src/features/setup/index.test.ts b/packages/opencode-plugin/src/features/setup/index.test.ts index d6663fa7..878a3090 100644 --- a/packages/opencode-plugin/src/features/setup/index.test.ts +++ b/packages/opencode-plugin/src/features/setup/index.test.ts @@ -274,12 +274,14 @@ describe("setup feature", () => { "executor-frontend-high", "planner", "verifier", + "wave-verifier", "researcher", "explorer", "debugger", "tester", "writer", ]; + expect(roles.length, "hardcoded roster must track AGENT_ROLES").toBe(AGENT_ROLES.length); for (const role of roles) { expect(DEFAULT_MODEL_MAP[role as keyof typeof DEFAULT_MODEL_MAP]).toBeDefined(); } @@ -352,6 +354,8 @@ describe("setup feature", () => { const expected = role === "explorer" || role === "researcher" ? "medium" : "high"; expect(DEFAULT_THINKING_LEVELS[role]).toBe(expected); } + // wave-verifier is a non-exploring role and must derive `high`. + expect(DEFAULT_THINKING_LEVELS["wave-verifier"]).toBe("high"); }); it("getEffectiveThinkingLevels returns built-in defaults with no config", () => { From 0102865bfc37e456fcf732e44f7c1529e45444b6 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 06:09:09 -0700 Subject: [PATCH 03/22] fix(plugin): align wave-verifier prompt with agent invariants Add the standard core-protocol boot pointer in a Mandatory First Steps section (required by the memory-first-boot semantic invariant shared by every agent) and prefix the delegation prohibition with an explicit "Do not" cue so the tool-grant scanner recognizes it as prohibitive rather than a required grant. Refresh the agents-directory byte snapshot for the added prose; file and bold-span counts are unchanged. --- .../opencode-plugin/agents/goop-wave-verifier.md | 8 +++++++- .../src/features/prompt-audit/index.test.ts | 14 +++++++++----- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/packages/opencode-plugin/agents/goop-wave-verifier.md b/packages/opencode-plugin/agents/goop-wave-verifier.md index 662282c3..8eb0cbc3 100644 --- a/packages/opencode-plugin/agents/goop-wave-verifier.md +++ b/packages/opencode-plugin/agents/goop-wave-verifier.md @@ -54,10 +54,16 @@ You are scoped to a single wave. Before any inspection: - Implement fixes, edit files, or write code. You report gaps; the orchestrator dispatches fixes. - Run at, or substitute for, the acceptance gate. `goop-verifier` owns final acceptance. -- Delegate work (`task`) or transition workflow state (`goop_state`). Progression is the orchestrator's call. +- Do not delegate work (`task`) or transition workflow state (`goop_state`). Progression is the orchestrator's call. - Span multiple waves. If your dispatch touches more than one wave, return `blocked`. - Mark a task verified without reproducible evidence, or trust summaries/commit messages as proof. +## Mandatory First Steps + +Before inspecting the wave: + +Boot sequence: see `references/core-protocol.md` §Agent Boot Sequence. Batch independent tool calls — see `references/core-protocol.md` §Tool-Call Batching. + ## Verification Row Contract Each task you inspect must produce at least one verification row: diff --git a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts index 6a1170c5..b77756a4 100644 --- a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts +++ b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts @@ -123,7 +123,7 @@ describe("auditPromptSurfaces (real tree)", () => { expect(report.directories.map((d) => d.directory)).toEqual([...PROMPT_DIRECTORIES]); }); - it("agents: 15 files, 82,100 bytes, 137 bold spans", () => { + it("agents: 15 files, 82,324 bytes, 137 bold spans", () => { // Wave 3 Task 3.2 consolidated agents/goop-orchestrator.md (the largest // single prompt) around the Task 3.1 pointer targets in core-protocol.md, // dispatch-patterns.md, and phase-gates.md: 17,207 -> 9,807 bytes @@ -165,12 +165,16 @@ describe("auditPromptSurfaces (real tree)", () => { // on top of this Wave 4 baseline: 14 files, 76,962 bytes, 127 bold // spans -> 15 files, 82,100 bytes, 137 bold spans (+5,138 bytes, +10 // bold spans, exactly the new file's own measurements). No existing - // agent file changed. The immutable Wave 1 baseline (99,822 bytes, - // 14 files) remains in RESEARCH.md and predates both this addition and - // the Wave 3/4 consolidation passes. + // agent file changed. A same-wave follow-up fix aligned the new file's + // prompt with the shared boot-pointer and delegation-prohibition + // invariants (added a Mandatory First Steps section and an explicit + // "Do not" prefix): 82,100 -> 82,324 bytes (+224), bold spans and + // absolute-language hits unchanged. The immutable Wave 1 baseline + // (99,822 bytes, 14 files) remains in RESEARCH.md and predates both + // this addition and the Wave 3/4 consolidation passes. const agents = report.directories.find((d) => d.directory === "agents")!; expect(agents.files).toBe(15); - expect(agents.bytes).toBe(82_100); + expect(agents.bytes).toBe(82_324); expect(agents.boldSpans).toBe(137); }); From dc724d0de1f2bdab6c71ccbbe03dca59077608f4 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 06:12:25 -0700 Subject: [PATCH 04/22] fix(webfront): mirror wave-verifier role and default model in hand-maintained settings surfaces Keeps the webfront role taxonomy and inlined DEFAULT_MODEL_MAP in sync with the canonical plugin registry so the new wave-verifier role is listed and resolves its default model in all agent/model settings pages. --- goopspec.example.json | 4 ++++ .../src/routes/[project]/settings/agents/+page.svelte | 3 ++- .../src/routes/[project]/settings/models/+page.svelte | 3 ++- packages/webfront/src/routes/settings/agents/+page.svelte | 3 ++- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/goopspec.example.json b/goopspec.example.json index 8310d350..76d54589 100644 --- a/goopspec.example.json +++ b/goopspec.example.json @@ -76,6 +76,10 @@ "goop-verifier": { "model": "anthropic/claude-sonnet-4-6", "temperature": 0.1 + }, + "goop-wave-verifier": { + "model": "anthropic/claude-sonnet-4-6", + "temperature": 0.1 } } } diff --git a/packages/webfront/src/routes/[project]/settings/agents/+page.svelte b/packages/webfront/src/routes/[project]/settings/agents/+page.svelte index d8c29acd..19583d02 100644 --- a/packages/webfront/src/routes/[project]/settings/agents/+page.svelte +++ b/packages/webfront/src/routes/[project]/settings/agents/+page.svelte @@ -31,7 +31,7 @@ { id: 'medium', title: 'Medium tier', - roles: ['executor-medium', 'executor-frontend-low', 'executor-low', 'verifier'] + roles: ['executor-medium', 'executor-frontend-low', 'executor-low', 'verifier', 'wave-verifier'] }, { id: 'specialized', @@ -51,6 +51,7 @@ 'executor-frontend-high': 'anthropic/claude-opus-4-6', planner: 'anthropic/claude-opus-4-6', verifier: 'anthropic/claude-sonnet-4-6', + 'wave-verifier': 'anthropic/claude-sonnet-4-6', researcher: 'anthropic/claude-sonnet-4-6', explorer: 'anthropic/claude-sonnet-4-6', debugger: 'anthropic/claude-sonnet-4-6', diff --git a/packages/webfront/src/routes/[project]/settings/models/+page.svelte b/packages/webfront/src/routes/[project]/settings/models/+page.svelte index 7730109d..efb6961f 100644 --- a/packages/webfront/src/routes/[project]/settings/models/+page.svelte +++ b/packages/webfront/src/routes/[project]/settings/models/+page.svelte @@ -31,7 +31,7 @@ { id: 'medium', title: 'Medium tier', - roles: ['executor-medium', 'executor-frontend-low', 'executor-low', 'verifier'] + roles: ['executor-medium', 'executor-frontend-low', 'executor-low', 'verifier', 'wave-verifier'] }, { id: 'specialized', @@ -51,6 +51,7 @@ 'executor-frontend-high': 'anthropic/claude-opus-4-6', planner: 'anthropic/claude-opus-4-6', verifier: 'anthropic/claude-sonnet-4-6', + 'wave-verifier': 'anthropic/claude-sonnet-4-6', researcher: 'anthropic/claude-sonnet-4-6', explorer: 'anthropic/claude-sonnet-4-6', debugger: 'anthropic/claude-sonnet-4-6', diff --git a/packages/webfront/src/routes/settings/agents/+page.svelte b/packages/webfront/src/routes/settings/agents/+page.svelte index 12e2bc70..29684148 100644 --- a/packages/webfront/src/routes/settings/agents/+page.svelte +++ b/packages/webfront/src/routes/settings/agents/+page.svelte @@ -26,7 +26,7 @@ { id: 'medium', title: 'Medium tier', - roles: ['executor-medium', 'executor-frontend-low', 'executor-low', 'verifier'] + roles: ['executor-medium', 'executor-frontend-low', 'executor-low', 'verifier', 'wave-verifier'] }, { id: 'specialized', @@ -46,6 +46,7 @@ 'executor-frontend-high': 'anthropic/claude-opus-4-6', planner: 'anthropic/claude-opus-4-6', verifier: 'anthropic/claude-sonnet-4-6', + 'wave-verifier': 'anthropic/claude-sonnet-4-6', researcher: 'anthropic/claude-sonnet-4-6', explorer: 'anthropic/claude-sonnet-4-6', debugger: 'anthropic/claude-sonnet-4-6', From ae72d67571ba4c9c9135371be754cef79984f8b1 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 06:18:40 -0700 Subject: [PATCH 05/22] test(plugin): cover wave-verifier registration across V1 and V2 Both adapters consume the shared AGENT_ROLES / DEFAULT_THINKING_LEVELS registries, so a single role addition flows through with no adapter branch. Pin that contract with focused assertions: V1 config.agent surface plus chat.params high-level resolution, and V2 agent-transform high-variant application. --- .../opencode-plugin/src/core/hooks-v2.test.ts | 60 +++++++++++++++++++ .../src/hooks/agent-registration.test.ts | 60 +++++++++++++++++++ 2 files changed, 120 insertions(+) diff --git a/packages/opencode-plugin/src/core/hooks-v2.test.ts b/packages/opencode-plugin/src/core/hooks-v2.test.ts index 8877fb7a..3f982eff 100644 --- a/packages/opencode-plugin/src/core/hooks-v2.test.ts +++ b/packages/opencode-plugin/src/core/hooks-v2.test.ts @@ -447,6 +447,66 @@ describe("registerHooksV2()", () => { env.cleanup(); }); + it("applies the high thinking variant to goop-wave-verifier through the shared V2 agent transform", async () => { + const env = setupTestEnvironment("v2-wave-verifier-thinking"); + const ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + // No agentThinkingLevels override — wave-verifier must resolve to its + // DEFAULT_THINKING_LEVELS value of "high" (it is not a medium role). + const registrations: Registrations = { + agentTransforms: 0, + catalogTransforms: 0, + agentReloads: 0, + catalogReloads: 0, + }; + + await registerHooksV2(createRuntimeContext(registrations), ctx); + + const agent: V2AgentInfo = { + id: "goop-wave-verifier", + model: { providerID: "anthropic", id: "claude-sonnet-4-6" }, + request: { headers: {}, body: {} }, + }; + const catalog: V2CatalogDraft = { + provider: { + list: () => [ + { + provider: { id: "anthropic" }, + models: new Map([ + [ + "claude-sonnet-4-6", + { + variants: [ + { id: "low", headers: {}, body: { reasoning_effort: "low" } }, + { + id: "high", + headers: { "x-reasoning": "high" }, + body: { reasoning_effort: "high" }, + }, + ], + }, + ], + ]), + }, + ], + }, + }; + const agents: V2AgentDraft = { + list: () => [agent], + update: (_id, update) => update(agent), + }; + + await registrations.catalogTransform?.(catalog); + await registrations.agentTransform?.(agents); + + // getGoopRole recognised "wave-verifier" via the shared AGENT_ROLES + // registry (otherwise applyThinkingLevelsToAgents would have skipped it) + // and the resolved level is the default "high". + expect(agent.model?.variant).toBe("high"); + expect(agent.request.headers).toEqual({ "x-reasoning": "high" }); + expect(agent.request.body).toEqual({ reasoning_effort: "high" }); + env.cleanup(); + }); + it("keeps experimental.session.compacting in the V2 skipped list and registers no compaction capability (AD8, NFR4)", async () => { const ctx = createMockPluginContext(); contexts.push(ctx); diff --git a/packages/opencode-plugin/src/hooks/agent-registration.test.ts b/packages/opencode-plugin/src/hooks/agent-registration.test.ts index 3b667a12..92567a7d 100644 --- a/packages/opencode-plugin/src/hooks/agent-registration.test.ts +++ b/packages/opencode-plugin/src/hooks/agent-registration.test.ts @@ -47,6 +47,66 @@ describe("createAgentRegistrationHook", () => { } }); + it("registers goop-wave-verifier via the shared roster and resolves its high thinking level", async () => { + const { testDir, cleanup } = setupTestEnvironment("agent-reg-wave-verifier"); + const originalGlobalPath = process.env.GOOPSPEC_GLOBAL_CONFIG_PATH; + try { + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = join(testDir, "no-global-config.json"); + const ctx = createMockPluginContext({ testDir }); + const hooks = createAgentRegistrationHook(ctx); + + const config: SdkConfig = {}; + await hooks.config?.(config); + + // V1 config registration surfaces wave-verifier from the shared agents/ + // roster — no adapter-specific branch is involved. + expect(config.agent?.["goop-wave-verifier"]).toBeDefined(); + expect(config.agent?.["goop-wave-verifier"]?.model).toBe("anthropic/claude-sonnet-4-6"); + + // chat.params resolves the role through the shared AGENT_ROLES registry + // (getGoopRole) and applies DEFAULT_THINKING_LEVELS["wave-verifier"], + // which derives to "high" because wave-verifier is not a medium role. + const output = { temperature: 0, topP: 0, topK: 0, maxOutputTokens: undefined, options: {} }; + await withProviderCatalog( + ctx, + { + providers: [ + { + id: "anthropic", + models: { + "claude-sonnet-4-6": { + capabilities: { reasoning: true }, + options: { reasoningEffort: ["low", "high"] }, + }, + }, + }, + ], + }, + async () => { + await hooks["chat.params"]?.( + { + sessionID: "session", + agent: "goop-wave-verifier", + model: { providerID: "anthropic", id: "claude-sonnet-4-6" } as never, + provider: {} as never, + message: {} as never, + }, + output, + ); + }, + ); + + expect(output.options).toEqual({ reasoningEffort: "high" }); + } finally { + if (originalGlobalPath === undefined) { + Reflect.deleteProperty(process.env, "GOOPSPEC_GLOBAL_CONFIG_PATH"); + } else { + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = originalGlobalPath; + } + cleanup(); + } + }); + it("does not overwrite an existing agent entry", async () => { const { testDir, cleanup } = setupTestEnvironment("agent-reg-override"); try { From 2a89b860e74e7632352f59878208d20ae267f941 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 06:36:27 -0700 Subject: [PATCH 06/22] feat(plugin): add pure verifier stage-gating predicates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduces isVerifierDispatchAllowed (role x phase dispatch check, fail-open on undetermined roles) and isWaveVerified (gate satisfied by >=1 verification row with none failing; an explicit skip row is an auditable escape). Also centralizes the pass|fail|skip -> passed| failed|skipped status mapping in one place so future integration points stop duplicating it. No DB access, hooks, or tool changes — runtime enforcement is wired up separately. --- .../enforcement/verifier-stage.test.ts | 188 ++++++++++++++++++ .../features/enforcement/verifier-stage.ts | 107 ++++++++++ 2 files changed, 295 insertions(+) create mode 100644 packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts create mode 100644 packages/opencode-plugin/src/features/enforcement/verifier-stage.ts diff --git a/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts b/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts new file mode 100644 index 00000000..78127bac --- /dev/null +++ b/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts @@ -0,0 +1,188 @@ +import { describe, expect, it } from "bun:test"; + +import { WORKFLOW_PHASES } from "../../core/constants.js"; +import type { WorkflowPhase } from "../../core/types.js"; +import { + VERIFICATION_RESULT_STATUSES, + VERIFICATION_RESULT_TO_DB_STATUS, + VERIFICATION_STATUSES, + type VerifiedRowLike, + isVerifierDispatchAllowed, + isWaveVerified, + toDbVerificationStatus, +} from "./verifier-stage.js"; + +// --------------------------------------------------------------------------- +// isVerifierDispatchAllowed +// --------------------------------------------------------------------------- + +describe("isVerifierDispatchAllowed", () => { + for (const phase of WORKFLOW_PHASES) { + it(`allows "verifier" only in accept (phase: ${phase})`, () => { + const result = isVerifierDispatchAllowed({ role: "verifier", phase }); + if (phase === "accept") { + expect(result.allowed).toBe(true); + expect(result.reason).toBeUndefined(); + } else { + expect(result.allowed).toBe(false); + expect(result.reason).toContain("acceptance-only"); + expect(result.reason).toContain(phase); + } + }); + + it(`allows "wave-verifier" only in execute (phase: ${phase})`, () => { + const result = isVerifierDispatchAllowed({ + role: "wave-verifier", + phase, + }); + if (phase === "execute") { + expect(result.allowed).toBe(true); + expect(result.reason).toBeUndefined(); + } else { + expect(result.allowed).toBe(false); + expect(result.reason).toContain("execute-only"); + expect(result.reason).toContain(phase); + } + }); + } + + const otherRoles = [ + "orchestrator", + "executor-low", + "executor-medium", + "executor-high", + "executor-frontend-low", + "executor-frontend-medium", + "executor-frontend-high", + "planner", + "researcher", + "explorer", + "debugger", + "tester", + "writer", + ]; + + for (const role of otherRoles) { + for (const phase of WORKFLOW_PHASES) { + it(`allows "${role}" in every phase (phase: ${phase})`, () => { + expect(isVerifierDispatchAllowed({ role, phase }).allowed).toBe(true); + }); + } + } + + for (const phase of WORKFLOW_PHASES) { + it(`allows an undefined role (fail open) in phase: ${phase}`, () => { + expect( + isVerifierDispatchAllowed({ role: undefined, phase }).allowed, + ).toBe(true); + }); + + it(`allows an unrecognized role string (fail open) in phase: ${phase}`, () => { + expect( + isVerifierDispatchAllowed({ role: "totally-unknown-role", phase }) + .allowed, + ).toBe(true); + }); + } + + it("is case-sensitive: 'Verifier' is not treated as the accept-only role", () => { + // Deliberately undetermined-role behavior, not an implicit normalization. + expect( + isVerifierDispatchAllowed({ role: "Verifier", phase: "discuss" }).allowed, + ).toBe(true); + }); +}); + +// --------------------------------------------------------------------------- +// pass/fail/skip <-> passed/failed/skipped mapping +// --------------------------------------------------------------------------- + +describe("verification status mapping", () => { + it("maps every result status to a valid DB status", () => { + for (const status of VERIFICATION_RESULT_STATUSES) { + const mapped = VERIFICATION_RESULT_TO_DB_STATUS[status]; + expect(VERIFICATION_STATUSES).toContain(mapped); + } + }); + + it("maps pass -> passed, fail -> failed, skip -> skipped", () => { + expect(toDbVerificationStatus("pass")).toBe("passed"); + expect(toDbVerificationStatus("fail")).toBe("failed"); + expect(toDbVerificationStatus("skip")).toBe("skipped"); + }); + + it("returns undefined for an input outside the result vocabulary", () => { + expect(toDbVerificationStatus("passed")).toBeUndefined(); + expect(toDbVerificationStatus("unknown")).toBeUndefined(); + expect(toDbVerificationStatus("")).toBeUndefined(); + }); +}); + +// --------------------------------------------------------------------------- +// isWaveVerified +// --------------------------------------------------------------------------- + +function row(status: VerifiedRowLike["status"]): VerifiedRowLike { + return { status }; +} + +describe("isWaveVerified", () => { + it("is false for zero rows", () => { + expect(isWaveVerified([])).toBe(false); + }); + + it("is true for a single passed row", () => { + expect(isWaveVerified([row("passed")])).toBe(true); + }); + + it("is false for a single failed row", () => { + expect(isWaveVerified([row("failed")])).toBe(false); + }); + + it("is true for a single skipped row (auditable escape)", () => { + expect(isWaveVerified([row("skipped")])).toBe(true); + }); + + it("is true for multiple passed rows", () => { + expect(isWaveVerified([row("passed"), row("passed")])).toBe(true); + }); + + it("is false when any row among several is failed", () => { + expect(isWaveVerified([row("passed"), row("failed"), row("passed")])).toBe( + false, + ); + }); + + it("is false for a mixed skip/fail set", () => { + expect(isWaveVerified([row("skipped"), row("failed")])).toBe(false); + }); + + it("is true for a mixed pass/skip set", () => { + expect(isWaveVerified([row("passed"), row("skipped")])).toBe(true); + }); + + it("treats a pending row as non-failing on its own", () => { + expect(isWaveVerified([row("pending")])).toBe(true); + }); + + it("is false when a pending row accompanies a failed row", () => { + expect(isWaveVerified([row("pending"), row("failed")])).toBe(false); + }); +}); + +// --------------------------------------------------------------------------- +// Sanity: WORKFLOW_PHASES actually covers all five phases used above +// --------------------------------------------------------------------------- + +describe("phase coverage sanity check", () => { + it("exercises all five workflow phases", () => { + const expected: WorkflowPhase[] = [ + "idle", + "discuss", + "plan", + "execute", + "accept", + ]; + expect([...WORKFLOW_PHASES].sort()).toEqual([...expected].sort()); + }); +}); diff --git a/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts b/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts new file mode 100644 index 00000000..057b8069 --- /dev/null +++ b/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts @@ -0,0 +1,107 @@ +/** + * Verifier stage-gating predicates: is a role dispatchable in the current + * phase, and do a wave's verification rows satisfy the completion gate. + * Pure and side-effect-free — the runtime guard hook and wave-completion + * gate (later tasks) consume these but own all I/O themselves. + * + * @module features/enforcement/verifier-stage + */ + +import type { WorkflowPhase } from "../../core/types.js"; +import { VERIFICATION_STATUSES, type VerificationStatus } from "../db/types.js"; +import type { ValidationResult } from "./validators.js"; + +// --------------------------------------------------------------------------- +// Verifier dispatch gating +// --------------------------------------------------------------------------- + +const ACCEPT_ONLY_ROLE = "verifier"; +const EXECUTE_ONLY_ROLE = "wave-verifier"; + +export interface VerifierDispatchCheck { + /** + * Arbitrary string, not just {@link AgentRole} — the caller derives this + * from a delegated agent name and may not normalize it. Undefined or + * unrecognized values are treated as undetermined and allowed. + */ + role: string | undefined; + phase: WorkflowPhase; +} + +/** + * `"verifier"` is accept-only and `"wave-verifier"` is execute-only; every + * other role (including undetermined ones) is allowed in every phase — + * fails OPEN so unrelated delegations are never blocked by this predicate. + */ +export function isVerifierDispatchAllowed({ + role, + phase, +}: VerifierDispatchCheck): ValidationResult { + if (role === ACCEPT_ONLY_ROLE) { + return phase === "accept" + ? { allowed: true } + : { + allowed: false, + reason: `verifier is acceptance-only; dispatch wave-verifier during execute (current phase: ${phase}).`, + }; + } + + if (role === EXECUTE_ONLY_ROLE) { + return phase === "execute" + ? { allowed: true } + : { + allowed: false, + reason: `wave-verifier is execute-only; dispatch verifier during accept (current phase: ${phase}).`, + }; + } + + return { allowed: true }; +} + +// --------------------------------------------------------------------------- +// Verification-result <-> DB status mapping (single source of truth) +// --------------------------------------------------------------------------- + +/** `goop_write_wave`'s `verifications[]` vocabulary, distinct from the DB's + * stored {@link VerificationStatus} (which also has a transient `"pending"`). */ +export const VERIFICATION_RESULT_STATUSES = ["pass", "fail", "skip"] as const; +export type VerificationResultStatus = + (typeof VERIFICATION_RESULT_STATUSES)[number]; + +export const VERIFICATION_RESULT_TO_DB_STATUS: Readonly< + Record +> = { + pass: "passed", + fail: "failed", + skip: "skipped", +}; + +/** Returns `undefined` for input outside {@link VERIFICATION_RESULT_STATUSES} + * rather than throwing — callers decide how to surface an invalid input. */ +export function toDbVerificationStatus( + status: string, +): VerificationStatus | undefined { + return VERIFICATION_RESULT_TO_DB_STATUS[status as VerificationResultStatus]; +} + +// Re-exported so consumers don't need a second import from features/db/types.js. +export { VERIFICATION_STATUSES }; +export type { VerificationStatus }; + +// --------------------------------------------------------------------------- +// Wave verification gate +// --------------------------------------------------------------------------- + +export interface VerifiedRowLike { + status: VerificationStatus; +} + +/** + * True when there is at least one row and none is `"failed"`. An explicit + * `"skipped"` row (alone or alongside passing rows) satisfies the gate as a + * deliberate, auditable escape — a wave with zero rows is never verified. + */ +export function isWaveVerified(rows: readonly VerifiedRowLike[]): boolean { + if (rows.length === 0) return false; + return rows.every((row) => row.status !== "failed"); +} From b49817cc3f2e239756b28ee6ccdaa9beba866ec3 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 06:59:46 -0700 Subject: [PATCH 07/22] feat(plugin): block wrong-stage verifier task delegation before execution MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a tool.execute.before guard that denies a task delegation to goop-verifier outside accept or goop-wave-verifier outside execute, with an actionable message naming the correct role and stage. Real blocking requires a thrown error to reach the host, but the shared hook chain (mergeHooks/chainHandlers) unconditionally swallows every handler error via safeHandler so a denial would never propagate. Introduces IntentionalToolDenialError, a narrowly-scoped sentinel that safeHandler rethrows instead of catching — every other error, from this hook or any other, keeps today's catch-and-log behavior unchanged. Fails open on unrecognized tools, roles, or an undeterminable workflow phase. --- .../opencode-plugin/src/hooks/index.test.ts | 135 ++++++- packages/opencode-plugin/src/hooks/index.ts | 5 + .../opencode-plugin/src/hooks/utils.test.ts | 56 +++ packages/opencode-plugin/src/hooks/utils.ts | 35 +- .../hooks/verifier-stage-guard/index.test.ts | 337 ++++++++++++++++++ .../src/hooks/verifier-stage-guard/index.ts | 76 ++++ 6 files changed, 641 insertions(+), 3 deletions(-) create mode 100644 packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts create mode 100644 packages/opencode-plugin/src/hooks/verifier-stage-guard/index.ts diff --git a/packages/opencode-plugin/src/hooks/index.test.ts b/packages/opencode-plugin/src/hooks/index.test.ts index c30f74cf..fc1a4db4 100644 --- a/packages/opencode-plugin/src/hooks/index.test.ts +++ b/packages/opencode-plugin/src/hooks/index.test.ts @@ -1,7 +1,18 @@ import { describe, expect, it, spyOn } from "bun:test"; -import { createMockPluginContext, setupTestEnvironment } from "../test-utils.js"; +import type { GoopState, WorkflowPhase } from "../core/types.js"; +import { + createDefaultWorkflowState, + createMockPluginContext, + setupTestEnvironment, +} from "../test-utils.js"; import { DEFAULT_HOOK_FACTORIES, createHooks, mergeHooks, registerHookFactory } from "./index.js"; import type { HookFactory, Hooks } from "./types.js"; +import { IntentionalToolDenialError } from "./utils.js"; + +/** Builds a `Partial` override that puts the default workflow at `phase`. */ +function stateAtPhase(phase: WorkflowPhase): Partial { + return { workflows: { default: createDefaultWorkflowState({ phase }) } }; +} // --------------------------------------------------------------------------- // mergeHooks @@ -131,6 +142,63 @@ describe("mergeHooks", () => { expect(order).toEqual([1, 2]); consoleSpy.mockRestore(); }); + + it("propagates an IntentionalToolDenialError through merged tool.execute.before handlers and stops later ones", async () => { + const order: string[] = []; + + const p1: Partial = { + "tool.execute.before": async () => { + order.push("p1-lifecycle"); + }, + }; + const p2: Partial = { + "tool.execute.before": async () => { + order.push("p2-guard"); + throw new IntentionalToolDenialError("goop-verifier is acceptance-only"); + }, + }; + const p3: Partial = { + "tool.execute.before": async () => { + order.push("p3-never-runs"); + }, + }; + + const result = mergeHooks([p1, p2, p3]); + + await expect( + result["tool.execute.before"]?.( + { tool: "task", sessionID: "s1", callID: "c1" }, + { args: { subagent_type: "goop-verifier" } }, + ), + ).rejects.toThrow("goop-verifier is acceptance-only"); + expect(order).toEqual(["p1-lifecycle", "p2-guard"]); + }); + + it("still swallows an ordinary error thrown from a tool.execute.before handler in a merged chain", async () => { + const consoleSpy = spyOn(console, "error").mockImplementation(() => {}); + const order: string[] = []; + + const p1: Partial = { + "tool.execute.before": async () => { + order.push("p1"); + throw new Error("unexpected bug"); + }, + }; + const p2: Partial = { + "tool.execute.before": async () => { + order.push("p2"); + }, + }; + + const result = mergeHooks([p1, p2]); + await result["tool.execute.before"]?.( + { tool: "read", sessionID: "s1", callID: "c1" }, + { args: {} }, + ); + + expect(order).toEqual(["p1", "p2"]); + consoleSpy.mockRestore(); + }); }); // --------------------------------------------------------------------------- @@ -295,3 +363,68 @@ describe("DEFAULT_HOOK_FACTORIES — AD7 boundary", () => { } }); }); + +// --------------------------------------------------------------------------- +// DEFAULT_HOOK_FACTORIES — verifier stage-dispatch guard reaches the host +// through the full production pipeline (createHooks -> mergeHooks -> chain), +// alongside the other two already-registered tool.execute.before hooks. +// --------------------------------------------------------------------------- + +describe("DEFAULT_HOOK_FACTORIES — verifier stage-dispatch guard end to end", () => { + it("blocks a goop-verifier task delegation outside accept via the real production wiring", async () => { + const { testDir, cleanup } = setupTestEnvironment("verifier-guard-e2e-deny"); + try { + const ctx = createMockPluginContext({ testDir, state: stateAtPhase("plan") }); + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + + await expect( + hooks["tool.execute.before"]?.( + { tool: "task", sessionID: "s1", callID: "c1" }, + { args: { description: "verify", prompt: "check it", subagent_type: "goop-verifier" } }, + ), + ).rejects.toThrow(IntentionalToolDenialError); + } finally { + cleanup(); + } + }); + + it("permits a goop-verifier task delegation during accept via the real production wiring", async () => { + const { testDir, cleanup } = setupTestEnvironment("verifier-guard-e2e-allow"); + try { + const ctx = createMockPluginContext({ testDir, state: stateAtPhase("accept") }); + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + + await expect( + hooks["tool.execute.before"]?.( + { tool: "task", sessionID: "s1", callID: "c1" }, + { args: { description: "verify", prompt: "check it", subagent_type: "goop-verifier" } }, + ), + ).resolves.toBeUndefined(); + } finally { + cleanup(); + } + }); + + it("leaves an unrelated task delegation untouched by the guard", async () => { + const { testDir, cleanup } = setupTestEnvironment("verifier-guard-e2e-unrelated"); + try { + const ctx = createMockPluginContext({ testDir, state: stateAtPhase("plan") }); + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + + await expect( + hooks["tool.execute.before"]?.( + { tool: "task", sessionID: "s1", callID: "c1" }, + { + args: { + description: "implement", + prompt: "build it", + subagent_type: "goop-executor-high", + }, + }, + ), + ).resolves.toBeUndefined(); + } finally { + cleanup(); + } + }); +}); diff --git a/packages/opencode-plugin/src/hooks/index.ts b/packages/opencode-plugin/src/hooks/index.ts index daa6c49d..309d1bc9 100644 --- a/packages/opencode-plugin/src/hooks/index.ts +++ b/packages/opencode-plugin/src/hooks/index.ts @@ -23,6 +23,7 @@ import { systemTransformFactory } from "./system-transform.js"; import { toolLifecycleHookFactory } from "./tool-lifecycle.js"; import type { HookEventName, HookFactory, Hooks } from "./types.js"; import { chainHandlers } from "./utils.js"; +import { verifierStageGuardHookFactory } from "./verifier-stage-guard/index.js"; // --------------------------------------------------------------------------- // Handler event names — used to distinguish chainable handlers from @@ -72,6 +73,7 @@ export const DEFAULT_HOOK_FACTORIES: readonly HookFactory[] = [ commentCheckerFactory, createCommandProcessorHook, orchestratorEnforcementFactory, + verifierStageGuardHookFactory, toolLifecycleHookFactory, loopDetectionHookFactory, lazyAutopilotNudgeHookFactory, @@ -101,6 +103,9 @@ type AnyHandler = (...args: never[]) => Promise; * * Handler events: if multiple partials define the same event, their handlers * are chained via `chainHandlers` — each runs sequentially, mutations accumulate. + * A deliberate `IntentionalToolDenialError` (see `./utils.js`) is the one + * exception: it stops the chain and propagates to the caller instead of + * being swallowed. * * Registration properties: * - `tool` maps are shallow-merged (later entries override earlier for same key) diff --git a/packages/opencode-plugin/src/hooks/utils.test.ts b/packages/opencode-plugin/src/hooks/utils.test.ts index 88cb1846..f80e221c 100644 --- a/packages/opencode-plugin/src/hooks/utils.test.ts +++ b/packages/opencode-plugin/src/hooks/utils.test.ts @@ -1,5 +1,6 @@ import { afterEach, describe, expect, it, spyOn } from "bun:test"; import { + IntentionalToolDenialError, chainHandlers, isGoopspecFile, isImplementationFile, @@ -94,6 +95,31 @@ describe("safeHandler", () => { ); consoleSpy.mockRestore(); }); + + it("rethrows IntentionalToolDenialError instead of swallowing it", async () => { + const consoleSpy = spyOn(console, "error").mockImplementation(() => {}); + const handler = async (_input: { event: unknown }) => { + throw new IntentionalToolDenialError("denied for test"); + }; + const safe = safeHandler("event", handler); + + await expect(safe({ event: { type: "test" } })).rejects.toThrow(IntentionalToolDenialError); + await expect(safe({ event: { type: "test" } })).rejects.toThrow("denied for test"); + expect(consoleSpy).not.toHaveBeenCalled(); + consoleSpy.mockRestore(); + }); + + it("still swallows a plain Error with the same message text as a denial", async () => { + const consoleSpy = spyOn(console, "error").mockImplementation(() => {}); + const handler = async (_input: { event: unknown }) => { + throw new Error("denied for test"); + }; + const safe = safeHandler("event", handler); + + await expect(safe({ event: { type: "test" } })).resolves.toBeUndefined(); + expect(consoleSpy).toHaveBeenCalledTimes(1); + consoleSpy.mockRestore(); + }); }); // --------------------------------------------------------------------------- @@ -168,6 +194,36 @@ describe("chainHandlers", () => { expect(output.system).toEqual(["injected-by-h1", "h2-saw-h1"]); }); + + it("propagates an IntentionalToolDenialError and stops the chain before later handlers run", async () => { + const order: number[] = []; + + const h1 = async (_input: { event: unknown }) => { + order.push(1); + }; + const h2 = async (_input: { event: unknown }) => { + order.push(2); + throw new IntentionalToolDenialError("stage denial"); + }; + const h3 = async (_input: { event: unknown }) => { + order.push(3); + }; + + const chained = chainHandlers("tool.execute.before", [h1, h2, h3]); + + await expect(chained({ event: { type: "test" } })).rejects.toThrow(IntentionalToolDenialError); + expect(order).toEqual([1, 2]); + }); + + it("propagates an IntentionalToolDenialError through the single-handler path", async () => { + const h1 = async (_input: { event: unknown }) => { + throw new IntentionalToolDenialError("stage denial"); + }; + + const chained = chainHandlers("tool.execute.before", [h1]); + + await expect(chained({ event: { type: "test" } })).rejects.toThrow(IntentionalToolDenialError); + }); }); // --------------------------------------------------------------------------- diff --git a/packages/opencode-plugin/src/hooks/utils.ts b/packages/opencode-plugin/src/hooks/utils.ts index e024aece..4447e829 100644 --- a/packages/opencode-plugin/src/hooks/utils.ts +++ b/packages/opencode-plugin/src/hooks/utils.ts @@ -12,13 +12,39 @@ import { log } from "../shared/logger.js"; /** Any async two-arg handler matching the SDK hook signature pattern. */ type AsyncHandler = (...args: never[]) => Promise; +// --------------------------------------------------------------------------- +// Intentional tool-execution denial — the one sentinel safeHandler rethrows +// --------------------------------------------------------------------------- + +/** + * Thrown only when a hook deliberately means to block the in-flight tool + * call (e.g. the verifier-stage guard denying a wrong-stage `task` + * delegation). This is the single, narrowly-scoped exception to "a hook + * error must never crash OpenCode": `safeHandler` recognizes this exact type + * by identity and rethrows it instead of catching it, so it propagates + * through `chainHandlers`/`mergeHooks` to the host, which aborts the tool + * call. Every other error — expected or not, from this hook or any other — + * keeps the default catch-and-log behavior unchanged. + * + * Construct this only for a deliberate denial decision, never for an + * unexpected failure inside a hook's own logic. + */ +export class IntentionalToolDenialError extends Error { + constructor(message: string) { + super(message); + this.name = "IntentionalToolDenialError"; + } +} + // --------------------------------------------------------------------------- // Safe handler wrapper — graceful degradation on throw // --------------------------------------------------------------------------- /** * Wrap a hook handler so that exceptions are caught and logged rather than - * propagated. A hook error must never crash OpenCode. + * propagated. A hook error must never crash OpenCode — except a deliberate + * {@link IntentionalToolDenialError}, which is rethrown so the host can + * actually block the tool call it was raised for. */ export function safeHandler(label: string, handler: H): H { // Capture once so high-frequency hook invocations avoid reading process.env. @@ -36,6 +62,9 @@ export function safeHandler(label: string, handler: H): await (handler as unknown as (...a: unknown[]) => Promise)(...args); } } catch (err) { + if (err instanceof IntentionalToolDenialError) { + throw err; + } // biome-ignore lint/suspicious/noConsole: Intentional error logging for graceful degradation console.error(`[goopspec] hook "${label}" error:`, err); } @@ -54,7 +83,9 @@ export function safeHandler(label: string, handler: H): * are visible to later ones. * * If a handler throws, the error is caught (via `safeHandler`) and the - * chain continues with the next handler. + * chain continues with the next handler — unless it is an + * {@link IntentionalToolDenialError}, which `safeHandler` rethrows; the + * chain then stops and the error propagates to the caller. */ export function chainHandlers(eventName: string, handlers: H[]): H { if (handlers.length === 1) { diff --git a/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts b/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts new file mode 100644 index 00000000..27b2cc08 --- /dev/null +++ b/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts @@ -0,0 +1,337 @@ +import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test"; +import type { GoopState, WorkflowPhase } from "../../core/types.js"; +import { + type PluginContext, + createDefaultWorkflowState, + createMockPluginContext, + setupTestEnvironment, +} from "../../test-utils.js"; +import { DEFAULT_HOOK_FACTORIES } from "../index.js"; +import { IntentionalToolDenialError } from "../utils.js"; +import { createVerifierStageGuardHook, verifierStageGuardHookFactory } from "./index.js"; + +const ALL_PHASES: readonly WorkflowPhase[] = ["idle", "discuss", "plan", "execute", "accept"]; + +function taskArgs(subagentType: string): { args: Record } { + return { args: { description: "d", prompt: "p", subagent_type: subagentType } }; +} + +/** Builds a `Partial` override that puts the default workflow at `phase`. */ +function stateAtPhase(phase: WorkflowPhase): Partial { + return { workflows: { default: createDefaultWorkflowState({ phase }) } }; +} + +describe("createVerifierStageGuardHook", () => { + let cleanup: () => void; + + afterEach(() => { + cleanup?.(); + }); + + function ctxAtPhase(phase: WorkflowPhase): PluginContext { + const env = setupTestEnvironment(`verifier-guard-${phase}`); + cleanup = env.cleanup; + return createMockPluginContext({ testDir: env.testDir, state: stateAtPhase(phase) }); + } + + it("returns a Partial with only tool.execute.before defined", () => { + const ctx = ctxAtPhase("execute"); + const hooks = createVerifierStageGuardHook(ctx); + expect(hooks["tool.execute.before"]).toBeDefined(); + expect(typeof hooks["tool.execute.before"]).toBe("function"); + expect(hooks["tool.execute.after"]).toBeUndefined(); + }); + + // --------------------------------------------------------------------------- + // goop-verifier: accept-only + // --------------------------------------------------------------------------- + + describe("goop-verifier dispatch matrix", () => { + for (const phase of ALL_PHASES) { + const shouldDeny = phase !== "accept"; + + it(`${shouldDeny ? "denies" : "permits"} goop-verifier in ${phase}`, async () => { + const ctx = ctxAtPhase(phase); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + const call = guardHandler( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-verifier"), + ); + + if (shouldDeny) { + await expect(call).rejects.toThrow(IntentionalToolDenialError); + } else { + await expect(call).resolves.toBeUndefined(); + } + }); + } + }); + + // --------------------------------------------------------------------------- + // goop-wave-verifier: execute-only + // --------------------------------------------------------------------------- + + describe("goop-wave-verifier dispatch matrix", () => { + for (const phase of ALL_PHASES) { + const shouldDeny = phase !== "execute"; + + it(`${shouldDeny ? "denies" : "permits"} goop-wave-verifier in ${phase}`, async () => { + const ctx = ctxAtPhase(phase); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + const call = guardHandler( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-wave-verifier"), + ); + + if (shouldDeny) { + await expect(call).rejects.toThrow(IntentionalToolDenialError); + } else { + await expect(call).resolves.toBeUndefined(); + } + }); + } + }); + + // --------------------------------------------------------------------------- + // Role-form normalization + // --------------------------------------------------------------------------- + + it("denies the unprefixed form 'verifier' identically to 'goop-verifier'", async () => { + const ctx = ctxAtPhase("plan"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("verifier")), + ).rejects.toThrow(IntentionalToolDenialError); + }); + + it("denies the unprefixed form 'wave-verifier' identically to 'goop-wave-verifier'", async () => { + const ctx = ctxAtPhase("accept"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("wave-verifier")), + ).rejects.toThrow(IntentionalToolDenialError); + }); + + it("permits the unprefixed form 'verifier' in accept", async () => { + const ctx = ctxAtPhase("accept"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("verifier")), + ).resolves.toBeUndefined(); + }); + + it("permits the unprefixed form 'wave-verifier' in execute", async () => { + const ctx = ctxAtPhase("execute"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("wave-verifier")), + ).resolves.toBeUndefined(); + }); + + // --------------------------------------------------------------------------- + // Actionable denial text + // --------------------------------------------------------------------------- + + it("names goop-wave-verifier and the phase when denying goop-verifier", async () => { + const ctx = ctxAtPhase("execute"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + let caught: unknown; + try { + await guardHandler( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-verifier"), + ); + } catch (err) { + caught = err; + } + + expect(caught).toBeInstanceOf(IntentionalToolDenialError); + const message = (caught as Error).message; + expect(message).toContain("goop-verifier"); + expect(message).toContain("acceptance-only"); + expect(message).toContain("goop-wave-verifier"); + expect(message).toContain("execute"); + }); + + it("names goop-verifier and the phase when denying goop-wave-verifier", async () => { + const ctx = ctxAtPhase("accept"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + let caught: unknown; + try { + await guardHandler( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-wave-verifier"), + ); + } catch (err) { + caught = err; + } + + expect(caught).toBeInstanceOf(IntentionalToolDenialError); + const message = (caught as Error).message; + expect(message).toContain("goop-wave-verifier"); + expect(message).toContain("execute-only"); + expect(message).toContain("goop-verifier"); + expect(message).toContain("accept"); + }); + + // --------------------------------------------------------------------------- + // Fail-open paths + // --------------------------------------------------------------------------- + + it("permits non-verifier roles in every phase", async () => { + for (const phase of ALL_PHASES) { + const env = setupTestEnvironment(`verifier-guard-nonverifier-${phase}`); + try { + const ctx = createMockPluginContext({ testDir: env.testDir, state: stateAtPhase(phase) }); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-executor-high"), + ), + ).resolves.toBeUndefined(); + } finally { + env.cleanup(); + } + } + // This test manages its own per-iteration environments; make the shared + // `cleanup` a no-op so afterEach does not re-invoke an already-closed env. + cleanup = () => {}; + }); + + it("permits an undetermined role (missing subagent_type)", async () => { + const ctx = ctxAtPhase("plan"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, { args: { description: "d" } }), + ).resolves.toBeUndefined(); + }); + + it("permits a non-string subagent_type value", async () => { + const ctx = ctxAtPhase("plan"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler( + { tool: "task", sessionID: "s1", callID: "c1" }, + { args: { subagent_type: 42 } }, + ), + ).resolves.toBeUndefined(); + }); + + it("permits a task call with non-object args", async () => { + const ctx = ctxAtPhase("plan"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, { args: null }), + ).resolves.toBeUndefined(); + }); + + it("ignores unrelated tools entirely, including write/edit and mcp_ prefixed names", async () => { + const ctx = ctxAtPhase("plan"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "write", sessionID: "s1", callID: "c1" }, taskArgs("goop-verifier")), + ).resolves.toBeUndefined(); + await expect( + guardHandler({ tool: "mcp_Task", sessionID: "s1", callID: "c2" }, taskArgs("goop-verifier")), + ).resolves.toBeUndefined(); + }); + + it("matches the task tool name case-insensitively", async () => { + const ctx = ctxAtPhase("plan"); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "TASK", sessionID: "s1", callID: "c1" }, taskArgs("goop-verifier")), + ).rejects.toThrow(IntentionalToolDenialError); + }); + + it("fails open when the active workflow cannot be resolved", async () => { + const env = setupTestEnvironment("verifier-guard-broken-state"); + cleanup = env.cleanup; + const consoleSpy = spyOn(console, "error").mockImplementation(() => {}); + const ctx = createMockPluginContext({ testDir: env.testDir }); + // Force getActiveWorkflow to throw, simulating an undeterminable phase. + Object.defineProperty(ctx.stateManager, "getActiveWorkflow", { + value: () => { + throw new Error("no active workflow"); + }, + }); + const hooks = createVerifierStageGuardHook(ctx); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("tool.execute.before handler not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("goop-verifier")), + ).resolves.toBeUndefined(); + expect(consoleSpy).toHaveBeenCalledTimes(1); + consoleSpy.mockRestore(); + }); +}); + +// --------------------------------------------------------------------------- +// HookFactory wrapper + registration +// --------------------------------------------------------------------------- + +describe("verifierStageGuardHookFactory", () => { + let cleanup: () => void; + + beforeEach(() => { + const env = setupTestEnvironment("verifier-guard-factory"); + cleanup = env.cleanup; + }); + + afterEach(() => cleanup()); + + it("is the same shape as createVerifierStageGuardHook", () => { + expect(verifierStageGuardHookFactory).toBe(createVerifierStageGuardHook); + }); + + it("is registered exactly once in DEFAULT_HOOK_FACTORIES", () => { + const occurrences = DEFAULT_HOOK_FACTORIES.filter( + (factory) => factory === verifierStageGuardHookFactory, + ); + expect(occurrences).toHaveLength(1); + }); +}); diff --git a/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.ts b/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.ts new file mode 100644 index 00000000..2edfbf24 --- /dev/null +++ b/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.ts @@ -0,0 +1,76 @@ +/** + * Verifier stage-dispatch guard — blocks a `task` delegation to + * `goop-verifier` or `goop-wave-verifier` outside its permitted lifecycle + * phase. `goop-verifier` is acceptance-only; `goop-wave-verifier` is + * execute-only. + * + * Denial is a deliberate `IntentionalToolDenialError` (see `../utils.js`): + * `safeHandler` rethrows only that sentinel, so this guard's decision + * reaches the host and aborts the pending `task` call before the subagent + * session is created, while every other error this guard (or any other + * hook) might raise keeps the default catch-and-log behavior. + * + * Fails OPEN: an unrecognized tool, a missing/unrecognized `subagent_type`, + * or a failure to read the active workflow phase all fall through to the + * underlying `safeHandler` catch clause and permit the call unchanged. + */ + +import type { PluginContext } from "../../core/types.js"; +import { isVerifierDispatchAllowed } from "../../features/enforcement/verifier-stage.js"; +import type { HookFactory, Hooks } from "../types.js"; +import { IntentionalToolDenialError, safeHandler } from "../utils.js"; + +const TASK_TOOL_NAME = "task"; +const GOOP_PREFIX = "goop-"; + +/** Strips a leading `goop-` prefix; returns the raw value for unprefixed names. */ +function normalizeRole(subagentType: unknown): string | undefined { + if (typeof subagentType !== "string" || subagentType.length === 0) return undefined; + return subagentType.startsWith(GOOP_PREFIX) + ? subagentType.slice(GOOP_PREFIX.length) + : subagentType; +} + +function extractSubagentType(args: unknown): unknown { + if (typeof args !== "object" || args === null) return undefined; + return (args as Record).subagent_type; +} + +/** + * Rewrites bare `verifier`/`wave-verifier` role mentions in the predicate's + * reason text to their real, `goop-`-prefixed agent names, matching what a + * caller actually types into a subsequent `task` dispatch. Presentational + * only — the allow/deny decision itself is fully owned by + * `isVerifierDispatchAllowed`. + */ +const VERIFIER_ROLE_NAMES = /\b(wave-verifier|verifier)\b/g; +function withGoopPrefix(message: string): string { + return message.replace(VERIFIER_ROLE_NAMES, (role) => `${GOOP_PREFIX}${role}`); +} + +/** + * Create the verifier stage-dispatch guard hook. + */ +export function createVerifierStageGuardHook(ctx: PluginContext): Partial { + const handler: NonNullable = async (input, output) => { + if (input.tool.toLowerCase() !== TASK_TOOL_NAME) return; + + const role = normalizeRole(extractSubagentType(output.args)); + if (!role) return; + + const phase = ctx.stateManager.getActiveWorkflow().phase; + const result = isVerifierDispatchAllowed({ role, phase }); + if (result.allowed) return; + + const reason = + result.reason ?? `${GOOP_PREFIX}${role} dispatch is not permitted in the ${phase} phase.`; + throw new IntentionalToolDenialError(withGoopPrefix(reason)); + }; + + return { + "tool.execute.before": safeHandler("verifier-stage-guard", handler), + }; +} + +/** HookFactory-compatible wrapper. */ +export const verifierStageGuardHookFactory: HookFactory = createVerifierStageGuardHook; From 16984488f63530a64679afac7e105c4e5df3f6f7 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 07:22:24 -0700 Subject: [PATCH 08/22] =?UTF-8?q?feat(plugin):=20gate=20wave=20completion?= =?UTF-8?q?=20and=20execute=E2=86=92accept=20on=20recorded=20verification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A wave can no longer transition to done/completed, and the workflow can no longer auto-progress execute→accept, without at least one passing or explicit-skip verification row for the final wave. Zero rows and any failing row block; an explicit skip is an auditable escape. Same-call verifications are considered before the completion decision, and denial rolls back the whole call atomically, including the verification rows just supplied. Also fixes a stored-vocabulary bug at the verification insertion seam: goop_write_wave was writing raw pass|fail|skip into a column whose predicates (and the DB's own passed|failed|skipped enum) expect the canonical form, so a stored 'fail' silently satisfied the not-equal-to- 'failed' gate check. Normalisation now happens once, at insertion. --- .../src/hooks/auto-progression.test.ts | 163 +++++++- .../src/hooks/auto-progression.ts | 13 + .../src/tools/goop-write-wave/index.test.ts | 376 +++++++++++++++++- .../src/tools/goop-write-wave/index.ts | 70 +++- 4 files changed, 591 insertions(+), 31 deletions(-) diff --git a/packages/opencode-plugin/src/hooks/auto-progression.test.ts b/packages/opencode-plugin/src/hooks/auto-progression.test.ts index a9f54006..76639a5b 100644 --- a/packages/opencode-plugin/src/hooks/auto-progression.test.ts +++ b/packages/opencode-plugin/src/hooks/auto-progression.test.ts @@ -1,7 +1,7 @@ import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test"; import type { PluginContext } from "../core/types.js"; import type { GoopSpecDB } from "../features/db/index.js"; -import type { TaskStatus, WaveStatus } from "../features/db/types.js"; +import type { TaskStatus, VerificationStatus, WaveStatus } from "../features/db/types.js"; import { createStateManager } from "../features/state-manager/index.js"; import { createDefaultWorkflowState, @@ -24,11 +24,17 @@ function makeOutput(text = "ok"): ToolAfterOutput { return { title: "result", output: text, metadata: {} }; } +/** + * Seeds a final wave row (and optional tasks/verification row). `verificationStatus` + * is omitted by default; tests expecting a successful execute→accept transition + * must pass `"passed"` or `"skipped"` explicitly. + */ function seedFinalWave( ctx: PluginContext, waveNumber: number, status: WaveStatus, taskStatuses: TaskStatus[] = [], + verificationStatus?: VerificationStatus, ): void { const workflowId = ctx.stateManager.getActiveWorkflowId(); ctx.db.upsertWave(workflowId, { wave_number: waveNumber, status }); @@ -43,6 +49,14 @@ function seedFinalWave( status: taskStatus, }); } + + if (verificationStatus !== undefined) { + ctx.db.insertVerification(workflowId, { + wave_id: wave.id, + check_name: "test", + status: verificationStatus, + }); + } } describe("auto-progression hook", () => { @@ -101,7 +115,7 @@ describe("auto-progression hook", () => { }, }, }); - seedFinalWave(ctx, 3, "completed", ["done", "completed"]); + seedFinalWave(ctx, 3, "completed", ["done", "completed"], "passed"); const hooks = createAutoProgressionHook(ctx); const handler = hooks["tool.execute.after"] as NonNullable; @@ -131,7 +145,7 @@ describe("auto-progression hook", () => { }, }, }); - seedFinalWave(ctx, 5, "completed", ["completed"]); + seedFinalWave(ctx, 5, "completed", ["completed"], "passed"); const hooks = createAutoProgressionHook(ctx); const handler = hooks["tool.execute.after"] as NonNullable; @@ -187,7 +201,7 @@ describe("auto-progression hook", () => { }, }, }); - seedFinalWave(ctx, 3, "completed", ["completed"]); + seedFinalWave(ctx, 3, "completed", ["completed"], "passed"); const stateTool = createGoopStateTool(ctx); await stateTool.execute( { action: "transition", phase: "execute", force: true }, @@ -226,7 +240,7 @@ describe("auto-progression hook", () => { }, }, }); - seedFinalWave(ctx, 3, "completed", ["done", "completed"]); + seedFinalWave(ctx, 3, "completed", ["done", "completed"], "passed"); // Force transitionPhase to throw const originalTransition = ctx.stateManager.transitionPhase; @@ -322,7 +336,7 @@ describe("auto-progression hook", () => { }, }, }); - seedFinalWave(ctx, 4, "completed", ["done", "completed"]); + seedFinalWave(ctx, 4, "completed", ["done", "completed"], "passed"); const hooks = createAutoProgressionHook(ctx); const handler = hooks["tool.execute.after"] as NonNullable; @@ -339,7 +353,138 @@ describe("auto-progression hook", () => { }); // ----------------------------------------------------------------------- -// 8. Caller-driven integration: goop_state update-wave → auto-progression +// 8. Wave verification gate: task completion alone is not sufficient +// ----------------------------------------------------------------------- + +describe("auto-progression hook: wave verification gate", () => { + let cleanup: () => void; + let testDir: string; + + beforeEach(() => { + const env = setupTestEnvironment("auto-prog-verify"); + cleanup = env.cleanup; + testDir = env.testDir; + }); + + afterEach(() => cleanup()); + + function makeExecuteCtx(waveNumber: number): PluginContext { + return createMockPluginContext({ + testDir, + state: { + workflows: { + default: createDefaultWorkflowState({ + phase: "execute", + currentWave: waveNumber, + totalWaves: waveNumber, + specLocked: true, + }), + }, + }, + }); + } + + it("does not progress when the final wave has zero verification rows despite complete tasks", async () => { + const ctx = makeExecuteCtx(3); + seedFinalWave(ctx, 3, "completed", ["done", "completed"]); // no verificationStatus + + const hooks = createAutoProgressionHook(ctx); + const handler = hooks["tool.execute.after"] as NonNullable; + const output = makeOutput(); + await handler(makeInput(), output); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); + expect(output.output).toContain("Blocked: execute → accept"); + expect(output.output).toContain("goop-wave-verifier"); + }); + + it("does not progress when the final wave's only verification row is failed", async () => { + const ctx = makeExecuteCtx(3); + seedFinalWave(ctx, 3, "completed", ["done", "completed"], "failed"); + + const hooks = createAutoProgressionHook(ctx); + const handler = hooks["tool.execute.after"] as NonNullable; + const output = makeOutput(); + await handler(makeInput(), output); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); + expect(output.output).toContain("goop-wave-verifier"); + }); + + it("does not progress when the final wave has mixed passing and failing verification rows", async () => { + const ctx = makeExecuteCtx(3); + seedFinalWave(ctx, 3, "completed", ["done", "completed"]); + const workflowId = ctx.stateManager.getActiveWorkflowId(); + const wave = ctx.db.getWave(workflowId, 3); + if (!wave) throw new Error("wave not seeded"); + ctx.db.insertVerification(workflowId, { + wave_id: wave.id, + check_name: "typecheck", + status: "passed", + }); + ctx.db.insertVerification(workflowId, { + wave_id: wave.id, + check_name: "test", + status: "failed", + }); + + const hooks = createAutoProgressionHook(ctx); + const handler = hooks["tool.execute.after"] as NonNullable; + const output = makeOutput(); + await handler(makeInput(), output); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); + }); + + it("progresses when the final wave has an explicit skip verification row (no pass required)", async () => { + const ctx = makeExecuteCtx(3); + seedFinalWave(ctx, 3, "completed", ["done", "completed"], "skipped"); + + const hooks = createAutoProgressionHook(ctx); + const handler = hooks["tool.execute.after"] as NonNullable; + const output = makeOutput(); + await handler(makeInput(), output); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + }); + + it("progresses when the final wave has a passing verification row", async () => { + const ctx = makeExecuteCtx(3); + seedFinalWave(ctx, 3, "completed", ["done", "completed"], "passed"); + + const hooks = createAutoProgressionHook(ctx); + const handler = hooks["tool.execute.after"] as NonNullable; + const output = makeOutput(); + await handler(makeInput(), output); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + }); + + it("a later passing row does not erase an earlier failing row — the wave stays blocked (append-only rows)", async () => { + const ctx = makeExecuteCtx(3); + seedFinalWave(ctx, 3, "completed", ["done", "completed"], "failed"); + const workflowId = ctx.stateManager.getActiveWorkflowId(); + const wave = ctx.db.getWave(workflowId, 3); + if (!wave) throw new Error("wave not seeded"); + // Record a later passing row for a different check — verifications are + // append-only (no upsert), so this does not supersede the earlier failure. + ctx.db.insertVerification(workflowId, { + wave_id: wave.id, + check_name: "test", + status: "passed", + }); + + const hooks = createAutoProgressionHook(ctx); + const handler = hooks["tool.execute.after"] as NonNullable; + const output = makeOutput(); + await handler(makeInput(), output); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); + }); +}); + +// ----------------------------------------------------------------------- +// 9. Caller-driven integration: goop_state update-wave → auto-progression // // These tests exercise the REAL caller path — goop_state tool → DB-backed // StateManager → GoopSpecDB — rather than seeding cached state directly. @@ -407,7 +552,7 @@ describe("caller-driven integration (goop_state update-wave → auto-progression it("transitions to accept when the final wave and all tasks are complete via the caller path", async () => { const ctx = await driveToExecute(5, 5); - seedFinalWave(ctx, 5, "completed", ["done", "completed"]); + seedFinalWave(ctx, 5, "completed", ["done", "completed"], "passed"); const hooks = createAutoProgressionHook(ctx); const handler = hooks["tool.execute.after"] as NonNullable; @@ -420,7 +565,7 @@ describe("caller-driven integration (goop_state update-wave → auto-progression it("appends ADL with concrete final-wave evidence (not a counter comparison) on caller-driven progression", async () => { const ctx = await driveToExecute(5, 5); - seedFinalWave(ctx, 5, "completed", ["done", "completed"]); + seedFinalWave(ctx, 5, "completed", ["done", "completed"], "passed"); const hooks = createAutoProgressionHook(ctx); const handler = hooks["tool.execute.after"] as NonNullable; diff --git a/packages/opencode-plugin/src/hooks/auto-progression.ts b/packages/opencode-plugin/src/hooks/auto-progression.ts index 189f1ee3..323ff846 100644 --- a/packages/opencode-plugin/src/hooks/auto-progression.ts +++ b/packages/opencode-plugin/src/hooks/auto-progression.ts @@ -17,6 +17,7 @@ */ import type { PluginContext } from "../core/types.js"; +import { isWaveVerified } from "../features/enforcement/verifier-stage.js"; import { isCompleteStatus } from "../shared/status.js"; import type { HookFactory, Hooks } from "./types.js"; import { safeHandler } from "./utils.js"; @@ -53,6 +54,18 @@ export const createAutoProgressionHook: HookFactory = (ctx: PluginContext): Part if (!isCompleteStatus(finalWave.status) || completedTaskCount !== finalWaveTasks.length) return; + // Task completion alone is not sufficient — the final wave must also + // carry at least one passing or explicit-skip verification row. Guidance + // names the exact next dispatch so lazy autopilot keeps moving. + const verificationRows = ctx.db.getVerifications( + ctx.stateManager.getActiveWorkflowId(), + finalWave.id, + ); + if (!isWaveVerified(verificationRows)) { + output.output += `\n\n---\n## Blocked: execute → accept\nFinal wave ${finalWave.wave_number} tasks are complete, but no passing or explicit-skip verification is recorded for it. Dispatch goop-wave-verifier for wave ${finalWave.wave_number}, record a pass or skip verification row (goop_write_wave verifications[]), then retry.\n`; + return; + } + // Transition execute → accept try { ctx.stateManager.transitionPhase("accept"); diff --git a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts index 5092d2d8..a0608c26 100644 --- a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts @@ -235,7 +235,12 @@ describe("goop_write_wave batch mode", () => { it("appends compact reminder when single wave is written with terminal status", async () => { const tool = createGoopWriteWaveTool(ctx); const result = await tool.execute( - { wave_number: 1, title: "Done wave", status: "done" }, + { + wave_number: 1, + title: "Done wave", + status: "done", + verifications: [{ check_name: "test", status: "pass" }], + }, toolCtx, ); expect(result).toContain("Written wave 1"); @@ -290,7 +295,12 @@ describe("goop_write_wave batch mode", () => { wave_number: 1, items: [ { wave_number: 1, title: "Pending batch wave", status: "pending" }, - { wave_number: 2, title: "Completed batch wave", status: "completed" }, + { + wave_number: 2, + title: "Completed batch wave", + status: "completed", + verifications: [{ check_name: "test", status: "pass" }], + }, ], }, toolCtx, @@ -920,7 +930,17 @@ describe("goop_write_wave multi-item batch targeting and rollback", () => { const tool = createGoopWriteWaveTool(ctx); // Pre-seed wave 2 as terminal so item 2's "pending" status regresses and // throws — a genuine invalid input, not a mock. - await tool.execute({ wave_number: 2, title: "Pre-seeded done wave", status: "done" }, toolCtx); + await tool.execute( + { + wave_number: 2, + title: "Pre-seeded done wave", + status: "done", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); + const wave2Before = ctx.db.getWave("default", 2); + const wave2Id = wave2Before?.id ?? -1; const result = await tool.execute( { @@ -957,8 +977,11 @@ describe("goop_write_wave multi-item batch targeting and rollback", () => { expect(wave2).not.toBeNull(); expect(wave2?.status).toBe("done"); - // No verifications or traceability rows from the batch may survive. - expect(ctx.db.getVerifications("default")).toHaveLength(0); + // No verification/traceability rows from the batch may survive — only the + // pre-seed's own verification (written outside the batch) remains. + const verifications = ctx.db.getVerifications("default"); + expect(verifications).toHaveLength(1); + expect(verifications[0].wave_id).toBe(wave2Id); expect(ctx.db.getTraceability("default")).toHaveLength(0); }); @@ -966,11 +989,21 @@ describe("goop_write_wave multi-item batch targeting and rollback", () => { const tool = createGoopWriteWaveTool(ctx); // Pre-seed wave 2 as terminal so item 2's "pending" status regresses and // throws. - await tool.execute({ wave_number: 2, title: "Pre-seeded done wave", status: "done" }, toolCtx); + await tool.execute( + { + wave_number: 2, + title: "Pre-seeded done wave", + status: "done", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); - // Before the batch, only the pre-seed's wave_write event exists. + // Before the batch, only the pre-seed's wave_write and verification_record + // events exist (the pre-seed now carries a verification row to satisfy + // the wave-completion gate). const eventsBefore = ctx.db.getEvents("default"); - expect(eventsBefore).toHaveLength(1); + expect(eventsBefore).toHaveLength(2); await tool.execute( { @@ -998,8 +1031,10 @@ describe("goop_write_wave multi-item batch targeting and rollback", () => { const eventsAfter = ctx.db.getEvents("default"); expect(eventsAfter).toHaveLength(eventsBefore.length); - // No verification_record or traceability_write events may survive. - expect(ctx.db.getEvents("default", "verification_record")).toHaveLength(0); + // No verification_record or traceability_write events from the BATCH may + // survive — the pre-seed's own verification_record (written before the + // batch, outside its transaction) is the only one that persists. + expect(ctx.db.getEvents("default", "verification_record")).toHaveLength(1); expect(ctx.db.getEvents("default", "traceability_write")).toHaveLength(0); // Only the pre-seed's wave_write event remains — the batch's wave_write @@ -1074,7 +1109,15 @@ describe("goop_write_wave status validation", () => { it("normalises complete to completed for top-level status", async () => { const tool = createGoopWriteWaveTool(ctx); - await tool.execute({ wave_number: 1, title: "W1", status: "complete" }, toolCtx); + await tool.execute( + { + wave_number: 1, + title: "W1", + status: "complete", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); expect(ctx.db.getWave("default", 1)?.status).toBe("completed"); }); @@ -1098,7 +1141,14 @@ describe("goop_write_wave status validation", () => { await tool.execute( { wave_number: 1, - items: [{ wave_number: 1, title: "W1", status: "complete" }], + items: [ + { + wave_number: 1, + title: "W1", + status: "complete", + verifications: [{ check_name: "test", status: "pass" }], + }, + ], }, toolCtx, ); @@ -1412,6 +1462,7 @@ describe("goop_write_wave write integrity", () => { title: "Completed wave", status: "done", tasks: [{ task_index: 1, description: "Completed task", status: "completed" }], + verifications: [{ check_name: "test", status: "pass" }], }, toolCtx, ); @@ -1434,7 +1485,15 @@ describe("goop_write_wave write integrity", () => { it("protects legacy 'complete' status from regression to pending", async () => { const writeTool = createGoopWriteWaveTool(ctx); - await writeTool.execute({ wave_number: 1, title: "Legacy wave", status: "done" }, toolCtx); + await writeTool.execute( + { + wave_number: 1, + title: "Legacy wave", + status: "done", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); // Simulate a legacy 'complete' status in the DB (pre-normalisation data // that would have been written before the status normalisation boundary). @@ -1761,7 +1820,12 @@ describe("goop_write_wave durability, idempotence, and preservation", () => { it("idempotence: writing the same terminal status twice is a no-op the second time", async () => { const writeTool = createGoopWriteWaveTool(ctx); const first = await writeTool.execute( - { wave_number: 1, title: "Idempotent wave", status: "complete" }, + { + wave_number: 1, + title: "Idempotent wave", + status: "complete", + verifications: [{ check_name: "test", status: "pass" }], + }, toolCtx, ); expect(first).toContain("Written wave 1"); @@ -1776,7 +1840,15 @@ describe("goop_write_wave durability, idempotence, and preservation", () => { it("preservation: a later write omitting status leaves an existing terminal status intact", async () => { const writeTool = createGoopWriteWaveTool(ctx); - await writeTool.execute({ wave_number: 1, title: "Original", status: "complete" }, toolCtx); + await writeTool.execute( + { + wave_number: 1, + title: "Original", + status: "complete", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); await writeTool.execute({ wave_number: 1, title: "Updated title" }, toolCtx); @@ -1923,3 +1995,277 @@ describe("goop_write_wave conditional wave_number", () => { expect(JSON.parse(events[0].payload).wave_number).toBe(1); }); }); + +describe("goop_write_wave wave-completion verification gate", () => { + let ctx: PluginContext; + let toolCtx: ToolContext; + let cleanup: () => void; + + beforeEach(() => { + const env = setupTestEnvironment("goop-write-wave-verify-gate"); + cleanup = env.cleanup; + ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + toolCtx = createMockToolContext(); + }); + + afterEach(() => cleanup()); + + it("blocks single-wave completion when the wave has zero verification rows", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { wave_number: 1, title: "Unverified wave", status: "done" }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_wave"); + expect(result).toContain("cannot be marked complete"); + expect(result).toContain("goop-wave-verifier"); + // The whole call rolled back — the wave was never created. + expect(ctx.db.getWave("default", 1)).toBeNull(); + }); + + it("blocks single-wave completion when the wave's only verification row is failed", async () => { + const tool = createGoopWriteWaveTool(ctx); + // Record a fail as a prior, non-completing call so the wave exists with a + // failing row before the completion attempt. + await tool.execute( + { + wave_number: 1, + title: "Failing wave", + status: "in_progress", + verifications: [{ check_name: "test", status: "fail" }], + }, + toolCtx, + ); + + const result = await tool.execute({ wave_number: 1, status: "done" }, toolCtx); + + expect(result).toContain("Error in goop_write_wave"); + expect(result).toContain("goop-wave-verifier"); + expect(ctx.db.getWave("default", 1)?.status).toBe("in_progress"); + }); + + it("blocks single-wave completion on mixed pass/fail rows", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "Mixed wave", + status: "in_progress", + verifications: [ + { check_name: "typecheck", status: "pass" }, + { check_name: "test", status: "fail" }, + ], + }, + toolCtx, + ); + + const result = await tool.execute({ wave_number: 1, status: "completed" }, toolCtx); + + expect(result).toContain("Error in goop_write_wave"); + expect(ctx.db.getWave("default", 1)?.status).toBe("in_progress"); + }); + + it("unblocks single-wave completion with a pass-only row", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + title: "Pass wave", + status: "done", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); + + expect(result).toContain("Written wave 1"); + expect(ctx.db.getWave("default", 1)?.status).toBe("done"); + }); + + it("unblocks single-wave completion with an explicit skip-only row (auditable escape)", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + title: "Skip wave", + status: "done", + verifications: [{ check_name: "custom", status: "skip" }], + }, + toolCtx, + ); + + expect(result).toContain("Written wave 1"); + expect(ctx.db.getWave("default", 1)?.status).toBe("done"); + }); + + it("rejects a failing verification supplied in the same call as completion, rolling back the row too", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + title: "Same-call fail", + status: "done", + verifications: [{ check_name: "test", status: "fail" }], + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_wave"); + expect(result).toContain("goop-wave-verifier"); + // No partial writes: neither the wave nor the failing verification row survive. + expect(ctx.db.getWave("default", 1)).toBeNull(); + expect(ctx.db.getVerifications("default")).toHaveLength(0); + }); + + it("persists the DB's canonical vocabulary, not the tool's pass|fail|skip input", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "Canonical status wave", + status: "done", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); + + const wave = ctx.db.getWave("default", 1); + const rows = ctx.db.getVerifications("default", wave?.id ?? -1); + expect(rows).toHaveLength(1); + // Stored value must be the DB's "passed", never the tool's raw "pass". + expect(rows[0].status).toBe("passed"); + }); + + it("persists 'failed' and 'skipped' as canonical DB statuses too", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "Mixed canonical wave", + status: "in_progress", + verifications: [ + { check_name: "typecheck", status: "fail" }, + { check_name: "custom", status: "skip" }, + ], + }, + toolCtx, + ); + + const wave = ctx.db.getWave("default", 1); + const rows = ctx.db.getVerifications("default", wave?.id ?? -1); + expect(rows.map((r) => r.status).sort()).toEqual(["failed", "skipped"]); + }); + + it("blocks items[] batch completion when the item's wave has zero verification rows", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + items: [{ wave_number: 1, title: "Unverified batch wave", status: "completed" }], + }, + toolCtx, + ); + + expect(result).toContain("0/1 succeeded"); + expect(result).toContain("goop-wave-verifier"); + expect(ctx.db.getWave("default", 1)).toBeNull(); + }); + + it("unblocks items[] batch completion with a same-call pass row", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + items: [ + { + wave_number: 1, + title: "Verified batch wave", + status: "completed", + verifications: [{ check_name: "test", status: "pass" }], + }, + ], + }, + toolCtx, + ); + + expect(result).toContain("1/1 succeeded"); + expect(ctx.db.getWave("default", 1)?.status).toBe("completed"); + }); + + it("in a multi-item batch, one item's unverified completion rolls back the whole batch including a sibling's verified completion", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + items: [ + { + wave_number: 1, + title: "Verified wave", + status: "completed", + verifications: [{ check_name: "test", status: "pass" }], + }, + { + wave_number: 2, + title: "Unverified wave", + status: "completed", + }, + ], + }, + toolCtx, + ); + + expect(result).toContain("0/2 succeeded"); + // Atomic: neither wave survives even though item 1 was individually verified. + expect(ctx.db.getWave("default", 1)).toBeNull(); + expect(ctx.db.getWave("default", 2)).toBeNull(); + }); + + it("does not gate task-level completion or metadata-only writes", async () => { + const tool = createGoopWriteWaveTool(ctx); + // A wave stays non-terminal; only its task is marked done. No verification + // row exists anywhere, and this must still succeed — the gate only + // applies to the wave's own status transitioning to a complete value. + await tool.execute( + { + wave_number: 1, + title: "Task-only wave", + tasks: [{ task_index: 1, description: "Task", status: "pending" }], + }, + toolCtx, + ); + + const result = await tool.execute( + { wave_number: 1, task_update: { task_index: 1, status: "done" } }, + toolCtx, + ); + + expect(result).toContain("Updated task 1"); + expect(ctx.db.getWave("default", 1)?.status).not.toBe("done"); + }); + + it("a later passing row does not erase an earlier failing row for the same wave (append-only)", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "Append-only wave", + status: "in_progress", + verifications: [{ check_name: "test", status: "fail" }], + }, + toolCtx, + ); + await tool.execute( + { + wave_number: 1, + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); + + // Both rows now exist for the wave — the later pass does not delete the + // earlier fail — so completion must still be blocked. + const result = await tool.execute({ wave_number: 1, status: "done" }, toolCtx); + expect(result).toContain("Error in goop_write_wave"); + expect(result).toContain("goop-wave-verifier"); + }); +}); diff --git a/packages/opencode-plugin/src/tools/goop-write-wave/index.ts b/packages/opencode-plugin/src/tools/goop-write-wave/index.ts index 16ecfc81..498c9e67 100644 --- a/packages/opencode-plugin/src/tools/goop-write-wave/index.ts +++ b/packages/opencode-plugin/src/tools/goop-write-wave/index.ts @@ -17,6 +17,12 @@ import { runBatch, } from "../../features/db/batch.js"; import { TASK_STATUSES, WAVE_STATUSES, normalizeStatus } from "../../features/db/types.js"; +import { + VERIFICATION_RESULT_STATUSES, + type VerificationResultStatus, + isWaveVerified, + toDbVerificationStatus, +} from "../../features/enforcement/verifier-stage.js"; import { WAVE_COMPLETE_COMPACT_REMINDER, isWaveComplete } from "../../shared/compact-reminder.js"; import { renderSidecars } from "../../shared/render-sidecars.js"; import { isCompleteStatus } from "../../shared/status.js"; @@ -52,12 +58,9 @@ interface BulkTaskStatusUpdate { const VERIFICATION_CHECK_NAMES = ["typecheck", "test", "lint", "custom"] as const; type VerificationCheckName = (typeof VERIFICATION_CHECK_NAMES)[number]; -const VERIFICATION_RESULT_STATUSES = ["pass", "fail", "skip"] as const; -type VerificationStatus = (typeof VERIFICATION_RESULT_STATUSES)[number]; - interface VerificationPayload { check_name: VerificationCheckName; - status: VerificationStatus; + status: VerificationResultStatus; detail?: string; /** Internal row id of the target wave (not the human-facing wave_number). */ wave_id?: number; @@ -83,10 +86,21 @@ function recordVerification( ): string { const waveId = item.wave_id ?? defaultWaveId; + // Normalise the tool's pass|fail|skip vocabulary to the DB's canonical + // passed|failed|skipped vocabulary at this single insertion seam. Payloads + // are already zod-enum-validated against VERIFICATION_RESULT_STATUSES, so + // this only fails defensively (e.g. a future enum drift). + const dbStatus = toDbVerificationStatus(item.status); + if (dbStatus === undefined) { + throw new Error( + `invalid verification status '${item.status}' for wave ${defaultWaveNumber}; expected one of ${VERIFICATION_RESULT_STATUSES.join(", ")}`, + ); + } + const verificationId = ctx.db.insertVerification(workflowId, { wave_id: waveId, check_name: item.check_name, - status: item.status, + status: dbStatus, detail: item.detail, }); @@ -94,7 +108,7 @@ function recordVerification( verification_id: verificationId, wave_id: waveId ?? null, check_name: item.check_name, - status: item.status, + status: dbStatus, detail: item.detail ?? null, timestamp: Date.now(), }); @@ -215,6 +229,33 @@ function incompatiblePayloadError(mode: string, fields: string[]): string { return `Error in goop_write_wave: ${fields.join(", ")} cannot be supplied alongside ${mode}; use one write mode per call so no fields are ignored.`; } +// --------------------------------------------------------------------------- +// Wave-completion verification gate +// --------------------------------------------------------------------------- + +/** incompatiblePayloadError-style single actionable message; thrown (not + * returned) so the caller's enclosing transaction rolls back atomically. */ +function waveNotVerifiedMessage(waveNumber: number): string { + return `wave ${waveNumber} cannot be marked complete: no passing or explicit-skip verification is recorded. Dispatch goop-wave-verifier for wave ${waveNumber}, record a pass or skip verification row via this tool's verifications[] argument, then retry this completion.`; +} + +/** No-op unless `status` is a complete status. Reads rows *after* this call's + * own verifications[] are inserted, so same-call evidence counts. Throws to + * roll back the whole transaction — no partial writes on denial. */ +function assertWaveVerifiedForCompletion( + ctx: PluginContext, + workflowId: string, + waveNumber: number, + waveId: number, + status: string | undefined, +): void { + if (!isWaveComplete(status)) return; + const rows = ctx.db.getVerifications(workflowId, waveId); + if (!isWaveVerified(rows)) { + throw new Error(waveNotVerifiedMessage(waveNumber)); + } +} + // --------------------------------------------------------------------------- // Tool factory // --------------------------------------------------------------------------- @@ -225,7 +266,10 @@ export function createGoopWriteWaveTool(ctx: PluginContext): ToolDefinition { "Create or partially update wave metadata and optional inline tasks in GoopSpecDB. " + "Omit fields you do not intend to change: omitted values are preserved, while supplied metadata values, including empty strings, overwrite. " + "A tasks[] entry with task_index and status updates that task's status alone. " + - "Optionally record verifications and traceability rows in the same call.", + "Optionally record verifications and traceability rows in the same call. " + + "A wave cannot transition to a complete status (done/completed) without at least one " + + "passing or explicit-skip verification row for that wave — record one via verifications[] " + + "in this call or a prior one.", args: { wave_number: tool.schema .number() @@ -500,6 +544,14 @@ export function createGoopWriteWaveTool(ctx: PluginContext): ToolDefinition { writeTraceability(ctx, workflowId, traceability, item.wave_number), ); + assertWaveVerifiedForCompletion( + ctx, + workflowId, + item.wave_number, + wave.id, + item.status, + ); + for (const task of item.tasks ?? []) { const existingTask = ctx.db .getWaveTasks(wave.id) @@ -773,6 +825,10 @@ export function createGoopWriteWaveTool(ctx: PluginContext): ToolDefinition { for (const item of args.traceability ?? []) { traceabilityResults.push(writeTraceability(ctx, workflowId, item, waveNumber)); } + + if (hasWaveWrite) { + assertWaveVerifiedForCompletion(ctx, workflowId, waveNumber, wave.id, args.status); + } }); renderSidecars(ctx, workflowId); From c29b9b3ffa4ad6b8849e5d2c5edb8ea15f97047a Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 07:33:36 -0700 Subject: [PATCH 09/22] test(plugin): absorb completion gate into fixtures and add pipeline matrix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Seed explicit verification rows in fixtures that drive a wave to a complete status — the completion gate now rejects bare complete-status writes, so durability and integration scenarios carry the evidence their semantics already implied. Update read-side assertions to the canonical DB status vocabulary (passed/failed) that recordVerification normalises to at the insertion seam. Add a merged-pipeline timing matrix (both verifier roles x five phases) through createHooks plus a contrast case proving ordinary hook errors degrade safely while a deliberate denial propagates. --- .../hooks/verifier-stage-guard/index.test.ts | 114 +++++++++++++++++- .../opencode-plugin/src/integration.test.ts | 5 + .../src/tools/goop-read-wave/index.test.ts | 33 +++-- 3 files changed, 144 insertions(+), 8 deletions(-) diff --git a/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts b/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts index 27b2cc08..b87d607b 100644 --- a/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts +++ b/packages/opencode-plugin/src/hooks/verifier-stage-guard/index.test.ts @@ -6,7 +6,8 @@ import { createMockPluginContext, setupTestEnvironment, } from "../../test-utils.js"; -import { DEFAULT_HOOK_FACTORIES } from "../index.js"; +import { DEFAULT_HOOK_FACTORIES, createHooks } from "../index.js"; +import type { HookFactory } from "../types.js"; import { IntentionalToolDenialError } from "../utils.js"; import { createVerifierStageGuardHook, verifierStageGuardHookFactory } from "./index.js"; @@ -310,6 +311,117 @@ describe("createVerifierStageGuardHook", () => { }); }); +// --------------------------------------------------------------------------- +// Merged-pipeline integration: the guard dispatched through the real +// createHooks() chain, not the isolated single-hook handler above. +// +// The single-hook matrix proves the predicate decides correctly; these tests +// prove the decision survives the full merge: the guard is wired into +// DEFAULT_HOOK_FACTORIES, its IntentionalToolDenialError propagates through +// chainHandlers + safeHandler on denial, and a sibling hook's ordinary error +// is still swallowed (graceful degradation) while the deliberate denial is not. +// --------------------------------------------------------------------------- + +describe("merged pipeline integration: verifier stage guard through createHooks()", () => { + let cleanup: () => void; + + afterEach(() => { + cleanup?.(); + }); + + function ctxAtPhase(phase: WorkflowPhase): PluginContext { + const env = setupTestEnvironment(`verifier-guard-merged-${phase}`); + cleanup = env.cleanup; + return createMockPluginContext({ testDir: env.testDir, state: stateAtPhase(phase) }); + } + + describe("goop-verifier timing (accept-only) through the merged pipeline", () => { + for (const phase of ALL_PHASES) { + const shouldDeny = phase !== "accept"; + + it(`${shouldDeny ? "denies" : "permits"} goop-verifier in ${phase} via createHooks`, async () => { + const ctx = ctxAtPhase(phase); + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + const before = hooks["tool.execute.before"]; + if (!before) throw new Error("merged tool.execute.before not defined"); + + const call = before( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-verifier"), + ); + + if (shouldDeny) { + await expect(call).rejects.toThrow(IntentionalToolDenialError); + } else { + await expect(call).resolves.toBeUndefined(); + } + }); + } + }); + + describe("goop-wave-verifier timing (execute-only) through the merged pipeline", () => { + for (const phase of ALL_PHASES) { + const shouldDeny = phase !== "execute"; + + it(`${shouldDeny ? "denies" : "permits"} goop-wave-verifier in ${phase} via createHooks`, async () => { + const ctx = ctxAtPhase(phase); + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + const before = hooks["tool.execute.before"]; + if (!before) throw new Error("merged tool.execute.before not defined"); + + const call = before( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-wave-verifier"), + ); + + if (shouldDeny) { + await expect(call).rejects.toThrow(IntentionalToolDenialError); + } else { + await expect(call).resolves.toBeUndefined(); + } + }); + } + }); + + it("swallows a sibling hook's ordinary error but propagates the guard's denial", async () => { + // The one sentinel exception to "a hook error must never crash OpenCode": + // safeHandler rethrows IntentionalToolDenialError and swallows everything + // else. A sibling throwing a plain Error must not abort the chain, while + // the guard's deliberate denial must still reach the caller. + const siblingErrorFactory: HookFactory = () => ({ + "tool.execute.before": async () => { + throw new Error("sibling hook exploded"); + }, + }); + + const consoleSpy = spyOn(console, "error").mockImplementation(() => {}); + + // Permitted dispatch (goop-wave-verifier in execute) + a sibling that + // throws a plain Error: the merged pipeline resolves — the sibling's + // error is swallowed by safeHandler and the guard permits the call. + const permitCtx = ctxAtPhase("execute"); + const permitHooks = createHooks(permitCtx, [...DEFAULT_HOOK_FACTORIES, siblingErrorFactory]); + const permitBefore = permitHooks["tool.execute.before"]; + if (!permitBefore) throw new Error("merged tool.execute.before not defined"); + await expect( + permitBefore({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("goop-wave-verifier")), + ).resolves.toBeUndefined(); + + // Forbidden dispatch (goop-verifier in plan): the guard's + // IntentionalToolDenialError propagates through the merged chain and the + // sibling never runs (the chain aborts on the sentinel). + const denyCtx = ctxAtPhase("plan"); + const denyHooks = createHooks(denyCtx, [...DEFAULT_HOOK_FACTORIES, siblingErrorFactory]); + const denyBefore = denyHooks["tool.execute.before"]; + if (!denyBefore) throw new Error("merged tool.execute.before not defined"); + await expect( + denyBefore({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("goop-verifier")), + ).rejects.toThrow(IntentionalToolDenialError); + + consoleSpy.mockRestore(); + }); +}); + // --------------------------------------------------------------------------- // HookFactory wrapper + registration // --------------------------------------------------------------------------- diff --git a/packages/opencode-plugin/src/integration.test.ts b/packages/opencode-plugin/src/integration.test.ts index 18fac213..b13e258b 100644 --- a/packages/opencode-plugin/src/integration.test.ts +++ b/packages/opencode-plugin/src/integration.test.ts @@ -765,6 +765,11 @@ describe("GoopSpec 5-phase integration", () => { { task_index: 2, description: "Second", status: "complete" }, { task_index: 3, description: "Last", status: "pending" }, ], + // The wave-completion gate (Wave 2) requires completion evidence + // before a wave can transition to a complete status; this write + // represents a verified-but-still-in-progress-tasks intermediate + // state, so it carries a passing verification row. + verifications: [{ check_name: "test", status: "pass", detail: "integration" }], }, toolContext, ); diff --git a/packages/opencode-plugin/src/tools/goop-read-wave/index.test.ts b/packages/opencode-plugin/src/tools/goop-read-wave/index.test.ts index 707dcaf8..cd0ab235 100644 --- a/packages/opencode-plugin/src/tools/goop-read-wave/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-read-wave/index.test.ts @@ -180,7 +180,16 @@ describe("goop_read_wave regression and durability", () => { it("durability: top-level status write is reflected by a subsequent read", async () => { const writeTool = createGoopWriteWaveTool(ctx); await writeTool.execute( - { wave_number: 1, title: "Status wave", status: "complete" }, + { + wave_number: 1, + title: "Status wave", + status: "complete", + // Wave-completion gate (Wave 2) requires at least one passing or + // explicit-skip verification row before a wave can transition to a + // complete status. The durability scenario is a completed wave, so it + // carries completion evidence. + verifications: [{ check_name: "test", status: "pass" }], + }, createMockToolContext(), ); @@ -195,7 +204,14 @@ describe("goop_read_wave regression and durability", () => { await writeTool.execute( { wave_number: 1, - items: [{ wave_number: 1, title: "Items wave", status: "complete" }], + items: [ + { + wave_number: 1, + title: "Items wave", + status: "complete", + verifications: [{ check_name: "test", status: "pass" }], + }, + ], }, createMockToolContext(), ); @@ -246,10 +262,13 @@ describe("goop_read_wave verification and traceability surfacing", () => { const readTool = createGoopReadWaveTool(ctx); const result = await readTool.execute({}, createMockToolContext()); - // Verifications appear with check name, status, and detail + // Verifications appear with check name, status, and detail. The read side + // renders the DB's canonical status vocabulary (passed/failed/skipped), + // not the tool-input vocabulary (pass/fail/skip) — recordVerification + // normalises at the insertion seam. expect(result).toContain("### Verifications"); - expect(result).toContain("typecheck: pass — No errors"); - expect(result).toContain("lint: fail — 2 issues"); + expect(result).toContain("typecheck: passed — No errors"); + expect(result).toContain("lint: failed — 2 issues"); // Traceability appears with requirement key and resolved wave/task target expect(result).toContain("### Traceability"); @@ -297,12 +316,12 @@ describe("goop_read_wave verification and traceability surfacing", () => { // Wave 1 data appears expect(result).toContain("## Wave 1: Wave one"); - expect(result).toContain("test: pass"); + expect(result).toContain("test: passed"); expect(result).toContain("MH1 -> wave 1 [covered]"); // Wave 2 data does NOT leak expect(result).not.toContain("## Wave 2: Wave two"); - expect(result).not.toContain("lint: fail"); + expect(result).not.toContain("lint: failed"); expect(result).not.toContain("MH2"); }); }); From 0bfa8c7511c99ac0a98eed34f4a076f08b70ab67 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 11:36:17 -0700 Subject: [PATCH 10/22] docs(plugin): gate wave completion on recorded verification The execute command now runs a mandatory verification step after each wave's tasks before the wave can be marked complete or its PR opened. This closes the gap where a wave could finish and stack a PR with no verification record, even though the runtime already rejects the completion transition without one. Changes: - Add a wave verification gate to goop-execute.md: dispatch the wave auditor scoped to the wave, record verification rows via the wave tool, remediate gaps with a bounded retry budget, and only then mark the wave complete and open its PR - Align wiring-checklist.md and task-decomposition.md boundary and handoff guidance with the runtime gate and its predicate - Update the prompt-surface audit snapshot counts for the prose delta --- .../opencode-plugin/commands/goop-execute.md | 10 ++++-- .../references/task-decomposition.md | 3 +- .../references/wiring-checklist.md | 2 ++ .../src/features/prompt-audit/index.test.ts | 33 ++++++++++++++++--- 4 files changed, 40 insertions(+), 8 deletions(-) diff --git a/packages/opencode-plugin/commands/goop-execute.md b/packages/opencode-plugin/commands/goop-execute.md index 2a079089..4c8a4d38 100644 --- a/packages/opencode-plugin/commands/goop-execute.md +++ b/packages/opencode-plugin/commands/goop-execute.md @@ -43,8 +43,14 @@ goop_reference({ name: "core-protocol" }) - Require every task to return `STATUS`, `SUMMARY`, `ARTIFACTS`, `VERIFICATION`, `NEXT`. 3. Apply the four-rule deviation system from `phase-gates`. Log every deviation to `ADL.md` via `goop_adl`. 4. Before dispatching a wave, call `goop_state({ action: "update-wave", currentWave: N, totalWaves: M })` to record that Wave N is in progress. `currentWave` is 1-based; `0` means no wave has started. -5. If Atomic PRs = Yes: immediately open a PR for the verified wave against the previous branch (Wave N → Wave N-1; Wave 1 → main) via `gh pr create` or `goop_create_pr`. Do not wait for it to merge. Then create the Wave N+1 branch from the current wave's branch and continue. Show the PR URL in the checkpoint. -6. Save a checkpoint at wave boundaries. +5. After every task in a wave completes, run the **wave verification gate** before the wave can be marked complete: + - Dispatch `goop-wave-verifier` scoped to that wave — one wave per dispatch; the role is execute-phase and inspect-only (see `agents/goop-wave-verifier.md`). + - The verifier records a verification row per task via `goop_write_wave({ wave_number: N, verifications: [...] })` and never implements fixes. + - On gaps: dispatch the correctly tiered executor to remediate, then re-dispatch `goop-wave-verifier` for that wave to re-verify the remediated tasks. + - Bound the remediation cycle with the three-strikes convention in `references/test-authoring.md` §Test Execution Discipline: after three failed attempts on the same gap, open a blocker via `goop_blocker` and stop; do not loop. + - The wave is complete when its rows satisfy the runtime gate — at least one verification row and zero `fail` rows; an explicit `skip` row is a deliberate, auditable escape (`isWaveVerified` in `src/features/enforcement/verifier-stage.ts`). The runtime enforces the boundary: `goop_write_wave` rejects a complete-status transition without it. +6. If Atomic PRs = Yes: after the wave verification gate passes, open a PR for the verified wave against the previous branch (Wave N → Wave N-1; Wave 1 → main) via `gh pr create` or `goop_create_pr`. Do not wait for it to merge. Then create the Wave N+1 branch from the current wave's branch and continue. Show the PR URL in the checkpoint. +7. Save a checkpoint at wave boundaries. ## Completion diff --git a/packages/opencode-plugin/references/task-decomposition.md b/packages/opencode-plugin/references/task-decomposition.md index 39c26fce..4133df02 100644 --- a/packages/opencode-plugin/references/task-decomposition.md +++ b/packages/opencode-plugin/references/task-decomposition.md @@ -104,6 +104,7 @@ Under `autopilot` or `lazyAutopilot`, skip the interactive per-wave review entir - `currentWave: 0` means no wave has started. - Call `update-wave(N, total)` when work on Wave N begins, including `update-wave(1, total)` when Wave 1 starts. - Wave completion comes from the `waves` and `wave_tasks` records, not from this progress indicator. +- Wave completion also requires the wave verification gate: `goop-wave-verifier` records a non-failing verification row for the wave via `goop_write_wave` `verifications[]`. The runtime enforces this boundary — `goop_write_wave` rejects the complete-status transition and `auto-progression.ts` blocks execute→accept until `isWaveVerified` (`src/features/enforcement/verifier-stage.ts`); see `commands/goop-execute.md` §Steps (wave verification gate). ### Parallel Execution Within a Wave @@ -121,7 +122,7 @@ Start conservatively (2 parallel agents), increase when stable. - Waves grouped by technical layer instead of feature. - Tasks without verification steps. - Must-haves that do not map to any task. -- Updating `update-wave` before a wave is verified. +- Updating `update-wave`, or marking a wave complete, before its verification gate passes — the runtime now rejects it (`isWaveVerified` in `src/features/enforcement/verifier-stage.ts`). --- diff --git a/packages/opencode-plugin/references/wiring-checklist.md b/packages/opencode-plugin/references/wiring-checklist.md index 9f799131..65d76af4 100644 --- a/packages/opencode-plugin/references/wiring-checklist.md +++ b/packages/opencode-plugin/references/wiring-checklist.md @@ -64,6 +64,7 @@ Before marking a feature complete: - [ ] **Exports** — public API re-exported from the package entry point. - [ ] **Config plumbing** — new options read by at least one consumer with observable effect. - [ ] **Documentation** — new agents, skills, or references listed in `AGENTS.md` or equivalent. +- [ ] **Verification gate** — the wave carries a non-failing verification row (`goop_write_wave` `verifications[]`) before it is marked complete or handed off. - [ ] **Build** — `bun run build` succeeds and includes new files in output. - [ ] **Discovery** — new resource appears in listing tools. @@ -124,6 +125,7 @@ Mandatory handoffs at phase completion, wave completion, checkpoint reached, or ### Handoff Rules - Include tasks completed, key decisions with rationale, exact workflow position, files modified, and explicit next steps. +- At wave completion, the wave verification gate precedes the handoff: `goop-wave-verifier` records a non-failing row for the wave before `HANDOFF.md` marks it complete. A handoff never substitutes for the recorded gate. - Do not include full file contents or detailed implementation code. - Keep the context summary to 2-4 sentences max. - Update chronicle via `goop_write_db({ doc_type: "chronicle", content: "..." })` before generating `HANDOFF.md`. diff --git a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts index b77756a4..3c05ec4f 100644 --- a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts +++ b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts @@ -178,7 +178,7 @@ describe("auditPromptSurfaces (real tree)", () => { expect(agents.boldSpans).toBe(137); }); - it("commands: 9 files, 24,702 bytes", () => { + it("commands: 9 files, 25,890 bytes", () => { // Wave 4 Task 4.1 reconciled the nine command docs against the // runtime-injected phase rules: trimmed anti-pattern/prohibition lists // to command-specific material (removing items the injected phase @@ -188,9 +188,17 @@ describe("auditPromptSurfaces (real tree)", () => { // goop-plan.md. Net effect: 25,547 -> 24,702 bytes; absolute-language // hits 34 -> 32; bold spans 68 -> 58. The immutable Wave 1 baseline // remains in RESEARCH.md. + // + // The wave-verifier-gating workflow's Wave 3 Task 1 inserted the wave + // verification gate into goop-execute.md (dispatch goop-wave-verifier + // after the per-wave task loop, bounded remediation cycle, runtime + // gate reference): 24,702 -> 25,890 bytes (+1,188); absolute hits + // 32 -> 34 (+2: the gate's "inspect-only" role boundary and the + // "never implements fixes" verifier invariant — both true role + // invariants per dispatch-patterns.md). const commands = report.directories.find((d) => d.directory === "commands")!; expect(commands.files).toBe(9); - expect(commands.bytes).toBe(24_702); + expect(commands.bytes).toBe(25_890); }); it("references: 19 files, 161,350 bytes", () => { @@ -238,12 +246,20 @@ describe("auditPromptSurfaces (real tree)", () => { // Net effect: 160,716 -> 161,350 bytes (+634, still below the 161,459 // Wave 1 baseline), absolute hits 202 -> 198 (-4), bold spans 526 -> // 530. The non-increase bar relative to the Wave 1 baseline holds. + // + // The wave-verifier-gating workflow's Wave 3 Task 1 aligned boundary/ + // handoff guidance with the runtime verification gate: wiring-checklist + // gained a verification-gate checklist item and a handoff rule ("never + // substitutes for the recorded gate" — one absolute hit), and + // task-decomposition's update-wave section and anti-pattern now cite the + // runtime predicate isWaveVerified. Net effect: 161,350 -> 162,326 bytes + // (+976), absolute hits 198 -> 199 (+1), bold spans 530 -> 532. const references = report.directories.find((d) => d.directory === "references")!; expect(references.files).toBe(19); - expect(references.bytes).toBe(161_350); + expect(references.bytes).toBe(162_326); }); - it("total absolute-language hits are 296 (Wave 1 role plumbing added wave-verifier.md)", () => { + it("total absolute-language hits are 299 (Wave 1 role plumbing plus the Wave 3 execution gate)", () => { // SPEC assumption A5: research-phase count (394) and spec count (396) // differ by measurement method. The Wave 1 audit re-measures with one // documented method (\b(?:must|never|always|critical|only)\b, gi) and @@ -307,7 +323,14 @@ describe("auditPromptSurfaces (real tree)", () => { // obligations), lifting the total from 286 to 296. The +10 delta is a // property of the added role's prompt, not a regression of the Wave 4 // consolidation work. - expect(report.totalAbsoluteHits).toBe(296); + // + // The wave-verifier-gating workflow's Wave 3 Task 1 added the execute + // wave verification gate: +2 hits in commands/goop-execute.md + // (inspect-only role boundary, never-implements-fixes invariant) and + // +1 in references/wiring-checklist.md (handoff never substitutes for + // the recorded gate) — all true invariants, lifting the total from 296 + // to 299. + expect(report.totalAbsoluteHits).toBe(299); }); it("per-file tokens are consistent with chars via estimateTokens", () => { From 1fb7263e74be74b1dfe16aaa5b39e8bafa6259cd Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 11:42:54 -0700 Subject: [PATCH 11/22] docs(plugin): restrict verifier dispatch to acceptance Wave verification is now a distinct goop-wave-verifier dispatch during execute; goop-verifier is acceptance-only across the dispatch-patterns, orchestrator, help, and verifier prompt surfaces. Update agent counts to the 15-role roster and refresh the prompt-audit snapshot. --- AGENTS.md | 4 +- README.md | 15 ++++--- .../agents/goop-orchestrator.md | 4 +- .../opencode-plugin/agents/goop-verifier.md | 4 +- .../opencode-plugin/commands/goop-help.md | 5 ++- .../references/dispatch-patterns.md | 10 +++-- .../src/features/prompt-audit/index.test.ts | 45 +++++++++++++++++-- 7 files changed, 66 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cee2d7c8..9b23c278 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,7 +52,7 @@ packages/opencode-plugin/src/ └── index.ts # Plugin entry point packages/opencode-plugin/ -├── agents/ # 14 agent markdown definitions +├── agents/ # 15 agent markdown definitions ├── commands/ # 9 slash command definitions ├── references/ # 19 consolidated reference documents (incl. field-notes-protocol) └── templates/ # File templates @@ -286,7 +286,7 @@ Defined in `src/core/constants.ts` (lines 140-146): | Role(s) | Default Level | |---------|---------------| | `explorer`, `researcher` | `medium` | -| All other `AGENT_ROLES` (12 roles) | `high` | +| All other `AGENT_ROLES` (13 roles) | `high` | Defaults derive from the canonical `AGENT_ROLES` list, so any new role added to the list automatically gets a safe default. diff --git a/README.md b/README.md index 434e44c5..fed7c30f 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ interview you lock you sign off the spec ``` -Underneath that loop sits a SQLite state engine, 14 specialised agents, 35 tools, a memory system that compounds across projects, and a set of runtime hooks that stop the orchestrator from writing code even when it wants to. +Underneath that loop sits a SQLite state engine, 15 specialised agents, 35 tools, a memory system that compounds across projects, and a set of runtime hooks that stop the orchestrator from writing code even when it wants to. --- @@ -180,7 +180,7 @@ Neither gate can be bypassed. Autopilot doesn't relax them. There is no config f ## Agents and Delegation -One orchestrator, thirteen specialists. The orchestrator coordinates and never implements. +One orchestrator, fourteen specialists. The orchestrator coordinates and never implements. | Agent | What it does | Default model | |-------|--------------|---------------| @@ -194,7 +194,8 @@ One orchestrator, thirteen specialists. The orchestrator coordinates and never i | `goop-executor-frontend-low` | Markup, design tokens, copy, simple styling | `claude-sonnet-4-6` | | `goop-researcher` | Domain research, technology evaluation, synthesis | `claude-sonnet-4-6` | | `goop-explorer` | Codebase mapping, pattern detection, reconnaissance | `claude-sonnet-4-6` | -| `goop-verifier` | Verification against the spec, security audit, trusts nothing | `claude-sonnet-4-6` | +| `goop-wave-verifier` | Per-wave verification during execute; inspect-only, records verification rows | `claude-sonnet-4-6` | +| `goop-verifier` | Acceptance-only verification against the spec, security audit, trusts nothing | `claude-sonnet-4-6` | | `goop-tester` | Test authoring, coverage, edge cases | `claude-sonnet-4-6` | | `goop-debugger` | Hypothesis-driven root cause analysis | `claude-sonnet-4-6` | | `goop-writer` | Documentation and technical writing | `claude-sonnet-4-6` | @@ -525,7 +526,7 @@ Five levels: `none`, `low`, `medium`, `high`, `xhigh`. `none` is a real variant, } ``` -Defaults: `explorer` and `researcher` get `medium`, the other twelve roles get `high`. +Defaults: `explorer` and `researcher` get `medium`, the other thirteen roles get `high`. Resolution walks the V2 catalog first (reading `model.variants[]` for the exact supported id plus the provider request body), falls back to the V1 provider catalog, and finally preserves the provider default. Providers differ (`reasoningEffort`, `reasoning.effort`, `thinking.budgetTokens`, `thinkingConfig`, `reasoningConfig`) and the resolver maps to whichever the target model actually accepts. @@ -556,7 +557,7 @@ Set `GOOPSPEC_GLOBAL_CONFIG_PATH` to relocate the global file. | Key | Type | Default | Does | |-----|------|---------|------| | `projectName` | string | directory name | Name shown in workflow documents and status | -| `defaultModel` | string | unset | Blanket model for all 14 roles, below per-role overrides | +| `defaultModel` | string | unset | Blanket model for all 15 roles, below per-role overrides | | `enforcement` | `assist` / `warn` / `strict` | unset | How hard phase rules are applied | | `adlEnabled` | boolean | unset | Decision log tracking | | `memoryEnabled` | boolean | `true` | In-process memory | @@ -663,7 +664,7 @@ Thirteen hook factories run the enforcement that prompts alone can't guarantee. | Hook | Binds to | Does | |------|----------|------| -| Agent registration | `config`, `chat.params` | Injects 14 agents and 9 commands; applies model and thinking overrides | +| Agent registration | `config`, `chat.params` | Injects 15 agents and 9 commands; applies model and thinking overrides | | System transform | `experimental.chat.system.transform` | Injects state, phase rules, document inventory, memory, and field notes | | Chat message | `chat.message` | Tracks activity, clears stale checkpoints, distils significant prompts to memory | | Comment checker | `tool.execute.*` | Flags excessive comment ratios and low-value comments on writes | @@ -762,7 +763,7 @@ Current suite: **1956 tests, 5140 assertions, 109 files, roughly 13 seconds.** ``` packages/opencode-plugin/ -├── agents/ # 14 agent definitions +├── agents/ # 15 agent definitions ├── commands/ # 9 slash commands ├── references/ # 19 reference documents ├── templates/ # 12 document templates diff --git a/packages/opencode-plugin/agents/goop-orchestrator.md b/packages/opencode-plugin/agents/goop-orchestrator.md index 4340e9d1..1397e2a5 100644 --- a/packages/opencode-plugin/agents/goop-orchestrator.md +++ b/packages/opencode-plugin/agents/goop-orchestrator.md @@ -73,7 +73,9 @@ discuss -> plan -> execute -> accept -> confirm Default to `goop-executor-medium` / `goop-executor-frontend-medium` for standard implementation work — scope, consequence, and blast radius are signals to double-check the tier choice, not reasons to skip past medium. Escalate to the `-high` tiers for architecture-, security-, or blast-radius-sensitive work; use the `-low` tiers for purely mechanical, pattern-following work. -All six tiers — `goop-executor-low`, `goop-executor-medium`, `goop-executor-high`, `goop-executor-frontend-low`, `goop-executor-frontend-medium`, `goop-executor-frontend-high` — are reachable via `task()`, alongside `goop-researcher`, `goop-explorer`, `goop-verifier`, `goop-tester`, `goop-writer`, and `goop-debugger`. See `references/dispatch-patterns.md` §Agent Selection for the full task-type/complexity tables, context budgets, and delegation-prompt structure. +All six tiers — `goop-executor-low`, `goop-executor-medium`, `goop-executor-high`, `goop-executor-frontend-low`, `goop-executor-frontend-medium`, `goop-executor-frontend-high` — are reachable via `task()`, alongside `goop-researcher`, `goop-explorer`, `goop-wave-verifier`, `goop-verifier`, `goop-tester`, `goop-writer`, and `goop-debugger`. See `references/dispatch-patterns.md` §Agent Selection for the full task-type/complexity tables, context budgets, and delegation-prompt structure. + +Wave verification and the acceptance audit are separate dispatches with separate stages. During execute, at wave completion, dispatch `goop-wave-verifier` scoped to that wave — it records verification rows and reports gaps; it never implements fixes (see `commands/goop-execute.md` §Steps for the wave verification gate). At accept, dispatch `goop-verifier` for the final acceptance audit — it is acceptance-only and does not run during execute (see `commands/goop-accept.md` §Steps). ## Auto-Delegation diff --git a/packages/opencode-plugin/agents/goop-verifier.md b/packages/opencode-plugin/agents/goop-verifier.md index 38fe831a..9e6aacfd 100644 --- a/packages/opencode-plugin/agents/goop-verifier.md +++ b/packages/opencode-plugin/agents/goop-verifier.md @@ -30,12 +30,13 @@ permission: # GoopSpec Verifier -You are the **Auditor**. You verify reality against the locked contract. You do not trust claims, summaries, or intent — evidence. Security is non-negotiable. +You are the **Auditor**. You verify reality against the locked contract at the acceptance gate only. You do not trust claims, summaries, or intent — evidence. Security is non-negotiable. **Identity:** You are a dispatched subagent (NOT the Conductor). See `references/subagent-identity.md`. ## What You Do +- Verify at the acceptance gate. Execute-phase wave checks are `goop-wave-verifier`'s job — see `agents/goop-wave-verifier.md`. - Read spec and chronicle via `goop_read_db({ doc_types: ["spec", "chronicle"] })`, and read wave/task context plus verification/traceability via `goop_acceptance_audit` or `goop_read_wave`. - Inspect actual code, tests, and commits. - Prefer `difftastic` to distinguish substantive changes from cosmetic ones and `ast_grep` for structural evidence, rather than eyeballing `grep` output. @@ -46,6 +47,7 @@ You are the **Auditor**. You verify reality against the locked contract. You do ## What You Do NOT Do - Write or edit files. Verifiers report; they do not fix. +- Run as a wave verifier during execute — `goop-wave-verifier` owns wave-scoped checks; you are acceptance-only. - Skip security checks because a feature is internal or small. - Mark anything passed without reproducible evidence. - Trust `SUMMARY.md`, commit messages, or agent self-reports as proof. diff --git a/packages/opencode-plugin/commands/goop-help.md b/packages/opencode-plugin/commands/goop-help.md index 9137de7d..008534b2 100644 --- a/packages/opencode-plugin/commands/goop-help.md +++ b/packages/opencode-plugin/commands/goop-help.md @@ -31,7 +31,7 @@ See `references/core-protocol.md` §Five-Phase Workflow for the full phase table ## Agents -The orchestrator delegates to 13 specialized agents: +One orchestrator, fourteen specialists. The orchestrator delegates and never implements. - `goop-orchestrator` — workflow conductor. - `goop-planner` — spec and blueprint authoring. @@ -43,7 +43,8 @@ The orchestrator delegates to 13 specialized agents: - `goop-executor-frontend-high` — deep design or UI-architecture work; use when genuinely warranted. - `goop-researcher` — domain and technology research. - `goop-explorer` — codebase mapping. -- `goop-verifier` — spec compliance and security audit. +- `goop-wave-verifier` — per-wave verification during execute; scoped to one wave, inspect/report-only, never implements fixes. +- `goop-verifier` — acceptance-only; spec compliance and security audit at the accept gate. - `goop-tester` — tests and QA. - `goop-debugger` — scientific debugging. - `goop-writer` — documentation. diff --git a/packages/opencode-plugin/references/dispatch-patterns.md b/packages/opencode-plugin/references/dispatch-patterns.md index 090db20d..5cedae03 100644 --- a/packages/opencode-plugin/references/dispatch-patterns.md +++ b/packages/opencode-plugin/references/dispatch-patterns.md @@ -72,8 +72,9 @@ Do not pass full conversation history, verbose logs, unrelated files, or complet | Deep UI design / UI architecture | `goop-executor-frontend-high` | — | | Research | `goop-researcher` | `goop-explorer` | | Exploration | `goop-explorer` | — | -| Verification | `goop-verifier` | `goop-tester` | -| Testing | `goop-tester` | `goop-verifier` | +| Wave verification (execute) | `goop-wave-verifier` | — | +| Acceptance verification (accept) | `goop-verifier` | `goop-tester` | +| Testing | `goop-tester` | — | | Debugging | `goop-debugger` | `goop-executor-high` | | Documentation | `goop-writer` | orchestrator | @@ -169,7 +170,8 @@ Default model assignments optimize cost and quality per task. | `goop-executor-frontend-high` | quality reasoning | Design-sensitive UI, component architecture | | `goop-researcher` | broad knowledge | Deep research, synthesis | | `goop-explorer` | fast lightweight | Codebase mapping, pattern detection | -| `goop-verifier` | strong code | Spec compliance, security audit | +| `goop-wave-verifier` | strong code | Wave-scoped execute verification, evidence rows | +| `goop-verifier` | strong code | Acceptance-gate spec compliance, security audit | | `goop-tester` | cost-effective code | Test writing, QA | | `goop-debugger` | strong code | Hypothesis testing, root cause | | `goop-writer` | strong writing | Documentation, structured writing | @@ -179,7 +181,7 @@ Users can override models in `goopspec.json` under `models`. ## Verification Dispatch -Use `goop-verifier` at acceptance gates and after high-risk changes. At the accept gate, prefer [`goop_acceptance_audit`](tool-reference.md) — it replaces the 3-call blocker+verification+wave-read sequence with a single read-only call returning combined `{blockers, verifications, waves}`. A verification report should check: +Wave verification during execute is a `goop-wave-verifier` job, scoped to one wave at a time (see `agents/goop-wave-verifier.md`). `goop-verifier` is acceptance-only: it runs at the accept gate and at no other stage. At the accept gate, prefer [`goop_acceptance_audit`](tool-reference.md) — it replaces the 3-call blocker+verification+wave-read sequence with a single read-only call returning combined `{blockers, verifications, waves}`. A verification report should check: | Area | What to Confirm | |------|-----------------| diff --git a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts index 3c05ec4f..ca89c49c 100644 --- a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts +++ b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts @@ -172,9 +172,18 @@ describe("auditPromptSurfaces (real tree)", () => { // absolute-language hits unchanged. The immutable Wave 1 baseline // (99,822 bytes, 14 files) remains in RESEARCH.md and predates both // this addition and the Wave 3/4 consolidation passes. + // + // The wave-verifier-gating workflow's Wave 3 Task 2 split the two + // verifier roles across the delegation surface: agents/goop-orchestrator.md + // gained goop-wave-verifier in the task()-reachable list plus a + // stage-bound verification-dispatch paragraph (+514 bytes, +2 abs), and + // agents/goop-verifier.md now states acceptance-only with a + // cross-reference to goop-wave-verifier (+273 bytes, +2 abs). Net: + // 82,324 -> 83,111 bytes, absolute hits 66 -> 70, bold spans unchanged + // at 137. const agents = report.directories.find((d) => d.directory === "agents")!; expect(agents.files).toBe(15); - expect(agents.bytes).toBe(82_324); + expect(agents.bytes).toBe(83_111); expect(agents.boldSpans).toBe(137); }); @@ -196,9 +205,18 @@ describe("auditPromptSurfaces (real tree)", () => { // 32 -> 34 (+2: the gate's "inspect-only" role boundary and the // "never implements fixes" verifier invariant — both true role // invariants per dispatch-patterns.md). + // + // The wave-verifier-gating workflow's Wave 3 Task 2 corrected the agent + // roster in goop-help.md: 13 -> 14 specialized agents (the canonical + // 15-role roster minus the orchestrator), added goop-wave-verifier with + // a stage boundary, and made goop-verifier acceptance-only. Net: + // 25,890 -> 26,092 bytes (+202), absolute hits 34 -> 38 (+4: the + // "never implements fixes" role invariant, the "acceptance-only" scope, + // the "inspect/report-only" boundary, and the "never implements" + // delegate statement). const commands = report.directories.find((d) => d.directory === "commands")!; expect(commands.files).toBe(9); - expect(commands.bytes).toBe(25_890); + expect(commands.bytes).toBe(26_092); }); it("references: 19 files, 161,350 bytes", () => { @@ -254,9 +272,18 @@ describe("auditPromptSurfaces (real tree)", () => { // task-decomposition's update-wave section and anti-pattern now cite the // runtime predicate isWaveVerified. Net effect: 161,350 -> 162,326 bytes // (+976), absolute hits 198 -> 199 (+1), bold spans 530 -> 532. + // + // The wave-verifier-gating workflow's Wave 3 Task 2 made goop-verifier + // acceptance-only in dispatch-patterns.md: the selection table gained a + // Wave-verification (execute) row pointing at goop-wave-verifier and + // dropped goop-verifier as the testing fallback, the model-profile table + // gained goop-wave-verifier, and the Verification Dispatch section + // removed the "after high-risk changes" guidance. Net: 162,326 -> + // 162,648 bytes (+322), absolute hits 199 -> 200 (+1: "acceptance-only"), + // bold spans unchanged at 532. const references = report.directories.find((d) => d.directory === "references")!; expect(references.files).toBe(19); - expect(references.bytes).toBe(162_326); + expect(references.bytes).toBe(162_648); }); it("total absolute-language hits are 299 (Wave 1 role plumbing plus the Wave 3 execution gate)", () => { @@ -330,7 +357,17 @@ describe("auditPromptSurfaces (real tree)", () => { // +1 in references/wiring-checklist.md (handoff never substitutes for // the recorded gate) — all true invariants, lifting the total from 296 // to 299. - expect(report.totalAbsoluteHits).toBe(299); + // + // The wave-verifier-gating workflow's Wave 3 Task 2 (doc restriction + // sweep) added the two-verifier stage boundary across the delegation + // surfaces: +1 in references/dispatch-patterns.md (acceptance-only), + // +2 in agents/goop-orchestrator.md (never-implements-fixes role + // invariant, acceptance-only), +2 in agents/goop-verifier.md + // (acceptance-gate-only scope, acceptance-only), +4 in commands/ + // goop-help.md (never-implements-fixes role invariant, acceptance-only, + // inspect/report-only boundary, delegate-never statement) — lifting the + // total from 299 to 308. + expect(report.totalAbsoluteHits).toBe(308); }); it("per-file tokens are consistent with chars via estimateTokens", () => { From 7034aaff1134980486058bb535c3fbbec31e3cc4 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 11:51:31 -0700 Subject: [PATCH 12/22] test(plugin): prove remediation loop and unblock lazy-autopilot verification turns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wave 3 Task 3 (MH3/MH7/MH8). Adds end-to-end integration coverage for the wave-verification remediation loop and fixes a lazy-autopilot stall across verification-only turns. MATERIAL DEVIATION surfaced to ADL: MH3's literal 'fail row → remediation → later passing evidence → wave completion succeeds' is impossible under locked Wave 2 D2 (verifier-stage.ts:104-107; insert-only rows; gate predicate rejects any wave with a historical fail). The integration scenarios model the supported auditable mechanisms instead: - Happy path: pass row recorded in the completion call (or earlier with no fail row present) → wave completion succeeds → auto-progression fires execute → accept. - Gate enforcement: fail row blocks completion; a later pass row does NOT unblock (locked D2 pinned end-to-end); the supported terminal state per goop-execute.md:50 is to open a high-severity blocker via goop_blocker, which the lazy-autopilot G_high-severity-blocker guard observes and uses to suppress further nudges. Lazy-autopilot fingerprint fix (rate-limit.ts): the progress fingerprint previously digested only phase|currentWave|task-status-digest. A verification-only turn (wave-verifier records evidence without changing any task status) left the fingerprint identical, so the consecutive counter did not reset and the session was eventually abandoned despite real forward motion. Added a verification-row digest slot (|v:) ordered by insertion, so a verification-only turn moves the fingerprint and resets the counter. Does not weaken the Wave 2 completion or stage-dispatch gates. Existing fail-closed session/project guards, cooldown, cap, and V1-only behavior preserved. --- .../lazy-autopilot-nudge/rate-limit.test.ts | 103 +++++++ .../hooks/lazy-autopilot-nudge/rate-limit.ts | 38 ++- .../opencode-plugin/src/integration.test.ts | 279 ++++++++++++++++++ 3 files changed, 413 insertions(+), 7 deletions(-) diff --git a/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts b/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts index 26f76cf1..b595662b 100644 --- a/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts +++ b/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts @@ -215,6 +215,109 @@ describe("lazy autopilot nudge rate-limit", () => { expect(after).not.toBe(before); }); + // ------------------------------------------------------------------------- + // T3 / MH7 / MH8: A verification-only turn must move the fingerprint. + // The orchestrator dispatches goop-wave-verifier after every wave's tasks + // are complete (commands/goop-execute.md). The verifier records evidence + // via goop_write_wave verifications[]; task statuses do not change. Without + // verification rows in the digest, the nudge's progress fingerprint would + // be identical before and after that turn, so the consecutive counter + // would not reset and the session would eventually be abandoned even + // though real evidence landed. These tests pin the fix. + // ------------------------------------------------------------------------- + + it("builds a fingerprint that ends with the verification digest slot", () => { + const fp = buildNudgeFingerprint( + baseCtx, + "default", + baseCtx.stateManager.getActiveWorkflow(), + ); + // No verification rows seeded in beforeEach -> slot is "none". + expect(fp).toMatch(/\|v:none$/); + }); + + it("changes fingerprint when a verification row is recorded without any task-status change", () => { + const before = buildNudgeFingerprint( + baseCtx, + "default", + baseCtx.stateManager.getActiveWorkflow(), + ); + const waveId = baseCtx.db.getWave("default", 3)?.id ?? 1; + baseCtx.db.insertVerification("default", { + wave_id: waveId, + check_name: "test", + status: "passed", + }); + const after = buildNudgeFingerprint( + baseCtx, + "default", + baseCtx.stateManager.getActiveWorkflow(), + ); + expect(after).not.toBe(before); + expect(after).toMatch(/\|v:test:passed$/); + }); + + it("changes fingerprint when a second verification row lands (insertion order preserved)", () => { + const waveId = baseCtx.db.getWave("default", 3)?.id ?? 1; + baseCtx.db.insertVerification("default", { + wave_id: waveId, + check_name: "typecheck", + status: "passed", + }); + const before = buildNudgeFingerprint( + baseCtx, + "default", + baseCtx.stateManager.getActiveWorkflow(), + ); + baseCtx.db.insertVerification("default", { + wave_id: waveId, + check_name: "test", + status: "passed", + }); + const after = buildNudgeFingerprint( + baseCtx, + "default", + baseCtx.stateManager.getActiveWorkflow(), + ); + expect(after).not.toBe(before); + // Insertion order: typecheck landed first, then test. getVerifications + // returns newest-first, so the digest reverses to insertion order. + expect(after).toMatch(/\|v:typecheck:passed,test:passed$/); + }); + + it("a verification-only turn resets the consecutive nudge counter (regression for the stall)", () => { + const check = createNudgeRateLimitCheck(baseCtx, cfg({ cap: 2 })).check; + const sess = "sess-verify-reset"; + + expect(check(baseCtx, sess).allowed).toBe(true); + recordNudge(baseCtx, sess, "default"); + expect(__getNudgeRateLimitState(sess)?.count).toBe(1); + + advanceTime(2_000); + + // Same fingerprint, second nudge — counter climbs toward the cap. + expect(check(baseCtx, sess).allowed).toBe(true); + recordNudge(baseCtx, sess, "default"); + expect(__getNudgeRateLimitState(sess)?.count).toBe(2); + + advanceTime(4_000); + + // Without the fix, a third check at the same fingerprint would be + // abandoned (count >= cap). A verification-only turn moves the + // fingerprint, so the counter resets and the session gets a fresh + // budget instead of being abandoned. + const waveId = baseCtx.db.getWave("default", 3)?.id ?? 1; + baseCtx.db.insertVerification("default", { + wave_id: waveId, + check_name: "test", + status: "passed", + }); + + const after = check(baseCtx, sess); + expect(after.allowed).toBe(true); + expect(__getNudgeRateLimitState(sess)?.count).toBe(0); + }); + it("kill switch produces zero SDK calls", () => { const check = createNudgeRateLimitCheck(baseCtx, cfg({ enabled: false })).check; const promptAsync = mock(async () => undefined); diff --git a/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.ts b/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.ts index 3f71b316..b8e8d4d2 100644 --- a/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.ts +++ b/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.ts @@ -98,10 +98,20 @@ export function __getNudgeRateLimitState( /** * Build a progress fingerprint for the active workflow. * - * Exact composition: `||`. - * The task-status digest is a comma-separated list of `task_index:status` - * for every task in the current wave, ordered by task_index. If no wave - * row or tasks exist, the digest is `none`. + * Exact composition: `|||v:`. + * + * - The task-status digest is a comma-separated list of `task_index:status` + * for every task in the current wave, ordered by task_index. If no wave + * row or tasks exist, the digest is `none`. + * - The verification digest is a comma-separated list of + * `check_name:status` rows attached to the current wave, ordered by row + * id ascending so the order in which rows were inserted is preserved. + * If no wave row or no verification rows exist, the digest is `none`. + * + * The verification digest matters because a wave-verifier turn can record + * evidence without changing any task status — without it, that turn would + * look identical to a no-op idle and the consecutive counter would not + * reset, eventually abandoning the session despite real forward motion. * * The consecutive counter resets only when this fingerprint changes, so * idle -> nudge -> idle with no real progress counts as a repeat, not a @@ -116,19 +126,33 @@ export function buildNudgeFingerprint( const currentWave = workflow.currentWave; const waveRow = ctx.db.getWave(workflowId, currentWave); - let digest = "none"; + let taskDigest = "none"; + let verificationDigest = "none"; if (waveRow != null) { const tasks = ctx.db.getWaveTasks(waveRow.id); if (tasks.length > 0) { - digest = tasks + taskDigest = tasks .slice() .sort((a, b) => a.task_index - b.task_index) .map((t) => `${t.task_index}:${t.status}`) .join(","); } + + // Order by id ascending so the digest captures insertion order, which + // is the auditable record of how verification evidence accumulated. + // getVerifications returns rows newest-first (created_at DESC, id DESC), + // so reverse to get insertion order. + const verifications = ctx.db.getVerifications(workflowId, waveRow.id); + if (verifications.length > 0) { + verificationDigest = verifications + .slice() + .reverse() + .map((v) => `${v.check_name}:${v.status}`) + .join(","); + } } - return `${phase}|${currentWave}|${digest}`; + return `${phase}|${currentWave}|${taskDigest}|v:${verificationDigest}`; } // --------------------------------------------------------------------------- diff --git a/packages/opencode-plugin/src/integration.test.ts b/packages/opencode-plugin/src/integration.test.ts index b13e258b..7d1a2701 100644 --- a/packages/opencode-plugin/src/integration.test.ts +++ b/packages/opencode-plugin/src/integration.test.ts @@ -34,6 +34,7 @@ import { createAutoProgressionHook } from "./hooks/auto-progression.js"; import { IDLE_COMPACTION_DEFER_MS, createEventHandlerHook } from "./hooks/event-handler.js"; import { createHooks } from "./hooks/index.js"; import { dispatchLazyAutopilotNudge } from "./hooks/lazy-autopilot-nudge/index.js"; +import { __clearNudgeRateLimitState, buildNudgeFingerprint } from "./hooks/lazy-autopilot-nudge/rate-limit.js"; import { createDefaultWorkflowState, createMockCompactionHandoff, @@ -843,4 +844,282 @@ describe("GoopSpec 5-phase integration", () => { expect(completedOutput.output).toContain("3/3 tasks complete"); }); }); + + // ======================================================================== + // 11. Wave-verification remediation loop (W3.T3 / MH3 / MH7 / MH8) + // + // Proves the bounded fail → remediate → pass → complete path and that + // lazy autopilot keeps moving across a verification-only turn. + // + // MATERIAL DEVIATION from MH3's literal wording (logged to ADL): + // Wave 2 D2 made verification rows insert-only and the gate predicate + // `isWaveVerified = rows.length >= 1 AND zero failing rows` (locked in + // src/features/enforcement/verifier-stage.ts and pinned by + // auto-progression.test.ts:463). A wave row with a historical fail + // therefore CANNOT be unblocked by inserting a later pass row — the + // gate is permanent for that wave. The integration scenarios below + // model the supported auditable mechanisms instead of silently + // weakening D2: the happy path (no fail row) completes and progresses; + // the gate-enforcement path proves a fail row blocks completion, a + // later pass row does NOT unblock it, and the orchestrator's recourse + // is to open a high-severity blocker (which the lazy-autopilot guard + // observes and suppresses). + // ======================================================================== + + describe("wave-verification remediation loop", () => { + function makeExecuteCtx() { + return createMockPluginContext({ + testDir, + state: { + activeWorkflowId: "default", + workflows: { + default: createDefaultWorkflowState({ + phase: "execute", + currentWave: 2, + totalWaves: 2, + specLocked: true, + lazyAutopilot: true, + }), + }, + }, + }); + } + + // Scenario A — supported happy path: the verifier records a pass row, + // then the orchestrator marks the wave complete and progression fires. + it("supported happy path: pass row recorded → wave completion succeeds → progression allowed", async () => { + const ctx = makeExecuteCtx(); + const tools = createTools(ctx); + const writeWave = tools.goop_write_wave; + const toolContext = createMockToolContext(); + + // Wave 2 (final) exists with two tasks, one still in progress. + await writeWave.execute( + { + wave_number: 2, + title: "Final wave", + status: "in_progress", + tasks: [ + { task_index: 1, description: "First", status: "complete" }, + { task_index: 2, description: "Second", status: "in_progress" }, + ], + }, + toolContext, + ); + + // Verification-only turn: the verifier records a pass row while the + // second task is still in progress. No task-status change. + await writeWave.execute( + { + wave_number: 2, + verifications: [{ check_name: "test", status: "pass", detail: "scoped run" }], + }, + toolContext, + ); + + // Remediation represented: the executor finishes the second task. + await writeWave.execute( + { wave_number: 2, task_updates: [{ task_index: 2, status: "complete" }] }, + toolContext, + ); + + // Wave completion succeeds because the gate reads the prior pass row + // and finds zero failing rows. + const completion = await writeWave.execute( + { wave_number: 2, status: "completed" }, + toolContext, + ); + expect(completion).toContain("Written wave 2"); + expect(ctx.db.getWave("default", 2)?.status).toBe("completed"); + + // Auto-progression fires and transitions execute → accept because + // the final wave is complete and the verification gate is satisfied. + const autoProgression = createAutoProgressionHook(ctx)["tool.execute.after"]; + const output = { title: "result", output: "ok", metadata: {} }; + await autoProgression?.( + { tool: "goop_write_wave", sessionID: "orchestrator", callID: "complete", args: {} }, + output, + ); + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + expect(output.output).toContain("2/2 tasks complete"); + }); + + // Scenario B — gate enforcement with a fail row: proves the locked D2 + // behavior is honored end-to-end. A fail row blocks completion; a later + // pass row does NOT unblock it; the supported terminal state is to open + // a high-severity blocker, which the lazy-autopilot guard observes and + // uses to suppress further nudges. + it("locked D2 enforced: fail row blocks completion; later pass row does NOT unblock; blocker suppresses nudge", async () => { + const ctx = makeExecuteCtx(); + const tools = createTools(ctx); + const writeWave = tools.goop_write_wave; + const blocker = tools.goop_blocker; + const toolContext = createMockToolContext(); + __clearNudgeRateLimitState(); + + // Wave exists with both tasks complete but a failing verification row. + await writeWave.execute( + { + wave_number: 2, + title: "Failing final wave", + status: "in_progress", + tasks: [ + { task_index: 1, description: "First", status: "complete" }, + { task_index: 2, description: "Second", status: "complete" }, + ], + verifications: [{ check_name: "test", status: "fail", detail: "regression: 2 failing" }], + }, + toolContext, + ); + + // 1. Completion is BLOCKED by the gate (zero-pass / one-fail row). + const blockedCompletion = await writeWave.execute( + { wave_number: 2, status: "completed" }, + toolContext, + ); + expect(blockedCompletion).toContain("Error in goop_write_wave"); + expect(blockedCompletion).toContain("cannot be marked complete"); + expect(blockedCompletion).toContain("goop-wave-verifier"); + expect(ctx.db.getWave("default", 2)?.status).toBe("in_progress"); + + // 2. Remediation phase represented: the orchestrator dispatches an + // executor to fix the gap, then re-dispatches the wave verifier. + // Per W3.T1 docs this is the documented loop. Per W2 D2 (locked), + // inserting a later pass row cannot unblock the wave — the gate + // reads ALL rows and rejects any wave with a historical fail. + const remediationRow = await writeWave.execute( + { + wave_number: 2, + verifications: [{ check_name: "test", status: "pass", detail: "post-fix recheck" }], + }, + toolContext, + ); + expect(remediationRow).toContain("Verifications:"); + expect(remediationRow).toContain("test=pass"); + + // 3. Re-attempted completion is STILL BLOCKED — this is the locked + // D2 behavior. The test pins it so a future change cannot silently + // weaken the gate. + const stillBlocked = await writeWave.execute( + { wave_number: 2, status: "completed" }, + toolContext, + ); + expect(stillBlocked).toContain("Error in goop_write_wave"); + expect(stillBlocked).toContain("cannot be marked complete"); + expect(ctx.db.getWave("default", 2)?.status).toBe("in_progress"); + + // 4. Because the wave never reaches a complete status, the + // auto-progression hook returns early at its isCompleteStatus + // guard and the phase stays execute. The hook's secondary + // "Blocked: execute → accept" defense is pinned directly by + // auto-progression.test.ts:401 (seeding a complete wave with a + // failing row); the integration assertion here is the + // higher-level guarantee: the phase cannot advance while the + // gate is unsatisfied. + const autoProgression = createAutoProgressionHook(ctx)["tool.execute.after"]; + const apOutput = { title: "result", output: "ok", metadata: {} }; + await autoProgression?.( + { tool: "goop_write_wave", sessionID: "orchestrator", callID: "any", args: {} }, + apOutput, + ); + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); + + // 5. Supported terminal state per commands/goop-execute.md:50 + // (three-strikes): open a high-severity blocker and stop. + const blockerResult = await blocker.execute( + { + action: "open", + description: + "Wave 2 verification gate cannot be satisfied: a failing row is permanently in the row set (D2 insert-only). Operator must force-complete or reset the wave.", + severity: "high", + }, + toolContext, + ); + expect(blockerResult).toContain("Opened blocker #"); + + // 6. The lazy-autopilot guard observes the open high-severity blocker + // and suppresses the nudge — the orchestrator is not pestered while + // a blocker is outstanding. + const promptAsync = mock(async () => undefined); + Object.assign(ctx.sdk.client, { + session: { + messages: mock(async () => [{ info: { role: "assistant", mode: "goop-orchestrator" } }]), + get: mock(async () => ({ directory: testDir })), + promptAsync, + }, + }); + + await dispatchLazyAutopilotNudge(ctx, "sess-blocked-by-blocker"); + await Promise.resolve(); + + expect(promptAsync).not.toHaveBeenCalled(); + expect(ctx.pendingLazyAutopilotNudges.has("sess-blocked-by-blocker")).toBe(false); + }); + + // Scenario C — verification-only turn yields forward motion in the + // lazy-autopilot progress fingerprint (MH7/MH8). Without the fix in + // rate-limit.ts, a verification-only turn left the fingerprint + // identical and the consecutive counter did not reset, eventually + // abandoning the session despite real evidence of progress. + it("a verification-only turn moves the lazy-autopilot progress fingerprint (no stall)", async () => { + const ctx = makeExecuteCtx(); + const tools = createTools(ctx); + const writeWave = tools.goop_write_wave; + const toolContext = createMockToolContext(); + + await writeWave.execute( + { + wave_number: 2, + title: "Verification turn wave", + status: "in_progress", + tasks: [{ task_index: 1, description: "Only task", status: "in_progress" }], + }, + toolContext, + ); + + const beforeFingerprint = buildNudgeFingerprint( + ctx, + "default", + ctx.stateManager.getActiveWorkflow(), + ); + expect(beforeFingerprint).toMatch(/\|v:none$/); + + // Verification-only turn — no task-status change. + await writeWave.execute( + { + wave_number: 2, + verifications: [{ check_name: "test", status: "pass", detail: "first evidence" }], + }, + toolContext, + ); + + const afterFingerprint = buildNudgeFingerprint( + ctx, + "default", + ctx.stateManager.getActiveWorkflow(), + ); + expect(afterFingerprint).not.toBe(beforeFingerprint); + expect(afterFingerprint).toMatch(/\|v:test:passed$/); + + // A second verification-only turn (the verifier records more evidence + // for the same wave) must also move the fingerprint — otherwise the + // nudge would treat the second evidence turn as a no-op repeat. + await writeWave.execute( + { + wave_number: 2, + verifications: [{ check_name: "typecheck", status: "pass", detail: "no type errors" }], + }, + toolContext, + ); + + const afterSecondFingerprint = buildNudgeFingerprint( + ctx, + "default", + ctx.stateManager.getActiveWorkflow(), + ); + expect(afterSecondFingerprint).not.toBe(afterFingerprint); + // Insertion order preserved: test landed first, then typecheck. + expect(afterSecondFingerprint).toMatch(/\|v:test:passed,typecheck:passed$/); + }); + }); }); From 0da0a7acdae0b260520623c33b80882c5b5e6343 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:04:08 -0700 Subject: [PATCH 13/22] fix(plugin): evaluate wave verification gate per latest check_name Reconciles MH3's bounded remediation loop with the W2 D2 append-only verification-row invariant. Rows are never deleted or updated, but isWaveVerified now computes the effective status per check_name as the latest (highest-id) row for that check rather than "zero failed rows across all history ever". A later pass/skip for the SAME check supersedes that check's own prior fail; a pass for a DIFFERENT check never resolves another check's unresolved fail. The predicate sorts by row id itself, so it stays correct regardless of caller ordering. - verifier-stage.ts: VerifiedRowLike gains id/check_name; isWaveVerified reduces to latest-per-check before checking for a failing status. - verifier-stage.test.ts: adds latest-per-check coverage (same-check supersession, different-check non-supersession, order independence). - auto-progression.test.ts, goop-write-wave/index.test.ts: replace the "later pass never unblocks" fixtures with same-check-unblocks / different-check-stays-blocked pairs. - integration.test.ts: replaces the permanent-fail Scenario B with the literal fail -> remediate -> same-check pass -> complete -> progress story, and adds Scenario B2 for the different-check block + blocker + lazy-autopilot-nudge-suppression path. - goop-execute.md, goop-wave-verifier.md: correct prose that pinned the superseded "any historical fail blocks forever" reading. - prompt-audit/index.test.ts: mechanically re-measured byte/abs-hit snapshots for the two reworded docs. Full plugin suite: 2511 pass / 0 fail. Typecheck clean. Biome: no new issues (pre-existing tabs-vs-spaces and organizeImports/format items unchanged). --- .../agents/goop-wave-verifier.md | 2 +- .../opencode-plugin/commands/goop-execute.md | 2 +- .../enforcement/verifier-stage.test.ts | 101 ++++++++++-- .../features/enforcement/verifier-stage.ts | 30 +++- .../src/features/prompt-audit/index.test.ts | 32 +++- .../src/hooks/auto-progression.test.ts | 31 +++- .../opencode-plugin/src/integration.test.ts | 144 ++++++++++++------ .../src/tools/goop-write-wave/index.test.ts | 61 +++++++- 8 files changed, 329 insertions(+), 74 deletions(-) diff --git a/packages/opencode-plugin/agents/goop-wave-verifier.md b/packages/opencode-plugin/agents/goop-wave-verifier.md index 8eb0cbc3..5da2c4a3 100644 --- a/packages/opencode-plugin/agents/goop-wave-verifier.md +++ b/packages/opencode-plugin/agents/goop-wave-verifier.md @@ -46,7 +46,7 @@ You are scoped to a single wave. Before any inspection: - **Execution:** scoped test or typecheck output (use `bash` with the narrowest covering rung; see `references/test-authoring.md` §Test Execution Discipline). - **Commit:** commit hash or chronicle entry covering the task. - Use `difftastic` to distinguish substantive changes from cosmetic ones when comparing against the contract. -- Record every finding as a verification row via `goop_write_wave({ wave_number: , verifications: [{ check_name, status, detail }] })`. Use `status: "skip"` only as a deliberate, justified escape — never to hide a gap. +- Record every finding as a verification row via `goop_write_wave({ wave_number: , verifications: [{ check_name, status, detail }] })`. Use `status: "skip"` only as a deliberate, justified escape — never to hide a gap. Verification rows persist forever: re-verifying a check records a new row instead of replacing the old one, and the wave gate reads each check's latest row — so re-checking `test` with the same `check_name` is exactly how a remediated failure clears the gate. - Log deviations to `ADL.md` via `goop_adl`. - Return only the format defined in `references/response-format.md`. diff --git a/packages/opencode-plugin/commands/goop-execute.md b/packages/opencode-plugin/commands/goop-execute.md index 4c8a4d38..1483e733 100644 --- a/packages/opencode-plugin/commands/goop-execute.md +++ b/packages/opencode-plugin/commands/goop-execute.md @@ -48,7 +48,7 @@ goop_reference({ name: "core-protocol" }) - The verifier records a verification row per task via `goop_write_wave({ wave_number: N, verifications: [...] })` and never implements fixes. - On gaps: dispatch the correctly tiered executor to remediate, then re-dispatch `goop-wave-verifier` for that wave to re-verify the remediated tasks. - Bound the remediation cycle with the three-strikes convention in `references/test-authoring.md` §Test Execution Discipline: after three failed attempts on the same gap, open a blocker via `goop_blocker` and stop; do not loop. - - The wave is complete when its rows satisfy the runtime gate — at least one verification row and zero `fail` rows; an explicit `skip` row is a deliberate, auditable escape (`isWaveVerified` in `src/features/enforcement/verifier-stage.ts`). The runtime enforces the boundary: `goop_write_wave` rejects a complete-status transition without it. + - The wave is complete when its rows satisfy the runtime gate: verification rows persist forever (never deleted or edited), and the gate reads the *latest* row per `check_name` — at least one check present, and every check's latest row non-`fail`. A later `pass` or explicit `skip` for the same check supersedes that check's own prior `fail`; it does not resolve a different check's unresolved fail (`isWaveVerified` in `src/features/enforcement/verifier-stage.ts`). The runtime enforces the boundary: `goop_write_wave` rejects a complete-status transition without it. 6. If Atomic PRs = Yes: after the wave verification gate passes, open a PR for the verified wave against the previous branch (Wave N → Wave N-1; Wave 1 → main) via `gh pr create` or `goop_create_pr`. Do not wait for it to merge. Then create the Wave N+1 branch from the current wave's branch and continue. Show the PR URL in the checkpoint. 7. Save a checkpoint at wave boundaries. diff --git a/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts b/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts index 78127bac..fac42c01 100644 --- a/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts +++ b/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts @@ -122,8 +122,13 @@ describe("verification status mapping", () => { // isWaveVerified // --------------------------------------------------------------------------- -function row(status: VerifiedRowLike["status"]): VerifiedRowLike { - return { status }; +let nextId = 1; +function row( + status: VerifiedRowLike["status"], + check_name = "test", + id?: number, +): VerifiedRowLike { + return { id: id ?? nextId++, check_name, status }; } describe("isWaveVerified", () => { @@ -143,30 +148,98 @@ describe("isWaveVerified", () => { expect(isWaveVerified([row("skipped")])).toBe(true); }); - it("is true for multiple passed rows", () => { - expect(isWaveVerified([row("passed"), row("passed")])).toBe(true); + it("is true for multiple passed rows across different checks", () => { + expect( + isWaveVerified([row("passed", "test"), row("passed", "typecheck")]), + ).toBe(true); }); - it("is false when any row among several is failed", () => { - expect(isWaveVerified([row("passed"), row("failed"), row("passed")])).toBe( - false, - ); + it("is false when any check among several has a failed latest row", () => { + expect( + isWaveVerified([ + row("passed", "typecheck"), + row("failed", "test"), + row("passed", "lint"), + ]), + ).toBe(false); }); - it("is false for a mixed skip/fail set", () => { - expect(isWaveVerified([row("skipped"), row("failed")])).toBe(false); + it("is false for a mixed skip/fail set across different checks", () => { + expect( + isWaveVerified([row("skipped", "lint"), row("failed", "test")]), + ).toBe(false); }); - it("is true for a mixed pass/skip set", () => { - expect(isWaveVerified([row("passed"), row("skipped")])).toBe(true); + it("is true for a mixed pass/skip set across different checks", () => { + expect( + isWaveVerified([row("passed", "test"), row("skipped", "lint")]), + ).toBe(true); }); it("treats a pending row as non-failing on its own", () => { expect(isWaveVerified([row("pending")])).toBe(true); }); - it("is false when a pending row accompanies a failed row", () => { - expect(isWaveVerified([row("pending"), row("failed")])).toBe(false); + it("is false when a pending row accompanies a failed row on a different check", () => { + expect( + isWaveVerified([row("pending", "lint"), row("failed", "test")]), + ).toBe(false); + }); + + // --------------------------------------------------------------------- + // Latest-per-check_name semantics (append-only history) + // --------------------------------------------------------------------- + + it("a later pass for the SAME check supersedes its own prior fail", () => { + expect( + isWaveVerified([row("failed", "test", 1), row("passed", "test", 2)]), + ).toBe(true); + }); + + it("a later skip for the SAME check supersedes its own prior fail", () => { + expect( + isWaveVerified([row("failed", "test", 1), row("skipped", "test", 2)]), + ).toBe(true); + }); + + it("a later fail for the SAME check supersedes its own prior pass", () => { + expect( + isWaveVerified([row("passed", "test", 1), row("failed", "test", 2)]), + ).toBe(false); + }); + + it("a pass for a DIFFERENT check never supersedes another check's unresolved fail", () => { + expect( + isWaveVerified([row("failed", "test", 1), row("passed", "typecheck", 2)]), + ).toBe(false); + }); + + it("is independent of array order — sorts by id, not caller position", () => { + // Fail row appended AFTER the pass row in the array, but its id is + // lower, so the pass (higher id) is still the effective latest. + expect( + isWaveVerified([row("passed", "test", 2), row("failed", "test", 1)]), + ).toBe(true); + }); + + it("every check must have a non-failing latest row, not just one of several", () => { + expect( + isWaveVerified([ + row("failed", "test", 1), + row("passed", "test", 2), + row("failed", "typecheck", 3), + ]), + ).toBe(false); + }); + + it("all checks resolved: same-check remediation plus an untouched passing check both count", () => { + expect( + isWaveVerified([ + row("failed", "test", 1), + row("passed", "lint", 2), + row("passed", "test", 3), + ]), + ).toBe(true); }); }); diff --git a/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts b/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts index 057b8069..4e10f6fc 100644 --- a/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts +++ b/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts @@ -93,15 +93,37 @@ export type { VerificationStatus }; // --------------------------------------------------------------------------- export interface VerifiedRowLike { + /** Recency key. `id` is `INTEGER PRIMARY KEY AUTOINCREMENT` on the + * append-only `verifications` table, so it is strictly increasing in + * insertion order — sorted here rather than trusted from caller order. */ + id: number; + /** The logical check this row reports on (e.g. `"test"`, `"typecheck"`). */ + check_name: string; status: VerificationStatus; } /** - * True when there is at least one row and none is `"failed"`. An explicit - * `"skipped"` row (alone or alongside passing rows) satisfies the gate as a - * deliberate, auditable escape — a wave with zero rows is never verified. + * True when every distinct `check_name`'s *effective* (latest-by-`id`) row + * is non-`"failed"`, and at least one check exists. Rows are append-only — + * a later `pass`/`skip` for the SAME check supersedes that check's prior + * `fail`; a pass for a DIFFERENT check never erases another check's + * unresolved fail. A wave with zero rows is never verified; an explicit + * `"skipped"` effective row satisfies the gate as an auditable escape. */ export function isWaveVerified(rows: readonly VerifiedRowLike[]): boolean { if (rows.length === 0) return false; - return rows.every((row) => row.status !== "failed"); + + const latestByCheck = new Map(); + for (const row of rows) { + const existing = latestByCheck.get(row.check_name); + if (existing === undefined || row.id > existing.id) { + latestByCheck.set(row.check_name, row); + } + } + + if (latestByCheck.size === 0) return false; + for (const row of latestByCheck.values()) { + if (row.status === "failed") return false; + } + return true; } diff --git a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts index ca89c49c..37d25844 100644 --- a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts +++ b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts @@ -181,9 +181,18 @@ describe("auditPromptSurfaces (real tree)", () => { // cross-reference to goop-wave-verifier (+273 bytes, +2 abs). Net: // 82,324 -> 83,111 bytes, absolute hits 66 -> 70, bold spans unchanged // at 137. + // + // The wave-verifier-gating workflow's Wave 3 Task 4 (Rule 4 remediation: + // latest-per-check_name verification gate) documented in + // agents/goop-wave-verifier.md that re-verifying a check records a new + // append-only row rather than replacing the old one, and that the wave + // gate reads each check's latest row. Net: 83,111 -> 83,373 bytes + // (+262), absolute hits unchanged at 70 (the added sentence uses + // "persist forever" and "instead of", not a must/never/always/critical/ + // only judgment word), bold spans unchanged at 137. const agents = report.directories.find((d) => d.directory === "agents")!; expect(agents.files).toBe(15); - expect(agents.bytes).toBe(83_111); + expect(agents.bytes).toBe(83_373); expect(agents.boldSpans).toBe(137); }); @@ -214,9 +223,17 @@ describe("auditPromptSurfaces (real tree)", () => { // "never implements fixes" role invariant, the "acceptance-only" scope, // the "inspect/report-only" boundary, and the "never implements" // delegate statement). + // + // The wave-verifier-gating workflow's Wave 3 Task 4 (Rule 4 remediation: + // latest-per-check_name verification gate) corrected goop-execute.md's + // wave-completion gate description, which pinned the superseded + // "zero fail rows ever" reading, to the append-only latest-per-check + // rule the runtime now enforces. Net: 26,092 -> 26,318 bytes (+226), + // absolute hits 38 -> 39 (+1: "never deleted or edited" — a true + // data-integrity invariant, not a judgment call). const commands = report.directories.find((d) => d.directory === "commands")!; expect(commands.files).toBe(9); - expect(commands.bytes).toBe(26_092); + expect(commands.bytes).toBe(26_318); }); it("references: 19 files, 161,350 bytes", () => { @@ -367,7 +384,16 @@ describe("auditPromptSurfaces (real tree)", () => { // goop-help.md (never-implements-fixes role invariant, acceptance-only, // inspect/report-only boundary, delegate-never statement) — lifting the // total from 299 to 308. - expect(report.totalAbsoluteHits).toBe(308); + // + // The wave-verifier-gating workflow's Wave 3 Task 4 (Rule 4 + // remediation: latest-per-check_name verification gate) corrected + // commands/goop-execute.md's wave-completion gate description to the + // append-only latest-per-check rule: +1 ("never deleted or edited" — a + // true data-integrity invariant). agents/goop-wave-verifier.md's + // matching clarification added zero new hits (its wording reuses the + // file's existing "only"/"never" vocabulary without a new match) — + // lifting the total from 308 to 309. + expect(report.totalAbsoluteHits).toBe(309); }); it("per-file tokens are consistent with chars via estimateTokens", () => { diff --git a/packages/opencode-plugin/src/hooks/auto-progression.test.ts b/packages/opencode-plugin/src/hooks/auto-progression.test.ts index 76639a5b..13ec5ce7 100644 --- a/packages/opencode-plugin/src/hooks/auto-progression.test.ts +++ b/packages/opencode-plugin/src/hooks/auto-progression.test.ts @@ -460,14 +460,15 @@ describe("auto-progression hook: wave verification gate", () => { expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); }); - it("a later passing row does not erase an earlier failing row — the wave stays blocked (append-only rows)", async () => { + it("a later passing row for the SAME check supersedes its own prior fail — progression proceeds (append-only rows)", async () => { const ctx = makeExecuteCtx(3); seedFinalWave(ctx, 3, "completed", ["done", "completed"], "failed"); const workflowId = ctx.stateManager.getActiveWorkflowId(); const wave = ctx.db.getWave(workflowId, 3); if (!wave) throw new Error("wave not seeded"); - // Record a later passing row for a different check — verifications are - // append-only (no upsert), so this does not supersede the earlier failure. + // Verifications are append-only (no upsert) — the earlier fail row is + // never deleted. A later pass row for the SAME check_name ("test") + // supersedes it as the effective status for that check. ctx.db.insertVerification(workflowId, { wave_id: wave.id, check_name: "test", @@ -479,6 +480,30 @@ describe("auto-progression hook: wave verification gate", () => { const output = makeOutput(); await handler(makeInput(), output); + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + // Both rows persist — nothing was deleted or mutated. + expect(ctx.db.getVerifications(workflowId, wave.id)).toHaveLength(2); + }); + + it("a later passing row for a DIFFERENT check does not erase another check's unresolved fail — the wave stays blocked", async () => { + const ctx = makeExecuteCtx(3); + seedFinalWave(ctx, 3, "completed", ["done", "completed"], "failed"); + const workflowId = ctx.stateManager.getActiveWorkflowId(); + const wave = ctx.db.getWave(workflowId, 3); + if (!wave) throw new Error("wave not seeded"); + // "test" is still failed at its latest row; "typecheck" passing does not + // resolve a different check's unresolved fail. + ctx.db.insertVerification(workflowId, { + wave_id: wave.id, + check_name: "typecheck", + status: "passed", + }); + + const hooks = createAutoProgressionHook(ctx); + const handler = hooks["tool.execute.after"] as NonNullable; + const output = makeOutput(); + await handler(makeInput(), output); + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); }); }); diff --git a/packages/opencode-plugin/src/integration.test.ts b/packages/opencode-plugin/src/integration.test.ts index 7d1a2701..6969e444 100644 --- a/packages/opencode-plugin/src/integration.test.ts +++ b/packages/opencode-plugin/src/integration.test.ts @@ -846,24 +846,26 @@ describe("GoopSpec 5-phase integration", () => { }); // ======================================================================== - // 11. Wave-verification remediation loop (W3.T3 / MH3 / MH7 / MH8) + // 11. Wave-verification remediation loop (W3.T3-T4 / MH3 / MH7 / MH8) // // Proves the bounded fail → remediate → pass → complete path and that // lazy autopilot keeps moving across a verification-only turn. // - // MATERIAL DEVIATION from MH3's literal wording (logged to ADL): - // Wave 2 D2 made verification rows insert-only and the gate predicate - // `isWaveVerified = rows.length >= 1 AND zero failing rows` (locked in - // src/features/enforcement/verifier-stage.ts and pinned by - // auto-progression.test.ts:463). A wave row with a historical fail - // therefore CANNOT be unblocked by inserting a later pass row — the - // gate is permanent for that wave. The integration scenarios below - // model the supported auditable mechanisms instead of silently - // weakening D2: the happy path (no fail row) completes and progresses; - // the gate-enforcement path proves a fail row blocks completion, a - // later pass row does NOT unblock it, and the orchestrator's recourse - // is to open a high-severity blocker (which the lazy-autopilot guard - // observes and suppresses). + // RULE 4 ARCHITECTURE DECISION (logged to ADL, reconciling W2 D2 with + // MH3's bounded remediation loop): verification rows remain append-only + // — never updated or deleted (src/features/db/index.ts insertVerification + // has no matching update/delete) — but the wave-completion gate + // (`isWaveVerified` in src/features/enforcement/verifier-stage.ts) reads + // the EFFECTIVE status per `check_name`: the latest (highest-id) row for + // each check. A later `pass` or explicit `skip` for the SAME check + // supersedes that check's own prior `fail` without touching history; a + // pass for a DIFFERENT check never erases another check's unresolved + // fail. The scenarios below prove: the happy path (no fail row) completes + // and progresses; a fail blocks completion; remediation via a same-check + // pass unblocks completion and lets progression proceed; and a + // different-check pass does NOT unblock — the orchestrator's recourse + // there remains opening a high-severity blocker, which the lazy-autopilot + // guard observes and suppresses. // ======================================================================== describe("wave-verification remediation loop", () => { @@ -944,18 +946,16 @@ describe("GoopSpec 5-phase integration", () => { expect(output.output).toContain("2/2 tasks complete"); }); - // Scenario B — gate enforcement with a fail row: proves the locked D2 - // behavior is honored end-to-end. A fail row blocks completion; a later - // pass row does NOT unblock it; the supported terminal state is to open - // a high-severity blocker, which the lazy-autopilot guard observes and - // uses to suppress further nudges. - it("locked D2 enforced: fail row blocks completion; later pass row does NOT unblock; blocker suppresses nudge", async () => { + // Scenario B — the bounded remediation loop MH3 describes: a fail row + // blocks completion; remediation is represented; a later pass row for + // the SAME check supersedes its own prior fail; completion then + // succeeds and progression proceeds. History stays append-only + // throughout — both rows persist, nothing is deleted or mutated. + it("fail row blocks completion → remediation represented → same-check pass supersedes it → completion succeeds → progression proceeds", async () => { const ctx = makeExecuteCtx(); const tools = createTools(ctx); const writeWave = tools.goop_write_wave; - const blocker = tools.goop_blocker; const toolContext = createMockToolContext(); - __clearNudgeRateLimitState(); // Wave exists with both tasks complete but a failing verification row. await writeWave.execute( @@ -972,7 +972,8 @@ describe("GoopSpec 5-phase integration", () => { toolContext, ); - // 1. Completion is BLOCKED by the gate (zero-pass / one-fail row). + // 1. Completion is BLOCKED by the gate — "test"'s only (so latest) + // row is a fail. const blockedCompletion = await writeWave.execute( { wave_number: 2, status: "completed" }, toolContext, @@ -982,11 +983,10 @@ describe("GoopSpec 5-phase integration", () => { expect(blockedCompletion).toContain("goop-wave-verifier"); expect(ctx.db.getWave("default", 2)?.status).toBe("in_progress"); - // 2. Remediation phase represented: the orchestrator dispatches an - // executor to fix the gap, then re-dispatches the wave verifier. - // Per W3.T1 docs this is the documented loop. Per W2 D2 (locked), - // inserting a later pass row cannot unblock the wave — the gate - // reads ALL rows and rejects any wave with a historical fail. + // 2. Remediation represented: the orchestrator dispatches an executor + // to fix the gap, then re-dispatches the wave verifier, which + // records a NEW row for the SAME check ("test") — the fail row is + // never deleted or updated (append-only). const remediationRow = await writeWave.execute( { wave_number: 2, @@ -997,9 +997,68 @@ describe("GoopSpec 5-phase integration", () => { expect(remediationRow).toContain("Verifications:"); expect(remediationRow).toContain("test=pass"); - // 3. Re-attempted completion is STILL BLOCKED — this is the locked - // D2 behavior. The test pins it so a future change cannot silently - // weaken the gate. + // 3. Re-attempted completion now SUCCEEDS — "test"'s latest row is + // the new pass, which supersedes its own prior fail. The earlier + // fail row still exists (proven below), just no longer effective. + const completion = await writeWave.execute( + { wave_number: 2, status: "completed" }, + toolContext, + ); + expect(completion).toContain("Written wave 2"); + expect(ctx.db.getWave("default", 2)?.status).toBe("completed"); + + const wave = ctx.db.getWave("default", 2); + const rows = ctx.db.getVerifications("default", wave?.id ?? -1); + expect(rows.filter((r) => r.check_name === "test")).toHaveLength(2); + expect(rows.map((r) => r.status).sort()).toEqual(["failed", "passed"]); + + // 4. Auto-progression fires: the final wave is complete and its + // verification gate is satisfied, so execute → accept proceeds. + const autoProgression = createAutoProgressionHook(ctx)["tool.execute.after"]; + const apOutput = { title: "result", output: "ok", metadata: {} }; + await autoProgression?.( + { tool: "goop_write_wave", sessionID: "orchestrator", callID: "any", args: {} }, + apOutput, + ); + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + }); + + // Scenario B2 — a pass for a DIFFERENT check never resolves another + // check's unresolved fail. The wave stays blocked; the orchestrator's + // recourse is to open a high-severity blocker, which the lazy-autopilot + // guard observes and uses to suppress further nudges. + it("different-check pass does NOT supersede an unresolved fail on another check; blocker suppresses nudge", async () => { + const ctx = makeExecuteCtx(); + const tools = createTools(ctx); + const writeWave = tools.goop_write_wave; + const blocker = tools.goop_blocker; + const toolContext = createMockToolContext(); + __clearNudgeRateLimitState(); + + await writeWave.execute( + { + wave_number: 2, + title: "Mismatched-remediation wave", + status: "in_progress", + tasks: [ + { task_index: 1, description: "First", status: "complete" }, + { task_index: 2, description: "Second", status: "complete" }, + ], + verifications: [{ check_name: "test", status: "fail", detail: "regression: 2 failing" }], + }, + toolContext, + ); + + // A pass is recorded for "typecheck", not "test" — the check that + // actually failed. This does not resolve the gate. + await writeWave.execute( + { + wave_number: 2, + verifications: [{ check_name: "typecheck", status: "pass", detail: "unrelated check" }], + }, + toolContext, + ); + const stillBlocked = await writeWave.execute( { wave_number: 2, status: "completed" }, toolContext, @@ -1008,14 +1067,9 @@ describe("GoopSpec 5-phase integration", () => { expect(stillBlocked).toContain("cannot be marked complete"); expect(ctx.db.getWave("default", 2)?.status).toBe("in_progress"); - // 4. Because the wave never reaches a complete status, the - // auto-progression hook returns early at its isCompleteStatus - // guard and the phase stays execute. The hook's secondary - // "Blocked: execute → accept" defense is pinned directly by - // auto-progression.test.ts:401 (seeding a complete wave with a - // failing row); the integration assertion here is the - // higher-level guarantee: the phase cannot advance while the - // gate is unsatisfied. + // Because the wave never reaches a complete status, the + // auto-progression hook returns early at its isCompleteStatus guard + // and the phase stays execute. const autoProgression = createAutoProgressionHook(ctx)["tool.execute.after"]; const apOutput = { title: "result", output: "ok", metadata: {} }; await autoProgression?.( @@ -1024,22 +1078,22 @@ describe("GoopSpec 5-phase integration", () => { ); expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); - // 5. Supported terminal state per commands/goop-execute.md:50 - // (three-strikes): open a high-severity blocker and stop. + // Supported terminal state per commands/goop-execute.md:50 + // (three-strikes): open a high-severity blocker and stop. const blockerResult = await blocker.execute( { action: "open", description: - "Wave 2 verification gate cannot be satisfied: a failing row is permanently in the row set (D2 insert-only). Operator must force-complete or reset the wave.", + "Wave 2 verification gate cannot be satisfied: the failing check (\"test\") has no matching pass or skip row. Dispatch goop-wave-verifier to re-check \"test\" specifically.", severity: "high", }, toolContext, ); expect(blockerResult).toContain("Opened blocker #"); - // 6. The lazy-autopilot guard observes the open high-severity blocker - // and suppresses the nudge — the orchestrator is not pestered while - // a blocker is outstanding. + // The lazy-autopilot guard observes the open high-severity blocker + // and suppresses the nudge — the orchestrator is not pestered while + // a blocker is outstanding. const promptAsync = mock(async () => undefined); Object.assign(ctx.sdk.client, { session: { diff --git a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts index a0608c26..557cea0a 100644 --- a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts @@ -2243,7 +2243,7 @@ describe("goop_write_wave wave-completion verification gate", () => { expect(ctx.db.getWave("default", 1)?.status).not.toBe("done"); }); - it("a later passing row does not erase an earlier failing row for the same wave (append-only)", async () => { + it("a later passing row for the SAME check supersedes an earlier failing row for that check — completion unblocks (append-only)", async () => { const tool = createGoopWriteWaveTool(ctx); await tool.execute( { @@ -2262,10 +2262,65 @@ describe("goop_write_wave wave-completion verification gate", () => { toolCtx, ); - // Both rows now exist for the wave — the later pass does not delete the - // earlier fail — so completion must still be blocked. + // Both rows still exist for the wave — the later pass does not delete + // the earlier fail — but the effective status for "test" is now its + // latest row (pass), so completion succeeds. + const result = await tool.execute({ wave_number: 1, status: "done" }, toolCtx); + expect(result).toContain("Written wave 1"); + expect(ctx.db.getWave("default", 1)?.status).toBe("done"); + + const wave = ctx.db.getWave("default", 1); + const rows = ctx.db.getVerifications("default", wave?.id ?? -1); + expect(rows).toHaveLength(2); + expect(rows.map((r) => r.status).sort()).toEqual(["failed", "passed"]); + }); + + it("a later passing row for a DIFFERENT check does not supersede another check's unresolved fail — completion stays blocked", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "Different-check wave", + status: "in_progress", + verifications: [{ check_name: "test", status: "fail" }], + }, + toolCtx, + ); + await tool.execute( + { + wave_number: 1, + verifications: [{ check_name: "typecheck", status: "pass" }], + }, + toolCtx, + ); + const result = await tool.execute({ wave_number: 1, status: "done" }, toolCtx); expect(result).toContain("Error in goop_write_wave"); expect(result).toContain("goop-wave-verifier"); + expect(ctx.db.getWave("default", 1)?.status).toBe("in_progress"); + }); + + it("a later skip row for the SAME check supersedes an earlier failing row for that check — completion unblocks", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "Skip-remediation wave", + status: "in_progress", + verifications: [{ check_name: "test", status: "fail" }], + }, + toolCtx, + ); + await tool.execute( + { + wave_number: 1, + verifications: [{ check_name: "test", status: "skip" }], + }, + toolCtx, + ); + + const result = await tool.execute({ wave_number: 1, status: "done" }, toolCtx); + expect(result).toContain("Written wave 1"); + expect(ctx.db.getWave("default", 1)?.status).toBe("done"); }); }); From e811bcc99830b60a14fedf2c9eeb29f989513dc8 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:17:14 -0700 Subject: [PATCH 14/22] test(plugin): lock write-tool call shapes as positive fixtures (W4.T1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a self-contained positive-fixture-inventory describe block to each of the five write tools, locking every currently-valid call shape as a passing fixture before Wave 4 Task 2/3 tightens runtime validation. Inventory per tool: - goop_write_db: 6 shapes (full write, append, patch, replace-all, items[], blank-doc patch workaround) - goop_write_section: 5 shapes (section create, patch, replace-all, items[], blank-doc patch workaround; append N/A — no mode field) - goop_save_note: 5 shapes (create, patch, replace-all, items[], empty-body patch workaround; append N/A) - goop_write_wave: 2 generic + 5 tool-specific shapes (wave write, items[], task_update, task_updates[], verifications[], traceability[], traceability-only without wave_number; patch/append/blank-doc N/A) - goop_blocker: 1 generic + 3 tool-specific shapes (open, resolve, list, items[]; patch/append/blank-doc N/A) Test-only; no production code changed. Inapplicable shapes documented inline with structural rationale. SPEC: MH9, MH11. --- .../src/tools/goop-blocker/index.test.ts | 82 ++++++++++ .../src/tools/goop-save-note/index.test.ts | 131 +++++++++++++++ .../src/tools/goop-write-db/index.test.ts | 90 ++++++++++ .../tools/goop-write-section/index.test.ts | 85 ++++++++++ .../src/tools/goop-write-wave/index.test.ts | 154 ++++++++++++++++++ 5 files changed, 542 insertions(+) diff --git a/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts b/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts index 93c55937..ce58d267 100644 --- a/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts @@ -351,3 +351,85 @@ describe("goop_blocker tool", () => { expect(ctx.db.getBlockers("default", "open").length).toBe(2); }); }); + +// --------------------------------------------------------------------------- +// Positive fixture inventory — valid call shapes (W4 Task 1) +// +// goop_blocker is an action-based lifecycle tool, structurally distinct +// from the content-document tools. It has no `content`, `mode`, +// `old_string`, `new_string`, or `replace_all` fields. The generic shapes: +// - "full-document write" → action: 'open' (the create analog) +// - "append mode" → N/A. No `mode`/content fields. +// - "patch mode" → N/A. No patch fields; lifecycle transitions use +// action: 'resolve' (which upserts with status: 'resolved'), not +// substring patching. +// - "replace-all patch" → N/A. +// - "items[] batch" → applies. +// - "blank-document patch workaround" → N/A. +// +// The tool's OWN valid shapes are action: open / resolve / list, plus the +// items[] batch combining them. All are locked below. +// --------------------------------------------------------------------------- + +describe("goop_blocker positive fixture inventory — valid call shapes (W4.T1)", () => { + let ctx: PluginContext; + let toolCtx: ToolContext; + let cleanup: () => void; + + beforeEach(() => { + const env = setupTestEnvironment("goop-blocker-inventory"); + cleanup = env.cleanup; + ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + toolCtx = createMockToolContext(); + }); + + afterEach(() => cleanup()); + + it("SHAPE: action open (action + description + optional severity)", async () => { + const tool = createGoopBlockerTool(ctx); + const result = await tool.execute( + { action: "open", description: "Inventory blocker", severity: "medium" }, + toolCtx, + ); + expect(result).toContain("Opened blocker #"); + expect(ctx.db.getBlockers("default", "open")).toHaveLength(1); + }); + + it("SHAPE (tool-specific): action resolve (action + id + resolution)", async () => { + const tool = createGoopBlockerTool(ctx); + await tool.execute({ action: "open", description: "To resolve" }, toolCtx); + const id = ctx.db.getBlockers("default", "open")[0].id; + + const result = await tool.execute( + { action: "resolve", id, resolution: "Resolved in inventory" }, + toolCtx, + ); + expect(result).toContain(`Resolved blocker #${id}`); + expect(ctx.db.getBlockers("default", "resolved")).toHaveLength(1); + }); + + it("SHAPE (tool-specific): action list (action + optional status filter)", async () => { + const tool = createGoopBlockerTool(ctx); + await tool.execute({ action: "open", description: "Listed blocker" }, toolCtx); + + const result = await tool.execute({ action: "list", status: "open" }, toolCtx); + expect(result).toContain("# Blockers"); + expect(result).toContain("Listed blocker"); + }); + + it("SHAPE: items[] batch (mixed open + list)", async () => { + const tool = createGoopBlockerTool(ctx); + const result = await tool.execute( + { + items: [ + { action: "open", description: "Batch A" }, + { action: "open", description: "Batch B" }, + { action: "list", status: "open" }, + ], + }, + toolCtx, + ); + expect(result).toContain("3/3 succeeded"); + expect(ctx.db.getBlockers("default", "open")).toHaveLength(2); + }); +}); diff --git a/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts b/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts index 2823c284..f3f5a8a3 100644 --- a/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts @@ -836,4 +836,135 @@ describe("goop_save_note tool", () => { }); }); }); + + // ----------------------------------------------------------------------- + // Positive fixture inventory — valid call shapes (W4 Task 1) + // + // goop_save_note is a CREATE-or-PATCH tool, structurally distinct from the + // content-document tools. The generic shapes map as follows: + // - "full-document write" → note CREATE (title + body + tags + source_agent) + // - "append mode" → N/A. There is no `mode` field; a note is a single + // inserted row, not appended content. Omitted. + // - "patch mode" → note PATCH via note_id + old_string + new_string + // - "replace-all patch" → note PATCH with replace_all: true + // - "items[] batch" → batch create/patch + // - "blank-document patch workaround" → patching a note whose body is '' + // with old_string: '' succeeds today (patchContent('', '', newString)). + // ----------------------------------------------------------------------- + + describe("positive fixture inventory — valid call shapes (W4.T1)", () => { + function extractId(result: string): string { + return result.match(/fn_\d{8}_[a-z0-9]+/)?.[0] ?? ""; + } + + it("SHAPE: note create (title + body + tags + source_agent)", async () => { + const tool = createGoopSaveNoteTool(ctx); + const result = String( + await tool.execute( + { + title: "Inventory note", + body: "Body for inventory.", + tags: ["inv"], + source_agent: "goop-tester", + }, + toolCtx, + ), + ); + expect(result).toContain("Field Note saved:"); + expect(result).toContain("Inventory note"); + }); + + it("SHAPE: patch mode (note_id + old_string + new_string, single match)", async () => { + const tool = createGoopSaveNoteTool(ctx); + const createResult = String( + await tool.execute( + { title: "Inv patch target", body: "alpha beta", tags: ["p"], source_agent: "agent" }, + toolCtx, + ), + ); + const noteId = extractId(createResult); + + const result = await tool.execute( + { note_id: noteId, old_string: "beta", new_string: "BETA" }, + toolCtx, + ); + expect(result).toContain(noteId); + expect(result).toContain("patched"); + expect(ctx.db.getNoteById(noteId)?.body).toBe("alpha BETA"); + }); + + it("SHAPE: replace-all patch (note_id + old_string + new_string + replace_all: true)", async () => { + const tool = createGoopSaveNoteTool(ctx); + const createResult = String( + await tool.execute( + { + title: "Inv replace-all target", + body: "foo bar foo baz foo", + tags: ["p"], + source_agent: "agent", + }, + toolCtx, + ), + ); + const noteId = extractId(createResult); + + const result = await tool.execute( + { note_id: noteId, old_string: "foo", new_string: "qux", replace_all: true }, + toolCtx, + ); + expect(result).toContain(noteId); + expect(ctx.db.getNoteById(noteId)?.body).toBe("qux bar qux baz qux"); + }); + + it("SHAPE: items[] batch (mixed create + patch items)", async () => { + const tool = createGoopSaveNoteTool(ctx); + const createResult = String( + await tool.execute( + { title: "Batch patch target", body: "alpha beta", tags: ["p"], source_agent: "agent" }, + toolCtx, + ), + ); + const noteId = extractId(createResult); + + const result = String( + await tool.execute( + { + title: "", + body: "", + tags: [], + source_agent: "agent", + items: [ + { title: "Fresh batch note", body: "Fresh body", tags: ["n"], source_agent: "agent" }, + { note_id: noteId, old_string: "beta", new_string: "BETA" }, + ], + }, + toolCtx, + ), + ); + expect(result).toContain("2/2 succeeded"); + expect(ctx.db.getNoteById(noteId)?.body).toBe("alpha BETA"); + }); + + it("SHAPE: blank-document patch workaround (note_id + old_string: '' on a note with empty body)", async () => { + // CURRENT behaviour: a note created with body: '' can be patched via + // old_string: '' because patchContent('', '', newString) succeeds with + // matchCount -1. Locked here so Wave 4 Task 2/3 must decide deliberately. + const tool = createGoopSaveNoteTool(ctx); + const createResult = String( + await tool.execute( + { title: "Empty body note", body: "", tags: ["empty"], source_agent: "agent" }, + toolCtx, + ), + ); + const noteId = extractId(createResult); + expect(ctx.db.getNoteById(noteId)?.body).toBe(""); + + const result = await tool.execute( + { note_id: noteId, old_string: "", new_string: "Filled in via empty patch" }, + toolCtx, + ); + expect(result).toContain(noteId); + expect(ctx.db.getNoteById(noteId)?.body).toBe("Filled in via empty patch"); + }); + }); }); diff --git a/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts index be4863c7..f7b501ae 100644 --- a/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts @@ -460,4 +460,94 @@ describe("goop_write_db tool", () => { expect(result).not.toContain("0 chars"); }); }); + + // ----------------------------------------------------------------------- + // Positive fixture inventory — valid call shapes (W4 Task 1) + // + // Locks every currently-valid goop_write_db call shape as a passing + // fixture in one self-contained block, so Wave 4 Task 2/3 runtime + // validation tightening cannot silently break a working caller. These + // fixtures assert the CURRENT behaviour; they are not a spec of the + // intended behaviour. Some shapes are individually covered by dedicated + // tests above — repeated here as a single contract surface. + // ----------------------------------------------------------------------- + + describe("positive fixture inventory — valid call shapes (W4.T1)", () => { + it("SHAPE: full-document write (doc_type + content)", async () => { + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute({ doc_type: "spec", content: "# Inventory Spec" }, toolCtx); + expect(result).toContain("Written spec"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("# Inventory Spec"); + }); + + it("SHAPE: append mode (doc_type + content + mode: 'append')", async () => { + ctx.db.upsertDocument("default", "spec", "# Base"); + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", content: "# Appended", mode: "append" }, + toolCtx, + ); + expect(result).toContain("mode: append"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("# Base\n\n# Appended"); + }); + + it("SHAPE: patch mode (doc_type + old_string + new_string, single match)", async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", old_string: "world", new_string: "GoopSpec" }, + toolCtx, + ); + expect(result).toContain("mode: patch"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello GoopSpec"); + }); + + it("SHAPE: replace-all patch (doc_type + old_string + new_string + replace_all: true)", async () => { + ctx.db.upsertDocument("default", "spec", "foo bar foo baz foo"); + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", old_string: "foo", new_string: "qux", replace_all: true }, + toolCtx, + ); + expect(result).toContain("mode: patch"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("qux bar qux baz qux"); + }); + + it("SHAPE: items[] batch (mixed create + patch items)", async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + content: "", + items: [ + { doc_type: "spec", old_string: "world", new_string: "GoopSpec" }, + { doc_type: "blueprint", content: "# Blueprint" }, + ], + }, + toolCtx, + ); + expect(result).toContain("2/2 succeeded"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello GoopSpec"); + expect(ctx.db.getDocument("default", "blueprint")?.content).toBe("# Blueprint"); + }); + + it("SHAPE: blank-document patch workaround (old_string: '' on an empty document)", async () => { + // CURRENT behaviour: an absent/empty document resolves to '' and + // patchContent('', '', newString) returns ok with matchCount -1, which + // falls through every guard so new_string becomes the full document + // content. This is the workaround observed during discovery. Locked + // here so Wave 4 Task 2/3 must decide deliberately whether to keep or + // reject it rather than silently changing the outcome. + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", old_string: "", new_string: "# Written via empty-old-string patch" }, + toolCtx, + ); + expect(result).toContain("mode: patch"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe( + "# Written via empty-old-string patch", + ); + }); + }); }); diff --git a/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts index 4ee55fb5..744f0c1c 100644 --- a/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts @@ -489,4 +489,89 @@ describe("goop_write_section tool", () => { expect(assembled.length).not.toBe(patchedSection.length); }); }); + + // ----------------------------------------------------------------------- + // Positive fixture inventory — valid call shapes (W4 Task 1) + // + // goop_write_section has no `mode` field and no append semantics — a + // section write always replaces the section content. The generic + // "append mode" shape is therefore N/A and omitted. All other generic + // shapes apply. The blank-document patch workaround applies because an + // absent section resolves to '' via getSection(...)?.content ?? '', and + // patchContent('', '', newString) succeeds with matchCount -1. + // ----------------------------------------------------------------------- + + describe("positive fixture inventory — valid call shapes (W4.T1)", () => { + it("SHAPE: section create (doc_type + section_key + content)", async () => { + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { doc_type: "spec", section_key: "inv", content: "# Inventory Section" }, + toolCtx, + ); + expect(result).toContain("Written section 'inv'"); + expect(ctx.db.getSection("default", "spec", "inv")?.content).toBe("# Inventory Section"); + }); + + it("SHAPE: patch mode (section + old_string + new_string, single match)", async () => { + ctx.db.upsertSection("default", "spec", "inv", "Hello world"); + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { doc_type: "spec", section_key: "inv", old_string: "world", new_string: "GoopSpec" }, + toolCtx, + ); + expect(result).toContain("Patched section 'inv'"); + expect(ctx.db.getSection("default", "spec", "inv")?.content).toBe("Hello GoopSpec"); + }); + + it("SHAPE: replace-all patch (section + old_string + new_string + replace_all: true)", async () => { + ctx.db.upsertSection("default", "spec", "inv", "foo bar foo baz foo"); + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + section_key: "inv", + old_string: "foo", + new_string: "qux", + replace_all: true, + }, + toolCtx, + ); + expect(result).toContain("Patched section 'inv'"); + expect(ctx.db.getSection("default", "spec", "inv")?.content).toBe("qux bar qux baz qux"); + }); + + it("SHAPE: items[] batch (mixed create + patch items)", async () => { + ctx.db.upsertSection("default", "spec", "inv", "Hello world"); + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + section_key: "", + content: "", + items: [ + { doc_type: "spec", section_key: "inv", old_string: "world", new_string: "GoopSpec" }, + { doc_type: "spec", section_key: "plan", content: "# Plan" }, + ], + }, + toolCtx, + ); + expect(result).toContain("2/2 succeeded"); + expect(ctx.db.getSection("default", "spec", "inv")?.content).toBe("Hello GoopSpec"); + expect(ctx.db.getSection("default", "spec", "plan")?.content).toBe("# Plan"); + }); + + it("SHAPE: blank-document patch workaround (old_string: '' on an absent section)", async () => { + // CURRENT behaviour: an absent section resolves to '' and + // patchContent('', '', newString) succeeds with matchCount -1, so + // new_string becomes the section content. Locked here so Wave 4 + // Task 2/3 must decide deliberately. + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { doc_type: "spec", section_key: "fresh", old_string: "", new_string: "# Via empty patch" }, + toolCtx, + ); + expect(result).toContain("Patched section 'fresh'"); + expect(ctx.db.getSection("default", "spec", "fresh")?.content).toBe("# Via empty patch"); + }); + }); }); diff --git a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts index 557cea0a..e1339903 100644 --- a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts @@ -2324,3 +2324,157 @@ describe("goop_write_wave wave-completion verification gate", () => { expect(ctx.db.getWave("default", 1)?.status).toBe("done"); }); }); + +// --------------------------------------------------------------------------- +// Positive fixture inventory — valid call shapes (W4 Task 1) +// +// goop_write_wave is structurally distinct from the content-document tools: +// it has no `content`, `mode`, `old_string`, `new_string`, or `replace_all` +// fields. The generic inventory shapes map as follows: +// - "full-document write" → wave metadata write (wave_number + title/status/pr_branch/...) +// - "append mode" → N/A. No `mode` field; metadata is upserted with +// per-field overwrite-or-preserve semantics, never appended. +// - "patch mode (old_string/new_string)" → N/A. The tool exposes no patch +// fields; wave metadata has no substring-patch semantics. +// - "replace-all patch" → N/A (same reason — no patch fields). +// - "items[] batch" → applies. +// - "blank-document patch workaround" → N/A (no patch fields). +// +// The tool's OWN structurally-distinct valid shapes are inventoried below +// the two generic ones: task_update, task_updates[], verifications[], +// traceability[], and the traceability-only call without a top-level +// wave_number. +// --------------------------------------------------------------------------- + +describe("goop_write_wave positive fixture inventory — valid call shapes (W4.T1)", () => { + let ctx: PluginContext; + let toolCtx: ToolContext; + let cleanup: () => void; + + beforeEach(() => { + const env = setupTestEnvironment("goop-write-wave-inventory"); + cleanup = env.cleanup; + ctx = createMockPluginContext({ testDir: env.testDir, db: env.db }); + toolCtx = createMockToolContext(); + }); + + afterEach(() => cleanup()); + + it("SHAPE: wave metadata write (wave_number + title + inline tasks)", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + title: "Inventory wave", + status: "in_progress", + tasks: [{ task_index: 1, description: "Inventory task", status: "pending" }], + }, + toolCtx, + ); + expect(result).toContain("Written wave 1"); + expect(ctx.db.getWave("default", 1)?.title).toBe("Inventory wave"); + }); + + it("SHAPE: items[] batch (multi-wave)", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + items: [ + { wave_number: 1, title: "Batch wave one" }, + { wave_number: 2, title: "Batch wave two" }, + ], + }, + toolCtx, + ); + expect(result).toContain("2/2 succeeded"); + expect(ctx.db.getWave("default", 1)?.title).toBe("Batch wave one"); + expect(ctx.db.getWave("default", 2)?.title).toBe("Batch wave two"); + }); + + it("SHAPE (tool-specific): single task_update (wave_number + task_update)", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "W", + tasks: [{ task_index: 1, description: "T1", status: "pending" }], + }, + toolCtx, + ); + const result = await tool.execute( + { wave_number: 1, task_update: { task_index: 1, status: "done" } }, + toolCtx, + ); + expect(result).toContain("Updated task 1"); + const wave = ctx.db.getWave("default", 1); + expect(ctx.db.getWaveTasks(wave?.id ?? -1)[0].status).toBe("done"); + }); + + it("SHAPE (tool-specific): bulk task_updates[] (wave_number + task_updates)", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute( + { + wave_number: 1, + title: "W", + tasks: [ + { task_index: 1, description: "T1", status: "pending" }, + { task_index: 2, description: "T2", status: "pending" }, + ], + }, + toolCtx, + ); + const result = await tool.execute( + { + wave_number: 1, + task_updates: [ + { task_index: 1, status: "done" }, + { task_index: 2, status: "done" }, + ], + }, + toolCtx, + ); + expect(result).toContain("2/2 succeeded"); + }); + + it("SHAPE (tool-specific): verifications[] side-payload alongside wave write", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + title: "Verified wave", + verifications: [{ check_name: "test", status: "pass" }], + }, + toolCtx, + ); + expect(result).toContain("Verifications:"); + expect(result).toContain("test=pass"); + }); + + it("SHAPE (tool-specific): traceability[] side-payload alongside wave write", async () => { + const tool = createGoopWriteWaveTool(ctx); + const result = await tool.execute( + { + wave_number: 1, + title: "Traced wave", + traceability: [{ requirement_key: "MH1", status: "covered" }], + }, + toolCtx, + ); + expect(result).toContain("Traceability:"); + expect(result).toContain("MH1"); + }); + + it("SHAPE (tool-specific): traceability-only call without a top-level wave_number", async () => { + const tool = createGoopWriteWaveTool(ctx); + await tool.execute({ wave_number: 1, title: "Target wave" }, toolCtx); + const result = await tool.execute( + { + traceability: [{ requirement_key: "MH1", wave_number: 1, status: "covered" }], + }, + toolCtx, + ); + expect(result).toContain("Traceability:"); + expect(ctx.db.getTraceability("default")).toHaveLength(1); + }); +}); From a97d68b2ef5b4cf1f6a2a79c594842dcdd5ea0d0 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:29:32 -0700 Subject: [PATCH 15/22] fix(plugin): resolve write-mode ambiguity in goop_write_db via shared helper (W4.T2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace presence-based isPatchActive/resolveContentForWrite branching with a pure resolveWriteMode() resolver (src/shared/write-mode.ts) that decides full-write/append, patch, or batch intent — and rejects four ambiguous shapes before any mutation: 1. meaningful content + old_string together 2. new_string/replace_all without old_string (previously silently dropped) 3. mode: "append" combined with patch fields 4. items[] combined with a top-level operation field Empty-string content stays a documented neutral placeholder when combined with items[] (matches existing batch fixtures); old_string presence alone (even "") still activates the blank-document patch workaround. Applied to both the single-call and per-item batch paths, so an ambiguous item now rolls back the whole batch transaction instead of silently mismatching. All W4.T1 pinned positive fixtures remain green. Adds full truth-table coverage for the resolver plus rejection/mutation-safety tests on the tool. SPEC: MH10, MH9 --- .../src/shared/write-mode.test.ts | 242 ++++++++++++++++++ .../opencode-plugin/src/shared/write-mode.ts | 156 +++++++++++ .../src/tools/goop-write-db/index.test.ts | 178 +++++++++++++ .../src/tools/goop-write-db/index.ts | 165 ++++++------ 4 files changed, 662 insertions(+), 79 deletions(-) create mode 100644 packages/opencode-plugin/src/shared/write-mode.test.ts create mode 100644 packages/opencode-plugin/src/shared/write-mode.ts diff --git a/packages/opencode-plugin/src/shared/write-mode.test.ts b/packages/opencode-plugin/src/shared/write-mode.test.ts new file mode 100644 index 00000000..b4885f2e --- /dev/null +++ b/packages/opencode-plugin/src/shared/write-mode.test.ts @@ -0,0 +1,242 @@ +import { describe, expect, it } from "bun:test"; + +import { resolveWriteMode } from "./write-mode.js"; + +describe("resolveWriteMode()", () => { + // ----------------------------------------------------------------------- + // Valid shapes + // ----------------------------------------------------------------------- + + describe("valid shapes", () => { + it("resolves a full-document write from content alone", () => { + const result = resolveWriteMode({ content: "# Spec" }); + expect(result).toEqual({ kind: "full-write", content: "# Spec", mode: "replace" }); + }); + + it("resolves an explicit append write", () => { + const result = resolveWriteMode({ content: "# Spec", mode: "append" }); + expect(result).toEqual({ kind: "full-write", content: "# Spec", mode: "append" }); + }); + + it("resolves an empty-string content as a legitimate empty-document write", () => { + const result = resolveWriteMode({ content: "" }); + expect(result).toEqual({ kind: "full-write", content: "", mode: "replace" }); + }); + + it("resolves a patch from old_string + new_string", () => { + const result = resolveWriteMode({ old_string: "world", new_string: "GoopSpec" }); + expect(result).toEqual({ + kind: "patch", + old_string: "world", + new_string: "GoopSpec", + replace_all: false, + }); + }); + + it("resolves a replace_all patch", () => { + const result = resolveWriteMode({ + old_string: "foo", + new_string: "qux", + replace_all: true, + }); + expect(result).toEqual({ + kind: "patch", + old_string: "foo", + new_string: "qux", + replace_all: true, + }); + }); + + it("resolves an empty old_string as a patch (blank-document workaround)", () => { + const result = resolveWriteMode({ old_string: "", new_string: "# Doc" }); + expect(result).toEqual({ + kind: "patch", + old_string: "", + new_string: "# Doc", + replace_all: false, + }); + }); + + it("defaults new_string to '' when old_string is present alone", () => { + const result = resolveWriteMode({ old_string: "remove me" }); + expect(result).toEqual({ + kind: "patch", + old_string: "remove me", + new_string: "", + replace_all: false, + }); + }); + + it("resolves mode: 'replace' + old_string as a patch (replace is the harmless default)", () => { + const result = resolveWriteMode({ old_string: "world", new_string: "x", mode: "replace" }); + expect(result.kind).toBe("patch"); + }); + + it("resolves a bare items[] call as batch", () => { + const result = resolveWriteMode({ hasItems: true }); + expect(result).toEqual({ kind: "batch" }); + }); + + it("resolves items[] alongside empty-string content as batch (neutral placeholder)", () => { + const result = resolveWriteMode({ hasItems: true, content: "" }); + expect(result).toEqual({ kind: "batch" }); + }); + + it("resolves no fields at all as 'none'", () => { + const result = resolveWriteMode({}); + expect(result).toEqual({ kind: "none" }); + }); + }); + + // ----------------------------------------------------------------------- + // Rule 1: meaningful content and old_string together + // ----------------------------------------------------------------------- + + describe("rule 1: meaningful content + old_string", () => { + it("rejects non-empty content combined with old_string", () => { + const result = resolveWriteMode({ content: "# New", old_string: "old" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain( + "content and old_string cannot be supplied together", + ); + }); + + it("names both valid shapes in the rejection message", () => { + const result = resolveWriteMode({ content: "# New", old_string: "old" }); + const message = (result as { message: string }).message; + expect(message).toContain("full write/append"); + expect(message).toContain("patch"); + expect(message).toContain("batch"); + }); + + it("does not reject empty-string content combined with old_string (content is not meaningful)", () => { + const result = resolveWriteMode({ content: "", old_string: "old", new_string: "new" }); + expect(result.kind).toBe("patch"); + }); + }); + + // ----------------------------------------------------------------------- + // Rule 2: new_string/replace_all without old_string + // ----------------------------------------------------------------------- + + describe("rule 2: new_string/replace_all without old_string", () => { + it("rejects new_string without old_string", () => { + const result = resolveWriteMode({ content: "# Doc", new_string: "x" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("new_string"); + expect((result as { message: string }).message).toContain("supplied without old_string"); + }); + + it("rejects replace_all without old_string", () => { + const result = resolveWriteMode({ content: "# Doc", replace_all: true }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("replace_all"); + }); + + it("rejects replace_all: false without old_string (presence, not truthiness, triggers the rule)", () => { + const result = resolveWriteMode({ content: "# Doc", replace_all: false }); + expect(result.kind).toBe("error"); + }); + + it("names both offending fields when new_string and replace_all are both present", () => { + const result = resolveWriteMode({ new_string: "x", replace_all: true }); + const message = (result as { message: string }).message; + expect(message).toContain("new_string"); + expect(message).toContain("replace_all"); + }); + + it("rejects new_string alone with no content and no old_string", () => { + const result = resolveWriteMode({ new_string: "x" }); + expect(result.kind).toBe("error"); + }); + }); + + // ----------------------------------------------------------------------- + // Rule 3: mode: "append" combined with patch fields + // ----------------------------------------------------------------------- + + describe('rule 3: mode: "append" combined with patch fields', () => { + it("rejects mode: append + old_string", () => { + const result = resolveWriteMode({ old_string: "x", new_string: "y", mode: "append" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain('mode: "append"'); + }); + + it("rejects mode: append + old_string even when new_string is absent", () => { + const result = resolveWriteMode({ old_string: "x", mode: "append" }); + expect(result.kind).toBe("error"); + }); + + it("rejects mode: append + old_string='' (blank-document workaround does not bypass the rule)", () => { + const result = resolveWriteMode({ old_string: "", new_string: "y", mode: "append" }); + expect(result.kind).toBe("error"); + }); + }); + + // ----------------------------------------------------------------------- + // Rule 4: items[] combined with top-level operation fields + // ----------------------------------------------------------------------- + + describe("rule 4: items[] combined with top-level operation fields", () => { + it("rejects non-empty content alongside items[]", () => { + const result = resolveWriteMode({ hasItems: true, content: "# Real content" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("content"); + expect((result as { message: string }).message).toContain("items[]"); + }); + + it("rejects old_string alongside items[]", () => { + const result = resolveWriteMode({ hasItems: true, old_string: "x" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("old_string"); + }); + + it("rejects new_string alongside items[]", () => { + const result = resolveWriteMode({ hasItems: true, new_string: "x" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("new_string"); + }); + + it("rejects replace_all alongside items[]", () => { + const result = resolveWriteMode({ hasItems: true, replace_all: true }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("replace_all"); + }); + + it("rejects mode alongside items[]", () => { + const result = resolveWriteMode({ hasItems: true, mode: "append" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("mode"); + }); + + it("names every offending field at once when several are present", () => { + const result = resolveWriteMode({ + hasItems: true, + content: "# Real", + old_string: "x", + mode: "append", + }); + const message = (result as { message: string }).message; + expect(message).toContain("content"); + expect(message).toContain("old_string"); + expect(message).toContain("mode"); + }); + + it("does not reject empty-string content alongside items[] (neutral placeholder)", () => { + const result = resolveWriteMode({ hasItems: true, content: "" }); + expect(result.kind).toBe("batch"); + }); + }); + + // ----------------------------------------------------------------------- + // Rule precedence — rule 4 wins first when multiple rules are violated + // ----------------------------------------------------------------------- + + describe("rule precedence", () => { + it("rule 4 fires ahead of rule 1 when both items[] and a content/old_string conflict are present", () => { + const result = resolveWriteMode({ hasItems: true, content: "# Real", old_string: "x" }); + expect(result.kind).toBe("error"); + expect((result as { message: string }).message).toContain("items[]"); + }); + }); +}); diff --git a/packages/opencode-plugin/src/shared/write-mode.ts b/packages/opencode-plugin/src/shared/write-mode.ts new file mode 100644 index 00000000..5db01756 --- /dev/null +++ b/packages/opencode-plugin/src/shared/write-mode.ts @@ -0,0 +1,156 @@ +/** + * write-mode.ts — shared operation-mode resolver for GoopSpecDB write tools. + * + * Decides whether a call means full-document write/append, patch, batch, or + * an ambiguous/invalid combination, before any mutation occurs. Replaces + * presence-based branching (`isPatchActive`) that let `content` silently + * lose to `old_string`, and let `new_string`/`replace_all` be silently + * dropped without `old_string`. Pure: callers own DB access and the actual + * patch execution (`content-patch.ts`). + */ + +export interface WriteModeFields { + content?: string; + mode?: "replace" | "append"; + old_string?: string; + new_string?: string; + replace_all?: boolean; + /** True when a non-empty items[] batch array accompanies this payload. */ + hasItems?: boolean; +} + +export interface FullWriteResolution { + kind: "full-write"; + content: string; + mode: "replace" | "append"; +} + +export interface PatchResolution { + kind: "patch"; + old_string: string; + new_string: string; + replace_all: boolean; +} + +export interface BatchResolution { + kind: "batch"; +} + +/** + * No operation fields were present at all. The caller picks the fallback + * error, because the correct wording differs by context (e.g. an explicitly + * empty `items: []` vs. no `items` key at all read differently to a caller + * even though both resolve to "none" here). + */ +export interface NoneResolution { + kind: "none"; +} + +export interface WriteModeError { + kind: "error"; + message: string; +} + +export type WriteModeResolution = + | FullWriteResolution + | PatchResolution + | BatchResolution + | NoneResolution + | WriteModeError; + +const VALID_SHAPES = + "Valid call shapes: (1) full write/append — doc_type + content, optional mode; " + + "(2) patch — doc_type + old_string, optional new_string/replace_all; " + + "(3) batch — items[] only, with no top-level content/old_string/new_string/replace_all/mode."; + +/** + * "Meaningfully present" = defined and non-empty. Empty-string `content` at + * the top level of a batch call is a documented neutral placeholder some + * callers still send; `old_string` activates patch mode on presence alone + * (even "") — that's the documented "patch an empty document" workaround. + */ +function isMeaningful(value: string | undefined): boolean { + return value !== undefined && value.length > 0; +} + +function err(message: string): WriteModeError { + return { kind: "error", message: `${message} ${VALID_SHAPES}` }; +} + +/** + * Resolve a single write-tool payload to exactly one operation mode, or an + * actionable error naming the field(s) that make the call ambiguous. Full + * truth table lives in write-mode.test.ts, which pins every row. + * + * Rule precedence when a call violates more than one rule: rule 4 (items + * conflict) first, since it's independent of the other three; then rule 2 + * (dangling patch modifiers), rule 3 (append + patch), rule 1 (content + + * old_string). Deterministic — callers always get exactly one message. + */ +export function resolveWriteMode(fields: WriteModeFields): WriteModeResolution { + const hasItems = fields.hasItems === true; + const hasOldString = fields.old_string !== undefined; + const hasNewString = fields.new_string !== undefined; + const hasReplaceAll = fields.replace_all !== undefined; + const hasMode = fields.mode !== undefined; + const meaningfulContent = isMeaningful(fields.content); + + // Rule 4: items[] + top-level operation field. content is exempt when + // present-but-empty (documented neutral placeholder). + if (hasItems) { + const offending = [ + meaningfulContent ? "content" : null, + hasOldString ? "old_string" : null, + hasNewString ? "new_string" : null, + hasReplaceAll ? "replace_all" : null, + hasMode ? "mode" : null, + ].filter((field): field is string => field !== null); + + if (offending.length > 0) { + return err( + `${offending.join(", ")} cannot be supplied alongside items[]: batch mode uses only the per-item fields inside items[], so top-level operation fields would be silently ignored.`, + ); + } + + return { kind: "batch" }; + } + + // Rule 2: new_string/replace_all only configure a patch; without + // old_string they were previously silently dropped. + if (!hasOldString && (hasNewString || hasReplaceAll)) { + const offending = [ + hasNewString ? "new_string" : null, + hasReplaceAll ? "replace_all" : null, + ].filter((field): field is string => field !== null); + return err( + `${offending.join(", ")} supplied without old_string: ${offending.join(" and ")} only configure patch mode, which activates when old_string is present.`, + ); + } + + // Rule 3: patch mode has no append variant — it always replaces in place. + if (hasOldString && fields.mode === "append") { + return err('mode: "append" cannot be combined with old_string/new_string/replace_all.'); + } + + // Rule 1: two conflicting operations named in the same call. mode: + // "replace" + old_string is not flagged — "replace" is the default and + // matches what patch mode already does. + if (hasOldString && meaningfulContent) { + return err("content and old_string cannot be supplied together."); + } + + if (hasOldString) { + return { + kind: "patch", + old_string: fields.old_string as string, + new_string: fields.new_string ?? "", + replace_all: fields.replace_all ?? false, + }; + } + + if (fields.content !== undefined) { + return { kind: "full-write", content: fields.content, mode: fields.mode ?? "replace" }; + } + + return { kind: "none" }; +} diff --git a/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts index f7b501ae..18f98c03 100644 --- a/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts @@ -550,4 +550,182 @@ describe("goop_write_db tool", () => { ); }); }); + + // ----------------------------------------------------------------------- + // Ambiguous/invalid write-mode combinations (W4.T2) — one-shot rejection, + // zero mutation. Mirrors the four rules in shared/write-mode.ts. + // ----------------------------------------------------------------------- + + describe("rejects ambiguous write-mode combinations (W4.T2)", () => { + it("rule 1: rejects meaningful content and old_string together, and does not mutate", async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", content: "# Full replacement", old_string: "world", new_string: "x" }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_db"); + expect(result).toContain("content and old_string cannot be supplied together"); + expect(result).toContain("Valid call shapes"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + }); + + it("rule 2: rejects new_string without old_string, and does not mutate", async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", content: "# Should not be written", new_string: "x" }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_db"); + expect(result).toContain("new_string"); + expect(result).toContain("supplied without old_string"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + }); + + it("rule 2: rejects replace_all without old_string, and does not mutate", async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", content: "# Should not be written", replace_all: true }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_db"); + expect(result).toContain("replace_all"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + }); + + it('rule 3: rejects mode: "append" combined with old_string, and does not mutate', async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { doc_type: "spec", old_string: "world", new_string: "GoopSpec", mode: "append" }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_db"); + expect(result).toContain('mode: "append"'); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + }); + + it("rule 4: rejects meaningful content alongside items[], and does not mutate any document", async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + content: "# Real top-level content", + items: [{ doc_type: "blueprint", content: "# Blueprint" }], + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_db"); + expect(result).toContain("content"); + expect(result).toContain("items[]"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + expect(ctx.db.getDocument("default", "blueprint")).toBeNull(); + }); + + it("rule 4: rejects old_string alongside items[], and does not mutate any document", async () => { + ctx.db.upsertDocument("default", "spec", "Hello world"); + + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + old_string: "world", + new_string: "GoopSpec", + items: [{ doc_type: "blueprint", content: "# Blueprint" }], + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_db"); + expect(result).toContain("old_string"); + expect(result).toContain("items[]"); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + expect(ctx.db.getDocument("default", "blueprint")).toBeNull(); + }); + + it("rule 4: rejects mode alongside items[], and does not mutate any document", async () => { + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + mode: "append", + items: [{ doc_type: "blueprint", content: "# Blueprint" }], + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_db"); + expect(result).toContain("mode"); + expect(result).toContain("items[]"); + expect(ctx.db.getDocument("default", "blueprint")).toBeNull(); + }); + + it("rule 4: does NOT reject empty-string content alongside items[] (documented neutral placeholder)", async () => { + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + content: "", + items: [{ doc_type: "blueprint", content: "# Blueprint" }], + }, + toolCtx, + ); + + expect(result).toContain("1/1 succeeded"); + expect(ctx.db.getDocument("default", "blueprint")?.content).toBe("# Blueprint"); + }); + + it("per-item validation: rejects a batch item that mixes content and old_string, rolling back the whole batch", async () => { + ctx.db.upsertDocument("default", "spec", "Original spec"); + + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + content: "", + items: [ + { doc_type: "blueprint", content: "# Should be rolled back" }, + { doc_type: "spec", content: "# Ambiguous", old_string: "Original", new_string: "x" }, + ], + }, + toolCtx, + ); + + expect(result).toContain("Batch write-db"); + expect(result).toContain("0/2 succeeded"); + // The first item's write must not survive despite validating fine on + // its own — the whole batch transaction rolls back on any item error. + expect(ctx.db.getDocument("default", "blueprint")).toBeNull(); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Original spec"); + }); + + it("per-item validation: rejects a batch item with new_string but no old_string", async () => { + const tool = createGoopWriteDbTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + content: "", + items: [{ doc_type: "spec", content: "# Doc", new_string: "x" }], + }, + toolCtx, + ); + + expect(result).toContain("0/1 succeeded"); + expect(result).toContain("supplied without old_string"); + expect(ctx.db.getDocument("default", "spec")).toBeNull(); + }); + }); }); diff --git a/packages/opencode-plugin/src/tools/goop-write-db/index.ts b/packages/opencode-plugin/src/tools/goop-write-db/index.ts index dfc52388..3d222e98 100644 --- a/packages/opencode-plugin/src/tools/goop-write-db/index.ts +++ b/packages/opencode-plugin/src/tools/goop-write-db/index.ts @@ -15,6 +15,7 @@ import { DOC_TYPES } from "../../features/db/types.js"; import type { DocType } from "../../features/db/types.js"; import { patchContent } from "../../shared/content-patch.js"; import { DOC_TYPE_FILENAMES, renderSidecars } from "../../shared/render-sidecars.js"; +import { resolveWriteMode } from "../../shared/write-mode.js"; interface PatchArgs { old_string?: string; @@ -30,10 +31,6 @@ interface WriteDbItem { type WriteDbItemWithPatch = WriteDbItem & PatchArgs; -function isPatchActive(patch: PatchArgs): boolean { - return patch.old_string !== undefined; -} - /** * Render the persisted document length for a success message. An explicit * "empty document" label distinguishes an intentional zero-length write @@ -53,45 +50,12 @@ function patchExistingDocument( db: PluginContext["db"], workflowId: string, docType: DocType, - patch: PatchArgs, + oldString: string, + newString: string, + replaceAll: boolean, ): import("../../shared/content-patch.js").PatchResult { - if (!isPatchActive(patch)) { - return { - ok: false, - matchCount: 0, - error: "old_string is required for patch mode", - }; - } - const existing = db.getDocument(workflowId, docType)?.content ?? ""; - return patchContent(existing, patch.old_string as string, patch.new_string ?? "", { - replaceAll: patch.replace_all ?? false, - }); -} - -function resolveContentForWrite( - db: PluginContext["db"], - workflowId: string, - item: WriteDbItemWithPatch, -): string { - if (isPatchActive(item)) { - const patchResult = patchExistingDocument(db, workflowId, item.doc_type, { - old_string: item.old_string, - new_string: item.new_string, - replace_all: item.replace_all, - }); - if (!patchResult.ok) { - throw new Error(patchResult.error ?? "Patch failed"); - } - - return patchResult.content as string; - } - - if (item.content === undefined) { - throw new Error("content is required when old_string is not provided"); - } - - return item.content; + return patchContent(existing, oldString, newString, { replaceAll }); } // --------------------------------------------------------------------------- @@ -150,26 +114,74 @@ export function createGoopWriteDbTool(ctx: PluginContext): ToolDefinition { // runBatch/formatBatchResult path and report per-item results // consistently with their single-item path, so no parity change was // required. Recorded to prevent re-auditing these two tools. - if (Array.isArray(args.items) && args.items.length > 0) { - const workflowId = args.workflow_id ?? ctx.stateManager.getState().activeWorkflowId; - const result = runBatch(ctx.db, args.items, (item) => { - const itemMode = item.mode ?? "replace"; - const itemContent = resolveContentForWrite(ctx.db, workflowId, item); + const hasItems = Array.isArray(args.items) && args.items.length > 0; + const resolution = resolveWriteMode({ + content: args.content, + mode: args.mode, + old_string: args.old_string, + new_string: args.new_string, + replace_all: args.replace_all, + hasItems, + }); + + if (resolution.kind === "error") { + return `Error in goop_write_db: ${resolution.message}`; + } + + const workflowId = args.workflow_id ?? ctx.stateManager.getState().activeWorkflowId; + + if (resolution.kind === "batch") { + const result = runBatch(ctx.db, args.items as WriteDbItemWithPatch[], (item) => { + const itemResolution = resolveWriteMode({ + content: item.content, + mode: item.mode, + old_string: item.old_string, + new_string: item.new_string, + replace_all: item.replace_all, + }); + + if (itemResolution.kind === "error") { + throw new Error(itemResolution.message); + } + if (itemResolution.kind === "batch" || itemResolution.kind === "none") { + throw new Error("content is required when old_string is not provided"); + } ctx.db.deleteSections(workflowId, item.doc_type); - if (itemMode === "append") { - ctx.db.appendDocument(workflowId, item.doc_type, itemContent); + if (itemResolution.kind === "patch") { + const patchResult = patchExistingDocument( + ctx.db, + workflowId, + item.doc_type, + itemResolution.old_string, + itemResolution.new_string, + itemResolution.replace_all, + ); + if (!patchResult.ok) { + throw new Error(patchResult.error ?? "Patch failed"); + } + ctx.db.upsertDocument(workflowId, item.doc_type, patchResult.content as string); + ctx.db.appendEvent(workflowId, "doc_write", { + doc_type: item.doc_type, + mode: "patch", + timestamp: Date.now(), + }); + return `wrote ${item.doc_type}`; + } + + if (itemResolution.mode === "append") { + ctx.db.appendDocument(workflowId, item.doc_type, itemResolution.content); if (item.doc_type === "chronicle") { - ctx.db.appendChronicleEvent(workflowId, itemContent); + ctx.db.appendChronicleEvent(workflowId, itemResolution.content); } } else { - ctx.db.upsertDocument(workflowId, item.doc_type, itemContent); + ctx.db.upsertDocument(workflowId, item.doc_type, itemResolution.content); } ctx.db.appendEvent(workflowId, "doc_write", { doc_type: item.doc_type, - mode: itemMode, + mode: itemResolution.mode, timestamp: Date.now(), }); @@ -180,15 +192,22 @@ export function createGoopWriteDbTool(ctx: PluginContext): ToolDefinition { return formatBatchResult(result, "write-db"); } - const workflowId = args.workflow_id ?? ctx.stateManager.getState().activeWorkflowId; - const mode = args.mode ?? "replace"; + if (resolution.kind === "none") { + if (args.items?.length === 0) { + return "Error in goop_write_db: items[] array is empty and no document content was provided"; + } + return "Error in goop_write_db: content is required when old_string is not provided"; + } - if (isPatchActive(args)) { - const patchResult = patchExistingDocument(ctx.db, workflowId, args.doc_type, { - old_string: args.old_string, - new_string: args.new_string, - replace_all: args.replace_all, - }); + if (resolution.kind === "patch") { + const patchResult = patchExistingDocument( + ctx.db, + workflowId, + args.doc_type, + resolution.old_string, + resolution.new_string, + resolution.replace_all, + ); if (!patchResult.ok) { return `Error in goop_write_db: ${patchResult.error}`; } @@ -209,45 +228,33 @@ export function createGoopWriteDbTool(ctx: PluginContext): ToolDefinition { return `Patched ${args.doc_type} for workflow '${workflowId}' (${describeWriteLength(sidecarContent.length)}, mode: patch). Sidecar: .goopspec/${workflowId}/${filename}`; } - if ( - args.items?.length === 0 && - args.content === undefined && - args.old_string === undefined - ) { - return "Error in goop_write_db: items[] array is empty and no document content was provided"; - } - - if (args.content === undefined) { - return "Error in goop_write_db: content is required when old_string is not provided"; - } - - // Persist to DB + // Persist to DB (full-document write/append) ctx.db.deleteSections(workflowId, args.doc_type); - if (mode === "append") { - ctx.db.appendDocument(workflowId, args.doc_type, args.content); + if (resolution.mode === "append") { + ctx.db.appendDocument(workflowId, args.doc_type, resolution.content); // Also insert chronicle event row when appending chronicle if (args.doc_type === "chronicle") { - ctx.db.appendChronicleEvent(workflowId, args.content); + ctx.db.appendChronicleEvent(workflowId, resolution.content); } } else { - ctx.db.upsertDocument(workflowId, args.doc_type, args.content); + ctx.db.upsertDocument(workflowId, args.doc_type, resolution.content); } // Log doc_write event ctx.db.appendEvent(workflowId, "doc_write", { doc_type: args.doc_type, - mode, + mode: resolution.mode, timestamp: Date.now(), }); // Read back the full document for sidecar (important for append mode) const updatedDoc = ctx.db.getDocument(workflowId, args.doc_type); - const sidecarContent = updatedDoc?.content ?? args.content; + const sidecarContent = updatedDoc?.content ?? resolution.content; renderSidecars(ctx, workflowId); const filename = DOC_TYPE_FILENAMES[args.doc_type]; - return `Written ${args.doc_type} for workflow '${workflowId}' (${describeWriteLength(sidecarContent.length)}, mode: ${mode}). Sidecar: .goopspec/${workflowId}/${filename}`; + return `Written ${args.doc_type} for workflow '${workflowId}' (${describeWriteLength(sidecarContent.length)}, mode: ${resolution.mode}). Sidecar: .goopspec/${workflowId}/${filename}`; } catch (error: unknown) { const msg = error instanceof Error ? error.message : String(error); return `Error in goop_write_db: ${msg}`; From 792a25937ce2da445c77a01742a300d8742dea55 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:40:58 -0700 Subject: [PATCH 16/22] fix(plugin): apply write-mode ambiguity fix at shared cause across sibling tools (W4.T3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - goop_write_section: reuse resolveWriteMode() for both the single-section and per-item batch paths, since it shares goop_write_db's content/ old_string/new_string/replace_all shape (no append mode). content + old_string together and items[] + meaningful top-level operation fields are now rejected before mutation instead of old_string silently winning. - goop_save_note: add a note-specific resolveNoteMode() mirroring resolveWriteMode()'s intent for a CREATE-or-PATCH-keyed-on-note_id shape that doesn't map onto the generic content/old_string fields. Rejects note_id + meaningful create fields together, and patch-only fields (old_string/new_string/replace_all) supplied without note_id, in both the single and batch paths. - goop_write_wave: audited against the one-shot standard; already the reference implementation. Added a missing regression test for task_update + task_updates[] supplied together (already guarded by the existing ignoredFields mechanism, previously untested for this pair). No production change. - goop_blocker: audited and found the analogous defect — items[] silently ignored meaningful top-level action/description/severity/wave_id/id/ resolution/status. Added the same ignoredFields rejection used by goop_write_wave (workflow_id excluded: it is genuinely consumed as the per-item default). All W4.T1 positive fixtures remain green, including empty-content/ section_key/note-field neutral batch placeholders. --- .../src/tools/goop-blocker/index.test.ts | 53 ++++++++++ .../src/tools/goop-blocker/index.ts | 14 +++ .../src/tools/goop-save-note/index.test.ts | 90 +++++++++++++++++ .../src/tools/goop-save-note/index.ts | 88 ++++++++++++++--- .../tools/goop-write-section/index.test.ts | 96 +++++++++++++++++++ .../src/tools/goop-write-section/index.ts | 63 +++++++++--- .../src/tools/goop-write-wave/index.test.ts | 31 ++++++ 7 files changed, 409 insertions(+), 26 deletions(-) diff --git a/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts b/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts index ce58d267..3da2c08a 100644 --- a/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-blocker/index.test.ts @@ -327,6 +327,59 @@ describe("goop_blocker tool", () => { expect(openBlockers[0].status).toBe("open"); }); + // ----------------------------------------------------------------------- + // Ambiguity rejection (W4.T3 — top-level operation fields alongside items[]) + // ----------------------------------------------------------------------- + + it("rejects a meaningful top-level action alongside items[], with zero mutation", async () => { + const blockerTool = createGoopBlockerTool(ctx); + + const result = await blockerTool.execute( + { + action: "open", + description: "Leaked top-level open", + items: [{ action: "open", description: "Batch A" }], + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_blocker"); + expect(result).toContain("action"); + expect(result).toContain("items[]"); + expect(ctx.db.getBlockers("default").length).toBe(0); + }); + + it("rejects a meaningful top-level description alongside items[], with zero mutation", async () => { + const blockerTool = createGoopBlockerTool(ctx); + + const result = await blockerTool.execute( + { + description: "Leaked description", + items: [{ action: "open", description: "Batch A" }], + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_blocker"); + expect(result).toContain("description"); + expect(ctx.db.getBlockers("default").length).toBe(0); + }); + + it("still accepts workflow_id alongside items[] because it is genuinely consumed as the default", async () => { + const blockerTool = createGoopBlockerTool(ctx); + + const result = await blockerTool.execute( + { + workflow_id: "custom-wf", + items: [{ action: "open", description: "Scoped blocker" }], + }, + toolCtx, + ); + + expect(result).toContain("1/1 succeeded"); + expect(ctx.db.getBlockers("custom-wf", "open")).toHaveLength(1); + }); + it("surfaces the completed-wave warning in batch items[] mode", async () => { ctx.db.upsertWave("default", { wave_number: 1, status: "completed" }); const blockerTool = createGoopBlockerTool(ctx); diff --git a/packages/opencode-plugin/src/tools/goop-blocker/index.ts b/packages/opencode-plugin/src/tools/goop-blocker/index.ts index 160a7d9e..8ce84893 100644 --- a/packages/opencode-plugin/src/tools/goop-blocker/index.ts +++ b/packages/opencode-plugin/src/tools/goop-blocker/index.ts @@ -203,6 +203,20 @@ export function createGoopBlockerTool(ctx: PluginContext): ToolDefinition { const workflowId = args.workflow_id ?? ctx.stateManager.getState().activeWorkflowId; if (Array.isArray(args.items) && args.items.length > 0) { + // workflow_id is excluded: it is genuinely used as the per-item default below. + const ignoredFields = [ + args.action !== undefined ? "action" : null, + args.description !== undefined ? "description" : null, + args.severity !== undefined ? "severity" : null, + args.wave_id !== undefined ? "wave_id" : null, + args.id !== undefined ? "id" : null, + args.resolution !== undefined ? "resolution" : null, + args.status !== undefined ? "status" : null, + ].filter((field): field is string => field !== null); + if (ignoredFields.length > 0) { + return `Error in goop_blocker: ${ignoredFields.join(", ")} cannot be supplied alongside items[]: batch mode uses only the per-item fields inside items[], so top-level operation fields would be silently ignored.`; + } + const touchedWorkflows = new Set(); const result = runBatch(ctx.db, args.items, (item) => { const itemWorkflowId = item.workflow_id ?? workflowId; diff --git a/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts b/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts index f3f5a8a3..56dfaedf 100644 --- a/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-save-note/index.test.ts @@ -540,6 +540,96 @@ describe("goop_save_note tool", () => { }); }); + // ----------------------------------------------------------------------- + // Ambiguity rejection (W4.T3 — note-specific mirror of resolveWriteMode()) + // ----------------------------------------------------------------------- + + describe("ambiguity rejection", () => { + it("rejects note_id + a meaningful create field together, with zero mutation", async () => { + const tool = createGoopSaveNoteTool(ctx); + const createResult = await tool.execute( + { title: "Original", body: "alpha beta", tags: ["p"], source_agent: "agent" }, + toolCtx, + ); + const noteId = String(createResult).match(/fn_\d{8}_[a-z0-9]+/)?.[0] ?? ""; + + const result = await tool.execute( + { + note_id: noteId, + title: "Should not apply", + old_string: "beta", + new_string: "BETA", + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_save_note"); + expect(result).toContain("title"); + expect(result).toContain("cannot be supplied alongside note_id"); + expect(ctx.db.getNoteById(noteId)?.body).toBe("alpha beta"); + expect(ctx.db.getNoteById(noteId)?.title).toBe("Original"); + }); + + it("rejects old_string without note_id even when create fields are also present, with zero mutation", async () => { + const tool = createGoopSaveNoteTool(ctx); + const result = await tool.execute( + { + title: "Would-be note", + body: "Body", + tags: ["t"], + source_agent: "agent", + old_string: "x", + new_string: "y", + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_save_note"); + expect(result).toContain("old_string"); + expect(result).toContain("supplied without note_id"); + expect(ctx.db.searchNotes("Would-be note")).toEqual([]); + }); + + it("rejects a batch item that supplies note_id and a meaningful create field, rolling back the batch", async () => { + const tool = createGoopSaveNoteTool(ctx); + const createResult = await tool.execute( + { title: "Batch target", body: "alpha beta", tags: ["p"], source_agent: "agent" }, + toolCtx, + ); + const noteId = String(createResult).match(/fn_\d{8}_[a-z0-9]+/)?.[0] ?? ""; + + const result = await tool.execute( + { + title: "", + body: "", + tags: [], + source_agent: "agent", + items: [ + { title: "Fresh", body: "Fresh body", tags: ["n"], source_agent: "agent" }, + { note_id: noteId, body: "Should not apply", old_string: "beta", new_string: "BETA" }, + ], + }, + toolCtx, + ); + + expect(result).toContain("0/2 succeeded"); + expect(result).toContain("cannot be supplied alongside note_id"); + expect(ctx.db.searchNotes("Fresh body")).toEqual([]); + expect(ctx.db.getNoteById(noteId)?.body).toBe("alpha beta"); + }); + + it("names both valid shapes in the note_id conflict rejection message", async () => { + const tool = createGoopSaveNoteTool(ctx); + const result = await tool.execute( + { note_id: "fn_20260618_missing0001", title: "conflict", old_string: "x" }, + toolCtx, + ); + + expect(result).toContain("create"); + expect(result).toContain("patch"); + }); + }); + // ----------------------------------------------------------------------- // Backward compatibility // ----------------------------------------------------------------------- diff --git a/packages/opencode-plugin/src/tools/goop-save-note/index.ts b/packages/opencode-plugin/src/tools/goop-save-note/index.ts index a4a5fc08..f0882630 100644 --- a/packages/opencode-plugin/src/tools/goop-save-note/index.ts +++ b/packages/opencode-plugin/src/tools/goop-save-note/index.ts @@ -74,6 +74,68 @@ function validateCreateFields(item: NoteFields): { ok: true } | { ok: false; err return { ok: true }; } +// --------------------------------------------------------------------------- +// Note-specific write-mode resolution. A note is CREATE-or-PATCH keyed on +// `note_id` presence (not a content/old_string pair), so resolveWriteMode() +// doesn't fit — this mirrors its intent for the note's own field shape. +// --------------------------------------------------------------------------- + +const NOTE_VALID_SHAPES = + "Valid call shapes: (1) create — title + body + tags + source_agent; " + + "(2) patch — note_id + old_string, optional new_string/replace_all."; + +type NoteModeResolution = + | { kind: "create" } + | { kind: "patch" } + | { kind: "error"; message: string }; + +function noteErr(message: string): NoteModeResolution { + return { kind: "error", message: `${message} ${NOTE_VALID_SHAPES}` }; +} + +function meaningfulCreateFields(item: NoteFields): string[] { + const offending: string[] = []; + if (item.title !== undefined && item.title.length > 0) offending.push("title"); + if (item.body !== undefined && item.body.length > 0) offending.push("body"); + if (item.tags !== undefined && normalizeTags(item.tags).length > 0) offending.push("tags"); + if (item.source_agent !== undefined && item.source_agent.length > 0) { + offending.push("source_agent"); + } + return offending; +} + +function meaningfulPatchFields(item: NotePatchArgs): string[] { + const offending: string[] = []; + if (item.old_string !== undefined) offending.push("old_string"); + if (item.new_string !== undefined) offending.push("new_string"); + if (item.replace_all !== undefined) offending.push("replace_all"); + return offending; +} + +function resolveNoteMode(item: NoteFields & NotePatchArgs): NoteModeResolution { + if (item.note_id !== undefined) { + const createFields = meaningfulCreateFields(item); + if (createFields.length > 0) { + return noteErr( + `${createFields.join(", ")} cannot be supplied alongside note_id: note_id activates patch mode, which only accepts old_string/new_string/replace_all.`, + ); + } + if (item.old_string === undefined) { + return noteErr("old_string is required when note_id is provided for patch mode."); + } + return { kind: "patch" }; + } + + const patchFields = meaningfulPatchFields(item); + if (patchFields.length > 0) { + return noteErr( + `${patchFields.join(", ")} supplied without note_id: ${patchFields.join(" and ")} only configure patch mode, which activates when note_id is present.`, + ); + } + + return { kind: "create" }; +} + // --------------------------------------------------------------------------- // Tag normalization // --------------------------------------------------------------------------- @@ -185,13 +247,14 @@ export function createGoopSaveNoteTool(ctx: PluginContext): ToolDefinition { try { if (Array.isArray(args.items) && args.items.length > 0) { const result = runBatch(ctx.db, args.items, (item) => { - if (item.note_id !== undefined) { - if (item.old_string === undefined) { - throw new Error("old_string is required when note_id is provided for patch mode"); - } + const itemResolution = resolveNoteMode(item); + if (itemResolution.kind === "error") { + throw new Error(itemResolution.message); + } - const updateResult = ctx.db.updateNote(item.note_id, { - oldString: item.old_string, + if (itemResolution.kind === "patch") { + const updateResult = ctx.db.updateNote(item.note_id as string, { + oldString: item.old_string as string, newString: item.new_string ?? "", replaceAll: item.replace_all ?? false, }); @@ -232,13 +295,14 @@ export function createGoopSaveNoteTool(ctx: PluginContext): ToolDefinition { return formatBatchResult(result, "save-note"); } - if (args.note_id !== undefined) { - if (args.old_string === undefined) { - return "Error in goop_save_note: old_string is required when note_id is provided for patch mode"; - } + const topResolution = resolveNoteMode(args); + if (topResolution.kind === "error") { + return `Error in goop_save_note: ${topResolution.message}`; + } - const updateResult = ctx.db.updateNote(args.note_id, { - oldString: args.old_string, + if (topResolution.kind === "patch") { + const updateResult = ctx.db.updateNote(args.note_id as string, { + oldString: args.old_string as string, newString: args.new_string ?? "", replaceAll: args.replace_all ?? false, }); diff --git a/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts index 744f0c1c..248fed78 100644 --- a/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-section/index.test.ts @@ -439,6 +439,102 @@ describe("goop_write_section tool", () => { }); }); + // ----------------------------------------------------------------------- + // Ambiguity rejection (W4.T3 — shared cause with goop_write_db) + // ----------------------------------------------------------------------- + + describe("ambiguity rejection", () => { + it("rejects content + old_string supplied together, with zero mutation", async () => { + ctx.db.upsertSection("default", "spec", "overview", "Original"); + + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + section_key: "overview", + content: "# New", + old_string: "old", + new_string: "new", + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_section"); + expect(result).toContain("content and old_string cannot be supplied together"); + expect(ctx.db.getSection("default", "spec", "overview")?.content).toBe("Original"); + }); + + it("rejects new_string supplied without old_string, with zero mutation", async () => { + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { doc_type: "spec", section_key: "overview", content: "# Doc", new_string: "x" }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_section"); + expect(result).toContain("new_string"); + expect(result).toContain("supplied without old_string"); + expect(ctx.db.getSection("default", "spec", "overview")).toBeNull(); + }); + + it("rejects meaningful old_string alongside items[], with zero mutation", async () => { + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + section_key: "", + old_string: "leaked", + items: [{ doc_type: "spec", section_key: "intro", content: "# Intro" }], + }, + toolCtx, + ); + + expect(result).toContain("Error in goop_write_section"); + expect(result).toContain("old_string"); + expect(result).toContain("items[]"); + expect(ctx.db.getSection("default", "spec", "intro")).toBeNull(); + }); + + it("rejects an item that supplies both content and old_string, rolling back the whole batch", async () => { + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { + doc_type: "spec", + section_key: "", + content: "", + items: [ + { doc_type: "spec", section_key: "intro", content: "# Intro" }, + { + doc_type: "spec", + section_key: "conflict", + content: "# New", + old_string: "old", + new_string: "new", + }, + ], + }, + toolCtx, + ); + + expect(result).toContain("0/2 succeeded"); + expect(result).toContain("content and old_string cannot be supplied together"); + // Batch is atomic — the valid first item must not have persisted either. + expect(ctx.db.getSection("default", "spec", "intro")).toBeNull(); + }); + + it("names both valid shapes in the rejection message", async () => { + const tool = createGoopWriteSectionTool(ctx); + const result = await tool.execute( + { doc_type: "spec", section_key: "overview", content: "# New", old_string: "old" }, + toolCtx, + ); + + expect(result).toContain("full write/append"); + expect(result).toContain("patch"); + expect(result).toContain("batch"); + }); + }); + // ----------------------------------------------------------------------- // Message accuracy — write size reporting // ----------------------------------------------------------------------- diff --git a/packages/opencode-plugin/src/tools/goop-write-section/index.ts b/packages/opencode-plugin/src/tools/goop-write-section/index.ts index 012bd804..71ff1426 100644 --- a/packages/opencode-plugin/src/tools/goop-write-section/index.ts +++ b/packages/opencode-plugin/src/tools/goop-write-section/index.ts @@ -15,6 +15,7 @@ import { DOC_TYPES } from "../../features/db/types.js"; import type { DocType } from "../../features/db/types.js"; import { patchContent } from "../../shared/content-patch.js"; import { DOC_TYPE_FILENAMES, renderSidecars } from "../../shared/render-sidecars.js"; +import { resolveWriteMode } from "../../shared/write-mode.js"; const MIGRATED_LEGACY_CONTENT_KEY = "_migrated-legacy-content"; @@ -51,11 +52,22 @@ export function createGoopWriteSectionTool(ctx: PluginContext): ToolDefinition { } function resolveSectionContent(workflowId: string, item: WriteSectionItem): string { - if (item.old_string !== undefined) { + const resolution = resolveWriteMode({ + content: item.content, + old_string: item.old_string, + new_string: item.new_string, + replace_all: item.replace_all, + }); + + if (resolution.kind === "error") { + throw new Error(resolution.message); + } + + if (resolution.kind === "patch") { const existing = ctx.db.getSection(workflowId, item.doc_type, item.section_key)?.content ?? ""; - const patchResult = patchContent(existing, item.old_string as string, item.new_string ?? "", { - replaceAll: item.replace_all ?? false, + const patchResult = patchContent(existing, resolution.old_string, resolution.new_string, { + replaceAll: resolution.replace_all, }); if (!patchResult.ok) { throw new Error(patchResult.error ?? "Patch failed"); @@ -64,11 +76,12 @@ export function createGoopWriteSectionTool(ctx: PluginContext): ToolDefinition { return patchResult.content as string; } - if (item.content === undefined) { - throw new Error("content is required when old_string is not provided"); + if (resolution.kind === "full-write") { + return resolution.content; } - return item.content; + // "none" or "batch" (nested items[] is not a supported per-item shape). + throw new Error("content is required when old_string is not provided"); } function writeSection( @@ -174,6 +187,17 @@ export function createGoopWriteSectionTool(ctx: PluginContext): ToolDefinition { } if (Array.isArray(args.items) && args.items.length > 0) { + const topResolution = resolveWriteMode({ + content: args.content, + old_string: args.old_string, + new_string: args.new_string, + replace_all: args.replace_all, + hasItems: true, + }); + if (topResolution.kind === "error") { + return `Error in goop_write_section: ${topResolution.message}`; + } + const checkedDocTypes = new Set(); const result = runBatch(ctx.db, args.items, (item) => { const shouldCheckForLegacyContent = !checkedDocTypes.has(item.doc_type); @@ -195,11 +219,26 @@ export function createGoopWriteSectionTool(ctx: PluginContext): ToolDefinition { return "Error in goop_write_section: section_key is required for action 'write'"; } - if (args.old_string !== undefined) { + const resolution = resolveWriteMode({ + content: args.content, + old_string: args.old_string, + new_string: args.new_string, + replace_all: args.replace_all, + }); + + if (resolution.kind === "error") { + return `Error in goop_write_section: ${resolution.message}`; + } + + if (resolution.kind === "none" || resolution.kind === "batch") { + return "Error in goop_write_section: content is required when old_string is not provided"; + } + + if (resolution.kind === "patch") { const existing = ctx.db.getSection(workflowId, args.doc_type, args.section_key)?.content ?? ""; - const patchResult = patchContent(existing, args.old_string, args.new_string ?? "", { - replaceAll: args.replace_all ?? false, + const patchResult = patchContent(existing, resolution.old_string, resolution.new_string, { + replaceAll: resolution.replace_all, }); if (!patchResult.ok) { return `Error in goop_write_section: ${patchResult.error}`; @@ -221,14 +260,10 @@ export function createGoopWriteSectionTool(ctx: PluginContext): ToolDefinition { return `Patched section '${args.section_key}' for ${args.doc_type} in workflow '${workflowId}' (section: ${sectionContent.length} chars, assembled document: ${assembledContent.length} chars). Sidecar: .goopspec/${workflowId}/${filename}`; } - if (args.content === undefined) { - return "Error in goop_write_section: content is required when old_string is not provided"; - } - writeSection(workflowId, { doc_type: args.doc_type, section_key: args.section_key, - content: args.content, + content: resolution.content, position: args.position, }); diff --git a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts index e1339903..430b622b 100644 --- a/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-wave/index.test.ts @@ -1454,6 +1454,37 @@ describe("goop_write_wave write integrity", () => { expect(ctx.db.getWave("default", 2)?.status).toBe("pending"); }); + // W4.T3 audit: goop_write_wave is the reference implementation and was + // audited for the same silent-precedence pattern found in the sibling + // write tools. task_update (singular) and task_updates[] (bulk) are the + // one place a caller could plausibly send both by mistake; the tool + // already guards this via the same ignoredFields mechanism proven above, + // it was simply untested for this exact pair. No production change was + // needed — this test closes the coverage gap. + it("rejects task_update alongside task_updates[], with zero mutation", async () => { + const writeTool = createGoopWriteWaveTool(ctx); + await writeTool.execute( + { + wave_number: 3, + title: "Both-modes wave", + tasks: [{ task_index: 1, description: "Task" }], + }, + toolCtx, + ); + + const result = await writeTool.execute( + { + wave_number: 3, + task_update: { task_index: 1, status: "in_progress" }, + task_updates: [{ task_index: 1, status: "done" }], + }, + toolCtx, + ); + + expect(result).toContain("task_update cannot be supplied alongside task_updates batch mode"); + expect(ctx.db.getWaveTasks(ctx.db.getWave("default", 3)?.id ?? -1)[0].status).toBe("pending"); + }); + it("rejects terminal status regressions unless explicitly overridden", async () => { const writeTool = createGoopWriteWaveTool(ctx); await writeTool.execute( From 1a9ed8976ddc65a3d54bab3d575929918d9b6bfe Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:48:19 -0700 Subject: [PATCH 17/22] test(plugin): pin host-visible tool schema contract and one-shot retry-loop guarantee MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lock the V2 JSON Schema boundary (convertToolArgsToJsonSchema) for every createTools() entry: assert properties exist and `required` equals an explicit intended set per tool. Catches a new tool added without a contract entry and any drift in requiredness — the exact defect class that let optional patch fields leak into `required` and turn full-document writes into silent patches. Add a retry-loop regression proving the W4.T2 runtime validation returns a single actionable error (naming conflicting fields and valid shapes), performs no mutation, and differs from the prior silent-patch success so an agent cannot loop on the identical payload. Host-side V1 conversion remains outside plugin control (opencode #20807, #13618); documented in-file. Runtime validation is the real safety guarantee. --- .../opencode-plugin/src/core/tools-v2.test.ts | 194 ++++++++++++++++++ .../src/tools/goop-write-db/index.test.ts | 67 ++++++ 2 files changed, 261 insertions(+) diff --git a/packages/opencode-plugin/src/core/tools-v2.test.ts b/packages/opencode-plugin/src/core/tools-v2.test.ts index 920d8d24..0354abea 100644 --- a/packages/opencode-plugin/src/core/tools-v2.test.ts +++ b/packages/opencode-plugin/src/core/tools-v2.test.ts @@ -8,6 +8,7 @@ import { import { createTools } from "../tools/index.js"; import { convertToolArgsToJsonSchema, registerToolsV2 } from "./tools-v2.js"; import type { + V2JsonSchema, V2RuntimeContext, V2ToolCapability, V2ToolDefinition, @@ -126,3 +127,196 @@ describe("registerToolsV2()", () => { }); }); }); + +// --------------------------------------------------------------------------- +// Host-visible required-array contract (W4.T4) +// +// HOST-CONVERSION BOUNDARY: this block pins the JSON Schema the PLUGIN hands +// to the host through the V2 conversion path (convertToolArgsToJsonSchema → +// z.toJSONSchema from Zod v4). Host-side V1 conversion — the host running its +// own z.toJSONSchema (or the older zod-to-json-schema@3.x) over our Zod args +// — is OUTSIDE plugin control and has independent, documented defects: +// - opencode #20807: zod-to-json-schema@3.x is broken with Zod v4 and can +// emit a schema with no `properties` and no `required`. +// - opencode #13618: a missing `required` key on a schema that has +// `properties` is rejected by the Claude API. +// We cannot test what the host does with our schema after we hand it over. +// We CAN and DO pin here that the schema the plugin emits at its boundary is +// correct: every tool declares `properties`, and `required` contains exactly +// the intended identifiers and nothing else. +// +// Runtime validation (shared/write-mode.ts and the per-tool mode checks from +// W4.T2/T3) remains the real safety guarantee: even if a host-side conversion +// defect or a confused model sends an optional field as if it were required, +// the tool rejects the ambiguous payload with a one-shot actionable error +// before any mutation occurs. See goop-write-db/index.test.ts +// "one-shot error prevents an identical retry loop" for that regression. +// +// A note on `.default()`: Zod v4 deliberately includes a `.default(...)` field +// in the JSON Schema `required` array because the *parsed output* always +// carries a value (the default). difftastic's `checkOnly` is therefore +// correctly listed below — this is distinct from the patch-field leakage +// defect, where a bare `.optional()` field (no default) must never appear. +// --------------------------------------------------------------------------- + +describe("convertToolArgsToJsonSchema() — host-visible required-array contract", () => { + const contractContexts: PluginContext[] = []; + + afterEach(() => { + for (const context of contractContexts.splice(0)) { + context.db.close(); + } + }); + + // Expected top-level `required` array for EVERY tool returned by + // createTools(). Update an entry ONLY when intentionally changing a tool's + // argument contract. Two failure modes are deliberate: + // - A new tool added to createTools() without an entry here fails the + // "every tool has a contract entry" test. + // - A schema change that drifts requiredness fails the per-tool + // properties+required test. + // Both force an explicit, reviewed contract update. + const EXPECTED_REQUIRED: Record = { + ast_grep: ["pattern", "language"], + background_cancel: ["job_id"], + background_command: ["command"], + background_status: [], + // checkOnly is `.optional().default(false)` — see the .default() note above. + difftastic: ["checkOnly"], + generate_image: ["prompt"], + goop_acceptance_audit: [], + goop_adl: ["action"], + goop_append_chronicle: [], + goop_blocker: [], + goop_boot: [], + goop_checkpoint: ["action"], + goop_compact: ["next_step"], + goop_create_pr: ["title", "body", "branch"], + goop_dashboard: [], + goop_get_global_config: [], + goop_infer_intent: ["transcript"], + goop_query_decisions: [], + goop_read_db: [], + goop_read_section: ["doc_type"], + goop_read_wave: [], + goop_reference: [], + // All create + patch fields are optional; runtime enforces per-mode rules. + goop_save_note: [], + goop_search_docs: ["query"], + goop_search_notes: [], + goop_setup: ["action"], + goop_spec: ["action"], + goop_state: ["action"], + goop_status: [], + goop_timeline: [], + goop_write_db: ["doc_type"], + goop_write_section: ["doc_type"], + goop_write_wave: [], + memory_forget: [], + memory_save: ["title", "content"], + memory_search: ["query"], + scip: ["action"], + slashcommand: ["command"], + }; + + function requiredOf(schema: V2JsonSchema): string[] { + return (schema.required as string[] | undefined) ?? []; + } + + function itemElementRequired(schema: V2JsonSchema, arrayProp: string): string[] { + const properties = schema.properties as Record | undefined; + const arraySchema = properties?.[arrayProp]; + const elementSchema = arraySchema?.items as V2JsonSchema | undefined; + return requiredOf(elementSchema ?? {}); + } + + it("every createTools() entry has an explicit expected-required contract entry", () => { + const ctx = createMockPluginContext(); + contractContexts.push(ctx); + const toolNames = Object.keys(createTools(ctx)).sort(); + const expectedNames = Object.keys(EXPECTED_REQUIRED).sort(); + + // Catches a new tool added to createTools() without a contract entry, and + // a stale entry left behind after a tool is removed. + expect(toolNames).toEqual(expectedNames); + }); + + it("every tool's converted schema declares properties and matches its pinned required array", () => { + const ctx = createMockPluginContext(); + contractContexts.push(ctx); + const tools = createTools(ctx); + + for (const [name, definition] of Object.entries(tools)) { + const schema = convertToolArgsToJsonSchema(definition.args); + + // opencode #20807: a host conversion defect can strip `properties` + // entirely. Pin that the plugin-side conversion always emits the key as + // an object. A zero-argument tool (goop_get_global_config) legitimately + // emits `properties: {}`, so we require the key be an object, not that + // it be non-empty. + const properties = schema.properties as Record | undefined; + expect(properties, `${name} must declare a properties object`).toBeDefined(); + expect(typeof properties, `${name} properties must be an object`).toBe("object"); + expect(properties, `${name} properties must not be null`).not.toBeNull(); + + // Zod v4's z.toJSONSchema OMITS the `required` key entirely when an + // object has no required fields (it does not emit `required: []`). + // That absent-key shape is the same one opencode #13618 documents as + // rejected by some providers — but forcing a present `required: []` + // would require a production change to the converter output, which is + // out of scope for this test-focused task. `requiredOf()` normalizes + // absence to `[]`, so the contract comparison is honest about what the + // plugin emits today; a future task that force-emits the key must + // update `requiredOf` or this assertion intentionally. + const expected = EXPECTED_REQUIRED[name].slice().sort(); + const actual = requiredOf(schema).slice().sort(); + expect(actual, `${name} required-array contract`).toEqual(expected); + } + }); + + it("no patch field (old_string/new_string/replace_all) appears in any tool's top-level required", () => { + // The defect this wave exists to prevent: an optional patch field leaking + // into `required` would force every caller to supply old_string/new_string, + // turning every full-document write into a silent patch call. Pin that no + // write tool's top-level schema ever requires a patch modifier. + const ctx = createMockPluginContext(); + contractContexts.push(ctx); + const tools = createTools(ctx); + const patchFields = ["old_string", "new_string", "replace_all"]; + + for (const [name, definition] of Object.entries(tools)) { + const schema = convertToolArgsToJsonSchema(definition.args); + const required = requiredOf(schema); + for (const field of patchFields) { + expect(required, `${name} must not require patch field '${field}'`).not.toContain(field); + } + } + }); + + it("goop_write_db items[] element requires only doc_type and omits patch fields from required", () => { + const ctx = createMockPluginContext(); + contractContexts.push(ctx); + const schema = convertToolArgsToJsonSchema(createTools(ctx).goop_write_db.args); + + expect(itemElementRequired(schema, "items").sort()).toEqual(["doc_type"]); + }); + + it("goop_write_section items[] element requires doc_type and section_key", () => { + const ctx = createMockPluginContext(); + contractContexts.push(ctx); + const schema = convertToolArgsToJsonSchema(createTools(ctx).goop_write_section.args); + + expect(itemElementRequired(schema, "items").sort()).toEqual(["doc_type", "section_key"]); + }); + + it("goop_save_note items[] element requires nothing (every field is optional)", () => { + const ctx = createMockPluginContext(); + contractContexts.push(ctx); + const schema = convertToolArgsToJsonSchema(createTools(ctx).goop_save_note.args); + + // No doc_type on note items; create fields and patch fields are all + // optional at the schema level and disambiguated at runtime. Pin that + // nothing leaked into required. + expect(itemElementRequired(schema, "items")).toEqual([]); + }); +}); diff --git a/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts b/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts index 18f98c03..3a0bfa42 100644 --- a/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts +++ b/packages/opencode-plugin/src/tools/goop-write-db/index.test.ts @@ -728,4 +728,71 @@ describe("goop_write_db tool", () => { expect(ctx.db.getDocument("default", "spec")).toBeNull(); }); }); + + // ----------------------------------------------------------------------- + // Retry-loop regression (W4.T4) — the one-shot error must differ from the + // prior silent-patch success so an agent cannot loop on the identical + // payload. Pin the runtime guarantee from W4.T2 (shared/write-mode.ts): + // the formerly-ambiguous call surfaces a single actionable message, performs + // no mutation, and yields a deterministic result on retry. + // ----------------------------------------------------------------------- + + describe("one-shot error prevents an identical retry loop (W4.T4)", () => { + it("returns an actionable error that differs from the prior silent-patch success", async () => { + // The incident this wave exists to prevent: an agent supplies BOTH + // content (intending a full-document write) AND old_string (because a + // host-side schema defect, or a confused model, marked it required). + // Before W4.T2, `isPatchActive(old_string)` silently chose patch mode, + // ignored content, and returned a "Patched ..." success — so the agent + // saw a success-shaped result, its full write never landed, and + // re-issuing the identical payload produced the identical misleading + // success forever. + ctx.db.upsertDocument("default", "spec", "Hello world"); + + const tool = createGoopWriteDbTool(ctx); + const payload = { + doc_type: "spec" as const, + content: "# Full document I intended to write", + old_string: "world", + new_string: "GoopSpec", + }; + const result = await tool.execute(payload, toolCtx); + + // (1) The output is an error, not a success-looking result. The + // contrast with the prior "Patched ... / Sidecar: ..." path is + // what breaks the loop — an agent can no longer mistake silence + // for success. + expect(result).toContain("Error in goop_write_db"); + expect(result).not.toContain("Patched"); + expect(result).not.toContain("Written"); + expect(result).not.toContain("Sidecar"); + + // (2) It names BOTH conflicting fields, so the agent knows exactly + // what to drop without guessing. + expect(result).toContain("content"); + expect(result).toContain("old_string"); + expect(result).toContain("content and old_string cannot be supplied together"); + + // (3) It names the valid call shapes, so the agent has a concrete + // correction rather than a generic "invalid input" that invites + // an identical retry with rearranged whitespace. + expect(result).toContain("Valid call shapes"); + expect(result).toContain("full write/append"); + expect(result).toContain("patch"); + expect(result).toContain("batch"); + + // (4) No mutation occurred — a retry with a corrected payload starts + // from the original document state, not a half-applied patch. + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + + // (5) Determinism: re-issuing the identical payload yields the + // identical actionable error. This is the retry-loop guarantee — + // the agent cannot stumble into a different (success-shaped) + // outcome by repeating the bad call. The error is stable and + // terminal until the agent actually changes the payload. + const retried = await tool.execute(payload, toolCtx); + expect(retried).toBe(result); + expect(ctx.db.getDocument("default", "spec")?.content).toBe("Hello world"); + }); + }); }); From a4b0eb10a1659da48724daf7f48939db8ae80bb3 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:05:50 -0700 Subject: [PATCH 18/22] test(plugin): prove the stage-gated verification lifecycle end-to-end (W5.T1) Single integration test file wires the seams that unit tests already cover in isolation through their real production entry points: - goop-wave-verifier registration via the V1 config hook and the V2 registerHooksV2 agent/catalog transform adapter (shared AGENT_ROLES path) - the real merged tool.execute.before guard chain (createHooks + DEFAULT_HOOK_FACTORIES) blocking/permitting goop-verifier and goop-wave-verifier by phase - goop_write_wave's wave-completion verification gate: zero rows and a failing row both block completion; a later pass row for the same check_name supersedes it (append-only, latest-per-check) - the real auto-progression hook advancing execute -> accept once the final wave carries verification evidence - goop_acceptance_audit surfacing the append-only fail+pass history Covers MH2, MH4, MH5, MH7. Verification: rtk proxy bun test packages/opencode-plugin/ --bail=3 --timeout=10000 (2606 pass, 0 fail); rtk proxy bun run --cwd packages/opencode-plugin typecheck (clean); focused biome check on the new file (clean). --- .../stage-gating.integration.test.ts | 518 ++++++++++++++++++ 1 file changed, 518 insertions(+) create mode 100644 packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts diff --git a/packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts b/packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts new file mode 100644 index 00000000..d5885e6e --- /dev/null +++ b/packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts @@ -0,0 +1,518 @@ +/** + * Stage-gated verification lifecycle — end-to-end integration proof. + * + * Wave 5 Task 1 (wave-verifier-gating). Unit tests already cover each seam + * (registration, the dispatch guard, the wave-completion gate, the + * auto-progression gate, the acceptance audit) in isolation. This file wires + * them together through their real production entry points — the same + * `PluginContext`, the same `GoopSpecDB`, the same `goop_write_wave` tool, + * the same merged `createHooks` pipeline, the same `registerHooksV2` + * adapter — to prove the *connected* path holds, not just its parts. + * + * Sequence (one flowing scenario, `it` blocks run in declaration order and + * share state through the describe-scoped `ctx`): + * 1. goop-wave-verifier registers through the V1 config hook and the V2 + * agent/catalog transform adapter (shared AGENT_ROLES-derived path). + * 2. In execute phase, the real merged `tool.execute.before` guard permits + * goop-wave-verifier and blocks goop-verifier. (MH5) + * 3. All wave 1 tasks complete, but completion is blocked with zero + * verification rows. (MH2) + * 4. A recorded fail row keeps completion blocked. (MH2) + * 5. Remediation is represented without dispatching a subagent; a later + * pass row for the SAME check_name supersedes the fail row and + * completion succeeds — proving latest-per-check semantics. (MH2, MH7) + * 6. Wave 1 is the final wave, so its completion (with verification + * evidence) permits the real auto-progression hook to advance + * execute → accept. (MH2) + * 7. In accept phase, the same merged guard flips: goop-verifier is + * permitted, goop-wave-verifier is blocked. (MH4, MH5) + * 8. `goop_acceptance_audit` surfaces the wave's verification rows, + * including both the historical fail row and the pass row that + * superseded it (append-only evidence). (MH2, MH7) + * + * @module features/enforcement/stage-gating.integration.test + */ + +import { afterAll, beforeAll, describe, expect, it } from "bun:test"; + +import { registerHooksV2 } from "../../core/hooks-v2.js"; +import type { SdkConfig, ToolResult } from "../../core/sdk-compat.js"; +import type { + V2AgentDraft, + V2AgentInfo, + V2CatalogDraft, + V2RuntimeContext, + V2SessionRequestEvent, + V2ToolExecuteAfterEvent, + V2ToolExecuteBeforeEvent, +} from "../../core/v2-compat.js"; +import { createAgentRegistrationHook } from "../../hooks/agent-registration.js"; +import { createAutoProgressionHook } from "../../hooks/auto-progression.js"; +import { DEFAULT_HOOK_FACTORIES, createHooks } from "../../hooks/index.js"; +import type { Hooks } from "../../hooks/types.js"; +import { IntentionalToolDenialError } from "../../hooks/utils.js"; +import { + type PluginContext, + createDefaultWorkflowState, + createMockPluginContext, + createMockToolContext, + setupTestEnvironment, +} from "../../test-utils.js"; +import { createGoopAcceptanceAuditTool } from "../../tools/goop-acceptance-audit/index.js"; +import { createGoopWriteWaveTool } from "../../tools/goop-write-wave/index.js"; + +// --------------------------------------------------------------------------- +// Test-local helpers +// --------------------------------------------------------------------------- + +function taskArgs(subagentType: string): { args: Record } { + return { + args: { description: "d", prompt: "p", subagent_type: subagentType }, + }; +} + +/** Extracts the `` envelope goop_acceptance_audit returns. */ +function parseAuditEnvelope(result: ToolResult | string): { + blockers: string; + verifications: string; + waves: string; +} { + const text = typeof result === "string" ? result : result.output; + const match = text.match(//); + if (!match) { + throw new Error( + `goop_acceptance_audit did not return the expected JSON envelope: ${text}`, + ); + } + return JSON.parse(match[1]); +} + +interface V2Registrations { + agentTransform?: (draft: V2AgentDraft) => void | Promise; + catalogTransform?: (draft: V2CatalogDraft) => void | Promise; +} + +/** + * Minimal real-shaped V2 runtime stub. Mirrors `createRuntimeContext` in + * `core/hooks-v2.test.ts`: session/tool capture the request and tool hooks so + * `registerHooksV2` runs its full registration path without throwing, while + * agent/catalog capture their transform callbacks so this test can invoke + * them directly with the exact draft under scrutiny. + */ +function createV2RuntimeStub(registrations: V2Registrations): V2RuntimeContext { + return { + session: { + create: async () => ({}), + get: async () => ({}), + prompt: async () => ({}), + command: async () => ({}), + synthetic: async () => ({}), + interrupt: async () => ({}), + hook: async ( + _event: "request", + _callback: (event: V2SessionRequestEvent) => void | Promise, + ) => {}, + }, + tool: { + transform: async () => {}, + hook: async ( + _event: "execute.before" | "execute.after", + _callback: + | ((event: V2ToolExecuteBeforeEvent) => void | Promise) + | ((event: V2ToolExecuteAfterEvent) => void | Promise), + ) => {}, + }, + agent: { + transform: async ( + callback: (draft: V2AgentDraft) => void | Promise, + ) => { + registrations.agentTransform = callback; + }, + reload: async () => {}, + }, + catalog: { + transform: async ( + callback: (draft: V2CatalogDraft) => void | Promise, + ) => { + registrations.catalogTransform = callback; + }, + reload: async () => {}, + }, + } as unknown as V2RuntimeContext; +} + +// --------------------------------------------------------------------------- +// Scenario +// --------------------------------------------------------------------------- + +describe("stage-gated verification lifecycle (integration)", () => { + let cleanup: () => void; + let ctx: PluginContext; + let originalGlobalConfigPath: string | undefined; + + beforeAll(() => { + const env = setupTestEnvironment("stage-gating-lifecycle"); + cleanup = env.cleanup; + + // Isolate from any real ~/.config/opencode/goopspec.json on the host + // machine so thinking-level and model-override assertions stay + // deterministic regardless of what is configured outside this repo. + originalGlobalConfigPath = process.env.GOOPSPEC_GLOBAL_CONFIG_PATH; + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = `${env.testDir}/no-global-config.json`; + + ctx = createMockPluginContext({ + testDir: env.testDir, + db: env.db, + state: { + workflows: { + default: createDefaultWorkflowState({ + phase: "execute", + currentWave: 1, + totalWaves: 1, + specLocked: true, + autopilot: true, + }), + }, + }, + }); + }); + + afterAll(() => { + if (originalGlobalConfigPath === undefined) { + Reflect.deleteProperty(process.env, "GOOPSPEC_GLOBAL_CONFIG_PATH"); + } else { + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = originalGlobalConfigPath; + } + cleanup(); + }); + + // ------------------------------------------------------------------------- + // 1. Registration — V1 config hook + V2 agent/catalog transform adapter + // ------------------------------------------------------------------------- + + it("1. goop-wave-verifier registers through both the V1 and V2 shared registration paths", async () => { + // V1: the real config hook loads agents/goop-wave-verifier.md from the + // package's bundled roster and injects it into config.agent. + const v1Hooks = createAgentRegistrationHook(ctx); + const config: SdkConfig = {}; + await v1Hooks.config?.(config); + + expect(config.agent?.["goop-wave-verifier"]).toBeDefined(); + expect(config.agent?.["goop-wave-verifier"]?.model).toBeTruthy(); + + // V2: the real registerHooksV2 adapter registers a thinking-level agent + // transform that recognises "wave-verifier" through the shared + // AGENT_ROLES registry (getGoopRole) — the same registry the V1 path + // used above — and resolves it to a live catalog variant. + const registrations: V2Registrations = {}; + await registerHooksV2(createV2RuntimeStub(registrations), ctx); + + const agent: V2AgentInfo = { + id: "goop-wave-verifier", + model: { providerID: "anthropic", id: "claude-sonnet-4-6" }, + request: { headers: {}, body: {} }, + }; + const catalog: V2CatalogDraft = { + provider: { + list: () => [ + { + provider: { id: "anthropic" }, + models: new Map([ + [ + "claude-sonnet-4-6", + { + variants: [ + { + id: "low", + headers: {}, + body: { reasoning_effort: "low" }, + }, + { + id: "high", + headers: { "x-reasoning": "high" }, + body: { reasoning_effort: "high" }, + }, + ], + }, + ], + ]), + }, + ], + }, + }; + const agentDraft: V2AgentDraft = { + list: () => [agent], + update: (_id, update) => update(agent), + }; + + await registrations.catalogTransform?.(catalog); + await registrations.agentTransform?.(agentDraft); + + // wave-verifier is not an explorer/researcher role, so its resolved + // default thinking level is "high" — proving getGoopRole recognised it + // via the shared registry rather than a role-specific special case. + expect(agent.model?.variant).toBe("high"); + expect(agent.request.body).toEqual({ reasoning_effort: "high" }); + }); + + // ------------------------------------------------------------------------- + // 2. Execute-phase dispatch guard (real merged tool.execute.before chain) + // ------------------------------------------------------------------------- + + it("2. in execute phase, the merged guard permits goop-wave-verifier and blocks goop-verifier", async () => { + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); + + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) + throw new Error("merged tool.execute.before not defined"); + + await expect( + guardHandler( + { tool: "task", sessionID: "s1", callID: "c1" }, + taskArgs("goop-wave-verifier"), + ), + ).resolves.toBeUndefined(); + + await expect( + guardHandler( + { tool: "task", sessionID: "s1", callID: "c2" }, + taskArgs("goop-verifier"), + ), + ).rejects.toThrow(IntentionalToolDenialError); + }); + + // ------------------------------------------------------------------------- + // 3. Tasks complete, but completion is blocked with zero verification rows + // ------------------------------------------------------------------------- + + it("3. wave 1 tasks complete, but completion is blocked without a verification row", async () => { + const writeWaveTool = createGoopWriteWaveTool(ctx); + const toolCtx = createMockToolContext(); + + const created = await writeWaveTool.execute( + { + wave_number: 1, + title: "Wave 1: stage-gated lifecycle proof", + status: "in_progress", + tasks: [ + { + task_index: 1, + description: "Implement the seam", + agent: "executor-high", + }, + { + task_index: 2, + description: "Wire the tests", + agent: "executor-high", + }, + ], + }, + toolCtx, + ); + expect(created).toContain("Written wave 1"); + + const tasksDone = await writeWaveTool.execute( + { + wave_number: 1, + task_updates: [ + { task_index: 1, status: "done" }, + { task_index: 2, status: "done" }, + ], + }, + toolCtx, + ); + expect(tasksDone).toContain("updated task 1 to done"); + expect(tasksDone).toContain("updated task 2 to done"); + + const blockedCompletion = await writeWaveTool.execute( + { wave_number: 1, status: "done" }, + toolCtx, + ); + expect(blockedCompletion).toContain("Error in goop_write_wave"); + expect(blockedCompletion).toContain("cannot be marked complete"); + expect(blockedCompletion).toContain("goop-wave-verifier"); + + // The denial threw inside the same DB transaction as the status write, + // so the whole attempt rolled back — the wave is still in_progress, not + // half-completed. + const waveAfterBlock = ctx.db.getWave("default", 1); + expect(waveAfterBlock?.status).toBe("in_progress"); + }); + + // ------------------------------------------------------------------------- + // 4. A fail verification row keeps completion blocked + // ------------------------------------------------------------------------- + + it("4. a recorded fail verification row keeps completion blocked", async () => { + const writeWaveTool = createGoopWriteWaveTool(ctx); + const toolCtx = createMockToolContext(); + + const failRecorded = await writeWaveTool.execute( + { + wave_number: 1, + verifications: [ + { check_name: "test", status: "fail", detail: "3 failing specs" }, + ], + }, + toolCtx, + ); + expect(failRecorded).toContain( + "Recorded test=fail verification for wave 1", + ); + + const stillBlocked = await writeWaveTool.execute( + { wave_number: 1, status: "done" }, + toolCtx, + ); + expect(stillBlocked).toContain("Error in goop_write_wave"); + expect(stillBlocked).toContain("cannot be marked complete"); + + const waveStillBlocked = ctx.db.getWave("default", 1); + expect(waveStillBlocked?.status).toBe("in_progress"); + }); + + // ------------------------------------------------------------------------- + // 5. Remediation (no subagent dispatch here) + a later pass row unblocks + // completion via latest-per-check semantics + // ------------------------------------------------------------------------- + + it("5. remediation is represented without dispatching a subagent, and a later pass row for the same check unblocks completion", async () => { + // Real remediation happens via a `task()` dispatch to a goop-executor-* + // subagent in production. This test does not perform that dispatch — it + // records the same durable evidence a real remediation turn would leave + // behind (an ADL observation), then proceeds to the re-verification the + // remediation would trigger. + ctx.stateManager.appendADL({ + timestamp: new Date().toISOString(), + type: "observation", + description: + "Executor remediation for wave 1 check 'test': fixed the 3 failing specs flagged above.", + action: + "Represents goop-executor-* remediation; re-verification recorded as a new row.", + }); + expect(ctx.stateManager.getADL()).toContain( + "Executor remediation for wave 1", + ); + + const writeWaveTool = createGoopWriteWaveTool(ctx); + const toolCtx = createMockToolContext(); + + const passRecorded = await writeWaveTool.execute( + { + wave_number: 1, + verifications: [ + { + check_name: "test", + status: "pass", + detail: "3/3 specs green after remediation", + }, + ], + }, + toolCtx, + ); + expect(passRecorded).toContain( + "Recorded test=pass verification for wave 1", + ); + + const completed = await writeWaveTool.execute( + { wave_number: 1, status: "done" }, + toolCtx, + ); + expect(completed).not.toContain("Error in goop_write_wave"); + expect(completed).toContain("Written wave 1"); + + const waveAfterCompletion = ctx.db.getWave("default", 1); + expect(waveAfterCompletion?.status).toBe("done"); + if (!waveAfterCompletion) + throw new Error("wave 1 not found after completion"); + + // Append-only: both the earlier fail row and the later pass row for the + // SAME check_name ("test") persist — nothing was deleted or overwritten. + // The gate is satisfied because the pass row is the latest by id. + const rows = ctx.db.getVerifications("default", waveAfterCompletion.id); + const testRows = rows.filter((row) => row.check_name === "test"); + expect(testRows).toHaveLength(2); + expect(testRows.map((row) => row.status).sort()).toEqual([ + "failed", + "passed", + ]); + }); + + // ------------------------------------------------------------------------- + // 6. Final-wave completion permits the real execute → accept transition + // ------------------------------------------------------------------------- + + it("6. final-wave completion with verification evidence permits execute → accept auto-progression", async () => { + const autoProgressionHooks = createAutoProgressionHook(ctx); + const afterHandler = autoProgressionHooks[ + "tool.execute.after" + ] as NonNullable; + + const progressionOutput = { title: "result", output: "ok", metadata: {} }; + await afterHandler( + { tool: "goop_write_wave", sessionID: "s1", callID: "c3", args: {} }, + progressionOutput, + ); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + expect(progressionOutput.output).toContain( + "Auto-Progression: execute → accept", + ); + }); + + // ------------------------------------------------------------------------- + // 7. Accept-phase dispatch guard flips: verifier permitted, wave-verifier blocked + // ------------------------------------------------------------------------- + + it("7. in accept phase, the merged guard permits goop-verifier and blocks goop-wave-verifier", async () => { + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) + throw new Error("merged tool.execute.before not defined"); + + await expect( + guardHandler( + { tool: "task", sessionID: "s1", callID: "c4" }, + taskArgs("goop-verifier"), + ), + ).resolves.toBeUndefined(); + + await expect( + guardHandler( + { tool: "task", sessionID: "s1", callID: "c5" }, + taskArgs("goop-wave-verifier"), + ), + ).rejects.toThrow(IntentionalToolDenialError); + }); + + // ------------------------------------------------------------------------- + // 8. goop_acceptance_audit surfaces the append-only verification history + // ------------------------------------------------------------------------- + + it("8. goop_acceptance_audit surfaces per-wave verification rows, including the append-only fail/pass history", async () => { + const auditTool = createGoopAcceptanceAuditTool(ctx); + const toolCtx = createMockToolContext(); + + const auditResult = await auditTool.execute({}, toolCtx); + const parsed = parseAuditEnvelope(auditResult); + + // Both the historical fail row and the pass row that superseded it are + // present — the audit never collapses history to only the effective row. + expect(parsed.verifications).toContain("test: failed"); + expect(parsed.verifications).toContain("test: passed"); + expect(parsed.verifications).toContain("Status: 1 failing"); + + // The wave itself renders as done, with its own verification section + // repeating the same append-only history for a second, independent + // confirmation source. + expect(parsed.waves).toContain( + "## Wave 1: Wave 1: stage-gated lifecycle proof", + ); + expect(parsed.waves).toContain("- status: done"); + expect(parsed.waves).toContain("- test: failed"); + expect(parsed.waves).toContain("- test: passed"); + }); +}); From 8cf9767cebfd08f8866cd7793f5d40207ce1c320 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:12:12 -0700 Subject: [PATCH 19/22] docs(plugin): document the stage-gated wave verification gate --- AGENTS.md | 11 +++++++- .../opencode-plugin/references/phase-gates.md | 14 +++++++++- .../references/wiring-checklist.md | 5 ++-- .../src/features/prompt-audit/index.test.ts | 26 ++++++++++++++++--- 4 files changed, 49 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9b23c278..38d65e94 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -248,6 +248,15 @@ export function createMyHook(ctx: PluginContext) { 8. **Minimal comments** - Only document non-obvious logic. 9. **Atomic commits** - Keep changes focused and small. +## Stage-Gated Verification + +Verification is split across two inspect-only roles, gated by lifecycle stage: + +- `goop-wave-verifier` — execute phase, scoped to one wave at a time. Inspects the wave and records verification rows via `goop_write_wave` `verifications[]`; it never implements fixes. Gaps go back to the correctly tiered executor for remediation, then the wave is re-verified. +- `goop-verifier` — acceptance only. Runs at the accept gate as the final whole-workflow audit against the spec; it is not dispatched during execute. + +A wave does not complete, and execute does not progress to accept, while the wave's effective verification evidence is missing or failing. + ## Agent Thinking Levels GoopSpec supports per-role reasoning-effort configuration through plain-text labels. The system resolves each label against the live OpenCode model catalog — never a hard-coded budget table. @@ -281,7 +290,7 @@ Input is case-insensitive and normalized to canonical lowercase. Unknown labels ### Built-in Role Defaults -Defined in `src/core/constants.ts` (lines 140-146): +Defined in `src/core/constants.ts` (lines 140-146). The canonical `AGENT_ROLES` list has 15 roles; the defaults below are derived from it: | Role(s) | Default Level | |---------|---------------| diff --git a/packages/opencode-plugin/references/phase-gates.md b/packages/opencode-plugin/references/phase-gates.md index 9be74738..ab0fe844 100644 --- a/packages/opencode-plugin/references/phase-gates.md +++ b/packages/opencode-plugin/references/phase-gates.md @@ -8,7 +8,8 @@ Mandatory checkpoints that enforce workflow discipline. No phase proceeds until |------|----------|-------------|-------------| | Discovery | Before `/goop-plan` | `interview_complete == true`, `requirements` document exists in DB (`goop_read_db({ doc_type: "requirements" })` returns content) | Orchestrator | | Spec | Before `/goop-execute` | `spec_locked == true`, `spec` document exists in DB, at least one wave row exists (via `goop_read_wave`), 100% traceability | Orchestrator | -| Execution | Before `/goop-accept` | All waves and tasks complete, verification passing, no blockers | Orchestrator | +| Wave Verification | Each wave during `/goop-execute` | Tasks complete → wave-scoped verifier evidence → remediation on gaps → non-failing effective evidence before completion | Orchestrator | +| Execution | Before `/goop-accept` | All waves and tasks complete, final whole-workflow verification passing, no blockers | Orchestrator | | Acceptance | Within `/goop-accept` | Verification passed, user explicitly accepts | Orchestrator | ## Gate Semantics @@ -30,6 +31,17 @@ Specification must be locked before execution. → Run: `/goop-plan` ``` +## Wave Verification Gate + +Each wave carries its own verification gate before it can be marked complete and before execute can progress to accept: + +1. **Tasks complete** — every task in the wave is done per the wave plan. +2. **Wave-scoped verifier evidence** — the orchestrator dispatches `goop-wave-verifier` scoped to that wave (one wave per dispatch; inspect/report-only, never implements fixes). The verifier records evidence rows via `goop_write_wave` `verifications[]`. +3. **Bounded remediation and re-verification** — on gaps, the orchestrator dispatches the correctly tiered executor to remediate, then re-dispatches `goop-wave-verifier` for that wave. The remediation cycle is bounded by the three-strikes convention in `references/test-authoring.md` §Test Execution Discipline: after three failed attempts on the same gap, open a blocker via `goop_blocker` and stop. +4. **Completion and progression** — the wave completes, and execute progresses to accept, when its effective verification evidence is non-failing (at least one recorded check, and every check's latest recorded row is `pass` or an explicit `skip`). The runtime enforces this boundary: `goop_write_wave` rejects a complete-status transition without it, and auto-progression blocks execute→accept until the gate holds. + +Acceptance remains a distinct final whole-workflow audit: after every wave has passed its own gate, `goop-verifier` inspects the finished workflow against the spec at the accept gate. + ## Bypass Policy | Gate | Bypass Allowed | Conditions | diff --git a/packages/opencode-plugin/references/wiring-checklist.md b/packages/opencode-plugin/references/wiring-checklist.md index 65d76af4..60067a7c 100644 --- a/packages/opencode-plugin/references/wiring-checklist.md +++ b/packages/opencode-plugin/references/wiring-checklist.md @@ -64,7 +64,8 @@ Before marking a feature complete: - [ ] **Exports** — public API re-exported from the package entry point. - [ ] **Config plumbing** — new options read by at least one consumer with observable effect. - [ ] **Documentation** — new agents, skills, or references listed in `AGENTS.md` or equivalent. -- [ ] **Verification gate** — the wave carries a non-failing verification row (`goop_write_wave` `verifications[]`) before it is marked complete or handed off. +- [ ] **Verification gate** — the wave carries a current non-failing verification row (`goop_write_wave` `verifications[]`; the effective per-check state is the latest row per `check_name`) before it is marked complete or handed off. +- [ ] **Acceptance visibility** — per-wave verification rows are surfaced to the acceptance audit (`goop_acceptance_audit` returns combined `{blockers, verifications, waves}`), so the accept gate can see evidence for every wave. - [ ] **Build** — `bun run build` succeeds and includes new files in output. - [ ] **Discovery** — new resource appears in listing tools. @@ -125,7 +126,7 @@ Mandatory handoffs at phase completion, wave completion, checkpoint reached, or ### Handoff Rules - Include tasks completed, key decisions with rationale, exact workflow position, files modified, and explicit next steps. -- At wave completion, the wave verification gate precedes the handoff: `goop-wave-verifier` records a non-failing row for the wave before `HANDOFF.md` marks it complete. A handoff never substitutes for the recorded gate. +- At wave completion, the wave verification gate precedes the handoff: `goop-wave-verifier` records a current non-failing row for the wave before `HANDOFF.md` marks it complete. A handoff never substitutes for the recorded gate. - Do not include full file contents or detailed implementation code. - Keep the context summary to 2-4 sentences max. - Update chronicle via `goop_write_db({ doc_type: "chronicle", content: "..." })` before generating `HANDOFF.md`. diff --git a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts index 37d25844..554e4a45 100644 --- a/packages/opencode-plugin/src/features/prompt-audit/index.test.ts +++ b/packages/opencode-plugin/src/features/prompt-audit/index.test.ts @@ -236,7 +236,7 @@ describe("auditPromptSurfaces (real tree)", () => { expect(commands.bytes).toBe(26_318); }); - it("references: 19 files, 161,350 bytes", () => { + it("references: 19 files, 164,672 bytes", () => { // Wave 3 Task 3.1 consolidated core-protocol.md, dispatch-patterns.md, and // subagent-identity.md (added one Prompt Authoring Rules section, offset // by removing duplicated material from the other two files). Net effect: @@ -298,9 +298,22 @@ describe("auditPromptSurfaces (real tree)", () => { // removed the "after high-risk changes" guidance. Net: 162,326 -> // 162,648 bytes (+322), absolute hits 199 -> 200 (+1: "acceptance-only"), // bold spans unchanged at 532. + // + // The wave-verifier-gating workflow's Wave 5 Task 2 documented the wave + // verification gate as a first-class execute gate: phase-gates.md gained + // a Wave Verification row in the gate-overview table and a Wave + // Verification Gate section (tasks complete -> wave-scoped verifier + // evidence -> bounded remediation -> non-failing effective evidence + // before completion, with acceptance remaining a distinct final + // whole-workflow audit), and wiring-checklist.md tightened its + // verification item to the current/effective per-check row and added an + // acceptance-visibility item. Net: 162,648 -> 164,672 bytes (+2,024), + // absolute hits 200 -> 202 (+2: the "never implements fixes" role + // invariant and the "inspect/report-only" boundary, both true invariants + // shared with dispatch-patterns.md), bold spans 532 -> 542 (+10). const references = report.directories.find((d) => d.directory === "references")!; expect(references.files).toBe(19); - expect(references.bytes).toBe(162_648); + expect(references.bytes).toBe(164_672); }); it("total absolute-language hits are 299 (Wave 1 role plumbing plus the Wave 3 execution gate)", () => { @@ -393,7 +406,14 @@ describe("auditPromptSurfaces (real tree)", () => { // matching clarification added zero new hits (its wording reuses the // file's existing "only"/"never" vocabulary without a new match) — // lifting the total from 308 to 309. - expect(report.totalAbsoluteHits).toBe(309); + // + // The wave-verifier-gating workflow's Wave 5 Task 2 documented the wave + // verification gate as a first-class execute gate: +2 in references + // (phase-gates.md's Wave Verification Gate section — the "never + // implements fixes" role invariant and the "inspect/report-only" + // boundary, both true invariants shared with dispatch-patterns.md) — + // lifting the total from 309 to 311. + expect(report.totalAbsoluteHits).toBe(311); }); it("per-file tokens are consistent with chars via estimateTokens", () => { From f495838a51ea1c51ca9cf29edd2ed326bdae95cf Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:20:07 -0700 Subject: [PATCH 20/22] style(plugin): apply biome formatting to the stage-gating integration test MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wave 5 Task 3 wiring/quality-gate check: lint diff against the Wave 4 base (1a9ed89) isolated exactly one net-new regression introduced by this workflow — a formatter-only violation in stage-gating.integration.test.ts (added in W5.T1, a4b0eb1). Applied `biome format --write` scoped to that single file only; whitespace-only, behavior-preserving. Post-fix lint diagnostics (10 errors / 17 warnings) now match the Wave 4 baseline file-and-rule set exactly, confirming no lint regression remains from this workflow. Remaining baseline errors belong to files this workflow never touched (prompt-audit/report.ts, continuation-prompt.test.ts, system-transform.test.ts) or were already present at the Wave 4 boundary, and are out of this task's scope. --- .../stage-gating.integration.test.ts | 829 +++++++++--------- 1 file changed, 393 insertions(+), 436 deletions(-) diff --git a/packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts b/packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts index d5885e6e..ab31461b 100644 --- a/packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts +++ b/packages/opencode-plugin/src/features/enforcement/stage-gating.integration.test.ts @@ -38,13 +38,13 @@ import { afterAll, beforeAll, describe, expect, it } from "bun:test"; import { registerHooksV2 } from "../../core/hooks-v2.js"; import type { SdkConfig, ToolResult } from "../../core/sdk-compat.js"; import type { - V2AgentDraft, - V2AgentInfo, - V2CatalogDraft, - V2RuntimeContext, - V2SessionRequestEvent, - V2ToolExecuteAfterEvent, - V2ToolExecuteBeforeEvent, + V2AgentDraft, + V2AgentInfo, + V2CatalogDraft, + V2RuntimeContext, + V2SessionRequestEvent, + V2ToolExecuteAfterEvent, + V2ToolExecuteBeforeEvent, } from "../../core/v2-compat.js"; import { createAgentRegistrationHook } from "../../hooks/agent-registration.js"; import { createAutoProgressionHook } from "../../hooks/auto-progression.js"; @@ -52,11 +52,11 @@ import { DEFAULT_HOOK_FACTORIES, createHooks } from "../../hooks/index.js"; import type { Hooks } from "../../hooks/types.js"; import { IntentionalToolDenialError } from "../../hooks/utils.js"; import { - type PluginContext, - createDefaultWorkflowState, - createMockPluginContext, - createMockToolContext, - setupTestEnvironment, + type PluginContext, + createDefaultWorkflowState, + createMockPluginContext, + createMockToolContext, + setupTestEnvironment, } from "../../test-utils.js"; import { createGoopAcceptanceAuditTool } from "../../tools/goop-acceptance-audit/index.js"; import { createGoopWriteWaveTool } from "../../tools/goop-write-wave/index.js"; @@ -66,30 +66,28 @@ import { createGoopWriteWaveTool } from "../../tools/goop-write-wave/index.js"; // --------------------------------------------------------------------------- function taskArgs(subagentType: string): { args: Record } { - return { - args: { description: "d", prompt: "p", subagent_type: subagentType }, - }; + return { + args: { description: "d", prompt: "p", subagent_type: subagentType }, + }; } /** Extracts the `` envelope goop_acceptance_audit returns. */ function parseAuditEnvelope(result: ToolResult | string): { - blockers: string; - verifications: string; - waves: string; + blockers: string; + verifications: string; + waves: string; } { - const text = typeof result === "string" ? result : result.output; - const match = text.match(//); - if (!match) { - throw new Error( - `goop_acceptance_audit did not return the expected JSON envelope: ${text}`, - ); - } - return JSON.parse(match[1]); + const text = typeof result === "string" ? result : result.output; + const match = text.match(//); + if (!match) { + throw new Error(`goop_acceptance_audit did not return the expected JSON envelope: ${text}`); + } + return JSON.parse(match[1]); } interface V2Registrations { - agentTransform?: (draft: V2AgentDraft) => void | Promise; - catalogTransform?: (draft: V2CatalogDraft) => void | Promise; + agentTransform?: (draft: V2AgentDraft) => void | Promise; + catalogTransform?: (draft: V2CatalogDraft) => void | Promise; } /** @@ -100,45 +98,41 @@ interface V2Registrations { * them directly with the exact draft under scrutiny. */ function createV2RuntimeStub(registrations: V2Registrations): V2RuntimeContext { - return { - session: { - create: async () => ({}), - get: async () => ({}), - prompt: async () => ({}), - command: async () => ({}), - synthetic: async () => ({}), - interrupt: async () => ({}), - hook: async ( - _event: "request", - _callback: (event: V2SessionRequestEvent) => void | Promise, - ) => {}, - }, - tool: { - transform: async () => {}, - hook: async ( - _event: "execute.before" | "execute.after", - _callback: - | ((event: V2ToolExecuteBeforeEvent) => void | Promise) - | ((event: V2ToolExecuteAfterEvent) => void | Promise), - ) => {}, - }, - agent: { - transform: async ( - callback: (draft: V2AgentDraft) => void | Promise, - ) => { - registrations.agentTransform = callback; - }, - reload: async () => {}, - }, - catalog: { - transform: async ( - callback: (draft: V2CatalogDraft) => void | Promise, - ) => { - registrations.catalogTransform = callback; - }, - reload: async () => {}, - }, - } as unknown as V2RuntimeContext; + return { + session: { + create: async () => ({}), + get: async () => ({}), + prompt: async () => ({}), + command: async () => ({}), + synthetic: async () => ({}), + interrupt: async () => ({}), + hook: async ( + _event: "request", + _callback: (event: V2SessionRequestEvent) => void | Promise, + ) => {}, + }, + tool: { + transform: async () => {}, + hook: async ( + _event: "execute.before" | "execute.after", + _callback: + | ((event: V2ToolExecuteBeforeEvent) => void | Promise) + | ((event: V2ToolExecuteAfterEvent) => void | Promise), + ) => {}, + }, + agent: { + transform: async (callback: (draft: V2AgentDraft) => void | Promise) => { + registrations.agentTransform = callback; + }, + reload: async () => {}, + }, + catalog: { + transform: async (callback: (draft: V2CatalogDraft) => void | Promise) => { + registrations.catalogTransform = callback; + }, + reload: async () => {}, + }, + } as unknown as V2RuntimeContext; } // --------------------------------------------------------------------------- @@ -146,373 +140,336 @@ function createV2RuntimeStub(registrations: V2Registrations): V2RuntimeContext { // --------------------------------------------------------------------------- describe("stage-gated verification lifecycle (integration)", () => { - let cleanup: () => void; - let ctx: PluginContext; - let originalGlobalConfigPath: string | undefined; - - beforeAll(() => { - const env = setupTestEnvironment("stage-gating-lifecycle"); - cleanup = env.cleanup; - - // Isolate from any real ~/.config/opencode/goopspec.json on the host - // machine so thinking-level and model-override assertions stay - // deterministic regardless of what is configured outside this repo. - originalGlobalConfigPath = process.env.GOOPSPEC_GLOBAL_CONFIG_PATH; - process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = `${env.testDir}/no-global-config.json`; - - ctx = createMockPluginContext({ - testDir: env.testDir, - db: env.db, - state: { - workflows: { - default: createDefaultWorkflowState({ - phase: "execute", - currentWave: 1, - totalWaves: 1, - specLocked: true, - autopilot: true, - }), - }, - }, - }); - }); - - afterAll(() => { - if (originalGlobalConfigPath === undefined) { - Reflect.deleteProperty(process.env, "GOOPSPEC_GLOBAL_CONFIG_PATH"); - } else { - process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = originalGlobalConfigPath; - } - cleanup(); - }); - - // ------------------------------------------------------------------------- - // 1. Registration — V1 config hook + V2 agent/catalog transform adapter - // ------------------------------------------------------------------------- - - it("1. goop-wave-verifier registers through both the V1 and V2 shared registration paths", async () => { - // V1: the real config hook loads agents/goop-wave-verifier.md from the - // package's bundled roster and injects it into config.agent. - const v1Hooks = createAgentRegistrationHook(ctx); - const config: SdkConfig = {}; - await v1Hooks.config?.(config); - - expect(config.agent?.["goop-wave-verifier"]).toBeDefined(); - expect(config.agent?.["goop-wave-verifier"]?.model).toBeTruthy(); - - // V2: the real registerHooksV2 adapter registers a thinking-level agent - // transform that recognises "wave-verifier" through the shared - // AGENT_ROLES registry (getGoopRole) — the same registry the V1 path - // used above — and resolves it to a live catalog variant. - const registrations: V2Registrations = {}; - await registerHooksV2(createV2RuntimeStub(registrations), ctx); - - const agent: V2AgentInfo = { - id: "goop-wave-verifier", - model: { providerID: "anthropic", id: "claude-sonnet-4-6" }, - request: { headers: {}, body: {} }, - }; - const catalog: V2CatalogDraft = { - provider: { - list: () => [ - { - provider: { id: "anthropic" }, - models: new Map([ - [ - "claude-sonnet-4-6", - { - variants: [ - { - id: "low", - headers: {}, - body: { reasoning_effort: "low" }, - }, - { - id: "high", - headers: { "x-reasoning": "high" }, - body: { reasoning_effort: "high" }, - }, - ], - }, - ], - ]), - }, - ], - }, - }; - const agentDraft: V2AgentDraft = { - list: () => [agent], - update: (_id, update) => update(agent), - }; - - await registrations.catalogTransform?.(catalog); - await registrations.agentTransform?.(agentDraft); - - // wave-verifier is not an explorer/researcher role, so its resolved - // default thinking level is "high" — proving getGoopRole recognised it - // via the shared registry rather than a role-specific special case. - expect(agent.model?.variant).toBe("high"); - expect(agent.request.body).toEqual({ reasoning_effort: "high" }); - }); - - // ------------------------------------------------------------------------- - // 2. Execute-phase dispatch guard (real merged tool.execute.before chain) - // ------------------------------------------------------------------------- - - it("2. in execute phase, the merged guard permits goop-wave-verifier and blocks goop-verifier", async () => { - expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); - - const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); - const guardHandler = hooks["tool.execute.before"]; - if (!guardHandler) - throw new Error("merged tool.execute.before not defined"); - - await expect( - guardHandler( - { tool: "task", sessionID: "s1", callID: "c1" }, - taskArgs("goop-wave-verifier"), - ), - ).resolves.toBeUndefined(); - - await expect( - guardHandler( - { tool: "task", sessionID: "s1", callID: "c2" }, - taskArgs("goop-verifier"), - ), - ).rejects.toThrow(IntentionalToolDenialError); - }); - - // ------------------------------------------------------------------------- - // 3. Tasks complete, but completion is blocked with zero verification rows - // ------------------------------------------------------------------------- - - it("3. wave 1 tasks complete, but completion is blocked without a verification row", async () => { - const writeWaveTool = createGoopWriteWaveTool(ctx); - const toolCtx = createMockToolContext(); - - const created = await writeWaveTool.execute( - { - wave_number: 1, - title: "Wave 1: stage-gated lifecycle proof", - status: "in_progress", - tasks: [ - { - task_index: 1, - description: "Implement the seam", - agent: "executor-high", - }, - { - task_index: 2, - description: "Wire the tests", - agent: "executor-high", - }, - ], - }, - toolCtx, - ); - expect(created).toContain("Written wave 1"); - - const tasksDone = await writeWaveTool.execute( - { - wave_number: 1, - task_updates: [ - { task_index: 1, status: "done" }, - { task_index: 2, status: "done" }, - ], - }, - toolCtx, - ); - expect(tasksDone).toContain("updated task 1 to done"); - expect(tasksDone).toContain("updated task 2 to done"); - - const blockedCompletion = await writeWaveTool.execute( - { wave_number: 1, status: "done" }, - toolCtx, - ); - expect(blockedCompletion).toContain("Error in goop_write_wave"); - expect(blockedCompletion).toContain("cannot be marked complete"); - expect(blockedCompletion).toContain("goop-wave-verifier"); - - // The denial threw inside the same DB transaction as the status write, - // so the whole attempt rolled back — the wave is still in_progress, not - // half-completed. - const waveAfterBlock = ctx.db.getWave("default", 1); - expect(waveAfterBlock?.status).toBe("in_progress"); - }); - - // ------------------------------------------------------------------------- - // 4. A fail verification row keeps completion blocked - // ------------------------------------------------------------------------- - - it("4. a recorded fail verification row keeps completion blocked", async () => { - const writeWaveTool = createGoopWriteWaveTool(ctx); - const toolCtx = createMockToolContext(); - - const failRecorded = await writeWaveTool.execute( - { - wave_number: 1, - verifications: [ - { check_name: "test", status: "fail", detail: "3 failing specs" }, - ], - }, - toolCtx, - ); - expect(failRecorded).toContain( - "Recorded test=fail verification for wave 1", - ); - - const stillBlocked = await writeWaveTool.execute( - { wave_number: 1, status: "done" }, - toolCtx, - ); - expect(stillBlocked).toContain("Error in goop_write_wave"); - expect(stillBlocked).toContain("cannot be marked complete"); - - const waveStillBlocked = ctx.db.getWave("default", 1); - expect(waveStillBlocked?.status).toBe("in_progress"); - }); - - // ------------------------------------------------------------------------- - // 5. Remediation (no subagent dispatch here) + a later pass row unblocks - // completion via latest-per-check semantics - // ------------------------------------------------------------------------- - - it("5. remediation is represented without dispatching a subagent, and a later pass row for the same check unblocks completion", async () => { - // Real remediation happens via a `task()` dispatch to a goop-executor-* - // subagent in production. This test does not perform that dispatch — it - // records the same durable evidence a real remediation turn would leave - // behind (an ADL observation), then proceeds to the re-verification the - // remediation would trigger. - ctx.stateManager.appendADL({ - timestamp: new Date().toISOString(), - type: "observation", - description: - "Executor remediation for wave 1 check 'test': fixed the 3 failing specs flagged above.", - action: - "Represents goop-executor-* remediation; re-verification recorded as a new row.", - }); - expect(ctx.stateManager.getADL()).toContain( - "Executor remediation for wave 1", - ); - - const writeWaveTool = createGoopWriteWaveTool(ctx); - const toolCtx = createMockToolContext(); - - const passRecorded = await writeWaveTool.execute( - { - wave_number: 1, - verifications: [ - { - check_name: "test", - status: "pass", - detail: "3/3 specs green after remediation", - }, - ], - }, - toolCtx, - ); - expect(passRecorded).toContain( - "Recorded test=pass verification for wave 1", - ); - - const completed = await writeWaveTool.execute( - { wave_number: 1, status: "done" }, - toolCtx, - ); - expect(completed).not.toContain("Error in goop_write_wave"); - expect(completed).toContain("Written wave 1"); - - const waveAfterCompletion = ctx.db.getWave("default", 1); - expect(waveAfterCompletion?.status).toBe("done"); - if (!waveAfterCompletion) - throw new Error("wave 1 not found after completion"); - - // Append-only: both the earlier fail row and the later pass row for the - // SAME check_name ("test") persist — nothing was deleted or overwritten. - // The gate is satisfied because the pass row is the latest by id. - const rows = ctx.db.getVerifications("default", waveAfterCompletion.id); - const testRows = rows.filter((row) => row.check_name === "test"); - expect(testRows).toHaveLength(2); - expect(testRows.map((row) => row.status).sort()).toEqual([ - "failed", - "passed", - ]); - }); - - // ------------------------------------------------------------------------- - // 6. Final-wave completion permits the real execute → accept transition - // ------------------------------------------------------------------------- - - it("6. final-wave completion with verification evidence permits execute → accept auto-progression", async () => { - const autoProgressionHooks = createAutoProgressionHook(ctx); - const afterHandler = autoProgressionHooks[ - "tool.execute.after" - ] as NonNullable; - - const progressionOutput = { title: "result", output: "ok", metadata: {} }; - await afterHandler( - { tool: "goop_write_wave", sessionID: "s1", callID: "c3", args: {} }, - progressionOutput, - ); - - expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); - expect(progressionOutput.output).toContain( - "Auto-Progression: execute → accept", - ); - }); - - // ------------------------------------------------------------------------- - // 7. Accept-phase dispatch guard flips: verifier permitted, wave-verifier blocked - // ------------------------------------------------------------------------- - - it("7. in accept phase, the merged guard permits goop-verifier and blocks goop-wave-verifier", async () => { - expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); - - const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); - const guardHandler = hooks["tool.execute.before"]; - if (!guardHandler) - throw new Error("merged tool.execute.before not defined"); - - await expect( - guardHandler( - { tool: "task", sessionID: "s1", callID: "c4" }, - taskArgs("goop-verifier"), - ), - ).resolves.toBeUndefined(); - - await expect( - guardHandler( - { tool: "task", sessionID: "s1", callID: "c5" }, - taskArgs("goop-wave-verifier"), - ), - ).rejects.toThrow(IntentionalToolDenialError); - }); - - // ------------------------------------------------------------------------- - // 8. goop_acceptance_audit surfaces the append-only verification history - // ------------------------------------------------------------------------- - - it("8. goop_acceptance_audit surfaces per-wave verification rows, including the append-only fail/pass history", async () => { - const auditTool = createGoopAcceptanceAuditTool(ctx); - const toolCtx = createMockToolContext(); - - const auditResult = await auditTool.execute({}, toolCtx); - const parsed = parseAuditEnvelope(auditResult); - - // Both the historical fail row and the pass row that superseded it are - // present — the audit never collapses history to only the effective row. - expect(parsed.verifications).toContain("test: failed"); - expect(parsed.verifications).toContain("test: passed"); - expect(parsed.verifications).toContain("Status: 1 failing"); - - // The wave itself renders as done, with its own verification section - // repeating the same append-only history for a second, independent - // confirmation source. - expect(parsed.waves).toContain( - "## Wave 1: Wave 1: stage-gated lifecycle proof", - ); - expect(parsed.waves).toContain("- status: done"); - expect(parsed.waves).toContain("- test: failed"); - expect(parsed.waves).toContain("- test: passed"); - }); + let cleanup: () => void; + let ctx: PluginContext; + let originalGlobalConfigPath: string | undefined; + + beforeAll(() => { + const env = setupTestEnvironment("stage-gating-lifecycle"); + cleanup = env.cleanup; + + // Isolate from any real ~/.config/opencode/goopspec.json on the host + // machine so thinking-level and model-override assertions stay + // deterministic regardless of what is configured outside this repo. + originalGlobalConfigPath = process.env.GOOPSPEC_GLOBAL_CONFIG_PATH; + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = `${env.testDir}/no-global-config.json`; + + ctx = createMockPluginContext({ + testDir: env.testDir, + db: env.db, + state: { + workflows: { + default: createDefaultWorkflowState({ + phase: "execute", + currentWave: 1, + totalWaves: 1, + specLocked: true, + autopilot: true, + }), + }, + }, + }); + }); + + afterAll(() => { + if (originalGlobalConfigPath === undefined) { + Reflect.deleteProperty(process.env, "GOOPSPEC_GLOBAL_CONFIG_PATH"); + } else { + process.env.GOOPSPEC_GLOBAL_CONFIG_PATH = originalGlobalConfigPath; + } + cleanup(); + }); + + // ------------------------------------------------------------------------- + // 1. Registration — V1 config hook + V2 agent/catalog transform adapter + // ------------------------------------------------------------------------- + + it("1. goop-wave-verifier registers through both the V1 and V2 shared registration paths", async () => { + // V1: the real config hook loads agents/goop-wave-verifier.md from the + // package's bundled roster and injects it into config.agent. + const v1Hooks = createAgentRegistrationHook(ctx); + const config: SdkConfig = {}; + await v1Hooks.config?.(config); + + expect(config.agent?.["goop-wave-verifier"]).toBeDefined(); + expect(config.agent?.["goop-wave-verifier"]?.model).toBeTruthy(); + + // V2: the real registerHooksV2 adapter registers a thinking-level agent + // transform that recognises "wave-verifier" through the shared + // AGENT_ROLES registry (getGoopRole) — the same registry the V1 path + // used above — and resolves it to a live catalog variant. + const registrations: V2Registrations = {}; + await registerHooksV2(createV2RuntimeStub(registrations), ctx); + + const agent: V2AgentInfo = { + id: "goop-wave-verifier", + model: { providerID: "anthropic", id: "claude-sonnet-4-6" }, + request: { headers: {}, body: {} }, + }; + const catalog: V2CatalogDraft = { + provider: { + list: () => [ + { + provider: { id: "anthropic" }, + models: new Map([ + [ + "claude-sonnet-4-6", + { + variants: [ + { + id: "low", + headers: {}, + body: { reasoning_effort: "low" }, + }, + { + id: "high", + headers: { "x-reasoning": "high" }, + body: { reasoning_effort: "high" }, + }, + ], + }, + ], + ]), + }, + ], + }, + }; + const agentDraft: V2AgentDraft = { + list: () => [agent], + update: (_id, update) => update(agent), + }; + + await registrations.catalogTransform?.(catalog); + await registrations.agentTransform?.(agentDraft); + + // wave-verifier is not an explorer/researcher role, so its resolved + // default thinking level is "high" — proving getGoopRole recognised it + // via the shared registry rather than a role-specific special case. + expect(agent.model?.variant).toBe("high"); + expect(agent.request.body).toEqual({ reasoning_effort: "high" }); + }); + + // ------------------------------------------------------------------------- + // 2. Execute-phase dispatch guard (real merged tool.execute.before chain) + // ------------------------------------------------------------------------- + + it("2. in execute phase, the merged guard permits goop-wave-verifier and blocks goop-verifier", async () => { + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("execute"); + + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("merged tool.execute.before not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c1" }, taskArgs("goop-wave-verifier")), + ).resolves.toBeUndefined(); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c2" }, taskArgs("goop-verifier")), + ).rejects.toThrow(IntentionalToolDenialError); + }); + + // ------------------------------------------------------------------------- + // 3. Tasks complete, but completion is blocked with zero verification rows + // ------------------------------------------------------------------------- + + it("3. wave 1 tasks complete, but completion is blocked without a verification row", async () => { + const writeWaveTool = createGoopWriteWaveTool(ctx); + const toolCtx = createMockToolContext(); + + const created = await writeWaveTool.execute( + { + wave_number: 1, + title: "Wave 1: stage-gated lifecycle proof", + status: "in_progress", + tasks: [ + { + task_index: 1, + description: "Implement the seam", + agent: "executor-high", + }, + { + task_index: 2, + description: "Wire the tests", + agent: "executor-high", + }, + ], + }, + toolCtx, + ); + expect(created).toContain("Written wave 1"); + + const tasksDone = await writeWaveTool.execute( + { + wave_number: 1, + task_updates: [ + { task_index: 1, status: "done" }, + { task_index: 2, status: "done" }, + ], + }, + toolCtx, + ); + expect(tasksDone).toContain("updated task 1 to done"); + expect(tasksDone).toContain("updated task 2 to done"); + + const blockedCompletion = await writeWaveTool.execute( + { wave_number: 1, status: "done" }, + toolCtx, + ); + expect(blockedCompletion).toContain("Error in goop_write_wave"); + expect(blockedCompletion).toContain("cannot be marked complete"); + expect(blockedCompletion).toContain("goop-wave-verifier"); + + // The denial threw inside the same DB transaction as the status write, + // so the whole attempt rolled back — the wave is still in_progress, not + // half-completed. + const waveAfterBlock = ctx.db.getWave("default", 1); + expect(waveAfterBlock?.status).toBe("in_progress"); + }); + + // ------------------------------------------------------------------------- + // 4. A fail verification row keeps completion blocked + // ------------------------------------------------------------------------- + + it("4. a recorded fail verification row keeps completion blocked", async () => { + const writeWaveTool = createGoopWriteWaveTool(ctx); + const toolCtx = createMockToolContext(); + + const failRecorded = await writeWaveTool.execute( + { + wave_number: 1, + verifications: [{ check_name: "test", status: "fail", detail: "3 failing specs" }], + }, + toolCtx, + ); + expect(failRecorded).toContain("Recorded test=fail verification for wave 1"); + + const stillBlocked = await writeWaveTool.execute({ wave_number: 1, status: "done" }, toolCtx); + expect(stillBlocked).toContain("Error in goop_write_wave"); + expect(stillBlocked).toContain("cannot be marked complete"); + + const waveStillBlocked = ctx.db.getWave("default", 1); + expect(waveStillBlocked?.status).toBe("in_progress"); + }); + + // ------------------------------------------------------------------------- + // 5. Remediation (no subagent dispatch here) + a later pass row unblocks + // completion via latest-per-check semantics + // ------------------------------------------------------------------------- + + it("5. remediation is represented without dispatching a subagent, and a later pass row for the same check unblocks completion", async () => { + // Real remediation happens via a `task()` dispatch to a goop-executor-* + // subagent in production. This test does not perform that dispatch — it + // records the same durable evidence a real remediation turn would leave + // behind (an ADL observation), then proceeds to the re-verification the + // remediation would trigger. + ctx.stateManager.appendADL({ + timestamp: new Date().toISOString(), + type: "observation", + description: + "Executor remediation for wave 1 check 'test': fixed the 3 failing specs flagged above.", + action: "Represents goop-executor-* remediation; re-verification recorded as a new row.", + }); + expect(ctx.stateManager.getADL()).toContain("Executor remediation for wave 1"); + + const writeWaveTool = createGoopWriteWaveTool(ctx); + const toolCtx = createMockToolContext(); + + const passRecorded = await writeWaveTool.execute( + { + wave_number: 1, + verifications: [ + { + check_name: "test", + status: "pass", + detail: "3/3 specs green after remediation", + }, + ], + }, + toolCtx, + ); + expect(passRecorded).toContain("Recorded test=pass verification for wave 1"); + + const completed = await writeWaveTool.execute({ wave_number: 1, status: "done" }, toolCtx); + expect(completed).not.toContain("Error in goop_write_wave"); + expect(completed).toContain("Written wave 1"); + + const waveAfterCompletion = ctx.db.getWave("default", 1); + expect(waveAfterCompletion?.status).toBe("done"); + if (!waveAfterCompletion) throw new Error("wave 1 not found after completion"); + + // Append-only: both the earlier fail row and the later pass row for the + // SAME check_name ("test") persist — nothing was deleted or overwritten. + // The gate is satisfied because the pass row is the latest by id. + const rows = ctx.db.getVerifications("default", waveAfterCompletion.id); + const testRows = rows.filter((row) => row.check_name === "test"); + expect(testRows).toHaveLength(2); + expect(testRows.map((row) => row.status).sort()).toEqual(["failed", "passed"]); + }); + + // ------------------------------------------------------------------------- + // 6. Final-wave completion permits the real execute → accept transition + // ------------------------------------------------------------------------- + + it("6. final-wave completion with verification evidence permits execute → accept auto-progression", async () => { + const autoProgressionHooks = createAutoProgressionHook(ctx); + const afterHandler = autoProgressionHooks["tool.execute.after"] as NonNullable< + Hooks["tool.execute.after"] + >; + + const progressionOutput = { title: "result", output: "ok", metadata: {} }; + await afterHandler( + { tool: "goop_write_wave", sessionID: "s1", callID: "c3", args: {} }, + progressionOutput, + ); + + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + expect(progressionOutput.output).toContain("Auto-Progression: execute → accept"); + }); + + // ------------------------------------------------------------------------- + // 7. Accept-phase dispatch guard flips: verifier permitted, wave-verifier blocked + // ------------------------------------------------------------------------- + + it("7. in accept phase, the merged guard permits goop-verifier and blocks goop-wave-verifier", async () => { + expect(ctx.stateManager.getActiveWorkflow().phase).toBe("accept"); + + const hooks = createHooks(ctx, [...DEFAULT_HOOK_FACTORIES]); + const guardHandler = hooks["tool.execute.before"]; + if (!guardHandler) throw new Error("merged tool.execute.before not defined"); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c4" }, taskArgs("goop-verifier")), + ).resolves.toBeUndefined(); + + await expect( + guardHandler({ tool: "task", sessionID: "s1", callID: "c5" }, taskArgs("goop-wave-verifier")), + ).rejects.toThrow(IntentionalToolDenialError); + }); + + // ------------------------------------------------------------------------- + // 8. goop_acceptance_audit surfaces the append-only verification history + // ------------------------------------------------------------------------- + + it("8. goop_acceptance_audit surfaces per-wave verification rows, including the append-only fail/pass history", async () => { + const auditTool = createGoopAcceptanceAuditTool(ctx); + const toolCtx = createMockToolContext(); + + const auditResult = await auditTool.execute({}, toolCtx); + const parsed = parseAuditEnvelope(auditResult); + + // Both the historical fail row and the pass row that superseded it are + // present — the audit never collapses history to only the effective row. + expect(parsed.verifications).toContain("test: failed"); + expect(parsed.verifications).toContain("test: passed"); + expect(parsed.verifications).toContain("Status: 1 failing"); + + // The wave itself renders as done, with its own verification section + // repeating the same append-only history for a second, independent + // confirmation source. + expect(parsed.waves).toContain("## Wave 1: Wave 1: stage-gated lifecycle proof"); + expect(parsed.waves).toContain("- status: done"); + expect(parsed.waves).toContain("- test: failed"); + expect(parsed.waves).toContain("- test: passed"); + }); }); From e680b0dc564f0122df611efd67d4e6144856de70 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:39:38 -0700 Subject: [PATCH 21/22] style(plugin): format verifier-stage module to satisfy package biome config Convert tab indentation to Biome's configured 2-space style and collapse signatures/calls that fit within lineWidth:100 in verifier-stage.ts and verifier-stage.test.ts. Formatting-only; no token, type, test, or behavior change. Removes the two workflow-owned lint diagnostics blocking the acceptance gate; unrelated baseline lint debt in other modules remains classified as skip. --- .../enforcement/verifier-stage.test.ts | 409 ++++++++---------- .../features/enforcement/verifier-stage.ts | 117 +++-- 2 files changed, 242 insertions(+), 284 deletions(-) diff --git a/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts b/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts index fac42c01..70bc9f93 100644 --- a/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts +++ b/packages/opencode-plugin/src/features/enforcement/verifier-stage.test.ts @@ -3,13 +3,13 @@ import { describe, expect, it } from "bun:test"; import { WORKFLOW_PHASES } from "../../core/constants.js"; import type { WorkflowPhase } from "../../core/types.js"; import { - VERIFICATION_RESULT_STATUSES, - VERIFICATION_RESULT_TO_DB_STATUS, - VERIFICATION_STATUSES, - type VerifiedRowLike, - isVerifierDispatchAllowed, - isWaveVerified, - toDbVerificationStatus, + VERIFICATION_RESULT_STATUSES, + VERIFICATION_RESULT_TO_DB_STATUS, + VERIFICATION_STATUSES, + type VerifiedRowLike, + isVerifierDispatchAllowed, + isWaveVerified, + toDbVerificationStatus, } from "./verifier-stage.js"; // --------------------------------------------------------------------------- @@ -17,80 +17,73 @@ import { // --------------------------------------------------------------------------- describe("isVerifierDispatchAllowed", () => { - for (const phase of WORKFLOW_PHASES) { - it(`allows "verifier" only in accept (phase: ${phase})`, () => { - const result = isVerifierDispatchAllowed({ role: "verifier", phase }); - if (phase === "accept") { - expect(result.allowed).toBe(true); - expect(result.reason).toBeUndefined(); - } else { - expect(result.allowed).toBe(false); - expect(result.reason).toContain("acceptance-only"); - expect(result.reason).toContain(phase); - } - }); - - it(`allows "wave-verifier" only in execute (phase: ${phase})`, () => { - const result = isVerifierDispatchAllowed({ - role: "wave-verifier", - phase, - }); - if (phase === "execute") { - expect(result.allowed).toBe(true); - expect(result.reason).toBeUndefined(); - } else { - expect(result.allowed).toBe(false); - expect(result.reason).toContain("execute-only"); - expect(result.reason).toContain(phase); - } - }); - } - - const otherRoles = [ - "orchestrator", - "executor-low", - "executor-medium", - "executor-high", - "executor-frontend-low", - "executor-frontend-medium", - "executor-frontend-high", - "planner", - "researcher", - "explorer", - "debugger", - "tester", - "writer", - ]; - - for (const role of otherRoles) { - for (const phase of WORKFLOW_PHASES) { - it(`allows "${role}" in every phase (phase: ${phase})`, () => { - expect(isVerifierDispatchAllowed({ role, phase }).allowed).toBe(true); - }); - } - } - - for (const phase of WORKFLOW_PHASES) { - it(`allows an undefined role (fail open) in phase: ${phase}`, () => { - expect( - isVerifierDispatchAllowed({ role: undefined, phase }).allowed, - ).toBe(true); - }); - - it(`allows an unrecognized role string (fail open) in phase: ${phase}`, () => { - expect( - isVerifierDispatchAllowed({ role: "totally-unknown-role", phase }) - .allowed, - ).toBe(true); - }); - } - - it("is case-sensitive: 'Verifier' is not treated as the accept-only role", () => { - // Deliberately undetermined-role behavior, not an implicit normalization. - expect( - isVerifierDispatchAllowed({ role: "Verifier", phase: "discuss" }).allowed, - ).toBe(true); - }); + for (const phase of WORKFLOW_PHASES) { + it(`allows "verifier" only in accept (phase: ${phase})`, () => { + const result = isVerifierDispatchAllowed({ role: "verifier", phase }); + if (phase === "accept") { + expect(result.allowed).toBe(true); + expect(result.reason).toBeUndefined(); + } else { + expect(result.allowed).toBe(false); + expect(result.reason).toContain("acceptance-only"); + expect(result.reason).toContain(phase); + } + }); + + it(`allows "wave-verifier" only in execute (phase: ${phase})`, () => { + const result = isVerifierDispatchAllowed({ + role: "wave-verifier", + phase, + }); + if (phase === "execute") { + expect(result.allowed).toBe(true); + expect(result.reason).toBeUndefined(); + } else { + expect(result.allowed).toBe(false); + expect(result.reason).toContain("execute-only"); + expect(result.reason).toContain(phase); + } + }); + } + + const otherRoles = [ + "orchestrator", + "executor-low", + "executor-medium", + "executor-high", + "executor-frontend-low", + "executor-frontend-medium", + "executor-frontend-high", + "planner", + "researcher", + "explorer", + "debugger", + "tester", + "writer", + ]; + + for (const role of otherRoles) { + for (const phase of WORKFLOW_PHASES) { + it(`allows "${role}" in every phase (phase: ${phase})`, () => { + expect(isVerifierDispatchAllowed({ role, phase }).allowed).toBe(true); + }); + } + } + + for (const phase of WORKFLOW_PHASES) { + it(`allows an undefined role (fail open) in phase: ${phase}`, () => { + expect(isVerifierDispatchAllowed({ role: undefined, phase }).allowed).toBe(true); + }); + + it(`allows an unrecognized role string (fail open) in phase: ${phase}`, () => { + expect(isVerifierDispatchAllowed({ role: "totally-unknown-role", phase }).allowed).toBe(true); + }); + } + + it("is case-sensitive: 'Verifier' is not treated as the accept-only role", () => { + // Deliberately undetermined-role behavior, not an implicit normalization. + expect(isVerifierDispatchAllowed({ role: "Verifier", phase: "discuss" }).allowed).toBe(true); + }); }); // --------------------------------------------------------------------------- @@ -98,24 +91,24 @@ describe("isVerifierDispatchAllowed", () => { // --------------------------------------------------------------------------- describe("verification status mapping", () => { - it("maps every result status to a valid DB status", () => { - for (const status of VERIFICATION_RESULT_STATUSES) { - const mapped = VERIFICATION_RESULT_TO_DB_STATUS[status]; - expect(VERIFICATION_STATUSES).toContain(mapped); - } - }); - - it("maps pass -> passed, fail -> failed, skip -> skipped", () => { - expect(toDbVerificationStatus("pass")).toBe("passed"); - expect(toDbVerificationStatus("fail")).toBe("failed"); - expect(toDbVerificationStatus("skip")).toBe("skipped"); - }); - - it("returns undefined for an input outside the result vocabulary", () => { - expect(toDbVerificationStatus("passed")).toBeUndefined(); - expect(toDbVerificationStatus("unknown")).toBeUndefined(); - expect(toDbVerificationStatus("")).toBeUndefined(); - }); + it("maps every result status to a valid DB status", () => { + for (const status of VERIFICATION_RESULT_STATUSES) { + const mapped = VERIFICATION_RESULT_TO_DB_STATUS[status]; + expect(VERIFICATION_STATUSES).toContain(mapped); + } + }); + + it("maps pass -> passed, fail -> failed, skip -> skipped", () => { + expect(toDbVerificationStatus("pass")).toBe("passed"); + expect(toDbVerificationStatus("fail")).toBe("failed"); + expect(toDbVerificationStatus("skip")).toBe("skipped"); + }); + + it("returns undefined for an input outside the result vocabulary", () => { + expect(toDbVerificationStatus("passed")).toBeUndefined(); + expect(toDbVerificationStatus("unknown")).toBeUndefined(); + expect(toDbVerificationStatus("")).toBeUndefined(); + }); }); // --------------------------------------------------------------------------- @@ -123,124 +116,98 @@ describe("verification status mapping", () => { // --------------------------------------------------------------------------- let nextId = 1; -function row( - status: VerifiedRowLike["status"], - check_name = "test", - id?: number, -): VerifiedRowLike { - return { id: id ?? nextId++, check_name, status }; +function row(status: VerifiedRowLike["status"], check_name = "test", id?: number): VerifiedRowLike { + return { id: id ?? nextId++, check_name, status }; } describe("isWaveVerified", () => { - it("is false for zero rows", () => { - expect(isWaveVerified([])).toBe(false); - }); - - it("is true for a single passed row", () => { - expect(isWaveVerified([row("passed")])).toBe(true); - }); - - it("is false for a single failed row", () => { - expect(isWaveVerified([row("failed")])).toBe(false); - }); - - it("is true for a single skipped row (auditable escape)", () => { - expect(isWaveVerified([row("skipped")])).toBe(true); - }); - - it("is true for multiple passed rows across different checks", () => { - expect( - isWaveVerified([row("passed", "test"), row("passed", "typecheck")]), - ).toBe(true); - }); - - it("is false when any check among several has a failed latest row", () => { - expect( - isWaveVerified([ - row("passed", "typecheck"), - row("failed", "test"), - row("passed", "lint"), - ]), - ).toBe(false); - }); - - it("is false for a mixed skip/fail set across different checks", () => { - expect( - isWaveVerified([row("skipped", "lint"), row("failed", "test")]), - ).toBe(false); - }); - - it("is true for a mixed pass/skip set across different checks", () => { - expect( - isWaveVerified([row("passed", "test"), row("skipped", "lint")]), - ).toBe(true); - }); - - it("treats a pending row as non-failing on its own", () => { - expect(isWaveVerified([row("pending")])).toBe(true); - }); - - it("is false when a pending row accompanies a failed row on a different check", () => { - expect( - isWaveVerified([row("pending", "lint"), row("failed", "test")]), - ).toBe(false); - }); - - // --------------------------------------------------------------------- - // Latest-per-check_name semantics (append-only history) - // --------------------------------------------------------------------- - - it("a later pass for the SAME check supersedes its own prior fail", () => { - expect( - isWaveVerified([row("failed", "test", 1), row("passed", "test", 2)]), - ).toBe(true); - }); - - it("a later skip for the SAME check supersedes its own prior fail", () => { - expect( - isWaveVerified([row("failed", "test", 1), row("skipped", "test", 2)]), - ).toBe(true); - }); - - it("a later fail for the SAME check supersedes its own prior pass", () => { - expect( - isWaveVerified([row("passed", "test", 1), row("failed", "test", 2)]), - ).toBe(false); - }); - - it("a pass for a DIFFERENT check never supersedes another check's unresolved fail", () => { - expect( - isWaveVerified([row("failed", "test", 1), row("passed", "typecheck", 2)]), - ).toBe(false); - }); - - it("is independent of array order — sorts by id, not caller position", () => { - // Fail row appended AFTER the pass row in the array, but its id is - // lower, so the pass (higher id) is still the effective latest. - expect( - isWaveVerified([row("passed", "test", 2), row("failed", "test", 1)]), - ).toBe(true); - }); - - it("every check must have a non-failing latest row, not just one of several", () => { - expect( - isWaveVerified([ - row("failed", "test", 1), - row("passed", "test", 2), - row("failed", "typecheck", 3), - ]), - ).toBe(false); - }); - - it("all checks resolved: same-check remediation plus an untouched passing check both count", () => { - expect( - isWaveVerified([ - row("failed", "test", 1), - row("passed", "lint", 2), - row("passed", "test", 3), - ]), - ).toBe(true); - }); + it("is false for zero rows", () => { + expect(isWaveVerified([])).toBe(false); + }); + + it("is true for a single passed row", () => { + expect(isWaveVerified([row("passed")])).toBe(true); + }); + + it("is false for a single failed row", () => { + expect(isWaveVerified([row("failed")])).toBe(false); + }); + + it("is true for a single skipped row (auditable escape)", () => { + expect(isWaveVerified([row("skipped")])).toBe(true); + }); + + it("is true for multiple passed rows across different checks", () => { + expect(isWaveVerified([row("passed", "test"), row("passed", "typecheck")])).toBe(true); + }); + + it("is false when any check among several has a failed latest row", () => { + expect( + isWaveVerified([row("passed", "typecheck"), row("failed", "test"), row("passed", "lint")]), + ).toBe(false); + }); + + it("is false for a mixed skip/fail set across different checks", () => { + expect(isWaveVerified([row("skipped", "lint"), row("failed", "test")])).toBe(false); + }); + + it("is true for a mixed pass/skip set across different checks", () => { + expect(isWaveVerified([row("passed", "test"), row("skipped", "lint")])).toBe(true); + }); + + it("treats a pending row as non-failing on its own", () => { + expect(isWaveVerified([row("pending")])).toBe(true); + }); + + it("is false when a pending row accompanies a failed row on a different check", () => { + expect(isWaveVerified([row("pending", "lint"), row("failed", "test")])).toBe(false); + }); + + // --------------------------------------------------------------------- + // Latest-per-check_name semantics (append-only history) + // --------------------------------------------------------------------- + + it("a later pass for the SAME check supersedes its own prior fail", () => { + expect(isWaveVerified([row("failed", "test", 1), row("passed", "test", 2)])).toBe(true); + }); + + it("a later skip for the SAME check supersedes its own prior fail", () => { + expect(isWaveVerified([row("failed", "test", 1), row("skipped", "test", 2)])).toBe(true); + }); + + it("a later fail for the SAME check supersedes its own prior pass", () => { + expect(isWaveVerified([row("passed", "test", 1), row("failed", "test", 2)])).toBe(false); + }); + + it("a pass for a DIFFERENT check never supersedes another check's unresolved fail", () => { + expect(isWaveVerified([row("failed", "test", 1), row("passed", "typecheck", 2)])).toBe(false); + }); + + it("is independent of array order — sorts by id, not caller position", () => { + // Fail row appended AFTER the pass row in the array, but its id is + // lower, so the pass (higher id) is still the effective latest. + expect(isWaveVerified([row("passed", "test", 2), row("failed", "test", 1)])).toBe(true); + }); + + it("every check must have a non-failing latest row, not just one of several", () => { + expect( + isWaveVerified([ + row("failed", "test", 1), + row("passed", "test", 2), + row("failed", "typecheck", 3), + ]), + ).toBe(false); + }); + + it("all checks resolved: same-check remediation plus an untouched passing check both count", () => { + expect( + isWaveVerified([ + row("failed", "test", 1), + row("passed", "lint", 2), + row("passed", "test", 3), + ]), + ).toBe(true); + }); }); // --------------------------------------------------------------------------- @@ -248,14 +215,8 @@ describe("isWaveVerified", () => { // --------------------------------------------------------------------------- describe("phase coverage sanity check", () => { - it("exercises all five workflow phases", () => { - const expected: WorkflowPhase[] = [ - "idle", - "discuss", - "plan", - "execute", - "accept", - ]; - expect([...WORKFLOW_PHASES].sort()).toEqual([...expected].sort()); - }); + it("exercises all five workflow phases", () => { + const expected: WorkflowPhase[] = ["idle", "discuss", "plan", "execute", "accept"]; + expect([...WORKFLOW_PHASES].sort()).toEqual([...expected].sort()); + }); }); diff --git a/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts b/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts index 4e10f6fc..eb22ddb0 100644 --- a/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts +++ b/packages/opencode-plugin/src/features/enforcement/verifier-stage.ts @@ -19,13 +19,13 @@ const ACCEPT_ONLY_ROLE = "verifier"; const EXECUTE_ONLY_ROLE = "wave-verifier"; export interface VerifierDispatchCheck { - /** - * Arbitrary string, not just {@link AgentRole} — the caller derives this - * from a delegated agent name and may not normalize it. Undefined or - * unrecognized values are treated as undetermined and allowed. - */ - role: string | undefined; - phase: WorkflowPhase; + /** + * Arbitrary string, not just {@link AgentRole} — the caller derives this + * from a delegated agent name and may not normalize it. Undefined or + * unrecognized values are treated as undetermined and allowed. + */ + role: string | undefined; + phase: WorkflowPhase; } /** @@ -34,28 +34,28 @@ export interface VerifierDispatchCheck { * fails OPEN so unrelated delegations are never blocked by this predicate. */ export function isVerifierDispatchAllowed({ - role, - phase, + role, + phase, }: VerifierDispatchCheck): ValidationResult { - if (role === ACCEPT_ONLY_ROLE) { - return phase === "accept" - ? { allowed: true } - : { - allowed: false, - reason: `verifier is acceptance-only; dispatch wave-verifier during execute (current phase: ${phase}).`, - }; - } - - if (role === EXECUTE_ONLY_ROLE) { - return phase === "execute" - ? { allowed: true } - : { - allowed: false, - reason: `wave-verifier is execute-only; dispatch verifier during accept (current phase: ${phase}).`, - }; - } - - return { allowed: true }; + if (role === ACCEPT_ONLY_ROLE) { + return phase === "accept" + ? { allowed: true } + : { + allowed: false, + reason: `verifier is acceptance-only; dispatch wave-verifier during execute (current phase: ${phase}).`, + }; + } + + if (role === EXECUTE_ONLY_ROLE) { + return phase === "execute" + ? { allowed: true } + : { + allowed: false, + reason: `wave-verifier is execute-only; dispatch verifier during accept (current phase: ${phase}).`, + }; + } + + return { allowed: true }; } // --------------------------------------------------------------------------- @@ -65,23 +65,20 @@ export function isVerifierDispatchAllowed({ /** `goop_write_wave`'s `verifications[]` vocabulary, distinct from the DB's * stored {@link VerificationStatus} (which also has a transient `"pending"`). */ export const VERIFICATION_RESULT_STATUSES = ["pass", "fail", "skip"] as const; -export type VerificationResultStatus = - (typeof VERIFICATION_RESULT_STATUSES)[number]; +export type VerificationResultStatus = (typeof VERIFICATION_RESULT_STATUSES)[number]; export const VERIFICATION_RESULT_TO_DB_STATUS: Readonly< - Record + Record > = { - pass: "passed", - fail: "failed", - skip: "skipped", + pass: "passed", + fail: "failed", + skip: "skipped", }; /** Returns `undefined` for input outside {@link VERIFICATION_RESULT_STATUSES} * rather than throwing — callers decide how to surface an invalid input. */ -export function toDbVerificationStatus( - status: string, -): VerificationStatus | undefined { - return VERIFICATION_RESULT_TO_DB_STATUS[status as VerificationResultStatus]; +export function toDbVerificationStatus(status: string): VerificationStatus | undefined { + return VERIFICATION_RESULT_TO_DB_STATUS[status as VerificationResultStatus]; } // Re-exported so consumers don't need a second import from features/db/types.js. @@ -93,13 +90,13 @@ export type { VerificationStatus }; // --------------------------------------------------------------------------- export interface VerifiedRowLike { - /** Recency key. `id` is `INTEGER PRIMARY KEY AUTOINCREMENT` on the - * append-only `verifications` table, so it is strictly increasing in - * insertion order — sorted here rather than trusted from caller order. */ - id: number; - /** The logical check this row reports on (e.g. `"test"`, `"typecheck"`). */ - check_name: string; - status: VerificationStatus; + /** Recency key. `id` is `INTEGER PRIMARY KEY AUTOINCREMENT` on the + * append-only `verifications` table, so it is strictly increasing in + * insertion order — sorted here rather than trusted from caller order. */ + id: number; + /** The logical check this row reports on (e.g. `"test"`, `"typecheck"`). */ + check_name: string; + status: VerificationStatus; } /** @@ -111,19 +108,19 @@ export interface VerifiedRowLike { * `"skipped"` effective row satisfies the gate as an auditable escape. */ export function isWaveVerified(rows: readonly VerifiedRowLike[]): boolean { - if (rows.length === 0) return false; - - const latestByCheck = new Map(); - for (const row of rows) { - const existing = latestByCheck.get(row.check_name); - if (existing === undefined || row.id > existing.id) { - latestByCheck.set(row.check_name, row); - } - } - - if (latestByCheck.size === 0) return false; - for (const row of latestByCheck.values()) { - if (row.status === "failed") return false; - } - return true; + if (rows.length === 0) return false; + + const latestByCheck = new Map(); + for (const row of rows) { + const existing = latestByCheck.get(row.check_name); + if (existing === undefined || row.id > existing.id) { + latestByCheck.set(row.check_name, row); + } + } + + if (latestByCheck.size === 0) return false; + for (const row of latestByCheck.values()) { + if (row.status === "failed") return false; + } + return true; } From ec3eb91b3b2411ed9ff27b9879c6cab1e6c1dc46 Mon Sep 17 00:00:00 2001 From: hffmnnj <52758545+hffmnnj@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:44:43 -0700 Subject: [PATCH 22/22] style(plugin): format lazy-autopilot-nudge rate-limit test to satisfy package biome config --- .../src/hooks/lazy-autopilot-nudge/rate-limit.test.ts | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts b/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts index b595662b..03087fd7 100644 --- a/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts +++ b/packages/opencode-plugin/src/hooks/lazy-autopilot-nudge/rate-limit.test.ts @@ -227,11 +227,7 @@ describe("lazy autopilot nudge rate-limit", () => { // ------------------------------------------------------------------------- it("builds a fingerprint that ends with the verification digest slot", () => { - const fp = buildNudgeFingerprint( - baseCtx, - "default", - baseCtx.stateManager.getActiveWorkflow(), - ); + const fp = buildNudgeFingerprint(baseCtx, "default", baseCtx.stateManager.getActiveWorkflow()); // No verification rows seeded in beforeEach -> slot is "none". expect(fp).toMatch(/\|v:none$/); });