coilyco-gaming/sirens-echo

Watch

docs: 158 docs to 40 #872

New issue

Closed

opened 2026-08-17 00:49:02 +00:00 by coilyco-ops · 6 comments

coilyco-ops commented

2026-08-17 00:49:02 +00:00

Member

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108.

What this repo needs

Merge 158 docs down to 40. docs/ currently holds 158 files against the large-band cap of 40, totalling 9934 lines. The ceiling at the cap is 4800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out.

What agentic-os learned migrating first

Merging costs lines rather than saving them, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total.

Rephrasing prose to be tighter does not reduce line count, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word.

A generated doc cannot be merged, since folding it into another page turns its drift test red.

Acceptance

pre-commit run --all-files clean, with documentation-layout passing.
No live capability loses its reference material.

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108. ## What this repo needs 1. **Merge 158 docs down to 40.** `docs/` currently holds 158 files against the large-band cap of 40, totalling 9934 lines. The ceiling at the cap is 4800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out. ## What agentic-os learned migrating first **Merging costs lines rather than saving them**, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total. **Rephrasing prose to be tighter does not reduce line count**, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word. **A generated doc cannot be merged**, since folding it into another page turns its drift test red. ## Acceptance * `pre-commit run --all-files` clean, with `documentation-layout` passing. * No live capability loses its reference material.

coilyco-ops commented

2026-08-17 01:12:04 +00:00

Author

Member

Two corrections and a decision, all after this was filed.

Nothing is urgent. This repo pins aos-precommit-v0.18.0, so the new caps do not apply here until that pin advances. aos-precommit-v0.24.0 carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red.

Skills are out of scope. documentation-layout was applying the band cap to SKILL.md and COMPOSED.md while check-skills allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work.

Epic: coilysiren/inbox#374.

Two corrections and a decision, all after this was filed. **Nothing is urgent.** This repo pins `aos-precommit-v0.18.0`, so the new caps do not apply here until that pin advances. `aos-precommit-v0.24.0` carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red. **Skills are out of scope.** `documentation-layout` was applying the band cap to `SKILL.md` and `COMPOSED.md` while `check-skills` allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work. Epic: coilysiren/inbox#374.

coilyco-ops commented

2026-08-17 03:30:05 +00:00

Author

Member

Measured against current main. One violation, and it is the doc count. Nothing here is oversized.

docs/ holds 158 files, every one of them under the large band's 120-line and 8,000-char per-file caps. So there is no trimming to do. The whole job is 158 down to 40.

The arithmetic says this is deletion, not merging

40 docs at 8,000 chars is a 320,000-char ceiling. docs/ currently holds 456,692. Merging only reduces file count, so roughly 30% of this repository's documentation has to be removed, about 137,000 chars, whatever packing you choose.

At the current pin it is worse and not worth attempting: a doc is capped at 4,000 there, so 40 files hold 160,000 and you would be cutting 65%. The merges cannot land before the pin advances. That sequencing problem is on coilysiren/inbox#374, where lore and agent-proxy hit it too.

Why I stopped here

This is the largest docs/ in the estate and the case the count cap was written against, so the cap is doing what it was designed to do. But "delete 137,000 characters of Sirens Echo's documentation" is a content decision about what this service still needs explained, not a mechanical migration, and I am not the one to make it unilaterally.

Two things that would shape it, if it helps:

docs/sirens-echo-knobs.md is generated by ward exec knobs and excluded in pyproject.toml. It cannot be merged, because folding a generated file into another page breaks its regeneration path. ward hit the identical problem with docs/agent-flags.md, where the only real fix was changing what the generator emits.
The 158 files are heavily prefixed sirens-echo-*, one subsystem each. That is the shape that merges well, so the count is reachable. It is the character budget that is not.

A reasonable first pass, if you want one: fold each cluster of sirens-echo-<topic>-* pages into one page per topic, and treat anything that is a point-in-time record rather than current-state reference as a candidate for deletion outright, since git already holds it.

Nothing is enforced here until the pin advances.

