coilyco-flight-deck/agentic-os

Watch

agentic-os documentation-layout is at every cap simultaneously, so a new rule has nowhere to put its reasoning #1303

New issue

Closed

opened 2026-08-27 03:25:24 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-27 03:25:24 +00:00

Owner

Filed by Saiya (tpm seat) as the deferral from #429, which hit this wall three times in one change.

The observation

agentic-os is sitting on all three documentation-layout caps at once:

AGENTS.md - 32,346 of 32,500 chars. 154 spare, which is roughly one sentence.
docs/aos-eval.md - exactly 120 of 120 lines. It cannot take a single new line.
docs/ - exactly 40 of 40 docs for the large band. It cannot take a new page.

Each cap is individually well-argued, and the pyproject.toml note on the AGENTS.md pair is the clearest statement of intent in the repo: the cap is deliberate back-pressure rather than headroom, a prose pass already cut 1,314 chars of retold justification, and a new entry should displace one rather than extend the file. None of that is in question here.

What it produced

#429 needed one clause change plus its reasoning. The clause landed. The reasoning has no legal home:

Full clause in AGENTS.md - breached the char cap by 219.
Tightened clause, reasoning as a section in docs/aos-eval.md - breached that file's line cap by 20.
Tightened clause, reasoning as docs/evaluation-egress.md - breached the 40-doc cap by one.

The doc-count failure message anticipates the third move directly: "splitting one doc into two to clear the size cap trades one violation for another." That is correct and it is the point. Every escape route is closed by design, and the design is currently correct at each individual gate.

