mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

chore(brain): de-surface brain_index from the model-facing MCP toolset (ADR-0012 rule 4) #78

New Issue
Closed
opened 2026-07-07 07:45:17 +00:00 by mathias · 2 comments
mathias commented 2026-07-07 07:45:17 +00:00
Owner
Copy Link
Copy Source

Charter: ADR-0012 rule 4 (hide automated mechanism) · smallest/safest of the ADR-0012 cleanup items

Problem

brain_index is exposed as a model-facing MCP verb, but its own description says it is auto-called after brain_write. An auto-called operation surfaced as a caller verb is pure cognitive load with no decision behind it — every model reading the toolset has to read it, determine it's not a thing it should call, and move on. That violates ADR-0012 rule 4.

What to do

  • Remove brain_index (Map-of-Content / _index.md regeneration) from the model-facing MCP toolset.
  • Keep the capability itself — it still needs to run (auto after writes, and as an admin/maintenance op). Just not as an LLM-callable verb. Options: keep it as an internal function only; or expose it on an admin/CLI surface (dma-cli) not the MCP tool list.
  • Confirm nothing in the current SKILLs / agents actually calls brain_index directly (grep the harnesses); if something does, that's a mis-use to fix, not a reason to keep it surfaced.

Acceptance

  • brain_index no longer appears in the model-facing MCP tool list
  • Auto-index-after-write still happens (verify with a brain_write → index refreshed)
  • Manual/admin invocation still possible via a non-LLM surface
  • No caller (SKILL/agent) left calling it directly
  • task check green

Related

  • ADR-0012 (rule 4) · sibling cleanup issues (legacy-param removal; brain consolidations under ADR-0009)
**Charter:** ADR-0012 rule 4 (hide automated mechanism) · smallest/safest of the ADR-0012 cleanup items ## Problem `brain_index` is exposed as a model-facing MCP verb, but its own description says it is **auto-called after `brain_write`**. An auto-called operation surfaced as a caller verb is pure cognitive load with no decision behind it — every model reading the toolset has to read it, determine it's not a thing it should call, and move on. That violates ADR-0012 rule 4. ## What to do - Remove `brain_index` (Map-of-Content / `_index.md` regeneration) from the **model-facing MCP toolset**. - Keep the capability itself — it still needs to run (auto after writes, and as an admin/maintenance op). Just not as an LLM-callable verb. Options: keep it as an internal function only; or expose it on an admin/CLI surface (`dma-cli`) not the MCP tool list. - Confirm nothing in the current SKILLs / agents actually calls `brain_index` directly (grep the harnesses); if something does, that's a mis-use to fix, not a reason to keep it surfaced. ## Acceptance - [ ] `brain_index` no longer appears in the model-facing MCP tool list - [ ] Auto-index-after-write still happens (verify with a `brain_write` → index refreshed) - [ ] Manual/admin invocation still possible via a non-LLM surface - [ ] No caller (SKILL/agent) left calling it directly - [ ] `task check` green ## Related - ADR-0012 (rule 4) · sibling cleanup issues (legacy-param removal; brain consolidations under ADR-0009)
mathias commented 2026-08-17 22:31:30 +00:00
Author
Owner
Copy Link
Copy Source

Done — 4e6fc7a. task check green.

  • brain_index no longer in tools/list
  • Auto-index after write untouched — it never went through the MCP verb. internal/brainstore.Store calls brain.BuildWingIndex directly on the write path, so the descriptor and the behaviour were already independent.
  • Manual invocation still possible: the tools/call dispatch case stays, so an admin caller can rebuild a Map of Content by hand
  • No caller left calling it — grepped skills/, specs/, docs/, and the Go tree. Nothing referenced it outside the MCP package itself.
  • task check green

One test worth keeping

Removing the descriptor and removing the capability look identical from the tool list, and only one of those is what this issue asked for. So there are two assertions, not one: tools/list must not contain brain_index, and tools/call on it must still dispatch without an error. Otherwise a later cleanup that deletes the dispatch case as "dead code" would pass the visible test and quietly remove the admin path.

