diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index 4d52273..bd4c6c7 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -44,12 +44,12 @@ Counting convention: line counts are hand-edited `.apm/` source unless marked "i | `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~~ → ~~10,189 + 502 + 2,901~~ → 10,608 + 502 + 3,139 | +| Enforcement: `tests/*.sh` + runners + `scripts/` | ~~12,400 + 475 + 4,500 lines~~ → ~~9,123 + 490 + 3,308 lines~~ → ~~10,189 + 502 + 2,901~~ → ~~10,608 + 502 + 3,139~~ → 10,000 + 502 + 1,924 (at `4b17703`) | | Validator scripts inside kyberforge (+ their bats tests) | ~~6,800 + 5,300 lines~~ → ~~5,861 + 6,015~~ → 5,876 + 6,015 | | 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]`**~~ → ~~**26 entries and 8 `stages: [pre-push]`**~~ → **27 entries and 9 `stages: [pre-push]`** (`467bbd7` removed `check-vale-style-sync` with finding 14's merge; `8451169` then added `check-skill-version-bump`; re-measured 2026-09-16 at HEAD (`b426460`) with `grep -c -- "- id:"` and `grep -c "stages: \[pre-push\]"` on `.pre-commit-config.yaml`). Like for like that is 14 → ~~9~~ → ~~8~~ → 9 repo-authored pre-push hooks. The stage *reports* ~~11~~ → ~~10~~ → 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. +> **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]`**~~ → ~~**26 entries and 8 `stages: [pre-push]`**~~ → ~~**27 entries and 9 `stages: [pre-push]`**~~ → **26 entries and 8 `stages: [pre-push]`** (`467bbd7` removed `check-vale-style-sync` with finding 14's merge; `8451169` then added `check-skill-version-bump`; `4de5b6b` then removed `check-release-needed`; re-measured 2026-09-16 at `4b17703` with `grep -c -- "- id:"` and `grep -c "stages: \[pre-push\]"` on `.pre-commit-config.yaml`). Like for like that is 14 → ~~9~~ → ~~8~~ → ~~9~~ → 8 repo-authored pre-push hooks. The stage *reports* ~~11~~ → ~~10~~ → ~~11~~ → 10, 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`: > @@ -106,8 +106,8 @@ This is the area you named as hardest to understand and slowest. Root cause: mos > **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/` 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]`~~ → ~~**26 `- id:` entries, 8 with `stages: [pre-push]`**~~ → **27 `- id:` entries, 9 with `stages: [pre-push]`** (re-measured 2026-09-16 at HEAD, `b426460`; `8451169` added `check-skill-version-bump`), 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 **10 reported / 8 self-authored** until `8451169` added `check-skill-version-bump`; at HEAD (`b426460`, 2026-09-16) `gates.md:24-28` reads **11 reported / 9 self-authored** again. Read the count from that file, not from this note. + > - **"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]`~~ → ~~**26 `- id:` entries, 8 with `stages: [pre-push]`**~~ → ~~**27 `- id:` entries, 9 with `stages: [pre-push]`**~~ → **26 `- id:` entries, 8 with `stages: [pre-push]`** (re-measured 2026-09-16 at `4b17703`; `8451169` added `check-skill-version-bump`, then `4de5b6b` removed `check-release-needed`), 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 **10 reported / 8 self-authored** until `8451169` added `check-skill-version-bump`; at `b426460` `gates.md:24-28` read **11 reported / 9 self-authored** again, and since `4de5b6b` removed `check-release-needed` it reads **10 reported / 8 self-authored** (checked at `4b17703`). 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`). @@ -137,7 +137,7 @@ This is the area you named as hardest to understand and slowest. Root cause: mos 5. [x] **`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. > - > **Salvage closed (2026-09-16, grill): not proceeding.** Timed one suite at a time on this 4-core machine, `test-adr0020-differential.sh` takes **34.3 s** of **213 s** total suite time, behind bats (70.7 s) and ahead of `test-vale-wrap.sh` (29.4 s). Its cost is about 90 validator runs, one after another, at 0.1–0.15 s each. Even deleting it outright would take at most 34 s off a pre-push measured at 3.5–5 min, and inside `run-tests` a parallel rewrite would compete for the same four cores, so a standalone speed-up is too small to be worth another change to a regression suite. Pre-push `run-tests` wall time is a separate question, pending a possible issue. + > **Salvage closed (2026-09-16, grill): not proceeding.** Timed one suite at a time on this 4-core machine, `test-adr0020-differential.sh` takes **34.3 s** of **213 s** total suite time, behind bats (70.7 s) and ahead of `test-vale-wrap.sh` (29.4 s). Its cost is about 90 validator runs, one after another, at 0.1–0.15 s each. Even deleting it outright would take at most 34 s off a pre-push measured at 3.5–5 min, and inside `run-tests` a parallel rewrite would compete for the same four cores, so a standalone speed-up is too small to be worth another change to a regression suite. Pre-push `run-tests` wall time is a separate question; the human decided (2026-09-16) not to track it. 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~~ → **167 + 282**, re-measured 2026-09-16 at HEAD) 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. @@ -163,7 +163,7 @@ This is the area you named as hardest to understand and slowest. Root cause: mos 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.~~ **Struck (2026-09-16, grill):** see finding 8's closing note — the suites are regression coverage (findings 3 and 5; finding 16 found the same of the validators they test). -> **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. +> **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**~~ — **struck (2026-09-16):** the target itself is withdrawn (see the struck sentence above); for the record, `tests/` holds **19** suites totalling **10,000** lines at `4b17703`, after `4de5b6b` deleted `test-check-release-needed.sh` and `test-vale-hooks-consumer.sh`. Finding 9's `check-ast` clause is moot anyway, since finding 9 is not proceeding. ## 4. Plugins @@ -352,9 +352,9 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research > > **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~~ → was redeployed on 2026-09-16 (see §10). (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. > - > **Decided and done (2026-09-16, grill).** The constitution moved from `docs/ai-constitution.md` to `core/ai-constitution.md`, so the existing `core` deploy step ships it to `~/.claude/core/ai-constitution.md`, and `governance.md`'s "read it when making decisions not covered here" pointer now names that deployed path. The three informational pointers (`HUMANS.md`, `CONTROLS.md`, and the footer) now say they live in the holocron repo rather than reading as local paths. Path-qualified citations were updated in `AGENTS.md`, `docs/spec/architecture.md`, `docs/notes/skill-implementation-workflow.md`, `CONTROLS.md` and the wiki's `HUMANS.md`; the vendored `write-skill` example under `plugins/kyberforge/docs/research/examples/` and this audit's historical notes were left as records. The wiki commit is local until its push is approved, and the `docs/wiki` gitlink is bumped only after that. + > **Decided and done (2026-09-16, grill).** The constitution moved from `docs/ai-constitution.md` to `core/ai-constitution.md`, so the existing `core` deploy step ships it to `~/.claude/core/ai-constitution.md`, and `governance.md`'s "read it when making decisions not covered here" pointer now names that deployed path. The three informational pointers (`HUMANS.md`, `CONTROLS.md`, and the footer) now say they live in the holocron repo rather than reading as local paths. Path-qualified citations were updated in `AGENTS.md`, `docs/spec/architecture.md`, `docs/notes/skill-implementation-workflow.md`, `CONTROLS.md` and the wiki's `HUMANS.md`; the vendored `write-skill` example under `plugins/kyberforge/docs/research/examples/` and this audit's historical notes were left as records. The wiki commit ~~is local until its push is approved, and the `docs/wiki` gitlink is bumped only after that~~ → is pushed (`ca1b35f` on the wiki's `main`), and the gitlink bump landed in `2ae7d4e`. > - > **Decision (2026-09-16):** Not proceeding — the human declined this finding, including the 168-word cross-reference trim. `core/instructions/governance.md` and the other three governance documents stay as they are. The `docs/HUMANS.md` path defect was fixed separately (see §10). + > **Decision (2026-09-16):** The finding as written is not proceeding: the human declined its cuts, including the 168-word cross-reference trim, so no governance document was deduplicated or shortened. The two defects above are fixed separately. The `docs/HUMANS.md` path was corrected on 2026-09-15 (see §10), and the dangling always-on pointer was fixed by the constitution move in the note above (`adaa978`). That move changed `governance.md`'s pointers, not its rules. 28. [x] **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. @@ -367,9 +367,9 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research > > 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`~~ → `docs/spec/gates.md:397-400` 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."* + > **"The rules already live in `gates.md`" is backwards.** ~~`docs/spec/gates.md:349-352`~~ → ~~`docs/spec/gates.md:397-400`~~ → `docs/spec/gates.md:399-401` 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."* > - > > **Repointed (2026-09-16, at HEAD `b426460`):** the quoted `gates.md` passage moved from `:349-352` to `:397-400` as later sections were added above it; verified with `grep -n "Quoting them here" docs/spec/gates.md` and `sed -n 397,400p`. `architecture.md:90` still resolves. + > > **Repointed (2026-09-16, at HEAD `b426460`):** the quoted `gates.md` passage moved from `:349-352` to `:397-400` as later sections were added above it; verified with `grep -n "Quoting them here" docs/spec/gates.md` and `sed -n 397,400p`. At `4b17703` it is `:399-401` (the "Quoting them here" line is `:400`). `architecture.md:90` still resolves. > > **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. > @@ -418,13 +418,13 @@ Not covered by the area audits above; found on a final sweep of the root config > > > **Repointed (2026-09-16, at HEAD):** `skill-audit/scripts/validate.sh` no longer exists — ADR-0025's merge moved the ADR-0022 check into `factory-audit`'s skill-side check library, where it is the `SEMVER_RE` block (comment header at `:235`, `fail()` calls at `:261` and `:275`). `skill-size-check.sh` grew by 5 lines above the block since `062ca47`, hence the shifted range there. All five instruction-level citations still resolve at HEAD, verified with `sed -n`. > - > **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`~~ → `gates.md:145` — and re-open the "is this field present here?" question issue #127 closed, just from the other side. *(Repointed 2026-09-16, at HEAD `b426460`: the `metadata.version` frontmatter sentence formerly at `gates.md:97` is now at `:143-146`, the field itself on `:145`; verified with `grep -n "metadata.version" docs/spec/gates.md`.)* **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. + > **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`~~ → ~~`gates.md:145`~~ → `gates.md:146` — and re-open the "is this field present here?" question issue #127 closed, just from the other side. *(Repointed 2026-09-16, at HEAD `b426460`: the `metadata.version` frontmatter sentence formerly at `gates.md:97` was at `:143-146`, the field itself on `:145`, and is at `:143-147` / `:146` at `4b17703`; verified with `grep -n "metadata.version" docs/spec/gates.md`.)* **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. > - > **Decided and done (2026-09-16, grill): enforce the bump.** Advisory status and dropping the field were both rejected. The six root `apm.yml` `packages[].version` lines are deleted (`apm pack --check-versions --check-clean` still passes, output unchanged), which also makes ADR-0006's "the only version field a plugin has" true. `scripts/check-skill-version-bump.sh` now runs at pre-push: any skill directory that changed against its merge-base with `main`, `tests/` excluded, must carry a strictly higher `metadata.version` than ~~`main`~~ → the same skill had at that merge-base (not `main`'s current tip; see `gates.md:90` and `:111-112`, and the hook comment at `.pre-commit-config.yaml:203-206`. *Amended in the 2026-09-16 review round: the gate now also compares against the `origin/main` tip; see §11.*); new, renamed and deleted skills are exempt; every plugin is covered, `bin` included. Recorded as a dated section in ADR-0022, not a new ADR. The 17 skills changed on this branch without a bump took a patch bump in the same commit. The `executables.allow` pin and the inert `tagPattern` are left as the note above recommends. + > **Decided and done (2026-09-16, grill): enforce the bump.** Advisory status and dropping the field were both rejected. The six root `apm.yml` `packages[].version` lines are deleted (`apm pack --check-versions --check-clean` still passes, output unchanged), which also makes ADR-0006's "the only version field a plugin has" true. `scripts/check-skill-version-bump.sh` now runs at pre-push: any skill directory that changed against its merge-base with `main`, `tests/` excluded, must carry a strictly higher `metadata.version` than ~~`main`~~ → the same skill had at that merge-base (not `main`'s current tip; see ~~`gates.md:90` and `:111-112`, and the hook comment at `.pre-commit-config.yaml:203-206`~~ → `gates.md:86` and `:100-113`, and the hook comment at `.pre-commit-config.yaml:194-197`, repointed at `4b17703` after `4de5b6b` shifted both files. *Amended in the 2026-09-16 review round: the gate now also compares against the `origin/main` tip; see §11.*); new, renamed and deleted skills are exempt; every plugin is covered, `bin` included. Recorded as a dated section in ADR-0022, not a new ADR. The 17 skills changed on this branch without a bump took a patch bump in the same commit. The `executables.allow` pin and the inert `tagPattern` are left as the note above recommends. 34. [x] **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.** @@ -461,7 +461,7 @@ Not covered by the area audits above; found on a final sweep of the root config > > **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`~~ → `.pre-commit-config.yaml:221,254,269`, the three `entry:` lines), so deleting the export costs **zero** internal lint coverage. + > **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`~~ → ~~`.pre-commit-config.yaml:221,254,269`~~ → `.pre-commit-config.yaml:212,245,260`, the three `entry:` lines), 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. > @@ -469,6 +469,8 @@ Not covered by the area audits above; found on a final sweep of the root config > > > **Repointed (2026-09-16, at HEAD `b426460`):** the line citations in this note were taken at `062ca47` and have shifted. The `check-release-needed` block is now `.pre-commit-config.yaml:186-193` (`grep -n "id: check-release-needed"`); the three internal `repo: local` wirings' `entry:` lines are `:221` (`skill-size-check`), `:254` and `:269` (the two `vale-audit-prefilter-*` hooks, both now on `factory-audit`'s one `vale-wrap.sh`); the `check-release-needed` table row is `gates.md:96` and the "External consumers" section heading is `gates.md:789`. Verified with `grep -n` and `sed -n`. Line counts in this note were not re-measured. > + > > **Repointed again (2026-09-16, at `4b17703`):** `4de5b6b` removed the `check-release-needed` block, so the three `entry:` lines are now `:212`, `:245` and `:260`. The `check-release-needed` table row and the "External consumers" section no longer exist in `gates.md`; the same commit deleted them, so the `:96` and `:789` citations above are historical. + > > **Decided and done (2026-09-16):** see commit `4de5b6b` on `docs/simplification-audit`. The human took the deferred decision: remove the mechanism. Deleted `.pre-commit-hooks.yaml` (31 lines), `scripts/check-release-needed.sh` (242), `tests/test-check-release-needed.sh` (449 at HEAD, not the 442 above) and `tests/test-vale-hooks-consumer.sh` (276 at HEAD, not 272), plus the `check-release-needed` hook block, for **1,443 lines removed and 234 added** across 20 files. ADR-0014 is **amended, not retired**, as the note above says: its runtime bundling decision stands, and the amendment records why the export went and keeps the `entry[0]`-only constraint (`LESSONS.md:101,105`) in case it returns. ADR-0025 gets a pointer to that amendment. Tags are left in place. **One cost the finding did not count:** `tests/test-vale-wrap.sh` case 33, the cross-manifest `files:` drift check, and case 28's hook-scope half both read the published manifest and went with it. Case 33's one guard that did not need a second manifest, a local regex narrowed to one plugin, is now a third property of case 32, with its own mutation test, so that coverage is kept. `gates.md` now counts 8 authored pre-push hooks (10 reported), no longer 9 (11). 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.~~ @@ -492,7 +494,7 @@ Not covered by the area audits above; found on a final sweep of the root config > > **Updated (2026-09-16, after the finding 15 grill):** **15** is refuted on measurement (see its note), so no finding is open. **22** stays deferred with `bin`. > -> **Complete (2026-09-16).** The follow-up read after 15 closed turned up four loose ends, all now settled: finding 6's `check-apm-agents-valid` fold (not proceeding, see its note); finding 27's dangling always-on pointer (constitution moved to `core/` and deployed, `adaa978`); finding 5's differential-suite speed-up (not proceeding, see its note); and finding 16's resolver-sourcing option (done, `ef27c97`). Nothing in this audit is open. **22** is out of scope with `bin` and is not tracked here. +> **Complete (2026-09-16).** The follow-up read after 15 closed turned up four loose ends, all now settled: finding 6's `check-apm-agents-valid` fold (not proceeding, see its note); finding 27's dangling always-on pointer (constitution moved to `core/` and deployed, `adaa978`); finding 5's differential-suite speed-up (not proceeding, see its note); and finding 16's resolver-sourcing option (done, `ef27c97`). Nothing in this audit is open. **22** is out of scope with `bin` and, by the human's decision, is not tracked anywhere. > **Re-derived (2026-09-16, at HEAD):** this ordering was written before the findings were worked, and ~~seven of its entries are now closed~~ → ~~all but two~~ → ~~all but one~~ → all of its bucket-2 and bucket-3 entries are now closed (corrected later on 2026-09-16, after the grill, and again once **36** closed and once **15** was refuted). Struck above: **14** landed (`467bbd7`, ADR-0025); **7** was superseded then done (`718c79a`); **3**, **5** and **19** are not proceeding on refuted premises; ~~**34**,~~ **16** and **24** are refuted outright; **34** was refuted as a removal and then decided and done as documentation of the branch hazard in ADR-0019 (`afcf477`), with the hook kept; **33** was decided and done (enforce the bump, `8451169`); **8**, **20** and **28** closed at the grill; **17**, **23** and **25** were declined by the human; **11** was declined by the human; **36** was done (`4de5b6b`). ~~**5** is left standing but is downstream of 16 by its own note, so it cannot be taken in this bucket's order.~~ **5** is closed with 16: its own note says it is downstream of 16, and 16 is refuted. ~~Still open, per the Status note above: **15** alone, now that **36** is done (`4de5b6b`);~~ **15** was refuted on measurement after its own grill, so none is still open; **22** is deferred with `bin`. Read each finding's own marker, not this list — it is a plan of record, not a status board. Bucket 1 is left as written: every entry in it is marked `[x]` or carries a decision note at its own finding. *(Updated 2026-09-16:)* `[x]` now marks every closed finding, whatever the outcome — done, refuted, declined or not proceeding; read the note for which. The only finding without one is **22**, deferred with `bin`.