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

Compare commits

base: Defame1297:e7ebc667b336928f55b3d67d688af0fe61b6f9c6
Branches Tags
Defame1297:main Defame1297:docs/onedev-migration-plan Defame1297:feat/66-wire-gitea-mcp-config
Defame1297:v2.0.1 Defame1297:v2.0.0 Defame1297:v1.0.0
..
compare: Defame1297:v2.0.1
Branches Tags
Defame1297:main Defame1297:docs/onedev-migration-plan Defame1297:feat/66-wire-gitea-mcp-config
Defame1297:v2.0.1 Defame1297:v2.0.0 Defame1297:v1.0.0

24 Commits
e7ebc667b3 ... v2.0.1

Author SHA1 Message Date
Defame1297
68e08c2413 Merge pull request 'docs: cut the every-session context set by 74%, and fix what the cut broke' (#105) from docs/slim-agents-md into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/105
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-08-17 14:08:23 +00:00
Defame1297
d42f6368fe fix(docs): correct claims the first fix round asserted without measuring 
Why: two blind verifiers re-ran the five preceding commits and found four
defects of the same class this branch exists to close -- a confidently stated
measured claim that does not survive re-measurement -- this time inside the
fixes themselves.

- AGENTS.md:41 still carried both phrasings c68e864 reports having corrected.
  `grep -rn repo-defined` returned exactly one hit repo-wide: that line, in the
  file every session preloads. 4d336bb edited the line directly above it.
- ADR-0021 asserted twice, in the section justifying that no gate is added,
  that the ADR-0020 validators "never open an apm.yml". All three open and
  yaml.safe_load it (skill-size-check.sh:342, both validate.sh). The conclusion
  survives -- none reads the description: key, and their globs are SKILL.md and
  *.agent.md only -- but the stated mechanism is falsified by one grep.
- architecture.md said the ADR directory holds 20 numbered ADRs; c7ba3d2 made
  it 21, and c68e864 audited that file for exactly this class of stale count.
  The number is dropped rather than corrected: `ls docs/adr/` is already the
  index, so a count in prose is a second thing to maintain.
- gates.md's new three-verdict table said `-> name` promotes an unresolved
  target to ERROR. Reproduced with fixtures: NAME_HYPH (skill-size-check.sh:543)
  requires a hyphen, so `-> gitea-prs` is checked and `-> triage` is not
  extracted at all, and the unicode arrow is never recognised. The SUGGESTION
  text advises that spelling, so taking its advice can silence the finding. The
  gap is now documented as a defect; nothing covers it, since the one arrow case
  in test-adr0020-targets.sh happens to use a hyphenated target.

Implementation notes:
- AGENTS.md:48's coverage claim is shrunk rather than chased. Restoring six
  glossary entries did not make it true: 12 more sampled terms are undefined,
  three of them (trigger/capability/boundary clause) used inside CONTEXT.md
  itself. It now says CONTEXT.md is the glossary and is not exhaustive.
- CONTEXT.md's output profile and near-miss entries are corrected against their
  sources. The first stated a false exclusion -- .github/plugin/plugin.json IS
  apm-generated; only the marketplace mirror has no profile. The second
  inverted its source's referent: description-quality.md defines a near-miss as
  a query, not a sibling skill.
- The strict-mode message named jq, which no suite guards on (`command -v jq`
  appears nowhere in tests/), while omitting python3/PyYAML, which three do.
- README's git and gitea bullets now name git-workflow and gitea-workflow.
  ADR-0021 leaves README the only inventory and architecture.md now points at
  it, so the two bullets that were short had to be completed.
- ADR-0018's 2026-08-14 correction is marked superseded in place. It asserted
  machine state in the present tense that its own 2026-08-17 note retracts.
- ADR-0021's remaining errors: six files -> four (measured from de84d1b), the
  wiki description's length 114 -> 96 chars, the codex self-contradiction, the
  cost argument overstating bumps already owed for any skill addition, and two
  claims about files this branch went on to edit.
- The "15 of 17 suites" figure is restored where I had removed it: it is a dated
  record of one incident, not a live count, and four sites now describe it the
  same way.

Impact: 16/16 pre-push hooks pass, suite 24 passed 0 skipped 0 failed. No
behaviour change; every edit is prose or a comment.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 13:18:55 +00:00
Defame1297
c68e864159 docs(spec): correct eight claims the trim carried into the new files 
Why: the relocation into gates.md and architecture.md moved text faster than it
verified it, and a review found eight assertions that do not survive contact
with the repo.

- gates.md cited docs/research/examples/, which does not exist; the tree is at
  plugins/kyberforge/docs/research/examples/. The same wrong string survives at
  ADR-0013:98, where it originated, and is tracked separately.
- gates.md's description-budget arithmetic was built on 23,427, a figure
  ADR-0020 measured at f9b919d and pins there, and compared a name-inclusive
  total against a description-only ceiling. Dropped rather than re-measured,
  following the precedent this branch set for CONTEXT.md's token figure: a
  second live copy is a second thing to go stale.
- gates.md listed "every boundary-clause routing target must resolve" as a hard
  FAIL. skill-size-check.sh emits unresolved targets as SUGGESTION by default,
  promotes to ERROR only when terminal and either route-notated or corroborated
  by a resolving target in the same sentence, and reports INFO DID NOT RUN when
  no universe resolves. Verified with five fixtures; replaced with a
  three-verdict table.
- gates.md and README called `pre-commit run --hook-stage pre-push --all-files`
  the whole push gate. check-release-needed.sh exits 0 unless
  PRE_COMMIT_REMOTE_BRANCH is refs/heads/main, which only the real git hook
  exports -- its own header comment titles this a "Known gap".
- "repo-defined" was loose: the two meta hooks are also declared here, and what
  separates them is repo: meta from repo: local.
- architecture.md claimed `when:` appears in two of 39 skill sources. Exactly
  one SKILL.md carries it; the second hit is a META.md. The likely origin is
  skill-implementation-workflow.md:233, which claims META.md sits alongside
  every skill when one exists in the whole tree.
- architecture.md said core/AGENTS.md is "deployed beside" CLAUDE.md.
  deploy-manifest.sh sends them to ~/.claude/ and ~/.agents/ respectively; the
  relation is import, not adjacency.
- gates.md's see-also cited ADRs as bare stems where its neighbours use paths.

Implementation notes: architecture.md's closing pointer sent readers to the
published description "for what a consumer actually gets", which was true
against an enumeration and is not after ADR-0021. It now names the boundary
relationship and points at the skills tree and README for an inventory. README's
bin bullet gains caveman and zoom-out, since ADR-0021 leaves it the only place
an inventory lives.

Impact: 16/16 pre-push hooks pass. Deliberately not fixed here and tracked
separately: the 12 pre-commit-stage hooks gates.md does not document, its own
SentenceOpenerThereIs violation, and README's missing scripts/install.sh step.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:29:16 +00:00
Defame1297
c7ba3d2ccf chore(apm): retire skill enumeration from published descriptions 
Why: enumerating a plugin's skills in its published description has now failed
three times in four days, the third time inside the correction for the second.

bb9158d (Aug 14) fixed core's description, which described bin's skills. That
failure was wrong content, not an incomplete list -- a syntactically perfect
four-item enumeration that belonged to a different plugin -- so enumerating
harder could not have caught it, and bb9158d's own fix replaced the enumeration
with a domain boundary. 65bac15 and de84d1b then cited that precedent while
doing the opposite, and the re-enumeration is itself incomplete: caveman and
zoom-out are unnamed in bin, git-workflow is unnamed in git despite 65bac15's
message claiming it was added, and gitea-workflow is unnamed in gitea. 23 of 27
skills named at the third attempt.

Nothing checks any of this. check-manifests.sh does not contain the string
"description"; apm audit --ci, apm pack --check-clean and
sync-plugin-content.sh --check all compare compiled output against apm.yml, so
their job is to propagate whatever it says byte-for-byte. The wiki claim passed
all fourteen pre-push hooks every day it was published. Enumeration also makes a
marketplace release the consequence of a directory appearing.

Implementation notes:
- ADR-0021 records the decision, the three failures, and why no gate is added:
  the check is one-directional, cannot see an invented capability, and a
  correspondence map would relocate the same per-skill maintenance one file over.
- bin 1.1.4 -> 1.1.5, git 1.3.4 -> 1.3.5, gitea 1.3.5 -> 1.3.6,
  marketplace.version 0.4.4 -> 0.4.5, all PATCH under per_package.
- apm.yml's top-level version: is restored to lockstep at 0.4.5. It has moved
  with marketplace.version in all eleven commits that ever touched the file
  until this branch left it at 0.4.2, and apm.yml's own comment records it as
  live and consumed by apm audit.
- git's boundary names the pre-commit hooks explicitly: pc-author and pc-run are
  not git operations, and a boundary drawn narrower than the contents is the
  same defect one level up.
- Regenerated with apm pack for the marketplace manifests and
  sync-plugin-content.sh --all for the per-plugin ones; both mirrors verified
  byte-identical.

Impact: consumer-facing. 16/16 pre-push hooks pass, suite green, generated diff
is 26 insertions and 26 deletions across 8 files with no incidental churn.

Refs: #105
ADR: 0021

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:28:55 +00:00
Defame1297
4d336bbf35 docs: stop the preloaded instruction set asserting machine state 
Why: four defects in the files every session pays for, all introduced or left
behind by the trim.

AGENTS.md told agents the `<plugin>:` form still resolves "because user-scope
native installs were left enabled on purpose", and that a working namespaced
call "is not something to fix". That premise is false on this machine:
installed_plugins.json is empty, no enabledPlugins key exists in ~/.claude.json,
and ~/.apm/marketplaces.json is empty. ADR-0018 already reversed itself once on
this exact claim (Correction 2026-08-14) using that same enablement as its
evidence, so flipping the assertion again would be the third revision in three.
Both files now assert nothing about install state at all, which removes the
flip-flop surface instead of re-aiming it.

The other three are guard-rails whose instruction survived the trim while the
caveat that made it safe did not:
- The run-tests.sh line omitted --strict, so it named the one invocation that
  reports SKIPPED rather than failed when a dependency is missing. gates.md
  records this gate going green having verified 15 of 17 suites on a vale-less
  PATH. .pre-commit-config.yaml:70 already uses --strict for that reason.
- The .claude/settings.json prohibition lost its ADR-0019 exception, so an agent
  applying it literally would strip apm's own merged SessionStart entry and
  create the drift the rule exists to prevent.
- LESSONS.md still routed graduated rules to CONTEXT.md's Principles section,
  which this branch deleted.

Implementation notes: the six terms the trim dropped while AGENTS.md still
claimed CONTEXT.md glosses everything -- authoring root, content mirror, apm
package, output profile, near-miss, vacuous green -- are restored as one-line
entries per CONTEXT-FORMAT.md, sourced from architecture.md, gates.md and
skill-audit's description-quality.md rather than reworded. ADR-0018 gets a third
dated note recording the observation and the fact that the state has now been
described two ways, and its stale user-scope inventory is replaced by a pointer
to it; the decision it records is untouched. LESSONS.md:3 carried the identical
stale claim as :5 and is fixed with it.

Impact: preloaded context is now free of assertions about machine state.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:28:30 +00:00
Defame1297
36596598ef fix(tests): point the strict-mode dependency citation at README.md 
Why: this branch moved the prerequisites list out of AGENTS.md into README.md
but left three references behind. The worst is run-tests.sh's --strict failure
message, which a developer is handed at the exact moment a push gate fails and
they need the dependency list: it named AGENTS.md, which no longer documents
vale, apm or jq anywhere. 56cc173 re-anchored this same class of citation in
.pre-commit-config.yaml, scripts/check-vale-style-sync.sh,
scripts/sync-marketplace-mirror.sh and tests/test-check-vale-style-sync.sh --
tests/run-tests.sh was missed, and it is the only one a human actually reads.

Implementation notes:
- run-tests.sh:262 (user-visible), run-tests.sh:16 (header rationale) and
  test-run-tests.sh:395 all now cite README.md's Prerequisites table, verified
  to name vale, apm, jq, python3/PyYAML and the claude CLI.
- Every assertion on this message greps for "a skip is a SETUP ERROR", which
  sits before the changed clause, so no test needed updating.
- test-vale-wrap.sh's bash 3.2 citation is corrected in the same pass: it
  credited LESSONS.md and the script headers, but LESSONS.md's only mention of
  3.2 is an aside inside an unrelated lesson, not a target declaration. It now
  cites scripts/lib/batch-run.sh and providers/claude-code/statusline-command.sh,
  which do declare it. The citation 56cc173 replaced was already false, so this
  finishes a half-fix rather than correcting a regression.

Impact: forced the strict-failure path with vale removed from PATH and confirmed
the corrected message printing -- 21 passed, 3 skipped, exit 1. Full suite with
vale present: 24 passed, 0 skipped, 0 failed.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:28:11 +00:00
Defame1297
b1ea14df3e fix(scripts): make the mirror DRIFT fix line safe to copy-paste 
Why: bd2bf66 restored the `apm pack` guard-rail by appending it to the `Fix:`
command after `--`, which made the printed line stop being runnable. Pasting it
ran the script with ~24 stray argv entries: `${1:-}` became `--`, so CHECK
stayed 0, no shift occurred, and `[[ $# -eq 0 ]] || usage` printed usage and
exited 1. The user got a usage error from the tool meant to fix their problem,
and the mirror stayed stale.

The unquoted backticks around `apm pack` were a second hazard in the same line:
the paste command-substituted a real `apm pack` run before this script was ever
reached, so the first error a user saw came from apm, not from here.

Implementation notes:
- The runnable command now stands alone on its own line, and the rationale
  follows as a separate `Note:` echo.
- Backticks downgraded to single quotes; a line printed next to a
  copy-pasteable command must not contain shell metacharacters.
- The guard-rail text is otherwise preserved verbatim. It exists because apm
  ships no output profile targeting this path, so `apm pack` does not refresh
  it, and expecting it to is the drift this hook prevents.

Impact: reproduced the break on a scratch copy, then verified the fix by pasting
the printed command verbatim — exit 0, mirror synced, re-check clean.
tests/test-sync-marketplace-mirror.sh asserts only exit codes and file contents,
so nothing pins this message and it could regress silently; tracked separately.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:27:56 +00:00
Defame1297
de84d1b677 chore(apm): give bin a published description that describes it 
Why: bin's marketplace description read "A place for things to be binned" — a
routing boundary sitting in the enumeration slot, phrased as a joke. It is what
a consumer sees in the marketplace listing for a plugin shipping eleven
substantive skills: research, write-docs, tdd, prototype, triage, diagnose,
improve-codebase-architecture, grill-me, grill-with-docs, zoom-out and caveman.

This is the same category error b0ef503 fixed for git and gitea, and the same
text bb9158d moved out of core's description in August — "triage, diagnosis,
architecture review" left core precisely because those skills live in bin, so
bin is where it should have landed.

Implementation notes: bin 1.1.3 -> 1.1.4, marketplace 0.4.3 -> 0.4.4, PATCH for
metadata under the per_package strategy. README's bin line mirrors the new
description. architecture.md's routing boundary is deliberately left as
"unsorted skills that have not earned a home yet" — that is still true, and it
answers a different question than the listing does.

Impact: consumer-facing. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace, validate-plugins and
apm-audit-ci all pass.
 2026-08-17 10:33:25 +00:00
Defame1297
65bac15257 chore(apm): correct git and gitea published descriptions and regenerate 
Why: both plugins' published descriptions named capabilities that do not exist
and omitted ones that do. `gitea` advertised wikis — no wiki skill exists and
`grep -ri wiki plugins/gitea/.apm/` is empty — while omitting gitea-branches and
gitea-files. `git` advertised pull requests, which are gitea's, while omitting
pc-author/pc-run, git-submodules and git-workflow. These are compiled into
plugin.json and both marketplace.json files, so they are published metadata, not
internal notes.

This is the same defect bb9158d fixed on `core` in August, so the fix follows
that precedent exactly: correct the package apm.yml and the root marketplace
entry together — fixing only the package manifest leaves it half-propagated,
since the root entry is what reaches the compiled marketplace.

Implementation notes:
- git 1.3.3 -> 1.3.4, gitea 1.3.4 -> 1.3.5, marketplace 0.4.2 -> 0.4.3, all
  PATCH for metadata under the per_package strategy at apm.yml:76.
- Regenerated with `apm pack` for the two marketplace manifests and
  `scripts/sync-plugin-content.sh --all` for the four per-plugin plugin.json
  files; `apm pack` alone does not touch those. `scripts/sync-marketplace-mirror.sh`
  refreshed the Copilot legacy mirror, which no apm profile targets.
- README's gitea line mirrors the new published description. The routing
  boundaries in architecture.md deliberately do not, since they answer a
  different question.

Impact: consumer-facing. Anyone reading the marketplace now sees what these
plugins ship. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace and apm-audit-ci all pass.
 2026-08-17 10:13:31 +00:00
Defame1297
b0ef503485 docs: correct plugin scope, hook ordering and the setup gap 
Why: the review found architecture.md's plugin table and README's plugin list
were both written by enumerating what happened to be in each plugin, so both
went stale immediately — README credited `git` with pull requests it has no
skill for, and both omitted `pc-author`/`pc-run`. bb9158d fixed this same class
on `core` in August and it recurred here, so the fix is to stop enumerating in
the place whose job is routing.

Implementation notes:
- architecture.md's table now states routing boundaries only, with a note saying
  so and pointing at each plugin's published apm.yml description for the actual
  inventory. Two boundaries are named explicitly: `core` vs `kyberforge` (kept),
  and `git` vs `gitea` — wire protocol against a local clone versus the forge's
  HTTP API, which is why git-branches and gitea-branches are not duplicates.
- The `git` row is widened to cover git hook tooling rather than moving
  pc-author/pc-run elsewhere. pre-commit manages .git/hooks/, so the placement
  was always right and the row was simply under-described.
- README's setup block had a comment where step 2's command should be. It now
  carries `pre-commit install -t pre-commit -t commit-msg -t pre-push`, verified
  against the three stages in .pre-commit-config.yaml and the three hooks in
  .git/hooks/. pc-run is still named, as the option rather than the only path.
- README:11 said each plugin carries agents, hooks and MCP servers. Only
  kyberforge ships hooks and only bin ships an MCP server.
- gates.md:30 claimed its hook list was in config order; it is grouped by
  concern, which is the better layout, so the claim is corrected to match.

Impact: docs-only. gitea's published description is corrected separately, since
that regenerates consumer-facing manifests.
 2026-08-17 10:11:59 +00:00
Defame1297
bd2bf667c5 docs: restore two guard-rails the trim dropped 
Why: 1929ffd and b9c7762 preserved every constant, hook ID and error string,
but two don't-re-litigate notes were lost. Both were guard-rails — they fired
from preloaded context, before the mistake. Restoring the sentence to an
on-demand spec doc restores the text without restoring the function, since an
on-demand file is opened after a plan is formed, not before.

Implementation notes: placed by when each note must fire, not by what it is
about.
- "Do not expect `apm pack` to refresh the .github/plugin/marketplace.json
  mirror" now lives in the DRIFT failure message of the script and hook that
  already catch that exact mistake. It costs no preloaded tokens, fires at the
  moment of the error, and cannot be missed. No test asserts on that message;
  --check and shellcheck both pass.
- Plugin self-containment has no gate that fires on it, so it goes in
  architecture.md's Plugin model beside "self-contained plugin units", stated as
  the constraint it is rather than a description, with the two consequences that
  make it load-bearing: the duplicated Vale styles (ADR-0014) and ADR-0020's
  constants copied into three validators.

Impact: the every-session set is unchanged — neither note returns to AGENTS.md.
 2026-08-17 10:10:55 +00:00
Defame1297
ba7cec7672 docs(adr): amend ADR-0007 and ADR-0015 for the CONTEXT.md trim 
Why: b9c7762 gave dated amendments to ADR-0013, ADR-0015 and ADR-0017, but two
pointers were missed. ADR-0007 cited the "Provider-agnostic issue tracker"
glossary entry, which the trim renamed to "Issue". ADR-0015 cited the "lint
plugin" entry, which the trim deleted outright — and ADR-0015 was amended for
its other CONTEXT.md pointer in the same commit, so this one was missed inside
an already-edited file.

Implementation notes: ADR-0007 gets a dated parenthetical matching the pattern
the other three carry, confirming the entry survived under a new name rather
than being dropped. ADR-0015's Considered-options parenthetical is re-pointed
at docs/spec/architecture.md's plugin scope table, which now carries the
repo-agnostic-versus-marketplace-specific argument the deleted entry held, and
its existing 2026-08-17 supersession note is extended to record that second
redirect in one place.

Impact: all four ADRs that referenced moved CONTEXT.md content now say where the
content went. No decision is altered.
 2026-08-17 10:10:24 +00:00
Defame1297
56cc173f65 fix: re-anchor doc citations that the CONTEXT.md trim broke 
Why: eight comments and one status note cited CONTEXT.md or AGENTS.md text that
b9c7762 and 1929ffd moved or deleted. All are inert at runtime, but they are the
rationale comments that tell the next maintainer why an assertion exists, and
they now name a file that no longer explains it.

Implementation notes: re-anchored by what the citation is for, not uniformly.
- Four sites quoted facts ADR-0013 owns — every rule is `level: error` with no
  ignorable tier (ADR-0013:59-70), and KyberforgeCopilot's `.agent.md`-only
  scope (ADR-0013:43-46). These now cite ADR-0013. ADRs are append-only here;
  the spec docs are refactored, which is what caused this rot.
- Two sites quoted the glob location-independence property, which no ADR owns.
  The quote was already inline and carried the full rationale, so the citation
  added a rot surface and no information — dropped, statement kept.
- sync-marketplace-mirror.sh's header attributed the mirror-not-a-profile fact
  to CONTEXT.md; the parenthetical beside it already carries the evidence, so
  the attribution is dropped rather than re-pointed.
- .pre-commit-config.yaml cited an AGENTS.md instruction that no longer exists;
  generalised to "the documented instruction".
- LESSONS.md:29 misquoted AGENTS.md's current session-start line.

Also corrects a pre-existing misattribution at tests/test-vale-wrap.sh:454:
AGENTS.md has never named bash 3.2 as a repo target (`git log -S'3.2'` on it is
empty). LESSONS.md and the script headers do.

Impact: no behaviour change. test-check-vale-style-sync.sh and test-vale-wrap.sh
both pass (42 passed, 0 failed).
 2026-08-17 10:09:51 +00:00
Defame1297
b93af30750 docs: fix a wrong pointer and two stale claims in CONTEXT.md 
Why: CONTEXT.md is an instructed every-session read, so a wrong assertion in it
is cited downstream without being checked. The b9c7762 rewrite introduced one
broken pointer and carried over two claims that were already false.

Implementation notes:
- The Preload tax entry pointed at docs/spec/gates.md for the measurement
  method. gates.md has no such method — it uses the 23,427-char figure once, in
  passing, without deriving it. The method and the current figure both live in
  ADR-0020, which is where a dated measurement belongs: it is superseded there
  deliberately, and issue #99 tracks its drift.
- Dropped the "~5,900 tokens across 39 skills" measurement rather than
  re-measuring it. It was already wrong three days after being written (~5,340
  today) and it was the only live number in the file. Every sibling entry is one
  definitional sentence plus a pointer fragment; this one now matches, and
  CONTEXT-FORMAT.md:43 asks for exactly that.
- Dropped "Written by the session-handoff skill or directly by the human" from
  the LESSONS.md entry. No session-handoff skill exists — LESSONS.md:7 records
  it as planned work. Who writes a file is not its definition.

Impact: removes the only rot surface in the file and the only assertion in it
that names an artifact the repo does not have.

Refs: #99
 2026-08-17 10:06:26 +00:00
Defame1297
b9c7762463 docs: trim CONTEXT.md to a glossary and demote VISION.md 
Why: CONTEXT.md is an instructed every-session read at 33,799 bytes (~8,450
tokens), and CONTEXT.md:17 layered docs/VISION.md on top. After the AGENTS.md
trim, that left ~9,650 tokens of instructed reads sitting behind a file whose
own format contract — grill-with-docs/CONTEXT-FORMAT.md:43, "Keep definitions
tight. One sentence max." — it was not following. 22 glossary entries averaged
190 words; the top four were 55% of the file, and one ("Vale audit prefilter")
was 1,444 words of pre-commit forensics filed as a definition.

Implementation notes:
- CONTEXT.md rewritten to CONTEXT-FORMAT.md's prescribed template: ## Language
  (five clusters, 22 terms with _Avoid_ aliases), ## Relationships,
  ## Example dialogue, ## Flagged ambiguities. 33,799 -> 9,762 bytes.
- Vale prefilter forensics moved to docs/spec/gates.md under nine subsections:
  the two-copy style layout, vale-wrap.sh and the Vale 3.15.2
  text.frontmatter.description limitation, the --config argv defect (E100),
  glob scoping, the rule inventory, and 0-files-means-NOT-RUN.
- Instruction-file format and the bidirectional-reference principle moved to
  docs/spec/architecture.md, the latter flagged as aspirational: no instruction
  file carries a `when:` field, only 2 of 39 skills do, and the reference
  scanner script it names does not exist.
- Added a per-plugin scope table to architecture.md so "which plugin owns this
  skill" survives the trim, and corrected its claim that the content index
  lives in providers/claude-code/CLAUDE.md — that file is now two import lines
  and the index sits in core/AGENTS.md.
- "Repo and Gitea are the only source of truth" moved from CONTEXT.md's
  Principles into AGENTS.md session rules; it was operative guidance in a
  glossary. docs/VISION.md and LESSONS.md added to the on-demand list.
- The apm-consumed install entry (432 words) was deleted outright: all four
  consequences are already carried by README.md, ADR-0018, gates.md and
  AGENTS.md.
- ADR-0013, ADR-0015 and ADR-0017 each pointed at CONTEXT.md sections that
  moved; amended with dated supersession notes rather than left dangling.

Impact: the every-session set drops from ~15,700 to ~4,140 tokens across both
passes (-74%). The deleted "lint plugin" entry was also stale on a safety
claim — it said lint-runner inherits Edit, but ADR-0016 restored
`disallowedTools: Edit, Write, NotebookEdit` and CONTEXT.md was never updated.

Refs: #99
 2026-08-17 09:28:01 +00:00
Defame1297
1929ffd2da docs: slim AGENTS.md to per-session context only 
Why: AGENTS.md is preloaded into every session via CLAUDE.md's @AGENTS.md
import, so every word is a tax paid whether or not it is relevant. It had
grown to 3,371 words (~4,550 tokens), 75% of it a single "Setup and testing"
section that was mostly neither: roughly 1,600 words were gate forensics —
why a hook is shaped the way it is, what was tried and rejected, verification
numbers — and only ~390 words were genuine one-time setup.

Implementation notes: split three ways by audience rather than by heading.
One-time setup, prerequisites and test commands move to a new root README.md,
which did not previously exist. The gate forensics move to a new
docs/spec/gates.md, preserving every constant, hook ID, error string and
tried-and-rejected note (policy.fetch_failure_default, the removed fallback
frontmatter reader, extending skill-size-check's files: pattern to agents,
tidying .claude/settings.json out of the pretty-format-json exclude list) —
these exist to stop settled decisions being re-litigated, so none were
dropped. AGENTS.md keeps only what applies every session, at one clause of
rationale per rule. The .apm/-mirror section collapses to a pointer because
docs/spec/architecture.md already covers it in full. The hot ADR-0020 gate
counts stay in AGENTS.md deliberately: they block any skill edit today.

Also corrects docs/spec/architecture.md's stale claim of 19 ADRs; ADR-0020
landed without updating the count.

Impact: per-session preload drops from ~4,550 to ~1,116 tokens, a 75% cut.
agentsmd-audit passes: secrets clean, drift clean, 4 informational findings
for sections deliberately relocated to the README.
 2026-08-17 08:56:37 +00:00
Defame1297
123ece2fb3 chore(apm): refresh lock after SessionStart auto-update 
Why: kyberforge's SessionStart hook found six packages behind the holocron
default branch and ran `apm update --yes`, which re-resolved every unpinned
dependency ref and rewrote the lock. The dependencies are declared unpinned
against the default branch, so this churn is expected rather than a defect.

Impact: pins the deployed skill and agent set to the refs resolved this
session. No manifest or plugin content changed.
 2026-08-17 08:56:22 +00:00
Defame1297
9385c77ac7 Merge pull request 'feat(kyberforge): ADR-0020 context contract for skills and agents' (#103) from refactor/trim-skills-agents-context into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/103
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-08-16 21:20:02 +00:00
Defame1297
54d7bd80ba docs: rule host built-ins out of the routing target universe 
Closes the second open design decision on PR #103. The `/compact` finding was
recorded as a false positive needing an allowlist or a suppression mechanism.
It is neither: the routing universe is the apm marketplace, so a target either
resolves to a skill or an agent or it does not resolve, and `/compact`,
`/clear` and `/init` are Claude Code slash commands with no counterpart in
Copilot CLI or Codex. `.apm/` source compiles for all three, so a
vendor-neutral description routing to one is a portability defect and the hard
FAIL is a true positive.

An allowlist was rejected for a concrete reason, not a stylistic one: it
answers a different question ("does this exist on some host?"), it cannot
answer that portably from a single source file, and it goes stale the next
time a host ships a command — reintroducing the same-commit-two-verdicts
failure ADR-0020 already closed for deployed trees.

Nothing is blocked today: zero of the 43 descriptions name a host built-in,
and an author who needs to mention one writes it un-slashed, which is not
route notation and carries no routing claim.

Recorded in ADR-0020 and in both author-facing contract references, so the
next agent reads the decision rather than "fixing" the gate.

ADR: 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-16 20:45:19 +00:00
Defame1297
75a13c82f6 fix(kyberforge): scope corroboration to a real sentence boundary 
A prose-form routing target blocks a commit only when its own sentence names
another target that resolves. That makes the sentence splitter part of the
ADR-0020 contract rather than an implementation detail, and the naive
"period, space, capital" rule got it wrong in both directions:

- OVER-SPLIT: `e.g. "..."` is not a sentence end, but the quote looks like a
  start. The clause was cut in half and the corroborator stranded on the far
  side, so a genuinely dangling target silently demoted to SUGGESTION — a
  measurement taken and then discarded, the vacuous-green shape this gate
  exists to prevent. Seven such splits are live in the current corpus.
- UNDER-SPLIT: a sentence opening with a code span or a lowercase skill name
  was not seen as a start, so two sentences merged and a resolving target
  vouched for an unresolvable one it never stood beside — a hard FAIL with no
  escape hatch, which is the exact failure corroboration was added to prevent.

The splitter now excludes the five abbreviations that occur in routing prose
and admits a backtick or lowercase letter as a sentence opener. Applied
byte-identically to all three copies of the shared resolver.

Verified zero-delta against the corpus: 37 ERROR / 58 SUGGESTION / 2 dangling
before and after, findings byte-identical. The exposure this closes is to the
descriptions #99 is about to rewrite, not to the ones already measured — which
is why the deferral reason recorded on PR #103 ("can move the documented corpus
counts") does not hold and the fix lands here rather than after the retrofit.

Three regression tests, one per direction plus the backtick opener, each proven
non-vacuous by reverting the splitter alone and watching it go red.

Refs: #99
ADR: 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-16 20:44:58 +00:00
Defame1297
79c9089122 docs: make the resolution contract match what the gate actually does 
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
 2026-08-16 19:49:50 +00:00
Defame1297
ede3f06689 fix(kyberforge): restore the authoring rules the ADR-0020 trim dropped 
Diffing each retrofitted SKILL.md against its replacement references/ files found
rules that existed on main and now existed nowhere — relocated in intent, deleted in
fact. A trim that loses a rule is not progressive disclosure, it is data loss with a
smaller word count.

Three had no survivor. The least-privilege guidance for `tools` kept its mechanics
and lost the "restrict to what the agent needs" half, so the remaining text read as
encouragement to omit the field. The improve flow lost its regression check, so
nothing compared the closing audit against the pre-edit state and a PASS quietly
becoming a SUGGESTION went unnoticed — restored on both halves of the author pair,
since agent-author had dropped its equivalent too. And agent bodies lost "would the
agent get this wrong without it?", which mattered more than it looks: ADR-0020
deliberately sets no body word gate for agents, three of the four already sit
between 933 and 1,199 words, and the delegation check only fires on procedure a
skill already owns. That heuristic was the only brake left.

Two more were reachable only from the wrong scope. agent-author tells the reader to
load only the file for the resolved scope, but the mcp__ glob syntax for
disallowedTools and the five tools no subagent ever receives had both landed in
project-user-scope.md. disallowedTools is the ONLY permitted fence at plugin/APM
scope, so the scope that needs the syntax most could not reach it, and a plugin-scope
run could write a body telling the agent to ask the user a question.

Two documents were actively wrong rather than merely thin. agent-audit told auditors
that validate.sh resolves boundary targets for skills only; it runs at both scopes,
so the auditor was hand-resolving what the script had already decided and could
contradict it. And skill-audit routed to its script-troubleshooting reference
whenever validate.sh "fails" — but it exits 1 on ordinary content FAILs, the normal
outcome for the whole #99 population, so 1,302 words loaded on nearly every audit.
A context-budget regression inside the skill that enforces the context budget.

Finally, two illustrations taught the shape the gate ERRORs on, unfenced, while an
adjacent rubric called it a hard ERROR.

LESSONS.md records the reference-chain depth rule flipping from "one level deep" to
"two hops, never three". ADR-0020 is silent on it and the reversal rode entirely on
the diff; the looser rule is what mandatory dispatch requires.

Refs: #99
ADR: 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
 2026-08-16 19:49:38 +00:00
Defame1297
b0d6d08239 test: pin the nine ADR-0020 gate defects that shipped untested 
Every defect fixed in f7cc279 was reachable because nothing asserted against it.
The gate had 43 assertions and none of them covered a consumer repo, a non-string
description, an unclosed fence, or the two spec ceilings. Each case below fails
against the pre-fix code and passes against the current one; every one was proved
non-vacuous by mutating a scratch copy of the script and watching the test go red,
independently twice.

The two that mattered most had no fixture anywhere. A consumer repo WITH .git is
the shape the resolver exists to serve, and only the no-.git case had ever been
tested, which is exactly why the blocker was invisible. And ADR-0020 says the
walk-up runs in two passes specifically so a nested .git cannot beat a plugins/
root further up — no fixture had ever placed a .git inside a plugin.

test-adr0020-differential.sh loses _non_adr_hook_error(). It excluded MAX_LINES and
MAX_WORDS from the cross-script comparison on the untested assumption that awk and
splitlines() agree. They do not, and the divergence stayed invisible for exactly as
long as the exclusion stood. The ceilings are now compared like any other rule.

Two existing assertions were repairs, not additions. The skill-improve probe had
been fixed by this very branch, so its iteration permanently took an
assertion-free SKIP that still counted as a pass; both branches now fail loudly and
each names the other file's pin so the two stay in step. And the yaml-none fixture
emitted `---/---`, which never matched the frontmatter pattern at all — it passed on
the bare word "frontmatter", present in both messages, while never reaching the
branch it was named for. Needles throughout that file now name their branch.

Refs: #99
ADR: 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
 2026-08-16 19:49:15 +00:00
Defame1297
f7cc27908c fix(kyberforge): close the vacuous-green and consumer-resolution defects 
Review of the ADR-0020 gate found four ways it could exit 0 without measuring, and
one way it hard-failed a repo it had no business failing. On a gate shipping hot
with no baseline, a silent pass is the worst outcome available and a false block is
the second worst.

Consumer resolution was the blocker. _authoring_root() fell back to the nearest
.git, so it returned truthy in ANY git repo; _collect_authoring_root() then
contributed nothing and the deployed-tree branch was dead code in precisely the
consumer case it exists for. A consumer repo routing to an installed sibling got an
unblockable ERROR, and deleting .git "fixed" it. It now keys on which of the two
walk-up passes matched. A name-count delta was tried first and is wrong: a
single-plugin monorepo re-collects its own package and adds no new name, so the
delta reads zero and drags the deployed trees — including a global ~/.claude — back
into the universe. That reintroduces the install-dependence ADR-0020 forbids, one
layer down.

The three silent passes: an indented `---` inside a block scalar truncated the
frontmatter and reclassified the rest of the description as body; a non-string
description was str()-coerced, so `description: true` measured as the four-character
"True"; and an unterminated fence blanked the rest of the body, disabling the
ERROR-tier references/ check and the gotcha counts.

Two measurement defects came with them. The awk line/word counts discarded awk's
exit status, so an unreadable file passed both spec ceilings in total silence, and
awk NR/NF disagreed with the audit script's splitlines()/split() on Unicode
whitespace — the "fix one gate, get blocked by the other" bug, on the two axes the
differential test deliberately excluded. Both counts now run in the Python block
that already reads the file. A type error also no longer reports itself as a syntax
error.

Also: glob metacharacters in the checkout path silently disabled the resolver;
re.I was applied to some extraction patterns and not others; agent-audit missed
`tools:` written as a YAML block sequence, the shape Copilot files use; and a
nonexistent agent file raised a bare FileNotFoundError instead of a diagnostic.

The shared resolver block stays byte-identical across all three scripts. Corpus
output is unchanged — 26 description FAIL, 9 body FAIL, 2 dangling, 0 missing
references, 58 SUGGESTIONs — so no documented count moves.

Refs: #99
ADR: 0020

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
 2026-08-16 19:48:56 +00:00
68 changed files with 3296 additions and 521 deletions
Expand all files Collapse all files

14
.claude-plugin/marketplace.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "holocron", "name": "holocron",
"description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
"version": "0.4.2", "version": "0.4.5",
"owner": { "owner": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",
@@ -17,22 +17,22 @@
}, },
{ {
"name": "bin", "name": "bin",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"version": "1.1.3", "version": "1.1.5",
"category": "Utilities", "category": "Utilities",
"source": "./plugins/bin" "source": "./plugins/bin"
}, },
{ {
"name": "git", "name": "git",
"description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.", "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"version": "1.3.3", "version": "1.3.5",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/git" "source": "./plugins/git"
}, },
{ {
"name": "gitea", "name": "gitea",
"description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.",
"version": "1.3.4", "version": "1.3.6",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/gitea" "source": "./plugins/gitea"
}, },

14
.github/plugin/marketplace.json vendored
View File

@@ -1,7 +1,7 @@
{ {
"name": "holocron", "name": "holocron",
"description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
"version": "0.4.2", "version": "0.4.5",
"owner": { "owner": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",
@@ -17,22 +17,22 @@
}, },
{ {
"name": "bin", "name": "bin",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"version": "1.1.3", "version": "1.1.5",
"category": "Utilities", "category": "Utilities",
"source": "./plugins/bin" "source": "./plugins/bin"
}, },
{ {
"name": "git", "name": "git",
"description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.", "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"version": "1.3.3", "version": "1.3.5",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/git" "source": "./plugins/git"
}, },
{ {
"name": "gitea", "name": "gitea",
"description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.",
"version": "1.3.4", "version": "1.3.6",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/gitea" "source": "./plugins/gitea"
}, },

2
.pre-commit-config.yaml
View File

@@ -207,7 +207,7 @@ repos:
# pre-commit prints nothing at all for a passing hook, so without this # pre-commit prints nothing at all for a passing hook, so without this
# the opt-out reinstated exactly the silent vacuous pass the script was # the opt-out reinstated exactly the silent vacuous pass the script was
# written to kill, one level up -- the run showed a bare `Passed` and # written to kill, one level up -- the run showed a bare `Passed` and
# AGENTS.md's instruction to read that summary line was impossible to # the documented instruction to read that summary line was impossible to
# follow in the one situation the opt-out exists for. The script's clean # follow in the one situation the opt-out exists for. The script's clean
# output is a single line, so this costs one line per push. # output is a single line, so this costs one line per push.

63
AGENTS.md
View File

@@ -1,29 +1,25 @@
# Working in this repo # Working in this repo
This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Built as a homelab tool intended to scale to professional environments. The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.
This file carries only what applies to **every** session. Setup, prerequisites, and test commands are in `README.md`; the reasoning behind each enforcement gate is in `docs/spec/gates.md`.
## Structure ## Structure
- `plugins/` — installable plugin units; each is an apm package (`apm.yml` + `.apm/`) carrying skills, agents, hooks, MCP servers, and bundled assets. This repo consumes them through **apm**, not Claude Code's native plugin install: root `apm.yml` declares all six as `dependencies.apm` git+path entries against the holocron remote, and `apm install` deploys them into `.claude/skills/` and `.claude/agents/` (both gitignored). External consumers can still install natively via `claude plugin install <name>@holocron` — the marketplace manifests are unchanged - `plugins/` — six installable plugin units, each an apm package (`apm.yml` + `.apm/`). Root `apm.yml` declares all six as `dependencies.apm`; `apm install` deploys them into `.claude/skills/` and `.claude/agents/`, both gitignored install output.
- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`) - `providers/claude-code/` — Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh`.
## Edit `.apm/`, never the flat mirror ## Edit `.apm/`, never the flat mirror
Inside a plugin, `plugins/<name>/.apm/` is the **only** hand-edited source for **plugin content** — the skills, agents, commands, instructions, extensions and hooks a host discovers. Everything in a plugin root that mirrors an `.apm/` primitive, plus both `plugin.json` manifests, is generated: `plugins/<name>/.apm/` is the only hand-edited source for plugin content. The flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories, the merged `plugins/<name>/hooks/hooks.json`, and both `plugin.json` manifests are generated — nothing marks them as generated, so check the path before you edit. An edit to the mirror is discarded by the next sync and reported as drift by the `check-plugin-content-sync` pre-push hook.
- `scripts/sync-plugin-content.sh` generates the flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories and the merged `plugins/<name>/hooks/hooks.json` (ADR-0017) Not everything in a plugin root is generated. `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json` and per-plugin extras are hand-authored there with no `.apm/` source — edit those in place. The rule is per-path, not per-directory. But a file placed *inside* a mirrored directory is deleted on the next sync (`sync_dir` runs `rm -rf` before every copy), so plugin-root documentation goes in `docs/`, never in `hooks/` or `skills/`.
- `apm pack` generates both per-plugin manifests — `plugins/<name>/.claude-plugin/plugin.json` and `plugins/<name>/.github/plugin/plugin.json` — and **two of the three** root marketplace manifests: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file) (ADR-0015)
- `scripts/sync-marketplace-mirror.sh` generates the third, `.github/plugin/marketplace.json` — Copilot CLI's legacy manifest path. **No apm output profile targets it**: apm ships exactly two marketplace output profiles, `claude` and `codex` (documented in `plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md`). The mirror is a byte-identical copy of `.claude-plugin/marketplace.json`, gated by the `check-marketplace-mirror-sync` pre-push hook. Do not expect `apm pack` to refresh it — that assumption is exactly the drift this pair exists to prevent
**A plugin root is not wholly generated.** Material that is not an `.apm/` primitive is hand-authored there and no compiler touches it: `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, plus per-plugin extras like `plugins/git/config.example.json`, `plugins/gitea/references/` and `plugins/bin/evals/`. Edit those in place — they have no `.apm/` source, and looking for one wastes a search. The rule is per-path, not per-directory: `plugins/<name>/skills/` is generated, `plugins/<name>/docs/` is not. `docs/spec/architecture.md` carries the same carve-out. Full model: `docs/spec/architecture.md`.
One qualification: "hand-authored, untouched" holds only at the plugin *root*. A file placed **inside** a mirrored directory is destroyed — `sync_dir` runs `rm -rf "$dst"` before every copy, so a `README.md` under `plugins/<name>/hooks/` or `plugins/<name>/skills/` is deleted on the next sync whether or not `.apm/` has a counterpart. Put root-level plugin documentation in `docs/`, never in a mirrored directory.
Nothing labels a generated file as generated — `plugins/kyberforge/skills/forge/SKILL.md` is byte-identical to its `.apm/` original, with no marker in either. Check the path before you edit. An edit to the mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook, which is the earliest anyone finds out. Details in `docs/spec/architecture.md`.
## Prefer plugin skills over raw shell ## Prefer plugin skills over raw shell
This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint tooling directly, check whether an installed skill already owns the operation — it usually does: This repo dogfoods its own plugins. Before shelling out, check whether a skill already owns the operation — it usually does:
- Commits, branches, history, worktrees, remotes → `git-commits`, `git-branches`, `git-history`, `git-worktrees`, `git-remotes` - Commits, branches, history, worktrees, remotes → `git-commits`, `git-branches`, `git-history`, `git-worktrees`, `git-remotes`
- Pre-commit hook install/config/troubleshooting → `pc-run` / `pc-author` - Pre-commit hook install/config/troubleshooting → `pc-run` / `pc-author`
@@ -31,40 +27,33 @@ This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint t
- Vale prose linting → `vale-config` / `vale-run` - Vale prose linting → `vale-config` / `vale-run`
- This repo's own AGENTS.md → `agentsmd-author` / `agentsmd-audit` - This repo's own AGENTS.md → `agentsmd-author` / `agentsmd-audit`
Use the bare, **unnamespaced** names above. Under the old `claude plugin install` these were `git:git-commits`, `kyberforge:skill-audit`, and so on; `apm install` deploys each skill to `.claude/skills/<name>/` as a plain project skill, which has no plugin prefix to carry. The `<plugin>:` form has not stopped resolving here, though — `~/.claude.json` still enables `core`, `git`, `gitea`, `kyberforge`, and `lint` at **user** scope, and ADR-0018 left those native installs in place on purpose, converting them being a separate decision with a blast radius beyond this repo. Every skill is therefore live under both names right now, and a working `gitea:gitea-prs` is the user-scope copy answering — not evidence that the apm install or this file is broken, and not something to "fix". Prefer the bare name anyway: apm deploys it, an external consumer installing holocron through apm gets it, and it is the form that survives those user-scope installs eventually being converted. The namespaced form also still resolves in any project that installs holocron natively, so a skill body written for both audiences should name the bare skill. Same for agents: `git-orchestrate`, not `git:git-orchestrate`. Use the bare, **unnamespaced** names. That is what `apm install` deploys and the only form this repo's own install produces — a project skill has no plugin to prefix (ADR-0018). Whether the `<plugin>:` form (`gitea:gitea-prs`) also resolves depends on native plugin installs at user scope, outside this repo; write the bare name either way.
Fall back to raw shell only when no skill covers it. Fall back to raw shell only when no skill covers it.
## Setup and testing ## Session rules
- Run `apm install` to deploy this repo's own skills and agents into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, not authoring source — `plugins/<name>/.apm/` remains the only place to edit. The six dependencies in root `apm.yml` resolve from the holocron **remote**, unpinned against the default branch, so a `.apm/` edit is not visible to the running session until it is pushed and `apm update` re-runs (`apm install` deploys from `apm.lock.yaml` and does not re-resolve refs). Needs the network, and needs `apm_modules/` (which it materializes) left gitignored. `apm install` also configures the `obsidian` MCP server into the repo's `.mcp.json`, carried over from `plugins/bin/.mcp.json`. - **Do not add repo-owned keys to `.claude/settings.json`.** apm treats it as its own deployed artifact and `apm audit --ci` replays the install and diffs, so anything apm would not have written is permanent drift that fails the `apm-audit-ci` pre-push hook. A hook you want here is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written into that file. The `SessionStart` entry already in it is exactly that: kyberforge authors it in `plugins/kyberforge/.apm/hooks/hooks.json` and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). Machine-specific settings go in the gitignored `.claude/settings.local.json`; shared enforcement goes in `.pre-commit-config.yaml`.
- Do not add repo-owned keys to `.claude/settings.json`. apm treats that file as its own deployed artifact: `apm audit --ci` replays the install into a scratch tree and diffs, so anything apm would not have written there — an `enabledPlugins` block, a real `hooks` entry — is permanent drift that fails the `apm-audit-ci` pre-push hook. Its committed content is whatever apm last wrote, which today is the merged `SessionStart` entry for kyberforge's `check-apm-current.sh` — apm's own output, and it belongs in the commit (ADR-0019). What does not change is that nothing repo-authored goes in the file. A hook you want in this repo is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written here. The file is also **excluded from `pretty-format-json`** in `.pre-commit-config.yaml` — the sixth and last alternation in that `exclude:` pattern, and the only one there for a reason other than "generated manifest". Mind which number you are quoting: six alternations, expanding to sixteen real files (3 root marketplace manifests, 2 per plugin × 6 plugins, plus this one). `pretty-format-json --autofix` sorts object keys while apm emits insertion order, so leaving the file in that hook's scope rewrites apm's output on the way into every commit and `apm audit --ci` then reports permanent drift on a file with an empty `git diff`. Do not tidy it out of that list; it is load-bearing (see `LESSONS.md`, 2026-08-14). Machine-specific settings go in the gitignored `.claude/settings.local.json`, which apm does not deploy and the replay does not compare; shared enforcement belongs in `.pre-commit-config.yaml`. - **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook runs `apm outdated` at startup and `apm update --yes` when something is behind, which rewrites the lock. Commit or discard it deliberately.
- Keeping the install current is automatic but not free. Because the six dependencies are unpinned, deployed skills go stale whenever anyone merges. kyberforge ships a `SessionStart` hook that runs `apm outdated` at startup (~0.7s) and, when something is behind, runs `apm update --yes` and asks the host to re-scan skills (~10.4s). That rewrites `apm.lock.yaml`, so an unexplained modification to it after opening a session is expected, not a bug — commit or discard it deliberately. Note `apm install` alone will **not** pick up remote changes; it deploys from the lock. `apm update` is the command that re-resolves refs. - **A `.apm/` edit is not live in this session until it is pushed.** The six dependencies resolve from the holocron remote, unpinned against the default branch. `apm install` deploys from the lock; `apm update` is what re-resolves refs.
- Install git hooks via `pc-run`, wiring all three stages — this repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (the 14-hook gate described below). - **The ADR-0020 skill gates ship hot, with no baseline.** 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the `Kyberforge.CompositionNote` Vale rule fires 10 errors across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Editing any of those skills *for any reason* means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. `skill-size-check` will not warn you about the Vale half, so check both: `pre-commit run --all-files`.
- Install the `apm` CLI — four pre-push hooks shell out to it: `apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wraps `apm pack`). `apm-marketplace-check` and `apm-pack-check-clean` are bare `apm …` hook entries and `apm-audit-ci` is a `bash -c` loop calling `apm` once per package, so without it the push dies with an unhelpful "command not found". Use `apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`. - **Run `bash tests/run-tests.sh --strict` before considering any change done.** Keep the flag: without it a suite whose dependency is missing exits 77 and is counted SKIPPED rather than failed, so the run goes green having verified less than it claims.
- Install `jq` — required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push. These at least fail loudly (`Error: jq is required but not installed`). - **Before pushing, rehearse the gate locally:** `pre-commit run --hook-stage pre-push --all-files`. It runs the 14 pre-push hooks this repo authors itself plus pre-commit's 2 `meta` hooks, so it prints 16; `check-release-needed` passes without checking anything, because it needs a real push to `main`. `docs/spec/gates.md` reconciles both.
- Install `python3` — required by `scripts/skill-size-check.sh`, the `skill-size-check` pre-commit hook. It measures the *folded* `description` value: most descriptions here are `>`-block scalars, so a regex over the raw lines measures indentation and newlines instead of the value. Missing it fails the hook with an install pointer rather than skipping the ADR-0020 checks, which would be a vacuous green. In practice it is already present — pre-commit is itself a Python application. **PyYAML is a hard requirement too**, not an optional accelerator: the hand-rolled fallback frontmatter reader has been removed, because a reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured, which is the exact vacuous-green failure the `python3` check exists to avoid. `pip install pyyaml` if the hook reports it missing. - **Pushing without a network** needs `SKIP=apm-marketplace-check,apm-pack-check-clean git push` — those two resolve a remote marketplace entry via `git ls-remote`. Skip only those two; the rest are real local checks, and adding one to `SKIP` disarms it silently.
- That hook enforces **two independent gate families** over `plugins/*/.apm/skills/*/SKILL.md`, and neither replaced the other. The agentskills.io spec backstop is unchanged: 500 lines and 2,770 words, counted over the **whole file including frontmatter**. ADR-0020 adds a context budget measured differently — `description` 250 chars SUGGESTION / 400 FAIL (it is preloaded into every session whether the skill fires or not), **body-only** word count 600 SUGGESTION / 900 FAIL (everything after the frontmatter's closing `---`), a missing, valueless or `null` `description:` (a hard FAIL, not a skip — a gate that declines to measure the one preloaded field reports green), every boundary-clause routing target resolving to a real skill or agent, and every `references/<file>.md` a body names actually existing. Target resolution walks up **from the file being checked** to an authoring root — the nearest ancestor holding `plugins/*/.apm/{skills,agents}`, falling back to the nearest `.git`, in two passes so a nested `.git` cannot beat a real monorepo root. The universe is then every skill and agent under `<root>/plugins/*/`, plus the checked file's own apm package and whatever that package declares in its own `apm.yml` `dependencies.apm`; the **root** manifest's `dependencies:` block is not read, and no plugin here declares a cross-plugin apm dependency. Deployed `.claude/`/`.agents/` trees are consulted only when no authoring root exists — the consumer case. That matters because those trees are gitignored `apm install` output: resolution used to reach the four cross-plugin `gitea-*` → `git-*` targets through `.claude/skills/` alone, so the same commit measured 2 dangling targets on a developer machine and 6 on a fresh clone. It no longer does — verified by running the hook over a tree holding only `plugins/` and the root `apm.yml`, which reports findings identical to the working tree (26 description / 9 body / 2 dangling / 0 missing references / 58 SUGGESTIONs). Three further checks are SUGGESTION-only: a description with no boundary clause at all, a `## Gotchas` section with more than five entries, and a `## Gotchas` section over 25% of the body. A file can sit well inside one family and fail the other. The hook is `verbose: true` so the SUGGESTION tier is audible — pre-commit prints nothing at all for a passing hook, and a SUGGESTION deliberately does not fail. `skill-audit`'s `validate.sh` holds a second copy of the four ADR-0020 constants; `tests/test-skill-size-check.sh` asserts the copies agree. - **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces.
- **Those ADR-0020 gates ship hot, with no baseline file.** 26 of 39 descriptions and 9 of 39 bodies currently exceed their FAIL tier, so editing one of those skills *for any reason* means retrofitting it to the contract first — a one-line fix to `gitea-prs` cannot be committed until that skill complies. This is deliberate, and the retrofit is tracked as Gitea issue #99. Check where a skill stands before starting: `pre-commit run skill-size-check --all-files`. - **This repo and Gitea are the only source of truth.** All project state, decisions, and working conventions live here. Do not use an external memory system for this project — cached state diverges from the repo and you get a split brain. Before answering any design or architecture question, check `docs/adr/` for an existing decision.
- **A second gate ships hot alongside it, and `skill-size-check` will not warn you about it.** `Kyberforge.CompositionNote` — the ADR-0020 Vale rule banning composition and architecture prose from a description — currently fires **10 errors across four skills**: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Every Vale rule here is `level: error` with no ignorable tier, so touching any of those four means fixing its prose findings as well as its size findings. Scoping a retrofit off `skill-size-check` output alone will leave you blocked at the second gate. Check both: `pre-commit run --all-files`.
- Install the `vale` binary — required by the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks. Their `files:` patterns are `.apm/`-scoped: `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` and `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$`. Only the authoring source triggers them — a `SKILL.md` in the generated mirror matches neither pattern, so prose findings surface only when you edit the file you are supposed to be editing. Without the binary the hooks fail with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (see ADR-0014).
- `vale` is also a **pre-push** dependency, not only pre-commit. `check-vale-style-sync` runs six glob-coverage probes by invoking `vale --config` — they are the only assertions in it that catch a `.vale.ini` glob typo, the failure mode where every text-level check stays clean while vale lints zero files. Missing `vale` is therefore a hard failure there. The opt-out is `CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1`, and it is **not** `SKIP=`: the hook still runs and still asserts everything verifiable from file text, but the six probes do not, and its summary says so explicitly — `Vale style sync check passed (text-level only, vale unavailable): … 0 glob probe(s) verified`. Use it only on a machine that genuinely cannot install `vale`, and read that summary line as "the glob axis was not checked", not as a pass.
- Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed.
- A suite that exits 77 because a dependency is missing is reported as SKIPPED, and does **not** fail an ad-hoc run. The pre-push hook invokes the same script as `--strict` (`RUN_TESTS_STRICT=1` is equivalent), where a skip **does** fail the push: at pre-push a skip means one of the dependencies above is absent on this machine, so the gate would otherwise report success having run fewer suites than it appears to. Without vale, for instance, three suites skip (`test-check-vale-style-sync.sh`, `test-vale-hooks-consumer.sh`, `test-vale-wrap.sh`) and the strict failure names each one and what to install.
- `tests/run-bats.sh` derives the set of `.bats` files it expects from `git ls-files`, so a `.bats` file deleted from the worktree but still tracked in the index fails the run rather than silently shrinking the suite. Remove one with `git rm` (or stage the deletion) when the removal is intentional; an untracked new `.bats` file is picked up and needs no ceremony. Both discovery walks (`tests/run-bats.sh` and `tests/run-tests.sh`) exclude `apm_modules/`: `apm install` materializes a full copy of every plugin there, and running a dependency's copy of a `.bats` file breaks its relative path to the bats helpers — 167 spurious failures before the exclusion landed.
- Pushing runs 14 repo-defined pre-push hooks, not just the test suite — `run-tests` and `check-manifests`, plus generated-content drift gates (`check-plugin-content-sync`, `check-marketplace-mirror-sync`, `check-vale-style-sync`, `check-scope-walkup-sync`, `check-executables-allow-sync`), artifact validators (`check-apm-agents-valid`, which runs agent-audit's `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md`), apm's own gates (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`), host validators (`validate-plugins`, `validate-marketplace`, both needing the `claude` CLI), and `check-release-needed`. `check-executables-allow-sync` is the odd one in that first group — it guards a silent failure rather than drift in generated text. apm gates a package's `hooks/` and `bin/` on an exact `<package>#<version>` lookup in root `apm.yml`'s `executables.allow`, with no wildcard and no version-less form, so bumping `plugins/kyberforge/apm.yml`'s `version:` without bumping the key errors nowhere: the entry simply stops matching, kyberforge's `SessionStart` hook stops deploying, and the install goes quietly stale — the failure ADR-0019 records as live. Run `pre-commit run --hook-stage pre-push --all-files` locally — one command, the whole gate. That command reports **16**, not 14: pre-commit's own `meta` hooks, `check-hooks-apply` and `check-useless-excludes`, declare no `stages:` and so run at every stage including this one.
- `apm-audit-ci` runs `apm audit --ci` once per manifest — the root one and each of the six plugin packages — because the root-only invocation audits the marketplace manifest and **nothing else**, and `apm-pack-check-clean` does not parse plugin `dependencies:` blocks either (verified: a malformed one passes `apm pack --check-versions --check-clean --dry-run` and fails `apm audit --ci` in that package's directory). It verifies two things and claims no more: each `apm.yml` parses as a valid APM manifest, and any package declaring dependencies has a consistent `apm.lock.yaml`. It does **not** enforce an org policy — apm discovers one from the git remote and only understands github.com and Azure DevOps, so against this repo's self-hosted Gitea remote it prints `No org policy found at unknown; enforcement skipped`. Do **not** "fix" that with `policy.fetch_failure_default: block` in `apm.yml`: it was tested and rejected, because with no reachable policy source it makes the hook exit 1 on every push forever.
- `check-apm-agents-valid` derives its expected agent-file set from `git ls-files` (same pattern as `tests/run-bats.sh`), so an agent file deleted from the worktree but still tracked fails the run, and discovering zero agent files is an error rather than a pass. An untracked new agent file is still validated — the derivation is one-directional on purpose, so uncommitted work is not blocked but also cannot bypass the gate. Agents take the ADR-0020 description gates (`agent-audit`'s `validate.sh` holds its own copy of those two constants) and, deliberately, **no** body word gate: an agent body becomes the system prompt of a fresh context rather than competing with the caller's live conversation, so the 900-word FAIL does not transfer. A bats test pins that absence in `agent-audit`'s validator — adding a body gate there contradicts the ADR rather than fixing an inconsistency. Be precise about the scope of that guarantee, though: it holds for the **validator**, not for the shared script. `scripts/skill-size-check.sh` applies its body gate to whatever path it is handed, and `bash scripts/skill-size-check.sh plugins/*/.apm/agents/*.agent.md` exits 1 today with 900-word body FAILs on `git-orchestrate` (933), `gitea-orchestrate` (1,199) and `apm-orchestrate` (1,080). Agent files escape only because the hook definitions filter on `SKILL.md` — a file-pattern accident that happens to implement the design, not the design itself. Do not "extend" that hook's `files:` pattern to cover agents on the assumption that the script already knows the difference.
- **Two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s `marketplace.packages[]` contains exactly one remote entry (`mattpocock-skills`, `source: mattpocock/skills`), and resolving it needs a `git ls-remote`. `apm-marketplace-check` resolves every entry and is `always_run`, so it fails with `No cached refs (offline)`. `apm-pack-check-clean` (`apm pack --check-versions --check-clean --dry-run`) re-resolves the same entry and fails with `Error: Git network timeout during ls-remote`. Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes. `--offline` rescues neither. To push without a network, skip both using pre-commit's own mechanism: `SKIP=apm-marketplace-check,apm-pack-check-clean git push`. Skip those two alone — verified under `unshare -rn`, the other twelve pre-push hooks pass offline because they are real local checks (`check-executables-allow-sync` landed after that run, but reads two local manifests and makes no network call), and adding one of them to `SKIP` disarms it silently. `apm-audit-ci` calls `apm` too but stays local: its org-policy discovery resolves nothing on this remote before any network call, so it does not join the pair above.
- Author commits with `git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you.
## Key documents ## Key documents
Read CONTEXT.md at the start of every session in this repo. Read `CONTEXT.md` at the start of every session — it is this repo's domain glossary, and the terms it defines are used unglossed everywhere else. It is not exhaustive: terms it does not carry are defined at their point of use, mostly in `docs/spec/`.
Read these on demand: Read these on demand:
- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model - `README.md` — prerequisites, install, and test commands
- `docs/VISION.md` — the phased roadmap and where this is going; read when a decision turns on product direction
- `LESSONS.md` — patterns that went wrong once; read before repeating a class of change that has burned the repo before
- `docs/spec/gates.md` — what each pre-commit and pre-push hook enforces and why; read when a gate fails or before changing hook config
- `docs/spec/architecture.md` — directory structure, install pipeline, provider model
- `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes - `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes
- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification - `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification
- `docs/research/ai-coding-factory/ai-coding-factory-principles.md` — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure - `docs/research/ai-coding-factory/ai-coding-factory-principles.md` — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure

256
CONTEXT.md
View File

@@ -1,106 +1,226 @@
--- ---
name: AI Development Repo name: AI Development Repo
description: Domain language and decisions for the global AI development config repository description: The domain language of the global AI development config repository
--- ---
# Context # AI Development Repo
## Principles The bounded context of this repo is **how agent instructions are authored, packaged, distributed, and
kept small**. Terms here name concepts specific to that problem. Mechanics live elsewhere:
`docs/spec/architecture.md` for structure, `docs/spec/gates.md` for enforcement, `docs/adr/` for
decisions.
### CLAUDE.md index model ## Language
`AGENTS.md` is the source of always-on universal rules (provider-agnostic). `providers/claude-code/CLAUDE.md` is a thin adapter: it imports `~/.agents/AGENTS.md` via `@~/.agents/AGENTS.md` and appends Claude Code-specific additions (`@import` for governance.md, content index). Deployed to `~/.claude/CLAUDE.md` via `install.sh`. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0003.
### Instruction file format ### Context cost
`core/instructions/<topic>.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.
### Repo/gitea as source of truth **Preload tax**:
All project state, decisions, context, and working conventions live in this repo or Gitea. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, and `docs/VISION.md`. Everything needed to orient is here. The always-on context cost of every installed skill's `name` and `description`, charged from the
first token of every session whether the skill is invoked or not. Measurement method and current
figure: ADR-0020.
_Avoid_: context cost, token overhead
Before answering any design or architecture question, check for existing decisions: `docs/adr/` (hard architectural decisions). **Skill context contract**:
The ADR-0020 authoring rules that hold the preload tax and body size down — a description carries a
trigger clause, at most one capability clause, and a boundary clause, and nothing else. Thresholds
and the target-resolution walk: `docs/spec/gates.md`.
_Avoid_: skill budget, size limit
## Glossary **Dispatch body**:
The body pattern a skill with two or more mutually exclusive flows must use — the body carries only
the dispatch table and the gates common to every branch, and each flow lives in its own
self-contained `references/` file. Exemplar: `apm-workflow`.
_Avoid_: router body, thin body
### Management Application **Hand-invoked skill**:
A separate product (separate repo) for browsing, editing, and configuring AI development configs through a proper product UI. Git is the persistence layer, invisible to the user. The app is repo-agnostic — it works with any git repo that follows these conventions. This repo is the canonical default content (the official starter). See `docs/VISION.md` for the phased roadmap. A skill reached only by typing its slash command, declared `disable-model-invocation: true`. The host
withholds it from the model-visible listing entirely, so it pays no preload tax and its description
becomes human-facing text. Exemplar: `zoom-out`.
_Avoid_: manual skill, disabled skill
### Skills **Delegation discipline**:
Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Authored at `plugins/<plugin-name>/.apm/skills/<skill-name>/SKILL.md` and reaching a host by one of two install paths: `apm install`, which deploys the skill directory to `.claude/skills/<skill-name>/` (this repo's own path — see "apm-consumed install"), or `claude plugin install <name>@<marketplace>`, which caches the whole plugin (still supported for external consumers). Skills are self-contained — they cannot reference files outside the plugin directory after install-time caching. The two paths name skills differently: apm deploys a plain project skill (`skill-audit`), a plugin install namespaces it (`kyberforge:skill-audit`). The agent-side counterpart to the dispatch body. A plugin-scope agent is a single `.agent.md` file
with no sibling `references/` directory, so it cannot disclose to itself — it can only delegate to
skills. Its characteristic defect is therefore restatement, not length.
_Avoid_: agent hygiene
### Preload tax ### Distribution
The always-on context cost of every installed skill's `name` + `description`, which sit in the agent's context from the first token of every session whether or not the skill is invoked. Measured 2026-08-14 against base commit `f9b919d` at 23,427 chars (~5,900 tokens) across 39 skills, plus 1,325 chars for 4 agents. Method, so it can be re-run: sum `len(name) + len(description)` over each `plugins/*/.apm/skills/*/SKILL.md` frontmatter with `>` block scalars folded to the value the host loads, at ~4 characters per token. Non-routing frontmatter (`metadata.source_keys`, `category`, `version`) is **not** part of it — the model-visible skill listing carries only `name` and `description`, which supersedes `LESSONS.md:63` on this host. Bodies are not part of it either; they are charged on invocation.
### Skill context contract **Skill**:
The authoring rules that hold the preload tax and body size down, set by ADR-0020. A description carries a trigger clause, at most one capability clause, and a boundary clause of the form `Not <thing> → <skill-name>` naming a resolvable target — nothing else. "Resolvable" is decided by walking up *from the file being checked* to an **authoring root** — the nearest ancestor holding `plugins/*/.apm/{skills,agents}`, falling back to the nearest `.git`, in two passes so a nested `.git` cannot outrank a real monorepo root. The universe is then every skill and agent under `<root>/plugins/*/` (sibling plugins resolve against each other, which is what a monorepo means), plus the checked file's own apm package and that package's own declared `dependencies.apm`. The **root** manifest's dependency list is never consulted, and no plugin here declares a cross-plugin apm dependency. Deployed `.claude/`/`.agents/` trees count only when there is no authoring root at all — the consumer case. The property this buys is that one commit gets one verdict: those trees are gitignored `apm install` output, so resolving through them made the same commit report 2 dangling targets on a developer machine and 6 on a fresh clone, which a gate shipping hot with no baseline cannot do. A `${BASH_SOURCE}`-relative repo root is the other half of the same defect and is gone — it leaked this repo's 39-skill universe into consumer repos running the hook through pre-commit. A *missing* boundary clause is a SUGGESTION rather than a failure, for skills and agents alike — some skills genuinely have no near-miss sibling. A *missing or empty description* is the opposite: a hard FAIL in all three validators, because a gate that merely declines to measure the one preloaded field reports green. Capability enumeration, output formats, and composition notes ("composes X rather than duplicating Y") belong in the body or `README.md`; a description that summarises workflow is a correctness hazard, not just a cost, because agents act on it instead of reading the body. Sizes are two-tier and sit *below* the agentskills.io spec limits, which stay unchanged as conformance backstops: description 250 SUGGESTION / 400 FAIL (spec 1,024); body 600 SUGGESTION / 900 FAIL (spec 2,770 words / 500 lines). Conflating the quality gate with the spec ceiling is what let `skill-author` and `agent-author` grow to within twelve words of 2,770. A reusable slash command defined as a `SKILL.md` file following the
[Agent Skills open standard](https://agentskills.io), authored at
`plugins/<plugin>/.apm/skills/<skill>/SKILL.md`.
_Avoid_: command, prompt, macro
### Dispatch body **Plugin**:
The body pattern a skill with two or more mutually exclusive flows must use: the body carries only the dispatch table and the gates common to every branch, and each flow lives in its own self-contained `references/` file. Named for `apm-workflow` (421-word body, 3,006 words of references), which arrived at it independently and is the repo's exemplar. Its absence was the characteristic defect at the time ADR-0020 was written: `skill-author` inlined both its create and improve flows, and `agent-author` carried 50-60 lines marked inapplicable by their own headers on any single run. Both were retrofitted to dispatch tables in the change that carries the ADR — `skill-author` went 2,623 body words to 595 and `agent-author` 2,582 to 616 — so they are now worked examples of the pattern rather than counter-examples of it. The 39-skill corpus at large is not: 9 bodies still exceed the 900-word FAIL (issue #99). The deployable unit — one or more skills, agents, hooks, commands, and MCP servers bundled into a
single installable directory under `plugins/<name>/`, compiled from that plugin's `.apm/` source.
_Avoid_: package, bundle, module
### Hand-invoked skill **apm package**:
A skill reached only by typing its slash command, declared with `disable-model-invocation: true`. The host withholds it from the model-visible skill listing entirely, so it pays no preload tax and its `description` becomes human-facing text rather than a trigger list. `zoom-out` is the worked example: apm passes the flag through verbatim to both install paths, and the skill is absent from the router while `/zoom-out` still works. Choosing model-invoked vs. hand-invoked is the first question `skill-author` asks, because it determines whether a description needs triggers at all. The unit apm builds and installs — `plugins/<name>/apm.yml` plus the hand-authored
`plugins/<name>/.apm/` tree it compiles from (ADR-0015).
_Avoid_: plugin directory, source tree
### Delegation discipline **Content mirror**:
The agent-side counterpart to the dispatch body. A plugin-scope agent is a single `.apm/agents/<name>.agent.md` file with no sibling `references/` directory, so it cannot disclose to itself — it can only delegate to skills. Its characteristic defect is therefore restatement, not length: an agent body that spells out a procedure a skill it can invoke already owns creates a second copy that drifts. `agent-audit` fails that, with the fix being "invoke `<skill>` instead". Agents take the same description gates as skills but no body word gate — a skill body competes with the caller's live conversation, an agent body becomes the system prompt of a fresh context. The generated flat `skills/`, `agents/`, `commands/`, `instructions/`, `extensions/` directories and
merged `hooks/hooks.json` at a plugin root — also called the flat mirror — compiled from that
plugin's `.apm/` tree so hosts that convention-scan those paths discover the content (ADR-0017).
_Avoid_: generated copy, duplicate tree
### Plugin **Output profile**:
The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a `bin/` directory into a single installable directory. In this repo, plugins live under `plugins/<name>/`, each with its own `apm.yml` + `.apm/{skills,agents,hooks,...}` — this is the authoring source of truth for the plugin's content (ADR-0015). Two categories of tracked output are compiled from that source, never hand-edited: `.claude-plugin/plugin.json` (Claude Code) and `.github/plugin/plugin.json` (Copilot CLI) via `apm pack`/`apm compile`; and, alongside them, a flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/` directory mirror at the plugin root plus a merged hooks file at `hooks/hooks.json`, generated by `scripts/sync-plugin-content.sh` — Claude Code's and Copilot's installers convention-scan only these flat paths (`hooks/hooks.json` is the convention path for hooks specifically; a root-level `hooks.json` is scanned by nothing and is deleted as stale by a sync — see ADR-0017's 2026-08-14 amendment) and have no awareness of `.apm/` nesting at all, so this mirror is what actually makes `.apm/` content discoverable at install time (ADR-0017). Plugins are copied to a cache on install — they cannot reference files outside their own directory. Install a plugin with `claude plugin install <name>@<marketplace>`, or consume it as an apm dependency (see "apm-consumed install"). An `apm pack` target format for a generated *marketplace* manifest; apm has `claude`
(`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped
`.agents/plugins/marketplace.json`), and none for `.github/plugin/marketplace.json` (Copilot CLI's
legacy path), which a sync script mirrors instead. Mechanics: `docs/spec/architecture.md`.
_Avoid_: build target, export format
### Plugin marketplace **Plugin marketplace**:
A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) is **compiled output** of `apm pack`, generated from the root `apm.yml`'s `marketplace:` block (owner, build/output config, versioning strategy, and the `packages:` list of installable plugins) — it is not hand-edited. See ADR-0015. `.github/plugin/marketplace.json` is Copilot CLI's legacy manifest path; apm has no output profile for it (only `claude` and `codex`, and `codex`'s is a differently-shaped file at `.agents/plugins/marketplace.json`), so `scripts/sync-marketplace-mirror.sh` keeps it byte-identical to `.claude-plugin/marketplace.json`, checked at pre-push. Each listed package's `source:` still points at that plugin's own `plugins/<name>/` root, not at an `apm pack` build artifact — which is why that root also carries the flat `agents/`/`skills/`/`commands/`/`hooks/hooks.json` content mirror described under "Plugin" (ADR-0017): without it, an install from this marketplace finds a valid manifest but no discoverable content. A Git repository carrying a `marketplace.json` manifest that lists installable plugins. There is no
backend, registry, or SaaS — the Git repo is the marketplace.
_Avoid_: registry, store, catalogue
### apm-consumed install **holocron**:
How this repo installs its own plugins, as of 2026-08-14: not `claude plugin install <name>@holocron`, but six `dependencies.apm` entries in the root `apm.yml`, each a `git:`/`path:` object against the holocron remote, deployed by `apm install` into `.claude/skills/` and `.claude/agents/`. Project scope only — apm installs nothing at user scope, so the switch is contained to this repo and any other repo opts in by declaring its own dependencies. The git+path object form is deliberate over the shorter `<name>@holocron` marketplace alias: an alias must first be registered with `apm marketplace add`, which writes to `~/.apm/marketplaces.json` (user scope, outside the repo), whereas the object form needs nothing beyond the committed manifest and so survives a fresh clone. This repository, in its role as a plugin marketplace and as the remote the six plugin dependencies
resolve against.
_Avoid_: the marketplace, upstream
Four consequences, each load-bearing: **apm-consumed install**:
- **Skills gain an unnamespaced name.** apm deploys plain project skills, so `git:git-commits` also answers to `git-commits`. The `<plugin>:` form has not stopped resolving here: `~/.claude.json` still enables `core`, `git`, `gitea`, `kyberforge`, and `lint` at user scope, which ADR-0018 left in place deliberately — converting them is a separate decision with a blast radius beyond this repo. Until it is taken, every skill is live under two names, which is the same "present twice under two names" outcome ADR-0018's own "Alternatives considered" rejected for *keeping both install paths* — reached here by leaving user scope alone rather than by adopting it as the install model. Write the bare name regardless: apm deploys it, and a repo consuming holocron through apm gets only that form. The namespaced form still resolves wherever holocron is installed natively, so cross-audience skill bodies should use the bare name. How this repo installs its own plugins as of 2026-08-14 — six `dependencies.apm` entries in the root
- **apm owns `.claude/settings.json`.** `apm audit --ci` (an `apm-audit-ci` pre-push hook) replays the install into a scratch tree and diffs it against the worktree, so any key apm would not have written is permanent drift. Committed content is exactly `{"hooks": {}}`; repo-owned settings have nowhere to live in that file. `apm.yml` deployed by `apm install`, rather than `claude plugin install <name>@holocron`. Its
- **Install output is gitignored.** `.claude/skills/`, `.claude/agents/`, and `apm_modules/` are all regenerated by `apm install`. `apm.lock.yaml` and the generated `.mcp.json` are committed. Committing the deployed skills would add a third mirror of the same content to the two ADR-0017 already governs. consequences: ADR-0018.
- **Test discovery must skip `apm_modules/`.** It holds a full copy of every plugin, `.bats` files included; both `tests/run-bats.sh` and `tests/run-tests.sh` exclude it. _Avoid_: apm install, dependency install
Dependencies are unpinned against the default branch, matching the `autoUpdate: true` the native marketplace install had. The practical cost is a round trip: an edit to `plugins/<name>/.apm/` is invisible locally until it is pushed and `apm install` re-runs, because the dependency resolves from the remote rather than from the working tree beside it. **Provenance chain**:
The three-stage traceability record linking a skill back to its research inputs: `/research` produces
topic docs and a `sources.md`; the author skill records which sources informed which files in
`references/sources.md` and `source_keys` frontmatter; `skill-audit` validates the chain is complete
and internally consistent.
_Avoid_: sources, citations, attribution
### HITL (human-in-the-loop) ### Governance
Agent pauses before a consequential action; human approves before execution. Required for irreversible or high-stakes actions (architecture changes, production deployments, security configuration). The agent drafts the change plan and waits — it does not proceed autonomously. Contrast with HOTL.
### HOTL (human-on-the-loop) **HITL** (human-in-the-loop):
Agent acts; human monitors and can intervene after the fact. Acceptable for low-stakes, bounded, reversible actions where the cost of pausing for approval exceeds the blast radius of an error. The distinction between HITL and HOTL must be explicit and documented — defaulting to HOTL for convenience is not acceptable. The agent pauses before a consequential action and a human approves before execution. Required for
irreversible or high-stakes actions — architecture changes, production deployments, security
configuration.
_Avoid_: manual approval, gated action
### Sycophancy **HOTL** (human-on-the-loop):
The failure mode where RLHF-trained models prioritise approval over accuracy. Treated as a first-class reliability risk: models change correct answers to wrong ones under user pressure in a majority of observed cases, then persist in the wrong answer. Designing against sycophancy is an explicit obligation, not a quality-of-life concern. Countermeasures: explicit pushback resistance instructions, prompting for dissent, cross-validating against independent sources. Never interpret AI agreement as AI accuracy. The agent acts and a human monitors, able to intervene after the fact. Acceptable only for
low-stakes, bounded, reversible actions where the cost of pausing exceeds the blast radius of an
error.
_Avoid_: autonomous, unsupervised
### AGENTS.md **Sycophancy**:
The provider-agnostic always-on instruction entry point. Two files: The failure mode where an RLHF-trained model prioritises approval over accuracy — changing a correct
- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules); imported by repo `CLAUDE.md` via `@AGENTS.md`. answer to a wrong one under user pressure, then persisting in the wrong answer. Treated here as a
- **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects; deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`. first-class reliability risk, not a quality-of-life concern.
_Avoid_: agreeableness, people-pleasing
Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0003. ### Documents
### Skill composition **AGENTS.md**:
A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `apm-workflow`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` had no audit counterpart and got no recheck; their terminal check was `claude plugin validate`. Both were deprecated per ADR-0015, superseded by `apm-workflow`, and deleted entirely once issue #90 landed. The provider-agnostic always-on instruction file, in plain markdown with no provider-specific syntax
(ADR-0003). Two exist: repo-level, and the global `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`.
_Avoid_: instructions file, system prompt
### Provider-agnostic issue tracker **Thin adapter**:
Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0007). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it). A provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`)
that imports its `AGENTS.md` and adds only that provider's syntax, carrying no original always-on
content of its own (ADR-0002, ADR-0003).
_Avoid_: wrapper, shim, provider file
### Provenance chain **LESSONS.md**:
The three-stage traceability record linking a skill back to its research inputs: (1) `/research` produces topic docs and a `sources.md` in `plugins/<plugin>/docs/research/docs/<topic>/`; (2) `/skill-author` reads those docs and records which sources informed which skill files in `references/sources.md` (including a `Research doc:` back-pointer to the upstream research file) and `source_keys` frontmatter on `SKILL.md` and `references/*.md`; (3) `skill-audit` validates the chain is complete and internally consistent via `validate-provenance.sh`. A skill with research input but no `references/sources.md`, or with `source_keys` that don't match `references/sources.md` slugs, has a broken provenance chain. The long-loop feedback log for patterns observed across sessions, at the repo root.
_Avoid_: changelog, retro, postmortem
### Bidirectional reference principle **Management Application**:
Files that reference other files should declare those references explicitly. The referencing file carries the forward reference (e.g. content index in `CLAUDE.md`, `references:` in frontmatter). The referenced file carries a `when:` field describing when it is loaded. Both sides should agree — divergence signals staleness. The reverse map ("what files reference this file?") is derived by a reference scanner script, not maintained manually. This principle applies to instruction files, skills, and workflow documents. A separate product in a separate repo for browsing, editing, and configuring AI development configs
through a product UI, with Git as an invisible persistence layer. Repo-agnostic; this repo is its
canonical default content. Roadmap: `docs/VISION.md`.
_Avoid_: the UI, the dashboard, the app
### agentsmd-author / agentsmd-audit ### Quality
A skill pair in the `core` plugin for writing, updating, and reviewing a repo's `AGENTS.md` file(s) — the generic open-standard file (see the `AGENTS.md` entry above), including this repo's own. `agentsmd-author` creates/updates AGENTS.md content, supports nested monorepo placement (per the standard's nearest-file-wins precedence), and closes out by invoking `agentsmd-audit` inline. `agentsmd-audit` runs a single combined pass checking three mandatory baselines: secrets/credentials (governance.md hard prohibition — AGENTS.md is committed content), structural completeness (common-sections checklist from the agents.md spec), and accuracy/drift (do referenced commands and paths actually resolve against the repo). `agentsmd-audit` never inspects provider adapter files (see `provider-adapter-author`) — its scope is AGENTS.md content only. Chosen over folding this into `kyberforge` because kyberforge's scope is meta-tooling for the holocron marketplace itself, not generic target-repo documentation; `core` is the intended home for cross-cutting, repo-agnostic utility skills.
### provider-adapter-author **Skill composition**:
A companion skill (`core` plugin) that detects a target repo's provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." `agentsmd-author` calls this skill via skill composition when it detects an existing provider file with overlapping content. A skill calling another skill by name to delegate a sub-task — the caller owns the orchestration
decision ("when to do X"), the callee owns the mechanics ("how to do X").
_Avoid_: chaining, nesting, sub-skill
### lint plugin **Vale audit prefilter**:
A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only **by instruction, not by capability** — its body states "You never edit files" and "Do not edit, fix, or rewrite any flagged content", but nothing enforces that. It previously carried `tools: Bash, Read, Grep, Glob`, which withheld `Edit` outright; plugin-scope APM agents cannot express a `tools:` field at all (ADR-0016 — `apm compile` copies frontmatter verbatim to both Claude Code and Copilot, whose `tools:` vocabularies are incompatible, so a value correct for one harness is wrong for the other), so `plugins/lint/.apm/agents/lint-runner.agent.md` now declares only `name`/`description`/`source_keys` and inherits every tool, `Edit` included. ADR-0016 accepted this loss of enforcement knowingly; the restriction survives as prose the agent is expected to follow. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin. The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Description dimension,
so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`.
_Avoid_: linting, style check
### Vale audit prefilter (skill-audit / agent-audit) **Authoring root**:
Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/.apm/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/.apm/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment. The directory a gate resolves against — the nearest ancestor of the file being checked holding
`plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding
`.git`. The walk: `docs/spec/gates.md`.
_Avoid_: repo root, project root
Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions. Verified by reproduction, not assumed: `>` folded scalars, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars all yield 0 alerts and exit 0 on a deliberately-bad fixture, while a `|` literal block spanning the same 2+ lines lints normally (alerts fire, exit 1). The wrapper flattens those three broken forms to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; `|` literal blocks and single-line descriptions pass through untouched, already linting correctly. The plain and quoted forms previously passed silently — unflattened and unmatched — so a bad description in either sailed through the prefilter. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root. Both audit skills' Step 1 now passes no `--config` either: it resolves the script relative to the skill's own directory so the call works from an installed plugin cache, but a relative `--config` alongside it would still resolve against the cwd, yielding `E100 Runtime error ... does not exist` and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to full LLM judgment. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment. **Near-miss**:
A query that shares keywords with this skill but needs a different one — and, by extension, the
sibling that would wrongly answer it; boundary clauses exist to exclude genuine near-misses rather
than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`.
_Avoid_: overlap, similar skill
This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the skill/agent corpus as it stood at the time of that measurement (2026-08-08, before the `.apm/` restructure), one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. A third, `Kyberforge.CompositionNote`, landed with ADR-0020 and bans architecture and composition prose from a description; it is `level: error` like the rest, and it currently fires 10 times across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`, so `pre-commit run --all-files` is red on prose as well as on size until issue #99 lands. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), which carries **two independent gate families that must not be conflated** (see "Skill context contract"). The agentskills.io spec backstop is `MAX_LINES=500` and `MAX_WORDS=2770`, both inclusive and both counting the **whole file including frontmatter** (2,770 is a word-count proxy for the 5,000-token limit, calibrated to the densest prose measured in this repo — 1.81 tokens per word — so even a worst-case `SKILL.md` at the ceiling stays under 5,000 tokens; it is not a percentile of the corpus). ADR-0020 adds a context budget measured differently: description characters 250 SUGGESTION / 400 FAIL, **body-only** words 600 SUGGESTION / 900 FAIL, plus deterministic checks that every boundary routing target resolves, that a body's named `references/<file>.md` all exist, and — SUGGESTION-tier — that a boundary clause is present at all, that `## Gotchas` holds at most five entries, and that it stays under 25% of the body. `skill-audit/scripts/validate.sh` and `agent-audit/scripts/validate.sh` hold their own copies of the shared constants and `tests/test-skill-size-check.sh` asserts the copies agree, so a `SKILL.md` can no longer pass its own audit yet be blocked by the commit hook. Agents take the description gates and no body word gate. `python3` **and PyYAML** are hard requirements — the earlier hand-rolled frontmatter fallback is gone, because a fallback that silently mis-parses a scalar shape reports a vacuous pass. Scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible. **Vacuous green**:
A check that reports success because it measured nothing — zero files scanned, an unparsed value read
as empty, a conditional branch that never armed.
_Avoid_: false pass, clean run
### LESSONS.md **Issue**:
Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root. The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker
(ADR-0007), but skills say "linked issue" generically rather than naming a provider.
_Avoid_: ticket, card, task
## Relationships
- A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**;
**holocron** is this repo wearing that hat.
- Every model-invocable **Skill** pays the **Preload tax**. A **Hand-invoked skill** does not — which
is the first question to settle when authoring one.
- The **Skill context contract** bounds both the **Preload tax** (description) and the body.
A **Dispatch body** is how a skill stays inside it; **Delegation discipline** is how an agent does.
- **AGENTS.md** is the source of always-on rules; a **Thin adapter** imports it and originates
nothing.
- **Skill composition** is the caller/callee split. `forge` routes a genuinely *undecided* artifact
type to the matching author skill — an already-specified fix (file, line, and change known) calls
that author skill directly, because each routing hop re-derives instructions from a shorter brief
and has been observed to drop hard constraints handed down the chain.
- **HITL** and **HOTL** are exclusive per action class, and the choice must be explicit and
documented. **Sycophancy** is why HOTL is not the safe default.
- A **Skill** built on research carries a **Provenance chain**; `skill-audit` fails it when broken.
- **LESSONS.md** feeds the standing files: three or more entries on one pattern graduate the pattern
into the relevant standing document.
## Example dialogue
> **Dev:** "This one only fires when someone types the slash command. Does its description still need
> trigger words?"
> **Maintainer:** "No — that's a **hand-invoked skill**. The host withholds it from the model-visible
> listing, so it pays no **preload tax** at all and the description is human-facing text."
> **Dev:** "Then the body can be as long as it needs to be?"
> **Maintainer:** "Different budget. The **skill context contract** gates the body whether or not the
> skill is model-invoked — the description competes with every other skill's description, the body
> competes with the caller's live conversation. Four mutually exclusive flows means a **dispatch
> body**: table in `SKILL.md`, one `references/` file per flow."
> **Dev:** "And if I split it into an agent instead?"
> **Maintainer:** "Then you're in **delegation discipline** territory. An agent has no `references/`
> to disclose to, so the failure mode flips — it stops being length and starts being restatement of
> a procedure some skill already owns."
## Flagged ambiguities
- "skill" was used for both the authored `SKILL.md` under `plugins/<name>/.apm/skills/` and the
deployed copy under `.claude/skills/` — resolved: the authoring source is the **Skill**; the
deployed copy is gitignored `apm install` output and is never edited.
- Skills can answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), depending on
whether a native install exists at user scope alongside the apm one (ADR-0018) — resolved: write
the bare name, which is the only form `apm install` produces.
- "context" means both the model's live token window (the **Preload tax** sense) and the bounded
domain this file describes — resolved: unqualified "context" in this repo means the token window.
- "audit" was used for both an author skill's inline closeout and `forge`'s independent
clean-context recheck — resolved: these are two distinct layers, kept separate precisely because
an audit running in the same context as the work it checks shares that work's blind spots.

22
LESSONS.md
View File

@@ -1,8 +1,8 @@
# Lessons # Lessons
Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule. Patterns observed during development of this repo. Three or more entries on the same pattern → promote to `docs/spec/architecture.md` (or the relevant instruction file) as a standing rule.
**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail). **Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `docs/spec/architecture.md` for structural and domain-level principles — `CONTEXT.md` is not a destination, its `## Principles` section was deleted and what was there now sits under that file's "AGENTS.md pattern" and "Reference conventions" headings — `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
**Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly. **Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
@@ -26,7 +26,7 @@ Issue files frequently referenced "the workflow defined in `docs/notes/skill-imp
The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context. The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context.
**Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read CONTEXT.md at the start of every session in this repo," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change. **Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read `CONTEXT.md` at the start of every session," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change.
## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity ## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity
@@ -245,3 +245,19 @@ noticed — and before describing any defect as pre-existing, run `git log -S` o
plugin-content and vale-style drift deterministically and has no equivalent gate asserting tool-owned plugin-content and vale-style drift deterministically and has no equivalent gate asserting tool-owned
paths stay out of formatter scope — `.claude/settings.json` was the sixteenth exclude and nothing paths stay out of formatter scope — `.claude/settings.json` was the sixteenth exclude and nothing
prevents a seventeenth. prevents a seventeenth.
## 2026-08-16 — A rule reversed inside a retrofit leaves no trace unless someone writes it down
`skill-author/SKILL.md:204` on `main` said "Keep reference chains one level deep — a reference file
that references another reference file is rarely loaded correctly." The ADR-0020 retrofit replaced it
with "Two hops from `SKILL.md`, never three" in `references/create.md` and `references/retrofit.md`,
which permits exactly the chain the old rule banned. The looser rule is the right one and the
retrofit could not have shipped without it: dispatch pushes each flow into its own file, so the
shipped structure is `SKILL.md` → `improve.md` → `retrofit.md`, and a one-level ceiling would have
made the mandatory dispatch pattern illegal. But ADR-0020 says nothing about chain depth, so the
reversal was carried entirely by the diff — the new text asserts the new rule with no sign that a
contradicting rule ever existed, and a reader who remembers the old one has no way to tell whether it
was overturned or overlooked. Fix: when a change inverts a standing authoring rule rather than
tightening or restating it, record the inversion where the rule's rationale lives — the ADR if the
ADR is the reason, here otherwise. A rule that quietly flips is indistinguishable from a rule that
was forgotten, and the second reading is the one that gets it re-added later.

131
README.md Normal file
View File

@@ -0,0 +1,131 @@
# holocron
The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Built as a homelab tool intended to scale to professional environments.
Content ships as six installable plugins, each an apm (Agent Package Manager) package. This repo consumes its own plugins through apm, so the working copy runs the same released content every other consumer gets.
## Repo layout
| Path | What it holds |
| --- | --- |
| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets |
| `providers/claude-code/` | Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh` |
| `core/` | Provider-agnostic always-on content — `core/AGENTS.md` and `core/instructions/` |
| `docs/` | Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes |
| `scripts/` | Install, sync, and check scripts used by the git hooks |
| `tests/` | `run-tests.sh`, `run-bats.sh`, the `test-*.sh` suites, and the bats submodules |
The six plugins:
- **kyberforge** — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace
- **git** — conventional commits, branches, history, submodules, worktrees, remotes, pre-commit hook authoring and running (`pc-author` / `pc-run`), and an interactive router (`git-workflow`)
- **gitea** — issues, pull requests, labels, milestones, releases, branches, files, and an interactive router (`gitea-workflow`)
- **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it
- **lint** — configuring and running linters
- **bin** — cross-cutting workflow skills not yet split into a focused plugin: research, documentation, TDD, prototyping, triage, diagnosis, architecture review, requirement grilling, compressed output (`caveman`), and re-orienting mid-task (`zoom-out`)
## Prerequisites
Install all of these before setting up. Each one is a hard dependency of a git hook or a script — several fail with an unhelpful "command not found" if missing.
| Tool | Why | Install |
| --- | --- | --- |
| `apm` CLI | Four pre-push hooks shell out to it (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` via `scripts/sync-plugin-content.sh`) | The `apm-install` skill, or `curl -sSL https://aka.ms/apm-unix \| sh`. Verify with `apm --version` |
| `jq` | Required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push | Your package manager |
| `python3` + PyYAML | Required by `scripts/skill-size-check.sh` (the `skill-size-check` pre-commit hook), which reads folded YAML frontmatter | `python3` is usually present — pre-commit is itself a Python application. `pip install pyyaml` if the hook reports PyYAML missing |
| `vale` | Required by the `vale-audit-prefilter-skill` / `-agent` pre-commit hooks and the `check-vale-style-sync` pre-push hook | `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or https://vale.sh/docs/vale-cli/installation/ |
| `claude` CLI | Required by the `validate-plugins` and `validate-marketplace` pre-push hooks | Claude Code |
Two notes worth reading before you skip one:
- **PyYAML is a hard requirement, not an optional accelerator.** The hand-rolled fallback frontmatter reader was removed deliberately: a reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured.
- **No `vale sync` is needed.** The `Kyberforge` styles are committed under `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (ADR-0014).
## Setup
Run these in order, from the repo root.
```bash
# 1. Deploy this repo's own skills and agents
apm install
# 2. Install the git hooks — all three stages
pre-commit install -t pre-commit -t commit-msg -t pre-push
```
**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins/<name>/.apm/` remains the only place to edit. It needs the network, materializes `apm_modules/` (which stays gitignored), and also configures the `obsidian` MCP server into the repo's `.mcp.json`.
**Git hooks** must be wired for **all three stages**. This repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain `pre-commit install` silently skips `commit-msg` (Conventional Commits) and `pre-push` (the full gate) — the `-t` flags above are not optional. The `pc-run` skill handles this and the troubleshooting around it, if you would rather not remember the flags.
## Keeping the install current
The six dependencies in root `apm.yml` are unpinned against the default branch, so deployed skills go stale whenever anyone merges. kyberforge ships a `SessionStart` hook that runs `apm outdated` at startup (~0.7s) and, when something is behind, runs `apm update --yes` and asks the host to re-scan skills (~10.4s).
That rewrites `apm.lock.yaml` — an unexplained modification to it after opening a session is expected, not a bug. Commit or discard it deliberately.
Note the difference between the two commands:
- `apm install` deploys from `apm.lock.yaml`. It does **not** pick up remote changes.
- `apm update` re-resolves refs. This is the command that pulls in a merged `.apm/` edit.
## Running tests
```bash
bash tests/run-tests.sh # every test-*.sh script plus the bats suite
bash tests/run-tests.sh --bats-only # just bats
```
The first run auto-initializes the bats submodules; no manual `git submodule update` needed.
A suite that exits 77 because a dependency is missing is reported as SKIPPED and does **not** fail an ad-hoc run. It *does* fail under `--strict` (equivalently `RUN_TESTS_STRICT=1`), which is how the pre-push hook invokes it — at pre-push, a skip means one of the prerequisites above is absent on this machine, and the gate would otherwise report success having run fewer suites than it appears to. The strict failure names each skipped suite and what to install.
## Before pushing
Run the pre-push gate locally in one command:
```bash
pre-commit run --hook-stage pre-push --all-files
```
One caveat: `check-release-needed` is a silent no-op under this invocation. It exits 0 unless
`PRE_COMMIT_REMOTE_BRANCH` is `refs/heads/main`, and pre-commit exports that only from the real
pre-push git hook during an actual `git push` — so the hook reports `Passed` having checked nothing.
Every other pre-push hook does run.
See [`docs/spec/gates.md`](docs/spec/gates.md) for what each hook enforces and why.
**Offline?** Exactly two pre-push hooks need the network, because root `apm.yml`'s marketplace contains one remote package entry that must be resolved with `git ls-remote`:
```bash
SKIP=apm-marketplace-check,apm-pack-check-clean git push
```
Skip **only** those two. The remaining pre-push hooks are real local checks and pass offline; adding one of them to `SKIP` disarms it silently.
## Editing plugin content
`plugins/<name>/.apm/` is the only hand-edited source for plugin content — skills, agents, commands, instructions, extensions, and hooks. The flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories, the merged `hooks/hooks.json`, and every `plugin.json` / `marketplace.json` manifest are generated. Nothing labels a generated file as generated, so check the path before you edit; an edit to the mirror is discarded by the next sync and reported as drift by the `check-plugin-content-sync` pre-push hook.
Hand-authored material that is *not* an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json` — lives at the plugin **root** and is untouched. Never place such a file inside a mirrored directory: the sync removes the destination before every copy, so it is deleted with no drift report.
Full detail in [`docs/spec/architecture.md`](docs/spec/architecture.md).
## For external consumers
Install a plugin natively from the marketplace manifests:
```bash
claude plugin install <name>@holocron
```
Or consume the packages through apm, the way this repo does — declare them as `dependencies.apm` git+path entries against the holocron remote and run `apm install`.
## Where to go next
- [`AGENTS.md`](AGENTS.md) — the rules for AI agents working in this repo
- [`CONTEXT.md`](CONTEXT.md) — domain language; read at the start of every session here
- [`docs/spec/architecture.md`](docs/spec/architecture.md) — directory structure, install pipeline, provider model
- [`docs/spec/gates.md`](docs/spec/gates.md) — the enforcement gates in depth
- [`docs/adr/`](docs/adr/) — architectural decisions; read before proposing structural changes
- [`docs/VISION.md`](docs/VISION.md) — where this is going
- [`LESSONS.md`](LESSONS.md) — things that went wrong once and should not again

350
apm.lock.yaml
View File

@@ -1,11 +1,11 @@
lockfile_version: '1' lockfile_version: '1'
generated_at: '2026-08-14T21:26:25.156410+00:00' generated_at: '2026-08-17T06:44:18.931217+00:00'
apm_version: 0.28.0 apm_version: 0.28.0
dependencies: dependencies:
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: bin name: bin
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.1.3 version: 1.1.3
virtual_path: plugins/bin virtual_path: plugins/bin
is_virtual: true is_virtual: true
@@ -87,7 +87,7 @@ dependencies:
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: core name: core
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.1.1 version: 1.1.1
virtual_path: plugins/core virtual_path: plugins/core
is_virtual: true is_virtual: true
@@ -134,7 +134,7 @@ dependencies:
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: git name: git
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.3.3 version: 1.3.3
virtual_path: plugins/git virtual_path: plugins/git
is_virtual: true is_virtual: true
@@ -241,7 +241,7 @@ dependencies:
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: gitea name: gitea
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.3.4 version: 1.3.4
virtual_path: plugins/gitea virtual_path: plugins/gitea
is_virtual: true is_virtual: true
@@ -332,8 +332,8 @@ dependencies:
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: kyberforge name: kyberforge
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.5.0 version: 1.6.0
virtual_path: plugins/kyberforge virtual_path: plugins/kyberforge
is_virtual: true is_virtual: true
package_type: marketplace_plugin package_type: marketplace_plugin
@@ -344,15 +344,20 @@ dependencies:
- .claude/skills/agent-audit/README.md - .claude/skills/agent-audit/README.md
- .claude/skills/agent-audit/SKILL.md - .claude/skills/agent-audit/SKILL.md
- .claude/skills/agent-audit/assets/vale/.vale.ini - .claude/skills/agent-audit/assets/vale/.vale.ini
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml
- .claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml - .claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml
- .claude/skills/agent-audit/references/README.md - .claude/skills/agent-audit/references/README.md
- .claude/skills/agent-audit/references/body-and-delegation.md
- .claude/skills/agent-audit/references/description-quality.md - .claude/skills/agent-audit/references/description-quality.md
- .claude/skills/agent-audit/references/field-inventory.md - .claude/skills/agent-audit/references/field-inventory.md
- .claude/skills/agent-audit/references/scope-plugin-apm.md
- .claude/skills/agent-audit/references/scope-project-user.md
- .claude/skills/agent-audit/references/sources.md - .claude/skills/agent-audit/references/sources.md
- .claude/skills/agent-audit/references/validation-scripts.md
- .claude/skills/agent-audit/scripts/README.md - .claude/skills/agent-audit/scripts/README.md
- .claude/skills/agent-audit/scripts/vale-wrap.sh - .claude/skills/agent-audit/scripts/vale-wrap.sh
- .claude/skills/agent-audit/scripts/validate-provenance.sh - .claude/skills/agent-audit/scripts/validate-provenance.sh
@@ -365,7 +370,12 @@ dependencies:
- .claude/skills/agent-author/assets/templates/claude-code.md - .claude/skills/agent-author/assets/templates/claude-code.md
- .claude/skills/agent-author/assets/templates/copilot.agent.md.template - .claude/skills/agent-author/assets/templates/copilot.agent.md.template
- .claude/skills/agent-author/references/README.md - .claude/skills/agent-author/references/README.md
- .claude/skills/agent-author/references/contract.md
- .claude/skills/agent-author/references/create.md
- .claude/skills/agent-author/references/deployment-modes.md - .claude/skills/agent-author/references/deployment-modes.md
- .claude/skills/agent-author/references/improve.md
- .claude/skills/agent-author/references/plugin-scope.md
- .claude/skills/agent-author/references/project-user-scope.md
- .claude/skills/agent-author/references/scripts.md - .claude/skills/agent-author/references/scripts.md
- .claude/skills/agent-author/references/sources.md - .claude/skills/agent-author/references/sources.md
- .claude/skills/agent-author/scripts/README.md - .claude/skills/agent-author/scripts/README.md
@@ -391,13 +401,18 @@ dependencies:
- .claude/skills/skill-audit/README.md - .claude/skills/skill-audit/README.md
- .claude/skills/skill-audit/SKILL.md - .claude/skills/skill-audit/SKILL.md
- .claude/skills/skill-audit/assets/vale/.vale.ini - .claude/skills/skill-audit/assets/vale/.vale.ini
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml
- .claude/skills/skill-audit/references/body-discipline.md - .claude/skills/skill-audit/references/body-discipline.md
- .claude/skills/skill-audit/references/description-quality.md - .claude/skills/skill-audit/references/description-quality.md
- .claude/skills/skill-audit/references/file-structure.md
- .claude/skills/skill-audit/references/formatting-and-scripts.md
- .claude/skills/skill-audit/references/patterns.md
- .claude/skills/skill-audit/references/sources.md - .claude/skills/skill-audit/references/sources.md
- .claude/skills/skill-audit/references/validation-scripts.md
- .claude/skills/skill-audit/scripts/vale-wrap.sh - .claude/skills/skill-audit/scripts/vale-wrap.sh
- .claude/skills/skill-audit/scripts/validate-provenance.sh - .claude/skills/skill-audit/scripts/validate-provenance.sh
- .claude/skills/skill-audit/scripts/validate.sh - .claude/skills/skill-audit/scripts/validate.sh
@@ -411,41 +426,55 @@ dependencies:
- .claude/skills/skill-author/assets/templates/references/sources.md - .claude/skills/skill-author/assets/templates/references/sources.md
- .claude/skills/skill-author/assets/templates/scripts/README.md - .claude/skills/skill-author/assets/templates/scripts/README.md
- .claude/skills/skill-author/assets/templates/tests/README.md - .claude/skills/skill-author/assets/templates/tests/README.md
- .claude/skills/skill-author/references/contract.md
- .claude/skills/skill-author/references/create.md
- .claude/skills/skill-author/references/deployment-modes.md - .claude/skills/skill-author/references/deployment-modes.md
- .claude/skills/skill-author/references/improve.md
- .claude/skills/skill-author/references/retrofit.md
- .claude/skills/skill-author/references/scripts.md - .claude/skills/skill-author/references/scripts.md
- .claude/skills/skill-author/references/sources.md - .claude/skills/skill-author/references/sources.md
- .claude/skills/skill-author/scripts/new-skill.sh - .claude/skills/skill-author/scripts/new-skill.sh
deployed_file_hashes: deployed_file_hashes:
.claude/agents/apm-orchestrate.md: sha256:fbb78f7c8c58b018639e7a39f2f1b3ce2adcd6bed277b3c8f8cd70893698ec73 .claude/agents/apm-orchestrate.md: sha256:fbb78f7c8c58b018639e7a39f2f1b3ce2adcd6bed277b3c8f8cd70893698ec73
.claude/hooks/kyberforge/.apm/hooks/check-apm-current.sh: sha256:96f44d63b5f4906ac1add5c32b718176ec10c8514615151d7303d9845c607b46 .claude/hooks/kyberforge/.apm/hooks/check-apm-current.sh: sha256:96f44d63b5f4906ac1add5c32b718176ec10c8514615151d7303d9845c607b46
.claude/skills/agent-audit/README.md: sha256:a3a63acb80981975330bd9a86d81c8f3e632f7f2d97ac99951710d035fb52953 .claude/skills/agent-audit/README.md: sha256:fafdb84bf258f6d606c97b785c7c378b5de805f0aa8a10d3cedefedb000e4230
.claude/skills/agent-audit/SKILL.md: sha256:080f391ea25de8afc5a20478cbd382a8d28fcf70a7be7f012033dacb6e9bfed3 .claude/skills/agent-audit/SKILL.md: sha256:a126a2a7b1b8c9f6b39272584e2f84577aeeb8c81707be6f151b3acbe35ecf51
.claude/skills/agent-audit/assets/vale/.vale.ini: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57 .claude/skills/agent-audit/assets/vale/.vale.ini: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/CompositionNote.yml: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083
.claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml: sha256:ba4f91479f66f9f03c74f791cbc6130b24bbc31a25f3897b424f72d02473b9b4 .claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml: sha256:ba4f91479f66f9f03c74f791cbc6130b24bbc31a25f3897b424f72d02473b9b4
.claude/skills/agent-audit/references/README.md: sha256:7664ae08efc8373c0b253c0a5c7a9cc930720c62abb8d31a81b2aedbd573dd30 .claude/skills/agent-audit/references/README.md: sha256:f6d777f7d3844d1be847f86f67b08c2db37b2d122e0bf1af92ef057bbfdd1004
.claude/skills/agent-audit/references/description-quality.md: sha256:79c62fd641d6785a3349d8ff1e207c64547ef9435d51e88518fc9fb5c2f4962e .claude/skills/agent-audit/references/body-and-delegation.md: sha256:788664bb75364354773bd9efd4a0f84a231009d3a8b080e2561fefff2aa95b69
.claude/skills/agent-audit/references/description-quality.md: sha256:15eea332149203ac18c6b3eee98f0078e8a764cdb91b3158590f45204cb3322a
.claude/skills/agent-audit/references/field-inventory.md: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae .claude/skills/agent-audit/references/field-inventory.md: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae
.claude/skills/agent-audit/references/sources.md: sha256:9e06addbfb1a58e4db23eaabe9fb13afe0fffa8419afa575525136cec189c558 .claude/skills/agent-audit/references/scope-plugin-apm.md: sha256:af32acf33aec0cd0a98022ee6796265066c693662e8874a8e4d7e03ce1657c88
.claude/skills/agent-audit/references/scope-project-user.md: sha256:9ea0d4014d78a6b02c760e42fb6cb72b3441ae6c93991fdeca666857bad05056
.claude/skills/agent-audit/references/sources.md: sha256:235de49e805d83ba19f8ecdc90da2f7d3b02c5f1c2fc54179d6bdd5bc398743e
.claude/skills/agent-audit/references/validation-scripts.md: sha256:7eb48ec40175d6cce2b3b9602c0d9e60d62bacca1df7cc120c138ea1ce328666
.claude/skills/agent-audit/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2 .claude/skills/agent-audit/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2
.claude/skills/agent-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995 .claude/skills/agent-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995
.claude/skills/agent-audit/scripts/validate-provenance.sh: sha256:0e1d2b3bb1abb9f302ed84a618246ebaa7d5f7fda727b290d323e70dcc26a323 .claude/skills/agent-audit/scripts/validate-provenance.sh: sha256:0e1d2b3bb1abb9f302ed84a618246ebaa7d5f7fda727b290d323e70dcc26a323
.claude/skills/agent-audit/scripts/validate.sh: sha256:29727875f419b8d3b6c76f157b7569adb4d2b9a88f01eeb2c09e04dfb8541cb3 .claude/skills/agent-audit/scripts/validate.sh: sha256:50c6d3875fd44901fba3fcb69256f616be19521ee8209b7132778c1d4a693a3f
.claude/skills/agent-author/README.md: sha256:015a6b030ff2aa913f982a223f8afad789edadc4e7148d3b1740a56b346c658d .claude/skills/agent-author/README.md: sha256:b2d14a3c8fc3ddc3935d0bd1765192b333b944baaf9bfa9a350bef0985890265
.claude/skills/agent-author/SKILL.md: sha256:39193473a9b1beacb4790cab4e5e31e01f7021a68a5c4cc16a606420bee65d6a .claude/skills/agent-author/SKILL.md: sha256:8fe96e4744378cd33876cf87a08a20af001898e89f0f27087044e1b87eac61f2
.claude/skills/agent-author/assets/README.md: sha256:a82665201ead91b7fa2b37629327ecb89ca785b7f2b261300c2dd816b4219bcd .claude/skills/agent-author/assets/README.md: sha256:730b2321b5f16dcc63fc5dc842618c116afc75217ae925057dafc490e7d57644
.claude/skills/agent-author/assets/templates/apm-agent.md: sha256:c2693395d7ec72645fc1b79c65039ddadc0077f5856de3277d600bde41f17e54 .claude/skills/agent-author/assets/templates/apm-agent.md: sha256:9b57e2b93a5705388351f14294d60833325d9596cf5294d22f4a586165fc35fa
.claude/skills/agent-author/assets/templates/claude-code.md: sha256:eef5ee46d93b6896e880b3c4aec1121c4077a2556c6d9f4a01b322afc7b63a7e .claude/skills/agent-author/assets/templates/claude-code.md: sha256:ea0bac6e8cd91c767c6114cbcf1ecd124d03abff06ba81696dac5115499c395a
.claude/skills/agent-author/assets/templates/copilot.agent.md.template: sha256:1e0c0445a8908148e69baeeb44316fb370aa483e17fcd63d7f1b2d3ad1927788 .claude/skills/agent-author/assets/templates/copilot.agent.md.template: sha256:ee8b7585c808c5ff4b715be74d9e4f8c5c17d13cd603a8727cd8ca1793d14760
.claude/skills/agent-author/references/README.md: sha256:bb4cf7a34c512da33f574b208756941f396f4a1e55daaed0fad22569a22af301 .claude/skills/agent-author/references/README.md: sha256:aca156b02a3f0b9fddde3cefdb24370e17cc5886dcd78adcb382699a5cc0bbaf
.claude/skills/agent-author/references/deployment-modes.md: sha256:6cd010455e10574566ebf7cfd0926217ae5812d56a62daf4bcdb325abf3b0421 .claude/skills/agent-author/references/contract.md: sha256:a96f0ef021a6629120e5af7c98fa483d31de92cea37f98b51528a28dee38e16a
.claude/skills/agent-author/references/create.md: sha256:e4a1b95970ec44d551a4b0598f2fe01463db13a6b118981d8cd03dfc7e24f451
.claude/skills/agent-author/references/deployment-modes.md: sha256:5675f8dcd1523269d5c65be5b0e06ff4d822b158050e2fdd72b54f605485ab1f
.claude/skills/agent-author/references/improve.md: sha256:f260e91f28bbd62093b53f4efc05821eff00d086f834ddb083b70dd77ddffcaa
.claude/skills/agent-author/references/plugin-scope.md: sha256:a20f8aff55c9d1c1ba5e21054b81da80618270b3b6ca5bfc37ae3c2089b4b916
.claude/skills/agent-author/references/project-user-scope.md: sha256:3f686736259402e38fed29f215b7aa5a9529fc9025005f82d0c3d439958e4e03
.claude/skills/agent-author/references/scripts.md: sha256:290f5d8ab0a4f2073e14f7139fd55ab40310137f08ca7a2d59ed35a53488a592 .claude/skills/agent-author/references/scripts.md: sha256:290f5d8ab0a4f2073e14f7139fd55ab40310137f08ca7a2d59ed35a53488a592
.claude/skills/agent-author/references/sources.md: sha256:56965f9b660fc9a32dd71ca1039b4c6b8f932420628ddfbf3a2525e7c3336ce4 .claude/skills/agent-author/references/sources.md: sha256:cac8baf85a6d958ed2f0f882446dc123d14082d5ca412c8edee12c6cd1b6fdc3
.claude/skills/agent-author/scripts/README.md: sha256:e8ea2f3391ca297afeda03911768000617a71df0cf9d673bbb260ee5bbfed7c2 .claude/skills/agent-author/scripts/README.md: sha256:e8ea2f3391ca297afeda03911768000617a71df0cf9d673bbb260ee5bbfed7c2
.claude/skills/agent-author/scripts/new-agent.sh: sha256:e917055957500a72c7f684810552ba8931781c90f96dedaabc07e899dae02a89 .claude/skills/agent-author/scripts/new-agent.sh: sha256:1c631f5178c6c0c397d7ceefb606892dd7e330cd1b22a03c1e4d11e85fbdb7de
.claude/skills/apm-install/README.md: sha256:d7bd79ee27997fffb5765c03358a700d8c00266ea120f6d067d74300d6c26eb0 .claude/skills/apm-install/README.md: sha256:d7bd79ee27997fffb5765c03358a700d8c00266ea120f6d067d74300d6c26eb0
.claude/skills/apm-install/SKILL.md: sha256:4c0db5454bcbf895a89e7405eeefb4521a2b23f2ff28aa96c82c59708d8819ee .claude/skills/apm-install/SKILL.md: sha256:4c0db5454bcbf895a89e7405eeefb4521a2b23f2ff28aa96c82c59708d8819ee
.claude/skills/apm-install/references/sources.md: sha256:b80245ff8ae179d458572cb9b03621d00bf7e2f052f0cd71b88112c0ea8a91ce .claude/skills/apm-install/references/sources.md: sha256:b80245ff8ae179d458572cb9b03621d00bf7e2f052f0cd71b88112c0ea8a91ce
@@ -460,39 +489,48 @@ dependencies:
.claude/skills/forge/README.md: sha256:2151b952f4438cd9212edd97de90eec06f027f01121b3badb9d32dc9c45320c4 .claude/skills/forge/README.md: sha256:2151b952f4438cd9212edd97de90eec06f027f01121b3badb9d32dc9c45320c4
.claude/skills/forge/SKILL.md: sha256:4de4c629cb4aec4c6cac5347163a86fe123299f131510dc43857597ded6ae497 .claude/skills/forge/SKILL.md: sha256:4de4c629cb4aec4c6cac5347163a86fe123299f131510dc43857597ded6ae497
.claude/skills/forge/references/sources.md: sha256:a7f614c0ab37aa403545e191722bca012836162dcab30ff8ac984cbb25ad68cd .claude/skills/forge/references/sources.md: sha256:a7f614c0ab37aa403545e191722bca012836162dcab30ff8ac984cbb25ad68cd
.claude/skills/skill-audit/README.md: sha256:9e3533c3c44cfd249cf02684ef43db822ed41382362e8ce71f1254d10711c8e0 .claude/skills/skill-audit/README.md: sha256:78bfcfb16bbeef814b83f37a4a5185886003f9442a6d0e7e94be56f54d18d7a5
.claude/skills/skill-audit/SKILL.md: sha256:dbe2adfd0101cf9d6b3c2c3c2aa3ae397c717f835c1059c0f1d805e9057dc397 .claude/skills/skill-audit/SKILL.md: sha256:57a9336d409c883dc9a78aa92a9f0075fac6f8e4aac6ee8fdab705055ef85162
.claude/skills/skill-audit/assets/vale/.vale.ini: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f .claude/skills/skill-audit/assets/vale/.vale.ini: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/CompositionNote.yml: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083
.claude/skills/skill-audit/references/body-discipline.md: sha256:2295d2fc72fa529f3700c21fa93516ad186a7cc66d470370173ab1a784d03d31 .claude/skills/skill-audit/references/body-discipline.md: sha256:f8a27d7266f4453781712f0bead151580158581a445a641613203a67a1c337d7
.claude/skills/skill-audit/references/description-quality.md: sha256:ab077e71bbc6e9d8e2a1384bedaf613a4219f28bbe42eb9e89f933b579db6b33 .claude/skills/skill-audit/references/description-quality.md: sha256:2d37eccb4889cade6cbad0deaaed6d1f5fe4c3276c5438c244b2f87ae27bf432
.claude/skills/skill-audit/references/sources.md: sha256:cb65dd3cc411d7b264fab24de5cd2353dec8fbb7bbcfe2388535d963be240280 .claude/skills/skill-audit/references/file-structure.md: sha256:b24638bd639ef048da171f6dc711e345749cde3c70ec6ba1b7fcbd696b921841
.claude/skills/skill-audit/references/formatting-and-scripts.md: sha256:5c319866b2f22ba07789dae7b0813132f67196c508e8da23971307c2a9e57095
.claude/skills/skill-audit/references/patterns.md: sha256:4a942ab30b95dc0cbf0fbe7da3b91157f166bce80cbd17bcf60dc365ea9237af
.claude/skills/skill-audit/references/sources.md: sha256:1db16ea23884ac2db799b42d1284daaab4b24eb94f184a95fb67ddc280385934
.claude/skills/skill-audit/references/validation-scripts.md: sha256:44f3b82413b57f2b5671637bb449a4c01b6d5fcd9059245aaa38e45108adf480
.claude/skills/skill-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995 .claude/skills/skill-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995
.claude/skills/skill-audit/scripts/validate-provenance.sh: sha256:015376c5ad1f6bb6b53549537317a55e3ac06cd4e347451dba85879a3928ccbe .claude/skills/skill-audit/scripts/validate-provenance.sh: sha256:015376c5ad1f6bb6b53549537317a55e3ac06cd4e347451dba85879a3928ccbe
.claude/skills/skill-audit/scripts/validate.sh: sha256:ebbef859276135b7fe4189b31396fd98e5d4019685d7cb55e39a10fac8ca546d .claude/skills/skill-audit/scripts/validate.sh: sha256:7ce27df82e4160c6296db6c8314865f022da5c4334151857570a86167c8d4e11
.claude/skills/skill-author/README.md: sha256:6c0b36f9b28a33de1646df45bd8e4d733ab3b26c0bdff49743962aa068085f6d .claude/skills/skill-author/README.md: sha256:d22035d302818e103486e447bd92d2da4c9b73da60f30157941710f32f400b89
.claude/skills/skill-author/SKILL.md: sha256:7b82d16fe0d61a71c5b59a244cf92b9b5fc2635916ad1572f4f5f6e37172bf09 .claude/skills/skill-author/SKILL.md: sha256:615a936580f44dd8e523496aadf88df6d512ac58369190b90407e8fca86e8345
.claude/skills/skill-author/assets/templates/README.md: sha256:f7e91356f4c85862f96a9f46a7a7ae8b5dc715c8174add5cf070166a8bae0658 .claude/skills/skill-author/assets/templates/README.md: sha256:f7e91356f4c85862f96a9f46a7a7ae8b5dc715c8174add5cf070166a8bae0658
.claude/skills/skill-author/assets/templates/SKILL.md: sha256:f05a127963874bfbbe4333c42c5208736d84d5bf12dd8478351f6853304cc9d1 .claude/skills/skill-author/assets/templates/SKILL.md: sha256:b20c65bd185b300de7e65d16decdf0ab4aaf6c094822c1f798b3c278d52abbff
.claude/skills/skill-author/assets/templates/assets/README.md: sha256:b72e51e643c45ded210a257e475d5661035d2aa5ed581e3294fd2aed00765c4b .claude/skills/skill-author/assets/templates/assets/README.md: sha256:b72e51e643c45ded210a257e475d5661035d2aa5ed581e3294fd2aed00765c4b
.claude/skills/skill-author/assets/templates/references/README.md: sha256:63754636f84a7841f31ab1f2854025ee449a29840ed6b9b51bcb1422ab5522d0 .claude/skills/skill-author/assets/templates/references/README.md: sha256:e2ef117972ab2625a456ed80ff085859666d145de4e270f383cde7c8e84ad60a
.claude/skills/skill-author/assets/templates/references/sources.md: sha256:fe126720ba890b98e829f2626e3f5a361a0c2ce47eda97bd3f7dc1812ddd62b7 .claude/skills/skill-author/assets/templates/references/sources.md: sha256:fe126720ba890b98e829f2626e3f5a361a0c2ce47eda97bd3f7dc1812ddd62b7
.claude/skills/skill-author/assets/templates/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2 .claude/skills/skill-author/assets/templates/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2
.claude/skills/skill-author/assets/templates/tests/README.md: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442 .claude/skills/skill-author/assets/templates/tests/README.md: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442
.claude/skills/skill-author/references/contract.md: sha256:d350721118a2bd57094fa9151f11b48a663a1c8a04e50fba71ff2baf64b7282f
.claude/skills/skill-author/references/create.md: sha256:0837a77ad6da7ae9894134d15eebd57950b8505e8bd2b32ee69f281d65a6abcb
.claude/skills/skill-author/references/deployment-modes.md: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759 .claude/skills/skill-author/references/deployment-modes.md: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759
.claude/skills/skill-author/references/improve.md: sha256:abe029587ce475fed165d8fcfa46ea1abe83f90727d093f8121a9a7a7daa5a3d
.claude/skills/skill-author/references/retrofit.md: sha256:6c8336caa717f2abd38cb1f9c776479c0e908f7dbf577021d3689b375287dc77
.claude/skills/skill-author/references/scripts.md: sha256:fe71da1fb3d947846ad1a37348f90866b0c4f7dbd81331cfe3300981656f6cc2 .claude/skills/skill-author/references/scripts.md: sha256:fe71da1fb3d947846ad1a37348f90866b0c4f7dbd81331cfe3300981656f6cc2
.claude/skills/skill-author/references/sources.md: sha256:27637acad4c0cdc7f1db15bc9cab339ebdac643e084642c58945ac2f81020c75 .claude/skills/skill-author/references/sources.md: sha256:652f7ce26c0d68a3ed11db09206bff20ba230ca8ff1fe71ae45b6f4505979327
.claude/skills/skill-author/scripts/new-skill.sh: sha256:46c6903404b9eabbd6c83892213fdabf9cad193be64613b8c1b84c8dc37e8eb2 .claude/skills/skill-author/scripts/new-skill.sh: sha256:c788b56f73ed4fd03edb179159361fe16e3afbf528a9895e9251909c5aa40a7f
content_hash: sha256:c89a45409fd3e06a6c63ca8a8f0f0d9c8e10bbded73fdef15dd482eebc6b6a78 content_hash: sha256:32185a11d3d859e5235de2c43065920ba8950c1684e6aec46f0f7170ff4a111e
declared_license: MIT declared_license: MIT
exec_status: deployed exec_status: deployed
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: lint name: lint
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
version: 1.1.6 version: 1.1.6
virtual_path: plugins/lint virtual_path: plugins/lint
is_virtual: true is_virtual: true
@@ -519,9 +557,8 @@ dependencies:
.claude/skills/vale-run/SKILL.md: sha256:16c42c97de14ef20296b9dfce46b0e2f9be6ad68751c35975251cecff80f79d9 .claude/skills/vale-run/SKILL.md: sha256:16c42c97de14ef20296b9dfce46b0e2f9be6ad68751c35975251cecff80f79d9
.claude/skills/vale-run/references/sources.md: sha256:1f46b727e5f3db09d6c8c01c8a615bad60ce2c5b3a01226e1a3fd3b933330bc7 .claude/skills/vale-run/references/sources.md: sha256:1f46b727e5f3db09d6c8c01c8a615bad60ce2c5b3a01226e1a3fd3b933330bc7
.claude/skills/vale-run/references/troubleshooting.md: sha256:b4c2bc67b413b102d9fe1cd7e5a248b19aba3dc3b60b4429e777977cf8021cd5 .claude/skills/vale-run/references/troubleshooting.md: sha256:b4c2bc67b413b102d9fe1cd7e5a248b19aba3dc3b60b4429e777977cf8021cd5
content_hash: sha256:7bc57b8852680bdcba32a6a6108b99ef6bcdf26eacfecd806c421ec5d1fd47d9 content_hash: sha256:f7915119bf5d349bb4dd26b7999278770dd2e0b38e4b4db57c0819a15cbf97a3
declared_license: MIT declared_license: MIT
exec_status: gated_pending_approval
deployments: deployments:
- kind: project-relative - kind: project-relative
target: claude target: claude
@@ -585,7 +622,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a3a63acb80981975330bd9a86d81c8f3e632f7f2d97ac99951710d035fb52953 content_hash: sha256:fafdb84bf258f6d606c97b785c7c378b5de805f0aa8a10d3cedefedb000e4230
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/SKILL.md value: .claude/skills/agent-audit/SKILL.md
@@ -594,7 +631,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:080f391ea25de8afc5a20478cbd382a8d28fcf70a7be7f012033dacb6e9bfed3 content_hash: sha256:a126a2a7b1b8c9f6b39272584e2f84577aeeb8c81707be6f151b3acbe35ecf51
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/assets/vale/.vale.ini value: .claude/skills/agent-audit/assets/vale/.vale.ini
@@ -604,6 +641,15 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57 content_hash: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
@@ -612,7 +658,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 content_hash: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
@@ -657,7 +703,16 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:7664ae08efc8373c0b253c0a5c7a9cc930720c62abb8d31a81b2aedbd573dd30 content_hash: sha256:f6d777f7d3844d1be847f86f67b08c2db37b2d122e0bf1af92ef057bbfdd1004
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/body-and-delegation.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:788664bb75364354773bd9efd4a0f84a231009d3a8b080e2561fefff2aa95b69
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/references/description-quality.md value: .claude/skills/agent-audit/references/description-quality.md
@@ -666,7 +721,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:79c62fd641d6785a3349d8ff1e207c64547ef9435d51e88518fc9fb5c2f4962e content_hash: sha256:15eea332149203ac18c6b3eee98f0078e8a764cdb91b3158590f45204cb3322a
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/references/field-inventory.md value: .claude/skills/agent-audit/references/field-inventory.md
@@ -676,6 +731,24 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae content_hash: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/scope-plugin-apm.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:af32acf33aec0cd0a98022ee6796265066c693662e8874a8e4d7e03ce1657c88
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/scope-project-user.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:9ea0d4014d78a6b02c760e42fb6cb72b3441ae6c93991fdeca666857bad05056
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/references/sources.md value: .claude/skills/agent-audit/references/sources.md
@@ -684,7 +757,16 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:9e06addbfb1a58e4db23eaabe9fb13afe0fffa8419afa575525136cec189c558 content_hash: sha256:235de49e805d83ba19f8ecdc90da2f7d3b02c5f1c2fc54179d6bdd5bc398743e
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/validation-scripts.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:7eb48ec40175d6cce2b3b9602c0d9e60d62bacca1df7cc120c138ea1ce328666
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/scripts/README.md value: .claude/skills/agent-audit/scripts/README.md
@@ -720,7 +802,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:29727875f419b8d3b6c76f157b7569adb4d2b9a88f01eeb2c09e04dfb8541cb3 content_hash: sha256:50c6d3875fd44901fba3fcb69256f616be19521ee8209b7132778c1d4a693a3f
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author value: .claude/skills/agent-author
@@ -738,7 +820,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:015a6b030ff2aa913f982a223f8afad789edadc4e7148d3b1740a56b346c658d content_hash: sha256:b2d14a3c8fc3ddc3935d0bd1765192b333b944baaf9bfa9a350bef0985890265
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/SKILL.md value: .claude/skills/agent-author/SKILL.md
@@ -747,7 +829,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:39193473a9b1beacb4790cab4e5e31e01f7021a68a5c4cc16a606420bee65d6a content_hash: sha256:8fe96e4744378cd33876cf87a08a20af001898e89f0f27087044e1b87eac61f2
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/README.md value: .claude/skills/agent-author/assets/README.md
@@ -756,7 +838,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a82665201ead91b7fa2b37629327ecb89ca785b7f2b261300c2dd816b4219bcd content_hash: sha256:730b2321b5f16dcc63fc5dc842618c116afc75217ae925057dafc490e7d57644
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/templates/apm-agent.md value: .claude/skills/agent-author/assets/templates/apm-agent.md
@@ -765,7 +847,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:c2693395d7ec72645fc1b79c65039ddadc0077f5856de3277d600bde41f17e54 content_hash: sha256:9b57e2b93a5705388351f14294d60833325d9596cf5294d22f4a586165fc35fa
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/templates/claude-code.md value: .claude/skills/agent-author/assets/templates/claude-code.md
@@ -774,7 +856,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:eef5ee46d93b6896e880b3c4aec1121c4077a2556c6d9f4a01b322afc7b63a7e content_hash: sha256:ea0bac6e8cd91c767c6114cbcf1ecd124d03abff06ba81696dac5115499c395a
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/templates/copilot.agent.md.template value: .claude/skills/agent-author/assets/templates/copilot.agent.md.template
@@ -783,7 +865,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:1e0c0445a8908148e69baeeb44316fb370aa483e17fcd63d7f1b2d3ad1927788 content_hash: sha256:ee8b7585c808c5ff4b715be74d9e4f8c5c17d13cd603a8727cd8ca1793d14760
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/references/README.md value: .claude/skills/agent-author/references/README.md
@@ -792,7 +874,25 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:bb4cf7a34c512da33f574b208756941f396f4a1e55daaed0fad22569a22af301 content_hash: sha256:aca156b02a3f0b9fddde3cefdb24370e17cc5886dcd78adcb382699a5cc0bbaf
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/contract.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a96f0ef021a6629120e5af7c98fa483d31de92cea37f98b51528a28dee38e16a
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/create.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e4a1b95970ec44d551a4b0598f2fe01463db13a6b118981d8cd03dfc7e24f451
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/references/deployment-modes.md value: .claude/skills/agent-author/references/deployment-modes.md
@@ -801,7 +901,34 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:6cd010455e10574566ebf7cfd0926217ae5812d56a62daf4bcdb325abf3b0421 content_hash: sha256:5675f8dcd1523269d5c65be5b0e06ff4d822b158050e2fdd72b54f605485ab1f
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/improve.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:f260e91f28bbd62093b53f4efc05821eff00d086f834ddb083b70dd77ddffcaa
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/plugin-scope.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a20f8aff55c9d1c1ba5e21054b81da80618270b3b6ca5bfc37ae3c2089b4b916
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/project-user-scope.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:3f686736259402e38fed29f215b7aa5a9529fc9025005f82d0c3d439958e4e03
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/references/scripts.md value: .claude/skills/agent-author/references/scripts.md
@@ -819,7 +946,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:56965f9b660fc9a32dd71ca1039b4c6b8f932420628ddfbf3a2525e7c3336ce4 content_hash: sha256:cac8baf85a6d958ed2f0f882446dc123d14082d5ca412c8edee12c6cd1b6fdc3
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/scripts/README.md value: .claude/skills/agent-author/scripts/README.md
@@ -837,7 +964,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e917055957500a72c7f684810552ba8931781c90f96dedaabc07e899dae02a89 content_hash: sha256:1c631f5178c6c0c397d7ceefb606892dd7e330cd1b22a03c1e4d11e85fbdb7de
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agentsmd-audit value: .claude/skills/agentsmd-audit
@@ -2241,7 +2368,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:9e3533c3c44cfd249cf02684ef43db822ed41382362e8ce71f1254d10711c8e0 content_hash: sha256:78bfcfb16bbeef814b83f37a4a5185886003f9442a6d0e7e94be56f54d18d7a5
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/SKILL.md value: .claude/skills/skill-audit/SKILL.md
@@ -2250,7 +2377,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:dbe2adfd0101cf9d6b3c2c3c2aa3ae397c717f835c1059c0f1d805e9057dc397 content_hash: sha256:57a9336d409c883dc9a78aa92a9f0075fac6f8e4aac6ee8fdab705055ef85162
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/assets/vale/.vale.ini value: .claude/skills/skill-audit/assets/vale/.vale.ini
@@ -2260,6 +2387,15 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f content_hash: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
@@ -2268,7 +2404,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 content_hash: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
@@ -2304,7 +2440,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:2295d2fc72fa529f3700c21fa93516ad186a7cc66d470370173ab1a784d03d31 content_hash: sha256:f8a27d7266f4453781712f0bead151580158581a445a641613203a67a1c337d7
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/references/description-quality.md value: .claude/skills/skill-audit/references/description-quality.md
@@ -2313,7 +2449,34 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:ab077e71bbc6e9d8e2a1384bedaf613a4219f28bbe42eb9e89f933b579db6b33 content_hash: sha256:2d37eccb4889cade6cbad0deaaed6d1f5fe4c3276c5438c244b2f87ae27bf432
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/file-structure.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:b24638bd639ef048da171f6dc711e345749cde3c70ec6ba1b7fcbd696b921841
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/formatting-and-scripts.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:5c319866b2f22ba07789dae7b0813132f67196c508e8da23971307c2a9e57095
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/patterns.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:4a942ab30b95dc0cbf0fbe7da3b91157f166bce80cbd17bcf60dc365ea9237af
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/references/sources.md value: .claude/skills/skill-audit/references/sources.md
@@ -2322,7 +2485,16 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:cb65dd3cc411d7b264fab24de5cd2353dec8fbb7bbcfe2388535d963be240280 content_hash: sha256:1db16ea23884ac2db799b42d1284daaab4b24eb94f184a95fb67ddc280385934
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/validation-scripts.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:44f3b82413b57f2b5671637bb449a4c01b6d5fcd9059245aaa38e45108adf480
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/scripts/vale-wrap.sh value: .claude/skills/skill-audit/scripts/vale-wrap.sh
@@ -2349,7 +2521,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:ebbef859276135b7fe4189b31396fd98e5d4019685d7cb55e39a10fac8ca546d content_hash: sha256:7ce27df82e4160c6296db6c8314865f022da5c4334151857570a86167c8d4e11
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author value: .claude/skills/skill-author
@@ -2367,7 +2539,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:6c0b36f9b28a33de1646df45bd8e4d733ab3b26c0bdff49743962aa068085f6d content_hash: sha256:d22035d302818e103486e447bd92d2da4c9b73da60f30157941710f32f400b89
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/SKILL.md value: .claude/skills/skill-author/SKILL.md
@@ -2376,7 +2548,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:7b82d16fe0d61a71c5b59a244cf92b9b5fc2635916ad1572f4f5f6e37172bf09 content_hash: sha256:615a936580f44dd8e523496aadf88df6d512ac58369190b90407e8fca86e8345
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/assets/templates/README.md value: .claude/skills/skill-author/assets/templates/README.md
@@ -2394,7 +2566,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:f05a127963874bfbbe4333c42c5208736d84d5bf12dd8478351f6853304cc9d1 content_hash: sha256:b20c65bd185b300de7e65d16decdf0ab4aaf6c094822c1f798b3c278d52abbff
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/assets/templates/assets/README.md value: .claude/skills/skill-author/assets/templates/assets/README.md
@@ -2412,7 +2584,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:63754636f84a7841f31ab1f2854025ee449a29840ed6b9b51bcb1422ab5522d0 content_hash: sha256:e2ef117972ab2625a456ed80ff085859666d145de4e270f383cde7c8e84ad60a
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/assets/templates/references/sources.md value: .claude/skills/skill-author/assets/templates/references/sources.md
@@ -2440,6 +2612,24 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442 content_hash: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/contract.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:d350721118a2bd57094fa9151f11b48a663a1c8a04e50fba71ff2baf64b7282f
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/create.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:0837a77ad6da7ae9894134d15eebd57950b8505e8bd2b32ee69f281d65a6abcb
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/references/deployment-modes.md value: .claude/skills/skill-author/references/deployment-modes.md
@@ -2449,6 +2639,24 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759 content_hash: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/improve.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:abe029587ce475fed165d8fcfa46ea1abe83f90727d093f8121a9a7a7daa5a3d
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/retrofit.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:6c8336caa717f2abd38cb1f9c776479c0e908f7dbf577021d3689b375287dc77
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/references/scripts.md value: .claude/skills/skill-author/references/scripts.md
@@ -2466,7 +2674,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:27637acad4c0cdc7f1db15bc9cab339ebdac643e084642c58945ac2f81020c75 content_hash: sha256:652f7ce26c0d68a3ed11db09206bff20ba230ca8ff1fe71ae45b6f4505979327
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/scripts/new-skill.sh value: .claude/skills/skill-author/scripts/new-skill.sh
@@ -2475,7 +2683,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:46c6903404b9eabbd6c83892213fdabf9cad193be64613b8c1b84c8dc37e8eb2 content_hash: sha256:c788b56f73ed4fd03edb179159361fe16e3afbf528a9895e9251909c5aa40a7f
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/tdd value: .claude/skills/tdd

16
apm.yml
View File

@@ -1,5 +1,5 @@
name: holocron name: holocron
version: 0.4.2 version: 0.4.5
description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows. description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
license: MIT license: MIT
@@ -52,7 +52,7 @@ marketplace:
# top-level apm.yml description:/version: above are NOT inherited into the # top-level apm.yml description:/version: above are NOT inherited into the
# compiled output despite being used elsewhere (e.g. by `apm audit`). # compiled output despite being used elsewhere (e.g. by `apm audit`).
description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows. description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
version: 0.4.2 version: 0.4.5
owner: owner:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net
@@ -83,21 +83,21 @@ marketplace:
category: Developer Tools category: Developer Tools
- name: bin - name: bin
description: A place for things to be binned description: Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.
source: ./plugins/bin source: ./plugins/bin
version: 1.1.3 version: 1.1.5
category: Utilities category: Utilities
- name: git - name: git
description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow. description: Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.
source: ./plugins/git source: ./plugins/git
version: 1.3.3 version: 1.3.5
category: Version Control category: Version Control
- name: gitea - name: gitea
description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis. description: Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.
source: ./plugins/gitea source: ./plugins/gitea
version: 1.3.4 version: 1.3.6
category: Version Control category: Version Control
- name: core - name: core

2
docs/adr/0007-gitea-canonical-issue-tracker.md
View File

@@ -18,4 +18,4 @@ Three alternatives were rejected. Keeping the file-based fallback adds code comp
The file-based model also had a structural weakness: issues in `docs/issues/` were invisible from the Gitea UI, making it impossible to track work, assign milestones, or filter by label without opening the repo locally. Gitea provides all of that natively. The file-based model also had a structural weakness: issues in `docs/issues/` were invisible from the Gitea UI, making it impossible to track work, assign milestones, or filter by label without opening the repo locally. Gitea provides all of that natively.
The "Provider-agnostic issue tracker" glossary entry in CONTEXT.md is updated in the same workstream to remove the file-based phase framing. The `providers/gitea/` adapter path described in ADR-0011 was never implemented — Gitea integration runs entirely via MCP, not a provider adapter. The "Provider-agnostic issue tracker" glossary entry in CONTEXT.md is updated in the same workstream to remove the file-based phase framing. (Amended 2026-08-17: the CONTEXT.md trim renamed that entry to **Issue**; it still records Gitea as this repo's canonical tracker and still tells skills to say "linked issue" generically.) The `providers/gitea/` adapter path described in ADR-0011 was never implemented — Gitea integration runs entirely via MCP, not a provider adapter.

6
docs/adr/0013-vale-harness-scope-and-rule-sources.md
View File

@@ -9,6 +9,12 @@ deferred PR #85 review item to broaden that coverage, retroactively captures #84
(since it was never recorded as a decision in its own right), and layers the expansion on top (since it was never recorded as a decision in its own right), and layers the expansion on top
without reversing or weakening the original four rules. without reversing or weakening the original four rules.
**2026-08-17 amendment.** The CONTEXT.md section named above no longer holds that documentation.
CONTEXT.md was cut back to a glossary and the prefilter's mechanics — the two-copy style layout,
`vale-wrap.sh`, the `--config` argv defect, the rule inventory, and the 0-files-means-NOT-RUN
fallback — moved to `docs/spec/gates.md`. Read that file, not CONTEXT.md, for the harness itself;
this ADR still owns the scope decision.
**File scope stays the same.** `SKILL.md` plus agent files (`**/agents/*.md`, **File scope stays the same.** `SKILL.md` plus agent files (`**/agents/*.md`,
`**/*.agent.md`) only — matching the existing prefilter's globs. Skill-level `**/*.agent.md`) only — matching the existing prefilter's globs. Skill-level
`README.md` files and `plugin.json` manifests are not added: README.md files are navigational, not `README.md` files and `plugin.json` manifests are not added: README.md files are navigational, not

6
docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
View File

@@ -56,6 +56,10 @@ new hand-maintained manifest format.
that work through to merge. that work through to merge.
- `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries were rewritten in issue #90 to - `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries were rewritten in issue #90 to
describe the compiled-output model directly, rather than carrying a forward-pointer to this ADR. describe the compiled-output model directly, rather than carrying a forward-pointer to this ADR.
Superseded 2026-08-17: CONTEXT.md was cut back to one-line definitions, and the compiled-output
model is now described in `docs/spec/architecture.md`. The same trim deleted the "lint plugin"
entry cited under Considered options below; that pointer now reads `docs/spec/architecture.md`'s
plugin scope table, which carries the repo-agnostic-versus-marketplace-specific argument.
## Considered options ## Considered options
@@ -66,7 +70,7 @@ maintenance in place unchanged.
**New standalone `plugins/apm/` plugin (rejected).** `plugins/lint/` was split out of `kyberforge` **New standalone `plugins/apm/` plugin (rejected).** `plugins/lint/` was split out of `kyberforge`
specifically because Vale tooling is generic and repo-agnostic, not holocron-marketplace-specific specifically because Vale tooling is generic and repo-agnostic, not holocron-marketplace-specific
(see `CONTEXT.md`'s "lint plugin" entry) — the same argument applies to a generic `apm` CLI (see `docs/spec/architecture.md`'s plugin scope table) — the same argument applies to a generic `apm` CLI
wrapper. The shipped `apm-install`/`apm-workflow` skills are, in fact, generic, repo-agnostic APM wrapper. The shipped `apm-install`/`apm-workflow` skills are, in fact, generic, repo-agnostic APM
CLI documentation with no holocron-specific content, so a standalone `plugins/apm/` would have CLI documentation with no holocron-specific content, so a standalone `plugins/apm/` would have
been a defensible split on artifact content alone. Rejected anyway, in favor of `kyberforge`, been a defensible split on artifact content alone. Rejected anyway, in favor of `kyberforge`,

4
docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md
View File

@@ -329,7 +329,9 @@ mirror does carry, and is reported.
stands; this ADR fixes the second, previously-unverified half. stands; this ADR fixes the second, previously-unverified half.
- `CONTEXT.md`'s "Plugin" and "Plugin marketplace" glossary entries are updated to describe the - `CONTEXT.md`'s "Plugin" and "Plugin marketplace" glossary entries are updated to describe the
flat mirror as a second compiled-output category, alongside the existing flat mirror as a second compiled-output category, alongside the existing
`.claude-plugin/plugin.json`/`marketplace.json` description. `.claude-plugin/plugin.json`/`marketplace.json` description. Superseded 2026-08-17: CONTEXT.md was
cut back to one-line definitions and no longer describes either compiled-output category;
`docs/spec/architecture.md` is where the mirror is documented.
- A future apm release that ships a native `.apm/`-aware plugin.json compiler (closing this gap - A future apm release that ships a native `.apm/`-aware plugin.json compiler (closing this gap
upstream) would let `sync-plugin-content.sh` and its drift gate be deleted outright — nothing in upstream) would let `sync-plugin-content.sh` and its drift gate be deleted outright — nothing in
this ADR's decision depends on the flat mirror existing beyond satisfying the current installer's this ADR's decision depends on the flat mirror existing beyond satisfying the current installer's

27
docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md
View File

@@ -59,7 +59,9 @@ answers to `git-commits` and `kyberforge:skill-audit` to `skill-audit`. This is
a project skill has no plugin to prefix. `AGENTS.md` and `CONTEXT.md` are updated to name the bare a project skill has no plugin to prefix. `AGENTS.md` and `CONTEXT.md` are updated to name the bare
form, which is what apm deploys and the only form a repo consuming holocron through apm gets. form, which is what apm deploys and the only form a repo consuming holocron through apm gets.
**Correction (2026-08-14): the namespaced form did not stop resolving.** An earlier revision of **Correction (2026-08-14): the namespaced form did not stop resolving.** *Superseded by the
2026-08-17 correction below: the machine state this cites is no longer present. Both are kept
because the pair is the finding — read neither as current.* An earlier revision of
this consequence said every `<plugin>:<skill>` reference "was stale the moment the switch landed", this consequence said every `<plugin>:<skill>` reference "was stale the moment the switch landed",
and `AGENTS.md`/`CONTEXT.md` were written to match. That contradicts the "User scope is untouched, and `AGENTS.md`/`CONTEXT.md` were written to match. That contradicts the "User scope is untouched,
deliberately" consequence below, and the contradiction resolves against it: `~/.claude.json` still deliberately" consequence below, and the contradiction resolves against it: `~/.claude.json` still
@@ -72,6 +74,20 @@ survives those user-scope installs eventually being converted, and the namespace
resolves for anyone installing holocron natively, so skill bodies written for both audiences resolves for anyone installing holocron natively, so skill bodies written for both audiences
should name the bare skill. should name the bare skill.
**Correction (2026-08-17): the evidence under the correction above is gone, and the claim goes with
it — not to its opposite.** Observed on this machine: `~/.claude/plugins/installed_plugins.json` is
`{"version": 2, "plugins": {}}`; there is no `enabledPlugins` key anywhere in `~/.claude.json`
(`grep -c enabledPlugins` returns 0); `~/.apm/marketplaces.json` is `{"marketplaces": []}`. The
`holocron` entry in `~/.claude/plugins/known_marketplaces.json` survives, but a registered
marketplace is not an installed plugin. So the user-scope installs the 2026-08-14 correction cited
are not there, and neither is the state the *original* consequence described before it. The claim
about the namespaced form has now been written twice off two different observations of the same
machine, and this ADR has already reversed itself once on it. That is the finding: the fact is
machine state, not a property of this decision, and it changes without any commit. No instruction
file — `AGENTS.md`, `CONTEXT.md`, or a skill body — should assert either way whether
`<plugin>:<skill>` resolves. The rule that survives every observation is the one that was always the
actionable half: write the bare name, because it is the only form `apm install` produces.
**apm owns `.claude/settings.json`.** (ADR-0019 supersedes the "exactly `{"hooks": {}}`" claim **apm owns `.claude/settings.json`.** (ADR-0019 supersedes the "exactly `{"hooks": {}}`" claim
below — once a package ships a hook, apm merges it into that file and the merged entry is apm's own below — once a package ships a hook, apm merges it into that file and the merged entry is apm's own
output. The rule that nothing repo-authored goes in the file is unchanged.) `apm audit --ci` replays the install into a scratch tree and output. The rule that nothing repo-authored goes in the file is unchanged.) `apm audit --ci` replays the install into a scratch tree and
@@ -117,10 +133,11 @@ pinned `resolved_commit` in `apm.lock.yaml` and does not re-resolve refs (`apm i
documents this explicitly — "does NOT refresh refs; use 'apm update' for that"). Running it after a documents this explicitly — "does NOT refresh refs; use 'apm update' for that"). Running it after a
merge redeploys the same content and reports success. merge redeploys the same content and reports success.
**User scope is untouched, deliberately.** `bin@holocron`, `gitea@holocron`, and a stale **User scope is untouched, deliberately.** This decision changed project scope only; whatever is
`hello-world@holocron` remain natively installed at user scope, and every project other than this natively installed at user scope was left alone, and converting it is a separate decision with a
one still resolves its skills that way. Converting them is a separate decision with a blast radius blast radius beyond this repo. The specific inventory this paragraph used to name
beyond this repo. (`bin@holocron`, `gitea@holocron`, a stale `hello-world@holocron`) is machine state and is stale —
see the 2026-08-17 correction above. The decision recorded here is unaffected by what that state is.
## Alternatives considered ## Alternatives considered

26
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 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 `<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 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 monorepo means. Deployed `.claude/`/`.agents/` trees are consulted **only** when the walk found no
exists — the consumer case, where there is no monorepo to read. What the resolver must never do is 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 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 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 routing to `skill-audit` resolved against a plugin it had never installed. Checked
@@ -125,6 +129,24 @@ clause**, and a **boundary clause**. Capability enumeration, output-format detai
dependency, and none needs to. Verified: a tree holding only `plugins/` and the root `apm.yml`, dependency, and none needs to. Verified: a tree holding only `plugins/` and the root `apm.yml`,
with no `.claude/` or `.agents/` anywhere, now produces findings identical to the working tree — with no `.claude/` or `.agents/` anywhere, now produces findings identical to the working tree —
26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs. 26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs.
- **The universe is the apm marketplace, and nothing else.** A routing target resolves to a skill or
an agent, or it does not resolve. Host built-ins are deliberately outside it: `/compact`, `/clear`
and `/init` are Claude Code slash commands with no counterpart in Copilot CLI or Codex, so a
vendor-neutral `.apm/` description routing to one is a portability defect and the hard FAIL is a
true positive, not a false one. An allowlist of known built-ins was **rejected**: it answers a
different question ("does this exist on *some* host?"), it cannot answer that portably from a
single source file, and it goes stale the next time a host ships a command — reintroducing the
same-commit-two-verdicts failure the bullet above exists to close. An author who needs to mention
one writes it un-slashed (``the `compact` built-in``), which is not route notation and makes no
routing claim.
- **Blocking is scoped to a sentence, which makes sentence boundaries load-bearing.** A prose-form
target earns a hard error only when its own sentence names another target that *resolves*; route
notation (`/name`, `→ name`) is exempt and always blocks. So the splitter is part of the contract,
not a detail of it. `e.g. "…"` is not a sentence end, and a sentence opening with a code span or a
lowercase skill name is a start; getting either wrong moves targets between the two tiers in
opposite directions — a stranded corroborator silently demotes a real finding to SUGGESTION, and a
missed boundary lets one sentence vouch for a target it never stood beside, producing a hard FAIL
with no escape hatch.
- **The blanket pushiness rules are deleted.** `skill-author/SKILL.md:104` and - **The blanket pushiness rules are deleted.** `skill-author/SKILL.md:104` and
`description-quality.md:21` are replaced by a conditional: add an indirect trigger only where the `description-quality.md:21` are replaced by a conditional: add an indirect trigger only where the
user's natural phrasing genuinely omits the domain word — true for the `gitea-*` family, false for user's natural phrasing genuinely omits the domain word — true for the `gitea-*` family, false for

227
docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md Normal file
View File

@@ -0,0 +1,227 @@
# A plugin's published description states its domain boundary and never enumerates its skills
Three of this repo's six plugins publish a `description` that lists the skills they ship. That style
has now failed three times in four days, the third time inside the correction for the second. It is
enforced by nothing, it obliges a marketplace release on every skill addition, and it was never
applied to the other three plugins. This ADR retires it: a published description says what the
plugin is *for*, and the inventory lives where an inventory can be read off the tree.
**Status: accepted (2026-08-17).**
## Context
A plugin's published description is one string authored twice — in `plugins/<name>/apm.yml` and in
the matching `marketplace.packages[]` entry of the root `apm.yml` — and compiled into four generated
files per plugin edit: the plugin's `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`,
plus the repo-wide `.claude-plugin/marketplace.json` and its `.github/plugin/marketplace.json`
mirror. (`.agents/plugins/marketplace.json`, apm's codex profile, carries no per-package
`description` or `version` at all and is unaffected.) It is the only text a consumer sees in a marketplace listing before
installing. It is **not** a SKILL.md `description`: it is never preloaded into an agent's context and
routes nothing at runtime. ADR-0020 governs that other artifact; this one governs this one. The
overlap is a finding, not a scope: ADR-0020 established that capability enumeration in a description
is "a correctness hazard, not only a token cost". The hazard at this layer is different — staleness
in published metadata rather than an agent shortcutting the body — but the enumeration is the same
construct and it fails the same way.
Measured at `de84d1b`, the branch tip before this change. Each figure is reproducible from the tree:
skill counts are `ls plugins/<name>/.apm/skills/ | wc -l`, description text is
`plugins/<name>/apm.yml`.
| Plugin | Style | Skills | Items enumerated | Skills named | Unnamed |
|---|---|---|---|---|---|
| `bin` | enumeration | 11 | 8 | 9 | `caveman`, `zoom-out` |
| `git` | enumeration | 9 | 8 | 8 | `git-workflow` |
| `gitea` | enumeration | 7 | 7 | 6 | `gitea-workflow` |
| `core` | boundary | 3 | — | — | — |
| `kyberforge` | boundary | 7 | — | — | — |
| `lint` | boundary | 2 | — | — | — |
Three failures, in order.
**`bb9158d` (2026-08-14) — `core`'s description described `bin`.** The text it deleted read
"Cross-cutting utility skills for everyday AI-assisted coding — triage, diagnosis, architecture
review, and session navigation." All four items are real skills and not one of them is `core`'s:
they are `bin`'s `triage`, `diagnose`, `improve-codebase-architecture` and `zoom-out`. `core` ships
`agentsmd-author`, `agentsmd-audit` and `provider-adapter-author`, and the published description
named none of them.
This is the failure the whole style was later adopted against, and it is worth being exact about
what it was, because the record has been read the other way twice since. It was **wrong content**,
not an incomplete list. The description was a syntactically perfect, complete, four-item enumeration
of a real skill set; it just belonged to a different plugin. Enumerating harder could not have caught
it, and a gate that asked "does every enumerated item exist as a skill?" would have passed it — all
four did exist. `bb9158d`'s own fix went the other direction: it replaced the enumeration with a
domain boundary, and `core` has needed no correction since. The precedent set by that commit was
therefore *boundary*, and the two commits below cite it while doing the opposite.
**`65bac15` (2026-08-17) — `git` advertised `gitea`'s domain, `gitea` advertised a skill that does
not exist.** `git` read "conventional commits, branch management, pull requests, and feature flow";
pull requests reach the forge over HTTP and are `gitea`'s, which is the exact boundary
`docs/spec/architecture.md` draws between the two plugins. `gitea` read "issues, pull requests,
milestones, releases, and wikis"; `grep -ri wiki plugins/gitea/.apm/` returns nothing and no wiki
skill has ever existed. Both were repaired by re-enumerating.
**`de84d1b` (2026-08-17) — the re-enumeration was itself incomplete.** `bin`'s "A place for things to
be binned" was replaced with an eight-item list over eleven skills; `caveman` and `zoom-out` are
absent. `zoom-out` is the same skill `bb9158d` had called "session navigation" three days earlier
while deleting it from the wrong plugin's description — named when it was in the wrong place,
unnamed once it was in the right one. And the miss is not confined to `bin`: `git-workflow` is
unnamed in `git`'s corrected description, though `65bac15`'s own commit message states it was added
("omitting pc-author/pc-run, git-submodules and git-workflow"), and `gitea-workflow` is unnamed in
`gitea`'s. Across the three plugins, 23 of 27 skills are named at the third attempt.
**Nothing checks any of this.** `scripts/check-manifests.sh` does not contain the string
`description`. The three ADR-0020 validators (`scripts/skill-size-check.sh` and skill-audit's and
agent-audit's `validate.sh`) gate on SKILL.md and agent frontmatter; they do open `apm.yml`, but only
to read `dependencies.apm` when resolving the boundary-target universe — none of them reads the
`description:` key, and their hook globs match `SKILL.md` and `*.agent.md` only. `apm audit --ci`,
`apm pack --check-clean` and `scripts/sync-plugin-content.sh --check --all` all compare compiled
output against `apm.yml`, so their entire job is to propagate whatever the description says into
those four files byte-for-byte and confirm they match. The `wiki` claim passed every one of the fourteen pre-push hooks, every day it
was published.
**And the obligation is unbounded.** Under enumeration, adding one skill to `bin`, `git` or `gitea`
means editing two copies of a prose string on top of the version bumps and regeneration any skill
addition already owes under this repo's release policy
(`plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md`). The bumps are not the
marginal cost — the prose edit is, and it is the half nothing checks. A skill *rename* triggers the
same, for a string no consumer can tell went stale. 27 of the repo's 39 skills sat behind
a description carrying that obligation; the other 12 did not, and their three plugins have generated
no defect of this class.
### Scope
This decision covers the six plugins this repo authors. The root marketplace also lists
`mattpocock-skills`, a third-party package whose description is not this repo's to write; its entry
is out of scope and is left as published upstream.
## Decision
**A plugin's published `description` states the plugin's domain boundary. It does not enumerate the
skills the plugin ships, by name or by paraphrase.**
- The boundary answers "what kind of work belongs to this plugin, and where is its edge against its
nearest sibling" — the question a consumer deciding whether to install is actually asking. It is
stable under skill addition, rename and removal, which is the entire point: an artifact that does
not change when the tree changes cannot go stale against it.
- **The boundary must cover everything the plugin actually ships.** A boundary drawn narrower than
the contents is the same defect as an incomplete enumeration, one level up, and it is the specific
risk in this change. `git` carries `pc-author` and `pc-run`, which are not git operations at all;
"Skills for working with Git" silently drops them, so the boundary names the pre-commit hooks
explicitly rather than trusting a reader to file them under Git.
- The two copies — package `apm.yml` and the root `marketplace.packages[]` entry — stay identical.
This is already the rule in practice and both prior corrections state why: the root entry is what
reaches the compiled marketplace, so fixing only the package manifest leaves it half-propagated.
- The three descriptions, rewritten here, with `core`/`kyberforge`/`lint` shown for register:
| Plugin | Published description | Chars |
|---|---|---|
| `bin` | Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin. | 152 |
| `git` | Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it. | 146 |
| `gitea` | Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone. | 134 |
| `core` | *(unchanged)* Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it. | 101 |
| `kyberforge` | *(unchanged)* Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace. | 105 |
| `lint` | *(unchanged)* Skills and agents for configuring and running linters. | 54 |
- **No gate is added.** This is a deliberate omission and the reasoning is below, not an item left
for later.
### Why no gate
The check enumeration would need — "every skill directory appears in the description" — was writable
in principle and was never written, including by the two commits that corrected an enumeration by
enumerating again and had every reason to. It is also only half a check: it
catches a skill missing from the list, and it cannot catch `wiki`, because "this noun does not name
any skill" requires a vocabulary of permissible non-skill nouns that no one is going to maintain.
Under a boundary there is no correspondence left to check, which is the property being bought.
What survives un-gated is `bb9158d`'s actual failure: a boundary that is simply wrong about its
plugin. That was never machine-checkable in either style — the text was a well-formed description of
a real plugin — and it is caught by the same review that has to happen when a published,
consumer-facing string is edited at all. A gate that would catch it needs a declared per-plugin
skill-to-boundary mapping for the description to be checked against, which is a second artifact
requiring exactly the per-skill maintenance this ADR exists to delete, relocated one file over.
Two cheap partial gates were considered and rejected in the same breath. Forbidding a comma-separated
run of three or more noun phrases is a prose heuristic that fires on `lint`'s perfectly good
"configuring and running linters" class of sentence. Forbidding any string matching a skill directory
name under `plugins/<name>/.apm/skills/` bans legitimate boundary vocabulary — `git-branches` exists,
and a `git` boundary has every right to say "branches". Both would be believed, and both would be
wrong, which ADR-0020 already records as worse than no gate.
## Considered options
**Keep enumeration and gate it.** The only option that makes the current style safe. Rejected on the
three grounds above: the check is one-directional, it cannot see an invented capability, and it makes
a marketplace release the consequence of adding a directory. It also hard-couples published consumer
copy to internal directory names, so a skill rename becomes a version bump on the plugin and on the
marketplace.
**Enumerate consistently across all six plugins**, on the grounds that the real defect is the split
style. Rejected: it takes an obligation that has produced three failures on three plugins and applies
it to six. The measured outcome of the most recent attempt to enumerate carefully, with the defect
fresh and two prior commits as precedent, is four skills unnamed.
**Cap the description length**, mirroring ADR-0020's 250/400-character tiers, on the theory that a
short description has no room to enumerate. Rejected because length does not measure correspondence:
`gitea`'s failing description was 96 characters and asserted a skill that has never existed, while
`bin`'s 176-character enumeration is under the same cap. All six descriptions here, before and after,
sit inside ADR-0020's tiers; the tier would have been silent through all three failures.
**Delete the description to a bare name.** Rejected: apm's Claude marketplace mapper emits
`description` into `marketplace.json`, and it is the only prose a consumer sees before installing.
**Point the description at the plugin's `README.md`.** Rejected: a marketplace listing renders a
string, not a link — and the README's own plugin list carries the same enumeration with the same
staleness, so this relocates the defect rather than fixing it.
## Consequences
**Three descriptions are rewritten and the compiled output regenerated.** Eight generated files
change: `plugins/{bin,git,gitea}/.claude-plugin/plugin.json`,
`plugins/{bin,git,gitea}/.github/plugin/plugin.json`, `.claude-plugin/marketplace.json` and its
byte-identical `.github/plugin/marketplace.json` mirror. `.agents/plugins/marketplace.json` (the
codex profile) is unchanged and correctly so — it carries no per-package `description` or `version`
field at all, only `name`, `source`, `policy` and `category`.
**Version bumps, all PATCH under the `per_package` strategy:** `bin` 1.1.4 → 1.1.5, `git` 1.3.4 →
1.3.5, `gitea` 1.3.5 → 1.3.6, `marketplace.version` 0.4.4 → 0.4.5.
**The root `apm.yml` top-level `version:` is restored to lockstep with `marketplace.version`,
0.4.2 → 0.4.5.** These two fields have moved together in every commit that has ever touched root
`apm.yml` — 0.3.2, 0.3.3, 0.3.4, 0.4.0, 0.4.1, 0.4.2 in both — until `65bac15` and
`de84d1b` on this branch bumped `marketplace.version` to 0.4.3 and then 0.4.4 while leaving the
top-level field at 0.4.2. Lockstep is not folklore: it is stated at
`plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md`. This is a defect, not a
style: `apm.yml`'s comment inside the marketplace block records that the top-level `version:` is not inherited into the compiled output
"despite being used elsewhere (e.g. by `apm audit`)", so the field is live and was silently two
releases behind what the marketplace published. Closed here rather than tracked, because the
correction is one line and the drift is three days old.
**`docs/spec/architecture.md`'s plugin table is unchanged and stays a routing table.** It answers
"where does a new skill go" for someone working *inside* this repo; the published description answers
"should I install this" for someone outside it. The two now read similarly, and that is not
duplication to collapse — they have different readers and different lifecycles, and the table already
says so in its own preamble ("These are routing boundaries, not inventories"). One caveat for whoever
next edits that page: its closing sentence sends a reader to the published description "for what a
consumer actually gets", which was true against an enumeration and is now a pointer to a second
boundary statement. Neither artifact carries an inventory after this change, so that sentence was
rewritten in the same branch to point at `plugins/<name>/.apm/skills/` and `README.md` instead.
**`README.md`'s plugin bullet list becomes the only place an inventory lives, and it still
enumerates.** That is deliberate, but it makes the list load-bearing in a way it was not before, so
its `bin`, `git` and `gitea` bullets were completed in the same branch to name every skill those
plugins ship. This ADR does not otherwise extend to it: a README is a hand-read document where a
list of what you get is the useful thing, it is not compiled into four files, and a stale line in it
costs a reader a moment rather than misrepresenting a published package. The tradeoff that makes
enumeration wrong in a marketplace manifest is precisely the one that makes it fine there.
**Nothing in the ADR-0020 gate set changes.** Its character and word tiers, its Vale rules and its
three validators all read `SKILL.md` and `*.agent.md` frontmatter; none of them opens an `apm.yml`.
The two contracts are adjacent and independent, and a future author retrofitting a skill under
issue #99 is not touched by this ADR.
**The failure mode this leaves open is a wrong boundary, and it is un-gated by design.** If a fourth
failure of this class occurs it will be a description that describes the wrong plugin — `bb9158d`'s
shape, the one enumeration never addressed. That is the trigger to revisit, and the thing to build
then is a declared skill-to-boundary mapping, not a return to enumeration.

27
docs/spec/architecture.md
View File

@@ -21,11 +21,26 @@ project repo (local overrides)
Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately — in this repo by `apm install` against the `dependencies.apm` entries in the root `apm.yml`, which lands them in `.claude/skills/` and `.claude/agents/` (ADR-0018); elsewhere by `claude plugin install <name>@holocron`. Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately — in this repo by `apm install` against the `dependencies.apm` entries in the root `apm.yml`, which lands them in `.claude/skills/` and `.claude/agents/` (ADR-0018); elsewhere by `claude plugin install <name>@holocron`.
`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication. `~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance) and carries nothing else — the content index of on-demand instruction files sits in `core/AGENTS.md`, deployed to `~/.agents/AGENTS.md` and imported by it. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
## Plugin model ## Plugin model
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source. Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source.
Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is `core` vs `kyberforge`: `core` is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against *their* repo, while `kyberforge` is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's `AGENTS.md` is `core`; a skill that audits a `SKILL.md` against this marketplace's contract is `kyberforge`.
The second boundary worth stating is `git` vs `gitea`, because both own things called branches and both touch pull requests: `git` is whatever works over the git wire protocol against a local clone, `gitea` is whatever goes through the forge's HTTP API. That is why `git-branches` and `gitea-branches` both exist and are not duplicates.
These are routing boundaries, not inventories — they answer "where does a new skill go", so they deliberately do not enumerate what each plugin ships today. The plugin's published `description` in its `apm.yml` states the same boundary for a consumer deciding whether to install (ADR-0021); neither carries an inventory. For what a plugin ships today, read `plugins/<name>/.apm/skills/` or the plugin list in `README.md`.
| Plugin | Scope |
|---|---|
| `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it |
| `git` | Git operations and git hook tooling — anything driven over the git wire protocol against a local clone, plus the pre-commit hooks that guard it |
| `gitea` | Anything reached through the Gitea HTTP API rather than the git wire protocol — the forge's own objects |
| `kyberforge` | Creating and maintaining a Claude Code / Copilot CLI plugin marketplace — this repo's own meta-tooling |
| `lint` | Configuring and running linters against a target repo; repo-agnostic, first linter is Vale |
| `bin` | Unsorted skills that have not earned a home yet |
Two compilers produce the plugin roots you see in the tree: Two compilers produce the plugin roots you see in the tree:
@@ -40,6 +55,8 @@ That immunity is positional, not by filename. Anything placed *inside* a mirrore
`core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins. `core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins.
Those on-demand files are plain markdown — no frontmatter, no schema. The agent decides when to read each one from task context and the content index label alone. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice; it is a deliberate deferral, not an oversight to close.
The governance layer has two phases: The governance layer has two phases:
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language. - **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
- **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`. - **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
@@ -57,10 +74,14 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
`CONTEXT.md` is therefore **not** always-loaded. `AGENTS.md` instructs agents to read it at session start, which is a behavioural instruction, not an `@import` guarantee — `LESSONS.md`'s 2026-05-17 entry proposed adding the import and it was never applied. Treat that entry as open work rather than a record of a landed change. `CONTEXT.md` is therefore **not** always-loaded. `AGENTS.md` instructs agents to read it at session start, which is a behavioural instruction, not an `@import` guarantee — `LESSONS.md`'s 2026-05-17 entry proposed adding the import and it was never applied. Treat that entry as open work rather than a record of a landed change.
## Reference conventions
The stated convention is that files referencing other files declare those references explicitly: the referencing file carries the forward reference (the content index in `core/AGENTS.md`, `references:` in frontmatter), the referenced file carries a `when:` field describing when it is loaded, and divergence between the two signals staleness. It is aspirational, not a description of the repo today — no file under `core/instructions/` carries frontmatter at all, `when:` appears in exactly one of the 39 `SKILL.md` sources under `plugins/*/.apm/skills/`, and the reference scanner script meant to derive the reverse map ("what files reference this file?") does not exist; `docs/notes/skill-implementation-workflow.md` still lists it as unbuilt work. Treat it as intent for instruction files, skills, and workflow documents, not as a rule the repo enforces.
## Provider model ## Provider model
`core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change. `core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change.
## Architectural decisions ## Architectural decisions
Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds 19 numbered ADRs whose filenames state their decision, so `ls docs/adr/` is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, ADR-0017 corrects ADR-0015's host-discovery gap, and ADR-0019 supersedes one claim in ADR-0018 (that `.claude/settings.json`'s committed content is exactly `{"hooks": {}}`) while keeping the rule behind it. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots). Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds numbered ADRs whose filenames state their decision, so `ls docs/adr/` is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, ADR-0017 corrects ADR-0015's host-discovery gap, and ADR-0019 supersedes one claim in ADR-0018 (that `.claude/settings.json`'s committed content is exactly `{"hooks": {}}`) while keeping the rule behind it. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots).

689
docs/spec/gates.md Normal file
View File

@@ -0,0 +1,689 @@
# Enforcement gates
Reference for this repo's pre-commit and pre-push hooks: what each one guards, what its numbers
mean, and which shapes were tried and rejected. Read it when a gate fails, before changing anything
in `.pre-commit-config.yaml`, or before "fixing" something that looks like an inconsistency — several
of the oddities documented here are load-bearing and have already been re-litigated once.
`AGENTS.md` carries only the operative rules an agent needs in the moment. The reasoning lives here.
---
## Running the gates
| Command | Scope |
|---|---|
| `pre-commit run --all-files` | the commit-stage hooks |
| `pre-commit run --hook-stage pre-push --all-files` | the push gate, one command — with one caveat below |
| `pre-commit run skill-size-check --all-files` | just the ADR-0020 size/context gates |
Install hooks via `pc-run`, wiring **all three stages**. This repo's `.pre-commit-config.yaml` has no
`default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits)
and `pre-push` (everything below).
The pre-push command reports **16** hooks, not 14. The extra two are pre-commit's own `meta` hooks,
`check-hooks-apply` and `check-useless-excludes`: they declare no `stages:`, so they run at every
stage including this one. Both are declared in this repo's `.pre-commit-config.yaml` like everything
else — what separates them is `repo: meta` (pre-commit's own built-ins) from `repo: local`. Fourteen
is the count of hooks this repo authors itself.
**The caveat: one of those 14 is a silent no-op under that invocation.**
`check-release-needed` exits 0 immediately unless `PRE_COMMIT_REMOTE_BRANCH` equals
`refs/heads/main`, and pre-commit exports that variable only from the real pre-push git hook during
an actual `git push`. Running the stage by hand — or from a CI runner — therefore reports it
`Passed` having checked nothing. That is by design for feature branches — pushing WIP must not be
blocked on cutting a premature tag — but it means `--hook-stage pre-push --all-files` is a full
rehearsal of 13 hooks and a skip of the fourteenth. The script's own header records the same gap for
a PR merged through Gitea's merge button, where no local push happens at all.
## The pre-push gate
Fourteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
**Core checks**
| Hook | Guards |
|---|---|
| `run-tests` | `bash tests/run-tests.sh --strict` — the whole suite, skips fatal (see [Tests](#tests)) |
| `check-manifests` | `marketplace.json` and `plugin.json` paths resolve (needs `jq`) |
**Generated-content drift gates**
| Hook | Guards |
|---|---|
| `check-plugin-content-sync` | each plugin's flat `skills/agents/commands/hooks` mirror matches `.apm/` (issue #90) |
| `check-marketplace-mirror-sync` | `.github/plugin/marketplace.json` is byte-identical to `.claude-plugin/marketplace.json` — no apm output profile targets that path |
| `check-vale-style-sync` | skill-audit's Vale copy matches agent-audit's canonical copy, plus six glob-coverage probes (see [Vale](#vale)) |
| `check-scope-walkup-sync` | `validate.sh`, `validate-provenance.sh`, `new-agent.sh` and `new-skill.sh`'s four independent `$HOME`/`.git`/`apm.yml` walk-up ports still agree behaviorally |
| `check-executables-allow-sync` | root `apm.yml`'s `executables.allow` key names kyberforge's actual version (see [apm gates](#apm-gates)) |
`check-executables-allow-sync` is the odd one in this group: it guards a *silent failure* rather than
drift in generated text.
**Artifact validators**
| Hook | Guards |
|---|---|
| `check-apm-agents-valid` | runs agent-audit's `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md` (see [Agent files](#agent-files-take-the-description-gates-not-the-body-gate)) |
**apm's own gates**
| Hook | Guards |
|---|---|
| `apm-marketplace-check` | every `marketplace.packages[]` entry resolves, including network reachability of remote refs |
| `apm-audit-ci` | `apm audit --ci` once per manifest — root plus each of the six plugin packages |
| `apm-pack-check-clean` | `apm pack --check-versions --check-clean --dry-run` — the compiled marketplace still matches what `apm.yml` + `.apm/` would generate, and per-package versions agree with the `per_package` strategy |
**Host validators** (both need the `claude` CLI on PATH)
| Hook | Guards |
|---|---|
| `validate-plugins` | `claude plugin validate --strict` on every plugin directory |
| `validate-marketplace` | `claude plugin validate --strict` on the root marketplace manifest |
**Release**
| Hook | Guards |
|---|---|
| `check-release-needed` | on a real `git push` to `main` only — fails if files exposed via `.pre-commit-hooks.yaml` changed since the last tag. A no-op everywhere else, including under `pre-commit run --hook-stage pre-push` (see [the caveat above](#running-the-gates)) |
Four of these shell out to `apm`: `apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`,
and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wraps `apm pack`). The
first and third are bare `apm …` entries and the second is a `bash -c` loop calling `apm` once per
package, so without the CLI the push dies with an unhelpful "command not found". Install with
`apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`. `jq` is
needed by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh` — those at least fail
loudly (`Error: jq is required but not installed`).
## Skill and agent context gates (ADR-0020)
The `skill-size-check` pre-commit hook, scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$`,
runs `scripts/skill-size-check.sh`. That scope means it never lints the
`plugins/kyberforge/docs/research/examples/` reference skills. It is also shipped to external repos
as `kyberforge-skill-size-check` (see
[External consumers](#external-consumers-the-root-pre-commit-hooksyaml)).
### Two independent gate families, neither replaced the other
**Family 1 — agentskills.io spec backstop** (unchanged, conformance not quality):
| Constant | Value | Measured over |
|---|---|---|
| `MAX_LINES` | 500 | whole file, **frontmatter included** |
| `MAX_WORDS` | 2,770 | whole file, **frontmatter included** |
**Family 2 — ADR-0020 context budget** (measured differently, on purpose):
| Check | SUGGESTION | FAIL | Measured over |
|---|---|---|---|
| `description` characters | 250 | 400 | the YAML-**folded** value |
| body words | 600 | 900 | **body only** — everything after the frontmatter's closing `---` |
Plus two hard FAILs with no suggestion tier:
- **A missing, valueless or `null` `description:`.** Not a skip. The description is the one field
preloaded into every session, so a gate that declines to measure it reports green. (This is not
hypothetical: `description:` with no value followed by `model: sonnet` let a line regex capture the
*next* key, which looked non-empty, so the "missing or empty" branch never fired and every gate
below early-returned on the genuinely empty folded value — exit 0, zero output, on a blocking gate.)
- **Every `references/<file>.md` a body names must exist** on disk. A dispatch table pointing at a
file that was never written is a silently dead branch, and nothing else in the gate/audit/vale
stack notices it.
A file can sit well inside one family and fail the other. 2,770 whole-file words is a conformance
backstop; 900 body-only words is a quality gate. Conflating them is what produced the current state.
### An unresolved routing target is not automatically a FAIL
A boundary-clause target that resolves to no skill or agent has **three** possible verdicts, not one
(`unresolved_targets()` in `scripts/skill-size-check.sh`):
| Verdict | When |
|---|---|
| **SUGGESTION** — the default | the target does not resolve and neither promotion condition below holds |
| **blocking ERROR** | the target is **terminal** (not a compound modifier) **and** either written in route notation (`/name` for any name; `-> name` only when the name is hyphenated — see the gap below) **or** corroborated by another target in the same sentence that *does* resolve |
| **INFO, "DID NOT RUN"** | no skill universe could be determined for the path at all — the targets are named and left unchecked, exit 0 |
The default is deliberately soft because a hyphenated word in a boundary clause is as likely to be a
tool, a file format or an English compound as a route: "pre-commit hooks" is prose about a tool and
never reaches the check at all, being a compound modifier rather than a terminal name. The
SUGGESTION text says how to opt in — write it as `/name` or `-> name` and it gets checked properly.
**Known gap: the arrow form only works for hyphenated names.** Target extraction is built on
`NAME_HYPH` (`scripts/skill-size-check.sh:543`), which requires at least one hyphen, and
`ARROW_BOUNDARY` (`:561`) inherits that. So `-> gitea-prs` is extracted and checked, while
`-> triage` is not extracted at all — no ERROR, no SUGGESTION, exit 0. The unicode arrow `→` is not
recognised in either case. This makes the SUGGESTION's own advice unsafe for a single-word skill:
taking it silences the finding rather than checking it. `/name` has no such restriction and is the
form to prefer. Tracked as a defect; `tests/test-adr0020-targets.sh` has one arrow case and its
target happens to be hyphenated, so nothing currently covers this.
Corroboration is what makes the soft default safe: a sentence whose *other* target resolves is
demonstrably a routing sentence, so a sibling that does not resolve is a typo rather than a noun, and
gets promoted.
### Target resolution walk
Resolution walks up **from the file being checked** — never from the script's own location. Deriving
it from `${BASH_SOURCE}` leaked holocron'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.
The walk finds an **authoring root**: the nearest ancestor holding `plugins/*/.apm/skills` or
`plugins/*/.apm/agents`, falling back to the nearest ancestor holding `.git`. **Two passes, not one
interleaved walk**, so a nested `.git` (a submodule, a sub-package worktree) cannot beat a real
monorepo root further up.
The universe is then:
1. every skill and agent under `<root>/plugins/*/` — sibling plugins resolve, which is what a
monorepo means;
2. the checked file's own apm package;
3. the packages that package declares in **its own** `apm.yml` `dependencies.apm`.
The **root** manifest's `dependencies:` block is not read, and no plugin here declares a cross-plugin
apm dependency — none needs to.
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.
**The gate keys on which of the two passes matched, never on whether the root contributed a new
name.** A name-count delta looks equivalent and is not: `_collect_authoring_root()` re-collects the
checked file's own plugin, whose names the earlier steps already added, so a single-plugin monorepo
shows a delta of zero and would wrongly reach for the deployed trees — including the user's global
`~/.claude/skills`, making the verdict depend on what happens to be installed.
Why it matters: those trees are gitignored `apm install` output, present only on a machine that has
run it. Four cross-plugin targets here (`gitea-branches` → `git-branches`, `gitea-branches` →
`git-history`, `gitea-issues` → `git-branches`, `gitea-workflow` → `git-workflow`) once resolved
through `.claude/skills/` alone, so **the same commit measured 2 dangling targets on a developer
machine and 6 on a fresh clone**. A gate shipping hot with no baseline cannot give two answers.
Verified fixed: running the hook over a tree holding only `plugins/` and the root `apm.yml`, with no
`.claude/` or `.agents/` anywhere, produces findings identical to the working tree — **26 description
FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs**.
### SUGGESTION-only checks
Three more, deterministic to measure but judgment to act on:
- a description with **no boundary clause at all**;
- a `## Gotchas` section with **more than five entries**;
- a `## Gotchas` section over **25% of the body**.
### `verbose: true` is load-bearing
The hook is declared `verbose: true` so the SUGGESTION tier is audible. pre-commit prints nothing at
all for a passing hook, and a SUGGESTION deliberately does not fail — without verbose every
suggestion is swallowed, which is exactly the invisibility ADR-0013 records for Vale warnings.
ADR-0020's preload arithmetic depends on it: writing to the 400-char FAIL delivers roughly half the
cut that writing to the 250-char SUGGESTION does, so the intended saving depends entirely on that
tier being visible. The numbers, and the measurement method behind them, are not restated here —
they live in ADR-0020's Consequences section, under "A ceiling does not produce an average", whose
figures are pinned to the base commit the decision was taken on (`f9b919d`). Quoting them here would
just create a second copy to go stale. It costs nothing on a clean file — the script prints only
findings.
### Duplicated constants
`skill-audit`'s `validate.sh` holds a second copy of the four ADR-0020 constants
(`DESC_SUGGEST_CHARS` / `DESC_MAX_CHARS` / `BODY_SUGGEST_WORDS` / `BODY_MAX_WORDS`), and
`agent-audit`'s `validate.sh` holds a third copy of the two description constants. They are copied
rather than imported because a cache-installed plugin's scripts cannot read files outside their own
plugin directory. `tests/test-skill-size-check.sh` asserts the copies agree, so drift fails CI rather
than silently letting an audit bless a skill the commit hook then rejects. The shared boundary
resolver block is embedded verbatim in all three scripts between `BEGIN`/`END ADR-0020 SHARED
BOUNDARY RESOLVER` markers and must stay byte-identical.
### `python3` and PyYAML are hard requirements
Both, and neither is a best-effort accelerator.
`python3` because the script measures the **folded** `description` value. Most descriptions here are
`>`-block scalars, so a regex over the raw lines measures indentation and newlines instead of the
value. Missing it fails the hook with an install pointer rather than skipping the ADR-0020 checks,
which would be a vacuous green. In practice it is already present — pre-commit is itself a Python
application.
**PyYAML** because the hand-rolled fallback frontmatter reader has been **removed deliberately**. It
disagreed with a real parser across the FAIL boundary — one corpus description measured 270
characters parsed and 412 unparsed — and a quoted `"description"` key or an explicit
`description: null` returned empty from it, silently skipping the description *and* routing checks. A
reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured,
which is the exact vacuous-green failure the `python3` check exists to avoid. `pip install pyyaml`
(or `python3 -m pip install PyYAML`, or the distro's `python3-yaml`) if the hook reports it missing.
## Agent files take the description gates, not the body gate
`check-apm-agents-valid` runs agent-audit's `validate.sh` over every real
`plugins/*/.apm/agents/*.agent.md`. It derives its expected file set from `git ls-files` — the pattern
`tests/run-bats.sh` established — so an agent file deleted from the worktree but still tracked fails
the run, and **discovering zero agent files is an error, not a pass**. An untracked *new* agent file
is still validated: the derivation is one-directional on purpose, so uncommitted work is not blocked
but also cannot bypass the gate.
The hook exists because `validate.sh` was previously exercised only by `check-scope-walkup-sync`,
against synthetic `mktemp` fixtures — it had never run against the agent files it governs. That is
how ADR-0016 could be amended to bless a `disallowedTools` frontmatter field while `validate.sh`'s
allowlist still rejected it: spec and enforcer disagreed and every gate stayed green.
Agents take the ADR-0020 **description** gates (agent-audit's `validate.sh` holds its own copy of
those two constants) and, deliberately, **no body word gate**. A skill body is loaded into the
caller's context and competes with the live conversation; an agent body becomes the system prompt of
a *fresh* context. The rationale for the 900-word FAIL does not transfer. A bats test pins that
absence in agent-audit's validator — adding a body gate there contradicts the ADR rather than fixing
an inconsistency.
**Be precise about the scope of that guarantee: it holds for the *validator*, not for the shared
script.** `scripts/skill-size-check.sh` applies its body gate to whatever path it is handed, and
```
bash scripts/skill-size-check.sh plugins/*/.apm/agents/*.agent.md
```
exits 1 today with 900-word body FAILs on `git-orchestrate` (933), `gitea-orchestrate` (1,199) and
`apm-orchestrate` (1,080). Agent files escape only because the hook definitions filter on `SKILL.md`
— a file-pattern accident that happens to implement the design, not the design itself. **Do not
"extend" that hook's `files:` pattern to cover agents** on the assumption that the script already
knows the difference; doing so silently enforces a gate ADR-0020 declines to set.
## Current retrofit status
**The ADR-0020 gates ship hot, with no baseline file.** A shrinking baseline recording each
non-compliant skill's current numbers was considered and rejected in favour of hot gates.
Two independent hot gates are currently red, and the first will not warn you about the second.
| Gate | Current findings |
|---|---|
| `skill-size-check` | **26 of 39** descriptions and **9 of 39** bodies exceed their FAIL tier; 2 dangling targets; 58 SUGGESTIONs |
| `Kyberforge.CompositionNote` (Vale) | **10 errors across four skills**: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-workflow` |
`Kyberforge.CompositionNote` is the ADR-0020 Vale rule banning composition and architecture prose
from a description. Every Vale rule here is `level: error` with no ignorable tier, so touching any of
those four skills means fixing its prose findings as well as its size findings.
Consequence: editing a non-compliant skill *for any reason* means retrofitting it to the contract
first — a one-line fix to `gitea-prs` cannot be committed until that skill complies. This is
deliberate; it guarantees convergence and avoids a half-state. Tracked as Gitea issue **#99**.
Check where a skill stands before starting, and check **both** gates:
```
pre-commit run skill-size-check --all-files # size/context only
pre-commit run --all-files # size AND Vale
```
Scoping a retrofit off `skill-size-check` output alone leaves you blocked at the second gate.
## Vale
Install the `vale` binary — `brew install vale` (macOS), `snap install vale` (Linux),
`choco install vale` (Windows), or see <https://vale.sh/docs/vale-cli/installation/>. No `vale sync`
is needed: the `Kyberforge` styles are **committed** under
`plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded
packages (ADR-0014).
### Two copies, one canonical
Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension
(motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it does not live
in `plugins/lint/` — and per ADR-0014 it no longer lives at the repo root either. It lives **twice**,
one copy per skill, both under `plugins/kyberforge/.apm/skills/`:
| Copy | Styles | `.vale.ini` sections |
|---|---|---|
| `agent-audit/assets/vale/` — **canonical** | `Kyberforge`, `KyberforgeCopilot` | `[**/agents/*.md]`, `[**/*.agent.md]` |
| `skill-audit/assets/vale/` — smaller duplicate | `Kyberforge` | `[**/SKILL.md]` |
Duplicated rather than shared because a plugin's cache-install copies only each skill's own files —
there is no cross-skill sharing to point at. `check-vale-style-sync` at pre-push is what keeps them
from drifting; `KyberforgeCopilot` is the one deliberate inequality, being scoped only to `.agent.md`
files for the Copilot-only "`Use proactively` has no effect" check.
### What Vale owns, and what stays LLM judgment
Eleven rule files across the two copies, six distinct rules:
| Rule | Vale scope | Bans | From |
|---|---|---|---|
| `Kyberforge.DescriptionOpener` | `text.frontmatter.description` | non-imperative openers ("This skill/agent…") | issue #84 |
| `Kyberforge.VagueWording` | `text.frontmatter.description` | vague capability wording ("helps with", "utilize", …) | issue #84 |
| `Kyberforge.PaddingPhrase` | `text` | generic "see `references/` for details" padding | issue #84 |
| `KyberforgeCopilot.ProactivePhrase` | `text.frontmatter.description` | `Use proactively` (no effect in Copilot) | issue #84 |
| `Kyberforge.SentenceOpenerThereIs` | `sentence` | "There is/are" sentence openers | ADR-0013 |
| `Kyberforge.CompositionNote` | `text.frontmatter.description` | architecture and composition prose in a description | ADR-0020 |
Vale covers the **pattern-matchable** sub-checks named in issue #84 plus, per ADR-0013, one
cherry-picked body-wide prose-pattern rule. Everything else stays LLM judgment: defaults-vs-menus,
why-rationale, the non-pattern-matchable body-discipline calls, near-miss exclusion strength, and
control calibration. New rules land directly in `styles/Kyberforge` and block immediately — there is
no trial tier.
The cherry-pick record, so it is not re-litigated:
- `Kyberforge.SentenceOpenerThereIs` **landed** — 22 held-out hits, both in-corpus hits clean
rewrites, zero suppressions needed.
- `Kyberforge.VagueQualifier` was cherry-picked and then **deleted**. 2 hits across the corpus as it
stood on 2026-08-08 (before the `.apm/` restructure): one marginal, and one unfixable false
positive — `caveman/SKILL.md` quotes `of course` as an example of filler, a mention rather than a
use — which forced the repo's only Vale suppression comments.
- `governance.md` and `CONTROLS.md` were evaluated as rule sources and **excluded**: nothing
prose-pattern-matchable to mine.
### Why every rule is `level: error`
Every alert is a FAIL, with no ignorable tier — same all-or-nothing model as shellcheck, the test
suite, and conventional-pre-commit. Graded severities do not work here: **Vale's exit code keys on
`error` alerts alone**, so a `warning` or `suggestion` rule exits 0, and pre-commit swallows a
passing hook's output. Such a rule would be invisible and would block nothing.
`MinAlertLevel` and `--minAlertLevel` are correspondingly **absent** from both `.vale.ini` files and
from the hook definitions. Under this model they are no-ops; adding one is not a missing knob.
The `verbose: true` escape hatch that makes `skill-size-check`'s SUGGESTION tier audible has no
analogue here — Vale has no tier to make audible.
### External consumers: the root `.pre-commit-hooks.yaml`
The root `.pre-commit-hooks.yaml` exposes both Vale copies (`kyberforge-vale-audit-skill`,
`kyberforge-vale-audit-agent`) plus `kyberforge-skill-size-check`, so any external repo can enforce
the same rules with `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml`.
pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the
`kyberforge` plugin is installed at all; the same mechanism covers CI via `pre-commit run
--all-files`. `skill-size-check` has no external asset dependency, so it needed no relocation under
ADR-0014 — only exposure.
This repo's own `vale-audit-prefilter-skill` / `-agent` hooks consume the **identical**
plugin-bundled copies via `repo: local`. Deliberately not a third root copy, and deliberately **not a
pinned self-reference** — a pinned self-reference would lint working-tree edits against the last
tagged release rather than against the change being made.
### Pre-commit
Two prefilter hooks, with `.apm/`-scoped `files:` patterns:
| Hook | Pattern |
|---|---|
| `vale-audit-prefilter-skill` | `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` |
| `vale-audit-prefilter-agent` | `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` |
Only the **authoring source** triggers them. A `SKILL.md` in the generated flat mirror matches
neither pattern, so prose findings surface only when you edit the file you are supposed to be
editing. Without the binary the hooks fail with a bare "command not found" and no install pointer.
**Two hooks, not one combined hook.** Both manifests split the prefilter in two precisely because a
single hook can point at only one copy, and that copy would silently 0-file-skip the other file
shape (see [A 0-file Vale run is NOT RUN](#a-0-file-vale-run-is-not-run)).
### The `.vale.ini` globs do no scoping
Each `.vale.ini`'s section globs are **path-agnostic** — `[**/SKILL.md]` for skill-audit's copy,
`[**/agents/*.md]` and `[**/*.agent.md]` for agent-audit's — and constrain filename *shape*, not
location: Vale's `*` crosses `/`. A `SKILL.md` outside `plugins/` (a project-scope
`.claude/skills/foo/SKILL.md`, say) still matches `[**/SKILL.md]` and gets linted normally.
All scoping therefore comes from the pre-commit hook's own `files:` regex and from the audit skills
passing one explicit file per invocation. The two manifests scope **differently on purpose**:
| Manifest | `-skill` | `-agent` |
|---|---|---|
| `.pre-commit-config.yaml` (pins this repo's layout) | `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` | `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` |
| `.pre-commit-hooks.yaml` (layout-agnostic for consumers) | `(^\|/)SKILL\.md$` | `(^\|/)agents/[^/]+\.md$\|\.agent\.md$` |
Narrowing a `.vale.ini` glob to a `plugins/`-shaped path to "tighten" it breaks the consumer case,
and `check-vale-style-sync`'s probe set is built to catch exactly that.
### `vale-wrap.sh`, never bare `vale`
Both audit skills' Step 1 and both pre-commit hooks call **each copy's own**
`scripts/vale-wrap.sh`, not `vale`. It works around a confirmed **Vale 3.15.2** limitation:
`text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions.
Verified by reproduction on a deliberately-bad fixture, not assumed:
| Description scalar spanning 2+ lines | Vale's behaviour |
|---|---|
| `>` folded block | 0 alerts, exit 0 — **broken** |
| plain (unquoted) continuation lines | 0 alerts, exit 0 — **broken** |
| single- or double-quoted, wrapped | 0 alerts, exit 0 — **broken** |
| `\|` literal block | alerts fire, exit 1 — lints normally |
The wrapper flattens the three broken forms to a single-line scalar in a scratch copy — or, for the
rare value no inline scalar can spell verbatim, a `|-` block with one content line — padding with
blank lines so **every other line number is unchanged**. `|` literal blocks and single-line
descriptions pass through untouched. Most descriptions in this repo are `>` blocks, so before the
wrapper a bad description in any of the three broken forms sailed straight through the prefilter.
### The `--config` argv defect
Handed **no `--config` at all**, the wrapper falls back to its own sibling `assets/vale/.vale.ini`,
located from `${BASH_SOURCE[0]}` rather than from the cwd. That is why both manifests' `entry:` is
now the bare script path with **no argument after it**.
pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]),
*cmd[1:])`), so every later argument resolves against the **consuming** repo's root. A `--config` in
`.pre-commit-hooks.yaml` therefore pointed at a path no consumer has and hard-failed every external
run with `E100 [--config] Runtime error`.
`.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical.
The local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was*
this repo — and that divergence is why three review rounds exercised a path no external consumer
takes and missed the defect. **Do not reintroduce a `--config` to either manifest to make the local
run "explicit".**
An explicit `--config` from any other caller still wins, in all three argv forms (`--config X`,
`--config=/abs`, `--config=rel`), and a relative one resolves against the caller's cwd — matching
bare `vale`, not the repo root.
Both audit skills' Step 1 passes no `--config` either. Step 1 resolves the script relative to the
skill's own directory so the call works from an installed plugin cache; a relative `--config`
alongside it would resolve against the cwd instead, yielding `E100 Runtime error … does not exist`
and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to
full LLM judgment.
`tests/test-vale-wrap.sh` regression-tests this against **skill-audit's** copy specifically: its
fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` carries that glob section.
### A 0-file Vale run is NOT RUN
Vale reports 0 files only when the path it is handed matches **no glob section at all** — a
differently-named file, or a directory argument holding nothing that matches. That run prints
```
✔ 0 errors ... in 0 files.
```
and exits 0, indistinguishable from a clean pass. Both audits therefore treat a 0-file Vale run as
**NOT RUN** and fall back to full LLM judgment rather than reporting the Description dimension
clean.
### Pre-push
`vale` is a **pre-push** dependency too, not only pre-commit. `check-vale-style-sync` runs **six
glob-coverage probes** by invoking `vale --config` — one representative path per file shape the
prefilter is supposed to cover. They are the only assertions in the script that catch a `.vale.ini`
glob typo (`[**/SKILL.md]` → `[**/SKILLS.md]`), the failure mode where every text-level check stays
clean while vale lints zero files. As a warning this self-disabled on exactly that mutation and
exited 0, and since pre-commit swallows a passing hook's output the stderr line was never seen — the
hook reported `Passed`. Missing `vale` is therefore a hard failure here.
The opt-out is `CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1`, and **it is not `SKIP=`**: the hook
still runs and still asserts everything verifiable from file text, but the six probes do not, and its
summary says so explicitly —
```
Vale style sync check passed (text-level only, vale unavailable): … 0 glob probe(s) verified.
```
Use it only on a machine that genuinely cannot install `vale`, and read that line as "the glob axis
was not checked", not as a pass. The hook is `verbose: true` for exactly that reason — its clean
output is a single line, so it costs one line per push.
### Mentioning banned phrasing without tripping the rule
House convention: banned phrasing that must be **mentioned** rather than used goes in backticks or a
fenced code block. Vale skips code spans and fences, so no suppression is needed — which is why this
document quotes `Use proactively` and "There is/are" the way it does.
Inline `<!-- vale Rule = NO -->` is the fallback **only** where backticking is impossible. Use the
HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown. The one time a rule forced
suppression comments, the rule was deleted instead (see the `VagueQualifier` entry above).
## Tests
```
bash tests/run-tests.sh # every test-*.sh plus the bats suite
bash tests/run-tests.sh --bats-only # just bats
```
First run auto-initializes the bats submodules; no manual `git submodule update` needed.
**Exit 77 = SKIPPED.** A suite that skips because a dependency is missing does **not** fail an ad-hoc
run. The pre-push hook invokes the same script as `--strict` (`RUN_TESTS_STRICT=1` is equivalent),
where a skip **does** fail the push: at pre-push a skip means one of the documented dependencies is
absent on this machine, so the gate would otherwise report success having run fewer suites than it
appears to. Without `--strict` the gate once went green having verified 15 of 17 suites on a
vale-less PATH, with the skip list swallowed. Without vale, three suites skip —
`test-check-vale-style-sync.sh`, `test-vale-hooks-consumer.sh`, `test-vale-wrap.sh` — and the strict
failure names each one and what to install.
`tests/run-bats.sh` derives the set of `.bats` files it expects from `git ls-files`, so a `.bats`
file deleted from the worktree but still tracked in the index fails the run rather than silently
shrinking the suite. Remove one with `git rm` (or stage the deletion) when intentional; an untracked
new `.bats` file is picked up and needs no ceremony.
Both discovery walks (`tests/run-bats.sh` and `tests/run-tests.sh`) exclude `apm_modules/`:
`apm install` materializes a full copy of every plugin there, and running a dependency's copy of a
`.bats` file breaks its relative path to the bats helpers — **167 spurious failures** before the
exclusion landed.
## apm gates
### `apm-audit-ci`
Runs `apm audit --ci` **once per manifest** — the root one and each of the six plugin packages —
because the root-only invocation audits the marketplace manifest and **nothing else**, and
`apm-pack-check-clean` does not parse plugin `dependencies:` blocks either. Verified: a malformed
dependency entry passes `apm pack --check-versions --check-clean --dry-run` and fails
`apm audit --ci` in that package's directory. Costs ~0.5s per package.
It verifies **exactly two things** per manifest and claims no more:
- **manifest-parse** — each `apm.yml` parses as a valid APM manifest. Unconditional; verified to fire
on a dependency entry missing its `git`/`path`/`registry` field (`Cannot parse apm.yml`).
- **lockfile-exists** — any package declaring dependencies has a consistent `apm.lock.yaml`.
Conditional, and vacuous while every plugin `apm.yml` declares `dependencies: {apm: [], mcp: []}`;
it arms itself the moment one does not (verified by adding a git dependency to
`plugins/lint/apm.yml`).
It does **not** enforce an org policy. apm discovers one from the git remote and only understands
github.com and Azure DevOps, so against this repo's self-hosted Gitea remote it prints:
```
No org policy found at unknown; enforcement skipped
```
**Do not "fix" that with `policy.fetch_failure_default: block` in `apm.yml`.** apm's own message
suggests it; it was tried on a scratch copy and **rejected**. With no reachable policy source it does
not make the check meaningful, it makes it permanently red — `apm audit --ci` exits 1 with
`No org policy found at unknown (policy.fetch_failure_default=block)` on every push, forever. A gate
that can never go green is not a gate. Revisit only if this repo gains a policy source apm can reach.
It also does not scan for hidden Unicode: that scan is plain `apm audit`, a different mode (`--ci`
refuses to combine with `--file`/`--strip`/`--dry-run`/`PACKAGE`), and plain `apm audit` here reports
`No apm.lock.yaml found -- nothing to scan` and exits 0. Adding it would buy a second vacuous check.
### `check-executables-allow-sync`
apm gates a package's `hooks/` and `bin/` on an **exact `<package>#<version>` dictionary lookup** in
root `apm.yml`'s `executables.allow` (`apm_cli/security/executables.py`, `is_package_approved`).
There is no wildcard and no version-less form.
So bumping `plugins/kyberforge/apm.yml`'s `version:` without bumping the key **errors nowhere**: the
entry simply stops matching, the gate blocks the hook, kyberforge's `SessionStart` hook stops
deploying, and the apm install goes quietly stale — the exact failure ADR-0019 exists to end,
reintroduced through the mechanism meant to secure it. ADR-0019 records this as a live failure mode;
the release that shipped the hook hit it immediately.
`scripts/check-executables-allow-sync.sh` parses `version:` out of `plugins/kyberforge/apm.yml` and
asserts root `apm.yml` carries the matching `kyberforge#<version>` key. A comment in the
`executables:` block stays as the human-facing pointer; the hook is what actually holds. It parses
with PyYAML where importable and falls back to a two-shape scan otherwise, so a missing pip package
cannot become the thing that blocks every push.
## `.claude/settings.json`
**apm owns this file. Nothing repo-authored goes in it.**
`apm audit --ci` replays the install into a scratch tree and diffs the result byte-for-byte, so
anything apm would not have written there — an `enabledPlugins` block, a real `hooks` entry — is
permanent drift that fails `apm-audit-ci`. A hook you want in this repo is authored in
`plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written here.
Its committed content is whatever apm last wrote, which today is the merged `SessionStart` entry for
kyberforge's `check-apm-current.sh`. That is apm's own output and it belongs in the commit (ADR-0019;
ADR-0018's statement that the committed content is exactly `{"hooks": {}}` is superseded on that
point only). Machine-specific settings go in the gitignored `.claude/settings.local.json`, which apm
does not deploy and the replay does not compare; shared enforcement belongs in
`.pre-commit-config.yaml`.
### Why it is excluded from `pretty-format-json`
It is the **sixth and last alternation** in that hook's `exclude:` pattern, and the only one there
for a reason other than "generated manifest". Mind which number you are quoting: **six alternations,
expanding to sixteen real files** — 3 root marketplace manifests, 2 per plugin × 6 plugins, plus this
one.
`pretty-format-json --autofix` sorts object keys unless `--no-sort-keys` is passed, while apm's hook
integrator emits insertion order (`matcher` before `hooks`, `type` before `command`). Leaving the
file in that hook's scope therefore rewrites apm's output into a form apm would never produce on the
way into **every** commit, and `apm-audit-ci` then reports permanent drift on a file with an empty
`git diff` — exactly what happened when the `SessionStart` hook first landed in `2e395a4`. Re-running
`apm install` fixes the file; leaving it in scope would re-break it on the very commit carrying the
fix.
**Load-bearing. Do not tidy it out of that list** (see `LESSONS.md`, 2026-08-14).
## Pushing without a network
Exactly **two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s
`marketplace.packages[]` contains exactly one remote entry — `mattpocock-skills`,
`source: mattpocock/skills` — and resolving it needs a `git ls-remote`.
| Hook | Offline failure |
|---|---|
| `apm-marketplace-check` (`always_run`, resolves every entry) | `No cached refs (offline)` |
| `apm-pack-check-clean` (re-resolves the same entry) | `Error: Git network timeout during ls-remote` |
Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes.
`--offline` rescues neither.
To push without a network, skip both using pre-commit's own mechanism:
```
SKIP=apm-marketplace-check,apm-pack-check-clean git push
```
**Skip those two alone.** Verified under `unshare -rn`: the other twelve pre-push hooks pass offline
because they are real local checks. (`check-executables-allow-sync` landed after that run, but reads
two local manifests and makes no network call.) Adding any other hook to `SKIP` disarms it silently.
`apm-audit-ci` calls `apm` too but stays local: its org-policy discovery resolves nothing on this
remote *before* any network call, so it does not join the pair above.
---
## See also
- `docs/adr/0020-skill-description-and-body-context-contract.md` — the context contract, its
enforcement table (deterministic vs. auditor judgment), and every rejected alternative
- `docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md` — the `SessionStart` hook, the
executable-trust gate, and the version-pinned allow key
- `docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md`,
`docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md`,
`docs/adr/0014-vale-prefilter-ships-from-the-plugin.md` — plugin content sync, apm-generated
manifests, committed Vale styles
- `docs/spec/architecture.md` — directory structure, install pipeline, what is generated and what is
hand-authored
- `.pre-commit-config.yaml` — the hooks themselves, with inline rationale comments

4
plugins/bin/.claude-plugin/plugin.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "bin", "name": "bin",
"version": "1.1.3", "version": "1.1.5",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/bin/.github/plugin/plugin.json vendored
View File

@@ -1,7 +1,7 @@
{ {
"name": "bin", "name": "bin",
"version": "1.1.3", "version": "1.1.5",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/bin/apm.yml
View File

@@ -1,6 +1,6 @@
name: bin name: bin
version: 1.1.3 version: 1.1.5
description: A place for things to be binned description: Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.
author: author:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net

4
plugins/git/.claude-plugin/plugin.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "git", "name": "git",
"version": "1.3.3", "version": "1.3.5",
"description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.", "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/git/.github/plugin/plugin.json vendored
View File

@@ -1,7 +1,7 @@
{ {
"name": "git", "name": "git",
"version": "1.3.3", "version": "1.3.5",
"description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.", "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/git/apm.yml
View File

@@ -1,6 +1,6 @@
name: git name: git
version: 1.3.3 version: 1.3.5
description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow. description: Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.
author: author:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net

4
plugins/gitea/.claude-plugin/plugin.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "gitea", "name": "gitea",
"version": "1.3.4", "version": "1.3.6",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API \u2014 the forge's own objects, as distinct from the local git clone.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/gitea/.github/plugin/plugin.json vendored
View File

@@ -1,7 +1,7 @@
{ {
"name": "gitea", "name": "gitea",
"version": "1.3.4", "version": "1.3.6",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API \u2014 the forge's own objects, as distinct from the local git clone.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/gitea/apm.yml
View File

@@ -1,6 +1,6 @@
name: gitea name: gitea
version: 1.3.4 version: 1.3.6
description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis. description: Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.
author: author:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net

9
plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md
View File

@@ -111,9 +111,12 @@ Flag as FAIL if:
available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is
judgment. judgment.
- **A boundary clause naming a target that does not resolve** to a real skill directory or agent - **A boundary clause naming a target that does not resolve** to a real skill directory or agent
file in the authoring source. No script checks this for an agent file — `validate.sh` resolves file in the authoring source. `validate.sh` resolves this for agent files at both scopes and
boundary targets for skills only, so resolve the name yourself against `plugins/*/.apm/skills/` reports each unresolved target itself — take its verdict rather than re-resolving the name by
and `plugins/*/.apm/agents/`. hand, because a hand-walk over a different universe can contradict it. What is left to you is
semantic and the script cannot reach it: whether a target that *does* resolve is the right
sibling to exclude, and whether a clause naming no target at all ("examine the files manually")
should have named one.
- **`Use proactively` in a Copilot or vendor-neutral description.** - **`Use proactively` in a Copilot or vendor-neutral description.**
`KyberforgeCopilot.ProactivePhrase` catches it. The phrase steers the Claude Code runtime and `KyberforgeCopilot.ProactivePhrase` catches it. The phrase steers the Claude Code runtime and
does nothing anywhere else, so in a `.agent.md` it is preloaded text that buys no behaviour. does nothing anywhere else, so in a `.agent.md` it is preloaded text that buys no behaviour.

201
plugins/kyberforge/.apm/skills/agent-audit/scripts/validate.sh
View File

@@ -222,17 +222,21 @@ def read_text(path):
# which is what a monorepo means, # which is what a monorepo means,
# 2. the target's own apm package, # 2. the target's own apm package,
# 3. the packages that package DECLARES in apm.yml dependencies.apm. # 3. the packages that package DECLARES in apm.yml dependencies.apm.
# Deployed .claude/ and .agents/ trees are deliberately NOT consulted in that # Deployed .claude/ and .agents/ trees are deliberately NOT consulted when the
# case. They are `apm install` output, gitignored, and present only on a machine # root came from the plugins/ probe. They are `apm install` output, gitignored,
# that has run it: four cross-plugin targets in this repo (gitea-branches -> # and present only on a machine that has run it: four cross-plugin targets in
# git-branches, gitea-branches -> git-history, gitea-issues -> git-branches, # this repo (gitea-branches -> git-branches, gitea-branches -> git-history,
# gitea-workflow -> git-workflow) resolved through .claude/skills/ alone, so the # gitea-issues -> git-branches, gitea-workflow -> git-workflow) resolved through
# same commit measured 2 dangling targets on a developer machine and 6 on a # .claude/skills/ alone, so the same commit measured 2 dangling targets on a
# fresh clone. A gate shipping hot with no baseline cannot give two answers. # developer machine and 6 on a fresh clone. A gate shipping hot with no baseline
# cannot give two answers.
# #
# Deployed trees are used only when NO authoring root exists — the consumer # Deployed trees ARE used when no plugin monorepo was found — whether the walk
# case, where the file being checked lives in or beside a deployed tree and # landed on a bare .git ancestor or on nothing at all. That is the consumer
# there is no monorepo to read. # case: the file being checked lives in or beside a deployed tree, inside an
# ordinary git repo, with no monorepo to read. The two cases are told apart by
# which probe matched, never by how many names a root contributed; see
# known_targets().
def _is_fs_root(path): def _is_fs_root(path):
@@ -241,11 +245,17 @@ def _is_fs_root(path):
def _collect_package(pkg_dir, names): def _collect_package(pkg_dir, names):
"""Add every skill/agent name a package directory exposes, any layout.""" """Add every skill/agent name a package directory exposes, any layout."""
# glob.escape() the DIRECTORY only. A checkout path containing `[`, `]`,
# `*` or `?` — a worktree named `feature[2]`, say — otherwise turns the
# whole pattern into a character class that matches nothing, and the
# resolver degrades to the "DID NOT RUN" INFO with rc=0 across every file
# in the tree. The wildcards in `sub` are the intended ones and stay raw.
safe_dir = glob.escape(pkg_dir)
for sub in ('.apm/skills/*/', 'skills/*/'): for sub in ('.apm/skills/*/', 'skills/*/'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
names.add(os.path.basename(path.rstrip('/')).lower()) names.add(os.path.basename(path.rstrip('/')).lower())
for sub in ('.apm/agents/*.md', 'agents/*.md'): for sub in ('.apm/agents/*.md', 'agents/*.md'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
base = os.path.basename(path) base = os.path.basename(path)
if base.endswith('.agent.md'): if base.endswith('.agent.md'):
base = base[:-len('.agent.md')] base = base[:-len('.agent.md')]
@@ -277,28 +287,35 @@ def _apm_package_root(start_dir):
def _authoring_root(start_dir): def _authoring_root(start_dir):
"""Nearest ancestor that is a plugin monorepo, else the nearest .git tree. """Nearest ancestor that is a plugin monorepo, else the nearest .git tree.
Returns (root, matched_plugins_probe). The flag reports WHICH probe
matched: True for the plugins/*/.apm/{skills,agents} glob, False for the
.git fallback and for no match at all. known_targets() needs that
distinction — only a real plugins/ root makes the deployed trees
redundant, and a name-count delta cannot tell the two apart.
Two passes, not one interleaved walk: a nested .git (a submodule, a Two passes, not one interleaved walk: a nested .git (a submodule, a
worktree of a sub-package) must not win over a real plugins/ root further worktree of a sub-package) must not win over a real plugins/ root further
up. Both passes stop before the filesystem root for the same reason up. Both passes stop before the filesystem root for the same reason
_apm_package_root does. _apm_package_root does.
""" """
for probe in ( probes = (
lambda d: bool(glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'skills')) lambda d: bool(glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'skills'))
or glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'agents'))), or glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'agents'))),
lambda d: os.path.exists(os.path.join(d, '.git'))): lambda d: os.path.exists(os.path.join(d, '.git')))
for index, probe in enumerate(probes):
current = os.path.abspath(start_dir) current = os.path.abspath(start_dir)
for _ in range(12): for _ in range(12):
if _is_fs_root(current): if _is_fs_root(current):
break break
if probe(current): if probe(current):
return current return current, index == 0
current = os.path.dirname(current) current = os.path.dirname(current)
return None return None, False
def _collect_authoring_root(root, names): def _collect_authoring_root(root, names):
"""Every plugin in the monorepo contributes its names.""" """Every plugin in the monorepo contributes its names."""
for pkg in glob.glob(os.path.join(root, 'plugins', '*')): for pkg in glob.glob(os.path.join(glob.escape(root), 'plugins', '*')):
if os.path.isdir(pkg): if os.path.isdir(pkg):
_collect_package(pkg, names) _collect_package(pkg, names)
@@ -362,7 +379,7 @@ def _declared_dependency_dirs(pkg_dir):
def _deployed_roots(start_dir): def _deployed_roots(start_dir):
""".claude/ and .agents/ trees above start_dir — what a host really sees. """.claude/ and .agents/ trees above start_dir — what a host really sees.
Consulted ONLY when no authoring root exists; see the section header. The Consulted ONLY when no plugin monorepo root was found; see the header. The
filesystem root is skipped for the same reason _apm_package_root skips it: filesystem root is skipped for the same reason _apm_package_root skips it:
a stray /.claude/skills/ must not join every path's universe. a stray /.claude/skills/ must not join every path's universe.
""" """
@@ -401,10 +418,22 @@ def known_targets(start_dir):
for dep_dir in _declared_dependency_dirs(package): for dep_dir in _declared_dependency_dirs(package):
_collect_package(dep_dir, names) _collect_package(dep_dir, names)
root = _authoring_root(start) # A .git ancestor is an authoring root only if it actually holds plugins.
# _authoring_root() falls back to the nearest .git, so it is truthy in ANY
# git repo; without the distinction that fallback wins in every consumer
# checkout, _collect_authoring_root() contributes nothing, and the deployed
# branch below is dead code in the exact case it exists for. So condition
# on WHICH probe matched, which _authoring_root() reports directly. A
# name-count delta looks equivalent and is not: _collect_authoring_root()
# re-collects the checked file's own plugin, whose names the blocks above
# already added, so a one-plugin monorepo shows a delta of zero and would
# wrongly reach for the deployed trees — including the user's global
# ~/.claude/skills, making the verdict depend on what happens to be
# installed (ADR-0020 lines 118-127).
root, root_has_plugins = _authoring_root(start)
if root: if root:
_collect_authoring_root(root, names) _collect_authoring_root(root, names)
else: if not root_has_plugins:
for base in _deployed_roots(start): for base in _deployed_roots(start):
_collect_package(base, names) _collect_package(base, names)
return names return names
@@ -510,16 +539,43 @@ MARKED_TARGET = r"(?:`/?(%s)`|(?<![\w./*-])/(%s)\b)" % (NAME_ANY, NAME_ANY)
ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH) ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH)
ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I) ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I)
ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I) ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I)
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET) # re.I on ALL of them, uniformly. The patterns are built from the same
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET) # lowercase NAME_* fragments, so half of them carrying the flag and half not
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET) # meant `Skill-Audit` at the start of a boundary sentence was extracted by
# ROUTE_ANY but invisible to BACKTICK — contradicting normalize_target()'s own
# docstring, which exists precisely because extraction is case-insensitive and
# the universe is not.
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET, re.I)
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET, re.I)
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET, re.I)
ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I) ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I)
BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH) BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH, re.I)
# A boundary clause takes two shapes and BOTH count: the prose markers, and # A boundary clause takes two shapes and BOTH count: the prose markers, and
# ADR-0020's compressed arrow form `Not <thing> -> <name>`. # ADR-0020's compressed arrow form `Not <thing> -> <name>`.
BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I) BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I)
BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I) BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I)
SENTENCE_SPLIT = re.compile(u'(?<=[.!?])\\s+(?=[A-Z"“(])') # Sentence boundaries decide the CORROBORATION scope above, so getting one wrong
# is not cosmetic — it moves a target between SUGGESTION and blocking ERROR. Two
# shapes common in these descriptions defeat the naive "period, space, capital"
# rule, in OPPOSITE directions:
# OVER-SPLIT. `e.g. "set up the manifest"` ends no sentence, but the quote
# looks like one starting. The clause is cut in half, the corroborating
# target lands on the far side of the cut, and a genuinely dangling target
# silently demotes to SUGGESTION — the gate takes a measurement and then
# throws it away, which is the vacuous-green shape this file exists to stop.
# UNDER-SPLIT. A real sentence opening with a code span or a lowercase skill
# name ("... Composes it. `gitea-prs` also uses it.") is not seen as a start
# at all, so two sentences merge and a resolving target vouches for an
# unresolvable one it never stood beside — a hard FAIL with no escape hatch,
# which is exactly the failure the corroboration rule was added to prevent.
# Both are closed here: the five abbreviations that actually occur in routing
# prose are excluded as sentence ends, and the opener class admits a backtick or
# a lowercase letter. Verified zero-delta on the current corpus (37 ERROR / 58
# SUGGESTION / 2 dangling before and after) — this protects the descriptions
# issue #99 is about to rewrite, not the ones already measured.
SENTENCE_SPLIT = re.compile(
u'(?<!\\be\\.g\\.)(?<!\\bi\\.e\\.)(?<!\\betc\\.)(?<!\\bvs\\.)(?<!\\bcf\\.)'
u'(?<=[.!?])\\s+(?=[A-Za-z`"“(])')
# The token that may follow a route target without turning it into a compound # The token that may follow a route target without turning it into a compound
# modifier: punctuation, end of sentence, a conjunction, a boundary word, or a # modifier: punctuation, end of sentence, a conjunction, a boundary word, or a
@@ -681,8 +737,16 @@ def unresolved_targets(description, known):
# description with a 1,000-word body exited 0 behind a BOM). A file that cannot # description with a 1,000-word body exited 0 behind a BOM). A file that cannot
# be measured must never report green, so every caller of these two ERRORs on a # be measured must never report green, so every caller of these two ERRORs on a
# miss instead of moving on. # miss instead of moving on.
#
# The CLOSING marker is anchored at column 0 — deliberately NOT `[ \t]*---`.
# YAML block-scalar content must be indented deeper than its key, so an
# indented `---` inside a folded description is CONTENT; letting it close the
# frontmatter truncated the description mid-value and silently reclassified the
# rest as body, which is a vacuous green in both directions at once. Leading
# whitespace is still tolerated on the OPENING marker, where no such content
# can exist.
FRONTMATTER_RE = re.compile( FRONTMATTER_RE = re.compile(
r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n[ \t]*---[ \t]*(?:\r?\n|\Z)', re.DOTALL) r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)', re.DOTALL)
def strip_bom(text): def strip_bom(text):
@@ -714,14 +778,26 @@ def description_value(fm_text):
try: try:
data = yaml.safe_load(fm_text) data = yaml.safe_load(fm_text)
except Exception as exc: except Exception as exc:
raise FrontmatterError(re.sub(r'\s+', ' ', str(exc)).strip()) # Every FrontmatterError message is a COMPLETE clause, never a detail a
# caller wraps in one. Callers used to prefix a hard-coded "frontmatter
# is not valid YAML (...)", which is true only of this branch: the two
# type failures below come from frontmatter that parsed fine, and
# telling their author the YAML is invalid sends them hunting for a
# syntax error that is not there — on a blocking gate with no baseline.
raise FrontmatterError('frontmatter is not valid YAML (%s)'
% re.sub(r'\s+', ' ', str(exc)).strip())
if not isinstance(data, dict): if not isinstance(data, dict):
raise FrontmatterError('frontmatter is not a YAML mapping') raise FrontmatterError('frontmatter is not a YAML mapping')
value = data.get('description') value = data.get('description')
if value is None: if value is None:
return '' return ''
if not isinstance(value, str): if not isinstance(value, str):
value = str(value) # NOT str()-coerced. `description: true` became the 4-character "True"
# and sailed through the 400-character gate; a list or mapping was
# measured as its Python repr. Neither is a description a host can
# preload, so this is a parse failure, reported as one.
raise FrontmatterError(
'description is a %s, not a string' % type(value).__name__)
return re.sub(r'\s+', ' ', value).strip() return re.sub(r'\s+', ' ', value).strip()
@@ -791,6 +867,18 @@ def mask_fenced(text):
if (marker and marker[0] == fence[0] and len(marker) >= len(fence) if (marker and marker[0] == fence[0] and len(marker) >= len(fence)
and not stripped.strip()[len(marker):].strip()): and not stripped.strip()[len(marker):].strip()):
fence = None fence = None
# An UNCLOSED fence has no cost-free answer, only a choice of which way to
# be wrong. Masking to end-of-body blanks the rest of the body, silently
# disabling the ERROR-tier references/ check and the gotcha counts.
# Returning the raw text instead exposes the unclosed example's own
# content, so a fenced example naming a nonexistent references/ file
# becomes a hard ERROR it would not have been had the fence been closed —
# confirmed, not hypothetical. The loud-false-positive direction is the one
# chosen: this script's rule is that a file it cannot measure must never
# report green, and masking-onward is exactly that failure. Both outcomes
# need an already-malformed file, and the false positive costs one fence.
if fence is not None:
return text
return ''.join(out) return ''.join(out)
@@ -869,12 +957,15 @@ def get_frontmatter_keys(fm):
return keys return keys
def agent_description(fm, local_fname): def agent_description(fm, local_fname):
"""The folded description VALUE, or None if the frontmatter is not YAML.""" """The folded description VALUE, or None if it could not be read."""
try: try:
return description_value(fm) return description_value(fm)
except FrontmatterError as exc: except FrontmatterError as exc:
fail(f"frontmatter is not valid YAML ({exc}) — the ADR-0020 description and " # `exc` carries the whole clause — invalid YAML, a non-mapping block, or
f"boundary-target gates could not run — {local_fname}") # a description of the wrong type. Do not prefix a diagnosis here; the
# last one named a syntax error for two failures that have none.
fail(f"{exc} — the ADR-0020 description and boundary-target gates could "
f"not run — {local_fname}")
return None return None
def check_description_budget(value, local_fname): def check_description_budget(value, local_fname):
@@ -944,11 +1035,31 @@ def check_boundary(value, fpath, local_fname):
f"{local_fname}") f"{local_fname}")
def extract_tools_list(fm): def extract_tools_list(fm):
"""Extract tool names from the tools frontmatter field (space or comma separated).""" """Tool names from the `tools` field — inline scalar OR YAML block sequence.
val = extract_field(fm, 'tools')
if not val: Read off the PARSED mapping, never off extract_field(). That function's
capture is newline-bounded on purpose (`[^\\S\\r\\n]*(.+)`), so a `tools:`
written as a block sequence — the shape Copilot agent files use — captured
nothing at all and the subagent-unavailable-tool check silently stopped
firing on exactly the files it was written for. Both spellings are legal
YAML, so both are read here.
"""
try:
data = yaml.safe_load(fm)
except Exception:
# Not this function's failure to report: the frontmatter's validity is
# decided (and failed) by agent_description() on the same text.
return set() return set()
return set(re.split(r'[\s,]+', val.strip())) if not isinstance(data, dict):
return set()
val = data.get('tools')
if isinstance(val, list):
items = [str(item).strip() for item in val]
elif isinstance(val, str):
items = re.split(r'[\s,]+', val.strip())
else:
return set()
return {item for item in items if item}
def is_copilot_cloud_ide(fpath): def is_copilot_cloud_ide(fpath):
"""True if the file is a cloud/IDE Copilot agent (name is optional for these).""" """True if the file is a cloud/IDE Copilot agent (name is optional for these)."""
@@ -1063,6 +1174,15 @@ def check_apm_agent_file(fpath, allowlist, stem):
fail(f"file is {exc}. Nothing could be measured, so this is a hard " fail(f"file is {exc}. Nothing could be measured, so this is a hard "
f"failure, not a skip — {local_fname}") f"failure, not a skip — {local_fname}")
return return
except OSError as exc:
# A path that cannot be opened gets a FAIL line naming it, not a bare
# FileNotFoundError traceback. scripts/check-apm-agents-valid.sh takes
# this path for an agent file deleted from the worktree but still
# tracked in the index — a real, expected state, and the caller needs to
# be told which file, not handed an interpreter stack.
fail(f"could not be read ({exc.strerror or exc}): {fpath}. Nothing could "
f"be measured, so this is a hard failure, not a skip — {local_fname}")
return
fm, body = parse_frontmatter(content) fm, body = parse_frontmatter(content)
if fm is None: if fm is None:
@@ -1168,6 +1288,13 @@ def check_file(fpath, file_provider):
fail(f"file is {exc}. Nothing could be measured, so this is a hard " fail(f"file is {exc}. Nothing could be measured, so this is a hard "
f"failure, not a skip — {local_fname}") f"failure, not a skip — {local_fname}")
return return
except OSError as exc:
# Same reason as check_apm_agent_file's: a diagnostic naming the path
# beats a FileNotFoundError traceback. The counterpart is pre-checked at
# the bottom of this script, but agent_file itself never was.
fail(f"could not be read ({exc.strerror or exc}): {fpath}. Nothing could "
f"be measured, so this is a hard failure, not a skip — {local_fname}")
return
fm, body = parse_frontmatter(content) fm, body = parse_frontmatter(content)
if fm is None: if fm is None:

133
plugins/kyberforge/.apm/skills/agent-audit/tests/validate.bats
View File

@@ -810,3 +810,136 @@ EOF
assert_success assert_success
refute_output --partial "hooks" refute_output --partial "hooks"
} }
# ---------------------------------------------------------------------------
# tools: — both YAML spellings
# ---------------------------------------------------------------------------
# The subagent-unavailable-tool SUGGESTION is read off the `tools` field, and
# `tools` has two legal spellings: an inline scalar and a block sequence. The
# field used to be pulled out with a line regex whose capture is newline-bounded
# on purpose, so a block sequence captured NOTHING and the check silently
# stopped firing — on the shape Copilot agent files actually use, which is to say
# on the files it was written for. Both spellings are pinned, and they are pinned
# together: the inline case alone was green throughout.
# make_pair <root> <tools-frontmatter> — a project-scope CC + Copilot pair
# carrying the same `tools` value in both files. `tools` is on neither the
# claude-code-only nor the copilot-only list, so it is legal in both and the pair
# stays otherwise clean; the description carries a boundary clause so the only
# SUGGESTION that can fire is the one under test.
make_tools_pair() {
local root="$1" tools="$2"
mkdir -p "$root/.git" "$root/.claude/agents" "$root/.github/agents"
local f
for f in "$root/.claude/agents/my-agent.md" "$root/.github/agents/my-agent.agent.md"; do
{
echo "---"
echo "name: my-agent"
echo "description: A valid agent description. Do not use for anything else."
echo "$tools"
echo "---"
echo ""
echo "You are a test agent. When invoked, do the thing."
} > "$f"
done
}
@test "a subagent-unavailable tool in an INLINE tools scalar raises a SUGGESTION" {
make_tools_pair "$TMPDIR/inline" "tools: Read ExitPlanMode"
run bash "$SCRIPT" "$TMPDIR/inline/.claude/agents/my-agent.md"
assert_success
assert_output --partial "'ExitPlanMode' is listed in tools but is never available to subagents"
}
@test "a subagent-unavailable tool in a BLOCK SEQUENCE tools field raises the same SUGGESTION" {
make_tools_pair "$TMPDIR/block" "$(printf 'tools:\n - Read\n - ExitPlanMode')"
run bash "$SCRIPT" "$TMPDIR/block/.claude/agents/my-agent.md"
assert_success
assert_output --partial "'ExitPlanMode' is listed in tools but is never available to subagents"
}
@test "a tools list with no subagent-unavailable tool stays silent in both spellings" {
# The control. Without it both cases above are satisfied by a check that
# fires on every tools field it can see, which would be the opposite defect.
make_tools_pair "$TMPDIR/inline-clean" "tools: Read Edit"
run bash "$SCRIPT" "$TMPDIR/inline-clean/.claude/agents/my-agent.md"
assert_success
refute_output --partial "never available to subagents"
make_tools_pair "$TMPDIR/block-clean" "$(printf 'tools:\n - Read\n - Edit')"
run bash "$SCRIPT" "$TMPDIR/block-clean/.claude/agents/my-agent.md"
assert_success
refute_output --partial "never available to subagents"
}
# ---------------------------------------------------------------------------
# A file that cannot be read
# ---------------------------------------------------------------------------
# scripts/check-apm-agents-valid.sh derives its expected agent-file set from
# `git ls-files`, so it hands this script paths that are tracked but absent from
# the worktree — a real and expected state, not a corner case. That used to exit
# 1 with a bare FileNotFoundError traceback and no FAIL line at all: non-zero, so
# the gate blocked, but with an interpreter stack instead of a diagnostic naming
# the file. Both scope paths are covered because they are separate call sites
# (check_apm_agent_file and check_file) and each needed its own handler.
#
# `is-a-dir.agent.md` is a DIRECTORY rather than a chmod 000 file on purpose:
# these tests run as root in CI, where mode bits do not deny anything and a
# permissions fixture would be silently readable and prove nothing.
@test "a nonexistent plugin/APM-scope agent file gets a FAIL naming the path, not a traceback" {
local root="$TMPDIR/pkg"
mkdir -p "$root/.apm/agents"
cat > "$root/apm.yml" <<EOF
name: test-package
version: 0.1.0
type: skill
EOF
run bash "$SCRIPT" "$root/.apm/agents/absent.agent.md"
assert_failure
assert_output --partial "FAIL"
assert_output --partial "could not be read"
assert_output --partial "absent.agent.md"
refute_output --partial "Traceback"
refute_output --partial "FileNotFoundError"
}
@test "an unreadable plugin/APM-scope agent file gets a FAIL naming the path, not a traceback" {
local root="$TMPDIR/pkg-dir"
mkdir -p "$root/.apm/agents/is-a-dir.agent.md"
cat > "$root/apm.yml" <<EOF
name: test-package
version: 0.1.0
type: skill
EOF
run bash "$SCRIPT" "$root/.apm/agents/is-a-dir.agent.md"
assert_failure
assert_output --partial "FAIL"
assert_output --partial "could not be read"
assert_output --partial "is-a-dir.agent.md"
refute_output --partial "Traceback"
refute_output --partial "IsADirectoryError"
}
@test "a nonexistent project-scope agent file gets a FAIL naming the path, not a traceback" {
# The counterpart is pre-checked before either file is opened, so this
# exercises the OTHER call site: the counterpart exists, the named file does
# not, and check_file is what has to report it.
local root="$TMPDIR/proj-missing"
mkdir -p "$root/.git" "$root/.claude/agents" "$root/.github/agents"
cat > "$root/.github/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description. Do not use for anything else.
---
You are a test agent. When invoked, do the thing.
EOF
run bash "$SCRIPT" "$root/.claude/agents/my-agent.md"
assert_failure
assert_output --partial "FAIL"
assert_output --partial "could not be read"
assert_output --partial "my-agent.md"
refute_output --partial "Traceback"
refute_output --partial "FileNotFoundError"
}

2
plugins/kyberforge/.apm/skills/agent-author/SKILL.md
View File

@@ -53,6 +53,8 @@ Gates `agent-audit` enforces at every scope:
- **Body** — no word gate, and a delegation check in its place: name the skill to invoke rather than restating what it does. - **Body** — no word gate, and a delegation check in its place: name the skill to invoke rather than restating what it does.
- **Invocation** — decide whether the agent is model-delegated or reached only by name. Only Copilot's cloud/IDE format expresses that in frontmatter (`disable-model-invocation`, `user-invocable`). - **Invocation** — decide whether the agent is model-delegated or reached only by name. Only Copilot's cloud/IDE format expresses that in frontmatter (`disable-model-invocation`, `user-invocable`).
At every scope, five tools reach no subagent whatever `tools` says — `AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup`, `WaitForMcpServers`. Never write a body that has the agent ask the user a question or enter plan mode; it describes a turn the runtime cannot give it.
## Step 4 — Validate and close ## Step 4 — Validate and close
Invoke `agent-audit` on each file written and resolve every FAIL before reporting done. It checks the field allowlist, name-to-stem match, leftover placeholders and template comments, the description budget and the Copilot body limit — do not hand-check those. Invoke `agent-audit` on each file written and resolve every FAIL before reporting done. It checks the field allowlist, name-to-stem match, leftover placeholders and template comments, the description budget and the Copilot body limit — do not hand-check those.

5
plugins/kyberforge/.apm/skills/agent-author/assets/templates/claude-code.md
View File

@@ -25,12 +25,13 @@ description: FILL IN: Use when <trigger>. <One capability clause.> Not <thing> -
<!-- tools: Read, Bash, Grep <!-- tools: Read, Bash, Grep
Optional. Allowlist of tool names: a comma-separated string or a YAML list. Optional. Allowlist of tool names: a comma-separated string or a YAML list.
Omit to inherit all tools from parent. Restrict it to what the agent actually needs. Omit only when it needs them
all — omitting inherits every tool from the parent.
Use Agent(type1,type2) to restrict which subagent types this agent can spawn. Use Agent(type1,type2) to restrict which subagent types this agent can spawn.
Omit Agent entirely to prevent this agent from spawning subagents. Omit Agent entirely to prevent this agent from spawning subagents.
Never available to subagents regardless of tools field: Never available to subagents regardless of tools field:
AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers
Exception: ExitPlanMode IS available when parent session runs in permissionMode: plan --> Listing any of them is a finding: agent-audit enforces the flat rule. -->
<!-- model: sonnet <!-- model: sonnet
Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID. Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID.

6
plugins/kyberforge/.apm/skills/agent-author/references/contract.md
View File

@@ -70,6 +70,12 @@ that package declares in `apm.yml` under `dependencies.apm`. A sibling plugin in
therefore resolves; a skill in an unrelated repo does not. A target outside that universe sends the therefore resolves; a skill in an unrelated repo does not. A target outside that universe sends the
router nowhere. Verify it before writing it — do not invent a plausible sibling. router nowhere. Verify it before writing it — do not invent a plausible sibling.
That universe is the apm marketplace and stops there. A **host built-in is not a routing target**:
`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI
or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The
gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write
it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked.
**Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only
with YAML folding resolved. Treat 250 as the target: the SUGGESTION tier is what moves the corpus with YAML folding resolved. Treat 250 as the target: the SUGGESTION tier is what moves the corpus
average, the FAIL tier only stops outliers. average, the FAIL tier only stops outliers.

11
plugins/kyberforge/.apm/skills/agent-author/references/improve.md
View File

@@ -57,6 +57,11 @@ procedure a skill it can invoke already owns is an `agent-audit` FAIL. When a si
missing procedure, check first whether an installed skill owns it and name that skill instead of missing procedure, check first whether an installed skill owns it and name that skill instead of
transcribing it. See `references/contract.md`. transcribing it. See `references/contract.md`.
The delegation check is not a length brake — it fires only on procedure an invocable skill already
owns, and says nothing about original prose. That brake is judgment, and it is the only one left:
for every sentence you add, ask "would the agent get this wrong without it?" and delete it if the
answer is no.
**Explain the why.** Reasoning-based instructions outperform rigid directives. A rule written in **Explain the why.** Reasoning-based instructions outperform rigid directives. A rule written in
all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can
apply judgment at the edges. apply judgment at the edges.
@@ -73,4 +78,10 @@ that was already there.
If the edit adds or removes research-sourced content, update `source_keys` in the edited file and If the edit adds or removes research-sourced content, update `source_keys` in the edited file and
the matching `sources.md` entry — the create flow's Step 3 has the rules. the matching `sources.md` entry — the create flow's Step 3 has the rules.
**Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL,
which says nothing about a check that passed *before* these edits and no longer does. Compare the
closing `agent-audit` against the agent's pre-edit state — a PASS that has become a SUGGESTION, or
a SUGGESTION that has become a FAIL, is damage this flow caused and is in scope for it. Only the
improve flow can make that comparison; the create flow has no prior state to compare against.
Then return to `SKILL.md` Step 4. Then return to `SKILL.md` Step 4.

5
plugins/kyberforge/.apm/skills/agent-author/references/plugin-scope.md
View File

@@ -37,6 +37,11 @@ The rule is about a field's *shape*, not a fixed roster:
Claude Code honours it for plugin subagents; the three fields plugin agents do silently ignore Claude Code honours it for plugin subagents; the three fields plugin agents do silently ignore
are `hooks`, `mcpServers` and `permissionMode`, and this is not one of them. Copilot's handling are `hooks`, `mcpServers` and `permissionMode`, and this is not one of them. Copilot's handling
of the key is unconfirmed, which ADR-0016 accepts as a stated risk. of the key is unconfirmed, which ADR-0016 accepts as a stated risk.
Its syntax is the same at every scope, and this is the one scope that cannot reach it anywhere
else: MCP tools are denied as `mcp__<server>`, `mcp__<server>__*` or `mcp__*`; both a YAML list
and a delimited string are accepted, and this repo writes the comma-separated string form
(`disallowedTools: Edit, Write, NotebookEdit`) — match it.
- The Claude-only knobs (`isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`, `skills`, - The Claude-only knobs (`isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`, `skills`,
`color`, `initialPrompt`, `background`, `hooks`, `mcpServers`) have no Copilot equivalent and `color`, `initialPrompt`, `background`, `hooks`, `mcpServers`) have no Copilot equivalent and
are never written to this file at all. "Silently ignored at plugin scope" is the wrong framing: are never written to this file at all. "Silently ignored at plugin scope" is the wrong framing:

5
plugins/kyberforge/.apm/skills/agent-author/references/project-user-scope.md
View File

@@ -25,7 +25,10 @@ duplicate silently.
**`description`** — write it against `references/contract.md`. It is the primary signal for **`description`** — write it against `references/contract.md`. It is the primary signal for
autonomous delegation. autonomous delegation.
**`tools`** — an allowlist; omit it to inherit every tool from the parent. Use `Agent(type1,type2)` **`tools`** — an allowlist. Write it, and restrict it to the tools the agent actually needs;
omitting it inherits every tool from the parent, which is the right value only when the agent
genuinely needs all of them. Least privilege is the default, not the exception. Use
`Agent(type1,type2)`
to restrict which subagent types this agent may spawn, and omit `Agent` entirely to stop it to restrict which subagent types this agent may spawn, and omit `Agent` entirely to stop it
spawning any. Five tools reach no subagent whatever this field says — `AskUserQuestion`, spawning any. Five tools reach no subagent whatever this field says — `AskUserQuestion`,
`EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup` and `WaitForMcpServers` — so listing one buys `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup` and `WaitForMcpServers` — so listing one buys

2
plugins/kyberforge/.apm/skills/skill-audit/SKILL.md
View File

@@ -35,7 +35,7 @@ scripts/vale-wrap.sh <skill-dir>/SKILL.md
`validate.sh` findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both. `validate.sh` findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both.
If any of the three fails, cannot run, or reports something needing interpretation, read `references/validation-scripts.md` — it carries the manual fallback and the misleading exit codes. If any of the three cannot run, or exits non-zero for a reason other than findings, read `references/validation-scripts.md` — it carries the manual fallback and the misleading exit codes. Ordinary content FAILs are the expected outcome here and need no fallback.
`validate-provenance.sh` prints nothing on success. Its FAIL and INFO findings become a separate `### Provenance` dimension, and it emits Why and Fix itself — surface those verbatim. `validate-provenance.sh` prints nothing on success. Its FAIL and INFO findings become a separate `### Provenance` dimension, and it emits Why and Fix itself — surface those verbatim.

6
plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md
View File

@@ -28,8 +28,10 @@ Include content the agent lacks:
- The specific tools or sequences to use — not the full range of options - The specific tools or sequences to use — not the full range of options
- One default per decision point with one escape hatch - One default per decision point with one escape hatch
Move to `references/`, behind an explicit "If X, read `references/file.md`" trigger — the literal Move to `references/`, behind an explicit "If X, read `references/<file>.md`" trigger — the literal
conditional form, never a generic pointer: conditional form, never a generic pointer. Write the real filename in the skill under audit; the
angle brackets are a placeholder here, and a literal `references/file.md` in a body is an ERROR
from the ADR-0020 gate because no such file exists on disk. Move:
- Lookup tables and spec restatements - Lookup tables and spec restatements
- Output schemas, templates and example blocks - Output schemas, templates and example blocks

12
plugins/kyberforge/.apm/skills/skill-audit/references/patterns.md
View File

@@ -32,8 +32,16 @@ read after the mistake.
inner fence as `` \`\`\` ``. An unescaped inner fence terminates the outer block and the remaining inner fence as `` \`\`\` ``. An unescaped inner fence terminates the outer block and the remaining
instructions render as prose. instructions render as prose.
**Conditional references** state a specific trigger: "If the API returns a non-200 status, read **Conditional references** state a specific trigger, naming a file that exists in the skill's own
`references/api-errors.md`." The generic form — pointing at the directory and hoping — defeats `references/` directory:
```text
If the API returns a non-200 status, read `references/api-errors.md`.
```
That block is fenced because the filename in it is illustrative — an unfenced `references/` pointer
in a `SKILL.md` body must resolve on disk or the ADR-0020 gate reports a hard ERROR. The generic
form — pointing at the directory and hoping — defeats
progressive disclosure, because the agent either loads everything or loads nothing. progressive disclosure, because the agent either loads everything or loads nothing.
`Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed `Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed
forms are judgment. forms are judgment.

155
plugins/kyberforge/.apm/skills/skill-audit/scripts/validate.sh
View File

@@ -148,17 +148,21 @@ def read_text(path):
# which is what a monorepo means, # which is what a monorepo means,
# 2. the target's own apm package, # 2. the target's own apm package,
# 3. the packages that package DECLARES in apm.yml dependencies.apm. # 3. the packages that package DECLARES in apm.yml dependencies.apm.
# Deployed .claude/ and .agents/ trees are deliberately NOT consulted in that # Deployed .claude/ and .agents/ trees are deliberately NOT consulted when the
# case. They are `apm install` output, gitignored, and present only on a machine # root came from the plugins/ probe. They are `apm install` output, gitignored,
# that has run it: four cross-plugin targets in this repo (gitea-branches -> # and present only on a machine that has run it: four cross-plugin targets in
# git-branches, gitea-branches -> git-history, gitea-issues -> git-branches, # this repo (gitea-branches -> git-branches, gitea-branches -> git-history,
# gitea-workflow -> git-workflow) resolved through .claude/skills/ alone, so the # gitea-issues -> git-branches, gitea-workflow -> git-workflow) resolved through
# same commit measured 2 dangling targets on a developer machine and 6 on a # .claude/skills/ alone, so the same commit measured 2 dangling targets on a
# fresh clone. A gate shipping hot with no baseline cannot give two answers. # developer machine and 6 on a fresh clone. A gate shipping hot with no baseline
# cannot give two answers.
# #
# Deployed trees are used only when NO authoring root exists — the consumer # Deployed trees ARE used when no plugin monorepo was found — whether the walk
# case, where the file being checked lives in or beside a deployed tree and # landed on a bare .git ancestor or on nothing at all. That is the consumer
# there is no monorepo to read. # case: the file being checked lives in or beside a deployed tree, inside an
# ordinary git repo, with no monorepo to read. The two cases are told apart by
# which probe matched, never by how many names a root contributed; see
# known_targets().
def _is_fs_root(path): def _is_fs_root(path):
@@ -167,11 +171,17 @@ def _is_fs_root(path):
def _collect_package(pkg_dir, names): def _collect_package(pkg_dir, names):
"""Add every skill/agent name a package directory exposes, any layout.""" """Add every skill/agent name a package directory exposes, any layout."""
# glob.escape() the DIRECTORY only. A checkout path containing `[`, `]`,
# `*` or `?` — a worktree named `feature[2]`, say — otherwise turns the
# whole pattern into a character class that matches nothing, and the
# resolver degrades to the "DID NOT RUN" INFO with rc=0 across every file
# in the tree. The wildcards in `sub` are the intended ones and stay raw.
safe_dir = glob.escape(pkg_dir)
for sub in ('.apm/skills/*/', 'skills/*/'): for sub in ('.apm/skills/*/', 'skills/*/'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
names.add(os.path.basename(path.rstrip('/')).lower()) names.add(os.path.basename(path.rstrip('/')).lower())
for sub in ('.apm/agents/*.md', 'agents/*.md'): for sub in ('.apm/agents/*.md', 'agents/*.md'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
base = os.path.basename(path) base = os.path.basename(path)
if base.endswith('.agent.md'): if base.endswith('.agent.md'):
base = base[:-len('.agent.md')] base = base[:-len('.agent.md')]
@@ -203,28 +213,35 @@ def _apm_package_root(start_dir):
def _authoring_root(start_dir): def _authoring_root(start_dir):
"""Nearest ancestor that is a plugin monorepo, else the nearest .git tree. """Nearest ancestor that is a plugin monorepo, else the nearest .git tree.
Returns (root, matched_plugins_probe). The flag reports WHICH probe
matched: True for the plugins/*/.apm/{skills,agents} glob, False for the
.git fallback and for no match at all. known_targets() needs that
distinction — only a real plugins/ root makes the deployed trees
redundant, and a name-count delta cannot tell the two apart.
Two passes, not one interleaved walk: a nested .git (a submodule, a Two passes, not one interleaved walk: a nested .git (a submodule, a
worktree of a sub-package) must not win over a real plugins/ root further worktree of a sub-package) must not win over a real plugins/ root further
up. Both passes stop before the filesystem root for the same reason up. Both passes stop before the filesystem root for the same reason
_apm_package_root does. _apm_package_root does.
""" """
for probe in ( probes = (
lambda d: bool(glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'skills')) lambda d: bool(glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'skills'))
or glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'agents'))), or glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'agents'))),
lambda d: os.path.exists(os.path.join(d, '.git'))): lambda d: os.path.exists(os.path.join(d, '.git')))
for index, probe in enumerate(probes):
current = os.path.abspath(start_dir) current = os.path.abspath(start_dir)
for _ in range(12): for _ in range(12):
if _is_fs_root(current): if _is_fs_root(current):
break break
if probe(current): if probe(current):
return current return current, index == 0
current = os.path.dirname(current) current = os.path.dirname(current)
return None return None, False
def _collect_authoring_root(root, names): def _collect_authoring_root(root, names):
"""Every plugin in the monorepo contributes its names.""" """Every plugin in the monorepo contributes its names."""
for pkg in glob.glob(os.path.join(root, 'plugins', '*')): for pkg in glob.glob(os.path.join(glob.escape(root), 'plugins', '*')):
if os.path.isdir(pkg): if os.path.isdir(pkg):
_collect_package(pkg, names) _collect_package(pkg, names)
@@ -288,7 +305,7 @@ def _declared_dependency_dirs(pkg_dir):
def _deployed_roots(start_dir): def _deployed_roots(start_dir):
""".claude/ and .agents/ trees above start_dir — what a host really sees. """.claude/ and .agents/ trees above start_dir — what a host really sees.
Consulted ONLY when no authoring root exists; see the section header. The Consulted ONLY when no plugin monorepo root was found; see the header. The
filesystem root is skipped for the same reason _apm_package_root skips it: filesystem root is skipped for the same reason _apm_package_root skips it:
a stray /.claude/skills/ must not join every path's universe. a stray /.claude/skills/ must not join every path's universe.
""" """
@@ -327,10 +344,22 @@ def known_targets(start_dir):
for dep_dir in _declared_dependency_dirs(package): for dep_dir in _declared_dependency_dirs(package):
_collect_package(dep_dir, names) _collect_package(dep_dir, names)
root = _authoring_root(start) # A .git ancestor is an authoring root only if it actually holds plugins.
# _authoring_root() falls back to the nearest .git, so it is truthy in ANY
# git repo; without the distinction that fallback wins in every consumer
# checkout, _collect_authoring_root() contributes nothing, and the deployed
# branch below is dead code in the exact case it exists for. So condition
# on WHICH probe matched, which _authoring_root() reports directly. A
# name-count delta looks equivalent and is not: _collect_authoring_root()
# re-collects the checked file's own plugin, whose names the blocks above
# already added, so a one-plugin monorepo shows a delta of zero and would
# wrongly reach for the deployed trees — including the user's global
# ~/.claude/skills, making the verdict depend on what happens to be
# installed (ADR-0020 lines 118-127).
root, root_has_plugins = _authoring_root(start)
if root: if root:
_collect_authoring_root(root, names) _collect_authoring_root(root, names)
else: if not root_has_plugins:
for base in _deployed_roots(start): for base in _deployed_roots(start):
_collect_package(base, names) _collect_package(base, names)
return names return names
@@ -436,16 +465,43 @@ MARKED_TARGET = r"(?:`/?(%s)`|(?<![\w./*-])/(%s)\b)" % (NAME_ANY, NAME_ANY)
ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH) ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH)
ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I) ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I)
ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I) ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I)
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET) # re.I on ALL of them, uniformly. The patterns are built from the same
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET) # lowercase NAME_* fragments, so half of them carrying the flag and half not
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET) # meant `Skill-Audit` at the start of a boundary sentence was extracted by
# ROUTE_ANY but invisible to BACKTICK — contradicting normalize_target()'s own
# docstring, which exists precisely because extraction is case-insensitive and
# the universe is not.
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET, re.I)
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET, re.I)
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET, re.I)
ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I) ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I)
BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH) BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH, re.I)
# A boundary clause takes two shapes and BOTH count: the prose markers, and # A boundary clause takes two shapes and BOTH count: the prose markers, and
# ADR-0020's compressed arrow form `Not <thing> -> <name>`. # ADR-0020's compressed arrow form `Not <thing> -> <name>`.
BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I) BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I)
BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I) BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I)
SENTENCE_SPLIT = re.compile(u'(?<=[.!?])\\s+(?=[A-Z"“(])') # Sentence boundaries decide the CORROBORATION scope above, so getting one wrong
# is not cosmetic — it moves a target between SUGGESTION and blocking ERROR. Two
# shapes common in these descriptions defeat the naive "period, space, capital"
# rule, in OPPOSITE directions:
# OVER-SPLIT. `e.g. "set up the manifest"` ends no sentence, but the quote
# looks like one starting. The clause is cut in half, the corroborating
# target lands on the far side of the cut, and a genuinely dangling target
# silently demotes to SUGGESTION — the gate takes a measurement and then
# throws it away, which is the vacuous-green shape this file exists to stop.
# UNDER-SPLIT. A real sentence opening with a code span or a lowercase skill
# name ("... Composes it. `gitea-prs` also uses it.") is not seen as a start
# at all, so two sentences merge and a resolving target vouches for an
# unresolvable one it never stood beside — a hard FAIL with no escape hatch,
# which is exactly the failure the corroboration rule was added to prevent.
# Both are closed here: the five abbreviations that actually occur in routing
# prose are excluded as sentence ends, and the opener class admits a backtick or
# a lowercase letter. Verified zero-delta on the current corpus (37 ERROR / 58
# SUGGESTION / 2 dangling before and after) — this protects the descriptions
# issue #99 is about to rewrite, not the ones already measured.
SENTENCE_SPLIT = re.compile(
u'(?<!\\be\\.g\\.)(?<!\\bi\\.e\\.)(?<!\\betc\\.)(?<!\\bvs\\.)(?<!\\bcf\\.)'
u'(?<=[.!?])\\s+(?=[A-Za-z`"“(])')
# The token that may follow a route target without turning it into a compound # The token that may follow a route target without turning it into a compound
# modifier: punctuation, end of sentence, a conjunction, a boundary word, or a # modifier: punctuation, end of sentence, a conjunction, a boundary word, or a
@@ -607,8 +663,16 @@ def unresolved_targets(description, known):
# description with a 1,000-word body exited 0 behind a BOM). A file that cannot # description with a 1,000-word body exited 0 behind a BOM). A file that cannot
# be measured must never report green, so every caller of these two ERRORs on a # be measured must never report green, so every caller of these two ERRORs on a
# miss instead of moving on. # miss instead of moving on.
#
# The CLOSING marker is anchored at column 0 — deliberately NOT `[ \t]*---`.
# YAML block-scalar content must be indented deeper than its key, so an
# indented `---` inside a folded description is CONTENT; letting it close the
# frontmatter truncated the description mid-value and silently reclassified the
# rest as body, which is a vacuous green in both directions at once. Leading
# whitespace is still tolerated on the OPENING marker, where no such content
# can exist.
FRONTMATTER_RE = re.compile( FRONTMATTER_RE = re.compile(
r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n[ \t]*---[ \t]*(?:\r?\n|\Z)', re.DOTALL) r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)', re.DOTALL)
def strip_bom(text): def strip_bom(text):
@@ -640,14 +704,26 @@ def description_value(fm_text):
try: try:
data = yaml.safe_load(fm_text) data = yaml.safe_load(fm_text)
except Exception as exc: except Exception as exc:
raise FrontmatterError(re.sub(r'\s+', ' ', str(exc)).strip()) # Every FrontmatterError message is a COMPLETE clause, never a detail a
# caller wraps in one. Callers used to prefix a hard-coded "frontmatter
# is not valid YAML (...)", which is true only of this branch: the two
# type failures below come from frontmatter that parsed fine, and
# telling their author the YAML is invalid sends them hunting for a
# syntax error that is not there — on a blocking gate with no baseline.
raise FrontmatterError('frontmatter is not valid YAML (%s)'
% re.sub(r'\s+', ' ', str(exc)).strip())
if not isinstance(data, dict): if not isinstance(data, dict):
raise FrontmatterError('frontmatter is not a YAML mapping') raise FrontmatterError('frontmatter is not a YAML mapping')
value = data.get('description') value = data.get('description')
if value is None: if value is None:
return '' return ''
if not isinstance(value, str): if not isinstance(value, str):
value = str(value) # NOT str()-coerced. `description: true` became the 4-character "True"
# and sailed through the 400-character gate; a list or mapping was
# measured as its Python repr. Neither is a description a host can
# preload, so this is a parse failure, reported as one.
raise FrontmatterError(
'description is a %s, not a string' % type(value).__name__)
return re.sub(r'\s+', ' ', value).strip() return re.sub(r'\s+', ' ', value).strip()
@@ -717,6 +793,18 @@ def mask_fenced(text):
if (marker and marker[0] == fence[0] and len(marker) >= len(fence) if (marker and marker[0] == fence[0] and len(marker) >= len(fence)
and not stripped.strip()[len(marker):].strip()): and not stripped.strip()[len(marker):].strip()):
fence = None fence = None
# An UNCLOSED fence has no cost-free answer, only a choice of which way to
# be wrong. Masking to end-of-body blanks the rest of the body, silently
# disabling the ERROR-tier references/ check and the gotcha counts.
# Returning the raw text instead exposes the unclosed example's own
# content, so a fenced example naming a nonexistent references/ file
# becomes a hard ERROR it would not have been had the fence been closed —
# confirmed, not hypothetical. The loud-false-positive direction is the one
# chosen: this script's rule is that a file it cannot measure must never
# report green, and masking-onward is exactly that failure. Both outcomes
# need an already-malformed file, and the false positive costs one fence.
if fence is not None:
return text
return ''.join(out) return ''.join(out)
@@ -802,8 +890,11 @@ name = name_m.group(1).strip('"\'') if name_m else ""
try: try:
desc = description_value(fm) desc = description_value(fm)
except FrontmatterError as exc: except FrontmatterError as exc:
fail(f"frontmatter is not valid YAML ({exc}). Nothing downstream can be " # `exc` carries the whole clause — invalid YAML, a non-mapping block, or a
f"measured, so this is a hard failure, not a skip") # description of the wrong type. Do not prefix a diagnosis here; the last
# one named a syntax error for two failures that have none.
fail(f"{exc}. Nothing downstream can be measured, so this is a hard "
f"failure, not a skip")
print("One or more checks failed.") print("One or more checks failed.")
sys.exit(1) sys.exit(1)

6
plugins/kyberforge/.apm/skills/skill-author/references/contract.md
View File

@@ -57,6 +57,12 @@ therefore resolves; a skill in an unrelated repo does not. A boundary clause nam
outside that universe sends the router nowhere and fails the audit. Check the target exists before outside that universe sends the router nowhere and fails the audit. Check the target exists before
writing it — do not invent a plausible sibling name. writing it — do not invent a plausible sibling name.
That universe is the apm marketplace and stops there. A **host built-in is not a routing target**:
`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI
or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The
gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write
it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked.
**Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only
with YAML folding resolved. The agentskills.io 1,024-character spec limit is unchanged and sits with YAML folding resolved. The agentskills.io 1,024-character spec limit is unchanged and sits
above both. The SUGGESTION tier is the one that moves the average; treat 250 as the target and 400 above both. The SUGGESTION tier is the one that moves the average; treat 250 as the target and 400

6
plugins/kyberforge/.apm/skills/skill-author/references/improve.md
View File

@@ -85,4 +85,10 @@ improvise the cuts — four dry runs invented six to ten different answers to th
If a signal points to a script or reference file, edit that file directly rather than adding a If a signal points to a script or reference file, edit that file directly rather than adding a
workaround in SKILL.md. workaround in SKILL.md.
**Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL,
which says nothing about a check that passed *before* these edits and no longer does. Compare the
closing audit against the skill's pre-edit state — a PASS that has become a SUGGESTION, or a
SUGGESTION that has become a FAIL, is damage this flow caused and is in scope for it. Only the
improve flow can make that comparison; the create flow has no prior state to compare against.
Then return to `SKILL.md` Step 4. Then return to `SKILL.md` Step 4.

9
plugins/kyberforge/skills/agent-audit/references/description-quality.md
View File

@@ -111,9 +111,12 @@ Flag as FAIL if:
available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is
judgment. judgment.
- **A boundary clause naming a target that does not resolve** to a real skill directory or agent - **A boundary clause naming a target that does not resolve** to a real skill directory or agent
file in the authoring source. No script checks this for an agent file — `validate.sh` resolves file in the authoring source. `validate.sh` resolves this for agent files at both scopes and
boundary targets for skills only, so resolve the name yourself against `plugins/*/.apm/skills/` reports each unresolved target itself — take its verdict rather than re-resolving the name by
and `plugins/*/.apm/agents/`. hand, because a hand-walk over a different universe can contradict it. What is left to you is
semantic and the script cannot reach it: whether a target that *does* resolve is the right
sibling to exclude, and whether a clause naming no target at all ("examine the files manually")
should have named one.
- **`Use proactively` in a Copilot or vendor-neutral description.** - **`Use proactively` in a Copilot or vendor-neutral description.**
`KyberforgeCopilot.ProactivePhrase` catches it. The phrase steers the Claude Code runtime and `KyberforgeCopilot.ProactivePhrase` catches it. The phrase steers the Claude Code runtime and
does nothing anywhere else, so in a `.agent.md` it is preloaded text that buys no behaviour. does nothing anywhere else, so in a `.agent.md` it is preloaded text that buys no behaviour.

201
plugins/kyberforge/skills/agent-audit/scripts/validate.sh
View File

@@ -222,17 +222,21 @@ def read_text(path):
# which is what a monorepo means, # which is what a monorepo means,
# 2. the target's own apm package, # 2. the target's own apm package,
# 3. the packages that package DECLARES in apm.yml dependencies.apm. # 3. the packages that package DECLARES in apm.yml dependencies.apm.
# Deployed .claude/ and .agents/ trees are deliberately NOT consulted in that # Deployed .claude/ and .agents/ trees are deliberately NOT consulted when the
# case. They are `apm install` output, gitignored, and present only on a machine # root came from the plugins/ probe. They are `apm install` output, gitignored,
# that has run it: four cross-plugin targets in this repo (gitea-branches -> # and present only on a machine that has run it: four cross-plugin targets in
# git-branches, gitea-branches -> git-history, gitea-issues -> git-branches, # this repo (gitea-branches -> git-branches, gitea-branches -> git-history,
# gitea-workflow -> git-workflow) resolved through .claude/skills/ alone, so the # gitea-issues -> git-branches, gitea-workflow -> git-workflow) resolved through
# same commit measured 2 dangling targets on a developer machine and 6 on a # .claude/skills/ alone, so the same commit measured 2 dangling targets on a
# fresh clone. A gate shipping hot with no baseline cannot give two answers. # developer machine and 6 on a fresh clone. A gate shipping hot with no baseline
# cannot give two answers.
# #
# Deployed trees are used only when NO authoring root exists — the consumer # Deployed trees ARE used when no plugin monorepo was found — whether the walk
# case, where the file being checked lives in or beside a deployed tree and # landed on a bare .git ancestor or on nothing at all. That is the consumer
# there is no monorepo to read. # case: the file being checked lives in or beside a deployed tree, inside an
# ordinary git repo, with no monorepo to read. The two cases are told apart by
# which probe matched, never by how many names a root contributed; see
# known_targets().
def _is_fs_root(path): def _is_fs_root(path):
@@ -241,11 +245,17 @@ def _is_fs_root(path):
def _collect_package(pkg_dir, names): def _collect_package(pkg_dir, names):
"""Add every skill/agent name a package directory exposes, any layout.""" """Add every skill/agent name a package directory exposes, any layout."""
# glob.escape() the DIRECTORY only. A checkout path containing `[`, `]`,
# `*` or `?` — a worktree named `feature[2]`, say — otherwise turns the
# whole pattern into a character class that matches nothing, and the
# resolver degrades to the "DID NOT RUN" INFO with rc=0 across every file
# in the tree. The wildcards in `sub` are the intended ones and stay raw.
safe_dir = glob.escape(pkg_dir)
for sub in ('.apm/skills/*/', 'skills/*/'): for sub in ('.apm/skills/*/', 'skills/*/'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
names.add(os.path.basename(path.rstrip('/')).lower()) names.add(os.path.basename(path.rstrip('/')).lower())
for sub in ('.apm/agents/*.md', 'agents/*.md'): for sub in ('.apm/agents/*.md', 'agents/*.md'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
base = os.path.basename(path) base = os.path.basename(path)
if base.endswith('.agent.md'): if base.endswith('.agent.md'):
base = base[:-len('.agent.md')] base = base[:-len('.agent.md')]
@@ -277,28 +287,35 @@ def _apm_package_root(start_dir):
def _authoring_root(start_dir): def _authoring_root(start_dir):
"""Nearest ancestor that is a plugin monorepo, else the nearest .git tree. """Nearest ancestor that is a plugin monorepo, else the nearest .git tree.
Returns (root, matched_plugins_probe). The flag reports WHICH probe
matched: True for the plugins/*/.apm/{skills,agents} glob, False for the
.git fallback and for no match at all. known_targets() needs that
distinction — only a real plugins/ root makes the deployed trees
redundant, and a name-count delta cannot tell the two apart.
Two passes, not one interleaved walk: a nested .git (a submodule, a Two passes, not one interleaved walk: a nested .git (a submodule, a
worktree of a sub-package) must not win over a real plugins/ root further worktree of a sub-package) must not win over a real plugins/ root further
up. Both passes stop before the filesystem root for the same reason up. Both passes stop before the filesystem root for the same reason
_apm_package_root does. _apm_package_root does.
""" """
for probe in ( probes = (
lambda d: bool(glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'skills')) lambda d: bool(glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'skills'))
or glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'agents'))), or glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'agents'))),
lambda d: os.path.exists(os.path.join(d, '.git'))): lambda d: os.path.exists(os.path.join(d, '.git')))
for index, probe in enumerate(probes):
current = os.path.abspath(start_dir) current = os.path.abspath(start_dir)
for _ in range(12): for _ in range(12):
if _is_fs_root(current): if _is_fs_root(current):
break break
if probe(current): if probe(current):
return current return current, index == 0
current = os.path.dirname(current) current = os.path.dirname(current)
return None return None, False
def _collect_authoring_root(root, names): def _collect_authoring_root(root, names):
"""Every plugin in the monorepo contributes its names.""" """Every plugin in the monorepo contributes its names."""
for pkg in glob.glob(os.path.join(root, 'plugins', '*')): for pkg in glob.glob(os.path.join(glob.escape(root), 'plugins', '*')):
if os.path.isdir(pkg): if os.path.isdir(pkg):
_collect_package(pkg, names) _collect_package(pkg, names)
@@ -362,7 +379,7 @@ def _declared_dependency_dirs(pkg_dir):
def _deployed_roots(start_dir): def _deployed_roots(start_dir):
""".claude/ and .agents/ trees above start_dir — what a host really sees. """.claude/ and .agents/ trees above start_dir — what a host really sees.
Consulted ONLY when no authoring root exists; see the section header. The Consulted ONLY when no plugin monorepo root was found; see the header. The
filesystem root is skipped for the same reason _apm_package_root skips it: filesystem root is skipped for the same reason _apm_package_root skips it:
a stray /.claude/skills/ must not join every path's universe. a stray /.claude/skills/ must not join every path's universe.
""" """
@@ -401,10 +418,22 @@ def known_targets(start_dir):
for dep_dir in _declared_dependency_dirs(package): for dep_dir in _declared_dependency_dirs(package):
_collect_package(dep_dir, names) _collect_package(dep_dir, names)
root = _authoring_root(start) # A .git ancestor is an authoring root only if it actually holds plugins.
# _authoring_root() falls back to the nearest .git, so it is truthy in ANY
# git repo; without the distinction that fallback wins in every consumer
# checkout, _collect_authoring_root() contributes nothing, and the deployed
# branch below is dead code in the exact case it exists for. So condition
# on WHICH probe matched, which _authoring_root() reports directly. A
# name-count delta looks equivalent and is not: _collect_authoring_root()
# re-collects the checked file's own plugin, whose names the blocks above
# already added, so a one-plugin monorepo shows a delta of zero and would
# wrongly reach for the deployed trees — including the user's global
# ~/.claude/skills, making the verdict depend on what happens to be
# installed (ADR-0020 lines 118-127).
root, root_has_plugins = _authoring_root(start)
if root: if root:
_collect_authoring_root(root, names) _collect_authoring_root(root, names)
else: if not root_has_plugins:
for base in _deployed_roots(start): for base in _deployed_roots(start):
_collect_package(base, names) _collect_package(base, names)
return names return names
@@ -510,16 +539,43 @@ MARKED_TARGET = r"(?:`/?(%s)`|(?<![\w./*-])/(%s)\b)" % (NAME_ANY, NAME_ANY)
ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH) ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH)
ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I) ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I)
ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I) ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I)
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET) # re.I on ALL of them, uniformly. The patterns are built from the same
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET) # lowercase NAME_* fragments, so half of them carrying the flag and half not
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET) # meant `Skill-Audit` at the start of a boundary sentence was extracted by
# ROUTE_ANY but invisible to BACKTICK — contradicting normalize_target()'s own
# docstring, which exists precisely because extraction is case-insensitive and
# the universe is not.
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET, re.I)
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET, re.I)
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET, re.I)
ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I) ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I)
BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH) BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH, re.I)
# A boundary clause takes two shapes and BOTH count: the prose markers, and # A boundary clause takes two shapes and BOTH count: the prose markers, and
# ADR-0020's compressed arrow form `Not <thing> -> <name>`. # ADR-0020's compressed arrow form `Not <thing> -> <name>`.
BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I) BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I)
BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I) BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I)
SENTENCE_SPLIT = re.compile(u'(?<=[.!?])\\s+(?=[A-Z"“(])') # Sentence boundaries decide the CORROBORATION scope above, so getting one wrong
# is not cosmetic — it moves a target between SUGGESTION and blocking ERROR. Two
# shapes common in these descriptions defeat the naive "period, space, capital"
# rule, in OPPOSITE directions:
# OVER-SPLIT. `e.g. "set up the manifest"` ends no sentence, but the quote
# looks like one starting. The clause is cut in half, the corroborating
# target lands on the far side of the cut, and a genuinely dangling target
# silently demotes to SUGGESTION — the gate takes a measurement and then
# throws it away, which is the vacuous-green shape this file exists to stop.
# UNDER-SPLIT. A real sentence opening with a code span or a lowercase skill
# name ("... Composes it. `gitea-prs` also uses it.") is not seen as a start
# at all, so two sentences merge and a resolving target vouches for an
# unresolvable one it never stood beside — a hard FAIL with no escape hatch,
# which is exactly the failure the corroboration rule was added to prevent.
# Both are closed here: the five abbreviations that actually occur in routing
# prose are excluded as sentence ends, and the opener class admits a backtick or
# a lowercase letter. Verified zero-delta on the current corpus (37 ERROR / 58
# SUGGESTION / 2 dangling before and after) — this protects the descriptions
# issue #99 is about to rewrite, not the ones already measured.
SENTENCE_SPLIT = re.compile(
u'(?<!\\be\\.g\\.)(?<!\\bi\\.e\\.)(?<!\\betc\\.)(?<!\\bvs\\.)(?<!\\bcf\\.)'
u'(?<=[.!?])\\s+(?=[A-Za-z`"“(])')
# The token that may follow a route target without turning it into a compound # The token that may follow a route target without turning it into a compound
# modifier: punctuation, end of sentence, a conjunction, a boundary word, or a # modifier: punctuation, end of sentence, a conjunction, a boundary word, or a
@@ -681,8 +737,16 @@ def unresolved_targets(description, known):
# description with a 1,000-word body exited 0 behind a BOM). A file that cannot # description with a 1,000-word body exited 0 behind a BOM). A file that cannot
# be measured must never report green, so every caller of these two ERRORs on a # be measured must never report green, so every caller of these two ERRORs on a
# miss instead of moving on. # miss instead of moving on.
#
# The CLOSING marker is anchored at column 0 — deliberately NOT `[ \t]*---`.
# YAML block-scalar content must be indented deeper than its key, so an
# indented `---` inside a folded description is CONTENT; letting it close the
# frontmatter truncated the description mid-value and silently reclassified the
# rest as body, which is a vacuous green in both directions at once. Leading
# whitespace is still tolerated on the OPENING marker, where no such content
# can exist.
FRONTMATTER_RE = re.compile( FRONTMATTER_RE = re.compile(
r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n[ \t]*---[ \t]*(?:\r?\n|\Z)', re.DOTALL) r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)', re.DOTALL)
def strip_bom(text): def strip_bom(text):
@@ -714,14 +778,26 @@ def description_value(fm_text):
try: try:
data = yaml.safe_load(fm_text) data = yaml.safe_load(fm_text)
except Exception as exc: except Exception as exc:
raise FrontmatterError(re.sub(r'\s+', ' ', str(exc)).strip()) # Every FrontmatterError message is a COMPLETE clause, never a detail a
# caller wraps in one. Callers used to prefix a hard-coded "frontmatter
# is not valid YAML (...)", which is true only of this branch: the two
# type failures below come from frontmatter that parsed fine, and
# telling their author the YAML is invalid sends them hunting for a
# syntax error that is not there — on a blocking gate with no baseline.
raise FrontmatterError('frontmatter is not valid YAML (%s)'
% re.sub(r'\s+', ' ', str(exc)).strip())
if not isinstance(data, dict): if not isinstance(data, dict):
raise FrontmatterError('frontmatter is not a YAML mapping') raise FrontmatterError('frontmatter is not a YAML mapping')
value = data.get('description') value = data.get('description')
if value is None: if value is None:
return '' return ''
if not isinstance(value, str): if not isinstance(value, str):
value = str(value) # NOT str()-coerced. `description: true` became the 4-character "True"
# and sailed through the 400-character gate; a list or mapping was
# measured as its Python repr. Neither is a description a host can
# preload, so this is a parse failure, reported as one.
raise FrontmatterError(
'description is a %s, not a string' % type(value).__name__)
return re.sub(r'\s+', ' ', value).strip() return re.sub(r'\s+', ' ', value).strip()
@@ -791,6 +867,18 @@ def mask_fenced(text):
if (marker and marker[0] == fence[0] and len(marker) >= len(fence) if (marker and marker[0] == fence[0] and len(marker) >= len(fence)
and not stripped.strip()[len(marker):].strip()): and not stripped.strip()[len(marker):].strip()):
fence = None fence = None
# An UNCLOSED fence has no cost-free answer, only a choice of which way to
# be wrong. Masking to end-of-body blanks the rest of the body, silently
# disabling the ERROR-tier references/ check and the gotcha counts.
# Returning the raw text instead exposes the unclosed example's own
# content, so a fenced example naming a nonexistent references/ file
# becomes a hard ERROR it would not have been had the fence been closed —
# confirmed, not hypothetical. The loud-false-positive direction is the one
# chosen: this script's rule is that a file it cannot measure must never
# report green, and masking-onward is exactly that failure. Both outcomes
# need an already-malformed file, and the false positive costs one fence.
if fence is not None:
return text
return ''.join(out) return ''.join(out)
@@ -869,12 +957,15 @@ def get_frontmatter_keys(fm):
return keys return keys
def agent_description(fm, local_fname): def agent_description(fm, local_fname):
"""The folded description VALUE, or None if the frontmatter is not YAML.""" """The folded description VALUE, or None if it could not be read."""
try: try:
return description_value(fm) return description_value(fm)
except FrontmatterError as exc: except FrontmatterError as exc:
fail(f"frontmatter is not valid YAML ({exc}) — the ADR-0020 description and " # `exc` carries the whole clause — invalid YAML, a non-mapping block, or
f"boundary-target gates could not run — {local_fname}") # a description of the wrong type. Do not prefix a diagnosis here; the
# last one named a syntax error for two failures that have none.
fail(f"{exc} — the ADR-0020 description and boundary-target gates could "
f"not run — {local_fname}")
return None return None
def check_description_budget(value, local_fname): def check_description_budget(value, local_fname):
@@ -944,11 +1035,31 @@ def check_boundary(value, fpath, local_fname):
f"{local_fname}") f"{local_fname}")
def extract_tools_list(fm): def extract_tools_list(fm):
"""Extract tool names from the tools frontmatter field (space or comma separated).""" """Tool names from the `tools` field — inline scalar OR YAML block sequence.
val = extract_field(fm, 'tools')
if not val: Read off the PARSED mapping, never off extract_field(). That function's
capture is newline-bounded on purpose (`[^\\S\\r\\n]*(.+)`), so a `tools:`
written as a block sequence — the shape Copilot agent files use — captured
nothing at all and the subagent-unavailable-tool check silently stopped
firing on exactly the files it was written for. Both spellings are legal
YAML, so both are read here.
"""
try:
data = yaml.safe_load(fm)
except Exception:
# Not this function's failure to report: the frontmatter's validity is
# decided (and failed) by agent_description() on the same text.
return set() return set()
return set(re.split(r'[\s,]+', val.strip())) if not isinstance(data, dict):
return set()
val = data.get('tools')
if isinstance(val, list):
items = [str(item).strip() for item in val]
elif isinstance(val, str):
items = re.split(r'[\s,]+', val.strip())
else:
return set()
return {item for item in items if item}
def is_copilot_cloud_ide(fpath): def is_copilot_cloud_ide(fpath):
"""True if the file is a cloud/IDE Copilot agent (name is optional for these).""" """True if the file is a cloud/IDE Copilot agent (name is optional for these)."""
@@ -1063,6 +1174,15 @@ def check_apm_agent_file(fpath, allowlist, stem):
fail(f"file is {exc}. Nothing could be measured, so this is a hard " fail(f"file is {exc}. Nothing could be measured, so this is a hard "
f"failure, not a skip — {local_fname}") f"failure, not a skip — {local_fname}")
return return
except OSError as exc:
# A path that cannot be opened gets a FAIL line naming it, not a bare
# FileNotFoundError traceback. scripts/check-apm-agents-valid.sh takes
# this path for an agent file deleted from the worktree but still
# tracked in the index — a real, expected state, and the caller needs to
# be told which file, not handed an interpreter stack.
fail(f"could not be read ({exc.strerror or exc}): {fpath}. Nothing could "
f"be measured, so this is a hard failure, not a skip — {local_fname}")
return
fm, body = parse_frontmatter(content) fm, body = parse_frontmatter(content)
if fm is None: if fm is None:
@@ -1168,6 +1288,13 @@ def check_file(fpath, file_provider):
fail(f"file is {exc}. Nothing could be measured, so this is a hard " fail(f"file is {exc}. Nothing could be measured, so this is a hard "
f"failure, not a skip — {local_fname}") f"failure, not a skip — {local_fname}")
return return
except OSError as exc:
# Same reason as check_apm_agent_file's: a diagnostic naming the path
# beats a FileNotFoundError traceback. The counterpart is pre-checked at
# the bottom of this script, but agent_file itself never was.
fail(f"could not be read ({exc.strerror or exc}): {fpath}. Nothing could "
f"be measured, so this is a hard failure, not a skip — {local_fname}")
return
fm, body = parse_frontmatter(content) fm, body = parse_frontmatter(content)
if fm is None: if fm is None:

2
plugins/kyberforge/skills/agent-author/SKILL.md
View File

@@ -53,6 +53,8 @@ Gates `agent-audit` enforces at every scope:
- **Body** — no word gate, and a delegation check in its place: name the skill to invoke rather than restating what it does. - **Body** — no word gate, and a delegation check in its place: name the skill to invoke rather than restating what it does.
- **Invocation** — decide whether the agent is model-delegated or reached only by name. Only Copilot's cloud/IDE format expresses that in frontmatter (`disable-model-invocation`, `user-invocable`). - **Invocation** — decide whether the agent is model-delegated or reached only by name. Only Copilot's cloud/IDE format expresses that in frontmatter (`disable-model-invocation`, `user-invocable`).
At every scope, five tools reach no subagent whatever `tools` says — `AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup`, `WaitForMcpServers`. Never write a body that has the agent ask the user a question or enter plan mode; it describes a turn the runtime cannot give it.
## Step 4 — Validate and close ## Step 4 — Validate and close
Invoke `agent-audit` on each file written and resolve every FAIL before reporting done. It checks the field allowlist, name-to-stem match, leftover placeholders and template comments, the description budget and the Copilot body limit — do not hand-check those. Invoke `agent-audit` on each file written and resolve every FAIL before reporting done. It checks the field allowlist, name-to-stem match, leftover placeholders and template comments, the description budget and the Copilot body limit — do not hand-check those.

5
plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md
View File

@@ -25,12 +25,13 @@ description: FILL IN: Use when <trigger>. <One capability clause.> Not <thing> -
<!-- tools: Read, Bash, Grep <!-- tools: Read, Bash, Grep
Optional. Allowlist of tool names: a comma-separated string or a YAML list. Optional. Allowlist of tool names: a comma-separated string or a YAML list.
Omit to inherit all tools from parent. Restrict it to what the agent actually needs. Omit only when it needs them
all — omitting inherits every tool from the parent.
Use Agent(type1,type2) to restrict which subagent types this agent can spawn. Use Agent(type1,type2) to restrict which subagent types this agent can spawn.
Omit Agent entirely to prevent this agent from spawning subagents. Omit Agent entirely to prevent this agent from spawning subagents.
Never available to subagents regardless of tools field: Never available to subagents regardless of tools field:
AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers
Exception: ExitPlanMode IS available when parent session runs in permissionMode: plan --> Listing any of them is a finding: agent-audit enforces the flat rule. -->
<!-- model: sonnet <!-- model: sonnet
Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID. Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID.

6
plugins/kyberforge/skills/agent-author/references/contract.md
View File

@@ -70,6 +70,12 @@ that package declares in `apm.yml` under `dependencies.apm`. A sibling plugin in
therefore resolves; a skill in an unrelated repo does not. A target outside that universe sends the therefore resolves; a skill in an unrelated repo does not. A target outside that universe sends the
router nowhere. Verify it before writing it — do not invent a plausible sibling. router nowhere. Verify it before writing it — do not invent a plausible sibling.
That universe is the apm marketplace and stops there. A **host built-in is not a routing target**:
`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI
or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The
gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write
it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked.
**Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only
with YAML folding resolved. Treat 250 as the target: the SUGGESTION tier is what moves the corpus with YAML folding resolved. Treat 250 as the target: the SUGGESTION tier is what moves the corpus
average, the FAIL tier only stops outliers. average, the FAIL tier only stops outliers.

11
plugins/kyberforge/skills/agent-author/references/improve.md
View File

@@ -57,6 +57,11 @@ procedure a skill it can invoke already owns is an `agent-audit` FAIL. When a si
missing procedure, check first whether an installed skill owns it and name that skill instead of missing procedure, check first whether an installed skill owns it and name that skill instead of
transcribing it. See `references/contract.md`. transcribing it. See `references/contract.md`.
The delegation check is not a length brake — it fires only on procedure an invocable skill already
owns, and says nothing about original prose. That brake is judgment, and it is the only one left:
for every sentence you add, ask "would the agent get this wrong without it?" and delete it if the
answer is no.
**Explain the why.** Reasoning-based instructions outperform rigid directives. A rule written in **Explain the why.** Reasoning-based instructions outperform rigid directives. A rule written in
all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can
apply judgment at the edges. apply judgment at the edges.
@@ -73,4 +78,10 @@ that was already there.
If the edit adds or removes research-sourced content, update `source_keys` in the edited file and If the edit adds or removes research-sourced content, update `source_keys` in the edited file and
the matching `sources.md` entry — the create flow's Step 3 has the rules. the matching `sources.md` entry — the create flow's Step 3 has the rules.
**Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL,
which says nothing about a check that passed *before* these edits and no longer does. Compare the
closing `agent-audit` against the agent's pre-edit state — a PASS that has become a SUGGESTION, or
a SUGGESTION that has become a FAIL, is damage this flow caused and is in scope for it. Only the
improve flow can make that comparison; the create flow has no prior state to compare against.
Then return to `SKILL.md` Step 4. Then return to `SKILL.md` Step 4.

5
plugins/kyberforge/skills/agent-author/references/plugin-scope.md
View File

@@ -37,6 +37,11 @@ The rule is about a field's *shape*, not a fixed roster:
Claude Code honours it for plugin subagents; the three fields plugin agents do silently ignore Claude Code honours it for plugin subagents; the three fields plugin agents do silently ignore
are `hooks`, `mcpServers` and `permissionMode`, and this is not one of them. Copilot's handling are `hooks`, `mcpServers` and `permissionMode`, and this is not one of them. Copilot's handling
of the key is unconfirmed, which ADR-0016 accepts as a stated risk. of the key is unconfirmed, which ADR-0016 accepts as a stated risk.
Its syntax is the same at every scope, and this is the one scope that cannot reach it anywhere
else: MCP tools are denied as `mcp__<server>`, `mcp__<server>__*` or `mcp__*`; both a YAML list
and a delimited string are accepted, and this repo writes the comma-separated string form
(`disallowedTools: Edit, Write, NotebookEdit`) — match it.
- The Claude-only knobs (`isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`, `skills`, - The Claude-only knobs (`isolation`, `maxTurns`, `effort`, `memory`, `permissionMode`, `skills`,
`color`, `initialPrompt`, `background`, `hooks`, `mcpServers`) have no Copilot equivalent and `color`, `initialPrompt`, `background`, `hooks`, `mcpServers`) have no Copilot equivalent and
are never written to this file at all. "Silently ignored at plugin scope" is the wrong framing: are never written to this file at all. "Silently ignored at plugin scope" is the wrong framing:

5
plugins/kyberforge/skills/agent-author/references/project-user-scope.md
View File

@@ -25,7 +25,10 @@ duplicate silently.
**`description`** — write it against `references/contract.md`. It is the primary signal for **`description`** — write it against `references/contract.md`. It is the primary signal for
autonomous delegation. autonomous delegation.
**`tools`** — an allowlist; omit it to inherit every tool from the parent. Use `Agent(type1,type2)` **`tools`** — an allowlist. Write it, and restrict it to the tools the agent actually needs;
omitting it inherits every tool from the parent, which is the right value only when the agent
genuinely needs all of them. Least privilege is the default, not the exception. Use
`Agent(type1,type2)`
to restrict which subagent types this agent may spawn, and omit `Agent` entirely to stop it to restrict which subagent types this agent may spawn, and omit `Agent` entirely to stop it
spawning any. Five tools reach no subagent whatever this field says — `AskUserQuestion`, spawning any. Five tools reach no subagent whatever this field says — `AskUserQuestion`,
`EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup` and `WaitForMcpServers` — so listing one buys `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup` and `WaitForMcpServers` — so listing one buys

2
plugins/kyberforge/skills/skill-audit/SKILL.md
View File

@@ -35,7 +35,7 @@ scripts/vale-wrap.sh <skill-dir>/SKILL.md
`validate.sh` findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both. `validate.sh` findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both.
If any of the three fails, cannot run, or reports something needing interpretation, read `references/validation-scripts.md` — it carries the manual fallback and the misleading exit codes. If any of the three cannot run, or exits non-zero for a reason other than findings, read `references/validation-scripts.md` — it carries the manual fallback and the misleading exit codes. Ordinary content FAILs are the expected outcome here and need no fallback.
`validate-provenance.sh` prints nothing on success. Its FAIL and INFO findings become a separate `### Provenance` dimension, and it emits Why and Fix itself — surface those verbatim. `validate-provenance.sh` prints nothing on success. Its FAIL and INFO findings become a separate `### Provenance` dimension, and it emits Why and Fix itself — surface those verbatim.

6
plugins/kyberforge/skills/skill-audit/references/body-discipline.md
View File

@@ -28,8 +28,10 @@ Include content the agent lacks:
- The specific tools or sequences to use — not the full range of options - The specific tools or sequences to use — not the full range of options
- One default per decision point with one escape hatch - One default per decision point with one escape hatch
Move to `references/`, behind an explicit "If X, read `references/file.md`" trigger — the literal Move to `references/`, behind an explicit "If X, read `references/<file>.md`" trigger — the literal
conditional form, never a generic pointer: conditional form, never a generic pointer. Write the real filename in the skill under audit; the
angle brackets are a placeholder here, and a literal `references/file.md` in a body is an ERROR
from the ADR-0020 gate because no such file exists on disk. Move:
- Lookup tables and spec restatements - Lookup tables and spec restatements
- Output schemas, templates and example blocks - Output schemas, templates and example blocks

12
plugins/kyberforge/skills/skill-audit/references/patterns.md
View File

@@ -32,8 +32,16 @@ read after the mistake.
inner fence as `` \`\`\` ``. An unescaped inner fence terminates the outer block and the remaining inner fence as `` \`\`\` ``. An unescaped inner fence terminates the outer block and the remaining
instructions render as prose. instructions render as prose.
**Conditional references** state a specific trigger: "If the API returns a non-200 status, read **Conditional references** state a specific trigger, naming a file that exists in the skill's own
`references/api-errors.md`." The generic form — pointing at the directory and hoping — defeats `references/` directory:
```text
If the API returns a non-200 status, read `references/api-errors.md`.
```
That block is fenced because the filename in it is illustrative — an unfenced `references/` pointer
in a `SKILL.md` body must resolve on disk or the ADR-0020 gate reports a hard ERROR. The generic
form — pointing at the directory and hoping — defeats
progressive disclosure, because the agent either loads everything or loads nothing. progressive disclosure, because the agent either loads everything or loads nothing.
`Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed `Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed
forms are judgment. forms are judgment.

155
plugins/kyberforge/skills/skill-audit/scripts/validate.sh
View File

@@ -148,17 +148,21 @@ def read_text(path):
# which is what a monorepo means, # which is what a monorepo means,
# 2. the target's own apm package, # 2. the target's own apm package,
# 3. the packages that package DECLARES in apm.yml dependencies.apm. # 3. the packages that package DECLARES in apm.yml dependencies.apm.
# Deployed .claude/ and .agents/ trees are deliberately NOT consulted in that # Deployed .claude/ and .agents/ trees are deliberately NOT consulted when the
# case. They are `apm install` output, gitignored, and present only on a machine # root came from the plugins/ probe. They are `apm install` output, gitignored,
# that has run it: four cross-plugin targets in this repo (gitea-branches -> # and present only on a machine that has run it: four cross-plugin targets in
# git-branches, gitea-branches -> git-history, gitea-issues -> git-branches, # this repo (gitea-branches -> git-branches, gitea-branches -> git-history,
# gitea-workflow -> git-workflow) resolved through .claude/skills/ alone, so the # gitea-issues -> git-branches, gitea-workflow -> git-workflow) resolved through
# same commit measured 2 dangling targets on a developer machine and 6 on a # .claude/skills/ alone, so the same commit measured 2 dangling targets on a
# fresh clone. A gate shipping hot with no baseline cannot give two answers. # developer machine and 6 on a fresh clone. A gate shipping hot with no baseline
# cannot give two answers.
# #
# Deployed trees are used only when NO authoring root exists — the consumer # Deployed trees ARE used when no plugin monorepo was found — whether the walk
# case, where the file being checked lives in or beside a deployed tree and # landed on a bare .git ancestor or on nothing at all. That is the consumer
# there is no monorepo to read. # case: the file being checked lives in or beside a deployed tree, inside an
# ordinary git repo, with no monorepo to read. The two cases are told apart by
# which probe matched, never by how many names a root contributed; see
# known_targets().
def _is_fs_root(path): def _is_fs_root(path):
@@ -167,11 +171,17 @@ def _is_fs_root(path):
def _collect_package(pkg_dir, names): def _collect_package(pkg_dir, names):
"""Add every skill/agent name a package directory exposes, any layout.""" """Add every skill/agent name a package directory exposes, any layout."""
# glob.escape() the DIRECTORY only. A checkout path containing `[`, `]`,
# `*` or `?` — a worktree named `feature[2]`, say — otherwise turns the
# whole pattern into a character class that matches nothing, and the
# resolver degrades to the "DID NOT RUN" INFO with rc=0 across every file
# in the tree. The wildcards in `sub` are the intended ones and stay raw.
safe_dir = glob.escape(pkg_dir)
for sub in ('.apm/skills/*/', 'skills/*/'): for sub in ('.apm/skills/*/', 'skills/*/'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
names.add(os.path.basename(path.rstrip('/')).lower()) names.add(os.path.basename(path.rstrip('/')).lower())
for sub in ('.apm/agents/*.md', 'agents/*.md'): for sub in ('.apm/agents/*.md', 'agents/*.md'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
base = os.path.basename(path) base = os.path.basename(path)
if base.endswith('.agent.md'): if base.endswith('.agent.md'):
base = base[:-len('.agent.md')] base = base[:-len('.agent.md')]
@@ -203,28 +213,35 @@ def _apm_package_root(start_dir):
def _authoring_root(start_dir): def _authoring_root(start_dir):
"""Nearest ancestor that is a plugin monorepo, else the nearest .git tree. """Nearest ancestor that is a plugin monorepo, else the nearest .git tree.
Returns (root, matched_plugins_probe). The flag reports WHICH probe
matched: True for the plugins/*/.apm/{skills,agents} glob, False for the
.git fallback and for no match at all. known_targets() needs that
distinction — only a real plugins/ root makes the deployed trees
redundant, and a name-count delta cannot tell the two apart.
Two passes, not one interleaved walk: a nested .git (a submodule, a Two passes, not one interleaved walk: a nested .git (a submodule, a
worktree of a sub-package) must not win over a real plugins/ root further worktree of a sub-package) must not win over a real plugins/ root further
up. Both passes stop before the filesystem root for the same reason up. Both passes stop before the filesystem root for the same reason
_apm_package_root does. _apm_package_root does.
""" """
for probe in ( probes = (
lambda d: bool(glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'skills')) lambda d: bool(glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'skills'))
or glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'agents'))), or glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'agents'))),
lambda d: os.path.exists(os.path.join(d, '.git'))): lambda d: os.path.exists(os.path.join(d, '.git')))
for index, probe in enumerate(probes):
current = os.path.abspath(start_dir) current = os.path.abspath(start_dir)
for _ in range(12): for _ in range(12):
if _is_fs_root(current): if _is_fs_root(current):
break break
if probe(current): if probe(current):
return current return current, index == 0
current = os.path.dirname(current) current = os.path.dirname(current)
return None return None, False
def _collect_authoring_root(root, names): def _collect_authoring_root(root, names):
"""Every plugin in the monorepo contributes its names.""" """Every plugin in the monorepo contributes its names."""
for pkg in glob.glob(os.path.join(root, 'plugins', '*')): for pkg in glob.glob(os.path.join(glob.escape(root), 'plugins', '*')):
if os.path.isdir(pkg): if os.path.isdir(pkg):
_collect_package(pkg, names) _collect_package(pkg, names)
@@ -288,7 +305,7 @@ def _declared_dependency_dirs(pkg_dir):
def _deployed_roots(start_dir): def _deployed_roots(start_dir):
""".claude/ and .agents/ trees above start_dir — what a host really sees. """.claude/ and .agents/ trees above start_dir — what a host really sees.
Consulted ONLY when no authoring root exists; see the section header. The Consulted ONLY when no plugin monorepo root was found; see the header. The
filesystem root is skipped for the same reason _apm_package_root skips it: filesystem root is skipped for the same reason _apm_package_root skips it:
a stray /.claude/skills/ must not join every path's universe. a stray /.claude/skills/ must not join every path's universe.
""" """
@@ -327,10 +344,22 @@ def known_targets(start_dir):
for dep_dir in _declared_dependency_dirs(package): for dep_dir in _declared_dependency_dirs(package):
_collect_package(dep_dir, names) _collect_package(dep_dir, names)
root = _authoring_root(start) # A .git ancestor is an authoring root only if it actually holds plugins.
# _authoring_root() falls back to the nearest .git, so it is truthy in ANY
# git repo; without the distinction that fallback wins in every consumer
# checkout, _collect_authoring_root() contributes nothing, and the deployed
# branch below is dead code in the exact case it exists for. So condition
# on WHICH probe matched, which _authoring_root() reports directly. A
# name-count delta looks equivalent and is not: _collect_authoring_root()
# re-collects the checked file's own plugin, whose names the blocks above
# already added, so a one-plugin monorepo shows a delta of zero and would
# wrongly reach for the deployed trees — including the user's global
# ~/.claude/skills, making the verdict depend on what happens to be
# installed (ADR-0020 lines 118-127).
root, root_has_plugins = _authoring_root(start)
if root: if root:
_collect_authoring_root(root, names) _collect_authoring_root(root, names)
else: if not root_has_plugins:
for base in _deployed_roots(start): for base in _deployed_roots(start):
_collect_package(base, names) _collect_package(base, names)
return names return names
@@ -436,16 +465,43 @@ MARKED_TARGET = r"(?:`/?(%s)`|(?<![\w./*-])/(%s)\b)" % (NAME_ANY, NAME_ANY)
ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH) ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH)
ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I) ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I)
ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I) ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I)
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET) # re.I on ALL of them, uniformly. The patterns are built from the same
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET) # lowercase NAME_* fragments, so half of them carrying the flag and half not
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET) # meant `Skill-Audit` at the start of a boundary sentence was extracted by
# ROUTE_ANY but invisible to BACKTICK — contradicting normalize_target()'s own
# docstring, which exists precisely because extraction is case-insensitive and
# the universe is not.
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET, re.I)
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET, re.I)
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET, re.I)
ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I) ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I)
BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH) BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH, re.I)
# A boundary clause takes two shapes and BOTH count: the prose markers, and # A boundary clause takes two shapes and BOTH count: the prose markers, and
# ADR-0020's compressed arrow form `Not <thing> -> <name>`. # ADR-0020's compressed arrow form `Not <thing> -> <name>`.
BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I) BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I)
BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I) BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I)
SENTENCE_SPLIT = re.compile(u'(?<=[.!?])\\s+(?=[A-Z"“(])') # Sentence boundaries decide the CORROBORATION scope above, so getting one wrong
# is not cosmetic — it moves a target between SUGGESTION and blocking ERROR. Two
# shapes common in these descriptions defeat the naive "period, space, capital"
# rule, in OPPOSITE directions:
# OVER-SPLIT. `e.g. "set up the manifest"` ends no sentence, but the quote
# looks like one starting. The clause is cut in half, the corroborating
# target lands on the far side of the cut, and a genuinely dangling target
# silently demotes to SUGGESTION — the gate takes a measurement and then
# throws it away, which is the vacuous-green shape this file exists to stop.
# UNDER-SPLIT. A real sentence opening with a code span or a lowercase skill
# name ("... Composes it. `gitea-prs` also uses it.") is not seen as a start
# at all, so two sentences merge and a resolving target vouches for an
# unresolvable one it never stood beside — a hard FAIL with no escape hatch,
# which is exactly the failure the corroboration rule was added to prevent.
# Both are closed here: the five abbreviations that actually occur in routing
# prose are excluded as sentence ends, and the opener class admits a backtick or
# a lowercase letter. Verified zero-delta on the current corpus (37 ERROR / 58
# SUGGESTION / 2 dangling before and after) — this protects the descriptions
# issue #99 is about to rewrite, not the ones already measured.
SENTENCE_SPLIT = re.compile(
u'(?<!\\be\\.g\\.)(?<!\\bi\\.e\\.)(?<!\\betc\\.)(?<!\\bvs\\.)(?<!\\bcf\\.)'
u'(?<=[.!?])\\s+(?=[A-Za-z`"“(])')
# The token that may follow a route target without turning it into a compound # The token that may follow a route target without turning it into a compound
# modifier: punctuation, end of sentence, a conjunction, a boundary word, or a # modifier: punctuation, end of sentence, a conjunction, a boundary word, or a
@@ -607,8 +663,16 @@ def unresolved_targets(description, known):
# description with a 1,000-word body exited 0 behind a BOM). A file that cannot # description with a 1,000-word body exited 0 behind a BOM). A file that cannot
# be measured must never report green, so every caller of these two ERRORs on a # be measured must never report green, so every caller of these two ERRORs on a
# miss instead of moving on. # miss instead of moving on.
#
# The CLOSING marker is anchored at column 0 — deliberately NOT `[ \t]*---`.
# YAML block-scalar content must be indented deeper than its key, so an
# indented `---` inside a folded description is CONTENT; letting it close the
# frontmatter truncated the description mid-value and silently reclassified the
# rest as body, which is a vacuous green in both directions at once. Leading
# whitespace is still tolerated on the OPENING marker, where no such content
# can exist.
FRONTMATTER_RE = re.compile( FRONTMATTER_RE = re.compile(
r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n[ \t]*---[ \t]*(?:\r?\n|\Z)', re.DOTALL) r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)', re.DOTALL)
def strip_bom(text): def strip_bom(text):
@@ -640,14 +704,26 @@ def description_value(fm_text):
try: try:
data = yaml.safe_load(fm_text) data = yaml.safe_load(fm_text)
except Exception as exc: except Exception as exc:
raise FrontmatterError(re.sub(r'\s+', ' ', str(exc)).strip()) # Every FrontmatterError message is a COMPLETE clause, never a detail a
# caller wraps in one. Callers used to prefix a hard-coded "frontmatter
# is not valid YAML (...)", which is true only of this branch: the two
# type failures below come from frontmatter that parsed fine, and
# telling their author the YAML is invalid sends them hunting for a
# syntax error that is not there — on a blocking gate with no baseline.
raise FrontmatterError('frontmatter is not valid YAML (%s)'
% re.sub(r'\s+', ' ', str(exc)).strip())
if not isinstance(data, dict): if not isinstance(data, dict):
raise FrontmatterError('frontmatter is not a YAML mapping') raise FrontmatterError('frontmatter is not a YAML mapping')
value = data.get('description') value = data.get('description')
if value is None: if value is None:
return '' return ''
if not isinstance(value, str): if not isinstance(value, str):
value = str(value) # NOT str()-coerced. `description: true` became the 4-character "True"
# and sailed through the 400-character gate; a list or mapping was
# measured as its Python repr. Neither is a description a host can
# preload, so this is a parse failure, reported as one.
raise FrontmatterError(
'description is a %s, not a string' % type(value).__name__)
return re.sub(r'\s+', ' ', value).strip() return re.sub(r'\s+', ' ', value).strip()
@@ -717,6 +793,18 @@ def mask_fenced(text):
if (marker and marker[0] == fence[0] and len(marker) >= len(fence) if (marker and marker[0] == fence[0] and len(marker) >= len(fence)
and not stripped.strip()[len(marker):].strip()): and not stripped.strip()[len(marker):].strip()):
fence = None fence = None
# An UNCLOSED fence has no cost-free answer, only a choice of which way to
# be wrong. Masking to end-of-body blanks the rest of the body, silently
# disabling the ERROR-tier references/ check and the gotcha counts.
# Returning the raw text instead exposes the unclosed example's own
# content, so a fenced example naming a nonexistent references/ file
# becomes a hard ERROR it would not have been had the fence been closed —
# confirmed, not hypothetical. The loud-false-positive direction is the one
# chosen: this script's rule is that a file it cannot measure must never
# report green, and masking-onward is exactly that failure. Both outcomes
# need an already-malformed file, and the false positive costs one fence.
if fence is not None:
return text
return ''.join(out) return ''.join(out)
@@ -802,8 +890,11 @@ name = name_m.group(1).strip('"\'') if name_m else ""
try: try:
desc = description_value(fm) desc = description_value(fm)
except FrontmatterError as exc: except FrontmatterError as exc:
fail(f"frontmatter is not valid YAML ({exc}). Nothing downstream can be " # `exc` carries the whole clause — invalid YAML, a non-mapping block, or a
f"measured, so this is a hard failure, not a skip") # description of the wrong type. Do not prefix a diagnosis here; the last
# one named a syntax error for two failures that have none.
fail(f"{exc}. Nothing downstream can be measured, so this is a hard "
f"failure, not a skip")
print("One or more checks failed.") print("One or more checks failed.")
sys.exit(1) sys.exit(1)

6
plugins/kyberforge/skills/skill-author/references/contract.md
View File

@@ -57,6 +57,12 @@ therefore resolves; a skill in an unrelated repo does not. A boundary clause nam
outside that universe sends the router nowhere and fails the audit. Check the target exists before outside that universe sends the router nowhere and fails the audit. Check the target exists before
writing it — do not invent a plausible sibling name. writing it — do not invent a plausible sibling name.
That universe is the apm marketplace and stops there. A **host built-in is not a routing target**:
`/compact`, `/clear` and `/init` are Claude Code slash commands with no counterpart in Copilot CLI
or Codex, and `.apm/` source compiles for all three, so routing to one is a portability defect. The
gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write
it un-slashed — ``the `compact` built-in`` — which makes no routing claim and is not checked.
**Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only **Length.** 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only
with YAML folding resolved. The agentskills.io 1,024-character spec limit is unchanged and sits with YAML folding resolved. The agentskills.io 1,024-character spec limit is unchanged and sits
above both. The SUGGESTION tier is the one that moves the average; treat 250 as the target and 400 above both. The SUGGESTION tier is the one that moves the average; treat 250 as the target and 400

6
plugins/kyberforge/skills/skill-author/references/improve.md
View File

@@ -85,4 +85,10 @@ improvise the cuts — four dry runs invented six to ten different answers to th
If a signal points to a script or reference file, edit that file directly rather than adding a If a signal points to a script or reference file, edit that file directly rather than adding a
workaround in SKILL.md. workaround in SKILL.md.
**Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL,
which says nothing about a check that passed *before* these edits and no longer does. Compare the
closing audit against the skill's pre-edit state — a PASS that has become a SUGGESTION, or a
SUGGESTION that has become a FAIL, is damage this flow caused and is in scope for it. Only the
improve flow can make that comparison; the create flow has no prior state to compare against.
Then return to `SKILL.md` Step 4. Then return to `SKILL.md` Step 4.

17
scripts/check-vale-style-sync.sh
View File

@@ -127,8 +127,8 @@ for ini in "$SKILL_INI" "$AGENT_INI"; do
err "$rel_ini has no section whose BasedOnStyles names Kyberforge — every rule the audit prefilters on lives in that style" err "$rel_ini has no section whose BasedOnStyles names Kyberforge — every rule the audit prefilters on lives in that style"
fi fi
# Per-rule overrides are the third way to retire a rule without touching a # Per-rule overrides are the third way to retire a rule without touching a
# style file or a glob. CONTEXT.md's "Vale audit prefilter" entry: "Every rule # style file or a glob. Per ADR-0013, every rule is `level: error` and every
# is `level: error` and every alert is a FAIL — no ignorable tier". Vale's exit # alert is a FAIL — there is no ignorable tier. Vale's exit
# code keys on `error` alerts alone, so any override that leaves a rule at # code keys on `error` alerts alone, so any override that leaves a rule at
# anything other than `error` still lints the file, still exits 0, and still # anything other than `error` still lints the file, still exits 0, and still
# shows `Passed` in pre-commit. The glob probe below cannot backstop this: it # shows `Passed` in pre-commit. The glob probe below cannot backstop this: it
@@ -175,9 +175,10 @@ for ini in "$SKILL_INI" "$AGENT_INI"; do
fi fi
done done
# KyberforgeCopilot is agent-audit's alone — CONTEXT.md describes it as "scoped # KyberforgeCopilot is agent-audit's alone — ADR-0013 scopes it to `.agent.md`
# only to `.agent.md` files for the Copilot-only 'Use proactively has no effect' # files only, for the Copilot-only 'Use proactively has no effect' check, and
# check". The loop above deliberately asserts only `Kyberforge`, since # records that it must not be extended to `.md` files. The loop above
# deliberately asserts only `Kyberforge`, since
# skill-audit's copy legitimately has no Copilot style, so dropping # skill-audit's copy legitimately has no Copilot style, so dropping
# `, KyberforgeCopilot` from agent-audit's `[**/*.agent.md]` section unloaded the # `, KyberforgeCopilot` from agent-audit's `[**/*.agent.md]` section unloaded the
# whole style silently: no glob broke, the styles/ diff above stayed clean (the # whole style silently: no glob broke, the styles/ diff above stayed clean (the
@@ -353,10 +354,10 @@ while IFS='|' read -r skill rel scope; do
# `.pre-commit-config.yaml`'s regex correctly no longer matches it and that's # `.pre-commit-config.yaml`'s regex correctly no longer matches it and that's
# not drift. `demo.agent.md` is the real, current shape and is `shared`. # not drift. `demo.agent.md` is the real, current shape and is `shared`.
# #
# The two `.claude/`-prefixed probes carry the location-independence CONTEXT.md # The two `.claude/`-prefixed probes carry the location-independence property: a
# asserts: "A `SKILL.md` outside `plugins/` (e.g. project-scope # `SKILL.md` outside `plugins/` (e.g. project-scope
# `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted # `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted
# normally — the globs constrain filename shape, not location." Every other # normally — the globs constrain filename shape, not location. Every other
# probe here starts with `plugins/`, so narrowing a glob to a `plugins/`-shaped # probe here starts with `plugins/`, so narrowing a glob to a `plugins/`-shaped
# path (`[**/SKILL.md]` -> `[**/.apm/skills/*/SKILL.md]`) left all of them # path (`[**/SKILL.md]` -> `[**/.apm/skills/*/SKILL.md]`) left all of them
# matching while the project-scope shape started linting as `0 errors ... in 0 # matching while the project-scope shape started linting as `0 errors ... in 0

219
scripts/skill-size-check.sh
View File

@@ -30,8 +30,11 @@ set -euo pipefail
# SKILL.md could pass its own audit and still be blocked by the commit hook. # SKILL.md could pass its own audit and still be blocked by the commit hook.
# The ADR-0020 ceilings are inclusive the same way. # The ADR-0020 ceilings are inclusive the same way.
# #
# Token counts aren't computed exactly here — word count (`wc -w`) is used as # Token counts aren't computed exactly here — a whitespace word count is used
# a proxy. Measured over this repo's 39 in-scope SKILL.md files, characters per # as a proxy (Python's str.split(), the same primitive
# skill-audit/scripts/validate.sh applies to these two constants; `wc -w`
# disagrees with it on Unicode separators, which is why the awk pass that used
# to live in the loop below is gone). Measured over this repo's 39 in-scope SKILL.md files, characters per
# word runs min 5.97 / median 6.79 / mean 6.77 / max 7.22. At the standard # word runs min 5.97 / median 6.79 / mean 6.77 / max 7.22. At the standard
# ~4-characters-per-token English approximation that is 1.49 / 1.70 / 1.69 / # ~4-characters-per-token English approximation that is 1.49 / 1.70 / 1.69 /
# 1.81 tokens per word. # 1.81 tokens per word.
@@ -105,23 +108,19 @@ for f in "$@"; do
continue continue
fi fi
# Single awk pass computes both line count and word count, avoiding a # The MAX_LINES / MAX_WORDS ceilings are NOT measured here. They used to be,
# second read of the file. NR counts the final line even without a # in a single awk pass, and that pass was wrong twice over:
# trailing newline, matching Python's splitlines() semantics (used by # * `read -r lines words <<< "$(awk ...)"` discarded awk's exit status, so a
# skill-audit/scripts/validate.sh for its own line count) — `wc -l` # file awk could not read yielded empty variables, bash arithmetic read
# undercounts by 1 in that case. Word count uses awk's default # them as 0, and both ceilings passed in total silence — the one outcome
# whitespace-splitting NF, matching `wc -w` semantics. # this script forbids itself.
read -r lines words <<< "$(awk '{w += NF} END{print NR, w+0}' "$f")" # * awk's NR/NF do not agree with the Python splitlines()/split() that
# skill-audit/scripts/validate.sh uses for the SAME two constants.
if (( lines > MAX_LINES )); then # splitlines() also breaks on \x0b \x0c \x1c \x1d \x1e \x85 U+2028 U+2029
echo "ERROR: $f has $lines lines, exceeding the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2 # and split() on every Unicode space, so a body padded with U+2028 read as
FAIL=1 # 6 lines here and 606 lines there — hook green, audit FAIL.
fi # One implementation now owns both: the Python block below already reads every
# file (with a real diagnostic on failure), so it counts there.
if (( words > MAX_WORDS )); then
echo "ERROR: $f has $words words (proxy for tokens), exceeding the $MAX_WORDS-word ceiling (~5,000 tokens, agentskills.io skill-authoring.md)" >&2
FAIL=1
fi
done done
if ! command -v python3 > /dev/null 2>&1; then if ! command -v python3 > /dev/null 2>&1; then
@@ -140,7 +139,7 @@ fi
if ! python3 -u - \ if ! python3 -u - \
"$DESC_SUGGEST_CHARS" "$DESC_MAX_CHARS" \ "$DESC_SUGGEST_CHARS" "$DESC_MAX_CHARS" \
"$BODY_SUGGEST_WORDS" "$BODY_MAX_WORDS" "$MAX_WORDS" "$@" <<'PYTHON' "$BODY_SUGGEST_WORDS" "$BODY_MAX_WORDS" "$MAX_WORDS" "$MAX_LINES" "$@" <<'PYTHON'
import glob import glob
import os import os
import re import re
@@ -153,7 +152,8 @@ DESC_MAX_CHARS = int(sys.argv[2])
BODY_SUGGEST_WORDS = int(sys.argv[3]) BODY_SUGGEST_WORDS = int(sys.argv[3])
BODY_MAX_WORDS = int(sys.argv[4]) BODY_MAX_WORDS = int(sys.argv[4])
MAX_WORDS = int(sys.argv[5]) MAX_WORDS = int(sys.argv[5])
files = sys.argv[6:] MAX_LINES = int(sys.argv[6])
files = sys.argv[7:]
failed = False failed = False
@@ -232,17 +232,21 @@ def read_text(path):
# which is what a monorepo means, # which is what a monorepo means,
# 2. the target's own apm package, # 2. the target's own apm package,
# 3. the packages that package DECLARES in apm.yml dependencies.apm. # 3. the packages that package DECLARES in apm.yml dependencies.apm.
# Deployed .claude/ and .agents/ trees are deliberately NOT consulted in that # Deployed .claude/ and .agents/ trees are deliberately NOT consulted when the
# case. They are `apm install` output, gitignored, and present only on a machine # root came from the plugins/ probe. They are `apm install` output, gitignored,
# that has run it: four cross-plugin targets in this repo (gitea-branches -> # and present only on a machine that has run it: four cross-plugin targets in
# git-branches, gitea-branches -> git-history, gitea-issues -> git-branches, # this repo (gitea-branches -> git-branches, gitea-branches -> git-history,
# gitea-workflow -> git-workflow) resolved through .claude/skills/ alone, so the # gitea-issues -> git-branches, gitea-workflow -> git-workflow) resolved through
# same commit measured 2 dangling targets on a developer machine and 6 on a # .claude/skills/ alone, so the same commit measured 2 dangling targets on a
# fresh clone. A gate shipping hot with no baseline cannot give two answers. # developer machine and 6 on a fresh clone. A gate shipping hot with no baseline
# cannot give two answers.
# #
# Deployed trees are used only when NO authoring root exists — the consumer # Deployed trees ARE used when no plugin monorepo was found — whether the walk
# case, where the file being checked lives in or beside a deployed tree and # landed on a bare .git ancestor or on nothing at all. That is the consumer
# there is no monorepo to read. # case: the file being checked lives in or beside a deployed tree, inside an
# ordinary git repo, with no monorepo to read. The two cases are told apart by
# which probe matched, never by how many names a root contributed; see
# known_targets().
def _is_fs_root(path): def _is_fs_root(path):
@@ -251,11 +255,17 @@ def _is_fs_root(path):
def _collect_package(pkg_dir, names): def _collect_package(pkg_dir, names):
"""Add every skill/agent name a package directory exposes, any layout.""" """Add every skill/agent name a package directory exposes, any layout."""
# glob.escape() the DIRECTORY only. A checkout path containing `[`, `]`,
# `*` or `?` — a worktree named `feature[2]`, say — otherwise turns the
# whole pattern into a character class that matches nothing, and the
# resolver degrades to the "DID NOT RUN" INFO with rc=0 across every file
# in the tree. The wildcards in `sub` are the intended ones and stay raw.
safe_dir = glob.escape(pkg_dir)
for sub in ('.apm/skills/*/', 'skills/*/'): for sub in ('.apm/skills/*/', 'skills/*/'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
names.add(os.path.basename(path.rstrip('/')).lower()) names.add(os.path.basename(path.rstrip('/')).lower())
for sub in ('.apm/agents/*.md', 'agents/*.md'): for sub in ('.apm/agents/*.md', 'agents/*.md'):
for path in glob.glob(os.path.join(pkg_dir, sub)): for path in glob.glob(os.path.join(safe_dir, sub)):
base = os.path.basename(path) base = os.path.basename(path)
if base.endswith('.agent.md'): if base.endswith('.agent.md'):
base = base[:-len('.agent.md')] base = base[:-len('.agent.md')]
@@ -287,28 +297,35 @@ def _apm_package_root(start_dir):
def _authoring_root(start_dir): def _authoring_root(start_dir):
"""Nearest ancestor that is a plugin monorepo, else the nearest .git tree. """Nearest ancestor that is a plugin monorepo, else the nearest .git tree.
Returns (root, matched_plugins_probe). The flag reports WHICH probe
matched: True for the plugins/*/.apm/{skills,agents} glob, False for the
.git fallback and for no match at all. known_targets() needs that
distinction — only a real plugins/ root makes the deployed trees
redundant, and a name-count delta cannot tell the two apart.
Two passes, not one interleaved walk: a nested .git (a submodule, a Two passes, not one interleaved walk: a nested .git (a submodule, a
worktree of a sub-package) must not win over a real plugins/ root further worktree of a sub-package) must not win over a real plugins/ root further
up. Both passes stop before the filesystem root for the same reason up. Both passes stop before the filesystem root for the same reason
_apm_package_root does. _apm_package_root does.
""" """
for probe in ( probes = (
lambda d: bool(glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'skills')) lambda d: bool(glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'skills'))
or glob.glob(os.path.join(d, 'plugins', '*', '.apm', 'agents'))), or glob.glob(os.path.join(glob.escape(d), 'plugins', '*', '.apm', 'agents'))),
lambda d: os.path.exists(os.path.join(d, '.git'))): lambda d: os.path.exists(os.path.join(d, '.git')))
for index, probe in enumerate(probes):
current = os.path.abspath(start_dir) current = os.path.abspath(start_dir)
for _ in range(12): for _ in range(12):
if _is_fs_root(current): if _is_fs_root(current):
break break
if probe(current): if probe(current):
return current return current, index == 0
current = os.path.dirname(current) current = os.path.dirname(current)
return None return None, False
def _collect_authoring_root(root, names): def _collect_authoring_root(root, names):
"""Every plugin in the monorepo contributes its names.""" """Every plugin in the monorepo contributes its names."""
for pkg in glob.glob(os.path.join(root, 'plugins', '*')): for pkg in glob.glob(os.path.join(glob.escape(root), 'plugins', '*')):
if os.path.isdir(pkg): if os.path.isdir(pkg):
_collect_package(pkg, names) _collect_package(pkg, names)
@@ -372,7 +389,7 @@ def _declared_dependency_dirs(pkg_dir):
def _deployed_roots(start_dir): def _deployed_roots(start_dir):
""".claude/ and .agents/ trees above start_dir — what a host really sees. """.claude/ and .agents/ trees above start_dir — what a host really sees.
Consulted ONLY when no authoring root exists; see the section header. The Consulted ONLY when no plugin monorepo root was found; see the header. The
filesystem root is skipped for the same reason _apm_package_root skips it: filesystem root is skipped for the same reason _apm_package_root skips it:
a stray /.claude/skills/ must not join every path's universe. a stray /.claude/skills/ must not join every path's universe.
""" """
@@ -411,10 +428,22 @@ def known_targets(start_dir):
for dep_dir in _declared_dependency_dirs(package): for dep_dir in _declared_dependency_dirs(package):
_collect_package(dep_dir, names) _collect_package(dep_dir, names)
root = _authoring_root(start) # A .git ancestor is an authoring root only if it actually holds plugins.
# _authoring_root() falls back to the nearest .git, so it is truthy in ANY
# git repo; without the distinction that fallback wins in every consumer
# checkout, _collect_authoring_root() contributes nothing, and the deployed
# branch below is dead code in the exact case it exists for. So condition
# on WHICH probe matched, which _authoring_root() reports directly. A
# name-count delta looks equivalent and is not: _collect_authoring_root()
# re-collects the checked file's own plugin, whose names the blocks above
# already added, so a one-plugin monorepo shows a delta of zero and would
# wrongly reach for the deployed trees — including the user's global
# ~/.claude/skills, making the verdict depend on what happens to be
# installed (ADR-0020 lines 118-127).
root, root_has_plugins = _authoring_root(start)
if root: if root:
_collect_authoring_root(root, names) _collect_authoring_root(root, names)
else: if not root_has_plugins:
for base in _deployed_roots(start): for base in _deployed_roots(start):
_collect_package(base, names) _collect_package(base, names)
return names return names
@@ -520,16 +549,43 @@ MARKED_TARGET = r"(?:`/?(%s)`|(?<![\w./*-])/(%s)\b)" % (NAME_ANY, NAME_ANY)
ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH) ANY_TARGET = r"(?:%s|(%s)\b)" % (MARKED_TARGET, NAME_HYPH)
ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I) ROUTE_MARKED = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, MARKED_TARGET), re.I)
ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I) ROUTE_ANY = re.compile(r"\b%s\s+(?:the\s+|an?\s+)?%s" % (ROUTE_VERB, ANY_TARGET), re.I)
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET) # re.I on ALL of them, uniformly. The patterns are built from the same
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET) # lowercase NAME_* fragments, so half of them carrying the flag and half not
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET) # meant `Skill-Audit` at the start of a boundary sentence was extracted by
# ROUTE_ANY but invisible to BACKTICK — contradicting normalize_target()'s own
# docstring, which exists precisely because extraction is case-insensitive and
# the universe is not.
CONT_MARKED = re.compile(r"\s*(?:or|and|/|,)\s*%s" % MARKED_TARGET, re.I)
CONT_ANY = re.compile(r"\s*(?:or|and|/|,)\s*%s" % ANY_TARGET, re.I)
ARROW_MARKED = re.compile(r"(?:->|→)\s*%s" % MARKED_TARGET, re.I)
ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I) ARROW_BOUNDARY = re.compile(r"\bnot\b[^.;]*?(?:->|→)\s*(%s)\b" % NAME_HYPH, re.I)
BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH) BACKTICK = re.compile(r"`(%s)`" % NAME_HYPH, re.I)
# A boundary clause takes two shapes and BOTH count: the prose markers, and # A boundary clause takes two shapes and BOTH count: the prose markers, and
# ADR-0020's compressed arrow form `Not <thing> -> <name>`. # ADR-0020's compressed arrow form `Not <thing> -> <name>`.
BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I) BOUNDARY_MARKER = re.compile(r"\b(?:do\s+not|instead|rather\s+than|not\s+for)\b", re.I)
BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I) BOUNDARY_ARROW = re.compile(r"\bnot\b[^.;]*?(?:->|→)", re.I)
SENTENCE_SPLIT = re.compile(u'(?<=[.!?])\\s+(?=[A-Z"“(])') # Sentence boundaries decide the CORROBORATION scope above, so getting one wrong
# is not cosmetic — it moves a target between SUGGESTION and blocking ERROR. Two
# shapes common in these descriptions defeat the naive "period, space, capital"
# rule, in OPPOSITE directions:
# OVER-SPLIT. `e.g. "set up the manifest"` ends no sentence, but the quote
# looks like one starting. The clause is cut in half, the corroborating
# target lands on the far side of the cut, and a genuinely dangling target
# silently demotes to SUGGESTION — the gate takes a measurement and then
# throws it away, which is the vacuous-green shape this file exists to stop.
# UNDER-SPLIT. A real sentence opening with a code span or a lowercase skill
# name ("... Composes it. `gitea-prs` also uses it.") is not seen as a start
# at all, so two sentences merge and a resolving target vouches for an
# unresolvable one it never stood beside — a hard FAIL with no escape hatch,
# which is exactly the failure the corroboration rule was added to prevent.
# Both are closed here: the five abbreviations that actually occur in routing
# prose are excluded as sentence ends, and the opener class admits a backtick or
# a lowercase letter. Verified zero-delta on the current corpus (37 ERROR / 58
# SUGGESTION / 2 dangling before and after) — this protects the descriptions
# issue #99 is about to rewrite, not the ones already measured.
SENTENCE_SPLIT = re.compile(
u'(?<!\\be\\.g\\.)(?<!\\bi\\.e\\.)(?<!\\betc\\.)(?<!\\bvs\\.)(?<!\\bcf\\.)'
u'(?<=[.!?])\\s+(?=[A-Za-z`"“(])')
# The token that may follow a route target without turning it into a compound # The token that may follow a route target without turning it into a compound
# modifier: punctuation, end of sentence, a conjunction, a boundary word, or a # modifier: punctuation, end of sentence, a conjunction, a boundary word, or a
@@ -691,8 +747,16 @@ def unresolved_targets(description, known):
# description with a 1,000-word body exited 0 behind a BOM). A file that cannot # description with a 1,000-word body exited 0 behind a BOM). A file that cannot
# be measured must never report green, so every caller of these two ERRORs on a # be measured must never report green, so every caller of these two ERRORs on a
# miss instead of moving on. # miss instead of moving on.
#
# The CLOSING marker is anchored at column 0 — deliberately NOT `[ \t]*---`.
# YAML block-scalar content must be indented deeper than its key, so an
# indented `---` inside a folded description is CONTENT; letting it close the
# frontmatter truncated the description mid-value and silently reclassified the
# rest as body, which is a vacuous green in both directions at once. Leading
# whitespace is still tolerated on the OPENING marker, where no such content
# can exist.
FRONTMATTER_RE = re.compile( FRONTMATTER_RE = re.compile(
r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n[ \t]*---[ \t]*(?:\r?\n|\Z)', re.DOTALL) r'^[ \t\r\n]*---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)', re.DOTALL)
def strip_bom(text): def strip_bom(text):
@@ -724,14 +788,26 @@ def description_value(fm_text):
try: try:
data = yaml.safe_load(fm_text) data = yaml.safe_load(fm_text)
except Exception as exc: except Exception as exc:
raise FrontmatterError(re.sub(r'\s+', ' ', str(exc)).strip()) # Every FrontmatterError message is a COMPLETE clause, never a detail a
# caller wraps in one. Callers used to prefix a hard-coded "frontmatter
# is not valid YAML (...)", which is true only of this branch: the two
# type failures below come from frontmatter that parsed fine, and
# telling their author the YAML is invalid sends them hunting for a
# syntax error that is not there — on a blocking gate with no baseline.
raise FrontmatterError('frontmatter is not valid YAML (%s)'
% re.sub(r'\s+', ' ', str(exc)).strip())
if not isinstance(data, dict): if not isinstance(data, dict):
raise FrontmatterError('frontmatter is not a YAML mapping') raise FrontmatterError('frontmatter is not a YAML mapping')
value = data.get('description') value = data.get('description')
if value is None: if value is None:
return '' return ''
if not isinstance(value, str): if not isinstance(value, str):
value = str(value) # NOT str()-coerced. `description: true` became the 4-character "True"
# and sailed through the 400-character gate; a list or mapping was
# measured as its Python repr. Neither is a description a host can
# preload, so this is a parse failure, reported as one.
raise FrontmatterError(
'description is a %s, not a string' % type(value).__name__)
return re.sub(r'\s+', ' ', value).strip() return re.sub(r'\s+', ' ', value).strip()
@@ -801,6 +877,18 @@ def mask_fenced(text):
if (marker and marker[0] == fence[0] and len(marker) >= len(fence) if (marker and marker[0] == fence[0] and len(marker) >= len(fence)
and not stripped.strip()[len(marker):].strip()): and not stripped.strip()[len(marker):].strip()):
fence = None fence = None
# An UNCLOSED fence has no cost-free answer, only a choice of which way to
# be wrong. Masking to end-of-body blanks the rest of the body, silently
# disabling the ERROR-tier references/ check and the gotcha counts.
# Returning the raw text instead exposes the unclosed example's own
# content, so a fenced example naming a nonexistent references/ file
# becomes a hard ERROR it would not have been had the fence been closed —
# confirmed, not hypothetical. The loud-false-positive direction is the one
# chosen: this script's rule is that a file it cannot measure must never
# report green, and masking-onward is exactly that failure. Both outcomes
# need an already-malformed file, and the false positive costs one fence.
if fence is not None:
return text
return ''.join(out) return ''.join(out)
@@ -868,12 +956,28 @@ for path in files:
"silence." % (path, why)) "silence." % (path, why))
continue continue
try: try:
content = strip_bom(read_text(path)) raw = read_text(path)
except EncodingError as exc: except EncodingError as exc:
error("%s: %s. None of the ADR-0020 gates could run on this file." error("%s: %s. Neither the spec line/word ceilings nor any of the "
% (path, exc)) "ADR-0020 gates could run on this file." % (path, exc))
continue continue
# SPEC CONFORMANCE (family 1). Whole file, frontmatter included, counted
# with the SAME primitives skill-audit/scripts/validate.sh uses for these
# two constants — see the note in the bash loop above for what the previous
# awk pass got wrong.
lines = len(raw.splitlines())
words = len(raw.split())
if lines > MAX_LINES:
error("%s has %d lines, exceeding the %d-line ceiling "
"(agentskills.io skill-authoring.md)" % (path, lines, MAX_LINES))
if words > MAX_WORDS:
error("%s has %d words (proxy for tokens), exceeding the %d-word ceiling "
"(~5,000 tokens, agentskills.io skill-authoring.md)"
% (path, words, MAX_WORDS))
content = strip_bom(raw)
fm_match = FRONTMATTER_RE.match(content) fm_match = FRONTMATTER_RE.match(content)
if not fm_match: if not fm_match:
error("%s: no parseable YAML frontmatter block. Expected a `---` line, " error("%s: no parseable YAML frontmatter block. Expected a `---` line, "
@@ -887,8 +991,11 @@ for path in files:
try: try:
desc = description_value(fm_match.group(1)) desc = description_value(fm_match.group(1))
except FrontmatterError as exc: except FrontmatterError as exc:
error("%s: frontmatter is not valid YAML (%s). None of the ADR-0020 " # `exc` carries the whole clause — invalid YAML, a non-mapping block, or
"gates could run on this file." % (path, exc)) # a description of the wrong type. Do not prefix a diagnosis here; the
# last one named a syntax error for two failures that have none.
error("%s: %s. None of the ADR-0020 gates could run on this file."
% (path, exc))
continue continue
body = content[fm_match.end():] body = content[fm_match.end():]

16
scripts/sync-marketplace-mirror.sh
View File

@@ -6,7 +6,7 @@ set -euo pipefail
# that same file at .claude-plugin/marketplace.json directly, but also has a legacy # that same file at .claude-plugin/marketplace.json directly, but also has a legacy
# convention path at .github/plugin/marketplace.json (see # convention path at .github/plugin/marketplace.json (see
# plugins/kyberforge/docs/research/docs/github-copilot-plugins/marketplace.md) -- and # plugins/kyberforge/docs/research/docs/github-copilot-plugins/marketplace.md) -- and
# CONTEXT.md documents that path as a mirror of the Claude output, not a separate apm # that path is a mirror of the Claude output, not a separate apm
# output profile (apm only ships "claude" and "codex" mappers; codex writes a # output profile (apm only ships "claude" and "codex" mappers; codex writes a
# differently-shaped file to .agents/plugins/marketplace.json, not this path). This # differently-shaped file to .agents/plugins/marketplace.json, not this path). This
# script keeps that legacy mirror byte-identical to .claude-plugin/marketplace.json # script keeps that legacy mirror byte-identical to .claude-plugin/marketplace.json
@@ -60,7 +60,19 @@ fi
if [[ "$CHECK" -eq 1 ]]; then if [[ "$CHECK" -eq 1 ]]; then
if [[ ! -f "$DST" ]] || ! diff -q "$SRC" "$DST" >/dev/null 2>&1; then if [[ ! -f "$DST" ]] || ! diff -q "$SRC" "$DST" >/dev/null 2>&1; then
echo "DRIFT $DST: out of sync with .claude-plugin/marketplace.json" >&2 echo "DRIFT $DST: out of sync with .claude-plugin/marketplace.json" >&2
echo "Fix: bash scripts/sync-marketplace-mirror.sh" >&2 # The runnable command gets a line to ITSELF, and the rationale gets its own
# echo. It was one line -- `Fix: bash scripts/sync-marketplace-mirror.sh --
# apm ships no output profile...` -- which put the prose after `--`, the
# POSIX end-of-options marker, so copy-pasting the Fix line ran this script
# with ~24 stray argv entries: `${1:-}` was `--` (so CHECK stayed 0 and no
# shift happened), `[[ $# -eq 0 ]]` failed, and the tool meant to fix the
# drift answered with its own usage error and exit 1. The backticks around
# `apm pack` made it worse: the paste also command-substituted a real
# `apm pack` run before the script was even reached. Hence plain quotes
# below too. Keep the command alone on its line.
echo "Fix: run, from the repository root:" >&2
echo " bash scripts/sync-marketplace-mirror.sh" >&2
echo "Note: apm ships no output profile targeting this path, so 'apm pack' does not refresh it. Expecting it to is exactly the drift this script and its pre-push hook exist to prevent." >&2
exit 1 exit 1
fi fi
exit 0 exit 0

14
tests/run-tests.sh
View File

@@ -13,11 +13,13 @@
# dev binary, the other 15 suites still tell you something, and turning that # dev binary, the other 15 suites still tell you something, and turning that
# into a red run would just train people to ignore red. # into a red run would just train people to ignore red.
# * as a GATE (the run-tests pre-push hook): a skip is a SETUP ERROR, not a # * as a GATE (the run-tests pre-push hook): a skip is a SETUP ERROR, not a
# legitimate state. AGENTS.md documents vale, apm and jq as required pre-push # legitimate state. README.md's Prerequisites table documents vale, apm and
# dependencies, so a suite that cannot run on the machine doing the pushing # python3/PyYAML -- the dependencies these suites actually guard on -- as
# means the machine is misconfigured -- and pre-commit prints NOTHING for a # required pre-push, so a suite that cannot run on the machine doing the
# passing hook, so the skip list below is swallowed entirely. On a vale-less # pushing means the machine is misconfigured -- and
# PATH that silently shipped a green gate having verified 15 of 17 suites. # pre-commit prints NOTHING for a passing hook, so the skip list below is
# swallowed entirely. On a vale-less PATH that once silently shipped a
# green gate having verified 15 of the 17 suites that existed then.
# Exactly the vacuous-pass class the rest of this file exists to close. # Exactly the vacuous-pass class the rest of this file exists to close.
# #
# Deliberately its own switch, NOT folded into # Deliberately its own switch, NOT folded into
@@ -258,7 +260,7 @@ fi
# here (not just referenced) because this block goes to stderr and is what a # here (not just referenced) because this block goes to stderr and is what a
# pre-push reader actually gets handed. # pre-push reader actually gets handed.
if [[ "$STRICT" == true && ${#SKIPPED[@]} -gt 0 ]]; then if [[ "$STRICT" == true && ${#SKIPPED[@]} -gt 0 ]]; then
echo "Error: --strict and ${#SKIPPED[@]} suite(s) skipped. Run as a gate, a skip is a SETUP ERROR on this machine, not a legitimate state: AGENTS.md documents vale, apm and jq as required pre-push dependencies, so every suite is expected to be runnable here. Install what each suite names below and re-run; do not skip the hook." >&2 echo "Error: --strict and ${#SKIPPED[@]} suite(s) skipped. Run as a gate, a skip is a SETUP ERROR on this machine, not a legitimate state: README.md's Prerequisites table documents vale, apm and python3/PyYAML — what these suites guard on — as required pre-push dependencies, so every suite is expected to be runnable here. Install what each suite names below and re-run; do not skip the hook." >&2
sidx=0 sidx=0
for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do
echo " $s" >&2 echo " $s" >&2

70
tests/test-adr0020-body-checks.sh
View File

@@ -332,6 +332,76 @@ EOF
)" )"
expect "a fenced references/example-file.md does not ERROR" "$F_REF_FENCED" silent expect "a fenced references/example-file.md does not ERROR" "$F_REF_FENCED" silent
echo ""
echo "--- an UNTERMINATED fence does not blank the rest of the body ---"
# The fenced-block exemptions above all rest on mask_fenced(), and an unclosed
# fence used to run to EOF: everything after it was blanked, so the ERROR-tier
# references/ check and both Gotchas counts silently stopped seeing any of it.
# That is the worst shape a masking bug can take — a stray ``` line, which is a
# typo an author makes while writing the very examples the masking exists for,
# turned the rest of the file invisible and the gate green. Masking may narrow
# what a check reads; it may never delete content from every check at once.
#
# Both suppressed checks are asserted, because they are separate call sites and
# a fix that restored only one would leave the other silent.
F_FENCE_REF="$(make_skill fence-unclosed-ref "$CLEAN_DESC" <<EOF
Here is how it is invoked:
\`\`\`bash
some-command --all
If the caller needs the long form, read references/behind-the-fence.md first.
EOF
)"
expect "an absent references/ pointer after an unclosed fence still ERRORs" \
"$F_FENCE_REF" errors "points at references/behind-the-fence.md"
F_FENCE_GOTCHAS="$(make_skill fence-unclosed-gotchas "$CLEAN_DESC" <<EOF
Here is how it is invoked:
\`\`\`bash
some-command --all
## Common gotchas
- first trap here
- second trap here
- third trap here
- fourth trap here
- fifth trap here
- sixth trap here
- seventh trap here
## Notes
$(filler 200)
EOF
)"
expect "a Gotchas section after an unclosed fence is still counted" \
"$F_FENCE_GOTCHAS" suggests "Gotchas section has 7 entries"
# The control. Closing the fence must still mask, or the fix above would have
# been "stop masking", which re-breaks every false-positive case in this file.
F_FENCE_CLOSED="$(make_skill fence-closed-ref "$CLEAN_DESC" <<EOF
Here is how it is invoked:
\`\`\`bash
some-command --all
\`\`\`
Dispatch tables look like this:
\`\`\`markdown
If X, read references/behind-the-fence.md.
\`\`\`
EOF
)"
expect "control: the same pointer inside a CLOSED fence is still masked" \
"$F_FENCE_CLOSED" silent
echo "" echo ""
echo "--- a references/ pointer in a same-line removal context is history, not dispatch ---" echo "--- a references/ pointer in a same-line removal context is history, not dispatch ---"
# Narrow on purpose: a live dispatch table never describes its own target as # Narrow on purpose: a live dispatch table never describes its own target as

135
tests/test-adr0020-differential.sh
View File

@@ -15,14 +15,20 @@
# ready to ship and the commit hook then rejects it, or worse, the reverse. So the # ready to ship and the commit hook then rejects it, or worse, the reverse. So the
# comparison here is over VERDICTS on files, not over source text. # comparison here is over VERDICTS on files, not over source text.
# #
# Scope: the ADR-0020 axes the two scripts share — description length and tier, # Scope: every axis the two scripts share. The ADR-0020 ones — description
# body word count and tier, dangling routing targets, missing references/ # length and tier, body word count and tier, dangling routing targets, missing
# pointers, the two Gotchas suggestions, the missing-boundary-clause suggestion, # references/ pointers, the two Gotchas suggestions, the missing-boundary-clause
# a declined resolution, and an empty description. The two scripts legitimately # suggestion, a declined resolution, an empty description — plus the two
# differ elsewhere (validate.sh also checks name/directory agreement, script # agentskills.io spec ceilings, MAX_LINES and MAX_WORDS.
# executability and the 1024-char spec backstop; the hook checks whole-file lines #
# and words), and those lines are ignored rather than being forced into a shared # Those last two were EXCLUDED from this comparison until a real divergence
# shape they were never meant to have. # shipped behind the exclusion. The header used to say "the hook checks
# whole-file lines and words" as if the auditor did not; it does, from its own
# copy of the same two constants, and the two implementations disagreed on
# Unicode whitespace for as long as nobody compared them. An axis both scripts
# measure is in scope by definition — the only lines still ignored are the ones
# a single script owns outright (validate.sh's name/directory agreement, script
# executability and 1024-char description backstop).
# #
# Run over the real 39-skill corpus AND over purpose-built fixtures that sit ON # Run over the real 39-skill corpus AND over purpose-built fixtures that sit ON
# each boundary. The corpus alone is not enough — it happens not to contain a # each boundary. The corpus alone is not enough — it happens not to contain a
@@ -145,6 +151,48 @@ make_fx gotchas-fraction "$CLEAN" 0
python3 -c "print(' '.join(['word'] * 70))" python3 -c "print(' '.join(['word'] * 70))"
} >> "$FX/gotchas-fraction/SKILL.md" } >> "$FX/gotchas-fraction/SKILL.md"
# The agentskills.io spec ceilings, measured over Unicode whitespace.
#
# These two are in the comparison at all because they used to be excluded from
# it — `_non_adr_hook_error()` waved a spec-ceiling exit through as "not a
# disagreement", and that exclusion is exactly why the divergence below stayed
# invisible. The hook counted lines and words in a single awk pass (NR / NF)
# while skill-audit counted them with Python's splitlines() / split(). The two
# primitives do not agree: splitlines() also breaks on U+2028, U+2029, \x0b,
# \x0c, \x1c-\x1e and \x85, and split() breaks on every Unicode space. Same
# constants, same file, different verdict — hook green, audit FAIL, which is the
# precise failure mode ("passes its own audit, blocked by the commit hook",
# inverted) this whole suite exists to catch.
#
# One fixture per primitive, each sitting just past its ceiling on the Python
# measurement and nowhere near it on the awk one.
python3 - "$FX" <<'PY'
import os
import sys
fx = sys.argv[1]
# Spelled as escapes, never as literals. An invisible separator pasted into a
# source file is unreviewable and one editor round-trip away from becoming an
# ordinary space, which would silently turn both fixtures into nothing.
SEP_LINE = '\u2028' # LINE SEPARATOR: splitlines() breaks on it, awk's NR does not
SEP_WORD = '\u00a0' # NO-BREAK SPACE: split() breaks on it, awk's NF does not
head = ('---\nname: %s\n'
'description: Use when doing the thing. Do not use for anything else.\n'
'---\n\n')
# 600 U+2028-separated segments: 605 lines to splitlines(), 6 to awk's NR.
# Word count stays far below the 2,770 ceiling, so this fixture isolates lines.
cases = {
'spec-lines-u2028': SEP_LINE.join(['word'] * 600),
# 2,800 U+00A0-separated words: 2,816 words to split(), 17 to awk's NF.
'spec-words-u00a0': SEP_WORD.join(['word'] * 2800),
}
for name, body in cases.items():
d = os.path.join(fx, name)
os.makedirs(d, exist_ok=True)
with open(os.path.join(d, 'SKILL.md'), 'w', encoding='utf-8') as fh:
fh.write(head % name + body + '\n')
PY
# Empty description — the shape that used to exit 0 in silence. # Empty description — the shape that used to exit 0 in silence.
mkdir -p "$FX/empty-desc" mkdir -p "$FX/empty-desc"
printf -- '---\nname: empty-desc\ndescription:\nmodel: sonnet\n---\n\nDo the thing.\n' \ printf -- '---\nname: empty-desc\ndescription:\nmodel: sonnet\n---\n\nDo the thing.\n' \
@@ -219,6 +267,18 @@ RULES = (
('NO_BOUNDARY_CLAUSE', re.compile(r'(description has no boundary clause)')), ('NO_BOUNDARY_CLAUSE', re.compile(r'(description has no boundary clause)')),
('RESOLUTION_DECLINED', re.compile(r'(boundary-target resolution DID NOT RUN)')), ('RESOLUTION_DECLINED', re.compile(r'(boundary-target resolution DID NOT RUN)')),
('DESC_EMPTY', re.compile(r'(description field is missing or empty)')), ('DESC_EMPTY', re.compile(r'(description field is missing or empty)')),
# The agentskills.io spec ceilings. These were EXCLUDED from the comparison
# until the awk/Python divergence shipped, on the reasoning that "the hook
# checks whole-file lines and words" and the auditor did not. It does — with
# the same two constants — so the exclusion was never a scope decision, only
# an untested assumption, and it hid a real disagreement. Both scripts spell
# the finding differently, so the patterns match either wording and capture
# only the MEASUREMENT:
# hook: "... has 605 lines, exceeding the 500-line ceiling ..."
# audit: "SKILL.md line count 605 — exceeds 500-line limit"
('SPEC_LINES', re.compile(r'(?:has|line count) (\d+)(?: lines,)? (?:exceeding|—)')),
('SPEC_WORDS', re.compile(
r'(?:has|word count) (\d+)(?: words \(proxy for tokens\),)? (?:exceeding|—)')),
) )
@@ -227,9 +287,15 @@ def verdict(output):
Lines that match no rule are dropped rather than compared: the two scripts Lines that match no rule are dropped rather than compared: the two scripts
legitimately check different things outside ADR-0020 (name/directory legitimately check different things outside ADR-0020 (name/directory
agreement, script executability, the 1024-char spec backstop, whole-file agreement, script executability, the 1024-char spec backstop), and forcing
line and word ceilings), and forcing those into the comparison would report those into the comparison would report a difference that is not a
a difference that is not a disagreement. disagreement.
The whole-file line and word ceilings are NOT in that list. They were
excluded once, on the untested assumption that awk and splitlines() agree;
they do not, and the divergence was invisible for exactly as long as the
exclusion stood. SPEC_LINES/SPEC_WORDS are compared like any other rule —
see the file header. Do not re-add an exclusion for them.
""" """
found = set() found = set()
for raw in output.splitlines(): for raw in output.splitlines():
@@ -278,9 +344,15 @@ def compare(label, skill_dir):
problems.append('the hook reported an ADR-0020 ERROR but exited 0') problems.append('the hook reported an ADR-0020 ERROR but exited 0')
if audit_err and audit_rc == 0: if audit_err and audit_rc == 0:
problems.append('skill-audit reported an ADR-0020 FAIL but exited 0') problems.append('skill-audit reported an ADR-0020 FAIL but exited 0')
if not hook_err and hook_rc != 0 and not _non_adr_hook_error(hook_out): # No escape hatch here any more. There used to be one — a
problems.append('the hook exited %d with no ADR-0020 ERROR and no spec-ceiling ERROR' # `_non_adr_hook_error()` helper that waved through a non-zero hook exit
% hook_rc) # explained by MAX_LINES / MAX_WORDS, on the grounds that those two were
# outside the comparison. They are inside it now (see SPEC_LINES /
# SPEC_WORDS in RULES), so every ERROR the hook can raise is a token this
# comparison holds both scripts to.
if not hook_err and hook_rc != 0:
problems.append('the hook exited %d with no compared ERROR at all — it has an '
'ERROR source this comparison does not know about' % hook_rc)
if problems: if problems:
bad('%s: %s' % (label, '; '.join(problems))) bad('%s: %s' % (label, '; '.join(problems)))
@@ -289,16 +361,6 @@ def compare(label, skill_dir):
return False return False
def _non_adr_hook_error(output):
"""True if the hook failed on a spec ceiling rather than an ADR-0020 gate.
MAX_LINES / MAX_WORDS are the hook's other ERROR sources and are outside
this comparison, so a non-zero exit explained by one of them is not a
disagreement.
"""
return bool(re.search(r'ERROR: .*(-line ceiling|-word ceiling \(~5,000 tokens)', output))
# --- The real corpus ------------------------------------------------------- # --- The real corpus -------------------------------------------------------
corpus = sorted(glob.glob(os.path.join(repo_root, 'plugins', '*', '.apm', 'skills', '*'))) corpus = sorted(glob.glob(os.path.join(repo_root, 'plugins', '*', '.apm', 'skills', '*')))
corpus = [d for d in corpus if os.path.isfile(os.path.join(d, 'SKILL.md'))] corpus = [d for d in corpus if os.path.isfile(os.path.join(d, 'SKILL.md'))]
@@ -359,6 +421,31 @@ else:
ok('every one of the %d compared axes was exercised by at least one fixture' ok('every one of the %d compared axes was exercised by at least one fixture'
% len(expected_tokens)) % len(expected_tokens))
# --- The Unicode-whitespace fixtures, named and asserted directly -----------
# The two comparisons above would catch this divergence, but only as "fixture
# spec-lines-u2028 disagreed" — one line among 65. Spelled out here so the
# failure names the primitive, and so the ceiling is asserted to FIRE in both
# scripts rather than merely to be reported the same way by both.
print("")
print("--- both scripts break the spec ceilings on the same Unicode whitespace ---")
for name, token, expected in (('spec-lines-u2028', 'SPEC_LINES', '605'),
('spec-words-u00a0', 'SPEC_WORDS', '2816')):
skill_dir = os.path.join(fixture_dir, name)
_, h_out = run(['bash', hook, os.path.join(skill_dir, 'SKILL.md')])
_, a_out = run(['bash', validate, skill_dir])
want = ('ERROR', token, expected)
missing = [who for who, v in (('the hook', verdict(h_out)),
('skill-audit', verdict(a_out)))
if want not in v]
if missing:
bad('%s: %s did not report %s=%s. The two scripts must count with the '
'same primitive — Python splitlines()/split(), not awk NR/NF, which '
'does not break on this character' % (name, ' and '.join(missing),
token, expected))
else:
ok('%s: both scripts measure %s=%s and raise the ceiling ERROR'
% (name, token, expected))
print("") print("")
print("Results: %d passed, %d failed" % (passes, failures)) print("Results: %d passed, %d failed" % (passes, failures))
sys.exit(1 if failures else 0) sys.exit(1 if failures else 0)

170
tests/test-adr0020-frontmatter.sh
View File

@@ -19,7 +19,22 @@
# NEXT key. The value then looked present (so "missing or empty" never # NEXT key. The value then looked present (so "missing or empty" never
# fired) and was empty once folded (so every ADR-0020 gate early-returned). # fired) and was empty once folded (so every ADR-0020 gate early-returned).
# An agent file with one exited 0 with zero output through a BLOCKING # An agent file with one exited 0 with zero output through a BLOCKING
# pre-push gate. All five spellings of "no value" are pinned here. # pre-push gate. All five spellings of "no value" are pinned here, plus the
# three shapes where the value is present but is not TEXT — a list, a
# mapping, a bool. Those used to be `str()`-coerced and then measured as a
# Python repr, so `description: true` was the four-character "True" and
# passed the 400-character gate.
#
# 3. THE INDENTED CLOSING MARKER. The mirror image of (1): content the pattern
# was too LOOSE to reject. `\r?\n[ \t]*---` matched an indented `---` inside
# a `>`-folded description, truncating the frontmatter mid-value — the
# description gate then measured a fragment and the body gate measured the
# discarded description text.
#
# Every needle names the specific branch or measurement the case is about. A
# needle loose enough to match two branches is how the yaml-none fixture spent
# its life asserting the wrong one: it emitted `---\n---\n`, which never matched
# the frontmatter pattern at all, and passed on the bare word "frontmatter".
# #
# Both fixtures carry an over-ceiling description AND an over-ceiling body on # Both fixtures carry an over-ceiling description AND an over-ceiling body on
# purpose: asserting a non-zero exit alone would be satisfied by the "cannot # purpose: asserting a non-zero exit alone would be satisfied by the "cannot
@@ -81,7 +96,48 @@ elif kind == 'yaml-list':
elif kind == 'yaml-string': elif kind == 'yaml-string':
fm_lines = ['just a bare scalar, not a mapping'] fm_lines = ['just a bare scalar, not a mapping']
elif kind == 'yaml-none': elif kind == 'yaml-none':
# A comment-only block, NOT an empty one. `---\n---\n` does not match
# FRONTMATTER_RE at all (the pattern needs a `\n` between the markers), so
# it lands on the "no parseable frontmatter" branch and never reaches the
# `data is None` -> "not a YAML mapping" branch this fixture is named for.
# It passed anyway because the needle used to be the bare word
# "frontmatter", which both messages contain. A comment is real frontmatter
# text that yaml.safe_load() returns None for, which is the branch.
fm_lines = ['# nothing but a comment']
elif kind == 'yaml-empty-block':
# The shape the fixture above USED to have, kept as its own case so the
# "no parseable frontmatter block" branch is covered on purpose rather than
# by accident.
fm_lines = [] fm_lines = []
elif kind == 'desc-folded-indented':
# A `>`-folded description whose CONTENT contains an indented `---` line.
# YAML block-scalar content must be indented deeper than its key, so this is
# a value, not a document marker — but the closing pattern used to be
# `\r?\n[ \t]*---`, which matched it, truncated the frontmatter mid-value
# and silently reclassified the rest of the description as body. Both halves
# of that are vacuous greens: the description gate measured a fragment, and
# the body gate measured description text.
#
# The value is padded to exactly desc_chars AFTER folding, and the boundary
# clause naming a target sits in the part the truncation used to discard.
head = 'Use when doing the thing. '
tail = ' Do not use for improvements — use no-such-folded-target instead.'
span = int(desc_chars) - len(head) - len(tail) - len(' --- ')
if span < 2:
raise SystemExit('desc_chars too small for the folded fixture')
fm_lines = [
'name: ' + name,
'description: >',
' ' + head + 'x' * (span // 2),
' ---',
' ' + 'x' * (span - span // 2) + tail,
]
elif kind == 'desc-list':
fm_lines = ['name: ' + name, 'description:', ' - one', ' - two']
elif kind == 'desc-mapping':
fm_lines = ['name: ' + name, 'description:', ' text: a description']
elif kind == 'desc-bool':
fm_lines = ['name: ' + name, 'description: true']
elif kind == 'yaml-malformed': elif kind == 'yaml-malformed':
fm_lines = ['name: ' + name, 'description: "unterminated', 'tabs:\t- a'] fm_lines = ['name: ' + name, 'description: "unterminated', 'tabs:\t- a']
elif kind == 'desc-no-value': elif kind == 'desc-no-value':
@@ -222,24 +278,58 @@ probe_all "trailing whitespace after either --- marker does not hide the finding
probe_all "CRLF line endings do not hide the findings" \ probe_all "CRLF line endings do not hide the findings" \
crlf "description is $DESC_CHARS char" "@skills:body is $BODY_WORDS words" crlf "description is $DESC_CHARS char" "@skills:body is $BODY_WORDS words"
# ---------------------------------------------------------------------------
# 1a-bis. An indented `---` inside a block scalar is CONTENT, not a marker
# ---------------------------------------------------------------------------
# The mirror image of the four shapes above. Those were markers the pattern was
# too strict to accept; this is content the pattern was too loose to reject. The
# closing marker used to be `\r?\n[ \t]*---`, so an indented `---` inside a
# `>`-folded description ended the frontmatter early: the description gate then
# measured a truncated fragment (under every ceiling, so silent) and the body
# gate measured the discarded description text as body. Measured on the fixture
# below, the old code exited 0 with nothing but a spurious "no boundary clause"
# SUGGESTION — the clause is in the half it threw away.
#
# The needle is the full-value length, so a script that merely rejected the file
# would not satisfy it.
echo ""
echo "--- an indented --- inside a >-folded description is content, not the end of the frontmatter ---"
build_subjects desc-folded-indented
probe_all "a folded description containing an indented '---' is measured whole" \
desc-folded-indented "description is $DESC_CHARS char"
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# 1b. Unparseable frontmatter is a hard ERROR, never a quiet skip # 1b. Unparseable frontmatter is a hard ERROR, never a quiet skip
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
echo "" echo ""
echo "--- genuinely unparseable frontmatter exits non-zero with a message, rather than passing quietly ---" echo "--- genuinely unparseable frontmatter exits non-zero with a message, rather than passing quietly ---"
for kind in no-close yaml-list yaml-string yaml-none yaml-malformed; do # Each needle names the BRANCH the fixture is supposed to reach, not the word
# "frontmatter" — which every one of these messages contains, and which is why
# the yaml-none fixture below passed for years while landing on the wrong branch
# entirely.
for kind in no-close yaml-list yaml-string yaml-none yaml-empty-block yaml-malformed; do
build_subjects "$kind" build_subjects "$kind"
done done
probe_all "frontmatter with no closing --- is reported, not skipped" \ probe_all "frontmatter with no closing --- is reported, not skipped" \
no-close "frontmatter" no-close "parseable YAML frontmatter block"
probe_all "frontmatter that parses to a LIST is reported, not skipped" \ probe_all "frontmatter that parses to a LIST is reported, not skipped" \
yaml-list "frontmatter" yaml-list "frontmatter is not a YAML mapping"
probe_all "frontmatter that parses to a STRING is reported, not skipped" \ probe_all "frontmatter that parses to a STRING is reported, not skipped" \
yaml-string "frontmatter" yaml-string "frontmatter is not a YAML mapping"
probe_all "frontmatter that parses to None (empty block) is reported, not skipped" \ probe_all "frontmatter that parses to None (a comment-only block) is reported, not skipped" \
yaml-none "frontmatter" yaml-none "frontmatter is not a YAML mapping"
probe_all "a completely empty '---/---' block is reported, not skipped" \
yaml-empty-block "parseable YAML frontmatter block"
# Two needles, both naming the SYNTAX branch specifically. "frontmatter is not
# valid YAML" is now exclusive to it — the wrong-typed-description failures reach
# the same wrapper and no longer borrow that phrase (see 2c below) — and the
# scanner context proves the parser's own diagnostic survives the wrapper rather
# than being replaced by a generic one. Do not needle the tail of PyYAML's
# message: an earlier attempt used "could not find expected", which PyYAML 6.0.3
# does not emit for this fixture at all, so the case failed on the assertion
# rather than on the behaviour.
probe_all "malformed YAML in the frontmatter is reported, not skipped" \ probe_all "malformed YAML in the frontmatter is reported, not skipped" \
yaml-malformed "frontmatter" yaml-malformed "frontmatter is not valid YAML" "while scanning a quoted scalar"
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# 2. A valueless description is a hard FAIL in all three scripts # 2. A valueless description is a hard FAIL in all three scripts
@@ -265,6 +355,70 @@ probe_all "'description: \"\"' FAILs" \
probe_all "'description: >' with nothing folded under it FAILs" \ probe_all "'description: >' with nothing folded under it FAILs" \
desc-empty-fold "description field is missing or empty" desc-empty-fold "description field is missing or empty"
# ---------------------------------------------------------------------------
# 2b. A description that is not a STRING is a parse failure, not a measurement
# ---------------------------------------------------------------------------
# The other half of the same family, and the reason it belongs beside the five
# above: all eight shapes are "the description is not a description", and seven
# of them used to be handled while this one was silently coerced. A non-string
# value went through `str()` and was then measured as a Python repr —
# `description: true` became the four-character "True" and sailed through the
# 400-character gate, a list became "['one', 'two']", a mapping its dict repr.
# None of those is text a host can preload, so measuring one is a green verdict
# on a file that was never measured.
echo ""
echo "--- a description that is a list, a mapping or a bool hard-FAILs in all three scripts ---"
for kind in desc-list desc-mapping desc-bool; do
build_subjects "$kind"
done
probe_all "a LIST description FAILs rather than being measured as its repr" \
desc-list "description is a list, not a string"
probe_all "a MAPPING description FAILs rather than being measured as its repr" \
desc-mapping "description is a dict, not a string"
probe_all "a BOOL description FAILs rather than being measured as the 4-char 'True'" \
desc-bool "description is a bool, not a string"
# ---------------------------------------------------------------------------
# 2c. The FAILURE CLASS reported has to be the one that happened
# ---------------------------------------------------------------------------
# The three fixtures above reach the same wrapper as a genuine YAML syntax
# error, and that wrapper used to prefix a hard-coded "frontmatter is not valid
# YAML (...)" onto all of them. For a non-string description that is false: the
# block parses, only the field's TYPE is wrong. On a blocking gate with no
# baseline it sent the author hunting for a syntax error that is not there. The
# assertion runs in both directions, because fixing it by dropping the phrase
# everywhere would trade one wrong diagnosis for another.
echo ""
echo "--- 'not valid YAML' is said for a syntax error and NOT for a wrong-typed description ---"
YAML_CLASS_PROBLEMS=""
for spec in "yaml-malformed|yes" "desc-list|no" "desc-mapping|no" "desc-bool|no"; do
kind="${spec%%|*}"
want="${spec#*|}"
build_subjects "$kind"
for target in \
"hook|$HOOK|$TMPDIR_T/$kind/skill/my-skill/SKILL.md" \
"skill-audit|$SKILL_VALIDATE|$TMPDIR_T/$kind/skill/my-skill" \
"agent-audit|$AGENT_VALIDATE|$TMPDIR_T/$kind/agent/.apm/agents/my-agent.agent.md"
do
who="${target%%|*}"; rest="${target#*|}"
script="${rest%%|*}"; arg="${rest#*|}"
set +e
out="$(bash "$script" "$arg" 2>&1)"
set -e
if [[ "$want" == yes && "$out" != *"frontmatter is not valid YAML"* ]]; then
YAML_CLASS_PROBLEMS="$YAML_CLASS_PROBLEMS [$who did not call $kind a YAML syntax error: $out]"
fi
if [[ "$want" == no && "$out" == *"not valid YAML"* ]]; then
YAML_CLASS_PROBLEMS="$YAML_CLASS_PROBLEMS [$who called $kind invalid YAML, but the frontmatter parsed: $out]"
fi
done
done
if [[ -z "$YAML_CLASS_PROBLEMS" ]]; then
pass "a type error is reported as a type error and a syntax error as a syntax error"
else
fail "wrong failure class reported —$YAML_CLASS_PROBLEMS"
fi
# The specific regression, spelled out: the valueless-description agent file must # The specific regression, spelled out: the valueless-description agent file must
# not merely fail — it must not be SILENT. Zero output on a blocking gate is what # not merely fail — it must not be SILENT. Zero output on a blocking gate is what
# made this un-diagnosable, so the output is asserted non-empty independently. # made this un-diagnosable, so the output is asserted non-empty independently.

201
tests/test-adr0020-targets.sh
View File

@@ -13,6 +13,14 @@
# identical with and without a deployed tree — on a synthetic fixture AND on # identical with and without a deployed tree — on a synthetic fixture AND on
# the real 39-skill corpus. # the real 39-skill corpus.
# #
# Three further ways the universe can be built out of the wrong directory,
# each of which shipped: a `.git` at the CONSUMER root (the fallback is
# truthy in any git repo, which made the deployed-tree branch dead code), a
# `.git` INSIDE a plugin (the walk-up is two passes precisely so this cannot
# capture the root), and glob metacharacters in the checkout path (which
# turned the directory name into a character class matching nothing, and the
# resolver into a no-op that still reported green).
#
# 2. THE BARE-TARGET GRAMMAR RULE. A hyphenated token used as a compound # 2. THE BARE-TARGET GRAMMAR RULE. A hyphenated token used as a compound
# MODIFIER ("pre-commit hooks", "pull-request template") is prose, not a # MODIFIER ("pre-commit hooks", "pull-request template") is prose, not a
# route; a terminal one is a real target. Getting this wrong in either # route; a terminal one is a real target. Getting this wrong in either
@@ -138,6 +146,175 @@ else
fail "the consumer path did not resolve through the deployed tree (exit $CONSUMER_RC): ${CONSUMER_OUT:-<empty>}" fail "the consumer path did not resolve through the deployed tree (exit $CONSUMER_RC): ${CONSUMER_OUT:-<empty>}"
fi fi
# ---------------------------------------------------------------------------
# 1a-bis. The consumer case with the one thing every real consumer has: .git
# ---------------------------------------------------------------------------
# The fixture immediately above has no .git, and that is precisely why it could
# never catch this. _authoring_root() falls back to the nearest .git ancestor, so
# it returns truthy in ANY git repo — a consumer checkout included. The branch
# that reads the deployed trees was guarded by `else`, so in every consumer
# checkout the fallback won, _collect_authoring_root() contributed nothing
# (there is no plugins/ directory to collect), and _deployed_roots() was dead
# code in exactly the case it exists for.
#
# The pair below is the whole test: the SAME tree, once with .git and once
# without. Old behaviour was rc=1 with .git and rc=0 without; a test covering
# only the no-.git shape reports green on both.
#
# `deployed-only-agent` lives ONLY in .agents/agents/, so it can be reached
# through no route but _deployed_roots(). `sibling-skill` sits in .claude/skills/
# beside the subject, which the sibling-collection block above reaches on its own
# — it is the corroborator that makes the dangling target BLOCKING rather than a
# SUGGESTION, so the old failure shows up in the exit code and not only in prose.
echo ""
echo "--- a consumer checkout resolves through its deployed trees even though it is a git repo ---"
build_consumer() {
local root="$1"
mkdir -p "$root/.agents/agents"
write_skill "$root/.claude/skills/sibling-skill" sibling-skill \
"Use when doing the other thing. Do not use for anything else."
write_skill "$root/.claude/skills/my-skill" my-skill \
"Use when doing the thing. Do not use for the other thing — use sibling-skill or deployed-only-agent instead."
: > "$root/.agents/agents/deployed-only-agent.agent.md"
}
build_consumer "$TMPDIR_T/consumer-git"
mkdir -p "$TMPDIR_T/consumer-git/.git"
build_consumer "$TMPDIR_T/consumer-nogit"
# consumer_case <label> <root>
consumer_case() {
local label="$1" root="$2" out status=0
set +e
out="$(bash "$HOOK" "$root/.claude/skills/my-skill/SKILL.md" 2>&1)"
status=$?
set -e
if [[ $status -eq 0 && "$out" != *"routes to"* && "$out" != *"DID NOT RUN"* ]]; then
pass "$label"
else
fail "$label (exit $status, output: ${out:-<empty>})"
fi
}
consumer_case "an agent in .agents/agents/ resolves in a consumer checkout that HAS a .git directory" \
"$TMPDIR_T/consumer-git"
consumer_case "control: the same tree without .git resolves too (the shape that always passed)" \
"$TMPDIR_T/consumer-nogit"
# ---------------------------------------------------------------------------
# 1a-ter. A monorepo with ONE plugin is still a monorepo
# ---------------------------------------------------------------------------
# The first attempt at the fix above conditioned the deployed branch on whether
# the authoring root had CONTRIBUTED a name — `if len(names) == before:`. That
# reads as "the .git fallback collected nothing, so fall through", and it is
# wrong: _collect_authoring_root() re-collects the subject's OWN plugin, whose
# names the sibling and package blocks have already added. With two plugins
# (fixture 1) the cross-plugin name makes the delta non-zero and the guard stays
# shut. With ONE plugin the delta is zero, the guard fires in a genuine
# monorepo, and _deployed_roots() walks up to ten levels — reaching the user's
# global ~/.claude/skills. That is install-dependence again, in the shape
# ADR-0020 lines 118-127 exist to forbid.
#
# So the predicate is which PROBE matched, not how many names arrived. The
# assertion is the same shape as fixture 1 — identical verdict either way — but
# on a single-plugin tree, which fixture 1 cannot express.
echo ""
echo "--- a SINGLE-plugin monorepo does not fall through to the deployed trees ---"
build_single() {
local root="$1"
write_skill "$root/plugins/only-plugin/.apm/skills/my-skill" my-skill \
"Use when doing the thing. Do not use for the other thing — use /deployed-only-skill instead."
}
build_single "$TMPDIR_T/single-no-claude"
build_single "$TMPDIR_T/single-with-claude"
write_skill "$TMPDIR_T/single-with-claude/.claude/skills/deployed-only-skill" deployed-only-skill \
"Use when doing the other thing. Do not use for anything else."
run_single() {
local root="$1" out
set +e
out="$(bash "$HOOK" "$root/plugins/only-plugin/.apm/skills/my-skill/SKILL.md" 2>&1)"
set -e
printf '%s\n' "$out" | sed "s#$root#<ROOT>#g"
}
SINGLE_NO_OUT="$(run_single "$TMPDIR_T/single-no-claude")"
SINGLE_WITH_OUT="$(run_single "$TMPDIR_T/single-with-claude")"
if [[ "$SINGLE_NO_OUT" == "$SINGLE_WITH_OUT" ]]; then
pass "a single-plugin monorepo gets the same verdict with and without a deployed .claude/ tree"
else
fail "the deployed tree changed the verdict in a single-plugin monorepo — without: [$SINGLE_NO_OUT] with: [$SINGLE_WITH_OUT]"
fi
# Identical-but-wrong guard, as in fixture 1: the deployed-only name must DANGLE,
# not resolve. Written as `/deployed-only-skill` so it blocks on its own without
# needing a second target in the sentence to corroborate it.
if [[ "$SINGLE_WITH_OUT" == *"routes to 'deployed-only-skill'"* ]]; then
pass "the deployed-only target dangles in a single-plugin monorepo (~/.claude/skills is not in the universe)"
else
fail "the deployed-only target resolved — the single-plugin tree fell through to _deployed_roots(): $SINGLE_WITH_OUT"
fi
# ---------------------------------------------------------------------------
# 1c. A nested .git inside a plugin must not beat the monorepo root
# ---------------------------------------------------------------------------
# ADR-0020 records the walk-up as TWO passes — plugins/*/.apm/{skills,agents}
# first, .git only afterwards — specifically so a .git inside a plugin (a
# submodule, or a sub-package with its own worktree) cannot capture the root.
# Nothing anywhere placed a .git inside a plugin, so the second pass was
# structural claim only. Collapsing the two probes into one interleaved walk
# passes every other fixture in this repo and fails here.
echo ""
echo "--- a .git INSIDE a plugin does not shadow the monorepo root above it ---"
NESTED="$TMPDIR_T/nested-git"
write_skill "$NESTED/plugins/other-plugin/.apm/skills/cross-plugin-skill" cross-plugin-skill \
"Use when doing the other thing. Do not use for anything else."
write_skill "$NESTED/plugins/subject-plugin/.apm/skills/sibling-skill" sibling-skill \
"Use when doing the other thing. Do not use for anything else."
write_skill "$NESTED/plugins/subject-plugin/.apm/skills/my-skill" my-skill \
"Use when doing the thing. Do not use for the other thing — use sibling-skill or cross-plugin-skill instead."
# The trap: a git checkout one level BELOW the monorepo root and above the skill.
mkdir -p "$NESTED/plugins/subject-plugin/.git"
set +e
NESTED_OUT="$(bash "$HOOK" "$NESTED/plugins/subject-plugin/.apm/skills/my-skill/SKILL.md" 2>&1)"
NESTED_RC=$?
set -e
# The sibling-plugin name is the discriminator: it is reachable ONLY from the
# monorepo root. If the nested .git won, subject-plugin would be the root, its
# plugins/ glob would collect nothing, and cross-plugin-skill would dangle —
# corroborated by sibling-skill in the same sentence, so it would BLOCK.
if [[ $NESTED_RC -eq 0 && "$NESTED_OUT" != *"routes to"* && "$NESTED_OUT" != *"DID NOT RUN"* ]]; then
pass "a sibling-plugin target still resolves with a .git directory inside the subject's own plugin"
else
fail "the nested .git captured the authoring root (exit $NESTED_RC): ${NESTED_OUT:-<empty>}"
fi
# ---------------------------------------------------------------------------
# 1d. Glob metacharacters in the checkout path
# ---------------------------------------------------------------------------
# The universe is built with glob.glob() against paths that begin with the
# checkout directory. A `[`, `]`, `*` or `?` anywhere in that prefix — a worktree
# named `feature[2]`, a CI workspace named `build[1]` — turned the literal
# directory name into a character class that matched nothing. The resolver then
# found no universe at all and degraded to the "DID NOT RUN" INFO with rc=0:
# every routing target in the tree silently unchecked, on a gate that reports
# green. Same monorepo as above, one directory renamed.
echo ""
echo "--- glob metacharacters in the checkout path do not silently disable the resolver ---"
GLOBDIR="$TMPDIR_T/gl[1]?x/mono"
write_skill "$GLOBDIR/plugins/other-plugin/.apm/skills/cross-plugin-skill" cross-plugin-skill \
"Use when doing the other thing. Do not use for anything else."
write_skill "$GLOBDIR/plugins/subject-plugin/.apm/skills/sibling-skill" sibling-skill \
"Use when doing the other thing. Do not use for anything else."
write_skill "$GLOBDIR/plugins/subject-plugin/.apm/skills/my-skill" my-skill \
"Use when doing the thing. Do not use for the other thing — use sibling-skill or cross-plugin-skill instead."
set +e
GLOB_OUT="$(bash "$HOOK" "$GLOBDIR/plugins/subject-plugin/.apm/skills/my-skill/SKILL.md" 2>&1)"
GLOB_RC=$?
set -e
if [[ $GLOB_RC -eq 0 && "$GLOB_OUT" != *"DID NOT RUN"* && "$GLOB_OUT" != *"routes to"* ]]; then
pass "a monorepo under a directory named 'gl[1]?x' resolves exactly like any other"
else
fail "glob metacharacters in the path changed the verdict (exit $GLOB_RC): ${GLOB_OUT:-<empty>}"
fi
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# 1b. Machine independence — the real corpus # 1b. Machine independence — the real corpus
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
@@ -387,6 +564,30 @@ grammar_case tp-backticked errors "routes to 'no-such-backticked-skill'" \
grammar_case tp-bare-terminal errors "routes to 'no-such-bare-skill'" \ grammar_case tp-bare-terminal errors "routes to 'no-such-bare-skill'" \
"Use when doing the thing. Do not use for improvements — use sibling-skill or no-such-bare-skill instead." "Use when doing the thing. Do not use for improvements — use sibling-skill or no-such-bare-skill instead."
echo ""
echo "--- corroboration is scoped to a REAL sentence, not to whatever the splitter says ---"
# Corroboration decides SUGGESTION vs blocking ERROR, so a mis-placed sentence
# boundary moves a target between the two tiers. The naive "period, space,
# capital" rule got this wrong in both directions, and both were live:
#
# OVER-SPLIT. `e.g. "..."` is not a sentence end, but the quote looks like a
# start. The clause was cut in half and the corroborator stranded on the far
# side, so a target that DOES sit beside a resolving sibling silently demoted
# to SUGGESTION — a measurement taken and then discarded.
grammar_case abbrev-split errors "routes to 'no-such-abbrev-skill'" \
"Use when doing the thing. Do not use for improvements — use sibling-skill first, e.g. \"run the audit\", then use no-such-abbrev-skill instead."
#
# UNDER-SPLIT. A sentence opening with a lowercase word or a code span was not
# seen as a start at all, so two sentences merged and a resolving target in the
# FIRST vouched for an unresolvable one in the SECOND that it never stood
# beside — a hard FAIL with no escape hatch, which is the exact failure
# corroboration was added to prevent. The target must still be REPORTED; only
# the power to block is withdrawn.
grammar_case lowercase-start suggests "routes to 'no-such-lower-skill'" \
"Use when doing the thing. Use sibling-skill for the main case. do not use for improvements — use no-such-lower-skill instead."
grammar_case backtick-start suggests "routes to 'no-such-tick-skill'" \
"Use when doing the thing. Use sibling-skill for the main case. \`no-such-tick-skill\` is not for this — do not use it instead."
# And the confirming half of the grammar rule: a compound-modifier target is # And the confirming half of the grammar rule: a compound-modifier target is
# CONFIRM-ONLY, not ignored. When the name does exist it still counts as a route # CONFIRM-ONLY, not ignored. When the name does exist it still counts as a route
# — the rule suppresses the ERROR, it does not delete the target. # — the rule suppresses the ERROR, it does not delete the target.

16
tests/test-check-vale-style-sync.sh
View File

@@ -457,8 +457,8 @@ fi
# --- 9b. Exits 1 when a per-rule override leaves a rule at anything but error --- # --- 9b. Exits 1 when a per-rule override leaves a rule at anything but error ---
# The third way to switch a rule off without touching a style file or a glob. # The third way to switch a rule off without touching a style file or a glob.
# CONTEXT.md's "Vale audit prefilter" entry: "Every rule is `level: error` and # Per ADR-0013, every rule is `level: error` and every alert is a FAIL -- there
# every alert is a FAIL -- no ignorable tier". Vale's exit code keys on `error` # is no ignorable tier. Vale's exit code keys on `error`
# alerts alone, so any such override leaves the glob intact, the styles # alerts alone, so any such override leaves the glob intact, the styles
# byte-identical, and the run at `0 errors`, exit 0, `Passed`. # byte-identical, and the run at `0 errors`, exit 0, `Passed`.
# #
@@ -553,9 +553,9 @@ fi
# equality check applies, and case 10's probe still passed because it keys on a # equality check applies, and case 10's probe still passed because it keys on a
# Kyberforge alert. Verified dead by probing a `.agent.md` carrying # Kyberforge alert. Verified dead by probing a `.agent.md` carrying
# "Use proactively": 0 alerts under the broken config, KyberforgeCopilot. # "Use proactively": 0 alerts under the broken config, KyberforgeCopilot.
# ProactivePhrase under the shipped one. CONTEXT.md describes the style as # ProactivePhrase under the shipped one. ADR-0013 scopes the style to
# "scoped only to `.agent.md` files for the Copilot-only 'Use proactively has # `.agent.md` files only, for the Copilot-only 'Use proactively has no effect'
# no effect' check", so shipping it unloaded is drift. # check, so shipping it unloaded is drift.
echo "" echo ""
echo "--- exits 1 when the shipped KyberforgeCopilot style is named by no BasedOnStyles ---" echo "--- exits 1 when the shipped KyberforgeCopilot style is named by no BasedOnStyles ---"
FIXTURE11C="$(make_fixture)" FIXTURE11C="$(make_fixture)"
@@ -609,9 +609,9 @@ fi
# still matched all of them and the check passed -- while a project-scope # still matched all of them and the check passed -- while a project-scope
# `.claude/skills/foo/SKILL.md` started linting as `0 errors ... in 0 files`, # `.claude/skills/foo/SKILL.md` started linting as `0 errors ... in 0 files`,
# exit 0, hook `Passed`: the exact failure the script's own header comment says # exit 0, hook `Passed`: the exact failure the script's own header comment says
# it exists to catch. CONTEXT.md: "A `SKILL.md` outside `plugins/` (e.g. # it exists to catch. A `SKILL.md` outside `plugins/` (e.g. project-scope
# project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and # `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted
# gets linted normally -- the globs constrain filename shape, not location." # normally -- the globs constrain filename shape, not location.
# These narrowings are still valid glob syntax and break no `plugins/`-shaped # These narrowings are still valid glob syntax and break no `plugins/`-shaped
# file, so only a non-`plugins/` probe path catches them. # file, so only a non-`plugins/` probe path catches them.
echo "" echo ""

9
tests/test-run-tests.sh
View File

@@ -392,10 +392,11 @@ fi
# --- 10. --strict turns a skip into a failure, and names the suite AND the reason --- # --- 10. --strict turns a skip into a failure, and names the suite AND the reason ---
# Graceful skipping is right for an ad-hoc run and wrong for a gate. At pre-push a # Graceful skipping is right for an ad-hoc run and wrong for a gate. At pre-push a
# suite exiting 77 means a dependency AGENTS.md documents as required is missing # suite exiting 77 means a dependency README.md's Prerequisites table documents
# on the pushing machine -- and pre-commit prints nothing at all for a passing # as required is missing on the pushing machine -- and pre-commit prints nothing
# hook, so the skip list this script writes to stdout was swallowed whole. A # at all for a passing hook, so the skip list this script writes to stdout was
# vale-less PATH shipped a green gate having verified 15 of 17 suites. # swallowed whole. A vale-less PATH once shipped a green gate having verified
# 15 of the 17 suites that existed then.
# #
# The reason is asserted, not just the name: "something was skipped" leaves the # The reason is asserted, not just the name: "something was skipped" leaves the
# reader with no idea which binary to install, which is most of why the swallowed # reader with no idea which binary to install, which is most of why the swallowed

30
tests/test-skill-size-check.sh
View File

@@ -535,19 +535,31 @@ expect_gate "a fixture with no authoring root reports DID NOT RUN and exits 0" \
"Unchecked target(s): some-other-skill" "Unchecked target(s): some-other-skill"
echo "" echo ""
echo "--- the three live dangling routing targets are caught (issue #100) ---" echo "--- the live dangling routing targets are caught (issue #100) ---"
# ADR-0020 records four broken routing targets and splits fixing them into its # ADR-0020 records the broken routing targets and splits fixing them into its own
# own issue. Three are detectable from the description text alone; this asserts # issue. This asserts the gate actually sees them rather than the check being
# the gate actually sees them rather than the check being vacuous in the corpus # vacuous in the corpus it was written against.
# it was written against. #
# There used to be a third probe here, for `skill-improve` in skill-audit's
# description. It was already stale: that target was fixed, so the iteration
# permanently took a `pass "SKIP: ..."` branch — an assertion-free result counted
# in the totals, which is worse than no probe at all because it makes the suite
# look one test stronger than it is. It also contradicted
# tests/test-adr0020-targets.sh, which pins the live dangling set as EXACTLY
# {gitea-labels, neuledge-context}; that file is the authority on the set, this
# one only checks the two are individually detected.
#
# Both SKIP branches are gone with it, for the same reason. A probe whose fixture
# has been retrofitted is not "still passing" — it is a pin that needs updating,
# here and in the exact-set assertion in test-adr0020-targets.sh, and it should
# say so out loud rather than quietly agreeing with whatever it finds.
for probe in \ for probe in \
"plugins/bin/.apm/skills/research/SKILL.md:neuledge-context" \ "plugins/bin/.apm/skills/research/SKILL.md:neuledge-context" \
"plugins/kyberforge/.apm/skills/skill-audit/SKILL.md:skill-improve" \
"plugins/gitea/.apm/skills/gitea-issues/SKILL.md:gitea-labels"; do "plugins/gitea/.apm/skills/gitea-issues/SKILL.md:gitea-labels"; do
probe_file="$REPO_ROOT/${probe%%:*}" probe_file="$REPO_ROOT/${probe%%:*}"
probe_name="${probe##*:}" probe_name="${probe##*:}"
if [[ ! -f "$probe_file" ]]; then if [[ ! -f "$probe_file" ]]; then
pass "SKIP: ${probe%%:*} no longer exists (retrofitted)" fail "the probe fixture ${probe%%:*} no longer exists — this pin has become vacuous; update it and EXPECTED_DANGLING in tests/test-adr0020-targets.sh together"
continue continue
fi fi
# Captured, not piped: the script exits non-zero on these files and # Captured, not piped: the script exits non-zero on these files and
@@ -558,10 +570,8 @@ for probe in \
set -e set -e
if [[ "$probe_out" == *"routes to '$probe_name'"* ]]; then if [[ "$probe_out" == *"routes to '$probe_name'"* ]]; then
pass "detects the dangling '$probe_name' target in ${probe%%:*}" pass "detects the dangling '$probe_name' target in ${probe%%:*}"
elif ! grep -q "$probe_name" "$probe_file"; then
pass "SKIP: '$probe_name' no longer appears in ${probe%%:*} (fixed by issue #100)"
else else
fail "did not detect the dangling '$probe_name' target in ${probe%%:*}" fail "did not detect the dangling '$probe_name' target in ${probe%%:*}. If issue #100 retrofitted it, drop this probe and update EXPECTED_DANGLING in tests/test-adr0020-targets.sh; if a false-positive fix took a true positive with it, that is the regression this asserts."
fi fi
done done

7
tests/test-vale-wrap.sh
View File

@@ -451,8 +451,11 @@ fi
# cover anything new: it omitted scripts/lib/batch-run.sh — the shared runner # cover anything new: it omitted scripts/lib/batch-run.sh — the shared runner
# this branch introduced, whose own header (batch-run.sh:9-11) documents it as # this branch introduced, whose own header (batch-run.sh:9-11) documents it as
# bash-3.2-safe — along with four other scripts/*.sh. Deriving the list means a # bash-3.2-safe — along with four other scripts/*.sh. Deriving the list means a
# new script is covered the moment it lands. AGENTS.md names bash 3.2 as an # new script is covered the moment it lands. The script headers name bash 3.2 as
# explicit repo target, so the scope is four globs, each floor-asserted below: # an explicit repo target -- scripts/lib/batch-run.sh:10 ("all three callers are
# explicitly bash-3.2-safe") and providers/claude-code/statusline-command.sh:100
# ("macOS's system bash, and an explicit repo target") -- so the scope is four
# globs, each floor-asserted below:
# - scripts/**/*.sh — repo tooling and pre-commit hook scripts # - scripts/**/*.sh — repo tooling and pre-commit hook scripts
# - tests/*.sh — the runners and every regression test # - tests/*.sh — the runners and every regression test
# - plugins/*/.apm/**/*.sh — the scripts plugins ship to users # - plugins/*/.apm/**/*.sh — the scripts plugins ship to users