fix(documentation-layout): the exemptions the fleet migration needs

coilyco-ops commented

2026-08-17 08:08:13 +00:00

Member

Part of coilysiren/inbox#374. Four repos in that migration are blocked on this branch, so it is the gate on the rest of the fleet.

The org profile README belongs to the forge

<org>/.github/profile/README.md is the organisation front page both Forgejo and GitHub render. It failed the band twice: over the per-doc size cap, and refused by the module-README shape whose only remedy is "move the body into a docs/*.md file" - which would blank the page.

Two commits: the exemption, and the walker fix behind it. iter_workspace_repos skipped every hidden directory name, so a repo literally named .github was invisible to every fleet rollout, which is why those three repos had never been swept at all. 117 violations were hiding behind that.

Rollout script

The band error named only pyproject.toml, so a non-Python repo was told to edit a file it does not have. The managed block the rollout writes trips code-comments on its own markers, so the rollout now writes that exclude itself rather than leaving every consumer to discover it. And eco-* repos skip typos as well as code-comments, because their misspellings are deliberate test fixtures whose spelling is the assertion.

What this deliberately does not do

The branch originally widened the skill exemption to whole trees. main has since landed a narrower version - SKILL.md and COMPOSED.md by basename, every other file under a skill directory still capped - and the merge resolves in favour of main. That decision is main s to keep, and overriding it inside a PR about the profile README would smuggle a doctrine change through an unrelated change.

The tension main s own text names is recorded in docs/documentation-bands.md instead: check-skills answers an over-long SKILL.md with "move detail into a sibling references/ file", and a band cap on that sibling makes its own instruction hard to follow. Worth its own decision.

Verified

530 tests pass, pre-commit run --all-files is green, and origin/main is merged in.

What unblocks on merge