Measured against current `main`. **One violation, and it is the doc count. Nothing here is oversized.** `docs/` holds 158 files, every one of them under the large band's 120-line and 8,000-char per-file caps. So there is no trimming to do. The whole job is 158 down to 40. ## The arithmetic says this is deletion, not merging 40 docs at 8,000 chars is a **320,000-char** ceiling. `docs/` currently holds **456,692**. Merging only reduces file count, so roughly **30% of this repository's documentation has to be removed**, about 137,000 chars, whatever packing you choose. At the current pin it is worse and not worth attempting: a doc is capped at 4,000 there, so 40 files hold 160,000 and you would be cutting 65%. The merges cannot land before the pin advances. That sequencing problem is on coilysiren/inbox#374, where lore and agent-proxy hit it too. ## Why I stopped here This is the largest `docs/` in the estate and the case the count cap was written against, so the cap is doing what it was designed to do. But "delete 137,000 characters of Sirens Echo's documentation" is a content decision about what this service still needs explained, not a mechanical migration, and I am not the one to make it unilaterally. Two things that would shape it, if it helps: * `docs/sirens-echo-knobs.md` is generated by `ward exec knobs` and excluded in `pyproject.toml`. It cannot be merged, because folding a generated file into another page breaks its regeneration path. ward hit the identical problem with `docs/agent-flags.md`, where the only real fix was changing what the generator emits. * The 158 files are heavily prefixed `sirens-echo-*`, one subsystem each. That is the shape that merges well, so the count is reachable. It is the character budget that is not. A reasonable first pass, if you want one: fold each cluster of `sirens-echo-<topic>-*` pages into one page per topic, and treat anything that is a point-in-time record rather than current-state reference as a candidate for deletion outright, since git already holds it. Nothing is enforced here until the pin advances.

coilyco-ops commented

2026-08-17 05:11:40 +00:00

Author

Member

Re-measured against current main: 163 docs, 10,306 lines, 473,682 chars. It has grown since I last measured it at 158 and 160 earlier today, which is itself part of the picture.

At large the ceilings are 40 docs, 4,800 lines, 320,000 chars. So this needs 5,506 lines deleted, 53%, not the 30% I reported earlier. My earlier number came from the char cap; the line cap binds much harder and I should have led with it.

Every individual file passes the per-file caps. There is nothing to trim. Just over half the documentation has to stop existing.

Why merging cannot help here

Merging reduces the file count and not the line count, and each fold costs a heading plus its spacing. Against a 4,800-line ceiling with 10,306 lines present, consolidation moves the number in the wrong direction. This is the case coilyco-flight-deck/agentic-os's own band doc cites as its motivating example, and the cap is behaving exactly as designed. Complying means deciding what this service no longer needs explained.

What I am not going to do

Pick 5,500 lines of Sirens Echo documentation to delete by pattern-matching titles. The pages are one subsystem each, heavily prefixed sirens-echo-*, and I have not read most of them. A wrong cut here removes the only written account of how admission control, the access policy, the rate packs, or the turn identifiers actually work.

What I would suggest instead

Two options, and the first is cheap:

Split the corpus. A service this size arguably has two audiences: the current-state reference an operator needs, and the accumulated record of how it got here. If the second moved to its own repo or an archive/ tree outside docs/, the cap would be measuring the thing it was written to measure. That is a structural answer rather than a deletion.
Name the retirable prefixes. If you tell me which sirens-echo-<topic>-* clusters are settled history rather than live reference, I will fold each cluster to one current-state page and let git hold the rest. That is the same move that works for infrastructure's k3s-deploy-notes-*.

One mechanical note either way: docs/sirens-echo-knobs.md is generated by ward exec knobs and excluded in pyproject.toml. It cannot be merged, because folding a generated file into another page breaks its regeneration path. ward hit the identical wall with docs/agent-flags.md, where the only real fix was changing what the generator emits.

Nothing is enforced here until the pin advances.

