From 123ece2fb3080458b5da1486b19e3cd5f87134b2 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 08:56:22 +0000 Subject: [PATCH 01/16] 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. --- apm.lock.yaml | 350 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 279 insertions(+), 71 deletions(-) diff --git a/apm.lock.yaml b/apm.lock.yaml index 899b302..b236fe6 100644 --- a/apm.lock.yaml +++ b/apm.lock.yaml @@ -1,11 +1,11 @@ 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 dependencies: - repo_url: Defame1297/holocron name: bin host: git.dev.rkdr.net - resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 + resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae version: 1.1.3 virtual_path: plugins/bin is_virtual: true @@ -87,7 +87,7 @@ dependencies: - repo_url: Defame1297/holocron name: core host: git.dev.rkdr.net - resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 + resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae version: 1.1.1 virtual_path: plugins/core is_virtual: true @@ -134,7 +134,7 @@ dependencies: - repo_url: Defame1297/holocron name: git host: git.dev.rkdr.net - resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 + resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae version: 1.3.3 virtual_path: plugins/git is_virtual: true @@ -241,7 +241,7 @@ dependencies: - repo_url: Defame1297/holocron name: gitea host: git.dev.rkdr.net - resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 + resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae version: 1.3.4 virtual_path: plugins/gitea is_virtual: true @@ -332,8 +332,8 @@ dependencies: - repo_url: Defame1297/holocron name: kyberforge host: git.dev.rkdr.net - resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 - version: 1.5.0 + resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae + version: 1.6.0 virtual_path: plugins/kyberforge is_virtual: true package_type: marketplace_plugin @@ -344,15 +344,20 @@ dependencies: - .claude/skills/agent-audit/README.md - .claude/skills/agent-audit/SKILL.md - .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/PaddingPhrase.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/KyberforgeCopilot/ProactivePhrase.yml - .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/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/validation-scripts.md - .claude/skills/agent-audit/scripts/README.md - .claude/skills/agent-audit/scripts/vale-wrap.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/copilot.agent.md.template - .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/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/sources.md - .claude/skills/agent-author/scripts/README.md @@ -391,13 +401,18 @@ dependencies: - .claude/skills/skill-audit/README.md - .claude/skills/skill-audit/SKILL.md - .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/PaddingPhrase.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/references/body-discipline.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/validation-scripts.md - .claude/skills/skill-audit/scripts/vale-wrap.sh - .claude/skills/skill-audit/scripts/validate-provenance.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/scripts/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/improve.md + - .claude/skills/skill-author/references/retrofit.md - .claude/skills/skill-author/references/scripts.md - .claude/skills/skill-author/references/sources.md - .claude/skills/skill-author/scripts/new-skill.sh deployed_file_hashes: .claude/agents/apm-orchestrate.md: sha256:fbb78f7c8c58b018639e7a39f2f1b3ce2adcd6bed277b3c8f8cd70893698ec73 .claude/hooks/kyberforge/.apm/hooks/check-apm-current.sh: sha256:96f44d63b5f4906ac1add5c32b718176ec10c8514615151d7303d9845c607b46 - .claude/skills/agent-audit/README.md: sha256:a3a63acb80981975330bd9a86d81c8f3e632f7f2d97ac99951710d035fb52953 - .claude/skills/agent-audit/SKILL.md: sha256:080f391ea25de8afc5a20478cbd382a8d28fcf70a7be7f012033dacb6e9bfed3 + .claude/skills/agent-audit/README.md: sha256:fafdb84bf258f6d606c97b785c7c378b5de805f0aa8a10d3cedefedb000e4230 + .claude/skills/agent-audit/SKILL.md: sha256:a126a2a7b1b8c9f6b39272584e2f84577aeeb8c81707be6f151b3acbe35ecf51 .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/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629 .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/references/README.md: sha256:7664ae08efc8373c0b253c0a5c7a9cc930720c62abb8d31a81b2aedbd573dd30 - .claude/skills/agent-audit/references/description-quality.md: sha256:79c62fd641d6785a3349d8ff1e207c64547ef9435d51e88518fc9fb5c2f4962e + .claude/skills/agent-audit/references/README.md: sha256:f6d777f7d3844d1be847f86f67b08c2db37b2d122e0bf1af92ef057bbfdd1004 + .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/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/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995 .claude/skills/agent-audit/scripts/validate-provenance.sh: sha256:0e1d2b3bb1abb9f302ed84a618246ebaa7d5f7fda727b290d323e70dcc26a323 - .claude/skills/agent-audit/scripts/validate.sh: sha256:29727875f419b8d3b6c76f157b7569adb4d2b9a88f01eeb2c09e04dfb8541cb3 - .claude/skills/agent-author/README.md: sha256:015a6b030ff2aa913f982a223f8afad789edadc4e7148d3b1740a56b346c658d - .claude/skills/agent-author/SKILL.md: sha256:39193473a9b1beacb4790cab4e5e31e01f7021a68a5c4cc16a606420bee65d6a - .claude/skills/agent-author/assets/README.md: sha256:a82665201ead91b7fa2b37629327ecb89ca785b7f2b261300c2dd816b4219bcd - .claude/skills/agent-author/assets/templates/apm-agent.md: sha256:c2693395d7ec72645fc1b79c65039ddadc0077f5856de3277d600bde41f17e54 - .claude/skills/agent-author/assets/templates/claude-code.md: sha256:eef5ee46d93b6896e880b3c4aec1121c4077a2556c6d9f4a01b322afc7b63a7e - .claude/skills/agent-author/assets/templates/copilot.agent.md.template: sha256:1e0c0445a8908148e69baeeb44316fb370aa483e17fcd63d7f1b2d3ad1927788 - .claude/skills/agent-author/references/README.md: sha256:bb4cf7a34c512da33f574b208756941f396f4a1e55daaed0fad22569a22af301 - .claude/skills/agent-author/references/deployment-modes.md: sha256:6cd010455e10574566ebf7cfd0926217ae5812d56a62daf4bcdb325abf3b0421 + .claude/skills/agent-audit/scripts/validate.sh: sha256:50c6d3875fd44901fba3fcb69256f616be19521ee8209b7132778c1d4a693a3f + .claude/skills/agent-author/README.md: sha256:b2d14a3c8fc3ddc3935d0bd1765192b333b944baaf9bfa9a350bef0985890265 + .claude/skills/agent-author/SKILL.md: sha256:8fe96e4744378cd33876cf87a08a20af001898e89f0f27087044e1b87eac61f2 + .claude/skills/agent-author/assets/README.md: sha256:730b2321b5f16dcc63fc5dc842618c116afc75217ae925057dafc490e7d57644 + .claude/skills/agent-author/assets/templates/apm-agent.md: sha256:9b57e2b93a5705388351f14294d60833325d9596cf5294d22f4a586165fc35fa + .claude/skills/agent-author/assets/templates/claude-code.md: sha256:ea0bac6e8cd91c767c6114cbcf1ecd124d03abff06ba81696dac5115499c395a + .claude/skills/agent-author/assets/templates/copilot.agent.md.template: sha256:ee8b7585c808c5ff4b715be74d9e4f8c5c17d13cd603a8727cd8ca1793d14760 + .claude/skills/agent-author/references/README.md: sha256:aca156b02a3f0b9fddde3cefdb24370e17cc5886dcd78adcb382699a5cc0bbaf + .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/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/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/SKILL.md: sha256:4c0db5454bcbf895a89e7405eeefb4521a2b23f2ff28aa96c82c59708d8819ee .claude/skills/apm-install/references/sources.md: sha256:b80245ff8ae179d458572cb9b03621d00bf7e2f052f0cd71b88112c0ea8a91ce @@ -460,39 +489,48 @@ dependencies: .claude/skills/forge/README.md: sha256:2151b952f4438cd9212edd97de90eec06f027f01121b3badb9d32dc9c45320c4 .claude/skills/forge/SKILL.md: sha256:4de4c629cb4aec4c6cac5347163a86fe123299f131510dc43857597ded6ae497 .claude/skills/forge/references/sources.md: sha256:a7f614c0ab37aa403545e191722bca012836162dcab30ff8ac984cbb25ad68cd - .claude/skills/skill-audit/README.md: sha256:9e3533c3c44cfd249cf02684ef43db822ed41382362e8ce71f1254d10711c8e0 - .claude/skills/skill-audit/SKILL.md: sha256:dbe2adfd0101cf9d6b3c2c3c2aa3ae397c717f835c1059c0f1d805e9057dc397 + .claude/skills/skill-audit/README.md: sha256:78bfcfb16bbeef814b83f37a4a5185886003f9442a6d0e7e94be56f54d18d7a5 + .claude/skills/skill-audit/SKILL.md: sha256:57a9336d409c883dc9a78aa92a9f0075fac6f8e4aac6ee8fdab705055ef85162 .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/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629 .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/description-quality.md: sha256:ab077e71bbc6e9d8e2a1384bedaf613a4219f28bbe42eb9e89f933b579db6b33 - .claude/skills/skill-audit/references/sources.md: sha256:cb65dd3cc411d7b264fab24de5cd2353dec8fbb7bbcfe2388535d963be240280 + .claude/skills/skill-audit/references/body-discipline.md: sha256:f8a27d7266f4453781712f0bead151580158581a445a641613203a67a1c337d7 + .claude/skills/skill-audit/references/description-quality.md: sha256:2d37eccb4889cade6cbad0deaaed6d1f5fe4c3276c5438c244b2f87ae27bf432 + .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/validate-provenance.sh: sha256:015376c5ad1f6bb6b53549537317a55e3ac06cd4e347451dba85879a3928ccbe - .claude/skills/skill-audit/scripts/validate.sh: sha256:ebbef859276135b7fe4189b31396fd98e5d4019685d7cb55e39a10fac8ca546d - .claude/skills/skill-author/README.md: sha256:6c0b36f9b28a33de1646df45bd8e4d733ab3b26c0bdff49743962aa068085f6d - .claude/skills/skill-author/SKILL.md: sha256:7b82d16fe0d61a71c5b59a244cf92b9b5fc2635916ad1572f4f5f6e37172bf09 + .claude/skills/skill-audit/scripts/validate.sh: sha256:7ce27df82e4160c6296db6c8314865f022da5c4334151857570a86167c8d4e11 + .claude/skills/skill-author/README.md: sha256:d22035d302818e103486e447bd92d2da4c9b73da60f30157941710f32f400b89 + .claude/skills/skill-author/SKILL.md: sha256:615a936580f44dd8e523496aadf88df6d512ac58369190b90407e8fca86e8345 .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/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/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2 .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/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/sources.md: sha256:27637acad4c0cdc7f1db15bc9cab339ebdac643e084642c58945ac2f81020c75 - .claude/skills/skill-author/scripts/new-skill.sh: sha256:46c6903404b9eabbd6c83892213fdabf9cad193be64613b8c1b84c8dc37e8eb2 - content_hash: sha256:c89a45409fd3e06a6c63ca8a8f0f0d9c8e10bbded73fdef15dd482eebc6b6a78 + .claude/skills/skill-author/references/sources.md: sha256:652f7ce26c0d68a3ed11db09206bff20ba230ca8ff1fe71ae45b6f4505979327 + .claude/skills/skill-author/scripts/new-skill.sh: sha256:c788b56f73ed4fd03edb179159361fe16e3afbf528a9895e9251909c5aa40a7f + content_hash: sha256:32185a11d3d859e5235de2c43065920ba8950c1684e6aec46f0f7170ff4a111e declared_license: MIT exec_status: deployed - repo_url: Defame1297/holocron name: lint host: git.dev.rkdr.net - resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 + resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae version: 1.1.6 virtual_path: plugins/lint is_virtual: true @@ -519,9 +557,8 @@ dependencies: .claude/skills/vale-run/SKILL.md: sha256:16c42c97de14ef20296b9dfce46b0e2f9be6ad68751c35975251cecff80f79d9 .claude/skills/vale-run/references/sources.md: sha256:1f46b727e5f3db09d6c8c01c8a615bad60ce2c5b3a01226e1a3fd3b933330bc7 .claude/skills/vale-run/references/troubleshooting.md: sha256:b4c2bc67b413b102d9fe1cd7e5a248b19aba3dc3b60b4429e777977cf8021cd5 - content_hash: sha256:7bc57b8852680bdcba32a6a6108b99ef6bcdf26eacfecd806c421ec5d1fd47d9 + content_hash: sha256:f7915119bf5d349bb4dd26b7999278770dd2e0b38e4b4db57c0819a15cbf97a3 declared_license: MIT - exec_status: gated_pending_approval deployments: - kind: project-relative target: claude @@ -585,7 +622,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-audit/SKILL.md @@ -594,7 +631,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-audit/assets/vale/.vale.ini @@ -604,6 +641,15 @@ deployments: - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge 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 target: claude value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml @@ -612,7 +658,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml @@ -657,7 +703,16 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-audit/references/description-quality.md @@ -666,7 +721,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-audit/references/field-inventory.md @@ -676,6 +731,24 @@ deployments: - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge 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 target: claude value: .claude/skills/agent-audit/references/sources.md @@ -684,7 +757,16 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-audit/scripts/README.md @@ -720,7 +802,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author @@ -738,7 +820,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/SKILL.md @@ -747,7 +829,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/assets/README.md @@ -756,7 +838,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/assets/templates/apm-agent.md @@ -765,7 +847,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/assets/templates/claude-code.md @@ -774,7 +856,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/assets/templates/copilot.agent.md.template @@ -783,7 +865,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/references/README.md @@ -792,7 +874,25 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/references/deployment-modes.md @@ -801,7 +901,34 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/references/scripts.md @@ -819,7 +946,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agent-author/scripts/README.md @@ -837,7 +964,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/agentsmd-audit @@ -2241,7 +2368,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-audit/SKILL.md @@ -2250,7 +2377,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-audit/assets/vale/.vale.ini @@ -2260,6 +2387,15 @@ deployments: - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge 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 target: claude value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml @@ -2268,7 +2404,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml @@ -2304,7 +2440,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-audit/references/description-quality.md @@ -2313,7 +2449,34 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-audit/references/sources.md @@ -2322,7 +2485,16 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-audit/scripts/vale-wrap.sh @@ -2349,7 +2521,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-author @@ -2367,7 +2539,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-author/SKILL.md @@ -2376,7 +2548,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-author/assets/templates/README.md @@ -2394,7 +2566,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-author/assets/templates/assets/README.md @@ -2412,7 +2584,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-author/assets/templates/references/sources.md @@ -2440,6 +2612,24 @@ deployments: - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge 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 target: claude value: .claude/skills/skill-author/references/deployment-modes.md @@ -2449,6 +2639,24 @@ deployments: - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge 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 target: claude value: .claude/skills/skill-author/references/scripts.md @@ -2466,7 +2674,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/skill-author/scripts/new-skill.sh @@ -2475,7 +2683,7 @@ deployments: owners: - 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 target: claude value: .claude/skills/tdd -- 2.43.0 From 1929ffd2da87444aa6155a1308bbd0083c377263 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 08:56:37 +0000 Subject: [PATCH 02/16] docs: slim AGENTS.md to per-session context only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- AGENTS.md | 60 ++--- README.md | 126 ++++++++++ docs/spec/architecture.md | 2 +- docs/spec/gates.md | 471 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 621 insertions(+), 38 deletions(-) create mode 100644 README.md create mode 100644 docs/spec/gates.md diff --git a/AGENTS.md b/AGENTS.md index 8eaf095..fbc7ee4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,29 +1,25 @@ # 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 -- `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 @holocron` — the marketplace manifests are unchanged -- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`) +- `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 `scripts/install.sh`. ## Edit `.apm/`, never the flat mirror -Inside a plugin, `plugins//.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//.apm/` is the only hand-edited source for plugin content. The flat `plugins//{skills,agents,commands,instructions,extensions}/` directories, the merged `plugins//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//{skills,agents,commands,instructions,extensions}/` directories and the merged `plugins//hooks/hooks.json` (ADR-0017) -- `apm pack` generates both per-plugin manifests — `plugins//.claude-plugin/plugin.json` and `plugins//.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 +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/`. -**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//skills/` is generated, `plugins//docs/` is not. `docs/spec/architecture.md` carries the same carve-out. - -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//hooks/` or `plugins//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`. +Full model: `docs/spec/architecture.md`. ## 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` - Pre-commit hook install/config/troubleshooting → `pc-run` / `pc-author` @@ -31,40 +27,30 @@ This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint t - Vale prose linting → `vale-config` / `vale-run` - 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//` as a plain project skill, which has no plugin prefix to carry. The `:` 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. The `:` form (`gitea:gitea-prs`) also still resolves, because user-scope native installs were left enabled on purpose (ADR-0018) — a working namespaced call is not evidence that anything is broken and is not something to "fix". Prefer the bare name anyway: it is what `apm install` deploys, and what survives those user-scope installs eventually being converted. 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//.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 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//.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`. -- 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. -- 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). -- 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`. -- 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`). -- 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. -- 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/.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 `/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 the walk found no plugin monorepo root — whether it landed on a bare `.git` ancestor or on nothing at all (the consumer case). The gate keys on which of the two passes matched, not on whether the root contributed any new name: a single-plugin monorepo re-collects its own package and adds nothing, so a name-count test reads zero there and would drag the deployed trees back into the universe. 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. -- **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`. -- **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 `#` 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. +- **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//.apm/hooks/` and deployed by apm, never hand-written into that file. Machine-specific settings go in the gitignored `.claude/settings.local.json`; shared enforcement goes 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. +- **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. +- **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`. +- **Run `bash tests/run-tests.sh` before considering any change done.** +- **Before pushing, run the whole gate locally:** `pre-commit run --hook-stage pre-push --all-files`. Pushing runs 14 repo-defined hooks, not just the test suite. +- **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. +- **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces. ## Key documents -Read CONTEXT.md at the start of every session in this repo. +Read `CONTEXT.md` at the start of every session. Read these on demand: -- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model +- `README.md` — prerequisites, install, and test commands +- `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/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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..c51958a --- /dev/null +++ b/README.md @@ -0,0 +1,126 @@ +# 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, 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, branch management, pull requests, feature flow +- **gitea** — issues, pull requests, milestones, releases, wikis +- **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it +- **lint** — configuring and running linters +- **bin** — a place for things to be binned + +## 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 +# (use the `pc-run` skill, which knows the stage wiring) +``` + +**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins//.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** go in via the `pc-run` skill, wiring **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). + +## 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 whole pre-push gate locally in one command: + +```bash +pre-commit run --hook-stage pre-push --all-files +``` + +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//.apm/` is the only hand-edited source for plugin content — skills, agents, commands, instructions, extensions, and hooks. The flat `plugins//{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 @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 diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 72f299c..3e6307a 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -63,4 +63,4 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for ## 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 20 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). diff --git a/docs/spec/gates.md b/docs/spec/gates.md new file mode 100644 index 0000000..ef83e09 --- /dev/null +++ b/docs/spec/gates.md @@ -0,0 +1,471 @@ +# 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 whole push gate, one command | +| `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. Fourteen is the count of repo-defined pre-push hooks. + +## The pre-push gate + +Fourteen hooks, in config order. + +**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 push to `main` only — fails if files exposed via `.pre-commit-hooks.yaml` changed since the last tag | + +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`. + +### 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 three 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 boundary-clause routing target must resolve** to a real skill or agent. +- **Every `references/.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. + +### 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 `/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 arithmetic depends on it: writing to the 400-char FAIL lands the preload at 39 × 400 = +15,600 chars (a 33% cut off 23,427); writing to the 250-char SUGGESTION lands at 9,750 (58%). The +halving depends entirely on that tier being visible. 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 . 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). + +### 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. + +### 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. + +## 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 `#` 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#` 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//.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` / `0015` / `0014` — 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 -- 2.43.0 From b9c7762463805049ad49b29b8d8d083cb6b4625f Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 09:28:01 +0000 Subject: [PATCH 03/16] docs: trim CONTEXT.md to a glossary and demote VISION.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 5 +- CONTEXT.md | 222 ++++++++++++------ ...013-vale-harness-scope-and-rule-sources.md | 6 + ...m-replaces-plugin-marketplace-authoring.md | 2 + ...nt-mirror-bridges-apm-to-host-discovery.md | 4 +- docs/spec/architecture.md | 19 +- docs/spec/gates.md | 175 +++++++++++++- 7 files changed, 361 insertions(+), 72 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fbc7ee4..b7d9e16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,14 +41,17 @@ Fall back to raw shell only when no skill covers it. - **Before pushing, run the whole gate locally:** `pre-commit run --hook-stage pre-push --all-files`. Pushing runs 14 repo-defined hooks, not just the test suite. - **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. - **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces. +- **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. ## Key documents -Read `CONTEXT.md` at the start of every session. +Read `CONTEXT.md` at the start of every session — it is this repo's domain language, and the terms in it are used unglossed everywhere else. Read these on demand: - `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 diff --git a/CONTEXT.md b/CONTEXT.md index 2a0dc12..ba247c5 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,106 +1,192 @@ --- 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 -`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. +## Language -### Instruction file format -`core/instructions/.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. +### Context cost -### Repo/gitea as source of truth -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. +**Preload tax**: +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. Measured 2026-08-14 at ~5,900 +tokens across 39 skills; method in `docs/spec/gates.md`. +_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 -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. +**Hand-invoked skill**: +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 -Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Authored at `plugins//.apm/skills//SKILL.md` and reaching a host by one of two install paths: `apm install`, which deploys the skill directory to `.claude/skills//` (this repo's own path — see "apm-consumed install"), or `claude plugin install @`, 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`). +**Delegation discipline**: +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 -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. +### Distribution -### Skill context contract -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 → ` 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 `/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. +**Skill**: +A reusable slash command defined as a `SKILL.md` file following the +[Agent Skills open standard](https://agentskills.io), authored at +`plugins//.apm/skills//SKILL.md`. +_Avoid_: command, prompt, macro -### 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. 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). +**Plugin**: +The deployable unit — one or more skills, agents, hooks, commands, and MCP servers bundled into a +single installable directory under `plugins//`, compiled from that plugin's `.apm/` source. +_Avoid_: package, bundle, module -### Hand-invoked skill -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. +**Plugin marketplace**: +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 -### Delegation discipline -The agent-side counterpart to the dispatch body. A plugin-scope agent is a single `.apm/agents/.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 `` 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. +**holocron**: +This repository, in its role as a plugin marketplace and as the remote the six plugin dependencies +resolve against. +_Avoid_: the marketplace, upstream -### Plugin -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//`, 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 @`, or consume it as an apm dependency (see "apm-consumed install"). +**apm-consumed install**: +How this repo installs its own plugins as of 2026-08-14 — six `dependencies.apm` entries in the root +`apm.yml` deployed by `apm install`, rather than `claude plugin install @holocron`. Its +consequences: ADR-0018. +_Avoid_: apm install, dependency install -### 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//` 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. +**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 -### apm-consumed install -How this repo installs its own plugins, as of 2026-08-14: not `claude plugin install @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 `@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. +### Governance -Four consequences, each load-bearing: -- **Skills gain an unnamespaced name.** apm deploys plain project skills, so `git:git-commits` also answers to `git-commits`. The `:` 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. -- **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. -- **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. -- **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. +**HITL** (human-in-the-loop): +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 -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//.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. +**HOTL** (human-on-the-loop): +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 -### HITL (human-in-the-loop) -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. +**Sycophancy**: +The failure mode where an RLHF-trained model prioritises approval over accuracy — changing a correct +answer to a wrong one under user pressure, then persisting in the wrong answer. Treated here as a +first-class reliability risk, not a quality-of-life concern. +_Avoid_: agreeableness, people-pleasing -### HOTL (human-on-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. +### Documents -### Sycophancy -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. +**AGENTS.md**: +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 -### AGENTS.md -The provider-agnostic always-on instruction entry point. Two files: -- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules); imported by repo `CLAUDE.md` via `@AGENTS.md`. -- **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`. +**Thin adapter**: +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 -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. +**LESSONS.md**: +The long-loop feedback log for patterns observed across sessions, at the repo root. Written by the +session-handoff skill or directly by the human. +_Avoid_: changelog, retro, postmortem -### Skill composition -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. +**Management Application**: +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 -### Provider-agnostic issue tracker -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). +### Quality -### Provenance chain -The three-stage traceability record linking a skill back to its research inputs: (1) `/research` produces topic docs and a `sources.md` in `plugins//docs/research/docs//`; (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. +**Skill composition**: +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 -### Bidirectional reference principle -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. +**Vale audit prefilter**: +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 -### agentsmd-author / agentsmd-audit -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. +**Issue**: +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 -### provider-adapter-author -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. +## Relationships -### lint plugin -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. +- 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. -### Vale audit prefilter (skill-audit / agent-audit) -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: , rev: ` 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. +## Example dialogue -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. +> **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." -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/.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 `` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible. +## Flagged ambiguities -### LESSONS.md -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. +- "skill" was used for both the authored `SKILL.md` under `plugins//.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 answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), because + user-scope native installs were left enabled deliberately (ADR-0018) — resolved: write the bare + name; a working namespaced call is not evidence of a defect. +- "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. diff --git a/docs/adr/0013-vale-harness-scope-and-rule-sources.md b/docs/adr/0013-vale-harness-scope-and-rule-sources.md index 2dfb67d..f35932d 100644 --- a/docs/adr/0013-vale-harness-scope-and-rule-sources.md +++ b/docs/adr/0013-vale-harness-scope-and-rule-sources.md @@ -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 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`, `**/*.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 diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md index 77b8a0e..d8fb9d3 100644 --- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -56,6 +56,8 @@ new hand-maintained manifest format. that work through to merge. - `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. + 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`. ## Considered options diff --git a/docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md b/docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md index ad7856a..35b8c2d 100644 --- a/docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md +++ b/docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md @@ -329,7 +329,9 @@ mirror does carry, and is reported. stands; this ADR fixes the second, previously-unverified half. - `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 - `.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 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 diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 3e6307a..137ad93 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -21,12 +21,23 @@ 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 @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 beside it. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication. ## 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 @holocron` for a host consuming the marketplace natively (ADR-0018). Each plugin is an **apm package**: `plugins//apm.yml` plus a hand-authored `plugins//.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`. + +| Plugin | Scope | +|---|---| +| `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it | +| `git` | Conventional commits, branch management, history, worktrees, remotes | +| `gitea` | Issues, pull requests, labels, milestones, releases, wikis | +| `kyberforge` | Creating and maintaining a Claude Code / Copilot CLI plugin marketplace — this repo's own meta-tooling | +| `lint` | Configuring and running linters; repo-agnostic, first linter is Vale (`vale-config` / `vale-run`, plus the `lint-runner` agent) | +| `bin` | Unsorted skills that have not earned a home yet | + Two compilers produce the plugin roots you see in the tree: - **`apm pack` compiles the manifests** (ADR-0015). Per plugin: `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`, both generated from `plugins//apm.yml`. Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, `.github/plugin/marketplace.json` (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by `scripts/sync-marketplace-mirror.sh` and gated by the `check-marketplace-mirror-sync` pre-push hook. @@ -40,6 +51,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. +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: - **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`. @@ -57,6 +70,10 @@ 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. +## 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 two of the 39 skill 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 `core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers//` that translates core content into the tool's expected format and location. The core content itself does not change. diff --git a/docs/spec/gates.md b/docs/spec/gates.md index ef83e09..1df8f64 100644 --- a/docs/spec/gates.md +++ b/docs/spec/gates.md @@ -87,7 +87,9 @@ 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`. +runs `scripts/skill-size-check.sh`. That scope means it never lints `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 @@ -279,6 +281,81 @@ 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: , rev: ` 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: @@ -292,6 +369,92 @@ Only the **authoring source** triggers them. A `SKILL.md` in the generated flat 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 @@ -314,6 +477,16 @@ Use it only on a machine that genuinely cannot install `vale`, and read that lin 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 `` 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 ``` -- 2.43.0 From b93af307502b2ad13cf75bf928f46216803f4331 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:06:26 +0000 Subject: [PATCH 04/16] docs: fix a wrong pointer and two stale claims in CONTEXT.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CONTEXT.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index ba247c5..272dc6c 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -16,8 +16,8 @@ decisions. **Preload tax**: 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. Measured 2026-08-14 at ~5,900 -tokens across 39 skills; method in `docs/spec/gates.md`. +first token of every session whether the skill is invoked or not. Measurement method and current +figure: ADR-0020. _Avoid_: context cost, token overhead **Skill context contract**: @@ -114,8 +114,7 @@ content of its own (ADR-0002, ADR-0003). _Avoid_: wrapper, shim, provider file **LESSONS.md**: -The long-loop feedback log for patterns observed across sessions, at the repo root. Written by the -session-handoff skill or directly by the human. +The long-loop feedback log for patterns observed across sessions, at the repo root. _Avoid_: changelog, retro, postmortem **Management Application**: -- 2.43.0 From 56cc173f658ef30cfbf414a95ac62a58610bcf02 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:09:51 +0000 Subject: [PATCH 05/16] fix: re-anchor doc citations that the CONTEXT.md trim broke MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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). --- .pre-commit-config.yaml | 2 +- LESSONS.md | 2 +- scripts/check-vale-style-sync.sh | 17 +++++++++-------- scripts/sync-marketplace-mirror.sh | 2 +- tests/test-check-vale-style-sync.sh | 16 ++++++++-------- tests/test-vale-wrap.sh | 5 +++-- 6 files changed, 23 insertions(+), 21 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8018897..ce44c29 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -207,7 +207,7 @@ repos: # 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 # 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 # output is a single line, so this costs one line per push. diff --git a/LESSONS.md b/LESSONS.md index 1b9a1ed..3c8f0b4 100644 --- a/LESSONS.md +++ b/LESSONS.md @@ -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. -**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 diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh index a0c81e9..0ce4d3d 100755 --- a/scripts/check-vale-style-sync.sh +++ b/scripts/check-vale-style-sync.sh @@ -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" fi # 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 - # is `level: error` and every alert is a FAIL — no ignorable tier". Vale's exit + # style file or a glob. Per ADR-0013, every rule is `level: error` and every + # 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 # 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 @@ -175,9 +175,10 @@ for ini in "$SKILL_INI" "$AGENT_INI"; do fi done -# KyberforgeCopilot is agent-audit's alone — CONTEXT.md describes it as "scoped -# only to `.agent.md` files for the Copilot-only 'Use proactively has no effect' -# check". The loop above deliberately asserts only `Kyberforge`, since +# KyberforgeCopilot is agent-audit's alone — ADR-0013 scopes it to `.agent.md` +# files only, for the Copilot-only 'Use proactively has no effect' check, and +# 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 # `, KyberforgeCopilot` from agent-audit's `[**/*.agent.md]` section unloaded 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 # not drift. `demo.agent.md` is the real, current shape and is `shared`. # -# The two `.claude/`-prefixed probes carry the location-independence CONTEXT.md -# asserts: "A `SKILL.md` outside `plugins/` (e.g. project-scope +# The two `.claude/`-prefixed probes carry the location-independence property: 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." 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 # path (`[**/SKILL.md]` -> `[**/.apm/skills/*/SKILL.md]`) left all of them # matching while the project-scope shape started linting as `0 errors ... in 0 diff --git a/scripts/sync-marketplace-mirror.sh b/scripts/sync-marketplace-mirror.sh index 225ba57..1af7882 100755 --- a/scripts/sync-marketplace-mirror.sh +++ b/scripts/sync-marketplace-mirror.sh @@ -6,7 +6,7 @@ set -euo pipefail # that same file at .claude-plugin/marketplace.json directly, but also has a legacy # convention path at .github/plugin/marketplace.json (see # 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 # differently-shaped file to .agents/plugins/marketplace.json, not this path). This # script keeps that legacy mirror byte-identical to .claude-plugin/marketplace.json diff --git a/tests/test-check-vale-style-sync.sh b/tests/test-check-vale-style-sync.sh index 69beb69..27af113 100755 --- a/tests/test-check-vale-style-sync.sh +++ b/tests/test-check-vale-style-sync.sh @@ -457,8 +457,8 @@ fi # --- 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. -# CONTEXT.md's "Vale audit prefilter" entry: "Every rule is `level: error` and -# every alert is a FAIL -- no ignorable tier". Vale's exit code keys on `error` +# Per ADR-0013, every rule is `level: error` and every alert is a FAIL -- there +# is no ignorable tier. Vale's exit code keys on `error` # alerts alone, so any such override leaves the glob intact, the styles # 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 # Kyberforge alert. Verified dead by probing a `.agent.md` carrying # "Use proactively": 0 alerts under the broken config, KyberforgeCopilot. -# ProactivePhrase under the shipped one. CONTEXT.md describes the style as -# "scoped only to `.agent.md` files for the Copilot-only 'Use proactively has -# no effect' check", so shipping it unloaded is drift. +# ProactivePhrase under the shipped one. ADR-0013 scopes the style to +# `.agent.md` files only, for the Copilot-only 'Use proactively has no effect' +# check, so shipping it unloaded is drift. echo "" echo "--- exits 1 when the shipped KyberforgeCopilot style is named by no BasedOnStyles ---" FIXTURE11C="$(make_fixture)" @@ -609,9 +609,9 @@ fi # 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`, # 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. -# project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and -# gets linted normally -- the globs constrain filename shape, not location." +# it exists to catch. 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. # These narrowings are still valid glob syntax and break no `plugins/`-shaped # file, so only a non-`plugins/` probe path catches them. echo "" diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh index 191700b..1421e86 100755 --- a/tests/test-vale-wrap.sh +++ b/tests/test-vale-wrap.sh @@ -451,8 +451,9 @@ fi # 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 # 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 -# explicit repo target, so the scope is four globs, each floor-asserted below: +# new script is covered the moment it lands. LESSONS.md and the script headers +# name bash 3.2 as an explicit repo target, so the scope is four globs, each +# floor-asserted below: # - scripts/**/*.sh — repo tooling and pre-commit hook scripts # - tests/*.sh — the runners and every regression test # - plugins/*/.apm/**/*.sh — the scripts plugins ship to users -- 2.43.0 From ba7cec7672ba58c0886ee683a37519bc3c6d9372 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:10:24 +0000 Subject: [PATCH 06/16] docs(adr): amend ADR-0007 and ADR-0015 for the CONTEXT.md trim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/adr/0007-gitea-canonical-issue-tracker.md | 2 +- docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/adr/0007-gitea-canonical-issue-tracker.md b/docs/adr/0007-gitea-canonical-issue-tracker.md index 7cd7d7a..e79313b 100644 --- a/docs/adr/0007-gitea-canonical-issue-tracker.md +++ b/docs/adr/0007-gitea-canonical-issue-tracker.md @@ -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 "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. diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md index d8fb9d3..eedcc21 100644 --- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -57,7 +57,9 @@ new hand-maintained manifest format. - `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. 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`. + 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 @@ -68,7 +70,7 @@ maintenance in place unchanged. **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 -(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 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`, -- 2.43.0 From bd2bf667c5e326f7bcebc85a3caa6bc5930fed1b Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:10:55 +0000 Subject: [PATCH 07/16] docs: restore two guard-rails the trim dropped MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/spec/architecture.md | 2 +- scripts/sync-marketplace-mirror.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 137ad93..dc21323 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -25,7 +25,7 @@ Skills are **not** deployed by `install.sh`. They are distributed as plugins and ## 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 @holocron` for a host consuming the marketplace natively (ADR-0018). Each plugin is an **apm package**: `plugins//apm.yml` plus a hand-authored `plugins//.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 @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//apm.yml` plus a hand-authored `plugins//.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`. diff --git a/scripts/sync-marketplace-mirror.sh b/scripts/sync-marketplace-mirror.sh index 1af7882..ffdb066 100755 --- a/scripts/sync-marketplace-mirror.sh +++ b/scripts/sync-marketplace-mirror.sh @@ -60,7 +60,7 @@ fi if [[ "$CHECK" -eq 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 "Fix: bash scripts/sync-marketplace-mirror.sh" >&2 + echo "Fix: bash scripts/sync-marketplace-mirror.sh -- 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 fi exit 0 -- 2.43.0 From b0ef5034855ffb0d23f5a505632c7548b2068a36 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:11:59 +0000 Subject: [PATCH 08/16] docs: correct plugin scope, hook ordering and the setup gap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 8 ++++---- docs/spec/architecture.md | 10 +++++++--- docs/spec/gates.md | 2 +- 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c51958a..b4c089d 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa | Path | What it holds | | --- | --- | -| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, agents, hooks, MCP servers, and bundled assets | +| `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 | @@ -18,7 +18,7 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa The six plugins: - **kyberforge** — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace -- **git** — conventional commits, branch management, pull requests, feature flow +- **git** — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running (`pc-author` / `pc-run`) - **gitea** — issues, pull requests, milestones, releases, wikis - **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it - **lint** — configuring and running linters @@ -50,12 +50,12 @@ Run these in order, from the repo root. apm install # 2. Install the git hooks — all three stages -# (use the `pc-run` skill, which knows the stage wiring) +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//.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** go in via the `pc-run` skill, wiring **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). +**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 diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index dc21323..6c9298e 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -29,13 +29,17 @@ Skills, agents, MCP servers, and hooks are distributed as self-contained plugin 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. For what a consumer actually gets, read the plugin's published `description` in its `apm.yml`. + | Plugin | Scope | |---|---| | `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it | -| `git` | Conventional commits, branch management, history, worktrees, remotes | -| `gitea` | Issues, pull requests, labels, milestones, releases, wikis | +| `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; repo-agnostic, first linter is Vale (`vale-config` / `vale-run`, plus the `lint-runner` agent) | +| `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: diff --git a/docs/spec/gates.md b/docs/spec/gates.md index 1df8f64..0fca311 100644 --- a/docs/spec/gates.md +++ b/docs/spec/gates.md @@ -27,7 +27,7 @@ stage including this one. Fourteen is the count of repo-defined pre-push hooks. ## The pre-push gate -Fourteen hooks, in config order. +Fourteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in. **Core checks** -- 2.43.0 From 65bac152574234d93d0e556484801099774b2919 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:13:31 +0000 Subject: [PATCH 09/16] chore(apm): correct git and gitea published descriptions and regenerate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .claude-plugin/marketplace.json | 10 +++++----- .github/plugin/marketplace.json | 10 +++++----- README.md | 2 +- apm.yml | 10 +++++----- plugins/git/.claude-plugin/plugin.json | 4 ++-- plugins/git/.github/plugin/plugin.json | 4 ++-- plugins/git/apm.yml | 4 ++-- plugins/gitea/.claude-plugin/plugin.json | 4 ++-- plugins/gitea/.github/plugin/plugin.json | 4 ++-- plugins/gitea/apm.yml | 4 ++-- 10 files changed, 28 insertions(+), 28 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1551e20..f17bb99 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "holocron", "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.3", "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net", @@ -24,15 +24,15 @@ }, { "name": "git", - "description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.", - "version": "1.3.3", + "description": "Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", + "version": "1.3.4", "category": "Version Control", "source": "./plugins/git" }, { "name": "gitea", - "description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.", - "version": "1.3.4", + "description": "Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.", + "version": "1.3.5", "category": "Version Control", "source": "./plugins/gitea" }, diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 1551e20..f17bb99 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "holocron", "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.3", "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net", @@ -24,15 +24,15 @@ }, { "name": "git", - "description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.", - "version": "1.3.3", + "description": "Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", + "version": "1.3.4", "category": "Version Control", "source": "./plugins/git" }, { "name": "gitea", - "description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.", - "version": "1.3.4", + "description": "Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.", + "version": "1.3.5", "category": "Version Control", "source": "./plugins/gitea" }, diff --git a/README.md b/README.md index b4c089d..abbdc66 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ 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, and pre-commit hook authoring and running (`pc-author` / `pc-run`) -- **gitea** — issues, pull requests, milestones, releases, wikis +- **gitea** — issues, pull requests, labels, milestones, releases, branches, files - **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it - **lint** — configuring and running linters - **bin** — a place for things to be binned diff --git a/apm.yml b/apm.yml index f727d09..4ed53a8 100644 --- a/apm.yml +++ b/apm.yml @@ -52,7 +52,7 @@ marketplace: # top-level apm.yml description:/version: above are NOT inherited into the # 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. - version: 0.4.2 + version: 0.4.3 owner: name: Defame1297 email: defame1297@rkdr.net @@ -89,15 +89,15 @@ marketplace: category: Utilities - name: git - description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow. + description: Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running. source: ./plugins/git - version: 1.3.3 + version: 1.3.4 category: Version Control - name: gitea - description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis. + description: Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files. source: ./plugins/gitea - version: 1.3.4 + version: 1.3.5 category: Version Control - name: core diff --git a/plugins/git/.claude-plugin/plugin.json b/plugins/git/.claude-plugin/plugin.json index f394b25..70256f3 100644 --- a/plugins/git/.claude-plugin/plugin.json +++ b/plugins/git/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "git", - "version": "1.3.3", - "description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.", + "version": "1.3.4", + "description": "Skills for working with Git \u2014 conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", "author": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/git/.github/plugin/plugin.json b/plugins/git/.github/plugin/plugin.json index f394b25..70256f3 100644 --- a/plugins/git/.github/plugin/plugin.json +++ b/plugins/git/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "git", - "version": "1.3.3", - "description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.", + "version": "1.3.4", + "description": "Skills for working with Git \u2014 conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", "author": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/git/apm.yml b/plugins/git/apm.yml index 7e270fb..066296f 100644 --- a/plugins/git/apm.yml +++ b/plugins/git/apm.yml @@ -1,6 +1,6 @@ name: git -version: 1.3.3 -description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow. +version: 1.3.4 +description: Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running. author: name: Defame1297 email: defame1297@rkdr.net diff --git a/plugins/gitea/.claude-plugin/plugin.json b/plugins/gitea/.claude-plugin/plugin.json index 61fa711..592bc34 100644 --- a/plugins/gitea/.claude-plugin/plugin.json +++ b/plugins/gitea/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gitea", - "version": "1.3.4", - "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.", + "version": "1.3.5", + "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, labels, milestones, releases, branches, and files.", "author": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/gitea/.github/plugin/plugin.json b/plugins/gitea/.github/plugin/plugin.json index 61fa711..592bc34 100644 --- a/plugins/gitea/.github/plugin/plugin.json +++ b/plugins/gitea/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gitea", - "version": "1.3.4", - "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.", + "version": "1.3.5", + "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, labels, milestones, releases, branches, and files.", "author": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/gitea/apm.yml b/plugins/gitea/apm.yml index 4ee17bc..55c97cf 100644 --- a/plugins/gitea/apm.yml +++ b/plugins/gitea/apm.yml @@ -1,6 +1,6 @@ name: gitea -version: 1.3.4 -description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis. +version: 1.3.5 +description: Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files. author: name: Defame1297 email: defame1297@rkdr.net -- 2.43.0 From de84d1b677cda9cf61fd07e0a335a2448c43e2a0 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 10:33:25 +0000 Subject: [PATCH 10/16] chore(apm): give bin a published description that describes it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .claude-plugin/marketplace.json | 6 +++--- .github/plugin/marketplace.json | 6 +++--- README.md | 2 +- apm.yml | 6 +++--- plugins/bin/.claude-plugin/plugin.json | 4 ++-- plugins/bin/.github/plugin/plugin.json | 4 ++-- plugins/bin/apm.yml | 4 ++-- 7 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f17bb99..aad6f3d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "holocron", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", - "version": "0.4.3", + "version": "0.4.4", "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net", @@ -17,8 +17,8 @@ }, { "name": "bin", - "description": "A place for things to be binned", - "version": "1.1.3", + "description": "Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", + "version": "1.1.4", "category": "Utilities", "source": "./plugins/bin" }, diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index f17bb99..aad6f3d 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "holocron", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", - "version": "0.4.3", + "version": "0.4.4", "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net", @@ -17,8 +17,8 @@ }, { "name": "bin", - "description": "A place for things to be binned", - "version": "1.1.3", + "description": "Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", + "version": "1.1.4", "category": "Utilities", "source": "./plugins/bin" }, diff --git a/README.md b/README.md index abbdc66..83bd147 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The six plugins: - **gitea** — issues, pull requests, labels, milestones, releases, branches, files - **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it - **lint** — configuring and running linters -- **bin** — a place for things to be binned +- **bin** — cross-cutting workflow skills not yet split into a focused plugin: research, documentation, TDD, prototyping, triage, diagnosis, architecture review, requirement grilling ## Prerequisites diff --git a/apm.yml b/apm.yml index 4ed53a8..9a7b63a 100644 --- a/apm.yml +++ b/apm.yml @@ -52,7 +52,7 @@ marketplace: # top-level apm.yml description:/version: above are NOT inherited into the # 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. - version: 0.4.3 + version: 0.4.4 owner: name: Defame1297 email: defame1297@rkdr.net @@ -83,9 +83,9 @@ marketplace: category: Developer Tools - name: bin - description: A place for things to be binned + description: Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling. source: ./plugins/bin - version: 1.1.3 + version: 1.1.4 category: Utilities - name: git diff --git a/plugins/bin/.claude-plugin/plugin.json b/plugins/bin/.claude-plugin/plugin.json index 7e40868..6a862f9 100644 --- a/plugins/bin/.claude-plugin/plugin.json +++ b/plugins/bin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "bin", - "version": "1.1.3", - "description": "A place for things to be binned", + "version": "1.1.4", + "description": "Cross-cutting workflow skills not yet split into a focused plugin \u2014 research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", "author": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/bin/.github/plugin/plugin.json b/plugins/bin/.github/plugin/plugin.json index c43b71d..e28d06b 100644 --- a/plugins/bin/.github/plugin/plugin.json +++ b/plugins/bin/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "bin", - "version": "1.1.3", - "description": "A place for things to be binned", + "version": "1.1.4", + "description": "Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", "author": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/bin/apm.yml b/plugins/bin/apm.yml index f9c8e65..83c8ef8 100644 --- a/plugins/bin/apm.yml +++ b/plugins/bin/apm.yml @@ -1,6 +1,6 @@ name: bin -version: 1.1.3 -description: A place for things to be binned +version: 1.1.4 +description: Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling. author: name: Defame1297 email: defame1297@rkdr.net -- 2.43.0 From b1ea14df3e14a852fa661cbdc756a8353b18f27d Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 12:27:56 +0000 Subject: [PATCH 11/16] fix(scripts): make the mirror DRIFT fix line safe to copy-paste MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w --- scripts/sync-marketplace-mirror.sh | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/scripts/sync-marketplace-mirror.sh b/scripts/sync-marketplace-mirror.sh index ffdb066..6c7fd17 100755 --- a/scripts/sync-marketplace-mirror.sh +++ b/scripts/sync-marketplace-mirror.sh @@ -60,7 +60,19 @@ fi if [[ "$CHECK" -eq 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 "Fix: bash scripts/sync-marketplace-mirror.sh -- 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 + # 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 fi exit 0 -- 2.43.0 From 36596598ef9c5742665ad222507380c0da63dc5d Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 12:28:11 +0000 Subject: [PATCH 12/16] 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) Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w --- tests/run-tests.sh | 13 +++++++------ tests/test-run-tests.sh | 9 +++++---- tests/test-vale-wrap.sh | 8 +++++--- 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/tests/run-tests.sh b/tests/run-tests.sh index f6ea424..683b824 100755 --- a/tests/run-tests.sh +++ b/tests/run-tests.sh @@ -13,11 +13,12 @@ # dev binary, the other 15 suites still tell you something, and turning that # 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 -# legitimate state. AGENTS.md documents vale, apm and jq as required pre-push -# dependencies, so a suite that cannot run on the machine doing the pushing -# means the machine is misconfigured -- and pre-commit prints NOTHING for a -# passing hook, so the skip list below is swallowed entirely. On a vale-less -# PATH that silently shipped a green gate having verified 15 of 17 suites. +# legitimate state. README.md's Prerequisites table documents vale, apm and +# jq as required pre-push dependencies, so a suite that cannot run on the +# machine doing the pushing means the machine is misconfigured -- and +# pre-commit prints NOTHING for a passing hook, so the skip list below is +# swallowed entirely. On a vale-less PATH that silently shipped a green +# gate having verified 15 of 17 suites. # Exactly the vacuous-pass class the rest of this file exists to close. # # Deliberately its own switch, NOT folded into @@ -258,7 +259,7 @@ fi # here (not just referenced) because this block goes to stderr and is what a # pre-push reader actually gets handed. 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 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 sidx=0 for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do echo " $s" >&2 diff --git a/tests/test-run-tests.sh b/tests/test-run-tests.sh index 803424f..ec3fe0a 100644 --- a/tests/test-run-tests.sh +++ b/tests/test-run-tests.sh @@ -392,10 +392,11 @@ fi # --- 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 -# suite exiting 77 means a dependency AGENTS.md documents as required is missing -# on the pushing machine -- and pre-commit prints nothing at all for a passing -# hook, so the skip list this script writes to stdout was swallowed whole. A -# vale-less PATH shipped a green gate having verified 15 of 17 suites. +# suite exiting 77 means a dependency README.md's Prerequisites table documents +# as required is missing on the pushing machine -- and pre-commit prints nothing +# at all for a passing hook, so the skip list this script writes to stdout was +# swallowed whole. A vale-less PATH shipped a green gate having verified 15 of +# 17 suites. # # 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 diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh index 1421e86..1e7261a 100755 --- a/tests/test-vale-wrap.sh +++ b/tests/test-vale-wrap.sh @@ -451,9 +451,11 @@ fi # 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 # bash-3.2-safe — along with four other scripts/*.sh. Deriving the list means a -# new script is covered the moment it lands. LESSONS.md and the script headers -# name bash 3.2 as an explicit repo target, so the scope is four globs, each -# floor-asserted below: +# new script is covered the moment it lands. The script headers name bash 3.2 as +# 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 # - tests/*.sh — the runners and every regression test # - plugins/*/.apm/**/*.sh — the scripts plugins ship to users -- 2.43.0 From 4d336bbf357975af877372a83bf91f495b8b9acb Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 12:28:30 +0000 Subject: [PATCH 13/16] 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 `:` 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) Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w --- AGENTS.md | 6 +-- CONTEXT.md | 40 +++++++++++++++++-- LESSONS.md | 4 +- ...po-consumes-its-own-plugins-through-apm.md | 23 +++++++++-- 4 files changed, 61 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b7d9e16..6c30aed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,17 +27,17 @@ This repo dogfoods its own plugins. Before shelling out, check whether a skill a - Vale prose linting → `vale-config` / `vale-run` - This repo's own AGENTS.md → `agentsmd-author` / `agentsmd-audit` -Use the bare, **unnamespaced** names. The `:` form (`gitea:gitea-prs`) also still resolves, because user-scope native installs were left enabled on purpose (ADR-0018) — a working namespaced call is not evidence that anything is broken and is not something to "fix". Prefer the bare name anyway: it is what `apm install` deploys, and what survives those user-scope installs eventually being converted. +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 `:` 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. ## Session rules -- **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//.apm/hooks/` and deployed by apm, never hand-written into that file. 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 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//.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`. - **`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. - **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. - **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`. -- **Run `bash tests/run-tests.sh` before considering any change done.** +- **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. - **Before pushing, run the whole gate locally:** `pre-commit run --hook-stage pre-push --all-files`. Pushing runs 14 repo-defined hooks, not just the test suite. - **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. - **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces. diff --git a/CONTEXT.md b/CONTEXT.md index 272dc6c..8e1fef7 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -57,6 +57,24 @@ The deployable unit — one or more skills, agents, hooks, commands, and MCP ser single installable directory under `plugins//`, compiled from that plugin's `.apm/` source. _Avoid_: package, bundle, module +**apm package**: +The unit apm builds and installs — `plugins//apm.yml` plus the hand-authored +`plugins//.apm/` tree it compiles from (ADR-0015). +_Avoid_: plugin directory, source tree + +**Content mirror**: +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 + +**Output profile**: +An `apm pack` target format for a generated manifest; apm has `claude` +(`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped +`.agents/plugins/marketplace.json`) and none for Copilot CLI's legacy path, which a sync script +mirrors instead. Mechanics: `docs/spec/architecture.md`. +_Avoid_: build target, export format + **Plugin marketplace**: 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. @@ -135,6 +153,22 @@ The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Des so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`. _Avoid_: linting, style check +**Authoring root**: +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 + +**Near-miss**: +A sibling skill or agent whose plausible queries share keywords with this one but need something +different — the only thing a boundary clause should exclude. +_Avoid_: overlap, similar skill + +**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 + **Issue**: 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. @@ -181,9 +215,9 @@ _Avoid_: ticket, card, task - "skill" was used for both the authored `SKILL.md` under `plugins//.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 answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), because - user-scope native installs were left enabled deliberately (ADR-0018) — resolved: write the bare - name; a working namespaced call is not evidence of a defect. +- 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 diff --git a/LESSONS.md b/LESSONS.md index 3c8f0b4..7a01d6c 100644 --- a/LESSONS.md +++ b/LESSONS.md @@ -1,8 +1,8 @@ # 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. diff --git a/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md b/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md index 8b2eb95..4f5551a 100644 --- a/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md +++ b/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md @@ -72,6 +72,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 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 +`:` 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 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 @@ -117,10 +131,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 merge redeploys the same content and reports success. -**User scope is untouched, deliberately.** `bin@holocron`, `gitea@holocron`, and a stale -`hello-world@holocron` remain natively installed at user scope, and every project other than this -one still resolves its skills that way. Converting them is a separate decision with a blast radius -beyond this repo. +**User scope is untouched, deliberately.** This decision changed project scope only; whatever is +natively installed at user scope was left alone, and converting it is a separate decision with a +blast radius beyond this repo. The specific inventory this paragraph used to name +(`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 -- 2.43.0 From c7ba3d2ccf1a7c0305d3a500e9d8f44b27db1b4f Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 12:28:55 +0000 Subject: [PATCH 14/16] 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) Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w --- .claude-plugin/marketplace.json | 14 +- .github/plugin/marketplace.json | 14 +- apm.yml | 16 +- ...in-descriptions-state-a-domain-boundary.md | 220 ++++++++++++++++++ plugins/bin/.claude-plugin/plugin.json | 4 +- plugins/bin/.github/plugin/plugin.json | 4 +- plugins/bin/apm.yml | 4 +- plugins/git/.claude-plugin/plugin.json | 4 +- plugins/git/.github/plugin/plugin.json | 4 +- plugins/git/apm.yml | 4 +- plugins/gitea/.claude-plugin/plugin.json | 4 +- plugins/gitea/.github/plugin/plugin.json | 4 +- plugins/gitea/apm.yml | 4 +- 13 files changed, 260 insertions(+), 40 deletions(-) create mode 100644 docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index aad6f3d..5a19094 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "holocron", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", - "version": "0.4.4", + "version": "0.4.5", "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net", @@ -17,22 +17,22 @@ }, { "name": "bin", - "description": "Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", - "version": "1.1.4", + "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.5", "category": "Utilities", "source": "./plugins/bin" }, { "name": "git", - "description": "Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", - "version": "1.3.4", + "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.5", "category": "Version Control", "source": "./plugins/git" }, { "name": "gitea", - "description": "Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.", - "version": "1.3.5", + "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.6", "category": "Version Control", "source": "./plugins/gitea" }, diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index aad6f3d..5a19094 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "holocron", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", - "version": "0.4.4", + "version": "0.4.5", "owner": { "name": "Defame1297", "email": "defame1297@rkdr.net", @@ -17,22 +17,22 @@ }, { "name": "bin", - "description": "Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", - "version": "1.1.4", + "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.5", "category": "Utilities", "source": "./plugins/bin" }, { "name": "git", - "description": "Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", - "version": "1.3.4", + "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.5", "category": "Version Control", "source": "./plugins/git" }, { "name": "gitea", - "description": "Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.", - "version": "1.3.5", + "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.6", "category": "Version Control", "source": "./plugins/gitea" }, diff --git a/apm.yml b/apm.yml index 9a7b63a..7ae2ec4 100644 --- a/apm.yml +++ b/apm.yml @@ -1,5 +1,5 @@ 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. license: MIT @@ -52,7 +52,7 @@ marketplace: # top-level apm.yml description:/version: above are NOT inherited into the # 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. - version: 0.4.4 + version: 0.4.5 owner: name: Defame1297 email: defame1297@rkdr.net @@ -83,21 +83,21 @@ marketplace: category: Developer Tools - name: bin - description: Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling. + 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 - version: 1.1.4 + version: 1.1.5 category: Utilities - name: git - description: Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running. + 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 - version: 1.3.4 + version: 1.3.5 category: Version Control - name: gitea - description: Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files. + 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 - version: 1.3.5 + version: 1.3.6 category: Version Control - name: core diff --git a/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md b/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md new file mode 100644 index 0000000..bb8d427 --- /dev/null +++ b/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md @@ -0,0 +1,220 @@ +# 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//apm.yml` and in +the matching `marketplace.packages[]` entry of the root `apm.yml` — and compiled into six files per +plugin edit: `.claude-plugin/plugin.json`, `.github/plugin/plugin.json`, +`.claude-plugin/marketplace.json`, `.github/plugin/marketplace.json`, and (for the version field +only) their codex counterpart. 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//.apm/skills/ | wc -l`, description text is +`plugins//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`. `scripts/skill-size-check.sh` and the three ADR-0020 validators read SKILL.md and +agent frontmatter and never open an `apm.yml`. `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 six 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, a PATCH bump on the package, a bump on +`marketplace.version`, and a regeneration of eight compiled files — a marketplace release, triggered +by a directory appearing. A skill *rename* triggers the same. 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//.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 114 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 one of the eleven commits that have +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. This is a defect, not a style: `apm.yml`'s own comment above 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. That sentence is owned +by a separate workstream in this change and is deliberately not edited here. + +**`README.md`'s plugin bullet list becomes the only place an inventory lives, and it still +enumerates.** Its `bin` and `git` bullets mirror the retired descriptions almost verbatim. This ADR +does not extend to it and does not require it to change: a README is a hand-read document where a +list of what you get is the useful thing, it is not compiled into six 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. diff --git a/plugins/bin/.claude-plugin/plugin.json b/plugins/bin/.claude-plugin/plugin.json index 6a862f9..d3644c8 100644 --- a/plugins/bin/.claude-plugin/plugin.json +++ b/plugins/bin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "bin", - "version": "1.1.4", - "description": "Cross-cutting workflow skills not yet split into a focused plugin \u2014 research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", + "version": "1.1.5", + "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": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/bin/.github/plugin/plugin.json b/plugins/bin/.github/plugin/plugin.json index e28d06b..18814d8 100644 --- a/plugins/bin/.github/plugin/plugin.json +++ b/plugins/bin/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "bin", - "version": "1.1.4", - "description": "Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling.", + "version": "1.1.5", + "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": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/bin/apm.yml b/plugins/bin/apm.yml index 83c8ef8..fd3c6d0 100644 --- a/plugins/bin/apm.yml +++ b/plugins/bin/apm.yml @@ -1,6 +1,6 @@ name: bin -version: 1.1.4 -description: Cross-cutting workflow skills not yet split into a focused plugin — research, documentation, TDD, prototyping, triage, diagnosis, architecture review, and requirement grilling. +version: 1.1.5 +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: name: Defame1297 email: defame1297@rkdr.net diff --git a/plugins/git/.claude-plugin/plugin.json b/plugins/git/.claude-plugin/plugin.json index 70256f3..bf02e91 100644 --- a/plugins/git/.claude-plugin/plugin.json +++ b/plugins/git/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "git", - "version": "1.3.4", - "description": "Skills for working with Git \u2014 conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", + "version": "1.3.5", + "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": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/git/.github/plugin/plugin.json b/plugins/git/.github/plugin/plugin.json index 70256f3..bf02e91 100644 --- a/plugins/git/.github/plugin/plugin.json +++ b/plugins/git/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "git", - "version": "1.3.4", - "description": "Skills for working with Git \u2014 conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.", + "version": "1.3.5", + "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": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/git/apm.yml b/plugins/git/apm.yml index 066296f..08c885c 100644 --- a/plugins/git/apm.yml +++ b/plugins/git/apm.yml @@ -1,6 +1,6 @@ name: git -version: 1.3.4 -description: Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running. +version: 1.3.5 +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: name: Defame1297 email: defame1297@rkdr.net diff --git a/plugins/gitea/.claude-plugin/plugin.json b/plugins/gitea/.claude-plugin/plugin.json index 592bc34..983109a 100644 --- a/plugins/gitea/.claude-plugin/plugin.json +++ b/plugins/gitea/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gitea", - "version": "1.3.5", - "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, labels, milestones, releases, branches, and files.", + "version": "1.3.6", + "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": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/gitea/.github/plugin/plugin.json b/plugins/gitea/.github/plugin/plugin.json index 592bc34..983109a 100644 --- a/plugins/gitea/.github/plugin/plugin.json +++ b/plugins/gitea/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gitea", - "version": "1.3.5", - "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, labels, milestones, releases, branches, and files.", + "version": "1.3.6", + "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": { "name": "Defame1297", "email": "defame1297@rkdr.net", diff --git a/plugins/gitea/apm.yml b/plugins/gitea/apm.yml index 55c97cf..d08b3ea 100644 --- a/plugins/gitea/apm.yml +++ b/plugins/gitea/apm.yml @@ -1,6 +1,6 @@ name: gitea -version: 1.3.5 -description: Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files. +version: 1.3.6 +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: name: Defame1297 email: defame1297@rkdr.net -- 2.43.0 From c68e864159939be63943ef876cc61afef712337b Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 12:29:16 +0000 Subject: [PATCH 15/16] 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) Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w --- README.md | 9 ++++-- docs/spec/architecture.md | 6 ++-- docs/spec/gates.md | 62 +++++++++++++++++++++++++++++++-------- 3 files changed, 59 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 83bd147..1ee498f 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The six plugins: - **gitea** — issues, pull requests, labels, milestones, releases, branches, files - **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 +- **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 @@ -81,12 +81,17 @@ A suite that exits 77 because a dependency is missing is reported as SKIPPED and ## Before pushing -Run the whole pre-push gate locally in one command: +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`: diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 6c9298e..b0d3ca4 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -21,7 +21,7 @@ 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 @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) and carries nothing else — the content index of on-demand instruction files sits in `core/AGENTS.md`, deployed beside it. 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 @@ -31,7 +31,7 @@ Which plugin a new skill belongs in follows from what each one is scoped to. The 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. For what a consumer actually gets, read the plugin's published `description` in its `apm.yml`. +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//.apm/skills/` or the plugin list in `README.md`. | Plugin | Scope | |---|---| @@ -76,7 +76,7 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for ## 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 two of the 39 skill 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. +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 diff --git a/docs/spec/gates.md b/docs/spec/gates.md index 0fca311..8a5140d 100644 --- a/docs/spec/gates.md +++ b/docs/spec/gates.md @@ -14,7 +14,7 @@ of the oddities documented here are load-bearing and have already been re-litiga | Command | Scope | |---|---| | `pre-commit run --all-files` | the commit-stage hooks | -| `pre-commit run --hook-stage pre-push --all-files` | the whole push gate, one command | +| `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 @@ -23,7 +23,18 @@ 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. Fourteen is the count of repo-defined pre-push hooks. +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 @@ -74,7 +85,7 @@ drift in generated text. | Hook | Guards | |---|---| -| `check-release-needed` | on push to `main` only — fails if files exposed via `.pre-commit-hooks.yaml` changed since the last tag | +| `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 @@ -87,8 +98,9 @@ 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 `docs/research/examples/` -reference skills. It is also shipped to external repos as `kyberforge-skill-size-check` (see +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 @@ -107,14 +119,13 @@ reference skills. It is also shipped to external repos as `kyberforge-skill-size | `description` characters | 250 | 400 | the YAML-**folded** value | | body words | 600 | 900 | **body only** — everything after the frontmatter's closing `---` | -Plus three hard FAILs with no suggestion tier: +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 boundary-clause routing target must resolve** to a real skill or agent. - **Every `references/.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. @@ -122,6 +133,26 @@ Plus three hard FAILs with no suggestion tier: 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`, `-> name`) **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. + +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 @@ -176,10 +207,13 @@ Three more, deterministic to measure but judgment to act on: 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 arithmetic depends on it: writing to the 400-char FAIL lands the preload at 39 × 400 = -15,600 chars (a 33% cut off 23,427); writing to the 250-char SUGGESTION lands at 9,750 (58%). The -halving depends entirely on that tier being visible. It costs nothing on a clean file — the script -prints only findings. +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 @@ -637,8 +671,10 @@ remote *before* any network call, so it does not join the pair above. 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` / `0015` / `0014` — plugin content sync, apm-generated manifests, committed Vale - styles +- `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 -- 2.43.0 From d42f6368febeb9e77cbffdeadb169b6c5e3905e4 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 17 Aug 2026 13:18:55 +0000 Subject: [PATCH 16/16] 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) Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w --- AGENTS.md | 4 +- CONTEXT.md | 11 ++-- README.md | 4 +- ...po-consumes-its-own-plugins-through-apm.md | 4 +- ...in-descriptions-state-a-domain-boundary.md | 51 +++++++++++-------- docs/spec/architecture.md | 2 +- docs/spec/gates.md | 11 +++- tests/run-tests.sh | 11 ++-- tests/test-run-tests.sh | 4 +- 9 files changed, 61 insertions(+), 41 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6c30aed..ae855dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,14 +38,14 @@ Fall back to raw shell only when no skill covers it. - **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. - **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`. - **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. -- **Before pushing, run the whole gate locally:** `pre-commit run --hook-stage pre-push --all-files`. Pushing runs 14 repo-defined hooks, not just the test suite. +- **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. - **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. - **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces. - **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. ## Key documents -Read `CONTEXT.md` at the start of every session — it is this repo's domain language, and the terms in it are used unglossed everywhere else. +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: diff --git a/CONTEXT.md b/CONTEXT.md index 8e1fef7..fa9dfbf 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -69,10 +69,10 @@ plugin's `.apm/` tree so hosts that convention-scan those paths discover the con _Avoid_: generated copy, duplicate tree **Output profile**: -An `apm pack` target format for a generated manifest; apm has `claude` +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 Copilot CLI's legacy path, which a sync script -mirrors instead. Mechanics: `docs/spec/architecture.md`. +`.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**: @@ -160,8 +160,9 @@ The directory a gate resolves against — the nearest ancestor of the file being _Avoid_: repo root, project root **Near-miss**: -A sibling skill or agent whose plausible queries share keywords with this one but need something -different — the only thing a boundary clause should exclude. +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 **Vacuous green**: diff --git a/README.md b/README.md index 1ee498f..80ebf16 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,8 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa 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, and pre-commit hook authoring and running (`pc-author` / `pc-run`) -- **gitea** — issues, pull requests, labels, milestones, releases, branches, files +- **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`) diff --git a/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md b/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md index 4f5551a..44fe717 100644 --- a/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md +++ b/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md @@ -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 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 `:` reference "was stale the moment the switch landed", 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 diff --git a/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md b/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md index bb8d427..5edc04d 100644 --- a/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md +++ b/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md @@ -11,10 +11,11 @@ plugin is *for*, and the inventory lives where an inventory can be read off the ## Context A plugin's published description is one string authored twice — in `plugins//apm.yml` and in -the matching `marketplace.packages[]` entry of the root `apm.yml` — and compiled into six files per -plugin edit: `.claude-plugin/plugin.json`, `.github/plugin/plugin.json`, -`.claude-plugin/marketplace.json`, `.github/plugin/marketplace.json`, and (for the version field -only) their codex counterpart. It is the only text a consumer sees in a marketplace listing before +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 @@ -70,17 +71,21 @@ unnamed in `git`'s corrected description, though `65bac15`'s own commit message `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`. `scripts/skill-size-check.sh` and the three ADR-0020 validators read SKILL.md and -agent frontmatter and never open an `apm.yml`. `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 six files byte-for-byte and -confirm they match. The `wiki` claim passed every one of the fourteen pre-push hooks, every day it +`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, a PATCH bump on the package, a bump on -`marketplace.version`, and a regeneration of eight compiled files — a marketplace release, triggered -by a directory appearing. A skill *rename* triggers the same. 27 of the repo's 39 skills sat behind +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. @@ -159,7 +164,7 @@ 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 114 characters and asserted a skill that has never existed, while +`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. @@ -183,11 +188,12 @@ field at all, only `name`, `source`, `policy` and `category`. 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 one of the eleven commits that have -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 +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. This is a defect, not a style: `apm.yml`'s own comment above the -marketplace block records that the top-level `version:` is not inherited into the compiled output +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. @@ -199,13 +205,14 @@ duplication to collapse — they have different readers and different lifecycles 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. That sentence is owned -by a separate workstream in this change and is deliberately not edited here. +boundary statement. Neither artifact carries an inventory after this change, so that sentence was +rewritten in the same branch to point at `plugins//.apm/skills/` and `README.md` instead. **`README.md`'s plugin bullet list becomes the only place an inventory lives, and it still -enumerates.** Its `bin` and `git` bullets mirror the retired descriptions almost verbatim. This ADR -does not extend to it and does not require it to change: a README is a hand-read document where a -list of what you get is the useful thing, it is not compiled into six files, and a stale line in it +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. diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index b0d3ca4..af7fd1c 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -84,4 +84,4 @@ The stated convention is that files referencing other files declare those refere ## Architectural decisions -Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds 20 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). diff --git a/docs/spec/gates.md b/docs/spec/gates.md index 8a5140d..8fa6a99 100644 --- a/docs/spec/gates.md +++ b/docs/spec/gates.md @@ -141,7 +141,7 @@ A boundary-clause target that resolves to no skill or agent has **three** possib | 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`, `-> name`) **or** corroborated by another target in the same sentence that *does* resolve | +| **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 @@ -149,6 +149,15 @@ tool, a file format or an English compound as a route: "pre-commit hooks" is pro 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. diff --git a/tests/run-tests.sh b/tests/run-tests.sh index 683b824..1893a79 100755 --- a/tests/run-tests.sh +++ b/tests/run-tests.sh @@ -14,11 +14,12 @@ # 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 # legitimate state. README.md's Prerequisites table documents vale, apm and -# jq as required pre-push dependencies, so a suite that cannot run on the -# machine doing the pushing means the machine is misconfigured -- and +# python3/PyYAML -- the dependencies these suites actually guard on -- as +# required pre-push, so a suite that cannot run on the machine doing the +# pushing means the machine is misconfigured -- and # pre-commit prints NOTHING for a passing hook, so the skip list below is -# swallowed entirely. On a vale-less PATH that silently shipped a green -# gate having verified 15 of 17 suites. +# 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. # # Deliberately its own switch, NOT folded into @@ -259,7 +260,7 @@ fi # here (not just referenced) because this block goes to stderr and is what a # pre-push reader actually gets handed. 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: README.md's Prerequisites table 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 for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do echo " $s" >&2 diff --git a/tests/test-run-tests.sh b/tests/test-run-tests.sh index ec3fe0a..a941e69 100644 --- a/tests/test-run-tests.sh +++ b/tests/test-run-tests.sh @@ -395,8 +395,8 @@ fi # suite exiting 77 means a dependency README.md's Prerequisites table documents # as required is missing on the pushing machine -- and pre-commit prints nothing # at all for a passing hook, so the skip list this script writes to stdout was -# swallowed whole. A 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 # reader with no idea which binary to install, which is most of why the swallowed -- 2.43.0