The three .github branches (coilyco-bridge#5, coilyco-flight-deck#6, coilyco-gaming#5) are clean against this checker and red against the released one. They need this merged and an aos-precommit-v* release before their pins resolve.

Part of coilysiren/inbox#374. **Four repos in that migration are blocked on this branch**, so it is the gate on the rest of the fleet. ## The org profile README belongs to the forge `<org>/.github/profile/README.md` is the organisation front page both Forgejo and GitHub render. It failed the band twice: over the per-doc size cap, and refused by the module-README shape whose only remedy is "move the body into a `docs/*.md` file" - **which would blank the page**. Two commits: the exemption, and the walker fix behind it. `iter_workspace_repos` skipped every hidden directory name, so **a repo literally named `.github` was invisible to every fleet rollout**, which is why those three repos had never been swept at all. 117 violations were hiding behind that. ## Rollout script The band error named only `pyproject.toml`, so a non-Python repo was told to edit a file it does not have. The managed block the rollout writes trips `code-comments` on its own markers, so the rollout now writes that exclude itself rather than leaving every consumer to discover it. And eco-* repos skip `typos` as well as `code-comments`, because their misspellings are deliberate test fixtures whose spelling is the assertion. ## What this deliberately does not do The branch originally widened the skill exemption to whole trees. `main` has since landed a narrower version - `SKILL.md` and `COMPOSED.md` by basename, every other file under a skill directory still capped - and **the merge resolves in favour of main**. That decision is main s to keep, and overriding it inside a PR about the profile README would smuggle a doctrine change through an unrelated change. The tension main s own text names is recorded in `docs/documentation-bands.md` instead: `check-skills` answers an over-long `SKILL.md` with "move detail into a sibling `references/` file", and a band cap on that sibling makes its own instruction hard to follow. Worth its own decision. ## Verified 530 tests pass, `pre-commit run --all-files` is green, and origin/main is merged in. ## What unblocks on merge The three `.github` branches (coilyco-bridge#5, coilyco-flight-deck#6, coilyco-gaming#5) are clean against this checker and red against the released one. They need this merged **and an `aos-precommit-v*` release** before their pins resolve.

coilyco-ops added 8 commits

2026-08-17 08:08:14 +00:00

fix(docs): skill entrypoints belong to check-skills, not the band cap

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

Details

ci / ward-doctor (pull_request) Successful in 11s

Details

ci / gate (pull_request) Successful in 50s

Details

fd59232972

Two hooks in one suite disagreed about the same file. documentation-layout
applied the band's per-file cap to SKILL.md and COMPOSED.md, 40 lines and 3,000
chars on the small band, while check-skills allows 500 lines and 10,000 bytes
for those same files from categories.yaml.

So a skill could pass the validator that owns skills and fail the one that owns
layout. The failure it got was also wrong for it:

  .agents/composed/kai-aws-auth/COMPOSED.md: 3628 chars exceeds the 3000-char
  cap. Split large docs into smaller docs/*.md files.

A skill does not overflow into docs/. It overflows into its own references/,
which check-skills deliberately leaves uncapped and the handbook documents.

Both entrypoints are exempt here now, scoped to those two basenames so every
other Markdown file under a skill directory still takes the band cap. A test
pins that split, and removing the exemption fails it.

Found while measuring the fleet for the band migration: 56 skill files across
23 repos were in that state, and it was the dominant burden in four repos whose
docs were already fine. Kai's call on coilysiren/inbox#374.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

fix(documentation-layout): exempt whole skill trees, not just entrypoints 49bba825b6

check-skills answers an over-long SKILL.md with "move detail into a sibling
references/ file" and caps nothing but the entrypoint. Scoping the exemption to
two basenames left that overflow target capped at 40 lines, so the instruction
one hook gives is impossible to satisfy under the other. voice-corpus surfaced
it with 4 writing-email references/ files over cap.

Refs #1109

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

fix(documentation-layout): name both config files in the band error ed33256ecd

The doc already says a non-Python repo declares the band in .agentic-os.toml,
but the failure message named pyproject.toml alone, so a repo with no
pyproject.toml is told to edit a file it does not have.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

fix(config): let fleet rollouts see the .github org-profile repos 319b71b856

iter_workspace_repos skipped every dotted name at both levels, so the repo
literally named .github was invisible in all three orgs. They have therefore
never received the managed pre-commit block, which is why they carry 117
documentation-layout violations between them and no band declaration.

Scoped to that one name rather than 'any hidden git tree', so .dispatch-worktrees
and other scaffolding stay skipped even if one ever carries a .git file.

Refs coilysiren/inbox#374

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

fix(documentation-layout): the org profile README is not a module README 4fea5d2d2a

Forgejo and GitHub both render <org>/.github's profile/README.md as the
organisation front page, so its shape belongs to them. The hook was holding it
to the 3-non-blank-line signage rule, whose remedy is 'move the body into a
docs/*.md file' - which blanks the org page.

Exempts that one path from the module-README shape and the size cap, the way
CODE_OF_CONDUCT.md is exempt as verbatim upstream text. It accounted for 113 of
the 117 violations across the three .github repos.

Refs coilysiren/inbox#374

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

docs(bands): record the org-profile-README exemption 6f259edee0

Also corrects the skill-path carve-out line, which still claimed the size cap
applied to skill trees after the exemption widened to cover them.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

fix(rollout): write the code-comments exclude the managed block requires ec0b85e837

apply-agentic-os-hooks.py stamps marker comments mid-file by construction,
which is exactly the shape the code-comments hook rejects. So the script wrote
a config that the suite it installed then failed on, and every consumer
hand-added the same three-line exclude afterwards.

Writes it to pyproject.toml, or .agentic-os.toml where the repo has no
pyproject. Idempotent: an existing section is left alone.

Refs coilysiren/inbox#374

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

fix(rollout): eco-* repos skip typos too, not just code-comments

ci / ward-doctor (pull_request) Successful in 14s

Details

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

Details

ci / gate (pull_request) Successful in 1m3s

Details

a0eff9ce66

They vendor the Strange Loop Games EcoModKit under unity/, whose XML docs carry
hundreds of upstream misspellings. Those are not ours to correct, and typos has
no working per-file exclude when pre-commit passes paths explicitly, so the hook
comes off for eco repos the same way code-comments already does.

Refs coilysiren/inbox#374

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-17 08:08:14 +00:00

coilyco-ops added 1 commit

2026-08-17 08:13:20 +00:00

Merge origin/main into the documentation-layout exemptions

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

Details

ci / ward-doctor (pull_request) Successful in 12s

Details

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

Details

ci / gate (pull_request) Successful in 1m19s

Details

020f7178e7

main landed a narrower version of the skill exemption while this branch was
open: SKILL.md and COMPOSED.md by basename, with every other file under a skill
directory still capped. This branch had widened it to the whole tree.

Resolved in favour of main. That decision is main's to keep, and this branch is
about the org profile README, so overriding it here would smuggle a doctrine
change through an unrelated PR. The tension main's own text names is recorded
in docs/documentation-bands.md instead: check-skills tells an over-long SKILL.md
to move detail into a sibling references/ file, and a band cap on that sibling
makes its own instruction hard to follow.

530 tests pass and pre-commit run --all-files is green.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>