Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

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

Browse Source 
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>
This commit was merged in pull request #129.
This commit is contained in:
Claude Code AI - Gitea MCP
2026-09-01 13:47:46 +00:00
committed by Defame1297
parent 0e91a3ae66
commit 598a7c326a
420 changed files with 15303 additions and 4740 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
plugins/git/skills/pc-run/README.md
View File

@@ -24,6 +24,9 @@ Common invocations:
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions |
| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks |
| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs |
| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments |
| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires |
| `references/sources.md` | Provenance: research sources that informed this skill |
| `references/README.md` | Directory index for references/ |

120
plugins/git/skills/pc-run/SKILL.md
View File

@@ -1,13 +1,9 @@
---
name: pc-run
description: >
Use when the user wants to run pre-commit hooks, install git hooks, update
hook versions, or maintain the pre-commit cache. Triggers on: "run
pre-commit", "run all hooks", "check everything passes", "install hooks",
"wire hooks into git", "update hook versions", "autoupdate", "bump revs",
"clean the cache", "rebuild environments", "gc", "why is my hook failing",
"hooks aren't running". Do not use for creating or editing
`.pre-commit-config.yaml` — use `pc-author` for that.
Use when the user wants to run pre-commit hooks, wire them into git, bump hook
revs, maintain the cache, or diagnose why a hook fails or never fires. Not
creating or editing the pre-commit config -> `pc-author`.
compatibility: Requires pre-commit installed and available on PATH.
@@ -22,102 +18,44 @@ allowed-tools: Bash Read
## Gotchas
- Hooks not running on `git commit` almost always means `pre-commit install` was never run in this clone. Git hooks are per-clone — they are not committed to the repo.
- When a hook modifies files (e.g. `trailing-whitespace`, `end-of-file-fixer`), the commit is blocked intentionally — the staged version is stale. The fix is `git add -u && git commit`. Do NOT call `pre-commit install -f` here; that is for overwriting existing hooks, not re-staging.
- `pre-commit autoupdate` modifies `.pre-commit-config.yaml` in-place. Re-read the file after calling it to show the user the updated `rev` values.
- The `SKIP` env var requires exact hook `id` values, comma-separated, no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after the comma silently skips nothing.
- Never use `git commit --no-verify` (or `-n`) to bypass a failing hook. Hooks are the automated QA gate; bypassing them breaks the pipeline. Diagnose and fix the failure instead — see the hook-specific guidance below and in `references/failure-patterns.md`.
- A stages mismatch — hook stage not installed — means the hook was added to the config but `pre-commit install` was not re-run with the correct `-t` flags. Hooks in stages not listed under `default_install_hook_types` will never fire.
- The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring.
- Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead.
- `- files were modified by this hook` is not a bug. A fixer hook rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. Re-stage and re-run the same commit: `git add -u && git commit`. Do NOT reach for `pre-commit install -f` here — it overwrites `.git/hooks/` and has nothing to do with re-staging.
## Gate — `pre-commit clean`
Confirm with the user before running `pre-commit clean`, on every path that reaches it — including when it turns up as the fix for a stale or broken environment. It wipes the whole cache at `~/.cache/pre-commit`, which is machine-wide and shared by every repo on the box, forcing every hook environment to be re-downloaded.
> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
`pre-commit gc` drops only unused environments and needs no confirmation — prefer it when the goal is just to reclaim disk.
## Route
Determine intent from the user's request, then execute the matching operation:
Determine intent from the user's request, then execute the matching operation. Where the matching row names a `references/` file, read that one file and no other — each flow file is self-contained.
| User intent | Operation |
|---|---|
| "run", "check", "verify", "test hooks" | `pre-commit run --all-files` (default) |
| "staged", "simulate commit" | `pre-commit run` (staged files only) |
| "CI", "changed files only", "diff range" | `pre-commit run --from-ref <base> --to-ref <head>` — prefer this over `--all-files` on large repos |
| "install", "set up hooks", "wire into git" | `pre-commit install` — see Install |
| "pre-create environments", "install-hooks", "warm cache" | `pre-commit install-hooks` — see Install |
| "remove hooks", "uninstall", "tear down pre-commit" | `pre-commit uninstall` |
| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` |
| "gc", "garbage collect" | `pre-commit gc` |
| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — see Clean |
| "install", "set up hooks", "wire into git" | `pre-commit install` — read `references/install.md` |
| "pre-create environments", "warm cache" | `pre-commit install-hooks` — builds every hook environment without running a hook |
| "remove hooks", "uninstall", "tear down" | `pre-commit uninstall` — removes pre-commit from `.git/hooks/` |
| "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` |
| "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time |
| "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` |
| "hooks aren't running", "hook never fires", "why did a hook fail", a hook failure whose cause is unclear | Diagnose — read `references/failure-patterns.md` |
If the intent is ambiguous, default to `pre-commit run --all-files`.
If the intent is ambiguous, default to `pre-commit run --all-files` — do not stop to ask, and do
not fall through to a narrower row on a guess.
## Run
Default: `pre-commit run --all-files`. Never silently run staged-only.
Default to `pre-commit run --all-files`; never silently narrow to staged files. Run `pre-commit run` (staged only) or `pre-commit run <hook-id>` (one named hook) when the user asks for it.
```bash
pre-commit run --all-files
```
When hooks fail:
**When hooks fail**, read the output and:
1. Identify which hook failed and the specific cause. Be concrete: "gitleaks blocked `config.json` (high-entropy string on line 12)", not just "gitleaks failed".
2. Suggest a concrete next step. Common patterns are in `references/failure-patterns.md`.
3. Do NOT auto-fix code files. Do NOT modify `.pre-commit-config.yaml`. Those are the user's or `pc-author`'s responsibility.
If the user asks to run only staged files: `pre-commit run` (no `--all-files`).
If the user names a specific hook: `pre-commit run <hook-id>`.
## Install
Only run when the user explicitly asks to install or set up hooks.
Before running, check for existing hook files:
```bash
ls .git/hooks/
```
If any hook files exist (e.g. a hand-written `pre-commit`), `pre-commit install` does NOT refuse or error — it defaults to migration mode, which runs the existing hook and pre-commit's hooks both. Only `-f` replaces the existing hook file outright, and that replacement is not reversible via `pre-commit uninstall` — uninstall only removes pre-commit from `.git/hooks/`, it does not restore whatever hand-written hook `-f` overwrote. If files are present, tell the user: "Existing hook files found at `.git/hooks/<names>`. Plain `pre-commit install` will run both; `pre-commit install -f` will overwrite them permanently instead. Proceed with plain install, or overwrite?" Wait for confirmation before using `-f`.
```bash
pre-commit install
```
Re-run with `-t` flags when `default_install_hook_types` was changed or when hooks in non-default stages aren't firing:
```bash
pre-commit install -t pre-commit -t pre-push -t commit-msg
```
To pre-create all hook environments without running hooks (useful for CI warm-up or first-time setup):
```bash
pre-commit install-hooks
```
To remove pre-commit from `.git/hooks/` entirely:
```bash
pre-commit uninstall
```
## Autoupdate
```bash
pre-commit autoupdate
```
After it completes, read `.pre-commit-config.yaml` and report which `rev` values changed. If the user wants to pin to exact SHAs (for reproducibility): `pre-commit autoupdate --freeze`.
## Clean and GC
**`gc`** — removes only unused cached environments. Safe to run at any time:
```bash
pre-commit gc
```
**`clean`** — wipes the entire cache at `~/.cache/pre-commit`. All hook environments will be re-downloaded on next run. Require explicit confirmation before running:
> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
Wait for the user to say yes before executing:
```bash
pre-commit clean
```
1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed".
2. Suggest one concrete next step. Common causes and their concrete fixes are in `references/failure-patterns.md` — read it whenever the output does not already name the fix.
3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`.

5
plugins/git/skills/pc-run/references/README.md
View File

@@ -10,5 +10,8 @@ source_keys:
| File | Purpose |
|---|---|
| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when hooks fail |
| `install.md` | The install flow — read when the user asks to install or set up hooks |
| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs |
| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments |
| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires |
| `sources.md` | Provenance: research sources that informed this skill |

17
plugins/git/skills/pc-run/references/autoupdate.md Normal file
View File

@@ -0,0 +1,17 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Bumping hook revs with `autoupdate`
Reached from `SKILL.md`'s Route table when the user asks to update hook versions or bump revs. Self-contained.
```bash
pre-commit autoupdate
```
This rewrites `.pre-commit-config.yaml` in place, so re-read the file afterwards and report which `rev` values changed. It is the one operation in this skill that writes that file, and the exception is deliberate: the rewrite is pre-commit's own, resolved against the hook repos, not a hand edit — which is why `pc-author` hands rev bumps here rather than making them itself.
Add `--freeze` when the user wants exact SHAs pinned for reproducibility.

17
plugins/git/skills/pc-run/references/clean.md Normal file
View File

@@ -0,0 +1,17 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Wiping the pre-commit cache
Reached from `SKILL.md`'s Route table when the user asks to clean the cache or rebuild environments from scratch. The confirmation gate on `pre-commit clean` stays in `SKILL.md`, because it must fire on every path that reaches this command, not only this one.
## Gate
`pre-commit clean` runs only after the confirmation gate in `SKILL.md` clears — that gate, its exact wording, and the `pre-commit gc` alternative live there and are not restated here.
```bash
pre-commit clean
```

9
plugins/git/skills/pc-run/references/failure-patterns.md
View File

@@ -18,6 +18,8 @@ git add -u
git commit -m "same message"
```
Do NOT reach for `pre-commit install -f` here. That flag overwrites existing hook files in `.git/hooks/`; it has nothing to do with re-staging.
## Secret detected (gitleaks)
> Not sourced from the pre-commit research corpus (`context7-pre-commit-com`/`pre-commit-com` cover pre-commit itself, not gitleaks) — general tool knowledge, verify against gitleaks' own docs if precision matters.
@@ -87,13 +89,14 @@ Fix: The user (or `pc-author`) must add `args: [--autofix]` to the hook override
Cause: A hook's cached environment is corrupted or out of date.
Fix:
Fix: `pre-commit clean` is gated. It wipes the machine-wide cache at `~/.cache/pre-commit`, shared by every repo on the box, so get explicit confirmation before running it — "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
```bash
pre-commit clean # wipe all environments
pre-commit clean # gated — confirm with the user first
pre-commit install-hooks # rebuild everything
```
Or less destructively:
Or less destructively, needing no confirmation:
```bash
pre-commit gc # remove only unused environments
```

