Skip to content

fix(plugin): harden write tool payload contracts - #285

Merged
hffmnnj merged 10 commits into
feat/execute-verification-loopfrom
feat/write-tool-contracts
Aug 3, 2026
Merged

hffmnnj merged 10 commits into
feat/execute-verification-loopfrom
feat/write-tool-contracts

Conversation

@hffmnnj

@hffmnnj hffmnnj commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Summary

Makes write operations explicit and safe across document, section, note, blocker, and progress tools. Ambiguous payloads now return actionable guidance before any mutation, while valid legacy call shapes remain covered.

Changes

  • Add a shared write-mode resolver for full writes, patches, and batches
  • Reject conflicting or incomplete operation fields before storage changes
  • Apply equivalent validation to section, note, and blocker operations
  • Preserve intentional empty-content compatibility behavior
  • Pin every registered tool's V2 JSON Schema required fields
  • Add positive compatibility fixtures, atomic rollback checks, and retry-loop coverage

Testing

  • Full plugin suite: 2598 passed, 0 failed across 124 files
  • Independent focused audit: 290 passed, 0 failed
  • TypeScript typecheck: clean
  • Structural diff check: clean
  • No skipped or disabled tests

Notes

Depends on #284. Host-side V1 schema conversion remains outside plugin control; runtime validation provides the safety guarantee.

hffmnnj added 7 commits August 3, 2026 12:17
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.
… helper (W4.T2)

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
…bling tools (W4.T3)

- 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.
…y-loop guarantee

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.
… (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).
… test

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.
hffmnnj and others added 3 commits August 3, 2026 13:39
…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.
test(plugin): prove verification lifecycle end to end
@hffmnnj
hffmnnj merged commit cc572c5 into feat/execute-verification-loop Aug 3, 2026
@hffmnnj
hffmnnj deleted the feat/write-tool-contracts branch August 3, 2026 23:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant