Skip to content

Say plainly which arguments do nothing - #293

Merged
hffmnnj merged 12 commits into
feat/empty-string-boundaryfrom
feat/workflow-memory-contracts
Aug 5, 2026
Merged

hffmnnj merged 12 commits into
feat/empty-string-boundaryfrom
feat/workflow-memory-contracts

Conversation

@hffmnnj

@hffmnnj hffmnnj commented Aug 5, 2026

Copy link
Copy Markdown
Owner

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.scope is declared as an enum of global, project, and both. No action reads it. goop_spec.phase is declared and ignored by all three of its actions. goop_status.verbose is 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, and goop_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_setup processes gitignoreGoopspec in a block that runs before the action switch. So action: "detect" — which every other part of its contract presents as read-only — will modify .gitignore and mutate workflow state when that argument is set. The same holds for verify and status.

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 confirm gates 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_spec may not need its allowlisting, is being handled in the next branch.

One bug was found and deliberately left unfixed: memory_save folds 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.

hffmnnj added 4 commits August 4, 2026 16:43
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.
hffmnnj and others added 8 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.
Fix duplicated decision content and record the deployment gap
@hffmnnj
hffmnnj merged commit 3e5d0cc into feat/empty-string-boundary Aug 5, 2026
@hffmnnj
hffmnnj deleted the feat/workflow-memory-contracts 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