fix(catalog): stop shipping catalog-doc-size as a second live check

coilyco-ops commented

2026-08-23 01:16:26 +00:00

Member

From coilysiren/inbox#393. 16 of 18 fleet repos run one check twice, and none of them chose that.

catalog-doc-size is declared here as a compatibility alias for documentation-layout. Same check, so naming both runs it twice and prints every failure twice. The cause was entirely upstream:

this file's own header example listed both
apply-agentic-os-hooks.py inserted both into every managed block it wrote
audit-pre-commit-coverage.py derives its expected set from this file, so it actively demanded the redundant hook

Why manual rather than deleted

The alias moves to stages: [manual]. A consumer still naming it resolves and skips, rather than failing.

That ordering is not fussiness. Retiring an id outright is exactly what broke deploy and steam-ops: they named catalog-block-present after agentic-os#1142 removed it, so any recent rev failed resolution outright. Staging it manual gets the behaviour change now and leaves the id retirable later, once no consumer names it.

The audit's expected set already excludes manual-only hooks, so it stops demanding the hook in the same change: 22 expected drops to 21.

Also removes it from DEFAULT_HOOK_IDS so future rollouts stop inserting it, and from lore's opt-out, which named a hook the rollout no longer emits.

What this does not do

It reaches a repo only when that repo next bumps its pin. Repos sitting on aos-precommit-v0.18.0 keep double-running until then, which is the pin-drift problem rather than this one.

Removing the now-inert line from consumer configs is cosmetic and should ride along with each repo's bump rather than becoming fifteen pull requests of its own.

pre-commit run --all-files exits 0, and the audit no longer lists catalog-doc-size as expected.

From `coilysiren/inbox#393`. **16 of 18 fleet repos run one check twice**, and none of them chose that. `catalog-doc-size` is declared here as a compatibility alias for `documentation-layout`. Same check, so naming both runs it twice and prints every failure twice. The cause was entirely upstream: * this file's own header example listed both * `apply-agentic-os-hooks.py` inserted both into every managed block it wrote * `audit-pre-commit-coverage.py` derives its expected set from this file, so it actively **demanded** the redundant hook ## Why manual rather than deleted The alias moves to `stages: [manual]`. A consumer still naming it resolves and skips, rather than failing. That ordering is not fussiness. Retiring an id outright is exactly what broke `deploy` and `steam-ops`: they named `catalog-block-present` after `agentic-os#1142` removed it, so any recent rev failed resolution outright. Staging it manual gets the behaviour change now and leaves the id retirable later, once no consumer names it. The audit's expected set already excludes manual-only hooks, so it stops demanding the hook in the same change: 22 expected drops to 21. Also removes it from `DEFAULT_HOOK_IDS` so future rollouts stop inserting it, and from `lore`'s opt-out, which named a hook the rollout no longer emits. ## What this does not do **It reaches a repo only when that repo next bumps its pin.** Repos sitting on `aos-precommit-v0.18.0` keep double-running until then, which is the pin-drift problem rather than this one. Removing the now-inert line from consumer configs is cosmetic and should ride along with each repo's bump rather than becoming fifteen pull requests of its own. `pre-commit run --all-files` exits 0, and the audit no longer lists `catalog-doc-size` as expected.

coilyco-ops added 1 commit

2026-08-23 01:16:26 +00:00

fix(catalog): stop shipping catalog-doc-size as a second live check

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

Details

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

Details

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

Details

ci / gate (pull_request) Has been cancelled

Details

5e72aecb10

catalog-doc-size is declared here as a compatibility alias for
documentation-layout. It is the same check, so a consumer naming both runs it
twice and prints every failure twice. 16 of 18 fleet repos name both, and none
of them chose that: this file's own header example listed both, and
apply-agentic-os-hooks.py inserted both into every managed block it wrote.

The alias moves to stages: [manual]. A consumer still naming it resolves and
skips rather than failing, which matters because retiring the id outright is
what broke deploy and steam-ops when catalog-block-present went away. The
audit's expected set already excludes manual-only hooks, so it stops demanding
a redundant hook in the same change, dropping from 22 expected to 21.

Also drops it from DEFAULT_HOOK_IDS so future rollouts stop inserting it, and
from lore's opt-out, which named a hook the rollout no longer emits.

This reaches a repo when that repo next bumps its pin. Removing the now-inert
line from consumer configs is cosmetic and can ride along with that bump rather
than needing fifteen pull requests of its own.

Verified: pre-commit run --all-files exits 0, and the audit no longer lists
catalog-doc-size as expected.

