Repository navigation
fix(tools): align write tool schemas, docs, and adapter coverage - #299
Merged
hffmnnj merged 6 commits intoAug 12, 2026
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Verification
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.