Skip to content

fix(tools): align write tool schemas, docs, and adapter coverage - #299

Merged
hffmnnj merged 6 commits into
fix/mutation-tool-validationfrom
fix/write-contract-integration
Aug 12, 2026
Merged

hffmnnj merged 6 commits into
fix/mutation-tool-validationfrom
fix/write-contract-integration

Conversation

@hffmnnj

@hffmnnj hffmnnj commented Aug 12, 2026

Copy link
Copy Markdown
Owner

Summary

  • align the emitted schemas and tool descriptions with the semantics the earlier changes landed
  • state the omission and rejection contract per field, with correction guidance
  • correct the batch inventory and coalescing docs to the real six-tool surface
  • add registry and V2 adapter coverage proving both paths execute one shared implementation
  • make the note tool's empty-collection message reachable on the wrapped path

Verification

  • six-tool focused suites: 355 passed
  • full package suite: 2810 passed
  • package typecheck passed
  • lint attribution identical to the pre-change baseline, no new findings in touched files
  • package build succeeded

The running host uses an already-loaded bundle, so source-level tests provide the behavioral evidence and the passing build is not live-host validation.

…mantics

Wave 4 Task 4.1 schema-and-description half. Synchronize the emitted
tool schemas and descriptions for the six write tools with the runtime
semantics landed in Waves 1-3:

- goop_write_wave: correct the stale 'empty strings overwrite' metadata
  claim — empty-string title/pr_branch/pr_url is rejected (intentional
  metadata clearing is not supported) and injected empty statuses /
  task_update:{} are treated as absent, never clobbering stored values.
- goop_write_section: drop the stale mode:"append" rejection (the tool
  has no mode arg); document section_key:'' rejection and the
  empty-items-batch distinction.
- goop_write_db / goop_save_note: state the load-bearing patch pair
  (old_string presence, empty new_string deletes), tags:[] vs empty-tag
  rejection, and importance:0 rejection.
- goop_append_chronicle: keep the cross-store non-atomicity caveat and
  add the empty-entry/empty-payload omission and empty-batch distinction.
- goop_blocker: document id:0/wave_id:0 as omitted (1-based ids),
  whitespace-only rejection guidance, and empty items[] vs no-args.

Contract pins (tools-v2.test.ts): complete INJECTED_DEFAULT_FIELDS for
all six tools, add batch-element requiredness pins for goop_write_wave
(items/task_updates/verifications/traceability), goop_blocker (items),
and goop_append_chronicle (entries), and update the two title-description
pins to the corrected wording.
… corrected descriptions

Wave-aligned markdown half of the write-tool contract alignment. The
factory descriptions and emitted schemas are the authority; prose now
mirrors them:

- Remove the stale empty-string metadata clearing contract from the
  load-bearing table (title/pr_branch/pr_url on goop_write_wave) and the
  'including empty strings, overwrite' semantic; intentional metadata
  clearing is not supported and empty metadata is treated as absent.
- Rewrite the empty-string coalescing contract to match coalesce.ts:
  exact "", false, [], {} are coalesced only per the per-tool policy,
  while 0, whitespace-only strings, and the load-bearing patch pairs
  (old_string/new_string) are always preserved.
- Add the six-tool batch inventory naming the exact batch array property
  per tool (entries/items) with schema-pinned per-item requiredness
  (blocker items require action; wave items require wave_number).
- Fix the stale 'Not available in entries batch mode' claim for
  goop_append_chronicle aux writes: alsoLogAdl/alsoSaveMemory apply once
  after the batch commits, only on full success; cross-store atomicity
  remains unavailable with per-store [OK]/[FAIL] reporting.
- Complete the goop_write_wave table row: allow_status_regression and
  per-item verifications/traceability inside items[].
Add registry and V2 integration coverage for all six write definitions under injected empty containers. Preserve save-note's explicit empty-batch diagnostic at the shared boundary so wrapped and direct calls agree.
Follow the wiring change that removed goop_save_note's items entry from
the injected-empty-container coalescing set: an empty items[] now stays
visible at the shared boundary so wrapped and direct calls agree on the
empty-batch error.

- tool-reference.md: add items on goop_save_note to the deliberately
  not-omitted list and to the empty-batch rejection list; trim absolute
  wording introduced by the prior commit so the reference stays within
  the prompt-audit budget (bytes +20, absolute-language hits -7 vs the
  previous head).
- AGENTS.md: replace the four-tool items[] claim with the real six-tool
  batch surface (goop_blocker via items[], goop_append_chronicle via
  entries[]), keeping the single-transaction and non-atomic aux caveats.
…t docs

tool-reference.md grew 27,620 -> 30,526 bytes (+2,906) documenting the
write-tool runtime contracts the schema does not state cross-tool: the
Six-tool batch inventory (per-item requiredness, sub-array element pins,
empty-batch rejection case), the corrected coalescing boundary with all
three omission categories and load-bearing exclusions, removal of the
stale pr_url/pr_branch/title clearing-operation rows (empty now preserves
stored value), and the corrected goop_append_chronicle batch-mode
aux-payload semantics. The growth is contract documentation, not bloat:
the rewrite also removed one absolute-language hit (tool-reference 27 ->
26, total 328 -> 327), so the budget's pressure lever moved the right
direction while the reference gained real contract content.
@hffmnnj
hffmnnj merged commit 87444a5 into fix/mutation-tool-validation Aug 12, 2026
@hffmnnj
hffmnnj deleted the fix/write-contract-integration branch August 12, 2026 12:16
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