ci: harden the doc extractors, and give skill discovery one predicate

CLAUDE.md

@@ -67,10 +67,13 @@ Conventional Commits, enforced by commitlint (husky `commit-msg` hook) and consu
 semantic-release. Two repo-specific rules:
 
 - Commits of type `feat|fix|perf|refactor|style|revert` **must** use a scope of `bulma-ui`, `docs`,
-  `create-bestax`, `bestax-migrate`, or `bestax-mcp` — unscoped release types are rejected
+  `create-bestax`, `bestax-migrate`, or `bestax-mcp` — an unscoped commit of any of these
+  scope-gated types is rejected
   (`RELEASE_SCOPES` in `commitlint.config.js` is the source of truth). One exception worth
   knowing: commitlint's default ignores skip git's own `Revert "…"` messages, so the hook cannot
-  reject an unscoped revert in that form — keep reverts conventional and scoped by hand.
+  reject an unscoped revert in that form — keep reverts conventional and scoped by hand, and
+  know that a scoped revert releases nothing: ship a rollback as `fix(<scope>)` (see
+  VERSIONING.md for why).
 - **Packages release independently, keyed off the scope**: `feat(bulma-ui)` bumps only
   `@allxsmith/bestax-bulma`; `fix(create-bestax)` bumps only `create-bestax`. The
   `releaseRules` in each package's `release.config.js` are the source of truth.

CONTRIBUTING.md

