holocron/SIMPLIFICATION-AUDIT.md

Simplification audit

Date: 2026-09-10. Read-only analysis; nothing has been changed. Purpose: a hand-off for deciding what to remove, merge, and shrink. Findings are ranked by payoff within each area; effort is S/M/L. Claims were independently re-verified against the repo by a clean reviewer; corrections have been applied.

Assumptions agreed before analysis: anything is on the table, Claude Code and Copilot CLI both stay supported, findings are ranked with effort.

Counting convention: line counts are hand-edited .apm/ source unless marked "incl. mirror". Every .apm/ file has a byte-identical generated copy at the plugin root, so plugin cuts count double in the repo total.

Superseded (2026-09-14): the mirror is gone (commit 718c79a, ADR-0024). "incl. mirror" totals below are historical. Measured against the 2026-09-10 baseline (9eb8bc7), what remains live varies by plugin — 44% to 71%, not a uniform ~70%:

Plugin	Baseline (incl. mirror)	At a6434e0	Live
kyberforge	44,568	31,432	70.5%
git	9,889	6,045	61.1%
gitea	6,047	3,471	57.4%
core	3,873	2,355	60.8%
lint	1,558	923	59.2%
bin	4,704	2,075	44.1%

Across all six the baseline was 70,639 lines and 46,301 remain (65.5%). The mirror was 20,061 of those lines, so mirror deletion alone would have left ~71.6%; everything below that line is source the other findings cut, which is why bin — where findings 10, 12, and 13 landed hardest — is the outlier. (Counted as tracked lines under plugins/<name>/ at 9eb8bc7 and at a6434e0.)

Re-measured (2026-09-14, at a6434e0): the right-hand column originally read 31,473 / 6,050 / 3,471 / 2,360 / 923 / 2,083 = 46,360 and was labelled "Today" against "the current working tree". It did not reconcile to its own commit's tree — at 061bb3d, where it was written, the six plugins measured 31,435 / 6,048 / 3,474 / 2,358 / 926 / 2,087 = 46,328 — and "the current working tree" is a basis that goes stale silently. Re-counted at a6434e0 and the column now names its SHA. The baseline column is confirmed exact against 9eb8bc7. Commits after 061bb3d (c96ca9c, which deleted the six plugin-root .mcp.json files) account for most of the remaining drift.

Reviewed (2026-09-14): commits 718c79a and d2480b8 were put through a five-agent review. Result: zero skill, agent or hook regressions — 39 skills before and after, all gates passing, and both hook removals (validate-plugins, check-plugin-content-sync) genuinely moot rather than merely unenforced. One real functional regression was found — MCP propagation to consumers, broken by the same commit's manifest deletion; see finding 37 — along with the numeric and bookkeeping drift in this document's own 2026-09-14 notes, corrected in place above and below.

1. The shape of the problem