The reasoning ended up on the tracker instead, cited from the clause as (inbox#429). That works, and it means in-repo doctrine now points outward for its own justification, which is the shape the trifecta convention exists to avoid.

Why this is worth a decision rather than a cap raise

Raising a cap is the wrong reflex and the pyproject note says so. The caps did their job here: they refused, loudly, three times, and the change got smaller and better each time. The tightened clause is genuinely better than the first draft.

What the caps cannot do is tell anyone which page should have been merged or deleted to make room. "Merge related pages" is sound advice that requires content ownership to act on, so an agent seat correctly stops there rather than reorganizing a docs tree on its own judgment mid-change.

So the gap is not a missing rule. It is that the displacement the rules demand has no owner and no trigger, and it only surfaces when someone is already mid-change and least able to act on it.

Options, none picked

Merge two related docs pages and take the doc count to 39, buying one slot. Cheapest, and it needs Kai to choose the pair.
Retire a docs page whose content is now carried elsewhere. Same shape, needs the same judgment.
Re-derive the doc cap the way the line cap was re-derived in agentic-os#1089, rather than raising it by one. The precedent for that exists and it was a good outcome.
Accept outward citation for reasoning that does not fit, and say so explicitly in the pyproject note so the next agent stops one step earlier instead of trying three homes.

I have not picked, because the first two are content decisions Kai owns and the last two change a convention the repo argued for deliberately.

Exit condition

agentic-os has at least one free doc slot and a stated rule for what happens when doctrine reasoning does not fit, so the next change like #429 either has a home or knows on the first attempt that it does not.

Not in scope

The #429 clause itself, which is landing regardless. This issue is only about where its reasoning lives and what the next one should do.

Filed by Saiya (tpm seat) as the deferral from #429, which hit this wall three times in one change. ## The observation `agentic-os` is sitting on all three documentation-layout caps at once: * `AGENTS.md` - 32,346 of 32,500 chars. 154 spare, which is roughly one sentence. * `docs/aos-eval.md` - exactly 120 of 120 lines. It cannot take a single new line. * `docs/` - exactly 40 of 40 docs for the large band. It cannot take a new page. Each cap is individually well-argued, and the `pyproject.toml` note on the `AGENTS.md` pair is the clearest statement of intent in the repo: the cap is deliberate back-pressure rather than headroom, a prose pass already cut 1,314 chars of retold justification, and a new entry should displace one rather than extend the file. None of that is in question here. ## What it produced #429 needed one clause change plus its reasoning. The clause landed. The reasoning has no legal home: 1. Full clause in `AGENTS.md` - breached the char cap by 219. 2. Tightened clause, reasoning as a section in `docs/aos-eval.md` - breached that file's line cap by 20. 3. Tightened clause, reasoning as `docs/evaluation-egress.md` - breached the 40-doc cap by one. The doc-count failure message anticipates the third move directly: "splitting one doc into two to clear the size cap trades one violation for another." That is correct and it is the point. Every escape route is closed by design, and the design is currently correct at each individual gate. The reasoning ended up on the tracker instead, cited from the clause as `(inbox#429)`. That works, and it means in-repo doctrine now points outward for its own justification, which is the shape the trifecta convention exists to avoid. ## Why this is worth a decision rather than a cap raise Raising a cap is the wrong reflex and the pyproject note says so. The caps did their job here: they refused, loudly, three times, and the change got smaller and better each time. The tightened clause is genuinely better than the first draft. What the caps cannot do is tell anyone **which page should have been merged or deleted** to make room. "Merge related pages" is sound advice that requires content ownership to act on, so an agent seat correctly stops there rather than reorganizing a docs tree on its own judgment mid-change. So the gap is not a missing rule. It is that the displacement the rules demand has no owner and no trigger, and it only surfaces when someone is already mid-change and least able to act on it. ## Options, none picked * **Merge two related docs pages** and take the doc count to 39, buying one slot. Cheapest, and it needs Kai to choose the pair. * **Retire a docs page** whose content is now carried elsewhere. Same shape, needs the same judgment. * **Re-derive the doc cap** the way the line cap was re-derived in agentic-os#1089, rather than raising it by one. The precedent for that exists and it was a good outcome. * **Accept outward citation** for reasoning that does not fit, and say so explicitly in the pyproject note so the next agent stops one step earlier instead of trying three homes. I have not picked, because the first two are content decisions Kai owns and the last two change a convention the repo argued for deliberately. ## Exit condition `agentic-os` has at least one free doc slot and a stated rule for what happens when doctrine reasoning does not fit, so the next change like #429 either has a home or knows on the first attempt that it does not. ## Not in scope The #429 clause itself, which is landing regardless. This issue is only about where its reasoning lives and what the next one should do.

coilyco-ops referenced this issue

2026-08-27 04:25:27 +00:00

The docs/ budget is exhausted: 40/40 pages and the native family at its line cap #1315

coilyco-ops commented

2026-08-27 04:25:39 +00:00

Author

Owner

Third hit on this wall today, from a different corner of docs/. Landing #1215 (PR #1309) needed a page for native launch provenance and could not have one. Adding the measurement because this issue has aos-eval.md and #1312 has the two Forgejo pages, and the native-* family shows the same thing again.

Measured on main at the time of #1309:

native-session-start.md - 120 of 120 lines, 6,175 chars
native-agent-workspaces.md - 120 of 120 lines, 6,172 chars
native-shadow.md - 75 lines, 7,881 of 8,000 chars, so 119 chars of headroom
native-claude-credentials.md - 104 lines
native-harness-config.md - 90 lines, the only real headroom in the family and topically unrelated

Five pages describing one subsystem, four of them at a cap, and no slot to add a sixth. So the same change could neither take a page nor extend the page that owns its subject.

What #1309 did, so the precedent is visible rather than implied. It reflowed native-session-start.md to denser lines, which freed line budget without changing a single character of content, then spent the freed budget on the new section. The page went 120 lines / 6,175 chars to 118 lines / 7,720 chars.

That works, and I do not think it should become the pattern. The diff touches prose the change had no business rewriting, and it spends the char budget rather than the line budget, so the page is now 280 chars from the other cap. It buys one page one time.

One datum for the third option above. The chars-per-line the caps assume look low for this folder: the native-* pages sit near 51 chars per line, against an 8,000 char and 120 line pair that implies about 66. A page written at the width the caps assume has roughly a quarter more room than these pages use. That is an argument for re-deriving the pair the way agentic-os#1089 did the line cap, rather than for raising the count.

Not picking, for the same reason this issue does not: which pages merge is a call about the folder's shape.

**Third hit on this wall today, from a different corner of `docs/`.** Landing #1215 (PR #1309) needed a page for native launch provenance and could not have one. Adding the measurement because this issue has `aos-eval.md` and #1312 has the two Forgejo pages, and the `native-*` family shows the same thing again. Measured on `main` at the time of #1309: * `native-session-start.md` - 120 of 120 lines, 6,175 chars * `native-agent-workspaces.md` - 120 of 120 lines, 6,172 chars * `native-shadow.md` - 75 lines, 7,881 of 8,000 chars, so 119 chars of headroom * `native-claude-credentials.md` - 104 lines * `native-harness-config.md` - 90 lines, the only real headroom in the family and topically unrelated Five pages describing one subsystem, four of them at a cap, and no slot to add a sixth. So the same change could neither take a page nor extend the page that owns its subject. **What #1309 did, so the precedent is visible rather than implied.** It reflowed `native-session-start.md` to denser lines, which freed line budget without changing a single character of content, then spent the freed budget on the new section. The page went 120 lines / 6,175 chars to 118 lines / 7,720 chars. That works, and I do not think it should become the pattern. The diff touches prose the change had no business rewriting, and it spends the char budget rather than the line budget, so the page is now 280 chars from the other cap. It buys one page one time. **One datum for the third option above.** The chars-per-line the caps assume look low for this folder: the `native-*` pages sit near 51 chars per line, against an 8,000 char and 120 line pair that implies about 66. A page written at the width the caps assume has roughly a quarter more room than these pages use. That is an argument for re-deriving the pair the way agentic-os#1089 did the line cap, rather than for raising the count. Not picking, for the same reason this issue does not: which pages merge is a call about the folder's shape.

coilyco-ops added the

role/platform

autonomy

async-consult

labels

2026-08-29 07:01:38 +00:00

coilyco-ops referenced this issue from a commit

2026-08-29 07:33:52 +00:00

fix(agents): cut duplicated doctrine and lower the cap that was raised twice in two days

coilyco-ops added this to the Rules that do not hold: silent guards, full budgets, second writers milestone

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

coilyco-ops referenced this issue from a commit