Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: make the resolution contract match what the gate actually does

Browse Source 
Both AGENTS.md and ADR-0020 said deployed .claude/.agents trees are consulted "only
when no authoring root exists". That stopped being true in f7cc279: the walk-up
finds a root in any git repo, so the condition is now whether that root holds
plugins, not whether one was found at all. Left alone, the two documents describe a
resolver that no longer exists — and this repo's prose is load-bearing, since the
next agent reads it instead of the code.

Both now also record why a name-count delta is not an equivalent test, because it is
the obvious simplification and it is wrong: a single-plugin monorepo re-collects its
own package, adds no new name, and would pull the deployed trees back in.

ADR: 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
This commit is contained in:
Defame1297
2026-08-16 19:49:50 +00:00
parent ede3f06689
commit 79c9089122
2 changed files with 7 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/adr/0020-skill-description-and-body-context-contract.md
View File

@@ -107,8 +107,12 @@ clause**, and a **boundary clause**. Capability enumeration, output-format detai
up. When an authoring root is found the universe is every skill and agent under
`<root>/plugins/*/`, plus the target's own apm package and the packages that package declares in
its own `apm.yml` `dependencies.apm`. Sibling plugins resolve against each other, which is what a
monorepo means. Deployed `.claude/`/`.agents/` trees are consulted **only** when no authoring root
exists — the consumer case, where there is no monorepo to read. What the resolver must never do is
monorepo means. Deployed `.claude/`/`.agents/` trees are consulted **only** when the walk found no
plugin monorepo root — whether it landed on a bare `.git` ancestor or on nothing at all. That is
the consumer case, where there is no monorepo to read. The condition is which of the two passes
matched, never a name-count delta: a single-plugin monorepo re-collects its own package and adds
no new name, so a delta test reads zero there and would pull the deployed trees back in. What the
resolver must never do is
derive the universe from its own location: a `${BASH_SOURCE}`-relative repo root leaked this repo's
39-skill universe into every consumer repo running the hook through pre-commit, so a consumer skill
routing to `skill-audit` resolved against a plugin it had never installed. Checked