Measure	Value
Tracked files / lines	820 / 102,000 → 475 / 73,073
Lines in plugins/	70,600 (69% of repo) → 46,301 (63% of repo)
Of which the 39 SKILL.md files a model actually loads	about 2,600 lines (under 4% of plugin lines) → 2,509 lines (5.4% of plugin lines)
Generated flat mirror files (byte copies of .apm/)	~263 files, 22,000 lines → 0 (deleted 2026-09-14, see below)
docs/research/ vendored inside plugins	~19,000 lines, nothing executable reads it
Repo-level docs/research/ + docs/notes/	4,500 lines, 47% of all prose words, 6 of 11 research files linked only from each other
Enforcement: hook entries in .pre-commit-config.yaml / pre-push hooks	33 / 14
Enforcement: tests/*.sh + runners + scripts/	12,400 + 475 + 4,500 lines → 9,123 + 490 + 3,308 lines
Validator scripts inside kyberforge (+ their bats tests)	6,800 + 5,300 lines
Preload tax (39 skill names + descriptions)	10,987 chars, ~2,750 tokens per session
Commits since 2026-05-10 / share touching hook, test, gate, vale, or sync	447 / ~25%

Corrected then done (2026-09-14): the mirror row's figure was wrong. The true mirror was 213 files / 20,061 lines, not 263 / ~22,000 — the original count swept in files that were never mirror output. All 213 were deleted in commit 718c79a on docs/simplification-audit (245 files changed, 298 insertions, 22,602 deletions across the whole change), so the row is now zero. The enforcement row is stale on both halves — it was correct at the 2026-09-10 baseline (9eb8bc7: 33 - id: entries, 14 repo-authored pre-push hooks), but .pre-commit-config.yaml today has 27 entries and 9 stages: [pre-push]. Like for like that is 14 → 9 repo-authored pre-push hooks. The stage reports 11, because the 2 pre-commit meta hooks also run there — a different counting basis; see the corrected §3 target, which states it the same way.

Re-measured (2026-09-14, at a6434e0): this table is a dated snapshot corrected in place, not a live figure — every arrow above reads "baseline (2026-09-10, 9eb8bc7) → value at the stated commit". Three further rows were still carrying baseline values after d2480b8/061bb3d corrected their neighbours, and are now corrected at a6434e0:

• Tracked files / lines: 475 / 73,073 (475 is git ls-files | wc -l: 471 regular files plus 4 submodule gitlinks — docs/wiki, tests/bats, tests/test_helper/bats-assert, tests/test_helper/bats-support, whose own contents are not counted).
• Lines in plugins/: 46,301, which is 63% of 73,073, not 69%.
• The 39 SKILL.md bodies: 2,509 lines. That is now 5.4% of plugin lines rather than "under 4%" — the share rose because the denominator shrank faster than the payload, which is the whole point of the audit.
• Enforcement scripts and tests: 20 tests/test-*.sh totalling 9,123 lines, the two runners 490 (run-tests.sh 281 + run-bats.sh 209), and scripts/ 3,308.

Re-checked and still accurate at a6434e0, so left alone: docs/research/ inside plugins (19,030), repo-level docs/research/ + docs/notes/ (4,488), kyberforge validators + their bats tests (6,849 + 5,256). The hook-entry row is superseded by the paragraph above. Not re-measured: the preload-tax row (10,987 chars) and the commit-share row — the commit count alone has moved to 476 since 2026-05-10, and that row was always a moving figure.

The pattern across every area is the same: the payload (skill bodies, rules, decisions) is small and the scaffolding around it (mirrors, research dumps, sync gates, tests of tests, justification prose) is 10 to 30 times larger. A quarter of all commits have gone into maintaining the scaffolding.

2. Measured baseline: hooks and tests

Measured on this machine, clean tree, all hooks passing. pre-commit run --all-files per stage. Figures below are the 2026-09-10 measurement; rows struck through were deleted on 2026-09-14 (commit 718c79a) and their times no longer apply.

Gate	Wall time
Full pre-push stage (everything below, sequential)	~5 min 10 s
run-tests (26 bash suites + 351 bats tests)	276 s
apm-audit-ci (7 manifests)	12.2 s
validate-plugins (6 × claude plugin validate) deleted	4.9 s
check-plugin-content-sync deleted	4.5 s
apm-pack-check-clean	3.1 s
Other 9 pre-push hooks combined	7.6 s
Full pre-commit stage, all files	18.2 s

run-tests is 90% of the wall time. Every push pays it in full: the runner has no change detection and the config sets always_run: true. apm-audit-ci is the second-slowest hook; per its own comment block its earlier description overclaimed, and what it verifies today is that seven manifests parse and the lockfile exists.

Where the 276 s goes (each suite run alone, sequential):

Suite	Time	Note
test-sync-plugin-content.sh deleted	83 s	14 temp trees, 2 git init, repeated apm pack
all 351 bats tests (10 files, kyberforge and core validators)	64 s	mostly validate.sh / validate-provenance.sh fixtures
test-adr0020-differential.sh	29 s	12 assertions; re-runs two validators over the live corpus and a fixture tree
test-check-vale-style-sync.sh deleted	25 s	guards a byte-identical copy
test-vale-wrap.sh	14 s
test-adr0020-frontmatter.sh + -targets.sh	25 s
Remaining 20 suites	36 s	12 of them run in under 2 s each

Five suites account for 215 s of 276 s. Three of those five (sync-plugin-content, vale-style-sync, adr0020-differential) test tooling that findings 2, 7, and 14 propose to delete or shrink, so the fastest path to a quick pre-push is removing the duplication those tests guard rather than optimising the tests.

Also struck (2026-09-15): test-check-vale-style-sync.sh (25 s) went with the check-vale-style-sync hook in finding 14's merge (ADR-0025). Measured at HEAD: tests/ holds 19 test-*.sh suites and tests/run-tests.sh reports 19 passed, 0 skipped, 0 failed. (Later the same day, the pipefail-race fix added tests/test-no-pipefail-early-exit-grep.sh, making it 20. That suite is a static scan and runs in well under a second, so the timing arithmetic here is unaffected.) Same basis as the note below — arithmetic on the 2026-09-10 baseline minus the struck rows, not a fresh timing run.

Done (2026-09-14): see commit 718c79a on docs/simplification-audit. The three struck-through rows are gone: test-sync-plugin-content.sh (83 s, 1,289 lines, 92 cases), check-plugin-content-sync (4.5 s) and validate-plugins (4.9 s). Expected, not re-measured: roughly 92 s comes off every push (83 + 4.5 + 4.9 = 92.4 s) (~83 s of it out of run-tests, which loses its single slowest suite), on the arithmetic of the 2026-09-10 figures alone. The remaining rows have not been re-timed since, so treat every number in this section as the 2026-09-10 baseline minus those three, not as a fresh measurement.

3. Enforcement layer: hooks, tests, scripts

This is the area you named as hardest to understand and slowest. Root cause: most pre-push hooks exist to keep two copies of something in sync, or to re-validate what another hook already validates.

1. Six hooks validate overlapping sets of the same manifests. check-manifests, validate-plugins, validate-marketplace, apm-pack-check-clean, apm-marketplace-check, apm-audit-ci. Keep the two claude plugin validate hooks plus apm-pack-check-clean. Delete check-manifests (282 lines + 771 test lines; its lib/marketplace-plugins.sh stays because sync-plugin-content.sh sources it). apm-audit-ci spends 12 s confirming that manifests apm pack already parses do parse; drop or keep on that basis. Move the network-dependent apm-marketplace-check to a release checklist. Effort S.

   Done (2026-09-12): see commit e647f14 on docs/simplification-audit. Deleted the check-manifests pre-commit hook entry, scripts/check-manifests.sh (282 lines), and tests/test-check-manifests.sh (771 lines); kept scripts/lib/marketplace-plugins.sh, still sourced by sync-plugin-content.sh. Updated the now-stale check-manifests.sh mentions in README.md and docs/spec/gates.md (hook table row and hook counts). The apm-audit-ci and apm-marketplace-check decisions in this finding remain open — out of scope for this change. Grilled and closed (2026-09-14): apm-audit-ci — already resolved before this audit was written: .pre-commit-config.yaml's own comment block (added in commit a155af6, months before this audit) already rebuts the "overclaimed description" complaint and gives a dated, verified justification for what the hook still checks. Keep, no action. apm-marketplace-check — its stated purpose ("the only hook that checks remote package references rather than local-source paths") is void: finding 35 (commit 568ca74) already removed the only remote package entry, so every marketplace.packages[] entry is now a local ./plugins/<name> path and the hook is pure overlap with apm-pack-check-clean. Removed the hook entry, and corrected the now-stale "does NOT join apm-marketplace-check ... on the offline SKIP= list" comment on apm-audit-ci (there is no offline skip list any more — every pre-push hook already passes offline per README.md). Updated README.md (tool table, "Offline?" section) and docs/spec/gates.md (hook table, hook counts 13→11 self-authored / 15→13 total, the "Three of these shell out to apm" paragraph, and the "Pushing without a network" section) accordingly. Verified: apm audit --ci still passes per-plugin, and the pre-push hook count now matches .pre-commit-config.yaml. Corrected and closed (2026-09-14, at a6434e0): two things above went stale within hours of being written, and the finding was never given a marker.

   • "Keep the two claude plugin validate hooks" is void. 718c79a (ADR-0024) deleted validate-plugins — the ADR's own reasoning is that claude plugin validate reads manifests only and could never detect the empty-content defect it was credited with guarding, and with the per-plugin manifests gone it has nothing left to read. Only validate-marketplace survives, over the one manifest this repo still ships (.claude-plugin/marketplace.json). Of the six hooks this finding named, three now exist: validate-marketplace, apm-pack-check-clean, apm-audit-ci. Verified against .pre-commit-config.yaml: 27 - id: entries, 9 with stages: [pre-push], no validate-plugins entry.
   • The gates.md figures above ("13→11 self-authored / 15→13 total") were correct for 0dffff3 and are no longer current. 718c79a removed two more pre-push hooks after that commit, and docs/spec/gates.md:24 read 11 reported / 9 self-authored when this note was written; finding 14's merge has since removed check-vale-style-sync, and it now reads 10 reported / 8 self-authored. Read the count from that file, not from this note.

   Marked [x]: all three of this finding's decisions are resolved — check-manifests deleted (e647f14), apm-audit-ci kept on the grill above, apm-marketplace-check removed (0dffff3).

2. Four two surviving "keep two copies in sync" gates: 1,100 script lines + 1,600 test lines 778 script lines + 1,079 test lines. Each one is a symptom of duplication that could be removed instead of guarded:

   Re-measured (2026-09-14, at a6434e0): two of the four are gone — check-marketplace-mirror-sync deleted in 0dffff3 (2c below) and, though it was never in this finding's own count, check-plugin-content-sync in 718c79a. The two that survive are check-vale-style-sync (413 script + 797 test) and check-scope-walkup-sync (365 + 282); check-executables-allow-sync also survives, shrunk to 222 + 243 (2d below), and counts as the third if that gate is read as part of this group rather than as its own item. Two-gate total 778 + 1,079; three-gate total 1,000 + 1,322. The per-bullet script and test figures below are all still exact at this commit except check-executables-allow-sync's "474 lines", which 2d already corrects.

   • check-vale-style-sync: 413 lines + 798 test lines guarding a byte-identical 526-line vale-wrap.sh and style directory copied between skill-audit and agent-audit. About 350 of its lines run Vale glob probes against the hook file patterns. Disappears if the two audit skills merge (finding 14); the probes belong in test-vale-wrap.sh.
   • check-scope-walkup-sync: 365 lines cross-checking four independent ports of the same package-root walk-up. Disappears if the ports share one script or the skills merge.

     Grilled, held (2026-09-14): both of the above are gated on findings 14/15 (merging skill-audit+agent-audit and skill-author+agent-author), deliberately held for a separate session rather than decided here. Correction for that session: the audit's §8 grouping is wrong — these merges don't need ADR-0012 revisited (that ADR governs the unrelated core plugin's three agentsmd-* skills). The actual constraint is ADR-0014 (no-cross-skill file sharing on plugin cache-install), and merging sidesteps it rather than requiring it be reversed. The open question for that session is a design one — a shared skill's description carrying both skill- and agent-audit trigger phrases — not an ADR supersession. ADR-0012 revisit is needed only for finding 24. Settled (2026-09-15) — split verdict, and the first bullet held in full. Finding 14 landed as factory-audit (ADR-0025). check-vale-style-sync is deleted, hook, script and test, exactly as the first bullet predicted — and its probes were rehomed into test-vale-wrap.sh, as cases 28-30 (case 31 carries the override allowlist), so both halves of that bullet are closed. docs/spec/gates.md records the rehoming, not an open gap. (Updated later on 2026-09-15.) The one assertion this note used to call still uncovered — cross-manifest agreement between .pre-commit-hooks.yaml's and .pre-commit-config.yaml's files: regexes — is now ported as case 33, which pairs the hooks by id:. Case 32 covers the separate zero-match question. It was a real gap while it lasted: narrowing the local skill hook to ^plugins/kyberforge/ left 6 of 38 skills prefiltered and the suite green. bash tests/test-vale-wrap.sh now reports 61 passed, 0 failed (it was 56 before cases 0 and 33 and the Part B mutation self-tests). The bullet's "about 350 of its lines run Vale glob probes" overstates the probe half: at a5962ba the script is 413 lines, of which the .vale.ini coverage section is 332 (67..398) and the machinery that actually invokes vale against a probe path is 204 (195..398). The balance of that section is StylesPath, BasedOnStyles and per-rule-override greps — text assertions, not probes. (Its test file is 797 lines, as the note above says, not the 798 the bullet carries.) check-scope-walkup-sync stays, and the second bullet's "or the skills merge" is wrong: two of its four walk-up ports are in the author skills (new-agent.sh, new-skill.sh), which this merge does not touch, and the audit-side pair is Python against the author-side pair's Bash, so the gate can never degrade into a text diff. Full reasoning in §10's 2026-09-15 note. Finding 15 would not remove it either.

   • check-marketplace-mirror-sync: guards .github/plugin/marketplace.json. The script header calls it Copilot's legacy convention path and says Copilot also accepts the Claude path; the vendored Copilot docs list it as primary. Verify against current Copilot CLI before deleting hook, script, test, and mirror file.

     Grilled and done (2026-09-14): verified against GitHub's current Copilot CLI plugin docs (not the vendored copy, which risked drift). Copilot CLI's marketplace discovery checks paths in order — marketplace.json, .plugin/marketplace.json, .github/plugin/marketplace.json, .claude-plugin/marketplace.json — falling through to whichever exists first. .claude-plugin/marketplace.json (apm's own claude output) already satisfies that chain's last step, so the dedicated .github/plugin/marketplace.json mirror bought Copilot users its preferred discovery path rather than a required one. Decided against reopening ADR-0018 (native install for both Claude Code and Copilot CLI stays supported) to justify this — the deletion holds either way, since Copilot's own fallback covers it. Deleted .github/plugin/marketplace.json, scripts/sync-marketplace-mirror.sh (81 lines), tests/test-sync-marketplace-mirror.sh (304 lines), and the check-marketplace-mirror-sync pre-push hook; removed the dangling references to the deleted script in scripts/sync-plugin-content.sh and tests/test-sync-plugin-content.sh (both had comments citing its reasoning by name), and updated docs/spec/architecture.md's description of the marketplace-manifest compile step. tests/test-sync-plugin-content.sh (92 cases) still passes in full.

     Correction (2026-09-14, later the same day): the parenthetical "Decided against reopening ADR-0018 (native install for both Claude Code and Copilot CLI stays supported) to justify this" was true when written and is now the opposite of the repo's decision. 718c79a landed ADR-0024 hours later and dropped native install support outright, for both hosts. The note is left standing as the record of what was decided at 0dffff3; read the parenthetical as historical. The deletion itself still holds, and holds more strongly — the file was removed on the grounds that Copilot's own fallback covers it, and ADR-0024 removed the content that fallback would have led to, so the mirror file would now be a discovery path to nothing. See the §8 Copilot bullet, corrected on the same point.

   • check-executables-allow-sync: 474 lines to assert one string equals kyberforge's version. A six-line grep, or drop it (the failure mode is visible and recoverable).

     Corrected then partially done (2026-09-13): see commit 1b01e25 on docs/simplification-audit. Independent re-verification found "drop it" unsafe — ADR-0019's own Consequences section calls this failure mode silent and says a silent-staleness failure here is worse than the duplication the other gates catch, directly contradicting the finding's "visible and recoverable" claim. The hook stays. Shrunk scripts/check-executables-allow-sync.sh 231 → 222 lines by deduplicating two comment blocks that re-derived ADR-0019's own reasoning inline, replacing them with a pointer at the ADR. The dual-reader design (PyYAML plus a hand-rolled fallback, so a missing PyYAML can't silently skip the check) was found to be load-bearing, not redundant, and left intact; test file unchanged (behavior unaffected). All 23 test cases and the live pre-push hook run still pass. Effort S each, M for the walk-up.

3. Tests of the test harness: 1,090 lines testing 475 lines. test-run-tests.sh and test-run-bats.sh defend "green either way" holes that exist only because the runners hand-roll TAP parsing and set-equality checks. Replace both runners with about 40 lines (bats -r plugins plus a parallel find | xargs over test-*.sh) and delete the meta-tests. lib/batch-run.sh stays; sync-plugin-content.sh sources it both runners source it. Effort M.

   Not proceeding (2026-09-13): premise doesn't hold. A full read of both runners and both meta-tests found the "TAP-parsing/set-equality" logic is regression coverage for specific past incidents — a BATS_FILE_FLOOR hardcode once let deleted test files vanish silently ("155 tests, 0 failures" with 11 tests missing); a missing/broken run-bats.sh used to make the whole bats suite disappear with a green summary; a formatter change once reported "0 tests, 0 failures" as a pass. Replacing the runners as specified would delete exactly the guards against that failure class. No changes made. Re-scoping this would mean deciding, guard by guard, which are still worth keeping — a design decision, not a mechanical cleanup. Rationale corrected, decision unchanged (2026-09-14, at a6434e0): the stated reason lib/batch-run.sh survives was void — sync-plugin-content.sh was deleted in 718c79a. The conclusion is unaffected: batch-run.sh (90 lines) is sourced by tests/run-tests.sh:185 and tests/run-bats.sh:138, and copied into fixture trees by tests/test-run-tests.sh:51 and tests/test-run-bats.sh:49. Since the finding is not proceeding, both runners stay and keep sourcing it, so nothing is orphaned. Note the knock-on if this is ever re-scoped: with the sync script gone, "replace both runners" would leave batch-run.sh with no caller at all, which the original wording assumed it could not. Headline figures re-measured: the meta-tests are 1,090 lines (675 + 415, as stated) against 490 runner lines, not 475 — the runners grew from 273 + 202 at the 9eb8bc7 baseline. (Both runners and batch-run.sh were under concurrent edit when this was measured; figures are as of a6434e0.)

4. skill-frontmatter is a 62-line bash script inlined in YAML with its own 366-line test. skill-size-check.sh already parses the same frontmatter with PyYAML. Fold it in (about 15 Python lines), delete the inline hook, its test, and the 79 lines in gates.md arguing for the split. Effort S.

   Done (2026-09-12): see commit c8a7c9e on docs/simplification-audit. Added a ~20-line required-frontmatter check (name, description, metadata.version as three-part semver) to scripts/skill-size-check.sh, reusing the YAML mapping description_value() already parses. Removed the inline skill-frontmatter hook (~80 lines) from .pre-commit-config.yaml and deleted tests/test-skill-frontmatter.sh (366 lines). Removed the 79-line "the other hook on that scope" discussion from docs/spec/gates.md and its now-dangling cross-reference, replacing both with a one-line note of the fold; updated the pre-push hook counts there. Updated fixture builders in tests/test-skill-size-check.sh, tests/test-adr0020-body-checks.sh, tests/test-adr0020-targets.sh, tests/test-adr0020-differential.sh, and tests/test-vale-hooks-consumer.sh to carry valid metadata.version so the new check doesn't spuriously fail existing fixtures.

5. skill-size-check.sh has six test files totalling 3,589 lines for one 1,497-line script, split by ADR section rather than behaviour. test-adr0020-differential.sh is 452 lines for 12 assertions. Merge to two files. Effort M.

   Not proceeding (2026-09-14): premise doesn't hold, in the same way finding 3's did not. The six suites are not split by ADR section — they are split by failure class, and five of the six headers name the incident they guard. (The exception is tests/test-skill-size-check.sh, whose header names no incident: it describes the two gate families the script must not conflate and flags the constant-agreement block as the load-bearing part.) test-adr0020-contract.sh defends structural claims that "each one fails silently": that the resolver block copied verbatim into three scripts has not drifted, that both interpreter preflights still exist, that verbose: true is still set on the hook (the entire delivery mechanism for the SUGGESTION tier). It records that the validate-provenance.sh pair "had already drifted" once. test-adr0020-differential.sh compares verdicts between skill-size-check.sh and validate.sh on real files, and its header states that constant-agreement is "necessary but demonstrably not sufficient — a previous review found the two scripts disagreeing on real files while every constant matched perfectly", with two ceilings excluded "until a real divergence shipped behind the exclusion". The suites also do not cover the same scripts: contract reaches validate-provenance.sh (tests/test-adr0020-contract.sh:115-116 byte-compares both copies of it). Merging by subject would delete exactly the guards against silent drift between hand-duplicated validators. Re-measured at HEAD: 3,619 lines across six suites against a 1,517-line script, not 3,589/1,497. That ratio is the cost of the duplication, not an independent defect — it is deleted by finding 16, which removes the thing being differentially compared. #5 is downstream of #16 and should be reconsidered only after it. The one salvageable part is a performance change, not a coverage change: test-adr0020-differential.sh spends 29 s of every push re-running two validators over the live corpus, and could be sped up with no coverage loss. That is a different finding than the one written here.

6. Prose-grep tests. test-governance-layer.sh and test-instructions-and-docs.sh (583 lines) grep markdown for phrases, including a one-shot "issue 0015 refactor incomplete" assertion made permanent and an assertion that docs/notes/ exists. Delete both. check-apm-agents-valid.sh (161 + 264 test lines) is a loop plus fail-closed guards around validate.sh; it folds into the merged audit skill's own tests (finding 14). Effort S.

   Done (2026-09-12): see commit 5f9f2b3 on docs/simplification-audit. Deleted tests/test-governance-layer.sh (270 lines) and tests/test-instructions-and-docs.sh (313 lines); no other file referenced either. check-apm-agents-valid.sh was left untouched — its fate is tied to the separate, out-of-scope skill-merge finding 14.

7. check-plugin-content-sync.sh is 813 lines wrapping apm pack, with a 1,291-line test. The mirror itself must stay (Claude Code marketplace installs need flat directories), and the script does real work a bare git diff would lose: it strips tests/ from the mirror, regenerates both plugin.json files with mcpServers reinjected, and packs into a scratch copy so --check never mutates. Even so, 2,100 lines for that is disproportionate; target a third. Effort M.

   Superseded then done (2026-09-14): see commit 718c79a on docs/simplification-audit. The recommendation ("target a third") is void, not met — the §8 question it depended on was settled the other way. Answering "apm-only" (ADR-0024) removed the mirror's reason to exist, and with the mirror gone the script guarded nothing, so the whole thing was deleted rather than shrunk: scripts/sync-plugin-content.sh (813 lines), tests/test-sync-plugin-content.sh (1,289 lines — the finding said 1,291), the check-plugin-content-sync pre-push hook, and scripts/lib/marketplace-plugins.sh (86 lines, whose only consumer was the sync script, and which finding 1 had explicitly kept alive for it). validate-plugins went with them, and the twelve per-plugin plugin.json manifests the script regenerated. The finding's own premise — "the mirror itself must stay" — is what turned out to be wrong.

8. docs/spec/gates.md (1,048 lines) is roughly 15% "what is enforced" and 85% post-mortems of defects already fixed and pinned by tests. The 60-line hook table is the useful part. Target 200 lines. The same applies to the 106 comment lines in .pre-commit-config.yaml and to scripts/, where 8 of 15 files are 40 to 60% comments. Effort M.

   Partially done (2026-09-13): see commit a35f5e8 on docs/simplification-audit. The 85%-post-mortem characterization was stale — the file had already shrunk to 966 lines by other findings, and most of what remained is load-bearing "why this design" rationale cited by ADRs and tests, not dead incident narration. Cut only the two genuinely stale passages: a reproduction paragraph carrying explicitly outdated numbers, and a retrofit-process narrative superseded by current state — a 36-line cut, 966 → 930 as measured at commit a35f5e8. Those two figures describe that commit only, not the file: 718c79a and later findings have edited gates.md again, so read its current length from the file rather than quoting a number here. .pre-commit-config.yaml's comments were left untouched; on inspection they're compact constraint notes, not filler. Target of 200 lines not reached and not recommended — would require deleting content the file itself flags as load-bearing.

Proposed target. Pre-push 14 hooks to 6: run-tests, validate-plugins, validate-marketplace, apm-pack-check-clean, check-plugin-content-sync, check-release-needed.

Corrected (2026-09-14): two of the six named targets no longer exist — validate-plugins and check-plugin-content-sync were deleted in commit 718c79a (finding 7, ADR-0024). Actual state today: 9 repo-authored pre-push hooks — run-tests, check-executables-allow-sync, apm-audit-ci, check-apm-agents-valid, apm-pack-check-clean, check-vale-style-sync, check-scope-walkup-sync, check-release-needed, validate-marketplace — plus the 2 pre-commit meta hooks that also run at this stage, so 11 are reported at pre-push. validate-marketplace was kept: the root marketplace: block in apm.yml and the root .claude-plugin/marketplace.json stay, because apm's own marketplace consumers read that same catalogue and <name>@holocron short names depend on it. (That manifest is the only tracked file under .claude-plugin/ — git ls-files .claude-plugin returns it alone. The sibling .claude-plugin/plugin.json is a local apm pack byproduct, has never been tracked on any branch, and is ignored at .gitignore:59; it was not "kept", because it was never there.)

Superseded count (2026-09-15): finding 14 deleted check-vale-style-sync with the merge into factory-audit (ADR-0025), so pre-push is now 8 repo-authored hooks (10 reported). The dated note above is the state on 2026-09-14; see finding 14's note for the correction.

Pre-commit stays roughly as is minus skill-frontmatter, and minus check-ast once finding 9 removes the only .py files. Tests 26 files to about 10 (12,400 to about 5,000 lines). Keep bats and its three submodules; the 351 bats tests ship inside plugins and are the right tool there. Do not port the bash suites to bats; delete them instead.

Re-measured (2026-09-14, at a6434e0): the tests target was stated against the 2026-09-10 baseline and both its numbers are stale. tests/ now holds 20 test-*.sh suites totalling 9,123 lines (plus the two runners, 490). Six suites have gone since the baseline: test-check-manifests.sh (e647f14), test-skill-frontmatter.sh (c8a7c9e), test-governance-layer.sh and test-instructions-and-docs.sh (5f9f2b3), test-sync-marketplace-mirror.sh (0dffff3), test-sync-plugin-content.sh (718c79a). Restated on the same basis the target is 20 files to about 10, 9,123 to about 5,000 lines — the file half of the target is now the closer half, and finding 9's check-ast clause is moot anyway, since finding 9 is not proceeding.

4. Plugins

The shared pattern: per-skill README.md files no model reads, a docs/research/ dump per plugin, a sources.md provenance chain with its own validator, and reference files that restate man pages.

4.1 Cross-plugin (apply everywhere)

9. Delete docs/research/ from every plugin (~19,000 lines). kyberforge's alone is 14,143 lines, 32% of the plugin, and about 8,900 of those are vendored third-party content (Anthropic skill-creator including a 1,325-line viewer.html and ten .py files, obra/superpowers, mattpocock). The rest is copied tool documentation. The gitea references explicitly say the research doc "has a known history of drifting from the deployed server". Every apm.yml uses includes: auto; whether the directory ships to consumers needs one check. Keep upstream URLs in one line per plugin README; git history keeps the rest. Check obra/superpowers licence if anything is retained. Goes together with finding 11: 32 sources.md files carry "Research doc" paths into these directories. Effort S.

   Decision (2026-09-12): Keep. docs/research/ is retained on purpose — it's read by agents doing work sourced from those docs. Not proceeding.

10. Delete per-skill README.md and references/README.md (48 files, 1,574 lines). They restate the SKILL.md in narrative form. The pre-commit config itself notes a skill README "is consumer-facing prose that no agent ever loads". Keep one plugin-level README with one line per skill. Requires dropping the README criterion in skill-audit/references/file-structure.md and the README step in new-skill.sh. Effort S.

Done (2026-09-12): see commit edcc57c on docs/simplification-audit. Deleted the 48 per-skill/reference READMEs plus 2 scaffold templates; dropped the README criterion from skill-audit's file-structure.md and finding-criteria.md and the README-generation step from new-skill.sh; updated new-skill.bats to match. Plugin-root READMEs were kept, not part of this finding.

11. Drop the provenance chain: sources.md, source_keys frontmatter, validate-provenance.sh. 32 plugin and skill sources.md files (about 1,300 lines) plus 9 research indexes, 216 source files with source_keys, two copies of the validator (1,198 and 632 lines) with ten checks, and 125 bats tests exist to track which upstream informed which file. Git blame and a URL in the README do the same job. This is more code than the content it tracks. Effort M (touches skill-audit, both validator copies, two repo tests, and every skill's frontmatter).

    Verified (2026-09-14, at HEAD 062ca47): direction defensible, two scope figures wrong, and blocked on a decision the finding never poses. The sources.md census below is exact, and so are the finding's own validator and bats figures (1,198 / 632 lines, 125 bats tests); the scope errors are narrower than an earlier revision of this note claimed.

    Corrected figures: 46 sources.md files / 1,752 lines in three distinct classes — 29 skill references/sources.md (1,217 lines), 13 research indexes (435), 4 plugin-root files (100, ADR-0010). The finding does not double-count: it states two disjoint classes additively ("32 plugin and skill sources.md files (about 1,300 lines) plus 9 research indexes"), and that plugin-and-skill subtotal is really 33 files / 1,317 lines, matching its "about 1,300" exactly — had the 32 swept in the research indexes the figure would have been ~1,750. Its real errors there are an off-by-one (32 should be 33) and an omission: it missed the 4 vendored example indexes under kyberforge/docs/research/examples/skill-write/, so 9 should be 13. Carriers of source_keys in YAML frontmatter: 196 — 168 at column 0 and 28 nested two spaces under metadata: — so the finding's 216 is closer to the truth than it looks. (219 files merely mention the string. A naive ^[[:space:]]*source_keys: grep returns 200, but 4 of those are heredoc or fixture text rather than frontmatter: both validate-provenance.bats copies, scripts/check-scope-walkup-sync.sh, and a fenced example in plugins/bin/.apm/skills/research/references/file-format.md.) Checks: 16 across the two copies (skill-audit 0–9, agent-audit 0–5), not ten. Validator line counts (1,198 / 632) and 125 bats tests are exact.

    "Touches every skill's frontmatter" is roughly right. 28 of the 39 real skills carry source_keys in frontmatter, nested under metadata: — see plugins/git/.apm/skills/git-commits/SKILL.md:10-17, where metadata: → source_keys: carries four slugs. (44 tracked files match *SKILL.md; subtract skill-author/assets/templates/SKILL.md and the 4 vendored under kyberforge/docs/research/examples/skill-write/, leaving 39 real skills.) The 11 without it are exactly the plugins/bin/ skills. Check 2 in the skill-side validator (SKILL.md source_keys → slug in sources.md) is correspondingly live, not dead code: parse_source_keys() at plugins/kyberforge/.apm/skills/factory-audit/scripts/lib-provenance-skill.sh:277-305 handles both spellings explicitly — the metadata-nested branch at :292, the top-level branch at :295, and a docstring that says "handles metadata.source_keys and top-level" — check 2 at :712 runs against all 28 carrier skills, every one of which has a references/sources.md, and bats pins it at plugins/kyberforge/.apm/skills/factory-audit/tests/validate-provenance-skill.bats:222 ("FAIL: source_keys slug in SKILL.md not present as H2 in sources.md") and :1337 (a BOM must not silently disable check 2). (Paths and line numbers re-derived at HEAD: ADR-0025's merge moved this code out of skill-audit/scripts/validate-provenance.sh into the shared skill-side library, so the figures this note carried at 062ca47 — :242-270, :257, :260, :766, :1313 — no longer resolve.) The imbalance the finding names is real and worse than claimed: 4,641 validator+bats lines against 1,752 of metadata, a 2.6:1 ratio.

    Omitted entirely: the chain has a producer. plugins/bin/.apm/skills/research/ specifies the sources.md + source_keys: output format, and plugins/bin/evals/research/research/eval.yaml carries three criteria asserting it. This is the blocking decision: does research keep emitting sources.md? If yes, the chain is not dropped — only unenforced, and the finding collapses to "delete the validators." If no, the research skill's output contract and its evals need redesigning.

    Also breaks: check-scope-walkup-sync loses one of four walk-up ports (the hook exists because three scripts drifted); tests/test-adr0020-contract.sh loses its parser byte-identity assertion; tests/test-check-scope-walkup-sync.sh must re-base its fixture; ADR-0010 is superseded outright and ADR-0009/0016 need amending (field-inventory.md's allowlist data line carries source_keys). LESSONS.md:73 records this validator as the only thing that catches a skill authored outside skill-author — a failure that "recurred twice in one session" — so "git blame + a README URL do the same job" is false for the one thing the chain demonstrably catches. Side effect: 55 reference files have frontmatter containing only source_keys:, leaving empty ---\n--- blocks to delete.

    Effort L, not M (~6,393 lines deleted across 242 files: the 4,641 validator and bats lines plus the 1,752 of sources.md measured above, across 196 source_keys carriers and 46 sources.md files. An earlier revision of this note said ~4,600 lines across ~230 files, which was internally inconsistent — 4,600 is validator-plus-bats only and silently drops the sources.md this same note measures, and ~230 inherited a carrier count of 172 that missed every metadata:-nested file.) Smaller alternative worth considering: scope the drop to the skill half only (1,217 lines, 1,198-line validator, 82 tests) and leave the ADR-0010 plugin-root half alone — no ADR supersession needed.

12. Strip ADR and changelog narration from model-facing files. ADR-0020 is cited in 3 of 7 kyberforge SKILL.md files and 16 references; ADR-0023 is cited inline 21 times in the git plugin. Examples: "was the old house rule and ADR-0020 deleted it", "were removed per ADR-0015 once issue #90 landed", "this file previously recorded list_issues as having neither a type nor a milestones parameter". skill-author/references/retrofit.md (197 lines) is a one-time migration guide; it is loaded from improve.md and listed in sources.md, so remove those in the same change. These belong in git history or the ADR, not in context. Effort S.

Done (2026-09-12): see commit edcc57c on docs/simplification-audit. Historical narration stripped from kyberforge (ADR-0020) and git (ADR-0023) skill content; retrofit.md deleted along with its load-step and sources.md entries. Caught in review: some ADR-0023 tags were not narration but the check-rtk-prefix hook's required opt-out marker for intentionally-bare git commands — those 12 were restored, not left stripped.

13. State repeated boilerplate once or delete it. A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is git-orchestrate (finding 19). Effort S.

    Done (2026-09-12): see commit 6cfc357. Trimmed each repeated instance in place — same meaning, fewer words — rather than extracting to a shared file (blocked by the one-file-per-skill install constraint, ADR-0014): the "Resolve owner and repo" block across 5 gitea-* skills, the 404-masks-403 note across 6 gitea files, the manual-pagination explanation across 8 gitea files, the main/master force-push refusal across 7 git plugin files (some with multiple internal restatements), and the domain-glossary/ADR paragraph across 5 bin skills. This was a trim-in-place pass, not a merge: the cross-skill duplication itself remains and is coupled to the (out-of-scope) skill-merge findings 19/20. Left the three git skills' structured-result JSON shapes untouched, as directed. Verified no regressions with scripts/skill-size-check.sh (pre/post diff) and claude plugin validate on both plugins.

4.2 kyberforge (290 files, 44,568 lines incl. mirror; the 7 SKILL.md bodies are 333 lines, under 1%)

14. Merge skill-audit + agent-audit into one audit skill (removes about 3,300 lines and two pre-push hooks). vale-wrap.sh is byte-identical in both; five Vale rules byte-identical (agent-audit carries one extra, so it is the superset); validate.sh shares a 1,061-line boundary-target resolver block that diffs as zero lines; SKILL.md steps 1, 3, 4 and the gotchas are the same text. Each copy is hard-wired to one mode, so the merged script needs a path switch. The duplication exists because a plugin-cache install copies only each skill's own files (the rule ADR-0014 follows), so a script cannot be shared across skills; merging the skills is the only way to remove the copy. Effort M.

    Done (2026-09-15), with three of its claims corrected. Merged into factory-audit, not audit — the name states the domain (the artifact factory's own output) rather than the verb. See docs/adr/0025-skill-audit-and-agent-audit-merge-into-factory-audit.md. The repo goes from 39 skills to 38. Entry scripts are scripts/validate.sh, scripts/validate-provenance.sh and scripts/vale-wrap.sh. Only the first two auto-detect the artifact type they were handed and dispatch to a per-type library. vale-wrap.sh does not and never did: it is byte-identical to both pre-merge copies (diff clean against each at a5962ba) and names neither SKILL.md nor .agent.md anywhere in its 526 lines. Its scoping comes from outside it — the .vale.ini glob sections and the files: regexes of the two hooks that call it.

    • Yield: 2,934 lines and ONE pre-push hook, not ~3,300 and two. The hook is check-vale-style-sync, deleted with its script (413 lines) and tests/test-check-vale-style-sync.sh (797). They did not exist only to diff the two now-merged Vale copies — an earlier revision of this bullet said so and it was wrong, as this document's own ":104" measurement already implied. The script has 17 assertion sites (13 err calls and 4 hard-fail exits; ADR-0025 maps each one). Only 6 are genuinely moot: two diffed the copies and four guarded the script's ability to locate them. 10 were rehomed into tests/test-vale-wrap.sh: case 0 (config loads), cases 28–30 (glob probes, style loading, Copilot scoping), case 31 (override allowlist) and the suite-level exit 77. 1, the cross-manifest files: drift check, is ported as case 33, pairing hooks by id: since both now share one entry:. (Corrected later on 2026-09-15.) An earlier revision of this bullet said 18 / 6 / 11 / 1. It called the cross-manifest check knowingly dropped and "seven of them stronger". None of that survives a recount. Two text greps became behavioural Vale probes, not seven, and case 32 alone never covered the narrowing that case 33 now catches. check-scope-walkup-sync survives; see the §10 correction below for why. Pre-push goes 9 repo-authored hooks to 8 (11 reported to 10). The rest of the saving is the second embedded resolver (1,061), the second vale-wrap.sh (526), the second assets/vale/styles/Kyberforge/ copy (44), and the Contributing-files parser embedded in both validate-provenance.sh copies (93). 413 + 797 + 1,061 + 526 + 44 + 93 = 2,934, which is the headline. An earlier revision of this bullet listed 413 + 797 + 526 + 48 + 1,061 = 2,845: it dropped the 93-line parser outright, and its 48 for the Vale copy is the five byte-identical style rules (13 + 7 + 7 + 7 + 10 = 44) plus skill-audit's 4-line .vale.ini. ADR-0025 counts 44 on purpose — the two .vale.ini files were deliberately not identical (agent-audit's carried the extra [**/*.agent.md] section and the KyberforgeCopilot style), so that file is a deleted file rather than a removed duplicate, and folding it in would make the headline 2,938. All six figures measured at a5962ba.
    • "Each copy is hard-wired to one mode" was false, and it is the claim that made this look like a bigger win than it is. The two validate.sh files are not one script parameterised per mode: outside the shared 1,061-line resolver they hold 1,293 lines between them (616 skill-side, 677 agent-side) and share 91 of those. That 91 is ADR-0025's figure and it is exactly reproducible: strip the marked resolver block from each copy at a5962ba (115..1175 skill-side, 189..1249 agent-side, 1,061 lines each), then take the size of the intersection of the two distinct raw line sets — 510 distinct lines skill-side, 530 agent-side, 91 in common. An earlier revision of this bullet said "about 115", which matches no counting rule that has been reproduced: dropping blank lines gives 90 and dropping comments as well gives 64. The merged validator dispatches on artifact type over two largely independent bodies of checks; it does not collapse them.
    • The §8 blocker was a non-issue. The design question held open there — whether one description could carry both skills' trigger sets without breaching the ADR-0020 ceiling — was answered against the 400-character FAIL, which the merged description clears. Read the number from the shipped file, not from a draft. (Corrected later on 2026-09-15.) The shipped description is 241 characters, inside the 250-character SUGGESTION target, and bash scripts/skill-size-check.sh plugins/kyberforge/.apm/skills/factory-audit/SKILL.md prints nothing for it. A first cut shipped at 319 and accepted the SUGGESTION as the cost of carrying both artifact types' trigger phrases. That reasoning was wrong. The quoted phrases (audit this skill, review my SKILL.md, audit this agent, review my agent file) restated the "skill directory or agent definition audited" trigger in a second register, which ADR-0020 makes a FAIL. Removing them, and keeping both boundary arrows, gives 241. An earlier "241" in this document and ADR-0025's "240" came from a hypothetical single-arrow draft that was never reproduced. That today's figure is also 241 is a coincidence, not a confirmation of it. The real ceiling was the other one: a single body covering both artifact types ran past the 900-word body FAIL. Solved the way ADR-0020 prescribes — a dispatch body that routes to per-type references, with the 16 per-type reference files namespaced skill-* and agent-* (plus the shared sources.md).

    Finding 18 was deliberately kept out of scope. Its re-scoped remainder is prose trimming inside these same files and would have made the merge diff unreviewable; it stays open against factory-audit's files.

