Repository navigation
Say plainly which arguments do nothing - #293
Merged
hffmnnj merged 12 commits intoAug 5, 2026
Merged
Conversation
Bring memory_save, memory_search, and memory_forget to the house tool-description standard and drop them from PENDING_CONFORMANCE (17 -> 14). memory_forget (allowlisted, 1074 chars): the destructive contract is now unmissable. Documents the two mutually exclusive modes (id deletes immediately and ignores confirm; query needs confirm:true), states plainly that the operation is irreversible, and calls out the footgun that the read-only preview caps at 20 rows while confirmed deletion searches up to 100. Added to HIGH_FRICTION_TOOLS with justification. memory_save (691 chars): documents what actually persists. Verifies the per-type importance defaults (decision 7, note 4, else 5) at the tool layer, the type=decision field-folding and fact auto-generation, the id -1 graceful-degradation signal, and the deduplicate:true reinforce-not-insert contract (importance=max(old,new), created_at refreshed, content unchanged, no new row). memory_search (695 chars): documents retrieval semantics honestly. Filters AND-combine; concepts OR within the list as a substring match; includeFieldNotes:true changes both membership and ranking via RRF (k=60) and applies filters to the memory side only. MH11/MH20 investigation: the 'query plus tag misses results that query alone finds' observation is the intended AND-combination contract, not a ranking bug. A record matching the query text but lacking the filter is excluded by design. Confirmed under real FTS5 and pinned at both the tool and manager levels. No algorithm change made or warranted. Tests added: - memory_forget: id precedence over query+confirm, confirm ignored on id path, query preview searches with limit 20, confirm-gates-query. - memory_save: failed write degrades to id -1 rather than throwing. - memory_search: limit clamp, empty-query no-results, concept filter narrows by design (tool level). - features/memory (real FTS5): concept filter excludes a query match lacking the concept; substring/case-insensitive tag matching; and forgetByQuery deletes 30 > the 20-row preview ceiling.
Bring goop_setup, goop_spec, goop_infer_intent, goop_status, goop_get_global_config, and slashcommand into conformance with the house tool-description standard (WHEN TO USE / WHEN NOT TO USE / RETURNS sections, recursive .describe() on every arg, length bounds). PENDING_CONFORMANCE: 14 → 8. Action-to-argument legality is now documented precisely for each tool: - goop_setup: every action mapped to which args it reads vs ignores; scope is declared but silently ignored by every action; gitignoreGoopspec applies as a cross-action side effect regardless of action. - goop_spec: file is read only by read; phase is ignored by all. - goop_infer_intent: autoApply vs autoRun documented as separate mechanisms with different confidence gates (0.85 hard floor + threshold default 0.9 vs 0.75 autoRun floor); below-threshold is never an error. - goop_status: verbose is declared but currently ignored. Allowlisted (HIGH_FRICTION_TOOLS): goop_setup (1169), goop_spec (841), goop_infer_intent (1152) — all carry mandatory mode/contract content that cannot fit under 700. Contract tests pin the three arguments-that-do-nothing (scope, phase, verbose) and action-dependent arg legality for goop_setup.
…y correct Bring ast_grep, difftastic, scip, background_command, background_status, and background_cancel into conformance with the house tool-description standard. Removes all six from PENDING_CONFORMANCE (8 -> 2); adds ast_grep, scip, and difftastic to HIGH_FRICTION_TOOLS with per-tool justifications. Each description now carries the mandatory WHEN TO USE / WHEN NOT TO USE / RETURNS sections plus MODES/CAVEATS where applicable, and every argument (including nested array item fields) carries a terminal .describe(). Key load-bearing content added: - ast_grep: documents the three modes (search / rewrite dry-run / rewrite apply) and the conditional no-op that apply:true without rewrite has no effect (-U is only appended inside the rewrite branch). - scip: documents the action-dependent required field (symbol required for definitions/references/implementations, ignored by index) and that each action resolves a different binary (scip vs scip-typescript). - difftastic: documents the alias-pair cross-field contract and the missing-binary-vs-no-differences distinction. - background_command: keeps the verified timeout default (1800s/30min), the integer [1,86400] range with reject-not-clamp, and the kill-on-expiry. - background_status: documents the lazy expiry sweep that marks timed-out without killing (eager timer owns the kill). - background_cancel: documents the process-group SIGTERM->SIGKILL escalation. No behavior changes; documentation and test-gate edits only.
…ORMANCE generate_image (allowlisted, 1136 chars): full house-standard rewrite — Purpose, WHEN TO USE/NOT TO USE, MODES (dryRun vs live), RETURNS, and CAVEATS covering the png-only transparency constraint (green-screen + local chromakey), default output path, count-suffix behavior, the OAuth/credits cost model, and two dead arguments. mask and outputCompression are declared on the schema but never read by execute() nor forwarded to buildBody() — documented as 'Declared but not read by the tool; supplying it has no effect.' Cross-field constraints surfaced on out, outputFormat, and background so callers see them before the call, not through a validation rejection. goop_create_pr (allowlisted, 904 chars): documents the terminology gate contract — scans title/body/branch, error-severity blocks while warn-severity proceeds, code spans masked in title/body but never in branch, reword-not-retry semantics with example rewrites. Dropped the misleading merge-method sentence; documented honestly that no merge-method argument is exposed and it is a repo setting on GitHub. goop_spec (tightened from 841 to 632 chars, removed from allowlist): the 3-action mode contract (file read only by read; phase ignored by all) fits under 700 when the per-action file-ignored clauses are collapsed into one. No contract lost. PENDING_CONFORMANCE is now empty: all 38 tools face every predicate. Full suite: 2690 pass, 0 fail.
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.
Fix duplicated decision content and record the deployment gap
Arm the gate over all 38 tools
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.
Brings nine more tools to the House Tool-Description Standard, taking the registry from 21 to 30 of 38. Stacked on #292.
Three arguments that were never read
goop_setup.scopeis declared as an enum ofglobal,project, andboth. No action reads it.goop_spec.phaseis declared and ignored by all three of its actions.goop_status.verboseis declared while the implementation's parameter is literally named_args.Each is now documented as ignored, in those words, and pinned by a test asserting identical output with and without it. None were made to work — that would be a behavior change, and this workflow is deliberately not making those.
This is the same defect family already found in
goop_state.workflowId, which 15 of its 17 actions ignore, andgoop_dashboard.workflow_id, which is declared and never read. Five instances across the registry. The shared failure is that a declared argument reads as a promise, so a caller supplies it, gets a success response, and concludes it took effect.A read-only action that writes
goop_setupprocessesgitignoreGoopspecin a block that runs before the action switch. Soaction: "detect"— which every other part of its contract presents as read-only — will modify.gitignoreand mutate workflow state when that argument is set. The same holds forverifyandstatus.Behavior is unchanged here and the trap is now documented and tested. The underlying design is tracked separately, because documenting a read-only action that writes is a weaker fix than not having one.
memory_forget
Allowlisted to 1074 characters, and it earns them. The description now distinguishes the invocation that deletes exactly one record from the one that can delete many, states what
confirmgates and what it does not, and states that the operation is irreversible.It also documents an asymmetry found while writing it: the preview searches with a limit of 20 while the actual delete searches with a limit of 100. A caller could review a preview of 20 records and then delete considerably more. That is now visible before the call rather than discoverable after it.
The retrieval question
Planning recorded a suspicion that searching memory with a query plus a tag filter misses results that the query alone finds. Investigated against the implementation and reproduced under real FTS5: it is the AND-combination working as designed. A record matching the query text but lacking the filtered concept is excluded on purpose. There is no ranking defect.
The narrowing is now documented and pinned by tests at both the tool level and against the real index. The ranking algorithm was not touched — a suspicion is not a mandate to change retrieval behavior.
Verification
2690 pass, 0 fail; typecheck clean. Independently audited: five checks passed, none failed. The audit's one recommendation, that
goop_specmay not need its allowlisting, is being handled in the next branch.One bug was found and deliberately left unfixed:
memory_savefolds reasoning and alternatives into stored content twice for decision records, inflating their search weighting. It is out of scope for a documentation change and is tracked for a fix.