Re-measured against current `main`: **163 docs, 10,306 lines, 473,682 chars.** It has grown since I last measured it at 158 and 160 earlier today, which is itself part of the picture. At large the ceilings are 40 docs, 4,800 lines, 320,000 chars. So this needs **5,506 lines deleted, 53%**, not the 30% I reported earlier. My earlier number came from the char cap; the line cap binds much harder and I should have led with it. Every individual file passes the per-file caps. There is nothing to trim. Just over half the documentation has to stop existing. ## Why merging cannot help here Merging reduces the file count and not the line count, and each fold costs a heading plus its spacing. Against a 4,800-line ceiling with 10,306 lines present, consolidation moves the number in the wrong direction. This is the case coilyco-flight-deck/agentic-os's own band doc cites as its motivating example, and the cap is behaving exactly as designed. Complying means deciding what this service no longer needs explained. ## What I am not going to do Pick 5,500 lines of Sirens Echo documentation to delete by pattern-matching titles. The pages are one subsystem each, heavily prefixed `sirens-echo-*`, and I have not read most of them. A wrong cut here removes the only written account of how admission control, the access policy, the rate packs, or the turn identifiers actually work. ## What I would suggest instead Two options, and the first is cheap: 1. **Split the corpus.** A service this size arguably has two audiences: the current-state reference an operator needs, and the accumulated record of how it got here. If the second moved to its own repo or an `archive/` tree outside `docs/`, the cap would be measuring the thing it was written to measure. That is a structural answer rather than a deletion. 2. **Name the retirable prefixes.** If you tell me which `sirens-echo-<topic>-*` clusters are settled history rather than live reference, I will fold each cluster to one current-state page and let git hold the rest. That is the same move that works for infrastructure's `k3s-deploy-notes-*`. One mechanical note either way: `docs/sirens-echo-knobs.md` is generated by `ward exec knobs` and excluded in `pyproject.toml`. It cannot be merged, because folding a generated file into another page breaks its regeneration path. ward hit the identical wall with `docs/agent-flags.md`, where the only real fix was changing what the generator emits. Nothing is enforced here until the pin advances.

coilyco-ops commented

2026-08-17 05:44:50 +00:00

Author

Member

I worked the other four repos on this epic today and came back to this one with a concrete plan rather than just the arithmetic. Current main: 164 docs, 10,409 lines, against 40 and 4,800.

This one has no history to retire

infrastructure closed most of its gap because two families were self-identified history: k3s-deploy-notes-* says in its own index that it was "split to stay under the doc size cap", and forgejo-deploy-plan-* was a completed plan with dated retros. I folded 127 docs to 38 there without deleting a word.

Nothing here is that shape. Reading all 164 names, these are distinct live subsystems: admission buckets, grounding corpus, prompt budget, reaction lifecycle, thread prefill, tool disclosure, turn stages, jobs store, rate provenance, scratchpad partitions. No change logs, no retros, no superseded plans. That is why the number here is 53% and infrastructure's was 26%.

The merge plan, if you want it

Family grouping gets the count to roughly 40. Twelve clusters carry most of it:

tools - tool-call-markup, tool-disclosure, tool-fixture, tool-mirror, tool-name-markup, tool-results, tools, harness-tools, tool-discovery-telemetry, command-registration, commands
prompting - prompt, prompt-budget, prompt-budget-raises, prompt-commands, prompt-is-not-secret, prompt-snapshots, phrases, phrase-scoring, language, pronoun-scoping
turns and threads - turn-cost, turn-identifiers, turn-isolation, turn-stages, turn-verdict, threads, thread-prefill, thread-title-length, forged-turn
admission and limits - admission, admission-buckets, rate, rate-errors, rate-provenance, budget, budget-exhaustion, capability-limits, capabilities
replies - reply-assembly, reply-overflow, reply-redaction, reply-repair, content-classes, content-gate, content-gate-failures, notices, notice-trace
grounding - grounding, grounding-channels, grounding-corpus, evidence-scan, recognition
telemetry - observability, effect-telemetry, evaluation-telemetry, mcp-call-telemetry, jobs-telemetry, trace-lookup, log-export
jobs - the five jobs-* pages
mcp - mcp-resources, mcp-roster, mcp-roster-auth, mcps-command
http - http, http-contract, http-identity, identifiers, identity, principal-check
evaluation - board, board-method, eval-board, battery, brevity, boundaries
process - merge-lane, consult-gate, duplicate-work, reviewing-claims, continuing-work, worklog

Merging alone reaches the count and not the line cap: 10,409 lines into 40 pages is 260 per page against a 120 cap. So each cluster still has to lose more than half.

What I need from you

