coilyco-flight-deck/agentic-os

Watch

docs/ is at 40 of 40 files with five pages inside 20 chars of the char cap, so the aterm tiers have nowhere to document #1274

New issue

Open

opened 2026-08-26 07:42:46 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-26 07:42:46 +00:00

Member

Surfaced by the #1245 batch while landing #1251, #1252, #1253, #1254, #1257. Not an aterm issue and not a defect: a budget that is full, and the decision about it is Kai's.

Measured on `main`, 2026-08-26

docs/*.md files                40 of 40   (large band count cap)
total                        4,154 lines, 228,473 chars

closest to the 8,000-char cap
  7,995  docs/aterm.md
  7,980  docs/features-agents.md
  7,954  docs/skill-discipline.md
  7,930  docs/warp.md
  7,881  docs/native-shadow.md

What it cost this batch, concretely

#1251 could not add a paragraph at all. docs/aterm.md was at 120 of 120 lines, and docs/documentation-bands.md names splitting as trading the line cap for the count. Normalized the page to one paragraph per line, the same move agentic-os#1089 made on AGENTS.md, which bought 47 lines and no chars.
#1254 fit by re-trimming prose #1251 and #1252 had just added.
#1257 shipped aterm doctor, a subsystem command, with one sentence. docs/repo-layout.md says a substantial feature earns its own docs/<feature>.md walkthrough. There is no slot, and fitting even the sentence meant trimming three earlier paragraphs again.
#1255, #1256, #1258 are each a user-visible capability that wants a page. All three will hit the same wall.

Why the obvious routes do not work

Split aterm.md. The status-line composer is genuinely a second subject inside it, roughly 2,800 chars. Splitting takes the count to 41 and the hook refuses, in its own words: "splitting one doc into two to clear the size cap trades one violation for another."
Move the composer into an existing page. Tried against docs/dev-base-agent-identity.md, which already links to it and is the closest topical home: 5,024 + 2,800 = 8,469, over by 469.
Merge two related pages to free a slot. 36 of the 780 pairs fit inside one 8,000-char file, and every one of them pairs an unrelated small page with another:

4,943  aos-roles-and-voice.md + catalog-caps-reference.md   (the second is generated)
6,405  aos-roles-and-voice.md + aos-cluster-access.md
6,469  aos-roles-and-voice.md + context-budget-roles.md
6,595  aos-roles-and-voice.md + native-harness-config.md

No pair is a merge anyone would make on the content. They are the pairs that happen to be small.

A per-file exemption. docs/documentation-bands.md: "No per-file escape. excludes no longer reaches either size cap or the count."
A larger band. There is no band above large.

The options, as I read them

Raise the large band. The bands doc argues the caps as a product: 40 x 120 = 4,800 lines. This repo is at 4,154 lines across 40 files, so it is at the count ceiling with roughly 13% of the line budget unspent, because pages are dense rather than numerous. A count of 48 or 50 at the same per-file caps would restore headroom without changing what a page may be.
A deliberate consolidation pass. Fold real duplication (three skill-discipline* pages, two context-budget* pages) and reclaim slots. Neither of those pairs fits in 8,000 chars today, so this means cutting text, not just concatenating.
Accept it. Subsystem commands get a sentence, and the walkthrough rule in docs/repo-layout.md gets amended to say so.

I did not restructure the folder to route around this, because every viable merge is a taste call about information architecture rather than a mechanical fix.

Where it bites next

#1255 (identity card), #1256 (sound mark), and #1258 (live re-brand) are the remaining #1245 tiers. Each is a visible behavior change in a subsystem whose page has 5 chars of headroom.

Surfaced by the #1245 batch while landing #1251, #1252, #1253, #1254, #1257. Not an aterm issue and not a defect: a budget that is full, and the decision about it is Kai's. ## Measured on `main`, 2026-08-26 ``` docs/*.md files 40 of 40 (large band count cap) total 4,154 lines, 228,473 chars closest to the 8,000-char cap 7,995 docs/aterm.md 7,980 docs/features-agents.md 7,954 docs/skill-discipline.md 7,930 docs/warp.md 7,881 docs/native-shadow.md ``` ## What it cost this batch, concretely * **#1251** could not add a paragraph at all. `docs/aterm.md` was at 120 of 120 lines, and `docs/documentation-bands.md` names splitting as trading the line cap for the count. Normalized the page to one paragraph per line, the same move agentic-os#1089 made on AGENTS.md, which bought 47 lines and no chars. * **#1254** fit by re-trimming prose #1251 and #1252 had just added. * **#1257** shipped `aterm doctor`, a subsystem command, with **one sentence**. `docs/repo-layout.md` says a substantial feature earns its own `docs/<feature>.md` walkthrough. There is no slot, and fitting even the sentence meant trimming three earlier paragraphs again. * **#1255**, **#1256**, **#1258** are each a user-visible capability that wants a page. All three will hit the same wall. ## Why the obvious routes do not work * **Split `aterm.md`.** The status-line composer is genuinely a second subject inside it, roughly 2,800 chars. Splitting takes the count to 41 and the hook refuses, in its own words: "splitting one doc into two to clear the size cap trades one violation for another." * **Move the composer into an existing page.** Tried against `docs/dev-base-agent-identity.md`, which already links to it and is the closest topical home: 5,024 + 2,800 = 8,469, over by 469. * **Merge two related pages to free a slot.** 36 of the 780 pairs fit inside one 8,000-char file, and every one of them pairs an unrelated small page with another: ``` 4,943 aos-roles-and-voice.md + catalog-caps-reference.md (the second is generated) 6,405 aos-roles-and-voice.md + aos-cluster-access.md 6,469 aos-roles-and-voice.md + context-budget-roles.md 6,595 aos-roles-and-voice.md + native-harness-config.md ``` No pair is a merge anyone would make on the content. They are the pairs that happen to be small. * **A per-file exemption.** `docs/documentation-bands.md`: "No per-file escape. `excludes` no longer reaches either size cap or the count." * **A larger band.** There is no band above `large`. ## The options, as I read them 1. **Raise the `large` band.** The bands doc argues the caps as a product: `40 x 120 = 4,800 lines`. This repo is at 4,154 lines across 40 files, so it is at the count ceiling with roughly 13% of the line budget unspent, because pages are dense rather than numerous. A count of 48 or 50 at the same per-file caps would restore headroom without changing what a page may be. 2. **A deliberate consolidation pass.** Fold real duplication (three `skill-discipline*` pages, two `context-budget*` pages) and reclaim slots. Neither of those pairs fits in 8,000 chars today, so this means cutting text, not just concatenating. 3. **Accept it.** Subsystem commands get a sentence, and the walkthrough rule in `docs/repo-layout.md` gets amended to say so. I did not restructure the folder to route around this, because every viable merge is a taste call about information architecture rather than a mechanical fix. ## Where it bites next #1255 (identity card), #1256 (sound mark), and #1258 (live re-brand) are the remaining #1245 tiers. Each is a visible behavior change in a subsystem whose page has 5 chars of headroom.

coilyco-ops referenced this issue from a commit

2026-08-26 07:52:48 +00:00

feat(aterm): draw the identity card from form.geometry, animated on form.motion (#1255)

coilyco-ops referenced this issue

2026-08-26 07:55:01 +00:00

feat(aterm): draw the identity card from form.geometry, animated on form.motion (#1255) #1276

coilyco-ops commented

2026-08-26 07:55:15 +00:00

Author

Member

Second instance, #1255

The identity card landed in #1276 with nothing in docs/aterm.md. It is a new user-visible behavior with a generated-figure grammar, nine animation modes, and three separate ways to turn the animation off, and the page had 5 chars of headroom.

What it got instead:

one clause in docs/FEATURES.md, which had room
the grammar and the escapes explained in the PR body, which is not a durable reference anyone reads later
--no-motion and ATERM_NO_MOTION documented only in --help

That is the shape the third and fourth instances will take too. #1256 adds a sound mark with a sample-cache path and an escape of its own, and #1258 adds live re-branding through kitten @ set-colors.

Updating the running count: docs/aterm.md 7,995 of 8,000, docs/ 40 of 40, unchanged, because neither #1255 nor #1257 could spend a byte.

## Second instance, #1255 The identity card landed in #1276 with **nothing** in `docs/aterm.md`. It is a new user-visible behavior with a generated-figure grammar, nine animation modes, and three separate ways to turn the animation off, and the page had 5 chars of headroom. What it got instead: * one clause in `docs/FEATURES.md`, which had room * the grammar and the escapes explained in the PR body, which is not a durable reference anyone reads later * `--no-motion` and `ATERM_NO_MOTION` documented only in `--help` That is the shape the third and fourth instances will take too. #1256 adds a sound mark with a sample-cache path and an escape of its own, and #1258 adds live re-branding through `kitten @ set-colors`. Updating the running count: `docs/aterm.md` 7,995 of 8,000, `docs/` 40 of 40, unchanged, because neither #1255 nor #1257 could spend a byte.

coilyco-ops referenced this issue

2026-08-26 08:06:01 +00:00

feat(aterm): play the role's sound mark from pre-rendered samples (#1256) #1277

coilyco-ops referenced this issue from a commit

2026-08-26 08:30:59 +00:00

docs(aterm): fit the contract paragraph back under the char cap (#1259)

coilyco-ops commented

2026-08-26 08:31:16 +00:00

Author

Member

Third and fourth instances, and the first collision

#1256, the sound mark, landed with nothing in docs/aterm.md. --silent, ATERM_SILENT, and just aterm-sounds are documented in --help and the recipe description only.

#1259 then hit the sharper version. The status-line composer moved out of docs/aterm.md while I was working, which freed roughly 1,500 chars, so the contract paragraph fit. Then #1279 landed its own additions to the same page inside the same hour, my branch merged them, and the page went to 8,481 of 8,000. Fitting it cost four rewrite passes of my own paragraph and, in the end, deleting the clause that documented the default-seat check.

That is the part worth adding to this issue: it is no longer only "a new feature has nowhere to go". Two agents adding to the same page in the same hour now overflow it, and neither one's addition is unreasonable. The page has no slack for concurrency.

What the composer move settles

Moving the composer into docs/dev-base-agent-identity.md was one of the routes this issue priced and rejected at 5,024 + 2,800 = 8,469, over by 469. Whoever did it made it fit by trimming, and it now sits at 7,236. So the route works with an edit, and the folder is still 40 of 40 with no slot for a new page.

Running count

docs/*.md files          40 of 40
docs/aterm.md            7,984 of 8,000    (after four trim passes)
docs/dev-base-agent-identity.md  7,236 of 8,000

Deferred so far: the doctor walkthrough (#1257), the identity card grammar and its three animation escapes (#1255), the sound-mark vocabulary and its escapes (#1256), and the default-seat contract check (#1259).

## Third and fourth instances, and the first collision **#1256**, the sound mark, landed with nothing in `docs/aterm.md`. `--silent`, `ATERM_SILENT`, and `just aterm-sounds` are documented in `--help` and the recipe description only. **#1259** then hit the sharper version. The status-line composer moved out of `docs/aterm.md` while I was working, which freed roughly 1,500 chars, so the contract paragraph fit. Then #1279 landed its own additions to the same page inside the same hour, my branch merged them, and the page went to **8,481 of 8,000**. Fitting it cost four rewrite passes of my own paragraph and, in the end, deleting the clause that documented the default-seat check. That is the part worth adding to this issue: it is no longer only "a new feature has nowhere to go". Two agents adding to the same page in the same hour now overflow it, and neither one's addition is unreasonable. The page has no slack for concurrency. ## What the composer move settles Moving the composer into `docs/dev-base-agent-identity.md` was one of the routes this issue priced and rejected at 5,024 + 2,800 = 8,469, over by 469. Whoever did it made it fit by trimming, and it now sits at 7,236. So the route works with an edit, and the folder is still 40 of 40 with no slot for a new page. ## Running count ``` docs/*.md files 40 of 40 docs/aterm.md 7,984 of 8,000 (after four trim passes) docs/dev-base-agent-identity.md 7,236 of 8,000 ``` Deferred so far: the doctor walkthrough (#1257), the identity card grammar and its three animation escapes (#1255), the sound-mark vocabulary and its escapes (#1256), and the default-seat contract check (#1259).

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/agentic-os#1274

No description provided.

Rows
Columns

docs/ is at 40 of 40 files with five pages inside 20 chars of the char cap, so the aterm tiers have nowhere to document #1274

Measured on main, 2026-08-26

What it cost this batch, concretely

Why the obvious routes do not work

The options, as I read them

Where it bites next

Second instance, #1255

Third and fourth instances, and the first collision

What the composer move settles

Running count

Measured on `main`, 2026-08-26