pre-commit fails on four catalog hooks, and the pyproject opt-out written for two of them is inert #31

New issue

Closed

opened 2026-08-20 06:31:32 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-20 06:31:32 +00:00

Member

pre-commit run fails on four hooks against a clean checkout. None of the failures are caused by recent commits. The repo's own justfile already calls these "the broken layout hooks" and routes secret-scan around them, so the workaround is older than the diagnosis.

Two of the four are fixable here today. Two are blocked on an upstream gap that this repo already tried to work around.

Fixable in this repo now

context-load-points flags four files:

mods/AGENTS.md      real file, 3517 bytes
mods/CLAUDE.md      real file, 12 bytes, contents `@AGENTS.md`
unity/AGENTS.md     real file, 2099 bytes
unity/CLAUDE.md     real file, 12 bytes, contents `@AGENTS.md`

The hook wants AGENTS.md and CLAUDE.md only at the repo root, and says to symlink or remove a subdirectory copy. These four are the load-points of the three repos that were merged into this one, still sitting as real files.

check_context_load_points.py imports load_excludes and is_excluded and reads HOOK_ID = "context-load-points", so [tool.agentic-os.context-load-points] excludes = [...] in pyproject.toml is a supported lever this repo has not used. Whether an exclude is the right answer or the copies should genuinely be collapsed is the real question. The unity/ pair is worth collapsing, since #29 covers rewriting those docs anyway.

dead-cross-links flags three, all genuine content bugs:

mods/AGENTS.md:53 links ../eco-cycle-prep/AGENTS.md. That tree was flat-copied into coilyco-gaming/eco-ops under cycle-prep/, so the target is cross-repo now and no relative link can reach it.
unity-embedded/.agents/skills/repo-eco-mods-assets-embeded/SKILL.md:11 links ../../../AGENTS.md, resolving to unity-embedded/AGENTS.md, which does not exist.
Same file line 12 links ../../../docs/FEATURES.md, resolving to unity-embedded/docs/FEATURES.md, which does not exist.

The sibling ../../../README.md resolves fine, so only two of the skill's three pointers are dead. That skill is also still named after the retired eco-mods-assets-embeded repo, which ties it to #29.

Blocked upstream

catalog-doc-size and documentation-layout report the same two files. They are not independent checks. check_catalog_doc_size.py imports its implementation from check_documentation_layout, so one root cause produces two failures.

mods/Mods/UserCode/MinesQuarries/README.md   3372 chars over a 3000-char cap
unity/Assets/EcoModKit/Docs/README.md        75 lines over a 40-line cap
unity/Assets/EcoModKit/Docs/README.md        3072 chars over a 3000-char cap

This repo already declared the exemption, with a correct justification:

[tool.agentic-os.documentation-layout]
# Placement only. excludes stopped reaching the size caps in agentic-os#1108.
excludes = ["mods/", "unity/", "unity-embedded/"]
# Size only, and the reason belongs here. unity/Assets/EcoModKit/ is the Eco
# SDK as upstream ships it, so cutting its docs forks them. Each mod under
# mods/Mods/UserCode/ carries the README that renders as its mod.io store page,
# so cutting one changes what a player reads. Neither shape is ours to choose.
vendored = ["unity/Assets/EcoModKit/", "mods/Mods/UserCode/"]

vendored is read by nothing. The string does not appear anywhere in agentic_os/. Someone wrote a precise exemption with a sound rationale and it has never had any effect.

So the state is: excludes stopped reaching the size caps in agentic-os#1108, vendored was written as the replacement but never implemented upstream, and there is currently no working escape hatch. agentic-os#1144 is an open request to add size_excludes for exactly this. Until it lands, these two paths cannot pass, and both reasons in that comment still stand. Cutting the EcoModKit docs forks the upstream SDK, and cutting a mod README changes what a player reads on its store page.

Also worth noting

The managed hook block pins rev: aos-precommit-v0.27.0. The train is at aos-precommit-v0.32.0, five minors ahead. Worth checking whether anything relevant moved before doing the work.

Scope note

CI does not run pre-commit or typos at all, and the git hook is not installed by default in a fresh clone. This is a local-only gate today, which is why it has been failing quietly.

#28 mods.py points at retired repos
#29 unity/ docs describe the pre-consolidation world
#30 the Checkout residency section contradicts the serialized-checkouts rule
agentic-os#1144 add size_excludes
agentic-os#1108 removed excludes from the size caps

