code-comments and documentation-layout need a vendored/generated-files escape hatch #22

New issue

Open

opened 2026-05-25 06:51:24 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-05-25 06:51:24 +00:00

Owner

Problem

The code-comments validator (agentic_os/check_code_comments.py) walks every code file in the repo regardless of vendored / generated status. The SKIP_DIR_NAMES set covers obvious build dirs (__pycache__, node_modules, vendor, etc.) but does not cover:

Unity third-party asset trees (Assets/Art/ThirdPartyPublic/, Assets/Art/Editor/, etc.)
Coily-managed regenerated files (.claude/lockdown-deny.sh, .claude/settings.json)

Consequence: eco-mods-assets reports 2012 code-comment violations on first pre-commit run, almost entirely third-party DOTween / Unity asset code that Kai cannot edit without breaking the upstream.

Proposed fix

Either:

Honor a .documentation-layout-ignore / .code-comments-ignore file at repo root (pre-commit-style glob list), or
Extend SKIP_DIR_NAMES to cover ThirdParty*, ThirdPartyPublic, and add a path-based skip for .claude/lockdown-deny.sh and .claude/settings.json since those are coily-managed and the agent is told never to hand-edit them.

Option 1 is the principled answer because the unknown-third-party-trees set is open-ended.

Workaround until then

Consumer adds an exclude: regex to the upstream-ref block. The managed-block rewriter (apply-agentic-os-hooks.py) currently overwrites the consumer's hook list, so any per-repo exclude: would need to live outside the managed markers or the rollout script needs to preserve consumer exclude: annotations.

Origin

Surfaced during the v0.2.7 baseline rollout to eco-mods-assets. See coilysiren/agentic-os#61 for the rollout tracker.

**Problem** The `code-comments` validator (`agentic_os/check_code_comments.py`) walks every code file in the repo regardless of vendored / generated status. The `SKIP_DIR_NAMES` set covers obvious build dirs (`__pycache__`, `node_modules`, `vendor`, etc.) but does not cover: - Unity third-party asset trees (`Assets/Art/ThirdPartyPublic/`, `Assets/Art/Editor/`, etc.) - Coily-managed regenerated files (`.claude/lockdown-deny.sh`, `.claude/settings.json`) Consequence: `eco-mods-assets` reports 2012 code-comment violations on first pre-commit run, almost entirely third-party DOTween / Unity asset code that Kai cannot edit without breaking the upstream. **Proposed fix** Either: 1. Honor a `.documentation-layout-ignore` / `.code-comments-ignore` file at repo root (pre-commit-style glob list), or 2. Extend `SKIP_DIR_NAMES` to cover `ThirdParty*`, `ThirdPartyPublic`, and add a path-based skip for `.claude/lockdown-deny.sh` and `.claude/settings.json` since those are coily-managed and the agent is told never to hand-edit them. Option 1 is the principled answer because the unknown-third-party-trees set is open-ended. **Workaround until then** Consumer adds an `exclude:` regex to the upstream-ref block. The managed-block rewriter (`apply-agentic-os-hooks.py`) currently overwrites the consumer's hook list, so any per-repo `exclude:` would need to live outside the managed markers or the rollout script needs to preserve consumer `exclude:` annotations. **Origin** Surfaced during the v0.2.7 baseline rollout to `eco-mods-assets`. See coilysiren/agentic-os#61 for the rollout tracker.

coilysiren commented

2026-05-26 02:18:52 +00:00

Author

Owner

the config should go inside of precommit itself

coilysiren referenced this issue

2026-05-26 02:48:50 +00:00

code-comments: soften to 2 contiguous lines, exempt eco-* repos #24

coilysiren referenced this issue from a commit

2026-05-26 02:49:36 +00:00

code-comments: soften to 2 contiguous lines, exempt eco-* repos

coilysiren referenced this issue