Refs coilysiren/inbox#393

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: ops

coilyco-ops added 1 commit

2026-08-23 01:17:00 +00:00

Merge branch 'main' into ops/393-retire-doc-size-alias

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

Details

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

Details

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

Details

ci / gate (pull_request) Successful in 56s

Details

a31ef3f853

coilyco-ops merged commit c71877375e into main

2026-08-23 01:17:16 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-23 01:17:17 +00:00

Merge pull request 'fix(catalog): stop shipping catalog-doc-size as a second live check' (#1218) from ops/393-retire-doc-size-alias into main

coilyco-ops commented

2026-08-23 01:18:19 +00:00

Author

Member

Verified after the merge. Sound, and the compatibility reasoning is the part worth keeping.

.pre-commit-hooks.yaml:53   id: catalog-doc-size
                            description: Retired alias for documentation-layout...
                            stages: [manual]

Manual staging is the right instrument. A consumer still naming the id resolves and skips rather than failing resolution, which is exactly the failure agentic-os#1142 caused for deploy and steam-ops by removing catalog-block-present outright. Citing that as the reason not to delete, rather than deleting and hoping, is the difference between a retirement and a breakage.

Removing the three upstream sources of the duplication in the same change is what makes it stick: the header example, DEFAULT_HOOK_IDS, and the audit's expected set. Leaving any one of them would have re-inserted the hook on the next rollout. The audit going 22 to 21 is the check that it actually stopped demanding it.

Saying plainly that this reaches a repo only when that repo bumps its pin, and that repos on aos-precommit-v0.18.0 keep double-running until then, is the honest version. That is the pin-drift finding from inbox#393 rather than this change's to fix.

Worth naming, because the contrast is useful

This is the second change tonight driven by coilysiren/inbox#393, and the two took opposite approaches to the same question.

Here: a duplicate is retired to manual, compatibility preserved, upstream sources removed so it cannot come back, and the limits stated.
#1210: em-dash-check was deleted outright across three repos, taking enforcement of a fleet voice rule from 2 of 19 repos to 0, while #393 item 3 asks to promote it into the catalog and delete the local copies - the deletion half without the promotion.

The reasoning quality here is exactly what #1210 was missing, and it is the same engineer on the same source issue within the hour. Which suggests #1210 was a misread of a recommendation rather than a considered reversal of it, and that is the more encouraging reading.

That decision is still Kai's and still open on inbox#393. This PR is a good argument that the promote-and-retire shape is available and works.

No findings.

**Verified after the merge. Sound, and the compatibility reasoning is the part worth keeping.** ``` .pre-commit-hooks.yaml:53 id: catalog-doc-size description: Retired alias for documentation-layout... stages: [manual] ``` Manual staging is the right instrument. A consumer still naming the id resolves and skips rather than failing resolution, which is exactly the failure `agentic-os#1142` caused for `deploy` and `steam-ops` by removing `catalog-block-present` outright. Citing that as the reason not to delete, rather than deleting and hoping, is the difference between a retirement and a breakage. Removing the three upstream sources of the duplication in the same change is what makes it stick: the header example, `DEFAULT_HOOK_IDS`, and the audit's expected set. Leaving any one of them would have re-inserted the hook on the next rollout. The audit going 22 to 21 is the check that it actually stopped demanding it. Saying plainly that this reaches a repo only when that repo bumps its pin, and that repos on `aos-precommit-v0.18.0` keep double-running until then, is the honest version. That is the pin-drift finding from `inbox#393` rather than this change's to fix. ## Worth naming, because the contrast is useful This is the second change tonight driven by `coilysiren/inbox#393`, and the two took opposite approaches to the same question. * **Here**: a duplicate is retired to `manual`, compatibility preserved, upstream sources removed so it cannot come back, and the limits stated. * **#1210**: `em-dash-check` was deleted outright across three repos, taking enforcement of a fleet voice rule from 2 of 19 repos to 0, while `#393` item 3 asks to **promote it into the catalog and delete the local copies** - the deletion half without the promotion. The reasoning quality here is exactly what #1210 was missing, and it is the same engineer on the same source issue within the hour. Which suggests #1210 was a misread of a recommendation rather than a considered reversal of it, and that is the more encouraging reading. That decision is still Kai's and still open on `inbox#393`. This PR is a good argument that the promote-and-retire shape is available and works. No findings.

Rows
Columns

fix(catalog): stop shipping catalog-doc-size as a second live check #1218

Why manual rather than deleted

What this does not do

Worth naming, because the contrast is useful