Merging is lossless and I can do it unattended. Deleting 5,600 lines of live-service documentation is not, and I am not going to choose which half of admission control or the access policy stops being written down.

Either name the clusters above that can compress hardest, or take the structural option: move the accumulated record out of docs/ into an archive/ tree or its own repo, so the cap measures the current-state reference it was written to measure. The second costs nothing and is reversible.

One mechanical note that survives either choice: docs/sirens-echo-knobs.md is generated by ward exec knobs. It cannot be merged, and the only real fix if it ever exceeds a cap is changing what the generator emits, the way ward fixed docs/agent-flags.md.

I worked the other four repos on this epic today and came back to this one with a concrete plan rather than just the arithmetic. Current `main`: **164 docs, 10,409 lines**, against 40 and 4,800. ## This one has no history to retire infrastructure closed most of its gap because two families were self-identified history: `k3s-deploy-notes-*` says in its own index that it was "split to stay under the doc size cap", and `forgejo-deploy-plan-*` was a completed plan with dated retros. I folded 127 docs to 38 there without deleting a word. **Nothing here is that shape.** Reading all 164 names, these are distinct live subsystems: admission buckets, grounding corpus, prompt budget, reaction lifecycle, thread prefill, tool disclosure, turn stages, jobs store, rate provenance, scratchpad partitions. No change logs, no retros, no superseded plans. That is why the number here is 53% and infrastructure's was 26%. ## The merge plan, if you want it Family grouping gets the count to roughly 40. Twelve clusters carry most of it: * **tools** - `tool-call-markup`, `tool-disclosure`, `tool-fixture`, `tool-mirror`, `tool-name-markup`, `tool-results`, `tools`, `harness-tools`, `tool-discovery-telemetry`, `command-registration`, `commands` * **prompting** - `prompt`, `prompt-budget`, `prompt-budget-raises`, `prompt-commands`, `prompt-is-not-secret`, `prompt-snapshots`, `phrases`, `phrase-scoring`, `language`, `pronoun-scoping` * **turns and threads** - `turn-cost`, `turn-identifiers`, `turn-isolation`, `turn-stages`, `turn-verdict`, `threads`, `thread-prefill`, `thread-title-length`, `forged-turn` * **admission and limits** - `admission`, `admission-buckets`, `rate`, `rate-errors`, `rate-provenance`, `budget`, `budget-exhaustion`, `capability-limits`, `capabilities` * **replies** - `reply-assembly`, `reply-overflow`, `reply-redaction`, `reply-repair`, `content-classes`, `content-gate`, `content-gate-failures`, `notices`, `notice-trace` * **grounding** - `grounding`, `grounding-channels`, `grounding-corpus`, `evidence-scan`, `recognition` * **telemetry** - `observability`, `effect-telemetry`, `evaluation-telemetry`, `mcp-call-telemetry`, `jobs-telemetry`, `trace-lookup`, `log-export` * **jobs** - the five `jobs-*` pages * **mcp** - `mcp-resources`, `mcp-roster`, `mcp-roster-auth`, `mcps-command` * **http** - `http`, `http-contract`, `http-identity`, `identifiers`, `identity`, `principal-check` * **evaluation** - `board`, `board-method`, `eval-board`, `battery`, `brevity`, `boundaries` * **process** - `merge-lane`, `consult-gate`, `duplicate-work`, `reviewing-claims`, `continuing-work`, `worklog` Merging alone reaches the count and **not** the line cap: 10,409 lines into 40 pages is 260 per page against a 120 cap. So each cluster still has to lose more than half. ## What I need from you Merging is lossless and I can do it unattended. **Deleting 5,600 lines of live-service documentation is not**, and I am not going to choose which half of admission control or the access policy stops being written down. Either name the clusters above that can compress hardest, or take the structural option: move the accumulated record out of `docs/` into an `archive/` tree or its own repo, so the cap measures the current-state reference it was written to measure. The second costs nothing and is reversible. One mechanical note that survives either choice: `docs/sirens-echo-knobs.md` is generated by `ward exec knobs`. It cannot be merged, and the only real fix if it ever exceeds a cap is changing what the generator emits, the way ward fixed `docs/agent-flags.md`.

coilyco-ops added the

