refactor(skills): retrofit the corpus to the ADR-0020 context contract (#129)

Retrofits all 39 skills to ADR-0020's description/body context contract, then fixes what six rounds of independent review found in that retrofit — including four ways the hot gate itself failed open.

Closes #99, #107, #108, #110, #111, #114, #115, #120.

## The retrofit (waves 1-5)

| | Start | Now |
|---|---|---|
| Description FAILs (>400 chars) | 26 | **0** |
| Body FAILs (>900 words, body-only) | 9 | **0** |
| Dangling routing targets | 2 | **0** |
| `Kyberforge.CompositionNote` | 10 | **0** |
| Preload tax | 21,005 chars | **~10,500** |

Under the 12,000-char success criterion. Per-wave detail is on #99.

## The review fixes

**The gate failed open four ways, three of them found after the retrofit shipped.** An unrecognised follower token made a dangling target vanish. A skill directory with no `SKILL.md` resolved as a valid target, so a commit could be green locally and red in a fresh clone — three existing fixtures were relying on that, one of which made the install-leak A/B pass vacuously. Then the free-standing `/name` sweep turned out to be gated on the sentence carrying a boundary marker, so route notation in any other sentence was invisible — not an ERROR, not a SUGGESTION, not an INFO — which left the documented "`/name` always blocks" promise false from a second direction. All four fixed and pinned.

**Two checks were silently not running.** `validate-provenance.sh` checks 7-8 were dead across nine skills. Waking them exposed a deeper problem: they assume `Research doc:` names a source index, but 30 of 121 entries point at topic content documents, so every new check-7 INFO was a false positive and check 8 was saved from a false-FAIL flood only by an *unannounced* skip. Checks 7/8 are now scoped to source indexes and every skip announces itself (#121).

**The retrofit's own anti-goal, four times.** ADR-0020 warns that a blunt gate gets satisfied by deleting content rather than relocating it. `diagnose` and `skill-audit` relocated prose and then read it unconditionally; `prototype` and `vale-config` deleted rules outright that survived nowhere. All four addressed.

## Verification

- `bash tests/run-tests.sh --strict` — 24 suites, 0 skipped, 0 failed
- `bash tests/run-bats.sh` — 325 tests, 0 failures
- `pre-commit run --all-files` — 17/17
- `pre-commit run --hook-stage pre-push --all-files` — 16/16, with `apm marketplace check` and `apm pack --check-clean` run against the remote, not skipped
- `scripts/skill-size-check.sh` over all 39 skills — rc 0, 0 ERROR/FAIL, SUGGESTION-only
- Preload tax measured at **10,498 chars**, max description 390 — both inside budget
- Every new test proven non-vacuous by a deliberate mutation of the behaviour it covers

**Per-commit sync, stated accurately:** the ten commits from the latest review round each pass `check-plugin-content-sync` in isolation, verified by checking each out in a detached worktree with a clean between. The earlier gitea window (`dfacf05..bedbd1d`, nine commits) does **not** — its mirror was regenerated in one batch at `bbc7300`. An earlier revision of this description claimed the property held for every commit; it does not, and a bisect through that window lands on a red commit. **Squash-merge** to collapse it, or accept that this range is not bisectable.

## Version bump

Six plugins and the catalog take a **patch**, not a minor. The branch is **89 commits — 40 `fix` / 30 `refactor` / 12 `docs` / 5 `chore` / 2 `test` — zero `feat`, zero `!`, zero `BREAKING CHANGE`** — and adds no skill, agent, command or hook. (Two earlier revisions of this section cited a stale histogram, most recently 78 commits; the figures above are measured at HEAD.) Both rules this repo ships (`forge/references/version-bump.md`, landing in this PR, and `git-commits/references/conventional-commits-spec.md`) make that a patch, and the catalog set is unchanged at 7 entries.

Not settled by that: four published files were removed from the installed tree, three moved, and `caveman` gained `disable-model-invocation`, retiring its old triggers. Under a strict reading those are major-class and currently ship under `refactor:` with no marker. Whether the deployed skill surface is a public contract is written down nowhere — worth deciding, but it outlives this PR.

## Deliberately not in scope

#112 (cherry-pick ownership, now resolved in favour of `git-commits`), #113 (`rtk git` normalisation), #116 (research fan-out), #101 (audit-skill merge), #122 (non-spec skill-root files), #123 (no PRD producer) stay open. #117 is the one worth reading: the contract's remedy is to move prose into `references/`, which is exactly where neither the size gate nor Vale looks — and the blind spot is wider than #117 currently records, since there is no root `.vale.ini` at all, so every ADR, `CONTEXT.md` and `README.md` is unlinted too.

That blind spot let this branch carry two `level: error` `Kyberforge.SentenceOpenerThereIs` violations into `references/` files it created — `provider-adapter-author/references/provider-matrix.md:31` and `agent-audit/references/finding-criteria.md:95`. Both are reworded in `afadaae`, confirmed by routing each file through the audit's own `vale-wrap.sh` (1 error each before, 0 after). Five further occurrences sit in `references/` files already on `main`; those are the pre-existing corpus and stay with #117, which is the real fix.

Also unfixed and not this PR's: `apm install` appends a duplicate `SessionStart` entry to `.claude/settings.json`, so a fresh clone cannot get pre-push green without an edit AGENTS.md warns against. Reproduces identically on `main`.

Co-authored-by: Defame1297 <gitea@rkdr.net>
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/129
Co-authored-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>
Co-committed-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>

plugins/git/skills/git-commits/references/cherry-pick.md

@@ -0,0 +1,12 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Cherry-picking a commit
+
+1. **Identify the source commit** — a hash or a branch reference.
+2. **Confirm the destination** — cherry-pick replays onto the branch currently checked out, so verify that is the intended branch before running anything.
+3. **Execute** — `rtk git cherry-pick <commit-hash>`. A range is `<a>..<b>` (exclusive of `<a>`) or `<a>^..<b>` (inclusive); `-n` stages without committing, for when the replay needs editing first.
+4. **Handle conflicts** — if the replay halts, offer resolution or `rtk git cherry-pick --abort`. Never resolve automatically without confirmation.
+5. **Report the outcome** — which commits replayed, which conflicted, and which were rejected.

plugins/git/skills/git-commits/references/commit-template.md

@@ -7,7 +7,7 @@ source_keys:
 
 Use this structure for the body/footer of any non-trivial commit (skip sections that don't apply — do not leave placeholders in the actual commit).
 
-```
+```text
 <type>(<scope>): <concise summary>
 ```
 The header is required. Describe the intended outcome, not the implementation.
@@ -53,7 +53,7 @@ Omit if there are no noteworthy impacts.
 
 Structured metadata for traceability and tooling. Use only the trailers that apply:
 
-```
+```text
 Fixes:
 Refs:
 ADR:

plugins/git/skills/git-commits/references/conventional-commits-spec.md

@@ -10,7 +10,7 @@ Conventional Commits is a lightweight convention on top of commit messages that
 
 ## Message Format
 
-```
+```text
 <type>[optional scope]: <description>
 
 [optional body]
@@ -58,20 +58,20 @@ A `BREAKING CHANGE` footer or `!` on **any** type always triggers a MAJOR bump.
 Two equivalent notations:
 
 **`!` in header** (preferred — visible in `git log --oneline`):
-```
+```text
 feat!: drop support for Node 6
 feat(api)!: remove deprecated endpoint
 ```
 
 **`BREAKING CHANGE` footer** (machine-readable body):
-```
+```text
 feat: allow config to extend other configs
 
 BREAKING CHANGE: `extends` key now used for extending config files
 ```
 
 **Both together** (most explicit):
-```
+```text
 feat!: drop support for Node 6
 
 BREAKING CHANGE: use JavaScript features not available in Node 6.
@@ -85,7 +85,7 @@ Rules:
 
 ## Footer Token Rules
 
-```
+```text
 <token>: <value>
 <token> #<value>    # for issue references
 ```
@@ -96,7 +96,7 @@ Rules:
 - Blank line required before the footer block.
 
 Valid footer examples:
-```
+```text
 Reviewed-by: Z
 Refs: #123
 Co-authored-by: Alice <alice@example.com>
@@ -106,29 +106,29 @@ BREAKING CHANGE: the `--format` flag now requires a value
 ## Examples
 
 Minimal — no body, no footer:
-```
+```text
 docs: correct spelling of CHANGELOG
 ```
 
 With scope:
-```
+```text
 feat(lang): add Polish language
 ```
 
 Breaking change via `!`:
-```
+```text
 feat!: send an email to the customer when a product is shipped
 ```
 
 Breaking change via footer:
-```
+```text
 feat: allow provided config object to extend other configs
 
 BREAKING CHANGE: `extends` key in config file is now used for extending other config files
 ```
 
 Multi-paragraph body with multiple footers:
-```
+```text
 fix: prevent racing of requests
 
 Introduce a request id and a reference to latest request. Dismiss
@@ -142,7 +142,7 @@ Refs: #123
 ```
 
 Revert:
-```
+```text
 revert: let us never again speak of the noodle incident
 
 Refs: 676104e, a215868

plugins/git/skills/git-commits/references/create-commit.md

@@ -0,0 +1,17 @@
+---
+source_keys:
+  - conventional-commits-spec
+  - commitlint-config-conventional
+  - org-commit-conventions
+---
+
+# Creating a new commit
+
+1. **Gather context** — what changed and why, from the staged diff, the PR description, or the issue. Confirm the staged diff is one logical, independently reviewable and reversible change that leaves the repository buildable and testable. If it bundles unrelated work, suggest splitting it before going further.
+2. **Determine the type** — read it off the change itself: a new user-visible feature is `feat`, a bug fix is `fix`. For the full 11-type set and each type's SemVer impact, read `references/conventional-commits-spec.md`.
+3. **Determine the scope** — use the scope from plugin config where one is set, otherwise infer it from the files changed (`api`, `db`, `cli`, `config`). Scope is optional, but it identifies which part of the system moved and is worth setting.
+4. **Write the description** — imperative mood, no trailing period: "add user authentication", "fix race condition in cache". Neither source spec sets a target below the 100-character header maximum, but convention favours roughly 50 characters so `git log --oneline` stays readable.
+5. **Add a body when the change is non-trivial** — blank line first, wrapped at 100 characters. Explain *why*, not what: the diff already shows what changed, and the message's job is the context the diff cannot carry — motivation, root cause, tradeoffs. Follow the Why / Implementation Notes / Impact structure in `references/commit-template.md`.
+6. **Add footers where they apply** — `Fixes: #123`, `Refs: #123`, `ADR: 0012`, `Co-authored-by: Name <email>`, `BREAKING CHANGE: description`. For the full trailer list, read `references/commit-template.md`.
+7. **Signal a breaking change with `!` before the colon** — `feat!: drop Node 6` is visible in `git log --oneline`, where the `BREAKING CHANGE:` footer alone is machine-readable but hidden. Use both when the break needs describing.
+8. **Validate, confirm, execute** — check header length, type, lowercase subject and trailing period against commitlint, show the message, and commit only once the caller has approved. Never add `--no-verify`.

plugins/git/skills/git-commits/references/rewrite-history.md

@@ -0,0 +1,76 @@
+---
+source_keys:
+  - org-commit-conventions
+  - context7-git-htmldocs
+---
+
+# Rewriting existing commits
+
+Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead.
+
+## Amend the last commit
+
+1. Stage the new changes, or the changes that undo something.
+2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is.
+3. If the message should change, show the current one and prompt for the replacement.
+4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding.
+
+## Fold a commit into an earlier one (autosquash — preferred)
+
+Prefer this whenever a commit is written to be folded, because git does the marking:
+
+1. `rtk git commit --fixup=<commit>` keeps the target's message; `rtk git commit --squash=<commit>` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit.
+2. Get explicit approval — the rebase still rewrites history.
+3. Run `rtk git rebase -i --autosquash HEAD~N`. Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply.
+
+**`-i` is not optional here.** On Git 2.39.5, `rtk git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/<branch>.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that.
+
+## Squash by hand (interactive rebase)
+
+Use this when the commits were not tagged at commit time. **Interactive rebase has no undo once `rebase -i` starts — `git reflog` is the recovery path.**
+
+1. Identify the commits to squash — typically the last N on the current branch.
+2. Get explicit approval.
+3. Run `rtk git rebase -i HEAD~N`, marking the older commits `squash` to keep their messages for editing, or `fixup` to discard them.
+4. Compose the combined message when the rebase stops to ask. For a non-trivial combined message, follow the structure in `references/commit-template.md`.
+
+## When a rebase halts on a conflict
+
+Offer conflict resolution or `rtk git rebase --abort`. Do not resolve conflicts automatically without confirmation.
+
+## Rebase the branch onto a new base
+
+Replays this branch's commits on top of another branch's tip — bringing a feature branch up to
+date without a merge commit.
+
+1. Confirm nothing being replayed has been pushed anywhere someone else has based work on. A rebase
+   gives every replayed commit a new SHA, which breaks any clone that already has the old ones.
+2. Get explicit approval — this rewrites history like every other flow on this page.
+3. `rtk git fetch origin` first, so `<newbase>` is the real tip rather than a stale local copy.
+4. `rtk git rebase <newbase>` — for example `rtk git rebase main`. Use
+   `rtk git rebase --onto <newbase> <upstream> <branch>` to replay only the commits after
+   `<upstream>`, which is how a branch started from the wrong base gets moved.
+5. The branch has now diverged from its remote. It needs
+   `--force-with-lease --force-if-includes` to push, never a bare `--force`, and never on
+   `main`/`master` — refuse that and explain.
+
+## Move the branch pointer back (`git reset`)
+
+`reset` moves the current branch to another commit. The mode decides what survives:
+
+| Mode | Branch pointer | Index | Working tree |
+|---|---|---|---|
+| `--soft` | moves | untouched — the changes stay staged | untouched |
+| `--mixed` (default) | moves | reset — the changes become unstaged | untouched |
+| `--hard` | moves | reset | **overwritten; uncommitted work is destroyed** |
+
+- "Undo my last commit but keep the changes" is `rtk git reset --soft HEAD~1`. That is the default
+  answer to the request; reach for anything else only when the caller asked for it.
+- `rtk git reset --mixed HEAD~1` when the staging should be redone from scratch too.
+- `rtk git reset --hard <ref>` is gated like a force-push: state exactly which uncommitted changes
+  will be discarded, get approval for that specific reset, and offer `rtk git stash push -u` first.
+  The commits it drops stay reachable through `git reflog`; the uncommitted edits never entered git
+  at all and nothing recovers them.
+
+Reset does not rewrite the commits it leaves behind, so no force-push is needed unless the branch
+was already pushed at the newer commit.

plugins/git/skills/git-commits/references/sources.md

@@ -7,34 +7,34 @@ source_keys:
   - context7-git-htmldocs
 ---
 
-# Research Sources for git:commits Skill
+# Research Sources for git-commits Skill
 
-Sources extracted from the git plugin research phase. Only sources that directly informed this skill are listed; sibling skills (git:branches, git:history, git:remotes, etc.) have their own sources.md.
+Sources extracted from the git plugin research phase. Only sources that directly informed this skill are listed; sibling skills (git-branches, git-history, git-remotes, etc.) have their own sources.md.
 
 ## conventional-commits-spec
 
 - **Description:** Conventional Commits Specification (v1.0.0) — message format, types, breaking changes, footer rules
 - **Research doc:** plugins/git/docs/research/docs/git/commits.md § "Conventional Commits Specification (v1.0.0)"
-- **Contributing files:** SKILL.md, references/conventional-commits-spec.md
+- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
 - **Status:** extracted
 
 ## commitlint-config-conventional
 
 - **Description:** commitlint config-conventional preset — validation constraints (max 100 chars header, no trailing periods, lowercase type, 11-type set enforcement)
 - **Research doc:** plugins/git/docs/research/docs/git/commits.md § "commitlint Constraints (`config-conventional`)"
-- **Contributing files:** SKILL.md, references/conventional-commits-spec.md
+- **Contributing files:** SKILL.md, references/conventional-commits-spec.md, references/create-commit.md
 - **Status:** extracted
 
 ## org-commit-conventions
 
 - **Description:** Organization commit message body template and git conventions (atomic commits, no `--no-verify`, no force-push main/master, `rtk git` wrapper) — content fully embedded in this skill; the org's `core/instructions/git.md` and `core/instructions/commits.md` are provenance only and are not a live dependency
 - **Research doc:** core/instructions/commits.md, core/instructions/git.md (org convention, not part of the plugin's research corpus)
-- **Contributing files:** SKILL.md, references/commit-template.md
+- **Contributing files:** SKILL.md, references/commit-template.md, references/create-commit.md, references/rewrite-history.md
 - **Status:** extracted
 
 ## context7-git-htmldocs
 
-- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup` and `git rebase --autosquash` flag semantics
-- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md
-- **Contributing files:** SKILL.md
+- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup`, `git rebase --autosquash`, and `git cherry-pick` range and abort semantics
+- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md § "Committing", § "Rebasing", § "Cherry-picking"
+- **Contributing files:** SKILL.md, references/rewrite-history.md, references/cherry-pick.md
 - **Status:** extracted