@@ -371,13 +371,17 @@ commitlint via the husky `commit-msg` hook ([`commitlint.config.js`](./commitlin
 - **Release types need a scope:** commits of type `feat`, `fix`, `perf`, `refactor`, `style`
   or `revert` **must** use a scope of `bulma-ui`, `docs`, `create-bestax`, `bestax-migrate`
   or `bestax-mcp` (repo-specific commitlint rule — the scope decides which package releases,
-  see [`VERSIONING.md`](./VERSIONING.md)). `revert` is in that list because
-  commit-analyzer ships `{ revert: true, release: 'patch' }`, so an unscoped revert would
-  match no package's negated-scope suppression and patch-release **all** of them. Note the
-  residual, which `commitlint.config.js` records: that rule fires on the parser's
-  `revertPattern` — git's own `Revert "…"` form — and commitlint's default `ignores` skip
-  those messages entirely, so scoping is a convention here rather than something the hook
-  can enforce. Keep reverts conventional and scoped. `RELEASE_TYPES` and `RELEASE_SCOPES`
+  see [`VERSIONING.md`](./VERSIONING.md)). One correction worth knowing about `revert`:
+  a scoped conventional `revert(<scope>): …` **releases nothing** — the only revert rule is
+  commit-analyzer's default `{ revert: true, release: 'patch' }`, keyed on the angular
+  `revertPattern`, which matches a `Revert "…"` **or** bare `revert: …` header followed by a
+  `This reverts commit <sha>` body; a parenthesized `revert(<scope>):` header matches
+  neither. The two detected forms differ in what fences them: an unscoped `revert: …` is
+  rejected by commitlint's scope rule before it can land, while git's own `Revert "…"` form
+  is skipped by commitlint's default `ignores` entirely — and its generated body **does**
+  trip the default patch rule for every package, making it the real hazard. So keep reverts
+  conventional and scoped, and ship an actual rollback release as a follow-up
+  `fix(<scope>): …`. `RELEASE_TYPES` and `RELEASE_SCOPES`
   in `commitlint.config.js` are the source of truth.
 - **Breaking changes** need a `BREAKING CHANGE:` footer in the body — a `!` after the type is
   **not** picked up by our release tooling.

SECURITY.md

@@ -50,9 +50,11 @@ Measures active in this repository and its release pipeline:
   `publishConfig.provenance` — having one would imply the flag was redundant,
   and dropping the flag is the quiet way to lose attestations entirely. The
   `prepack`/`prepublishOnly` guards refuse packers they recognise as not being
-  pnpm. They do not refuse a hand-run `pnpm publish` that omits the flag; the
-  `prepublishOnly` hook warns about it instead, and only outside CI, so that
-  inspecting a tarball with `pnpm pack` stays quiet. Why it works that way is in
+  pnpm. They cannot see CLI flags at all, so they do not refuse a hand-run
+  `pnpm publish` that omits `--provenance`; the `prepublishOnly` hook prints an
+  unconditional reminder on every non-CI hand publish — including one that
+  passes the flags correctly — and only outside CI, so that inspecting a
+  tarball with `pnpm pack` stays quiet. Why it works that way is in
   [`VERSIONING.md`](./VERSIONING.md#release-process).
 - **Licence text comes from the workspace root** — no package carries its own
   `LICENSE` file, and `pnpm publish` copies the root one into every tarball.

VERSIONING.md

@@ -31,16 +31,22 @@ Notes:
 
 - **Breaking changes require a `BREAKING CHANGE:` footer** in the commit body. The angular
   commit-analyzer preset does **not** parse `feat(bulma-ui)!:` bang headers.
-- Commits of a releasing type (`feat`, `fix`, `perf`, `refactor`, `style`, `revert`) **must**
+- Commits of a scope-gated type (`feat`, `fix`, `perf`, `refactor`, `style`, `revert`) **must**
   carry a scope of `bulma-ui`, `docs`, `create-bestax`, `bestax-migrate`, or `bestax-mcp` —
   enforced by commitlint ([`commitlint.config.js`](./commitlint.config.js)) via the husky
   `commit-msg` hook. This is what guarantees the per-scope release rules can't be bypassed by
   an unscoped commit.
-- `revert` is scope-gated too: commit-analyzer's default rules ship
-  `{ revert: true, release: 'patch' }`, so an unscoped revert would patch-release **every**
-  package. A scoped `revert(bulma-ui): …` patch-releases only its package. Caveat: commitlint's
-  default ignores skip git-revert-style `Revert "…"` messages entirely, so keep reverts in
-  conventional form.
+- `revert` is scope-gated too, but a scoped revert **releases nothing** — plan rollbacks
+  accordingly. The only revert rule anywhere is commit-analyzer's default
+  `{ revert: true, release: 'patch' }`, keyed on the parser's revert _detection_, and the
+  angular `revertPattern` matches only a `Revert "…"`/`revert: …` header followed by a
+  `This reverts commit <sha>` body — a scoped `revert(bulma-ui): …` header is invisible to
+  it, and no `releaseRules` entry here names the `revert` type. To actually publish a
+  rollback, follow the revert with `fix(<scope>): …` (or commit the rollback as a `fix`
+  directly). The hazard runs the other way for git's own `Revert "…"` form, which
+  commitlint's default ignore rules let through unexamined: with its generated body it trips the default
+  revert rule with **no scope to confine it** and would patch-release every package — so
+  keep reverts in conventional, scoped form, and don't expect them to publish on their own.
 - A commit scoped to `docs` never releases any package.
 
 ## Tags & Changelogs

docs/docs/guides/getting-started/contributing.md

@@ -168,10 +168,14 @@ drive [semantic-release](https://semantic-release.gitbook.io/). Releasing types
 `perf`, `refactor`, `style`, `revert`) must carry one of the scopes in `RELEASE_SCOPES`
 (`bulma-ui`, `docs`, `create-bestax`, `bestax-migrate`, `bestax-mcp`); `docs`, `chore`, `ci`,
 `build`, and `test` don't publish — note `docs` is both a valid scope and a non-releasing
-type, so `docs(bulma-ui):` and `docs:` alike publish nothing. `revert` is release-triggering because commit-analyzer
-patch-releases reverts by default, so an unscoped one would bump every package — though
-commitlint's default ignores skip git's own `Revert "…"` form, so scoping that one is a
-convention the hook cannot enforce. Publishing uses npm **OIDC trusted publishing** with **provenance**
+type, so `docs(bulma-ui):` and `docs:` alike publish nothing. A scoped `revert(scope):`
+commit releases **nothing** — the only revert rule is commit-analyzer's default, and its
+`revertPattern` matches a `Revert "…"` or bare `revert: …` header (never the parenthesized
+`revert(scope):` form) followed by a `This reverts commit <sha>` body; ship a rollback with a
+follow-up `fix(scope):` commit. An unscoped `revert: …` is stopped by commitlint's scope rule,
+but git's own `Revert "…"` form is the real hazard: commitlint's default ignore rules let it
+through unexamined, and its generated body trips the default revert rule with no scope to
+confine it, so it would patch-release every package. Publishing uses npm **OIDC trusted publishing** with **provenance**
 (no long-lived token). See [`CONTRIBUTING.md`](https://github.com/allxsmith/bestax/blob/main/CONTRIBUTING.md)
 for the full details.