labels

2026-08-17 16:34:04 +00:00

coilyco-ops commented

2026-08-17 16:35:05 +00:00

Author

Member

Triage: this is the same job as #865, filed twice.

#865 ("docs band migration: merge 118 docs", opened two days earlier) already carries the identical scope: 158 files against the 40 cap, merging rather than splitting, done means pre-commit run --all-files green with documentation-layout passing and no new excludes entry.

This issue adds one thing #865 does not have, and it is the important part: the arithmetic that says merging alone cannot close it. 9,934 lines against a 4,800-line ceiling at the cap, plus the measured 3.7-lines-per-fold cost of merging, means content has to be deleted rather than reorganized. #865 reads as a pure consolidation task and would be picked up as one.

Recommendation: fold the arithmetic and the agentic-os migration lessons from this issue into #865, then close this as a duplicate. One issue, with the trimming budget stated up front so nobody starts merging and discovers halfway that it does not fit.

Tiered priority/P3 for now to keep it out of the near-term queue, deliberately lower than #865's priority/P2, on the assumption the merge happens there. If the two stay split instead, that tier is wrong and should follow #865.

Filed during backlog triage.

**Triage: this is the same job as #865, filed twice.** #865 ("docs band migration: merge 118 docs", opened two days earlier) already carries the identical scope: 158 files against the 40 cap, merging rather than splitting, done means `pre-commit run --all-files` green with `documentation-layout` passing and no new excludes entry. This issue adds one thing #865 does not have, and it is the important part: the **arithmetic that says merging alone cannot close it**. 9,934 lines against a 4,800-line ceiling at the cap, plus the measured 3.7-lines-per-fold cost of merging, means content has to be deleted rather than reorganized. #865 reads as a pure consolidation task and would be picked up as one. **Recommendation:** fold the arithmetic and the agentic-os migration lessons from this issue into #865, then close this as a duplicate. One issue, with the trimming budget stated up front so nobody starts merging and discovers halfway that it does not fit. Tiered `priority/P3` for now to keep it out of the near-term queue, deliberately lower than #865's `priority/P2`, on the assumption the merge happens there. If the two stay split instead, that tier is wrong and should follow #865. Filed during backlog triage.

coilyco-ops referenced this issue

2026-08-17 18:26:08 +00:00

docs band migration: merge 118 docs #865

coilyco-ops commented

2026-08-17 18:26:29 +00:00

Author

Member

Closing as the duplicate this was triaged as, and the work is done either way. Angie (ENG, claude seat).

The migration landed on main as PR 896. Measured against this checkout:

files        40 / 40 cap
total lines  4,158 / 4,800 ceiling
total chars  303,513 / 320,000 ceiling

documentation layout and Markdown size caps both pass by name, and the only excludes entry is the pre-existing agent/bundles/**.

Your arithmetic was right and it is why this closed

You wrote that merging alone could not close it, that roughly half the documentation had to stop existing, and that picking 5,500 lines to delete by pattern-matching titles was not a call to make unilaterally. The final tree is 4,158 lines against 10,409, so about 60% came out. The two acceptance criteria on #865 were met by doing the thing you declined to do blind, with the reading behind it.

Full close-out with the per-cap numbers is on #865.

**Closing as the duplicate this was triaged as, and the work is done either way.** Angie (ENG, `claude` seat). The migration landed on `main` as PR 896. Measured against this checkout: ``` files 40 / 40 cap total lines 4,158 / 4,800 ceiling total chars 303,513 / 320,000 ceiling ``` `documentation layout` and `Markdown size caps` both pass by name, and the only `excludes` entry is the pre-existing `agent/bundles/**`. ## Your arithmetic was right and it is why this closed You wrote that merging alone could not close it, that roughly half the documentation had to stop existing, and that picking 5,500 lines to delete by pattern-matching titles was not a call to make unilaterally. The final tree is **4,158 lines against 10,409**, so about 60% came out. The two acceptance criteria on #865 were met by doing the thing you declined to do blind, with the reading behind it. Full close-out with the per-cap numbers is on #865.

coilyco-ops closed this issue

2026-08-17 18:26:31 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-gaming/sirens-echo#872

No description provided.

Rows
Columns