chore(gates): retire the external pre-commit hook contract

Why: .pre-commit-hooks.yaml and its release-tag gate served external
consumers that do not exist. No repo on the Gitea instance pins these
hooks, and the README names apm as the only supported install path. The
mechanism was also already failing: skill-size-check.sh changed after
v2.0.1 with no tag cut, and the gate cannot fire through Gitea's merge
button. (Simplification audit finding 36.)

Implementation Notes:
- Delete .pre-commit-hooks.yaml, scripts/check-release-needed.sh,
  tests/test-check-release-needed.sh and tests/test-vale-hooks-consumer.sh,
  and remove the check-release-needed pre-push hook. The repo: local
  skill-size-check and vale-audit-prefilter-* hooks are unchanged.
- ADR-0014 is amended, not retired: its runtime decision to bundle Vale
  inside factory-audit stands. The amendment keeps the entry[0]-only
  constraint (LESSONS.md:101,105) in case the export returns. ADR-0025
  gets a pointer.
- test-vale-wrap.sh: drop case 33 (the cross-manifest drift check) and
  case 28's hook-scope half, which read the published manifest. Case 32
  now also requires each hook to select every tracked file of its class,
  which keeps case 33's one-plugin-narrowing guard, with a mutation test.
- test-skill-size-check.sh and test-adr0020-contract.sh now assert the
  hook contract and verbose: true on .pre-commit-config.yaml only.
- gates.md: pre-push count goes from 9 to 8 authored hooks (11 to 10
  reported), and the Release table, the External consumers section and
  the two-manifest scope table are removed. README and script/test
  comments no longer describe the export as live. The resolver comment
  is edited identically in both copies.
- The v1.0.0/v2.0.0/v2.0.1 tags are left in place; they are inert.

ADR: 0014
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-16 11:52:14 +00:00
parent 2119da9700
commit 4de5b6b355
20 changed files with 233 additions and 1442 deletions

View File

@@ -27,6 +27,14 @@ them by name — and the argument-free `entry:` contract is untouched. Read the
sync-check paragraph, and the `tests/test-vale-wrap.sh` Consequences bullet below as the state this
ADR established, not as current layout.
**Amended (2026-09-16): the `.pre-commit-hooks.yaml` export and its release tags are retired.**
The runtime half of this ADR — Vale config, styles and wrapper bundled inside the skill (now
`factory-audit`), self-located from `${BASH_SOURCE[0]}` — stands. The external git-hook/CI half does
not: the manifest, `check-release-needed` and the tag-cutting consequence are gone. See
[the amendment at the end of this file](#amendment-2026-09-16-the-external-hook-contract-is-retired)
before reading any paragraph below that names `.pre-commit-hooks.yaml`, a `rev:` tag, or
`check-release-needed` as current.
`skill-audit`/`agent-audit`'s Step 1 called
`"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini"`
— which resolves to whichever repo the skill happens to be running in. Inside `ai-development`
@@ -219,3 +227,51 @@ only when the original span is already two or more lines, so the pad count stays
`tests/test-vale-wrap.sh` case 20 asserts an apostrophe-bearing token actually fires on a flattened
description in all three apostrophe-carrying branches, and case 20b pins the pad arithmetic against
a body line's true line number.
## Amendment (2026-09-16): the external hook contract is retired
Root `.pre-commit-hooks.yaml`, `scripts/check-release-needed.sh`,
`tests/test-check-release-needed.sh` and `tests/test-vale-hooks-consumer.sh` are deleted, and the
`check-release-needed` pre-push hook is removed from `.pre-commit-config.yaml`. The three exported
hook IDs — `kyberforge-vale-audit-skill`, `kyberforge-vale-audit-agent` and
`kyberforge-skill-size-check` — no longer exist, and no new `vX.Y.Z` tag is cut when hook files
change. (Simplification audit finding 36.)
Three reasons, any one of which would have been enough to ask the question:
- **No consumer was found.** The Gitea instance holds two repos. The other one pins seven hook
repos, and none of them is this one. None of the 13 commits that touched the mechanism came from a
consumer report; all were found by this repo's own tests. Clones outside the instance cannot be
counted, but ADR-0024 accepted the same standard when it deleted the mirror.
- **The mechanism was already failing at its one job.** `scripts/skill-size-check.sh` changed on
`main` after `v2.0.1`, and no tag was cut, so a consumer pinning `rev: v2.0.1` already ran a
stale hook. The gate could not have caught it. It acted only when pre-commit reported a push to
`refs/heads/main`, and PRs here merge through Gitea's server-side merge button, which runs no
local hook. The script's own header said that closing the gap needed a server-side CI job the
repo does not have.
- **The README already contradicted it.** Its "For external consumers" section says apm is the only
supported install path and never mentions `.pre-commit-hooks.yaml` or `rev:` pinning.
**What is unaffected.** This repo's `repo: local` hooks — `skill-size-check`,
`vale-audit-prefilter-skill` and `vale-audit-prefilter-agent` — were always wired separately from
the export, so no internal lint coverage is lost. The two prefilter hook IDs stay separate for the
file-scope reason in "One hook per file-scope" above, not for an external contract.
`tests/test-vale-wrap.sh` case 33, the cross-manifest `files:` drift check that ADR-0025 ported,
went with the manifest it compared against. Its one guard that did not need a second manifest, a
local regex narrowed to a single plugin, is now a third property of case 32. The `v1.0.0`, `v2.0.0`
and `v2.0.1` tags are left in place. They are inert: nothing reads them, and apm's `per_package`
versioning never consults `tagPattern`.
**What is preserved for a return.** The `entry[0]`-only constraint in the Consequences above, and
its incident records at `LESSONS.md:101` and `:105`, stay as written. That constraint says a
published entry is a bare script path, with every bundled file located from `${BASH_SOURCE[0]}`,
and it took three review rounds to find. Both hook scripts still meet it: `vale-wrap.sh` takes no
`--config`, and `skill-size-check.sh` keeps its embedded resolver copy. If a consumer appears,
restore the manifest under that constraint, and restore `test-vale-hooks-consumer.sh` with it: it
was the only test that exercised the entry-resolution path that once shipped broken. Restore a
release gate only once a server-side job can run it on merge.
**Superseded statements elsewhere.** ADR-0022's notes that the version-bump gate "is not exported
through `.pre-commit-hooks.yaml`" and that it shares its gaps with `check-release-needed`, and
ADR-0025's point 5 ("Both exported Vale hook IDs survive unchanged") and its case-33 port, describe
the state before this amendment.

View File

@@ -5,6 +5,11 @@ exact pair, scoped itself to them, and then deferred the work as issue #101. The
here. `skill-author` and `agent-author` stay separate — ADR-0020 excluded the author pair
deliberately, and nothing in this change touches that exclusion.
**Amended by ADR-0014 (2026-09-16).** The published `.pre-commit-hooks.yaml` is retired. Point 5
below (both exported hook IDs survive) and the case 33 port no longer describe the repo. Case 33 is
deleted, and its one-plugin narrowing guard is now a property of case 32. See
[ADR-0014's amendment](0014-vale-prefilter-ships-from-the-plugin.md#amendment-2026-09-16-the-external-hook-contract-is-retired).
## Context
Every figure below was measured against the worktree on 2026-09-15. Re-derive rather than quote; the