Cut duplicated doctrine from AGENTS.md and lower the cap that was raised twice in two days

coilyco-ops commented

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

Owner

Kai, on being shown this file at 34,485 of 34,600 chars: the file is too large. She is right, and the cap history is the sharper half of it.

The cap became headroom

2026-08-25   32,500
2026-08-28   33,600   commit subject: '...and the cap raise they need'
2026-08-29   34,600

Two raises, 2,100 chars, in two days, each one granted so a new rule could land. The pyproject.toml note directly above those keys says the opposite: the cap is deliberate back-pressure rather than headroom, and a new entry should displace one rather than extend the file.

AGENTS.md is loaded in full into every agent session, so unlike a docs/ page its size is paid continuously rather than once.

What I cut: 1,146 chars, 7 lines, all of it said twice

The four-lane list in ## Release re-defined lanes the generated git-workflow block already defines, and the --no-verify never appeared in both. Release now points at the block.
A pushed branch owes its pull request restated the block's "ALWAYS open the pull request in the same turn" and its litter framing almost verbatim. Kept only what the block does not cover: a blocked merge on a main-landing lane, and what to do when the agent cannot open the PR itself.
Native checkpoints must be remote re-derived the block's commit-and-push rule before extending it. It now names the extension, undurable work product, and the checkpoint definition, without restating the push.

Caps drop to 240 / 33,339, exactly the new size. Zero headroom, so the next entry displaces one. That is what the note already asked for.

What I did not cut, and why

Front-load the context you know you need is the largest section at 3,909 chars. It is nine distinct rules rather than restatement, so there is no duplication to remove. Its closing "this rule grants no new authority" clause reads defensive and is the obvious next target, but it is precisely what stops the rule being read as licence to reach past a role boundary. Cutting it is a judgement about doctrine rather than a duplication cut, so it is Kai's call rather than mine.

Returning to the pre-ratchet 32,500 needs another 839 chars, and I have exhausted the text that is duplicated. Everything after this point costs meaning.

#1303 is the issue for this shape: agentic-os sits on all three documentation-layout caps at once, so a new rule has nowhere to put its reasoning. This fixes the AGENTS.md third of it and does not touch the docs/ 40-of-40 half, where Kai's answer was to keep the cap and force merges rather than expand.

Kai, on being shown this file at 34,485 of 34,600 chars: *the file is too large.* She is right, and the cap history is the sharper half of it. ## The cap became headroom ``` 2026-08-25 32,500 2026-08-28 33,600 commit subject: '...and the cap raise they need' 2026-08-29 34,600 ``` Two raises, 2,100 chars, in two days, each one granted so a new rule could land. The `pyproject.toml` note directly above those keys says the opposite: the cap is deliberate back-pressure rather than headroom, and a new entry should displace one rather than extend the file. AGENTS.md is loaded in full into every agent session, so unlike a `docs/` page its size is paid continuously rather than once. ## What I cut: 1,146 chars, 7 lines, all of it said twice * **The four-lane list in `## Release`** re-defined lanes the generated git-workflow block already defines, and the `--no-verify` never appeared in both. Release now points at the block. * **`A pushed branch owes its pull request`** restated the block's "ALWAYS open the pull request in the same turn" and its litter framing almost verbatim. Kept only what the block does not cover: a blocked merge on a main-landing lane, and what to do when the agent cannot open the PR itself. * **`Native checkpoints must be remote`** re-derived the block's commit-and-push rule before extending it. It now names the extension, undurable work product, and the checkpoint definition, without restating the push. Caps drop to **240 / 33,339**, exactly the new size. Zero headroom, so the next entry displaces one. That is what the note already asked for. ## What I did not cut, and why `Front-load the context you know you need` is the largest section at 3,909 chars. It is nine distinct rules rather than restatement, so there is no duplication to remove. Its closing "this rule grants no new authority" clause reads defensive and is the obvious next target, but it is precisely what stops the rule being read as licence to reach past a role boundary. Cutting it is a judgement about doctrine rather than a duplication cut, so it is Kai's call rather than mine. Returning to the pre-ratchet 32,500 needs another 839 chars, and I have exhausted the text that is duplicated. Everything after this point costs meaning. ## Related `#1303` is the issue for this shape: agentic-os sits on all three documentation-layout caps at once, so a new rule has nowhere to put its reasoning. This fixes the AGENTS.md third of it and does not touch the `docs/` 40-of-40 half, where Kai's answer was to keep the cap and force merges rather than expand.

coilyco-ops added 2 commits

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

fix(hooks): install the pre-push hook, so pr-guard has somewhere to run

ci / aos-eval-tests (pull_request) Successful in 9s

Details

ci / aos-cli-tests (pull_request) Successful in 34s

Details

ci / gate (pull_request) Successful in 51s

Details

614ecbbc4f

The rollout installed pre-commit, commit-msg, and prepare-commit-msg and
stopped. pr-guard is `stages: [pre-push]`, so on every consumer it was a
configured hook with no git hook to fire it. Measured before the fix: 5 of 15
merge-remote-main repos had a pre-push hook at all, and each of those got it
from someone running `just pre-commit-install` by hand.

That is the failure class in agentic-os#1382: a check that does not run reads
exactly like a check that passed. It also made agentic-os#1383 partly moot
while it stood, because a guard corrected across thirteen repos still had no
hook to execute in on eight of them.

Adding pre-push to the install list closes it for every resident checkout on
the next rollout. A fresh clone is the other half and is git's `init.templateDir`,
which is an ansible rollout rather than this script's business.

Verified: deleting .git/hooks/pre-push from a consumer and re-running the
script restores it, and a template-seeded fresh clone refuses both a violating
commit and a guarded push to main.

Refs coilyco-flight-deck/agentic-os#1382

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

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

ci / aos-eval-tests (pull_request) Successful in 9s

Details

ci / aos-cli-tests (pull_request) Successful in 33s

Details

ci / gate (pull_request) Successful in 53s

Details

a471c21948

AGENTS.md was at 34,485 of 34,600 chars and 247 of 247 lines. The cap is meant
to be back-pressure, and it had become headroom: 32,500 on 2026-08-25, 33,600 on
2026-08-28 in a commit whose own subject says "and the cap raise they need", then
34,600 today. Two raises, 2,100 chars, in two days. The file is loaded in full
into every agent session, so that cost is paid continuously.

Cut 1,146 chars and 7 lines, all of it text stated twice rather than prose worth
keeping:

* the four-lane list in `## Release` re-defined lanes the generated git-workflow
  block already defines. Release now points at the block instead of restating it,
  and the `--no-verify` never was in both places.
* `A pushed branch owes its pull request` restated the block's "ALWAYS open the
  pull request in the same turn" and its litter framing almost verbatim. It keeps
  only the two cases the block does not cover: a blocked merge on a main-landing
  lane, and what to do when the agent cannot open the PR itself.
* `Native checkpoints must be remote` restated the block's commit-and-push rule
  before extending it. It now names the extension, undurable work product, and
  the checkpoint definition, without re-deriving the push.

Caps drop to 240 / 33,339, exactly the new size, so the next entry displaces one
rather than extending the file. That is what the note above them already asked
for.

Not cut: `Front-load the context you know you need` is the largest section at
3,909 chars and is nine distinct rules rather than restatement. Its closing
"grants no new authority" clause reads defensive, but it is what stops the rule
being read as licence to reach past a role boundary, so removing it is a
judgement about doctrine rather than a duplication cut.

Refs coilyco-flight-deck/agentic-os#1303

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Agent-Role: platform

coilyco-ops added 1 commit

2026-08-29 07:44:00 +00:00