feat(pre-commit): gate roles.kdl against the composed catalogue in both directions #1073

New issue

Closed

opened 2026-08-15 21:57:42 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-15 21:57:42 +00:00

Member

Nothing validates .agents/composed/ against .agents/roles.kdl.
check_composed_skills.py reads the composed sources alone and never opens
the role graph, and no other hook in the suite closes the loop.

Two failure modes therefore land silently.

Missing role block

A role agent-compose deploys can have no role block at all. A role with no
block selects nothing, so its bundle composes zero methods and every hook
still passes.

This is not hypothetical. 48c48414 deleted the parked role exec block
because the code-comments hook rejects commented-out config, correctly, and
the Executive Strategist composed zero AOS methods from 2026-08-08 until it
was noticed by hand. The AOSK side, 9a117d4, went the same way two days
later. Neither commit was wrong about the comment. The gap is that nothing
noticed the role had gone empty.

Orphaned composed source

A composed source no role selects is dead weight in the catalogue. 48c48414's
own body recorded that tooling-advisor-* and tooling-ceo-* were "now
unclaimed by any role" and shipped anyway, because a commit-message note is
not a gate.

Proposal

Extend check-composed-skills, or add a sibling, to assert both directions:

every role agent-compose catalog roles reports has a role block with at least one selector
every directory under .agents/composed/ is matched by at least one selector, with an explicit opt-out list for deliberate exceptions

The sales methods are the known deliberate exception, per
docs/role-skill-coverage-audit.md, so the opt-out list is needed rather
than optional. AOSK carries the same role graph shape and would consume the
same hook.

Found while restoring the exec role block.

Nothing validates `.agents/composed/` against `.agents/roles.kdl`. `check_composed_skills.py` reads the composed sources alone and never opens the role graph, and no other hook in the suite closes the loop. Two failure modes therefore land silently. ## Missing role block A role agent-compose deploys can have no `role` block at all. A role with no block selects nothing, so its bundle composes zero methods and every hook still passes. This is not hypothetical. 48c48414 deleted the parked `role exec` block because the code-comments hook rejects commented-out config, correctly, and the Executive Strategist composed zero AOS methods from 2026-08-08 until it was noticed by hand. The AOSK side, 9a117d4, went the same way two days later. Neither commit was wrong about the comment. The gap is that nothing noticed the role had gone empty. ## Orphaned composed source A composed source no role selects is dead weight in the catalogue. 48c48414's own body recorded that `tooling-advisor-*` and `tooling-ceo-*` were "now unclaimed by any role" and shipped anyway, because a commit-message note is not a gate. ## Proposal Extend `check-composed-skills`, or add a sibling, to assert both directions: 1. every role `agent-compose catalog roles` reports has a `role` block with at least one selector 2. every directory under `.agents/composed/` is matched by at least one selector, with an explicit opt-out list for deliberate exceptions The sales methods are the known deliberate exception, per `docs/role-skill-coverage-audit.md`, so the opt-out list is needed rather than optional. AOSK carries the same role graph shape and would consume the same hook. Found while restoring the `exec` role block.

coilyco-ops added the

labels

2026-08-17 02:36:07 +00:00

coilyco-ops referenced this issue

2026-08-17 02:40:19 +00:00

Nothing validates .agents/roles.kdl against the composed catalogue, which is why a deleted role block and three orphaned methods both went unnoticed #1076

coilyco-ops referenced this issue

2026-08-22 20:54:50 +00:00