`pre-commit run` fails on four hooks against a clean checkout. None of the failures are caused by recent commits. The repo's own justfile already calls these "the broken layout hooks" and routes `secret-scan` around them, so the workaround is older than the diagnosis. Two of the four are fixable here today. Two are blocked on an upstream gap that this repo already tried to work around. ## Fixable in this repo now **`context-load-points`** flags four files: ``` mods/AGENTS.md real file, 3517 bytes mods/CLAUDE.md real file, 12 bytes, contents `@AGENTS.md` unity/AGENTS.md real file, 2099 bytes unity/CLAUDE.md real file, 12 bytes, contents `@AGENTS.md` ``` The hook wants AGENTS.md and CLAUDE.md only at the repo root, and says to symlink or remove a subdirectory copy. These four are the load-points of the three repos that were merged into this one, still sitting as real files. `check_context_load_points.py` imports `load_excludes` and `is_excluded` and reads `HOOK_ID = "context-load-points"`, so `[tool.agentic-os.context-load-points] excludes = [...]` in `pyproject.toml` is a supported lever this repo has not used. Whether an exclude is the right answer or the copies should genuinely be collapsed is the real question. The `unity/` pair is worth collapsing, since #29 covers rewriting those docs anyway. **`dead-cross-links`** flags three, all genuine content bugs: * `mods/AGENTS.md:53` links `../eco-cycle-prep/AGENTS.md`. That tree was flat-copied into `coilyco-gaming/eco-ops` under `cycle-prep/`, so the target is cross-repo now and no relative link can reach it. * `unity-embedded/.agents/skills/repo-eco-mods-assets-embeded/SKILL.md:11` links `../../../AGENTS.md`, resolving to `unity-embedded/AGENTS.md`, which does not exist. * Same file line 12 links `../../../docs/FEATURES.md`, resolving to `unity-embedded/docs/FEATURES.md`, which does not exist. The sibling `../../../README.md` resolves fine, so only two of the skill's three pointers are dead. That skill is also still named after the retired `eco-mods-assets-embeded` repo, which ties it to #29. ## Blocked upstream **`catalog-doc-size` and `documentation-layout`** report the same two files. They are not independent checks. `check_catalog_doc_size.py` imports its implementation from `check_documentation_layout`, so one root cause produces two failures. ``` mods/Mods/UserCode/MinesQuarries/README.md 3372 chars over a 3000-char cap unity/Assets/EcoModKit/Docs/README.md 75 lines over a 40-line cap unity/Assets/EcoModKit/Docs/README.md 3072 chars over a 3000-char cap ``` This repo already declared the exemption, with a correct justification: ```toml [tool.agentic-os.documentation-layout] # Placement only. excludes stopped reaching the size caps in agentic-os#1108. excludes = ["mods/", "unity/", "unity-embedded/"] # Size only, and the reason belongs here. unity/Assets/EcoModKit/ is the Eco # SDK as upstream ships it, so cutting its docs forks them. Each mod under # mods/Mods/UserCode/ carries the README that renders as its mod.io store page, # so cutting one changes what a player reads. Neither shape is ours to choose. vendored = ["unity/Assets/EcoModKit/", "mods/Mods/UserCode/"] ``` **`vendored` is read by nothing.** The string does not appear anywhere in `agentic_os/`. Someone wrote a precise exemption with a sound rationale and it has never had any effect. So the state is: `excludes` stopped reaching the size caps in agentic-os#1108, `vendored` was written as the replacement but never implemented upstream, and there is currently no working escape hatch. agentic-os#1144 is an open request to add `size_excludes` for exactly this. Until it lands, these two paths cannot pass, and both reasons in that comment still stand. Cutting the EcoModKit docs forks the upstream SDK, and cutting a mod README changes what a player reads on its store page. ## Also worth noting The managed hook block pins `rev: aos-precommit-v0.27.0`. The train is at `aos-precommit-v0.32.0`, five minors ahead. Worth checking whether anything relevant moved before doing the work. ## Scope note CI does not run pre-commit or typos at all, and the git hook is not installed by default in a fresh clone. This is a local-only gate today, which is why it has been failing quietly. ## Related * #28 mods.py points at retired repos * #29 unity/ docs describe the pre-consolidation world * #30 the Checkout residency section contradicts the serialized-checkouts rule * agentic-os#1144 add `size_excludes` * agentic-os#1108 removed `excludes` from the size caps