31
plugins/git/skills/pc-run/references/install.md Normal file
View File

@@ -0,0 +1,31 @@
---
source_keys:
- context7-pre-commit-com
- pre-commit-com
---
# Installing hooks into `.git/hooks/`
Reached from `SKILL.md`'s Route table when the user asks to install or set up hooks. Self-contained.
Only run this flow when the user explicitly asks for it. Installing rewrites their clone's `.git/hooks/`; it is never a side effect of another request.
## Gate — existing hook files
Check `ls .git/hooks/` first. With hook files already there, `pre-commit install` does not refuse — it silently enters migration mode and runs both. Only `-f` replaces them, and `pre-commit uninstall` cannot restore whatever `-f` overwrote.
So when hook files are present, put the choice to the user in these terms, including the irreversibility, and wait for an answer before passing `-f`:
> "Existing hook files found in `.git/hooks/`. Plain `pre-commit install` runs both; `-f` overwrites them permanently and `pre-commit uninstall` cannot restore them. Plain install, or overwrite?"
## Install
```bash
pre-commit install
```
Re-run with `-t` flags when `default_install_hook_types` changed, or when hooks in a non-default stage never fire — a hook whose stage was never installed cannot run:
```bash
pre-commit install -t pre-commit -t pre-push -t commit-msg
```

4
plugins/git/skills/pc-run/references/sources.md
View File

@@ -4,7 +4,7 @@
- **URL:** context7:/pre-commit/pre-commit.com
- **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting
- **Contributing files:** SKILL.md, references/failure-patterns.md
- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
- **Status:** `extracted`
@@ -12,7 +12,7 @@
- **URL:** https://pre-commit.com/
- **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration
- **Contributing files:** SKILL.md, references/failure-patterns.md
- **Contributing files:** SKILL.md, references/install.md, references/autoupdate.md, references/clean.md, references/failure-patterns.md
- **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,cli-reference,troubleshooting}.md
- **Status:** `extracted`