# 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`. 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. [x] **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.
   - [x] ~~`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.
   - [x] ~~`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. [x] ~~**`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. [x] ~~**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. [x] ~~**`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. [x] ~~**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. [x] ~~**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. [x] ~~**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. [x] ~~**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. [x] ~~**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. [x] ~~**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. [x] ~~**`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 `@import`ed at session start) was removed rather than filed as an issue — full text preserved in this session's transcript if wanted later.

31. [x] ~~**`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. [x] ~~**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 0`s 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. [x] ~~**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. [x] ~~**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. [x] ~~**`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

- [x] ~~**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.
- [x] ~~**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.
- [x] ~~**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.