docs(tools): split the tracker surface out of the tool loop #531

Merged

coilyco-ops merged 1 commit from eng/split-the-tracker-surface into main

2026-08-13 15:22:02 +00:00

coilyco-ops commented

2026-08-13 15:19:56 +00:00

Member

First slice of #527, which measured eighteen docs sitting at exactly the 80-line cap. This is one file, not the class, which is why it closes #529 rather than #527.

docs/sirens-echo-tools.md was at 80. Any line added to it fails catalog-doc-size and documentation-layout for whoever commits next, on a file they never opened — that is precisely how main went red earlier today in #500, when two branches each added a few lines to the mentions doc and the merge summed them.

Why this file first

Its subject is busy. The MCP roster, the tracker surface and tool-result handling all moved today. A file at the cap in a quiet corner is a landmine; one at the cap where people are actively working is a landmine with someone walking toward it.

Where the cut is

The doc carried two subjects that change for different reasons and on different schedules:

discovery, the call loop, validation and failure — moves when the harness changes
what the Forgejo server publishes, and what naming it issue_tracker selects — moves when deploy changes the guardfile

The second is now sirens-echo-tracker-surface.md, verbatim: the guardfile pin, the published tool list, the deliberately absent list, and the prompt policy issue_tracker selects. It links back to the tool loop and across to sirens-echo-issues.md, which covers when a turn files as opposed to what it may reach.

80 → 64 lines, plus a 31-line doc. Room to record the next capability in either.

Not claimed by this

Seventeen files remain at the cap. #527 keeps the measurement, the three options, and the recommendation — a pre-emptive split pass now, and a merge-time size check eventually, since the branch-versus-merge gap is the actual defect and it lives in the lane rather than here.

closes #529

First slice of #527, which measured **eighteen docs sitting at exactly the 80-line cap**. This is one file, not the class, which is why it closes #529 rather than #527. `docs/sirens-echo-tools.md` was at 80. Any line added to it fails `catalog-doc-size` and `documentation-layout` for whoever commits next, on a file they never opened — that is precisely how `main` went red earlier today in #500, when two branches each added a few lines to the mentions doc and the merge summed them. ## Why this file first Its subject is busy. The MCP roster, the tracker surface and tool-result handling all moved today. A file at the cap in a quiet corner is a landmine; one at the cap where people are actively working is a landmine with someone walking toward it. ## Where the cut is The doc carried two subjects that change for different reasons and on different schedules: - **discovery, the call loop, validation and failure** — moves when the harness changes - **what the Forgejo server publishes, and what naming it `issue_tracker` selects** — moves when deploy changes the guardfile The second is now `sirens-echo-tracker-surface.md`, verbatim: the guardfile pin, the published tool list, the deliberately absent list, and the prompt policy `issue_tracker` selects. It links back to the tool loop and across to `sirens-echo-issues.md`, which covers *when a turn files* as opposed to *what it may reach*. 80 → 64 lines, plus a 31-line doc. Room to record the next capability in either. ## Not claimed by this Seventeen files remain at the cap. #527 keeps the measurement, the three options, and the recommendation — a pre-emptive split pass now, and a merge-time size check eventually, since the branch-versus-merge gap is the actual defect and it lives in the lane rather than here. closes #529

coilyco-ops added 1 commit

2026-08-13 15:19:56 +00:00

docs(tools): split the tracker surface out of the tool loop

ci / image-build (pull_request) Successful in 27s

Details

ci / test (pull_request) Successful in 39s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

30e2dfded9

sirens-echo-tools.md sat at exactly the 80-line cap, so the next line
added to it fails the gate for whoever commits next, on a file they did
not touch. That is how main went red earlier today.

What the Forgejo server publishes, and what naming it issue_tracker
changes, is a different subject from discovery and the call loop. It also
changes on a different schedule: the surface moves when deploy changes
the guardfile, the loop moves when the harness changes.

Leaves tools.md at 64 lines with room to record the next capability. One
of the eighteen files measured in 527, filed as its own slice so that
issue is not closed by a single file.

closes #529

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-13 15:19:56 +00:00

coilyco-ops merged commit 8295848dcd into main

2026-08-13 15:22:02 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-13 15:22:03 +00:00

Merge pull request 'docs(tools): split the tracker surface out of the tool loop' (#531) from eng/split-the-tracker-surface into main

coilyco-ops referenced this pull request

2026-08-13 15:23:33 +00:00

Split sirens-echo-tools.md, which is at the 80-line cap with active work in its subject #529