coilyco-flight-deck/agent-compose

Watch

docs: 65 docs to 40 #293

New issue

Closed

opened 2026-08-17 00:48:44 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-08-17 00:48:44 +00:00

Member

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

What this repo needs

Merge 65 docs down to 40. docs/ currently holds 65 files against the large-band cap of 40, totalling 4005 lines. The ceiling at the cap is 4800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it fits, so this is consolidation rather than deletion.

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 65 docs down to 40.** `docs/` currently holds 65 files against the large-band cap of 40, totalling 4005 lines. The ceiling at the cap is 4800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it fits, so this is consolidation rather than deletion. ## 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:11:07 +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:31 +00:00

Author

Member

Measured against current main. One violation, the doc count, and this is the one big count migration that actually fits.

docs/ holds 65 files against the large band's 40-doc cap. Every one passes the per-file caps of 120 lines and 8,000 chars, so there is no trimming to do at all. The whole job is 25 merges.

It fits, unlike its neighbours

40 docs at 8,000 chars is a 320,000-char ceiling and docs/ holds 177,415, so there is room to spare. That makes agent-compose the only one of the four large count migrations that needs no deletion: sirens-echo needs about 30% removed, infrastructure 18%, and umbra 52% at its assigned small band.

But it cannot land at the current pin

At aos-precommit-v0.18.0 a doc is capped at 4,000 chars, so 40 files hold 160,000 against the 177,415 here. Merging is the change the new count cap asks for, merging makes files bigger, and the cap still in force rejects the result. So this needs the merges and the pin bump in one change, or the bump first.

That is not specific to this repo. galaxy-gen, lore, agent-proxy, and sirens-echo all hit it, and I verified it concretely in galaxy-gen by building its one required merge and watching the pinned hook reject the 4,848-char result. Raised on coilysiren/inbox#374, where the epic's "migrate first, then bump" ordering needs amending.

I have changed nothing here rather than land a merge that turns the repo red against its own pinned hook. Once the pin question is settled this is the most mechanical job left on the epic.

Measured against current `main`. **One violation, the doc count, and this is the one big count migration that actually fits.** `docs/` holds 65 files against the large band's 40-doc cap. Every one passes the per-file caps of 120 lines and 8,000 chars, so there is no trimming to do at all. The whole job is 25 merges. ## It fits, unlike its neighbours 40 docs at 8,000 chars is a **320,000-char** ceiling and `docs/` holds **177,415**, so there is room to spare. That makes agent-compose the only one of the four large count migrations that needs no deletion: sirens-echo needs about 30% removed, infrastructure 18%, and umbra 52% at its assigned small band. ## But it cannot land at the current pin At `aos-precommit-v0.18.0` a doc is capped at **4,000 chars**, so 40 files hold 160,000 against the 177,415 here. Merging is the change the new count cap asks for, merging makes files bigger, and the cap still in force rejects the result. So this needs the merges and the pin bump in one change, or the bump first. That is not specific to this repo. galaxy-gen, lore, agent-proxy, and sirens-echo all hit it, and I verified it concretely in galaxy-gen by building its one required merge and watching the pinned hook reject the 4,848-char result. Raised on coilysiren/inbox#374, where the epic's "migrate first, then bump" ordering needs amending. I have changed nothing here rather than land a merge that turns the repo red against its own pinned hook. Once the pin question is settled this is the most mechanical job left on the epic.

coilyco-ops commented

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

Author

Member

Done and landed on main (d2c6f73). pre-commit run --all-files clean, go build and go test ./... pass.

65 docs to 40, exactly the cap. The count was the whole job: every file already passed the large band's per-file caps.

The pin had to move in the same commit

At aos-precommit-v0.18.0 a doc is capped at 4,000 chars, and these docs average 2,700. So merging any pair overshoots the cap still in force, and the new count cap asks for exactly the merges the old size cap forbids. "Migrate first, then bump" cannot work here, so the pin advances to aos-precommit-v0.24.0 in the same change. At that rev the repo shows one violation, the doc count, and nothing else.

What merged

By family, and the line cap decided the grouping rather than taste. Docs here average 63 lines against a 120 cap, so two fit and three usually do not.

The six eval references became eval-ref-papers and eval-ref-platforms.
person-*, personality-*, role-*, identity/seat-identity, and the skill catalogue and selector pages each collapsed to one page.
kdl-contracts and manifest-schema stayed apart. Merged they hit 136 lines, and splitting them back is what put the repo at exactly 40 rather than 39.

Two things worth knowing

Nothing was deleted. Eleven merged pages landed over the 120-line cap and came down by joining adjacent paragraphs, not by cutting sentences. I verified word-level integrity against HEAD on the merged files: the only tokens that disappear are the per-doc ## See also blocks the merge folds away.

33 files were repointed, which is the part a merge quietly breaks. That includes Go source doc references (internal/person/person.go, internal/agentid/agentid.go, and others), two outpost README.md files under assets/, and the cross-links between merged pages. source-doc-refs and dead-cross-links both catch these, which is how I found all 65.

Done and landed on `main` (`d2c6f73`). `pre-commit run --all-files` clean, `go build` and `go test ./...` pass. 65 docs to 40, exactly the cap. The count was the whole job: every file already passed the large band's per-file caps. ## The pin had to move in the same commit At `aos-precommit-v0.18.0` a doc is capped at **4,000 chars**, and these docs average 2,700. So merging any pair overshoots the cap still in force, and the new count cap asks for exactly the merges the old size cap forbids. "Migrate first, then bump" cannot work here, so the pin advances to `aos-precommit-v0.24.0` in the same change. At that rev the repo shows one violation, the doc count, and nothing else. ## What merged By family, and the line cap decided the grouping rather than taste. Docs here average 63 lines against a 120 cap, so two fit and three usually do not. * The six eval references became **eval-ref-papers** and **eval-ref-platforms**. * `person-*`, `personality-*`, `role-*`, `identity`/`seat-identity`, and the skill catalogue and selector pages each collapsed to one page. * `kdl-contracts` and `manifest-schema` stayed **apart**. Merged they hit 136 lines, and splitting them back is what put the repo at exactly 40 rather than 39. ## Two things worth knowing **Nothing was deleted.** Eleven merged pages landed over the 120-line cap and came down by joining adjacent paragraphs, not by cutting sentences. I verified word-level integrity against `HEAD` on the merged files: the only tokens that disappear are the per-doc `## See also` blocks the merge folds away. **33 files were repointed**, which is the part a merge quietly breaks. That includes Go source doc references (`internal/person/person.go`, `internal/agentid/agentid.go`, and others), two outpost `README.md` files under `assets/`, and the cross-links between merged pages. `source-doc-refs` and `dead-cross-links` both catch these, which is how I found all 65.

coilyco-ops closed this issue

2026-08-17 05:08:10 +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-flight-deck/agent-compose#293

No description provided.

Rows
Columns