15. Merge skill-author + agent-author likewise. contract.md shares most of its Description section; new-skill.sh and new-agent.sh implement the same package-root walk-up with different mode names; step 1 dispatch tables and step 3 gates are near-identical. Keep the agent scope logic (plugin vs project/user) as its own reference. Effort M.

16. Cut the validators by an order of magnitude. validate.sh is 1,677 lines of bash with embedded Python, ported twice; skill-size-check.sh is 1,497. Target about 200 lines total: frontmatter present, size ceilings, boundary targets resolve. The 526-line vale-wrap.sh exists to work around folded > scalars in descriptions; writing descriptions as | literal blocks removes the folding problem, but the wrapper is also the exported hook entry in .pre-commit-hooks.yaml and carries the NOT RUN guard the audits depend on, so it shrinks rather than disappears. This is where the real complexity lives and is the item most worth discussing. Effort L.

    Refuted (2026-09-14, at HEAD 062ca47). Finding 16 has no independent content — its only safe saving belongs to finding 14.

    The three validators are not three implementations. They contain one block, 1,061 lines, byte-identical in all three, delimited by # ===== BEGIN/END ADR-0020 SHARED BOUNDARY RESOLVER ===== and hashed by tests/test-adr0020-contract.sh. So 3,183 of 4,932 validator lines (65%) are that block × 3, and what is left once the resolver is excised is 1,749 lines across all three — 1,580 non-blank, 992 with comments and blanks both stripped. The duplication is forced by the self-containment constraint, which is why merging is the lever and shrinking is not.

    Corrected figures: skill-size-check.sh is 1,517. The finding's 1,497 was correct when written — git show 9eb8bc7:scripts/skill-size-check.sh is 1,497 lines, and 9eb8bc7 (2026-09-10) is this audit's own first commit. It went stale two days after, at c8a7c9e (2026-09-12), the commit that folded skill-frontmatter in — which is why the finding's "frontmatter present" target is now work already done, not why its number was wrong. agent-audit's validate.sh is 1,738, a superset, not a 1,677-line port. vale-wrap.sh 526 × 2 is exact.

    The 200-line target is off by an order of magnitude. The resolver's executable core alone, every comment and blank stripped, is 549 lines (of its 1,061: 411 comment, 101 blank) — 2.7× the whole proposed budget, before any of the three scripts' own diagnostics. Counting call sites to error/fail, suggest and info, those number 23 in skill-size-check.sh, 31 in skill-audit's validate.sh and 38 in agent-audit's. ADR-0020 mandates 10 deterministic gates — its Enforcement table has 15 content rows: 10 deterministic, 1 prose pattern, 4 auditor judgment — and explicitly warns against "a rule filed under 'Enforcement' that no validator implements". 5,506 lines of tests guard these scripts: the six repo suites over skill-size-check.sh (3,619) plus the two in-skill validate.bats (965 + 922). Realistic floor with prose intact and duplication removed: ~2,600–2,900; comment-stripped and fully merged, ~1,100–1,200.

    The comment volume is an incident log, not filler — 26 verbatim failing input strings and four filed issues (#99, #107, #108, #110). Samples: deriving the skill universe from $BASH_SOURCE "leaked holocron's 39-skill universe into every consumer repo"; a worktree named feature[2] turned a glob into a character class and "silently disabled the gate tree-wide"; description: followed by model: sonnet "exited 0 with zero output on a BLOCKING pre-push gate"; a 550-char description with a 1,000-word body "exited 0 behind a BOM". Exactly one clause argues for speculative retention and flags itself as unexercised. Same pattern as findings 3, 5 and 24.

    The vale-wrap half is wrong on its conclusion. | literal blocks do fix the folding case — the script says so and deliberately no-ops on them — but the wrapper handles four affected scalar forms (folded >, bare plain, double- and single-quoted continuation lines), and 277 of its 526 lines are argv handling unrelated to folding (cwd-relative absolutization, the is_builtin_output guard, scratch-tree mirroring, path relativization), each with its own incident record. Decisively, .pre-commit-hooks.yaml exports these hooks to external consumer repos whose scalar style this repo cannot dictate. Converting the 40 in-repo descriptions to | is a fine independent change; it does not shrink the wrapper.

    Where the savings actually are: merge skill-audit + agent-audit (finding 14) → −1,587 lines, zero coverage loss. A second option — sourcing the resolver into scripts/skill-size-check.sh rather than embedding it (−1,061) — is technically possible but couples the root hook to plugin layout and dismantles the byte-identity contract test's design; needs a decision, not an assumption.

17. Fold forge and apm-install. forge is a four-row routing table plus 207 lines of references explaining fork vs inline; it should be 25 lines with no references. apm-install (53 lines + 17-line sources) becomes a sixth dispatch row in apm-workflow. Effort S.

18. Delete prose the model already knows. "Valid characters: lowercase letters, numbers, hyphens"; what pipx does and PEP 668; "code blocks carry a language tag"; "data to stdout, diagnostics to stderr". Ironically body-discipline.md instructs auditors not to include "concepts the agent already knows". Effort S.

    Re-scoped and folded into finding 22 (2026-09-14). All four named examples were located, and they are four different classes of thing — only one is what the finding describes:

    Example	Location	What it actually is
    "Code blocks carry a language tag"	skill-audit/references/formatting-and-scripts.md:19	An audit criterion
    "Data to stdout, diagnostics to stderr"	same file, line 39	An audit criterion
    "Valid characters: lowercase letters…"	skill-author/assets/templates/SKILL.md:7	A scaffold comment emitted into new skills by new-skill.sh; never loaded as model context
    pipx / PEP 668	apm-install/SKILL.md:35-36, skill-author/references/scripts.md	Generic tool prose — the only true positive

    Three exemptions agreed, which is what re-scopes the finding:

    • Audit criteria are exempt. body-discipline.md:14 frames the rule as "Would the agent get this wrong without this instruction?" — an auditor would, because the criterion is what it reports against. Cutting criteria is a redesign of what skill-audit checks, which belongs with finding 14.
    • assets/templates/ is exempt. Scaffold output, not context.
    • Sourced restatement of a spec this repo's own artifacts are built to is exempt. skill-author/references/scripts.md carries source_keys: agentskills-using-scripts and deliberately restates the agentskills.io spec — the contract every skill here is written against, so the restatement governs this repo's artifacts and has to be in front of the author. source_keys: alone is not the test, and cannot be: conventional-commits-spec.md and bisect.md both carry it too, and finding 20 recommends reducing both to a pointer plus the house delta. The decidable line is what the content governs — a spec this repo's artifacts must satisfy (agentskills.io) is exempt; documentation of an external tool the model already has (Conventional Commits, git bisect) is not. Grounding, stated honestly: findings 9 and 26 closed as "Keep — vendored upstream content is intentional", but both closed over the docs/research/ and docs/notes/ directories, not over skill references/*.md; extending them to scripts.md is this note's inference, not a recorded decision. (An earlier revision added "finding 11 re-decides this content's status anyway" — withdrawn: finding 11 proposes dropping the provenance metadata and validators, not the sourced prose.)

    What remains is unsourced explanatory prose in skill bodies and non-criteria references — roughly 30–60 lines across kyberforge, where apm-install/SKILL.md yields about one clause. Too small to stand alone, and the same class of writing as finding 22 with a larger surface and no sourced-content conflict. Merged into finding 22 under these exemptions; not a separate work item. Safety note established while scoping: validate-provenance.sh is not a pre-push gate (the only .pre-commit-config.yaml reference is check-scope-walkup-sync, over the walk-up port) and validates sources.md structure, never line-level traceability — so trimming sourced prose trips no gate provided frontmatter and sources.md are left intact. Loose end in the fold, stated so it is not lost: finding 22's total is computed over five bin skills (1,018 lines) and its implementation sizing names two agents, neither touching kyberforge — so these 30–60 lines sit outside the scope finding 22 states. Track them there as a separate line item with its own estimate; they are not covered by "bin: strip generic process theatre" as written.

4.3 git and gitea (153 + 93 files, 9,889 + 6,047 lines incl. mirror; source 3,288 + 2,286)

19. Delete the two router skills and two orchestrate agents (309 lines + 195 reference lines). No skill invokes them as a step; they appear only in boundary clauses (AGENTS.md, git-worktrees, gitea-issues, gitea-prs) and as worked examples in agent-audit references, all of which must change in the same commit or skill-size-check fails on the dangling target. Claude Code already routes on descriptions. The chain today is git-workflow step 5 invokes git-orchestrate, whose step 5 invokes git-commits, which runs rtk git commit: three hops. Both agents exceed 900 words; ADR-0020 deliberately sets no agent body gate. Effort S.

    Not proceeding (2026-09-13): premise doesn't hold. There are no separate "router skills" — only two .agent.md files. git-orchestrate is not a dangling boundary-clause reference; it's git-workflow step 5's actual execution backend (documented both directions), so deleting it breaks git-workflow's only execution path rather than tidying an orphan. gitea-orchestrate is intentional per ADR-0011 (agent-facing counterpart for agent callers) even though gitea-workflow doesn't call it. A third, undocumented instance of the same pattern (apm-orchestrate) exists and isn't addressed by this finding. The four boundary-clause locations named above don't actually reference either agent. No changes made. This needs the "short discussion" §7 bucket 2 implies, not a mechanical delete.

20. Collapse git 7 skills to 1; gitea 7 to 2. Git references are man-page restatement: git-log-format.md (242 lines listing %H, %ar), conventional-commits-spec.md (170 lines), worktrees.md (178), merging.md explaining fast-forward. Roughly 60% of the plugin is generic. The genuinely house-specific content fits in about 150 lines: the rtk rule and ADR-0023 exceptions, main/master refusal, --no-verify, the -i --autosquash 2.39.5 trap, --force-with-lease --force-if-includes, bisect exit codes, submodule push ordering, the detached-HEAD worktree trap. Gitea is more legitimately specific (MCP schema quirks: tree_sha, withLines, silent drops on PR create, per_page 20 vs 30, 404 means 403) and splits naturally into gitea-tracker (issues, PRs, labels, milestones) and gitea-repo (branches, files, releases). Risk: one description must carry all trigger phrases; keep a dispatch table at the top of the body. Keep pc-author and pc-run (finding 38). Effort M.

    Refuted as specified (2026-09-14, at HEAD 062ca47). The routing concern is not a risk to mitigate — it is a blocking gate failure.

    What holds: skill counts (git 7 git-* + pc-*, gitea 7); the four named git reference files at their stated sizes (git-log-format.md 242, conventional-commits-spec.md 170, worktrees.md 178; merging.md is 31, among the smallest). "Roughly 60% generic" holds at the top of its range — two independent methods give 54–60%. Gitea being "more legitimately specific" holds and is understated: gitea is ~72% house-specific, the inverse of git, with ~50 MCP quirks beyond the five named (no method:"close" on issue_write; draft:true is literally a "WIP:" title prefix; no update tool for releases exists at all; replace_labels clears unlisted labels; org-label methods take org not owner). Note commit 6cfc357 (finding 13) touched none of the four named files, so its trim does not deflate this evidence.

    The 150-line target fails on the finding's own arithmetic. 60% generic of 1,891 non-sources.md lines leaves 756 house-specific; an independent full read puts the floor at ~918. Off by 5–6×. The house-specific list is also not exhaustive — it misses the rest of the ADR-0023 bare-git exceptions (~23 sites across nine files, which collapse to about ten distinct documented reasons, not one per site: the four git log -L lines share one reason, the four --word-diff lines another, the two git diff --name-* lines a third — the genuinely distinct ones include git branch --list's phantom * line, stash pop swallowing the conflict report, stash list printing No stashes where git prints nothing, and the inner $(git config remote.origin.url) substitution, where output rewriting would poison a remote URL), a second version trap (worktree add --orphan needs 2.42+, exits 129 on 2.39.5), commit-template.md (66 lines, wholly house), three specified JSON result shapes across the six skills that carry an output section (git-commits/SKILL.md:54, git-remotes:48, git-branches:61) plus the request schema in git-branches/references/orchestrator-contract.md, and every cross-skill dispatch clause. Conversely one item on the list is misfiled: bisect exit codes restate git bisect run's own docs (bisect.md is ~97% generic).

    Git 7→1 is uncommittable. Measured against skill-size-check's FAIL tiers: description 1,950 chars = 4.9× the 400 ceiling, body 3,381 words = 3.8× the 900 ceiling, and the plugin is already at 492 of 500 whole-file lines. The finding's own mitigation — "keep a dispatch table at the top of the body" — adds body words to a budget already 3.8× over, and ADR-0020 makes stating the same trigger in two registers a FAIL in its own right. The smallest existing git description is 214 chars for one domain.

    Gitea 7→2 fails the same gate and puts a seam through the commonest workflow. Both halves FAIL the description ceiling: gitea-tracker (issues + PRs + labels/milestones) sums to 991 chars, gitea-repo (branches + files + releases) to 989 — 2.5× the 400 ceiling, measured as skill-size-check's description_value() measures it (YAML-folded, whitespace-collapsed). The proposal also silently drops gitea-workflow, a seventh skill it never places, so "7→2" is really 7→2-plus-a-deletion. gitea-repo would carry 20 of 32 MCP tools across three unrelated families. And the structural objection: the split puts a hard cross-skill boundary through the commonest real workflow — edit-a-file-then-open-a-PR lands gitea-files and gitea-prs on opposite sides of the tracker/repo seam, forcing the same duplicate-or-reach-across choice ADR-0011 rejected the 5-skill option for, at a different seam. What this is not: blocked by ADR-0011's reasoning. An earlier revision argued that ADR-0011 rejected a 5-skill split and gitea-tracker "bundles strictly more", so it is rejected a fortiori — withdrawn, the premise is false. ADR-0011's stated reason is that bundling labels under gitea-issues "forc[es] gitea-prs to either duplicate the guide or reach into gitea-issues' references/ — breaking the self-contained skill boundary": an objection to a boundary being crossed, not to bundle size. gitea-tracker puts issues, PRs, labels and milestones in one skill, so there is no boundary to cross and no guide to duplicate. What remains of ADR-0011 here is procedural: reversing the recorded 7-skill split needs a superseding ADR. Merging concatenates; it does not compress.

    Interaction with rejected finding 19, unacknowledged: collapsing git to one skill absorbs git-workflow itself — one of the seven — so its 8-row Domains table would route to itself, and leaves git-orchestrate a dispatcher with exactly one target, its contract vacuous. Finding 19 was rejected for doing less than this, mechanically.

    Blast radius if ever revisited: 68 backticked references to git skill names, 99 to gitea names under plugins/. Only the ones in a SKILL.md are boundary targets skill-size-check resolves and FAILs on if dangling — its files: regex is ^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$, so it opens nothing else — and that is 35 of the 68 git mentions and 26 of the 99 gitea ones. The remaining 33 and 73 live in references/*.md, the two orchestrate agents (10 and 23 on their own), the plugin READMEs, kyberforge's audit and author references, and two validate.sh copies — none of which this gate opens: they still have to be rewritten by hand, but they fail no hook. Plus AGENTS.md:16,18, README.md:21-22, CONTEXT.md:168 (uses gitea-prs as the naming exemplar), architecture.md:34 (uses git-branches vs gitea-branches as the canonical boundary example), and ADRs 0011, 0020, 0021, 0022, 0023. Two false alarms not worth chasing: tests/test-check-rtk-prefix.sh:97 reads from a pinned historical SHA, and scripts/check-rtk-prefix.sh's mention is in a comment.

    Salvageable independently, ~230 lines: conventional-commits-spec.md (~98% generic) and bisect.md (~97%) are the only two files where the generic-restatement thesis fully holds — reduce each to a pointer plus the house delta. Also worth a finding-13-style trim-in-place: the issue-vs-PR disambiguation duplicated across 4 gitea files. Neither needs a merge.

21. Delete config.example.json / .claude/plugins/git/config.json. Read by two steps, written by nothing. Default to GitHub Flow with the existing develop / release/* inference. Effort S.

    Done (2026-09-12): see commit f5e4d0d. Deleted plugins/git/config.example.json (the runtime .claude/plugins/git/config.json was never a tracked file). Removed the config-read step from git-orchestrate's Process and from git-branches' Step 1, leaving the existing default-inference logic (GitHub Flow, with Gitflow inferred from a develop/release/* branch) as the sole path; updated git-workflow's description of the orchestrator's behaviour to match. Dropped the now-dangling applied_config field from git-orchestrate's output shape and the config.example.json example from docs/spec/architecture.md.

4.4 bin, core, lint (88 + 49 + 31 files incl. mirror)

22. bin: strip generic process theatre. write-docs is 109 lines, mostly form-filling sections plus a 15-line source provenance block; its rules fit in 25 lines. tdd is about 70% textbook (RED/GREEN diagram, "good tests are integration-style", five thin references restating textbook design advice). diagnose 40%, prototype 50% (pixel-level UI switcher spec), grill-with-docs 35%. Keep the opinionated parts: "no horizontal slicing", "no phase 2 without a loop", [DEBUG-xxxx] tags, "never infer the output path", the triage state machine. Effort M.

    Verified (2026-09-14, at HEAD 062ca47): percentages inflated 3–4×, target set wrong, but a real and better defect found. This finding also now carries finding 18's re-scoped remainder (unsourced explanatory prose only — audit criteria, assets/templates/ and sourced spec restatement are exempt; see finding 18).

    Corrected percentages, by a stated method (a line counts generic only if it states a general SE principle with no repo-specific term, no named house convention, and would survive unchanged in any textbook): diagnose ~10–15%, not 40%. prototype ~13%, not 50% — and its ?variant= switcher spec is a prescriptive house convention (floating bar, arrow keys, NODE_ENV gating), not theatre. grill-with-docs ~10%, not 35%. tdd ~25% in the body, ~53% only at directory scope, not 70%. On the "RED/GREEN diagram" the finding names for deletion: tdd/SKILL.md has three diagrams, so the name is ambiguous. The horizontal-vs-vertical block (:36-46, whose own rows are labelled RED:/GREEN:) is the clearest statement of the skill's central opinion and should stay; the two literal RED:/GREEN: loop blocks at :71-74 and :82-85 are what the finding most plausibly means, and those two are textbook and go — eight lines with their fences. So the rebuttal stands only for the horizontal-vs-vertical block; it is an eight-line cut either way, not a case against the skill's one original diagram. write-docs is exactly 109 lines ✓, but "its rules fit in 25 lines" is wrong — the Process section alone is 17 lines of real content; floor is ~55–60.

    Two of five keep-list items name skills this finding never targets — "never infer the output path" is research/SKILL.md:25, the triage state machine is in triage. And the target set does not match the repo's own over-budget list: skill-size-check flags six bin skills; this finding names two that pass clean (prototype, grill-with-docs) and misses three that are over — improve-codebase-architecture (730w + 316-char desc), research (703w), triage (712w).

    The real defect, which "form-filling sections" understates: write-docs is 54% restatement. 431 of the 801 body words the gate counts (skill-size-check reports 801; the 775 an earlier revision used omits the heading words the gate includes). Constraints (126w), When-to-use (110w), Failure handling (104w) and Self-check (91w) each restate the Process section or the description. Measured claim by claim, the repetition is wider than "four claims four times": the Reader-Testing scoping rule appears five times (lines 63/80/88/96/107); file approval before reading four (58/68/93/103); the delta summary four (62/78/87/106); stage-skip logging four (59/72/94/104); "every claim traceable, never invent behaviour" four (34/57/101/102); show-the-full-section-before-gating three (60/76/105). contract.md:119 explicitly forbids this: "Exclude: Restatements of the description — it is already in context." It is also the corpus's only outlier frontmatter — the sole SKILL.md of the 39 real skills carrying when:, updated: or source: (44 files are named SKILL.md under plugins/; 1 is a template under skill-author/assets/templates/ and 4 are vendored under kyberforge/docs/research/examples/skill-write/, the same 39 architecture.md:82 states).

    Realistic total ~150–180 lines of 1,018 (15–18%), itemised so it adds up: tdd's three textbook references 74 lines (refactoring.md 10 — a Fowler smell list; deep-modules.md 33 — self-declared "From 'A Philosophy of Software Design'"; interface-design.md 31 — generic DI advice), where improve-codebase-architecture already carries richer house-specific treatments of both concepts; write-docs 109 → ~58, so ~51; tdd's body at ~25% generic, ~25; diagnose ~15. That sums to ~165. The three textbook references are ~45% of the cut, not the ~75% an earlier revision claimed — 74 of ~165. prototype and grill-with-docs contribute nothing, per the scope recommendation below, and finding 18's folded kyberforge remainder (30–60 lines) sits outside this 1,018-line denominator.

    Coupling — the important caution. This corpus has already been through two trim passes, and the last one broke two of these five targets the same way. PR #129 (598a7c3) records: "prototype and vale-config deleted rules outright that survived nowhere." This finding proposes redoing that operation on prototype and diagnose. Recommend dropping prototype and grill-with-docs from scope entirely — both pass every gate and both have prior-regression history. Also: deleting a references/*.md named in a body is a hard ERROR (skill-size-check.sh:1265), so tdd's reference deletions and its SKILL.md relinks must land in one commit; improve-codebase-architecture/SKILL.md:77,79 hard-name grill-with-docs's context-format.md and adr-format.md by path, so neither can be renamed; and shrinking write-docs falsifies live comments at skill-size-check.sh:64,596, tests/test-adr0020-targets.sh:592 and architecture.md:82. Unlike finding 23's caveman/zoom-out, none of these five is cited as a convention exemplar anywhere.

    Sizing if implemented: two parallelizable agents over disjoint files — A on write-docs (self-contained, no references), B on tdd (reference deletion + same-commit relink, ERROR-gated, cannot be split). diagnose is ~15 lines, too small for its own agent.

23. bin: merge grill-me into grill-with-docs. grill-me is 16 lines and a subset of the docs flow; grill-with-docs creates CONTEXT.md when missing, so the merged skill needs a no-write opt-out. caveman (50 lines) and zoom-out (9) are hand-invoked prompts rather than workflow skills; they are also the repo's disable-model-invocation exemplars in CONTEXT.md, contract.md, ADR-0020, ADR-0021, and gates.md, and install.sh has no path for ~/.claude/commands/, so moving them means picking a new exemplar. improve-codebase-architecture defines its glossary twice (inline and in language.md; the README documents the split as intentional). Effort S.

24. core: provider-adapter-author is a 1,200-line wrapper around one instruction ("replace duplicated lines with @AGENTS.md, keep provider-specific lines"): a 496-line validator with a 519-line bats suite for a check that is a grep. agentsmd-author already calls agentsmd-audit as mandatory closeout, and both route to provider-adapter-author in boundary clauses that must change with it. Target: one agentsmd skill with an audit mode, adapter conversion as a step, validator about 40 lines. Needs an ADR-0012 revisit. Effort L.

    Refuted (2026-09-14, at HEAD 062ca47). Not deferred — the target fails the repo's own gate before any judgment call is reached, so the ADR-0012 §8 question is moot for this finding.

    The merge is arithmetically impossible as specified. Body word counts: agentsmd-author 485 + agentsmd-audit 361 + provider-adapter-author 514 = 1,360 words against BODY_MAX_WORDS=900 (ADR-0020 hard FAIL). Descriptions: 251 + 275 + 280 = 806 chars into a field capped at 400. Relocating the overflow into references/ is PR #129's named anti-goal, and issue #117 records that references/ is where neither the size gate nor Vale looks.

    Both factual anchors describe a validator that no longer exists. scripts/validate-adapter.sh was 141 lines at birth (6fd6876) and in that form was approximately a grep — which is why it shipped two recorded defects: a8cd5e8 (a UTF-8 BOM hid the import line, so a CLAUDE.md whose first line was @AGENTS.md failed with "no reference to AGENTS.md" and was told to add the line already in front of it) and issue #115 (c59e4bf: the --no-import-syntax flag was a proven no-op — "both branches reduce to the same expression"). 141 → 496 is the fix for those. "Validator about 40 lines" targets below the version whose defects are on the record. Line counts otherwise exact: validator 496, bats 519 — but "1,200-line wrapper" is 1,164, of which the wrapper is 52; 1,015 are validator + tests (1,071 with the two READMEs, 28 each), and the remaining 41 are references/.

    Coverage given up by a 40-line validator: ~67% of the 42-test suite. 20 tests sit under explicit Q1–Q5 headers — Q1 inert fenced/indented/HTML-comment regions (5), Q2 valid-UTF-8-but-not-UTF-8 encodings (4), Q3 exists-but-unreadable (1), Q4 path resolution (4), Q5 pointer-vs-mention (6); 8 more are hardening, so 28 of 42. Every one was proven non-vacuous by deliberate mutation under PR #129. Representative guards: a ```-fenced @AGENTS.md "exited 0"; @NOTAGENTS.md counted as an import for want of a path-segment boundary; "AGENTS.md" in ln passed "Do NOT read AGENTS.md; it is obsolete."; BOM-less UTF-16LE decodes as valid UTF-8 and produced a false diagnosis; exit 2/3 split from 1 "because the skill's closeout tells the agent to fix every non-zero exit by editing the provider file, which for a mistyped flag edits the wrong file forever".

    The self-containment constraint does not support this finding the way it supports 14/15 — there is no cross-skill duplication here to merge away. agentsmd-audit's three scripts share essentially nothing with validate-adapter.sh (no read_text, no BOM handling, no NUL check; they exit 1 on usage errors). Merging would expose that they are unhardened — costing lines, not saving them.

    Two further blockers if it were ever revisited: the merge dissolves agentsmd-author's standing prohibition "Never write to a provider file yourself, in any circumstance" (SKILL.md:21), a hazard c59e4bf closed after the validator's own size-FAIL remediation text "actively invited the prohibited edit"; and skill-size-check.sh:121 + tests/test-skill-size-check.sh:729 both cite a8cd5e8's exit-2 split as precedent for their own, so deleting it orphans two live cross-references.

25. lint: delete the lint-runner agent. Its body is "call vale-run, reformat output", which --output=JSON already gives; it exists for backends that do not exist. It is the example boundary clause in three agent-author templates and ADR-0016, so those need a new example. About 40% of vale-config is install tables and settings lists the model can fetch from vale.sh. Keep the house-verified matrices (E100/E201, Packages below glob, frontmatter, ignore paths). lint/docs/research/docs/vale/ overlaps the skill's own references by about two thirds. Effort S.

5. Prose and docs (9,600 lines, 109,000 words outside plugins)

26. Move or delete docs/research/ and docs/notes/ (4,500 lines, 47% of prose words). Six of eleven research files are linked only from each other; they are self-described session audit trails, agendas, and a "temporary build reference". docs/notes/factory-research-gaps-conflicts.md says "Status: Superseded"; factory-integration-decisions.md says "Complete" and its decisions already live in ADRs, yet AGENTS.md tells every session to read it. archive/team-self-organisation-sprint-brief.md (3,400 words) is unrelated to this repo. Archive or delete; drop the three AGENTS.md pointers. Moving CONTROLS.md to docs/spec/ means updating its literal path in nine or more files including the deployed governance.md. Effort S.

    Decision (2026-09-12): Keep. Same reasoning as finding 9 — these docs are intentional context for sourced work. Not proceeding.

27. Four governance documents say one thing. core/instructions/governance.md (949 words, always-on), docs/ai-constitution.md (2,906), docs/wiki/HUMANS.md (1,413), CONTROLS.md (1,224), with near-identical preambles and, in three of the four, a "what this file does not govern" block pointing at the others. The constitution repeats one of its own principle lead sentences. Keep governance.md as the operative file, trimmed to about 50 lines (drop the classification table that repeats the bullets above it, the footer, the non-governance block). Dedupe the constitution by about 20%. Effort M.

    Refuted as framed (2026-09-14, at HEAD 062ca47). All four word counts are exact — the first finding in this audit whose figures survive checking — and everything built on them fails.

    "Four documents say one thing" misreads audience separation as duplication. They are one principle set projected onto four execution surfaces, and each projection is load-bearing: governance.md is imperative to the model and injected into every session; HUMANS.md is imperative to a person on a wiki; CONTROLS.md is a declarative spec for CI tooling; the constitution is the justification layer with citations. Take "secrets never enter AI context": the constitution states it with evidence, governance.md tells the model never to emit one, HUMANS.md tells the person never to paste one, CONTROLS.md specifies the pre-commit hook that catches both when the first two fail. CONTROLS.md:8 names this explicitly — "Agent instructions and human practitioner rules are probabilistic… A control that runs automatically in CI enforces a principle more reliably than any instruction in any file." The three "what this file does not govern" blocks are the seams that keep the four from bleeding together, each pointing at a different file for a different reason. Real overlap is ~15%.

    22% of the finding's word count is not this repo's to edit. docs/wiki is a submodule pointing at a separate Gitea wiki repo, concurrently editable through the web UI. HUMANS.md's 1,413 words are out of scope for any change made here.

    "Drop the classification table" would delete live rules. The table has four rows; only Confidential and Restricted restate the bullets above it. Public and Internal exist nowhere else in the file — dropping it removes the only statement of Internal | Operational data, anonymised logs | Enterprise AI tools only; not consumer/free-tier from always-on agent context, in every project.

    The 50-line target is arithmetically unreachable and contradicts the finding's own keep-list. The file is 82 lines; the three named cuts total 16 lines counting only their own content — the table rows (31–36, 6), the non-governance block (71–76, 6), the footer (79–82, 4) — landing at 66, or at most 23 if each cut also takes its heading, surrounding blanks and the --- rules, landing at 59. Both include the table cut that shouldn't happen. Reaching 50 means cutting ~9–16 more from Hard Prohibitions (18 lines) or Required Behaviours (24), the operative rules the finding says to keep. "Dedupe the constitution by about 20%" overstates by 4× — verifiable duplication is 133 words (4.6%), in two adjacent principle pairs (§5 lines 114/117 byte-identical; §4 lines 89/92), both merge artifacts. §§1–10 are ten distinct domains with near-zero cross-section.

    Any cut to governance.md is a global agent-behaviour change, not a docs edit. Verified chain: scripts/deploy-manifest.sh:21 maps core:.claude/core, and both providers/claude-code/CLAUDE.md and the live ~/.claude/CLAUDE.md carry @~/.claude/core/instructions/governance.md. Repo and deployed copies are byte-identical (6,590 bytes). All 949 words are injected into every session in every project. Needs explicit sign-off on that basis.

    Honest ceiling: 168 words / 17.7% of the file's 949 — the cross-reference scaffolding only: preamble 43 (lines 3–5), non-governance block 77 (71–76), footer 48 (79–82), landing at ~67 lines with no rule loss. (An earlier revision said 47 for the preamble, which is only reachable by counting lines 1–7 — that sweeps in the # glyph and a --- rule as words.) Plus 133 words from the constitution. Not 50 lines, not 20%.

    Two defects the finding missed, both worth fixing independently of it. (1) A live bug: docs/HUMANS.md does not exist — the file is docs/wiki/HUMANS.md. The wrong path appears five times across three files, including the deployed core/instructions/governance.md:82, which is self-inconsistent (line 73 correct, line 82 broken); the other four are CONTROLS.md:5,101,106 and ai-constitution.md:238. (An earlier revision said "four times" while enumerating all five.) Fixed (2026-09-15): all five corrected to docs/wiki/HUMANS.md; the deployed copy under ~/.claude/ is now stale until scripts/install.sh re-runs. (2) The deployed always-on file carries repo-relative pointers that dangle in every project but this one — an agent told to "read it when making decisions not covered here" cannot. That is the substantive question this finding should have asked. The footer is additionally self-referential: governance.md:80 lists the file as compatible with itself.

28. ADRs: 2,740 lines, 72% in eight ADRs over 150 lines. ADR-0020 is 513 lines with a 71-line measurement log as Context; ADR-0017 has 173 lines of amendments against 45 of decision. ADR-0001 is superseded and ADR-0006 moot, both keeping full text below the banner. ADR-0002 is three lines. Truncate superseded ones to the banner, fold amendments into the decision, cap Context at 20 lines, add a 25-line docs/adr/README.md index with status. The rules already live in gates.md; the ADRs need only decision and consequences. Effort M.

    Moved backwards (measured 2026-09-14 over afa7187^..a6434e0): today's ADR-0024 work did the opposite of this finding on every axis, and that is recorded here so it is a known trade rather than a surprise. docs/adr/ went from 23 files / 2,748 lines to 24 / 3,084 — one new ADR (0024, 259 lines) plus amendment and banner text across eleven existing ADRs (0001, 0006, 0011, 0013, 0014, 0015, 0017, 0018, 0019, 0020, 0021 — 87 lines added, 10 removed, net +77), for a total of net +336 lines (+12%). The two ADRs this finding names for truncation both grew below their banners instead: ADR-0001 26 → 27 lines and ADR-0006 22 → 27, each gaining a fresh "as of ADR-0024" paragraph rather than losing the historical body beneath it. ADR-0017 gained a supersession banner while keeping its four amendments in full — the exact shape this finding proposes to fold.

    Not a defect in that work: a supersession has to be recorded somewhere, and an unread stale ADR is worse than a long one. But it does mean the finding's estimate is now conservative and its "truncate superseded ones to the banner" step has more to remove than when it was written — ADR-0001, ADR-0006 and ADR-0017 are all superseded-with-full-body today. State the basis when re-measuring: this is a two-SHA measurement, not a standing count, and further ADR amendments were being written by other sessions while it was taken. Re-derive with git ls-tree -r --name-only <sha> docs/adr before acting on it.

    Verified (2026-09-14, at HEAD 062ca47): as written this finding saves nothing and breaks citations in four files. The size of the saving depends on a convention the finding never states. Truncating ADR-0001 and ADR-0006 to their banners removes 20 lines if the --- separator and its trailing blank are kept (13 + 7), or 24–26 if truncation drops those too, which is the natural edit (15–16 + 9–10). The proposed docs/adr/README.md index costs 25. So the range is +5 to −1 lines — the robust conclusion is that the proposal is a wash, not that it nets +5.

    The finding's headline was accurately measured; it has since gone stale. Current state is 3,118 lines / 24 files. The 2,740 was correct at commit a3e721e (2026-09-09, "docs: retire the META.md guidance ADR-0022 overruled"), an ancestor of HEAD: docs/adr/ there is exactly 2,740 lines across 23 files, exactly 8 ADRs exceed 150 lines, the top-eight share is 71.90% (1,970/2,740 — the finding says 72%), and ADR-0020 is 513 lines. Every headline figure reproduces at that one commit, which rules out coincidence, and across all 67 commits touching docs/adr/ a3e721e is the unique one yielding 2,740 (neighbours: ed8c99e 2,732, a3e721e 2,740, 568ca74 2,747, af80d27 2,748). What moved the numbers is the ADR-0024 wave, already recorded in the note above. Re-derive with git show a3e721e:<path> rather than assuming the figure was invented.

    Today those same figures read: ten ADRs exceed 150 lines, not eight; top-eight share is 68.3%, the over-150 cohort 79.2%. ADR-0020 is 514 lines. Its Context is 72 lines counting the ## Context heading and 71 without — a counting convention, not drift: the section is byte-identical at a3e721e and at HEAD (## Context at :11 through ## Decision at :83), so the finding's 71 and this note's 72 are the same span counted two ways. ADR-0017's "173 amendment lines against 45 of decision" and ADR-0002's three lines are exact.

    "The rules already live in gates.md" is backwards. docs/spec/gates.md:349-352 explicitly declines to restate ADR-0020's numbers: "they live in ADR-0020's Consequences section… Quoting them here would just create a second copy to go stale." gates.md is a consumer of the ADR, not its replacement. The index proposal also contradicts a recorded decision — docs/spec/architecture.md:90: "There is no index file — the directory holds numbered ADRs whose filenames state their decision, so ls docs/adr/ is the index."

    No superseded body can be truncated — every one is quoted by content, not merely cited by number. ADR-0001's body text is quoted verbatim at docs/adr/0015:5,36, and factory-integration-decisions.md:133 lists "Pull-based distribution (ADR-0001)" as settled, a concept living only in its consequences bullets. ADR-0006's version-parity invariant is stated only at 0006:23 and is relied on by 0014:116 and 0024:183-185 — and its banner (17 lines) is already longer than its body (7). ADR-0017's own banner says its diagnosis "is still accurate about how Claude Code's installer works", and ADR-0024 cites its body in eight places. ADR-0002 is only partially superseded and is cited as a design source by a shipped skill.

    Nothing in tests/ or .pre-commit-config.yaml reads docs/adr/ — grep -n "docs/adr" tests/test-adr0020-*.sh returns nothing; the ADR-0020 gate family tests skill-size-check.sh and the embedded resolver copies. Editing ADR prose breaks no gate. The only constraint is citation integrity.

    "Cap Context at 20 lines" would destroy a derivation three scripts depend on. ADR-0020's Context pins base commit f9b919d7e3b, states the summation method and the token approximation, and derives the 2,770 gate from 7.22 chars/word × 20,000 — stating body-only vs whole-file explicitly because conflating them is the defect the ADR exists to stop. Only the four illustrative anecdotes (~42 lines) are trimmable, and those are the argument, not the measurement.

    Honest ceiling ~235 lines (7.5%), and the one real win is not in the finding: delete ADR-0017's four amendments (−173) now that ADR-0024 consequence 7 has restated them in full, re-pointing eight citations. Plus ADR-0001/0006 compressed to banner-plus-one-line (−20) and ADR-0020's anecdotes (−42). No README index. Restate the headline as 79% in ten ADRs.

    The framing question this finding never notices: it proposes reversing a convention the repo just re-affirmed — every banner added by the ADR-0024 work ends with some form of "kept below as the historical record". Is a superseded ADR's body a record or dead weight? Nothing here is mechanical; every proposed cut touches text another file quotes.

29. The same facts are stated in full three or four times. "Edit .apm/, never the mirror": README (2 paragraphs), AGENTS.md (2 paragraphs), architecture.md (2 paragraphs plus the lost-README anecdote), ADR-0017. The apm.lock / SessionStart story: README (11 lines), AGENTS.md, ADR-0018, ADR-0019, gates.md. The offline SKIP= command and the three-stage install each appear three times. Rule: README has the how-to, AGENTS.md has one-line rules with links, architecture.md has mechanics. Effort S.

    Corrected then partially done (2026-09-14): independent re-verification found the "edit .apm/, never the mirror" and apm.lock/SessionStart clusters confirmed but the third overstated — no file documents an offline SKIP= command (the one SKIP=-adjacent mention in gates.md explicitly says a different opt-out "is not SKIP="), and "three-stage install" appears twice, not three times, with no restatement worth trimming. Trimmed the two confirmed clusters: README's "Editing plugin content" and AGENTS.md's "Edit .apm/, never the flat mirror" sections cut to the how-to/one-line-plus-link split the finding itself proposed, full mechanics (the rm -rf behavior and the plugins/kyberforge/hooks/README.md anecdote) staying solely in docs/spec/architecture.md. README's "Keeping the install current" and AGENTS.md's apm.lock bullet trimmed to drop the restated apm outdated/apm update --yes timing narrative, pointing to ADR-0019 as the canonical mechanism instead. No test greps the trimmed wording (checked).

30. LESSONS.md: 41 entries, 2 graduated, about 12 stale. Twelve entries from 2026-05-17 describe a write-skill / write-eval workflow whose skills no longer exist. One entry is open work labelled "Status: neither part landed". The longest eight are 200 to 550-word incident reports. Delete the stale entries, move open work to an issue, cap entries at about 60 words, target 100 lines. Effort S.

    Done (2026-09-12): see commit 629320b on docs/simplification-audit. 255→131 lines, 41→30 entries. Kept 3 of the same-dated entries (RLHF defaults, secrets-rule gap, HITL gap) — judged unrelated to the defunct write-skill/write-eval workflow and still applicable, so 10 deleted rather than 12. The "neither part landed" open-work entry (CONTEXT.md not @imported at session start) was removed rather than filed as an issue — full text preserved in this session's transcript if wanted later.

31. CONTEXT.md: 28 terms, most used only by gates.md, scripts, or tests rather than by skills; two (Preload tax, Skill context contract) are never used outside CONTEXT.md and ADR-0020. The preload-tax entry quotes two dated numbers then says not to quote them. The example dialogue and flagged-ambiguities sections are grill residue. Cut to about 20 one-line terms. Effort S.

    Corrected then done (2026-09-13): see commits 124ce6e and follow-up on docs/simplification-audit. Independent re-verification found "most used only by gates.md/scripts/tests" overstated: 13 of 28 terms are actually referenced from model-facing references/*.md files skills load in normal use (Routing target, Hand-invoked skill, Dispatch body, Near-miss, Thin adapter, Provenance chain, Output profile, apm package, Plugin marketplace, HITL, Skill composition, Delegation discipline, holocron) and were kept untouched. Only the 9 terms confirmed as true orphans were removed after a fresh independent grep: Content mirror, apm-consumed install, Vale audit prefilter, Vacuous green, Management Application, Sycophancy, HOTL, Preload tax, Skill context contract — 28 → 19 terms. Re-counted (2026-09-14, at a6434e0): 18 terms, not 19. The "28 → 19" above is an accurate record of this finding's own commit (124ce6e) and is left standing. 718c79a then removed a twentieth-to-nineteenth entry this finding never touched: the standalone Plugin term, folded into apm package when ADR-0024 made "plugin" and "apm package" the same thing. Counted as bolded term entries between ## Language and ## Relationships in CONTEXT.md: 19 at 124ce6e, 18 at 718c79a and unchanged at a6434e0. The finding's own target ("about 20 one-line terms") is met either way. The preload-tax self-contradiction (quotes 23,427/10,478-char figures then says not to quote either) was confirmed verbatim and resolved by the entry's own deletion. The "example dialogue" and "flagged ambiguities" sections were found to be mandated by grill-with-docs/references/context-format.md's template spec, not grill residue — left untouched, except one dangling bolded cross-reference to the now-deleted "Preload tax" term in a Flagged-ambiguities line, which was unbolded/de-referenced in place (the ambiguity resolution itself still holds without a defined glossary entry to point at).

32. Structure is described three ways (README layout table, architecture.md plugin table, AGENTS.md structure bullets), and VISION.md carries a 35-line stack spec for a product that lives in another repo. One layout table in README; architecture.md keeps mechanics only; VISION drops the stack detail. Effort S.

    Premise corrected, residual done (2026-09-14). Both halves were inflated; most of the proposed split already existed.

    • "Described three ways" overstates it. docs/spec/architecture.md had already been differentiated, and says so in the file: its plugin table is prefaced "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 plugin ships today, read plugins/<name>/.apm/skills/ or the plugin list in README.md." That is the split this finding proposes, already implemented and self-documenting. README holds a path→contents table plus the six-plugin inventory; architecture.md holds a plugin→scope routing table that delegates inventory to README. AGENTS.md's ## Structure was two bullets, not a third description.
    • "A 35-line stack spec" counted the wrong thing. docs/VISION.md is 71 lines total. The whole ## Long-term: Management Application section is 35 lines; the stack detail inside it was 5 lines (Stack, Stack rationale, Deployment, Hosting, Users).

    The one genuine duplicate was AGENTS.md's plugins/ bullet restating apm-install mechanics owned by docs/spec/architecture.md:22 and README.md:55. Done: that section cut to two actionable one-liners plus pointers to the README layout table and architecture.md — keeping the load-bearing session rule (.claude/skills/ and .claude/agents/ are install output, never edit them), which finding 29's earlier trim had left the Structure bullet carrying implicitly. In VISION.md, the stack/framework/deployment lines were replaced with a one-line scope statement deferring those choices to that product's own repo, and the Phase 1 "Mobile/desktop (Phase 3)" line was dropped as an intra-file duplicate of the Phase 3 section. Net 6 lines (f91babc: 2 files changed, 5 insertions, 11 deletions); README and architecture.md untouched, both already correct.

6. Distribution, versioning, and session startup

Not covered by the area audits above; found on a final sweep of the root config and install pipeline. The install pipeline itself (scripts/install.sh 55 lines, deploy-manifest.sh 24, statusline 109) is fine and needs nothing.

33. Every plugin version lives in four places (five for kyberforge), plus one per skill. plugins/<name>/apm.yml, two generated plugin.json files, the root apm.yml packages list, the executables.allow key (kyberforge#1.6.2), and a metadata.version in all 39 SKILL.md files (ADR-0022) that nothing consumes and that drifts freely (gitea skills sit at five different values). Repo tags (v2.0.1) follow a third scheme that the declared tagPattern: v{version} can never match under per_package versioning. ADR-0006, ADR-0022, check-executables-allow-sync, skill-frontmatter, and apm pack --check-versions all exist to police this. Proposal: one version per plugin in its apm.yml; drop metadata.version and ADR-0022; let apm pack derive the rest. Effort M.

    Partially advanced (2026-09-14): see commit 718c79a on docs/simplification-audit. Two of the four locations per plugin are gone: the twelve generated plugin.json manifests (plugins/*/.claude-plugin/ and plugins/*/.github/plugin/) were deleted with the mirror. ADR-0006 needed no action — it was already moot and governed only those two now-deleted manifests, so no version bumps were required by the change. Not closed. Still outstanding: plugins/<name>/apm.yml, the root apm.yml packages list, the executables.allow pin, and metadata.version in all 39 SKILL.md files (still unconsumed, still drifting), plus ADR-0022 and the v{version} tagPattern mismatch. Verified (2026-09-14, at HEAD 062ca47): headline wrong, central claim inverted — and it contains the one zero-risk, empirically-verified win in this audit.

    Do this regardless of anything else: delete the six root apm.yml packages[].version lines. Tested in an isolated scratch copy (repo untouched): setting plugins/lint/apm.yml to 9.9.9 while root says 1.1.7 passes apm pack --check-versions --check-clean with exit 0, reports [matches], and emits 1.1.7 — the curator entry wins (output_mappers.py:163-171). Deleting the root version: line entirely leaves marketplace.json byte-unchanged (builder._fetch_local_metadata reads the plugin's own apm.yml). All six are removable with zero output diff. This is unpoliced duplication that silently ships the wrong number on drift. Effort S, no decision needed.

    Corrected headline: two hand-maintained per-plugin locations (three for kyberforge), not four — the audit's own "already done" note records the plugin.json deletion but never fixed the headline. Gitea skills drift across six values (0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.1.6, 1.0.1), not five. 39 SKILL.md files ✓. The 0.4.6 duplication between root version: and marketplace.version: is forced by apm, not a repo choice — deleting marketplace.version makes --check-clean go dirty.

    "Nothing consumes metadata.version" is false twice over. Machine enforcers: scripts/skill-size-check.sh:1365-1374 and skill-audit/scripts/validate.sh:1292-1332, both FAIL tier, the latter citing ADR-0022 by name, with four dedicated bats cases and ~10 fixture generators baking the field in. Instruction-level consumers: skill-author/SKILL.md:60 (bump minor on create, patch on improve), create.md:89,101, improve.md:82, and forge/SKILL.md:54 + references/version-bump.md. apm parses it for Chatmode/Instruction/Context primitives but not for Skills, and never emits it. Precise statement: the value is written, shape-validated, and never read downstream — it is an agent-visible revision counter, and the drift table shows the counter is not being maintained.

    ADR-0022 already considered and rejected dropping the field, on the grounds that skill-author depends on it to decide whether a pass owes a bump — a rationale still live today. Superseding costs: rewrite skill-author's bump rule, delete forge's version-bump route premise, strip two scripts, delete four bats cases, fix ~10 fixture generators, edit the scaffold template, update gates.md:97 — and re-open the "is this field present here?" question issue #127 closed, just from the other side. Recommendation: keep it and fix the actual defect, which is that nobody bumps it. Either enforce the bump in the skill-author workflow or declare the values advisory in the ADR.

    The tagPattern claim is refuted — inert, not broken. Under versioning.strategy: per_package, apm never reads it: version_check.py:262 gates on strategy == "tag_pattern", and builder.py:641,781 are reachable only for remote source entries, while all six packages here are local paths. The v1.0.0/v2.0.0/v2.0.1 tags are not "a third scheme" — they are the .pre-commit-hooks.yaml external-consumer contract tags from finding 36, a different axis entirely. Latent risk only: if dependencies.apm ever gains ref: pins, tagPattern goes live against per-package tags that do not exist.

    Also: executables.allow should be kept — it is version-keyed by apm's design and check-executables-allow-sync guards a real silent failure (ADR-0019). And ADR-0006's ADR-0024 amendment asserting "apm.yml's version: is the only version field a plugin has" is inaccurate while root packages[].version exists — fixed by the deletion above.

34. The SessionStart hook auto-updates the install on every startup. check-apm-current.sh runs apm outdated (network, 60 s timeout) and then apm update --yes (300 s timeout) at every session start, rewriting apm.lock.yaml. That is why the lock file is dirty at the start of this session and why AGENTS.md has to explain "commit or discard it deliberately". It is a 60-line script with a 368-line test, an ADR (0019), the executables.allow pin, and a sync hook behind it. For a repo that is its own source, the update belongs in install.sh or a manual apm update, not in session startup. Effort S to remove; the design question is whether auto-update at startup is wanted at all.

    Refuted (2026-09-14, at HEAD 062ca47). The evidence is inverted: the finding cites as proof of over-eagerness a session in which the mechanism did not fire, and the observed state is the exact silent failure ADR-0019 exists to prevent.

    The update is conditional, not unconditional. check-apm-current.sh:42-43 captures apm outdated and exit 0s unless the output matches outdated dependenc(y|ies) found. The staleness test is a real SHA comparison (apm_cli/commands/outdated.py, git-branch branch) of the lockfile's resolved_commit against the remote tip. On a current install the cost is one ~0.8 s check and no lock rewrite — confirmed by timed probe. hooks.json also declares "matcher": "startup" only, so --resume/--continue/post-compact sessions never fire it (ADR-0019 sub-decision 3).

    "That is why the lock file is dirty at the start of this session" is false. The session-start git status reads (clean) and apm.lock.yaml was unmodified. Meanwhile apm outdated reports 6 outdated dependencies — the install sits 9 commits behind main, right now, with nothing reporting it. The hook did not run.

    ADR-0019 pre-answers the finding's core argument, Context ¶3: "Refreshing on push assumes the person who pushes is the person who goes stale, which is backwards: your install goes stale when someone else merges, and a push of your own is neither necessary nor sufficient for it to have happened." "For a repo that is its own source" conflates authoring source with installed content — under ADR-0018 this repo consumes its own plugins as unpinned git refs against the remote default branch, so a session loads main, never the working tree (AGENTS.md states this). Being its own source makes it more exposed, not less: it is the only consumer whose authors routinely hold uninstalled edits and may assume they are live. The ADR also pre-rejects a manual apm update (sub-decision 1), accepting the dirty-lock cost deliberately — the AGENTS.md line the finding reads as evidence of a problem is the ADR's documented consequence.

    scripts/install.sh has no apm step at all — it installs git hooks and deploys providers/claude-code/, and runs once at setup, so it structurally cannot address staleness caused by someone else merging later. The proposed destination does not exist. Footprint is also understated: six files, 1,096 lines. And the claimed saving largely evaporates — deleting the executables.allow block turns apm's trust gate off for all six packages, a security regression ADR-0019 deliberately closed, so it must be retained in some form and check-executables-allow-sync (222 + 243) only becomes droppable if reduced to a non-version-keyed form.

    Recommendation: keep the hook. Cost is 0.8 s on a current install; offline it fails fast (0.81 s, status unknown, grep misses, exit 0 — the 60 s timeout is a bound, not a latency). The benefit guards a failure that is silent by construction and that the repo is exhibiting right now.

    Two things worth fixing, neither of which is removal. (1) ADR-0019's ~10.4 s refresh figure is now ~18 s measured warm on a LAN remote — it is quoted in the timeout: 380 invariant reasoning and understates by 75%. (2) An undocumented branch hazard, and the strongest argument the finding could have made: the hook resolves against the remote default branch, so on a feature branch that changes plugins/, an auto-refresh reinstalls main's version over it. Reproduced — running apm update today re-installs main's plugins/bin/.mcp.json and writes back the obsidian MCP server that commit c96ca9c removed on this branch. That deserves a line in ADR-0019's Consequences; the proportionate fix if it bites is ~3 lines skipping the refresh when HEAD is not the default branch.

35. Outputs and packages for consumers that do not exist. The codex output profile generates .agents/plugins/marketplace.json (95 lines) although Codex is not a supported consumer. The mattpocock-skills remote package entry is the only reason apm-marketplace-check needs the network, and its pin is advanced by hand (ADR-0015). The .github/plugin/marketplace.json mirror is a legacy path (finding 2). Removing all three leaves one generated marketplace manifest (the per-plugin plugin.json pairs remain) and no network-dependent hook. Effort S.

    Done (2026-09-13): see commit 568ca74 on docs/simplification-audit. Removed the codex output profile from root apm.yml and its compiled .agents/plugins/marketplace.json (95 lines), and the mattpocock-skills remote package entry — the only remote marketplace entry, so apm-marketplace-check and apm-pack-check-clean no longer need network access at all. Updated README.md, AGENTS.md, docs/spec/gates.md, and docs/spec/architecture.md accordingly; added one-line superseded/updated notes to ADR-0015 and ADR-0021. Left .github/plugin/marketplace.json untouched — that's the Copilot legacy-path question in finding 2/§8, out of scope here; only re-ran the sync script to keep it consistent. apm.lock.yaml unaffected (marketplace.packages[] isn't part of the lockfile). Verified via apm install, apm pack --marketplace=claude --check-versions, and all four affected pre-push hooks. Both carve-outs overtaken the next day (2026-09-14, verified at a6434e0): neither survives, and the finding's headline outcome — "one generated marketplace manifest, no network-dependent hook" — is now literally true rather than approximately so.

    • "The per-plugin plugin.json pairs remain" is void. All twelve were deleted in 718c79a (ADR-0024); git ls-files '*plugin.json' returns nothing. The only tracked manifest left anywhere is the root .claude-plugin/marketplace.json. (The root .claude-plugin/plugin.json beside it is untracked local apm pack output, ignored at .gitignore:59.)
    • "Left .github/plugin/marketplace.json untouched … out of scope here" is void the same day: 0dffff3 deleted it under finding 2c, along with scripts/sync-marketplace-mirror.sh and its test. The "only re-ran the sync script to keep it consistent" step above refers to sync-plugin-content.sh, itself deleted in 718c79a.

36. The release-tag mechanism guards an external contract with no known consumer. .pre-commit-hooks.yaml exports three hooks for other repos to pin by rev: <tag>. check-release-needed (242 lines + 442 test), test-vale-hooks-consumer (270 lines), ADR-0014, and three tags exist to serve that. If no other repo pins these hooks today, the whole mechanism can be deferred until one does. Effort S.

    Verified (2026-09-14, at HEAD 062ca47): premise holds — the only premise in this audit to survive verification, though not the finding whole: test-vale-hooks-consumer.sh is 272 lines, not 270. Not yet decided; deferred by the human on 2026-09-14.

    Exact: three exported hooks (kyberforge-vale-audit-skill, kyberforge-vale-audit-agent, kyberforge-skill-size-check), check-release-needed.sh 242, its test 442, three tags (v1.0.0, v2.0.0, v2.0.1). test-vale-hooks-consumer.sh is 272 lines, not 270.

    Consumer evidence: none found, near-conclusive for this instance. The Gitea instance holds exactly two repos; the other (Defame1297/ansible-homelab-mono) pins seven hook repos in its .pre-commit-config.yaml — conventional-pre-commit, gitleaks, jumanjihouse, yamllint, ansible-lint, pre-commit/pre-commit-hooks, plus local and meta — none referencing this repo or any of the three hook ids. All 13 commits touching the mechanism are self-authored fixes found by this repo's own tests; none traces to a reported external breakage. test-vale-hooks-consumer.sh builds a synthetic consumer in mktemp — a genuine regression test that caught a genuine shipped bug (LESSONS.md:101), simulating nobody who exists. Off-instance clones remain undeterminable. ADR-0024 already ruled this standard sufficient four commits earlier, deleting the 20,000-line mirror as "maintained for an audience of zero".

    The README documents a contradictory contract — "For external consumers" says consume through apm, "apm is the only supported install path", and never mentions .pre-commit-hooks.yaml or rev: pinning.

    The mechanism is already failing at its one job. scripts/skill-size-check.sh changed on origin/main in 598a7c3 after v2.0.1, with no tag cut since — a consumer pinning rev: v2.0.1 gets a stale hook today. The gate cannot fire: it is wholly gated on PRE_COMMIT_REMOTE_BRANCH == refs/heads/main, and PRs merge through Gitea's server-side button, which sets nothing. The script's own header documents this as needing "a server-side CI job, which this repo does not have yet".

    The premise that it serves only the external contract holds — all three exported hooks are separately wired internally via repo: local (.pre-commit-config.yaml:216,249,258), so deleting the export costs zero internal lint coverage.

    Correction to the finding: ADR-0014 gets amended, not retired. Its primary decision — moving Vale config/styles/wrapper into skill-audit/assets/vale/ and agent-audit/assets/vale/, self-locating from ${BASH_SOURCE[0]} so the prefilter works at runtime in any repo installing kyberforge — is independent of the release-tag mechanism and stands on its own. Only the .pre-commit-hooks.yaml half and the tag consequence retire.

    Removal is ~1,000 lines and mechanical: .pre-commit-hooks.yaml, check-release-needed.sh, both tests, the hook block at .pre-commit-config.yaml:194-201, the gates.md:83 row and its "External consumers" section. Tags are inert and can stay. The one real loss: test-vale-hooks-consumer.sh is the sole test exercising the entry-resolution path that once shipped broken — it goes only with the manifest, never while it stays. Reversal cost is bounded provided ADR-0014 and LESSONS.md:101,105 are kept: they preserve the entry[0]-only constraint that took three review rounds to find.

37. Two .mcp.json files declare an Obsidian vault server over docs/ (root and plugins/bin/; the other five plugin .mcp.json files are empty stubs), while AGENTS.md forbids using an external memory system for this repo. If the Obsidian tools are unused, drop both and the reinject_mcp_servers explanation in the bin README; the bin plugin.json pair regenerates. Effort S.

    Not proceeding (2026-09-13): premise doesn't hold. The server exposes the repo's own git-tracked docs/ folder — not an external/off-repo store — so it isn't the "external memory system" AGENTS.md's rule targets. It was deliberately added and versioned (3 commits), is documented as current intended behavior in both READMEs, and ADR-0018 uses it as its only concrete worked example of apm's MCP-dependency propagation mechanism actually working. No skill invokes the Obsidian tools as a workflow step, but that alone doesn't make the config dead. No changes made; recommend a human confirm whether the vault tooling is still wanted before removing it. Confirmed and done (2026-09-14): the human confirmed the vault tooling is not wanted — remove it entirely. All seven .mcp.json files deleted (the six plugin-root files and the repo-root one), and the repo-root path added to .gitignore so a local apm run cannot recreate it as tracked content. The bin README's reinject_mcp_servers explanation goes with it; the plugin.json pair the finding expected to regenerate no longer exists (deleted in 718c79a, finding 7).

    What made this urgent is the substantive discovery, not the tidying: deleting the per-plugin plugin.json manifests in 718c79a had already broken MCP propagation silently. apm_cli/deps/plugin_parser.py maps a plugin-root .mcp.json → .apm/.mcp.json, and that code path runs only for marketplace plugins — with no manifest, apm never reads the file. plugins/bin/apm.yml declares dependencies.mcp: [], so the supported mechanism was never used either. Proved on ref-pinned consumer clones: at the parent commit a consumer gets an obsidian server, at HEAD it gets none, and on upgrade apm prints Removed stale MCP server 'obsidian' from .mcp.json — which would in time have stripped the server from this repo's own tracked .mcp.json once the lock re-resolved. Deleting the files makes the intent match the behaviour instead of leaving a config that silently does nothing.

38. pc-author / pc-run (689 lines) carry generic pre-commit documentation. hooks-by-language.md (128 lines) and failure-patterns.md (133) restate pre-commit.com. Keep the skills, trim to the house-specific rules. Effort S.

    Corrected then done (2026-09-13): see commit a622200 on docs/simplification-audit. Independent re-verification found the 689-line figure overstated (actual combined size 598 lines) and the realistic cut smaller than a rewrite (~60-85 lines, concentrated in the two named reference files, not the SKILL.md files or the four short flow files, which are house-specific gates rather than restatement). Landed within that range: hooks-by-language.md 128 → 92 lines (collapsed six per-language tables repeating the same repo/rev/rationale into one shared-repo table plus a small other-repos table); failure-patterns.md 133 → 109 lines (removed generic SSH/proxy and shellcheck SC-code restatement, compressed generic schema-error bullets). Kept verbatim: both "Unverified — not in research corpus" flags, the rev-freshness caveat, the rtk git add -u/rtk git commit fix (ADR-0023), and the pre-commit install -f warning. Combined cut: 60 lines. Flat mirror regenerated and verified byte-identical.

7. Suggested order

1. Quick wins, all S, no design decisions needed: findings 9, 10, 26, 30, 31, 29, 12, 13, 1, 6, 4, 35, 37, 38, and the mirror-sync and executables-allow halves of 2. Removes roughly 25,000 to 30,000 lines and 6 hooks.
2. Structural changes that need a short discussion: 14, 15, 19, 20, 23, 25, 17, 3, 5, 7, 33, 34, 36.
3. The real complexity: 16 (validators), 11 (provenance), 24 (core), 8 and 28 (gates.md and ADRs).

Findings 9, 10, 11, and 12 are coupled through the provenance validator and the audit criteria; land them together or the audit gates start reporting the removals.

8. Questions to settle before starting

• Native Claude Code marketplace install vs apm-only. The flat mirror, check-plugin-content-sync, and ADR-0017 exist only for native claude plugin install. If apm install is the only supported path, the mirror and its 2,100 lines of tooling go away. Which install paths must work for consumers?

  Answered (2026-09-14): apm-only. See ADR-0024 (docs/adr/0024-apm-is-the-only-supported-install-path.md) and commit 718c79a on docs/simplification-audit. Native claude plugin install support is dropped; the flat mirror, the twelve per-plugin manifests, sync-plugin-content.sh, its test suite, lib/marketplace-plugins.sh, and the check-plugin-content-sync and validate-plugins hooks are all deleted (245 files changed, −22,602 lines). ADR-0017 carries a superseded banner. Kept deliberately: the root marketplace: block and the root .claude-plugin/marketplace.json, which apm's own consumers read. (marketplace.json is the only tracked file under .claude-plugin/; the root plugin.json beside it is untracked local apm pack output, ignored at .gitignore:59.) This answer is what voided finding 7's recommendation and closed §3's check-plugin-content-sync target.

• Copilot CLI legacy path. Is .github/plugin/marketplace.json still read by any Copilot version you target? If not, finding 2c is a pure delete.

  Answered (2026-09-14): yes, but only as a preferred path, not a required one — so the delete holds. Settled under finding 2c above and executed in commit 0dffff3; this bullet was left open by oversight when that finding closed. Copilot CLI falls through marketplace.json, .plugin/marketplace.json, .github/plugin/marketplace.json, .claude-plugin/marketplace.json in order, and the .claude-plugin/ file apm already emits satisfies the last step. What was lost is discovery-order preference, not Copilot consumability.

  Corrected (2026-09-14, later the same day, verified at a6434e0): "not Copilot consumability" no longer holds. It was true at 0dffff3; 718c79a (ADR-0024) then removed native install support for both hosts, and Copilot consumability went with it. The fallback still resolves — that part stands — but it now resolves to a catalogue of six packages whose roots contain no content: ls plugins/*/ shows .apm/, apm.yml, docs/ and a README, and plugins/*/skills, .../agents, .../hooks do not exist at all.

  The mechanism is host-independent, which is why this bullet had to change. ADR-0024 consequence 1 and §9's first residual both state it for Claude Code: a native registration succeeds and installs six plugins containing zero skills, silently. Nothing in that chain is Claude-specific. The catalogue is a list of plugin roots; discovery of content inside a root is a convention-scan of flat skills//agents//hooks/ directories, and that is the layout 718c79a deleted. Whichever of the four paths a host resolves the catalogue through, it lands on the same empty roots. Copilot was in fact always the weaker case — ADR-0017's own hooks amendment records that the mirror only ever partially served it.

  The delete still holds, for a stronger reason than the one given: the file was a preferred discovery path to content that no longer exists. What changed is the accepted cost — this is no longer "preference lost", it is the same accepted silent-empty-install residual §9 records, now known to apply to Copilot as well.

• Provenance chain. Is "which upstream informed this file" a requirement you still want, or was it a governance experiment? Finding 11 hinges on this.

  Sharpened (2026-09-14): still open, but ask it of the producer first. plugins/bin/.apm/skills/research/ specifies the sources.md + source_keys: format and three evals in plugins/bin/evals/research/research/eval.yaml assert it. If research keeps emitting the chain, finding 11 collapses to "delete the validators" and the metadata stays. See finding 11's verification note.

• ADR-0012 (three core skills) and the one-script-per-skill install constraint. The merges in 14, 15, and 24 need the first revisited and are the only way around the second. Corrected (2026-09-14): this grouping was wrong, and finding 2b's note has said so since 0dffff3 while this bullet said the opposite. ADR-0012 governs only the core plugin's three agentsmd-* skills (agentsmd-author, agentsmd-audit, provider-adapter-author) — read it: it names those three and nothing else. Only finding 24 touches them, so only finding 24 needs ADR-0012 revisited. Findings 14 and 15 merge kyberforge's skill-audit/agent-audit and skill-author/agent-author, which ADR-0012 does not govern; what constrains them is the self-containment rule, and merging is the way around it rather than a reason to reverse anything. That rule survives ADR-0024 — see §9's negative result and ADR-0024 consequence 6, which also correct its source: it is the agentskills.io spec for APM package mode, not a property of Claude Code's plugin cache-install as finding 2b's note assumed. The open question for 14/15 is a design one — one description carrying both skills' trigger phrases — not an ADR supersession. Are you open to superseding ADR-0012, for finding 24?

  Moot (2026-09-14): finding 24 is refuted on arithmetic before this question is reached — the three core bodies total 1,360 words against BODY_MAX_WORDS=900, and their descriptions 806 chars against a 400 cap. Nothing needs superseding because the merge it would unblock cannot be committed. Question closed unless finding 24 is rewritten.

• Granularity of git/gitea skills. One git skill vs seven trades routing precision for size. Is one broad description acceptable?

  Answered by measurement (2026-09-14): no, and it is not a preference question. A merged git description measures 1,950 chars against a 400-char FAIL ceiling (4.9×) and a 3,381-word body against 900 (3.8×). Both proposed gitea halves also FAIL at 2.5×, and the gitea split additionally puts a hard boundary through the edit-a-file-then-open-a-PR workflow. (An earlier revision also called the gitea split "blocked by ADR-0011, which already rejected a smaller bundling" — withdrawn; ADR-0011's objection is to a boundary being crossed, not to bundle size. See finding 20's verification note.)

• Auto-update at session start. Do you want the install refreshed from the remote every time a session opens (finding 34), or is a manual apm update acceptable?

  Recommendation on evidence (2026-09-14): keep it; finding 34 refuted. The premise that it runs on every startup is false (the update is conditional on a real SHA check), the lock was not dirty, the hook did not fire this session, and the install is currently 9 commits behind main with nothing reporting it — the failure the hook exists to prevent. install.sh, the proposed alternative host, has no apm step. Still formally the human's call, but the factual basis for removing it does not survive. See finding 34.

• External hook consumers. Does any other repo pin this repo's .pre-commit-hooks.yaml by tag today? If not, finding 36 defers the release mechanism entirely.

  Evidence gathered, decision deferred (2026-09-14). No consumer found: the Gitea instance holds two repos, and the other pins seven hook repos, none of them this one. No consumer-driven commit in the 13 touching the mechanism. Off-instance clones undeterminable — but ADR-0024 accepted exactly this standard when it deleted the mirror. The mechanism is additionally already broken (a consumer pinning rev: v2.0.1 gets a stale skill-size-check.sh, and the guard cannot fire through Gitea's merge button). The human deferred the decision on 2026-09-14; the finding is ready to execute when it is taken. See finding 36.

• Obsidian MCP. Are the Obsidian tools over docs/ used by anyone? If not, finding 37 is a pure delete.

  Answered (2026-09-14): not used — remove entirely. All seven .mcp.json files are deleted and the repo-root path is gitignored; see finding 37, which also records the functional regression this uncovered (since 718c79a deleted the per-plugin manifests, apm no longer propagated the server to consumers at all).

9. Carried forward from the apm-only decision (2026-09-14)

Recorded here so they are not rediscovered as defects. All follow from commit 718c79a / ADR-0024.

Two accepted residuals.

• Native install still half-works, and cannot be prevented. apm reuses Claude's catalogue format by design, so a Claude Code user can still register holocron natively and will install six plugins containing zero skills. Accepted, not overlooked: no schema change closes this, because the format that makes it possible is the format apm's own consumers need.
• Consumers now receive test fixtures. apm installs from .apm/, which carries the tests/ directories the mirror used to strip, so a consumer installing from this branch receives 10 .bats files across 6 skills, plus those skills' 6 tests/README.md files — 16 files. (Repo-wide, 17 tracked paths contain /tests/: the 10 .bats and 7 README.md, one of which is a template asset under skill-author/assets/templates/tests/ and is not a test fixture.) This is what consumers receive, not what this checkout shows: .claude/skills/ here currently holds zero .bats files, because that deployed tree is stale and predates this branch. The mechanism was confirmed empirically on a ref-pinned consumer clone — the 16 files are absent at the parent commit and present at HEAD. Suppressing them means switching all six apm.yml files from includes: auto to explicit lists, where a wrong list silently drops content — worse failure mode than the noise. Deferred deliberately.

Negative result — do not re-litigate. Deleting native install does not relax the self-containment constraint. plugins/kyberforge/.apm/skills/skill-author/references/deployment-modes.md, sourced from the agentskills.io spec, states it independently for APM package mode: the spec defines no cross-skill sharing. So findings 14 and 15 still require merging skills; sharing one file between two skills remains impossible, and §8's "one-script-per-skill install constraint" bullet is unchanged by this decision.

Accepted gap — symlinks under .apm/. ADR-0017's check_apm_symlinks() was the only thing reporting that symlinks under .apm/ do not survive to a consumer. It is gone, and no replacement guard is being added — the human decided to accept the gap.

The mechanism is not the bundle exporter, as ADR-0017 assumed; it is the install path, and it has since been verified. apm_cli/security/gate.py's ignore_non_content() is a shutil.copytree ignore callback whose docstring says "Excludes symlinks (security)"; it is used at apm_cli/integration/skill_integrator.py:424, :791 and :1152. Materialization into apm_modules/ dereferences first, so symlinked content survives there and is dropped when skills are deployed out of it. ADR-0024 flagged the prediction as unverified; it holds, with that corrected attribution. No symlinks exist under any .apm/ today, so nothing is broken now — but the next one added there will silently not reach consumers, and nothing will say so.

10. Verification wave (2026-09-14)

Ten open findings with claimed yield — 11, 16, 20, 22, 24, 27, 28, 33, 34, 36 — were each re-checked against the files by an independent read-only agent, at HEAD 062ca47. Findings 14 and 15 were deliberately excluded: their blocker is a design decision, not a premise. Results are recorded in each finding's own note above.

Read this section before acting on any remaining finding.

Why the wave was run

This audit was written read-only, and its scope estimates are systematically optimistic. Before the wave, ten findings had been examined closely in the course of implementing them: 3, 19 and 37 each cost a full agent run to conclude "premise doesn't hold", and 2d, 29, 31 and 38 each needed correcting mid-implementation. Findings 5, 18 and 32 were then examined during a grill on 2026-09-14 and all three collapsed — 18's four examples were three different classes of load-bearing content, 5's suites turned out to be split by failure class rather than ADR section, and 32's proposed split already existed and was self-documenting in architecture.md.

That base rate made "effort S, no decisions needed" an unreliable signal, and §7's bucket 1 an unreliable plan. Dispatching implementation agents against unverified premises costs more than verifying first.

Outcome

Finding	Verdict	Verified yield
36	Premise holds — the only one whose premise survived; one supporting figure wrong (272 lines, not 270)	~1,000 lines
33	Headline wrong; one item empirically verified zero-risk	6 lines, zero output diff
28	Headline accurate when measured (a3e721e), now stale; as written it is a wash (+5 to −1 lines); real win is elsewhere	~235 lines
22	Percentages 3–4× inflated, wrong target set; better defect found	~150–180 lines
20	Refuted — git 7→1 is 4.9× the description FAIL ceiling	~230 lines salvage
27	Refuted — audience separation misread as duplication	~168 words + a live bug
11	Direction defensible, two scope figures wrong; blocked on a decision it never poses	~6,393 if unblocked
16	Refuted — its only safe saving belongs to finding 14	0 independent
24	Refuted — arithmetically impossible (1,360w vs a 900 cap)	0
34	Refuted — evidence inverted	0

One premise of ten survived — finding 36's — but not the finding whole: its supporting figure was wrong (test-vale-hooks-consumer.sh is 272 lines, not 270). The other nine premises failed.

The headline figure was wrong in at most eight of the ten, not all ten. Two exceptions, stated so the claim is not overstated:

• Finding 36 states no headline figure. Its headline is a claim — "the release-tag mechanism guards an external contract with no known consumer" — and the numbers appear only in a supporting sentence.
• Finding 34's stated figures are exact. "A 60-line script with a 368-line test" checks out at both ends (plugins/kyberforge/.apm/hooks/check-apm-current.sh 60, tests/test-apm-current-hook.sh 368). Its note's only figure correction runs the other way — the footprint is understated at six files / 1,096 lines. What is refuted in 34 is the mechanism claim ("on every startup"), not an arithmetic error.

Three findings (16, 24, 34) are refuted outright; two (22, 28) contain a real finding different from the one written. Finding 28 is the one case where the headline was accurately measured and went stale: 2,740 lines / 72% in eight ADRs is exact at a3e721e, and the ADR-0024 wave moved it afterwards.

The recurring failure mode is worth naming, because it has now produced six wrong findings (3, 5, 16, 22, 24, and by implication 28): dense validator and test code with heavy comments reads as over-engineering when skimmed, and turns out to be regression coverage whose comments name the incident. Findings 16 and 24 propose reverting validators to sizes whose defects are on the commit record. Before proposing to cut any script or suite in this repo, read its header.

Where the real remaining opportunity is: finding 14 (merge skill-audit + agent-audit) at −1,587 lines with zero coverage loss, which is also where finding 16's savings actually live. Its blocker is the design question in §8 — one description carrying both skills' trigger phrases — not an ADR supersession.

Executed, and one knock-on claim corrected (2026-09-15). Finding 14 landed as factory-audit (ADR-0025); yield 2,934 lines and one pre-push hook, and the §8 blocker turned out to be a non-issue. The body was the binding ceiling, not the description, which ships at 241 characters, under the 250 target, once a duplicated trigger register was removed. See finding 14's own note for the corrections.

The merge does not unblock check-scope-walkup-sync, and nothing in this audit should be read as saying it does. §3's finding 2 bullet says that gate "disappears if the ports share one script or the skills merge"; the second half of that is wrong, and the first is unreachable. The gate cross-checks four independent $HOME/.git/apm.yml walk-up ports, and only two of them are in the audit pair (validate.sh's detect_scope, validate-provenance.sh's find_plugin_root). The other two — new-agent.sh's and new-skill.sh's find_package_root — live in the author skills, which finding 15 has not merged and which could not be merged into the audit skill in any case. Four ports go to four ports.

It cannot degrade into a text diff either, which is the shape that would let it be deleted rather than merely shrunk: the two audit-side ports are Python (def detect_scope, def find_plugin_root, inside heredocs) and the two author-side ports are Bash functions. Byte-comparing them is not an option at any point on this path, so the behavioural fixture cross-check is the only available form of the gate. It survives finding 15 too.

check-vale-style-sync was the only one of the two "keep two copies in sync" gates that finding 14 could remove, which is why the yield is one hook and not two.

Two defects to fix independently of any finding

• A live bug in always-on context. Fixed (2026-09-15). The deployed core/instructions/governance.md cited docs/HUMANS.md, which does not exist — the file is docs/wiki/HUMANS.md. Five occurrences across three files (governance.md:82, which was self-inconsistent against its own correct line 73; CONTROLS.md:5,101,106; ai-constitution.md:238), in a file @-imported into every session in every project. All five now point at docs/wiki/HUMANS.md. Note the deployed copy under ~/.claude/ no longer matches the repo until scripts/install.sh re-runs.
• This checkout's install is stale and there is a branch hazard. At the time of the wave apm outdated reported 6 outdated dependencies, 9 commits behind main, with a clean tree and nothing reporting it. Do not run apm update on this branch — it resolves against main and restores the obsidian MCP server that commit c96ca9c removed here. Reproduced. The mechanism is worse than "reinstalls plugins/bin/.mcp.json": apm never writes into plugins/, it re-materialises the file under apm_modules/ and regenerates the repo-root /.mcp.json — which c96ca9c gitignored, so the restoration would not appear in git status at all. This belongs in ADR-0019's Consequences; see finding 34.