Skip to content

Fix duplicated decision content and record the deployment gap - #295

Merged
hffmnnj merged 6 commits into
feat/utility-tool-contractsfrom
feat/tool-contract-integration
Aug 5, 2026
Merged

hffmnnj merged 6 commits into
feat/utility-tool-contractsfrom
feat/tool-contract-integration

Conversation

@hffmnnj

@hffmnnj hffmnnj commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Closes the tool-contract effort. One data bug fixed, error messages made self-correcting, and documentation reconciled with what the code actually does. Stacked on #294.

Decision records were storing everything twice

For type: "decision", reasoning and alternatives were folded into stored content by two different layers — once by the tool under ## Reasoning and ## Alternatives Considered headers, then again by the manager with inline Reasoning: and Alternatives considered: prefixes. Every decision record written to date holds both copies, and since content is indexed for full-text search at weight 5, those records have been outranking everything else.

The manager is now the sole owner of composition and the tool passes raw content.

The reason this survived is worth stating: the existing test asserted toContain("Reasoning:"), which passes identically whether the text appears once or twice. The replacement asserts occurrence counts. A test that cannot distinguish the bug from the fix is not protecting anything, and this one had been green the whole time.

Pre-fix records are deliberately left unmigrated, and that decision is now recorded next to the code rather than living in someone's head. The duplicated text carries no marker separating content a caller genuinely wrote twice from content the two layers each contributed, so a cleanup pass could destroy real user content. Affected records remain correct and searchable; they just rank higher than they should.

Source changes here do not affect the running session

This is the finding that cost the most to learn, so it is now written into the Gotchas.

The host loads this plugin from a built bundle at its install path, once per session. That path is outside this git worktree. An agent that edits tool behavior cannot observe the change in its own tool calls — not after committing, not after a green test run. A clean session is not evidence a tool change works.

I learned this the hard way. An earlier description in this stack claimed that agent sessions after a fix landed reported no failures, and offered that as the strongest evidence it worked. The fix had never executed. Those sessions were running the old bundle and their clean reports described the old code. That claim has been withdrawn and corrected in #292.

Two independent reviews passed that branch without catching it, because both reasoned about the source in the worktree rather than asking which artifact the host had loaded. What exposed it was a later agent reporting it had been rejected over a value it never supplied — impossible if the fix were live. The contradiction was only visible because friction reporting is mandatory.

Documentation that had drifted

AGENTS.md claimed 30 tool factories. There are 38, and have been throughout.

Three genuine contradictions in references/tool-reference.md: two statements that verifications and traceability cannot accompany batch mode, when in fact they are supported per item and only rejected at the top level, and a generate_image argument list carrying model and inputFidelity — arguments the schema has never declared. Documentation describing arguments that do not exist is the same defect this effort spent its length attacking, sitting in the document defining the standard.

Sections that restated calling rules now point at the emitted schemas instead. A restatement is a copy, and this one had already gone stale in three places.

Verification

2690 pass, 0 fail; typecheck clean; build exits 0. Independently audited twice — the first review failed this branch for stating the migration decision in a report but never in the repository, which is fixed and re-verified.

Lint reports 46 errors, all pre-existing and confirmed unchanged against a stash comparison.

hffmnnj added 6 commits August 4, 2026 17:24
The memory-save tool previously formatted decision rationale before passing it to the manager, which formatted the same fields again. Delegate content composition solely to the storage manager so persisted decision content and FTS weighting are not duplicated.

Changes:\n- Pass raw decision content from the tool\n- Pin manager composition and tool delegation contracts
Several action-dispatch errors identified a missing field without showing a corrected request. Include the tool context and a valid retry shape so callers can recover without consulting implementation details.

Changes:\n- Teach required state and blocker action payloads\n- Clarify memory deletion and setup reset confirmations
Reconcile secondary doc surfaces with what the code actually does so each
fact has one owner (the emitted schema) rather than stale copies.

AGENTS.md:
- Record the build-vs-source deployment gap in Gotchas: package.json
  points main/exports at src/index.ts, but the build script emits a
  dist/index.js bundle and the host loads that bundle, once per session,
  from an install path outside this worktree. Source edits here do not
  affect the running session; validating a behavior change needs a
  rebuild plus restart, and unit tests are the only in-session evidence.
- Fix the stale tool-factory count (30 -> 38), pinned by the registry
  tests; point at the emitted schema as the argument authority.
- Replace the restated ast_grep/difftastic/scip/generate_image/
  background_* argument and when-to-use lists with pointers to the
  emitted schemas. A restatement is a copy that silently goes stale;
  a prior version of this section fabricated model and inputFidelity
  args that generate_image never declared.

tool-reference.md (the maintained cheat sheet):
- Resolve two goop_write_wave contradictions that claimed
  verifications/traceability were 'not available alongside items batch
  mode'. They are supplied per-item inside each items[] entry;
  top-level side payloads alongside items[] are rejected, not dropped.
- Remove the phantom generate_image model/inputFidelity args and note
  mask/outputCompression are declared but ignored (owned by the schema).

prompt-audit test:
- Repin references.bytes 174_506 -> 174_965 to the true measured value.
  totalAbsoluteHits unchanged at 328 (no must/never/always/critical/
  only language added or removed).
Classify every registered tool for MODES and CAVEATS requirements so newly added tools cannot bypass the conditional section gate. Document the five additional mode-bearing tools and prove missing required conditional sections fail conformance.
Require mode sections for duplicate reinforcement, cross-store memory search, and draft pull-request creation. Document each opt-in path so callers can predict its execution and result.
@hffmnnj
hffmnnj merged commit acd8b4c into feat/utility-tool-contracts Aug 5, 2026
@hffmnnj
hffmnnj deleted the feat/tool-contract-integration branch August 5, 2026 12:44
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