Note on the acceptance criterion I could not check as written

"Verify with a brain_write → index refreshed" needs a live brain. What I verified instead is structural and stronger against this particular change: the auto-index call site is in the store, not in the MCP handler, so nothing this commit touched is on that path. The live check is still worth one brain_write next time you are in there.

Closing.

Done — `4e6fc7a`. `task check` green. - [x] `brain_index` no longer in `tools/list` - [x] Auto-index after write untouched — it never went through the MCP verb. `internal/brainstore.Store` calls `brain.BuildWingIndex` directly on the write path, so the descriptor and the behaviour were already independent. - [x] Manual invocation still possible: the `tools/call` dispatch case stays, so an admin caller can rebuild a Map of Content by hand - [x] No caller left calling it — grepped `skills/`, `specs/`, `docs/`, and the Go tree. Nothing referenced it outside the MCP package itself. - [x] `task check` green ### One test worth keeping Removing the descriptor and removing the capability look identical from the tool list, and only one of those is what this issue asked for. So there are two assertions, not one: `tools/list` must **not** contain `brain_index`, and `tools/call` on it must still dispatch without an error. Otherwise a later cleanup that deletes the dispatch case as "dead code" would pass the visible test and quietly remove the admin path. ### Note on the acceptance criterion I could not check as written "Verify with a `brain_write` → index refreshed" needs a live brain. What I verified instead is structural and stronger against this particular change: the auto-index call site is in the store, not in the MCP handler, so nothing this commit touched is on that path. The live check is still worth one `brain_write` next time you are in there. Closing.
mathias commented 2026-08-22 06:42:29 +00:00
Author
Owner
Copy Link
Copy Source

Verified live, 2026-08-22 — closed correctly

Re-checked during the ADR-0009 sprint because this was closed on 2026-08-17 without a recorded live confirmation.

POST https://brain-mcp.d-ma.be/mcp  {"method":"tools/list"}
→ 17 tools: brain_answer, brain_classify, brain_context, brain_edit, brain_get,
            brain_graph, brain_ingest, brain_ingest_raw, brain_pending, brain_promote,
            brain_query, brain_read, brain_tunnel, brain_update, brain_write,
            capture, session_log

brain_index is absent from the model-facing surface. The auto-index-after-write half still works — every brain_write and frontmatter-touching brain_edit in this session reindexed its wing without a caller invoking anything.

Worth noting what this issue established as precedent, since ADR-0009 and #80 both lean on it: de-surfaced ≠ removed. The capability stayed; only its model-facing verb went. That is the exact mechanism the #80 deprecation plan uses for every mechanism-named verb it retires, and the one brain_edit_root uses for a capability that must exist but must not be discoverable by a model reading tools/list. First application of ADR-0012 rule 4, and it held up.

No action. Recording the verification so the next reader does not have to redo it.

## Verified live, 2026-08-22 — closed correctly Re-checked during the ADR-0009 sprint because this was closed on 2026-08-17 without a recorded live confirmation. ``` POST https://brain-mcp.d-ma.be/mcp {"method":"tools/list"} → 17 tools: brain_answer, brain_classify, brain_context, brain_edit, brain_get, brain_graph, brain_ingest, brain_ingest_raw, brain_pending, brain_promote, brain_query, brain_read, brain_tunnel, brain_update, brain_write, capture, session_log ``` `brain_index` is **absent** from the model-facing surface. The auto-index-after-write half still works — every `brain_write` and frontmatter-touching `brain_edit` in this session reindexed its wing without a caller invoking anything. Worth noting what this issue established as precedent, since ADR-0009 and #80 both lean on it: **de-surfaced ≠ removed.** The capability stayed; only its model-facing verb went. That is the exact mechanism the #80 deprecation plan uses for every mechanism-named verb it retires, and the one `brain_edit_root` uses for a capability that must exist but must not be discoverable by a model reading `tools/list`. First application of ADR-0012 rule 4, and it held up. No action. Recording the verification so the next reader does not have to redo it.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#78