docs: record subagent outcomes for findings 2, 31, 38

Three findings from the simplification audit were independently
re-verified before execution, corrected, then implemented by
subagents:

- Finding 2 (check-executables-allow-sync): the audit's "drop it"
  option was found unsafe (ADR-0019 calls this failure mode silent,
  not "visible and recoverable" as claimed); shrunk instead of
  deleted, 231 -> 222 lines.
- Finding 31 (CONTEXT.md): "most terms unused by skills" was found
  overstated (13 of 28 are model-facing must-keeps); cut only the
  9 confirmed true orphans, 28 -> 19 terms. Also de-referenced one
  dangling pointer to a deleted term in the Flagged-ambiguities
  section.
- Finding 38 (pc-author/pc-run): line count was found overstated
  (598 actual vs. 689 claimed); trimmed the two generic reference
  files by 60 lines while preserving house-specific content.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD

CONTEXT.md

@@ -14,22 +14,6 @@ decisions.
 
 ### Context cost
 
-**Preload tax**:
-The always-on context cost of every installed skill's `name` and `description`, charged from the
-first token of every session whether the skill is invoked or not. Measurement method: ADR-0020. Its
-**23,427 characters is the pre-retrofit baseline, not a current reading** — measured at the decision
-commit, before #99. Across the same 39 skills it is **10,478 characters** (~2,620 tokens) as of
-2026-09-01. Both figures move with the corpus, so re-derive rather than quote either: sum
-`len(name) + len(description)` over the frontmatter of every `plugins/*/.apm/skills/*/SKILL.md`,
-folding block scalars as `scripts/skill-size-check.sh` does.
-_Avoid_: context cost, token overhead
-
-**Skill context contract**:
-The ADR-0020 authoring rules that hold the preload tax and body size down — a description carries a
-trigger clause, at most one capability clause, and a boundary clause, and nothing else. Thresholds
-and the target-resolution walk: `docs/spec/gates.md`.
-_Avoid_: skill budget, size limit
-
 **Routing target**:
 The skill or agent name a boundary clause sends work to. It **resolves** when a skill or agent of
 that name is reachable from the file being checked, and **dangles** when none is — a route the router
@@ -76,12 +60,6 @@ The unit apm builds and installs — `plugins/<name>/apm.yml` plus the hand-auth
 `plugins/<name>/.apm/` tree it compiles from (ADR-0015).
 _Avoid_: plugin directory, source tree
 
-**Content mirror**:
-The generated flat `skills/`, `agents/`, `commands/`, `instructions/`, `extensions/` directories and
-merged `hooks/hooks.json` at a plugin root — also called the flat mirror — compiled from that
-plugin's `.apm/` tree so hosts that convention-scan those paths discover the content (ADR-0017).
-_Avoid_: generated copy, duplicate tree
-
 **Output profile**:
 An `apm pack` target format for a generated *marketplace* manifest; apm has `claude`
 (`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped
@@ -99,12 +77,6 @@ This repository, in its role as a plugin marketplace and as the remote the six p
 resolve against.
 _Avoid_: the marketplace, upstream
 
-**apm-consumed install**:
-How this repo installs its own plugins as of 2026-08-14 — six `dependencies.apm` entries in the root
-`apm.yml` deployed by `apm install`, rather than `claude plugin install <name>@holocron`. Its
-consequences: ADR-0018.
-_Avoid_: apm install, dependency install
-
 **Provenance chain**:
 The three-stage traceability record linking a skill back to its research inputs: `/research` produces
 topic docs and a `sources.md`; the author skill records which sources informed which files in
@@ -120,18 +92,6 @@ irreversible or high-stakes actions — architecture changes, production deploym
 configuration.
 _Avoid_: manual approval, gated action
 
-**HOTL** (human-on-the-loop):
-The agent acts and a human monitors, able to intervene after the fact. Acceptable only for
-low-stakes, bounded, reversible actions where the cost of pausing exceeds the blast radius of an
-error.
-_Avoid_: autonomous, unsupervised
-
-**Sycophancy**:
-The failure mode where an RLHF-trained model prioritises approval over accuracy — changing a correct
-answer to a wrong one under user pressure, then persisting in the wrong answer. Treated here as a
-first-class reliability risk, not a quality-of-life concern.
-_Avoid_: agreeableness, people-pleasing
-
 ### Documents
 
 **AGENTS.md**:
@@ -149,12 +109,6 @@ _Avoid_: wrapper, shim, provider file
 The long-loop feedback log for patterns observed across sessions, at the repo root.
 _Avoid_: changelog, retro, postmortem
 
-**Management Application**:
-A separate product in a separate repo for browsing, editing, and configuring AI development configs
-through a product UI, with Git as an invisible persistence layer. Repo-agnostic; this repo is its
-canonical default content. Roadmap: `docs/VISION.md`.
-_Avoid_: the UI, the dashboard, the app
-
 ### Quality
 
 **Skill composition**:
@@ -162,11 +116,6 @@ A skill calling another skill by name to delegate a sub-task — the caller owns
 decision ("when to do X"), the callee owns the mechanics ("how to do X").
 _Avoid_: chaining, nesting, sub-skill
 
-**Vale audit prefilter**:
-The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Description dimension,
-so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`.
-_Avoid_: linting, style check
-
 **Authoring root**:
 The directory a gate resolves against — the nearest ancestor of the file being checked holding
 `plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding
@@ -179,11 +128,6 @@ sibling that would wrongly answer it; boundary clauses exist to exclude genuine
 than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`.
 _Avoid_: overlap, similar skill
 
-**Vacuous green**:
-A check that reports success because it measured nothing — zero files scanned, an unparsed value read
-as empty, a conditional branch that never armed.
-_Avoid_: false pass, clean run
-
 **Issue**:
 The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker
 (ADR-0007), but skills say "linked issue" generically rather than naming a provider.
@@ -193,18 +137,12 @@ _Avoid_: ticket, card, task
 
 - A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**;
   **holocron** is this repo wearing that hat.
-- Every model-invocable **Skill** pays the **Preload tax**. A **Hand-invoked skill** does not — which
-  is the first question to settle when authoring one.
-- The **Skill context contract** bounds both the **Preload tax** (description) and the body.
-  A **Dispatch body** is how a skill stays inside it; **Delegation discipline** is how an agent does.
 - **AGENTS.md** is the source of always-on rules; a **Thin adapter** imports it and originates
   nothing.
 - **Skill composition** is the caller/callee split. `forge` routes a genuinely *undecided* artifact
   type to the matching author skill — an already-specified fix (file, line, and change known) calls
   that author skill directly, because each routing hop re-derives instructions from a shorter brief
   and has been observed to drop hard constraints handed down the chain.
-- **HITL** and **HOTL** are exclusive per action class, and the choice must be explicit and
-  documented. **Sycophancy** is why HOTL is not the safe default.
 - A **Skill** built on research carries a **Provenance chain**; `skill-audit` fails it when broken.
 - **LESSONS.md** feeds the standing files: three or more entries on one pattern graduate the pattern
   into the relevant standing document.
@@ -233,8 +171,8 @@ _Avoid_: ticket, card, task
 - Skills can answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), depending on
   whether a native install exists at user scope alongside the apm one (ADR-0018) — resolved: write
   the bare name, which is the only form `apm install` produces.
-- "context" means both the model's live token window (the **Preload tax** sense) and the bounded
-  domain this file describes — resolved: unqualified "context" in this repo means the token window.
+- "context" means both the model's live token window and the bounded domain this file describes —
+  resolved: unqualified "context" in this repo means the token window.
 - "audit" was used for both an author skill's inline closeout and `forge`'s independent
   clean-context recheck — resolved: these are two distinct layers, kept separate precisely because
   an audit running in the same context as the work it checks shares that work's blind spots.

SIMPLIFICATION-AUDIT.md

@@ -66,7 +66,8 @@ This is the area you named as hardest to understand and slowest. Root cause: mos
    - `check-vale-style-sync`: 413 lines + 798 test lines guarding a byte-identical 526-line `vale-wrap.sh` and style directory copied between skill-audit and agent-audit. About 350 of its lines run Vale glob probes against the hook file patterns. Disappears if the two audit skills merge (finding 14); the probes belong in `test-vale-wrap.sh`.
    - `check-scope-walkup-sync`: 365 lines cross-checking four independent ports of the same package-root walk-up. Disappears if the ports share one script or the skills merge.
    - `check-marketplace-mirror-sync`: guards `.github/plugin/marketplace.json`. The script header calls it Copilot's legacy convention path and says Copilot also accepts the Claude path; the vendored Copilot docs list it as primary. Verify against current Copilot CLI before deleting hook, script, test, and mirror file.
-   - `check-executables-allow-sync`: 474 lines to assert one string equals kyberforge's version. A six-line grep, or drop it (the failure mode is visible and recoverable).
+   - [x] ~~`check-executables-allow-sync`: 474 lines to assert one string equals kyberforge's version. A six-line grep, or drop it (the failure mode is visible and recoverable).~~
+     > **Corrected then partially done (2026-09-13):** see commit `1b01e25` on `docs/simplification-audit`. Independent re-verification found "drop it" unsafe — ADR-0019's own Consequences section calls this failure mode *silent* and says a silent-staleness failure here is worse than the duplication the other gates catch, directly contradicting the finding's "visible and recoverable" claim. The hook stays. Shrunk `scripts/check-executables-allow-sync.sh` 231 → 222 lines by deduplicating two comment blocks that re-derived ADR-0019's own reasoning inline, replacing them with a pointer at the ADR. The dual-reader design (PyYAML plus a hand-rolled fallback, so a missing PyYAML can't silently skip the check) was found to be load-bearing, not redundant, and left intact; test file unchanged (behavior unaffected). All 23 test cases and the live pre-push hook run still pass.
    Effort S each, M for the walk-up.
 
 3. **Tests of the test harness: 1,090 lines testing 475 lines.** `test-run-tests.sh` and `test-run-bats.sh` defend "green either way" holes that exist only because the runners hand-roll TAP parsing and set-equality checks. Replace both runners with about 40 lines (`bats -r plugins` plus a parallel `find | xargs` over `test-*.sh`) and delete the meta-tests. `lib/batch-run.sh` stays; `sync-plugin-content.sh` sources it. Effort M.
@@ -153,7 +154,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research
 30. [x] ~~**`LESSONS.md`: 41 entries, 2 graduated, about 12 stale.** Twelve entries from 2026-05-17 describe a write-skill / write-eval workflow whose skills no longer exist. One entry is open work labelled "Status: neither part landed". The longest eight are 200 to 550-word incident reports. Delete the stale entries, move open work to an issue, cap entries at about 60 words, target 100 lines. Effort S.~~
     > **Done (2026-09-12):** see commit `629320b` on `docs/simplification-audit`. 255→131 lines, 41→30 entries. Kept 3 of the same-dated entries (RLHF defaults, secrets-rule gap, HITL gap) — judged unrelated to the defunct write-skill/write-eval workflow and still applicable, so 10 deleted rather than 12. The "neither part landed" open-work entry (CONTEXT.md not `@import`ed at session start) was removed rather than filed as an issue — full text preserved in this session's transcript if wanted later.
 
-31. **`CONTEXT.md`: 28 terms, most used only by gates.md, scripts, or tests rather than by skills;** two (Preload tax, Skill context contract) are never used outside `CONTEXT.md` and ADR-0020. The preload-tax entry quotes two dated numbers then says not to quote them. The example dialogue and flagged-ambiguities sections are grill residue. Cut to about 20 one-line terms. Effort S.
+31. [x] ~~**`CONTEXT.md`: 28 terms, most used only by gates.md, scripts, or tests rather than by skills;** two (Preload tax, Skill context contract) are never used outside `CONTEXT.md` and ADR-0020. The preload-tax entry quotes two dated numbers then says not to quote them. The example dialogue and flagged-ambiguities sections are grill residue. Cut to about 20 one-line terms. Effort S.~~
+    > **Corrected then done (2026-09-13):** see commits `124ce6e` and follow-up on `docs/simplification-audit`. Independent re-verification found "most used only by gates.md/scripts/tests" overstated: 13 of 28 terms are actually referenced from model-facing `references/*.md` files skills load in normal use (Routing target, Hand-invoked skill, Dispatch body, Near-miss, Thin adapter, Provenance chain, Output profile, apm package, Plugin marketplace, HITL, Skill composition, Delegation discipline, holocron) and were kept untouched. Only the 9 terms confirmed as true orphans were removed after a fresh independent grep: Content mirror, apm-consumed install, Vale audit prefilter, Vacuous green, Management Application, Sycophancy, HOTL, Preload tax, Skill context contract — 28 → 19 terms. The preload-tax self-contradiction (quotes 23,427/10,478-char figures then says not to quote either) was confirmed verbatim and resolved by the entry's own deletion. The "example dialogue" and "flagged ambiguities" sections were found to be mandated by `grill-with-docs/references/context-format.md`'s template spec, not grill residue — left untouched, except one dangling bolded cross-reference to the now-deleted "Preload tax" term in a Flagged-ambiguities line, which was unbolded/de-referenced in place (the ambiguity resolution itself still holds without a defined glossary entry to point at).
 
 32. **Structure is described three ways** (README layout table, architecture.md plugin table, AGENTS.md structure bullets), and `VISION.md` carries a 35-line stack spec for a product that lives in another repo. One layout table in README; architecture.md keeps mechanics only; VISION drops the stack detail. Effort S.
 
@@ -173,7 +175,8 @@ Not covered by the area audits above; found on a final sweep of the root config
 37. **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.
     > **Not proceeding (2026-09-13):** premise doesn't hold. The server exposes the repo's own git-tracked `docs/` folder — not an external/off-repo store — so it isn't the "external memory system" AGENTS.md's rule targets. It was deliberately added and versioned (3 commits), is documented as current intended behavior in both READMEs, and ADR-0018 uses it as its only concrete worked example of apm's MCP-dependency propagation mechanism actually working. No skill invokes the Obsidian tools as a workflow step, but that alone doesn't make the config dead. No changes made; recommend a human confirm whether the vault tooling is still wanted before removing it.
 
-38. **`pc-author` / `pc-run` (689 lines) carry generic pre-commit documentation.** `hooks-by-language.md` (128 lines) and `failure-patterns.md` (133) restate pre-commit.com. Keep the skills, trim to the house-specific rules. Effort S.
+38. [x] ~~**`pc-author` / `pc-run` (689 lines) carry generic pre-commit documentation.** `hooks-by-language.md` (128 lines) and `failure-patterns.md` (133) restate pre-commit.com. Keep the skills, trim to the house-specific rules. Effort S.~~
+    > **Corrected then done (2026-09-13):** see commit `a622200` on `docs/simplification-audit`. Independent re-verification found the 689-line figure overstated (actual combined size 598 lines) and the realistic cut smaller than a rewrite (~60-85 lines, concentrated in the two named reference files, not the SKILL.md files or the four short flow files, which are house-specific gates rather than restatement). Landed within that range: `hooks-by-language.md` 128 → 92 lines (collapsed six per-language tables repeating the same repo/rev/rationale into one shared-repo table plus a small other-repos table); `failure-patterns.md` 133 → 109 lines (removed generic SSH/proxy and shellcheck SC-code restatement, compressed generic schema-error bullets). Kept verbatim: both "Unverified — not in research corpus" flags, the rev-freshness caveat, the `rtk git add -u`/`rtk git commit` fix (ADR-0023), and the `pre-commit install -f` warning. Combined cut: 60 lines. Flat mirror regenerated and verified byte-identical.
 
 ## 7. Suggested order
 

plugins/git/.apm/skills/pc-author/references/hooks-by-language.md

@@ -16,70 +16,34 @@ files but do NOT re-stage them, so the commit is still blocked and the user has
 again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
 broken.
 
-## Universal (recommend for every repo)
+## `pre-commit/pre-commit-hooks` (rev `v6.0.0`)
 
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `end-of-file-fixer` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Ensures files end with a newline — prevents spurious diffs |
-| `trailing-whitespace` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Strips trailing whitespace — prevents invisible diff noise |
-| `check-merge-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches unresolved merge markers before commit |
-| `detect-private-key` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks PEM private key material |
-| `check-added-large-files` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks accidentally committing large binary files |
-| `check-case-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches filenames that would collide on case-insensitive filesystems |
-| `mixed-line-ending` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Normalizes line endings |
-| `no-commit-to-branch` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks direct commits to protected branches — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
+| Hook ID | Language / Context |
+|---------|---------------------|
+| `end-of-file-fixer` | Universal |
+| `trailing-whitespace` | Universal |
+| `check-merge-conflict` | Universal |
+| `detect-private-key` | Universal |
+| `check-added-large-files` | Universal |
+| `check-case-conflict` | Universal |
+| `mixed-line-ending` | Universal |
+| `no-commit-to-branch` | Universal — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
+| `check-ast` | Python (`.py`) |
+| `check-builtin-literals` | Python (`.py`) |
+| `check-json` | JSON (`.json`) |
+| `pretty-format-json` | JSON (`.json`) |
+| `check-yaml` | YAML (`.yaml`, `.yml`) — for Kubernetes/Helm with custom tags add `args: ['--unsafe']` and `exclude: ^helm/templates/` |
+| `check-toml` | TOML (`.toml`) |
 
-## Shell (`.sh`)
+Full repo URL: `https://github.com/pre-commit/pre-commit-hooks`. For Python formatting, check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
 
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Static analysis for shell scripts; catches common errors |
+## Other repos
 
-Recommended args: `args: [--severity=warning]`
-
-## Python (`.py`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-ast` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates Python files parse as valid AST |
-| `check-builtin-literals` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Enforces literal syntax for `dict()`, `list()` |
-
-For formatting: check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
-
-## JSON (`.json`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates JSON parses correctly |
-| `pretty-format-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Auto-formats JSON (fixer — warns user to re-stage after commit) |
-
-## YAML (`.yaml`, `.yml`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-yaml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates YAML parses correctly |
-
-For Kubernetes/Helm YAML with custom tags, add `args: ['--unsafe']` and `exclude: ^helm/templates/`.
-
-## TOML (`.toml`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-toml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates TOML parses correctly |
-
-## Secrets / security
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** Scans for secrets and high-entropy strings |
-
-## Commit message
-
-| Hook ID | Repo | Rev | Stage | Rationale |
-|---------|------|-----|-------|-----------|
-| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | `commit-msg` | Enforces Conventional Commits format |
-
-When adding commit-msg hooks, also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present.
+| Hook ID | Repo | Rev | Notes |
+|---------|------|-----|-------|
+| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Recommended args: `args: [--severity=warning]` |
+| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** |
+| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | Stage `commit-msg`; also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present |
 
 ## Meta-validation (add last, after all other repos)
 
@@ -125,4 +89,4 @@ Language choices for local hooks:
 
 ## Rev pin freshness
 
-The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
+The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats these tables as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against these tables.

plugins/git/.apm/skills/pc-run/references/failure-patterns.md

@@ -36,10 +36,7 @@ Suggestions:
 
 Cause: shellcheck found a shell script issue. The output includes the file path, line number, and SC-code.
 
-Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellcheck for a detailed explanation. The most common fixes:
-- SC2086 (unquoted variable): wrap in double quotes.
-- SC2046 (unquoted command substitution): wrap in double quotes.
-- SC2181 (check exit code of `$?`): use `if command; then` directly.
+Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellcheck for a detailed explanation.
 
 ## `check-hooks-apply` fails
 
@@ -53,23 +50,6 @@ Cause: An `exclude` pattern matches no files.
 
 Fix: Remove or fix the pattern.
 
-## SSH cloning fails in CI
-
-Cause: The CI environment lacks SSH credentials to clone hook repos over SSH.
-
-Fix: Export `SSH_AUTH_SOCK` in the CI environment, or switch hook repo URLs to HTTPS.
-
-## HTTP proxy needed
-
-Cause: The CI/sandbox network requires a proxy to reach hook repos.
-
-Fix:
-```bash
-export http_proxy=http://proxy.example.com:3128
-export https_proxy=http://proxy.example.com:3128
-export no_proxy=localhost,127.0.0.1
-```
-
 ## `rev` is a branch name — `autoupdate` broke it
 
 Cause: Branch refs are mutable and drift over time; pre-commit resolves them once at install time, so pinning to a branch name (instead of a tag or commit SHA) leads to silent version drift.
@@ -126,8 +106,4 @@ Or add `default_install_hook_types` to `.pre-commit-config.yaml` and re-run `pre
 
 ## `validate-config` schema error
 
-Common causes:
-- Missing `id` under a hook block
-- Missing `rev` under a non-local repo block
-- `repo: local` hook missing `language` or `entry`
-- Indentation error (valid YAML but invalid pre-commit schema)
+Common causes: missing `id` under a hook block, missing `rev` under a non-local repo block, a `repo: local` hook missing `language` or `entry`, or an indentation error (valid YAML but invalid pre-commit schema).

plugins/git/skills/pc-author/references/hooks-by-language.md

@@ -16,70 +16,34 @@ files but do NOT re-stage them, so the commit is still blocked and the user has
 again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
 broken.
 
-## Universal (recommend for every repo)
+## `pre-commit/pre-commit-hooks` (rev `v6.0.0`)
 
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `end-of-file-fixer` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Ensures files end with a newline — prevents spurious diffs |
-| `trailing-whitespace` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Strips trailing whitespace — prevents invisible diff noise |
-| `check-merge-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches unresolved merge markers before commit |
-| `detect-private-key` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks PEM private key material |
-| `check-added-large-files` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks accidentally committing large binary files |
-| `check-case-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches filenames that would collide on case-insensitive filesystems |
-| `mixed-line-ending` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Normalizes line endings |
-| `no-commit-to-branch` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks direct commits to protected branches — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
+| Hook ID | Language / Context |
+|---------|---------------------|
+| `end-of-file-fixer` | Universal |
+| `trailing-whitespace` | Universal |
+| `check-merge-conflict` | Universal |
+| `detect-private-key` | Universal |
+| `check-added-large-files` | Universal |
+| `check-case-conflict` | Universal |
+| `mixed-line-ending` | Universal |
+| `no-commit-to-branch` | Universal — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
+| `check-ast` | Python (`.py`) |
+| `check-builtin-literals` | Python (`.py`) |
+| `check-json` | JSON (`.json`) |
+| `pretty-format-json` | JSON (`.json`) |
+| `check-yaml` | YAML (`.yaml`, `.yml`) — for Kubernetes/Helm with custom tags add `args: ['--unsafe']` and `exclude: ^helm/templates/` |
+| `check-toml` | TOML (`.toml`) |
 
-## Shell (`.sh`)
+Full repo URL: `https://github.com/pre-commit/pre-commit-hooks`. For Python formatting, check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
 
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Static analysis for shell scripts; catches common errors |
+## Other repos
 
-Recommended args: `args: [--severity=warning]`
-
-## Python (`.py`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-ast` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates Python files parse as valid AST |
-| `check-builtin-literals` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Enforces literal syntax for `dict()`, `list()` |
-
-For formatting: check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
-
-## JSON (`.json`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates JSON parses correctly |
-| `pretty-format-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Auto-formats JSON (fixer — warns user to re-stage after commit) |
-
-## YAML (`.yaml`, `.yml`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-yaml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates YAML parses correctly |
-
-For Kubernetes/Helm YAML with custom tags, add `args: ['--unsafe']` and `exclude: ^helm/templates/`.
-
-## TOML (`.toml`)
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `check-toml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates TOML parses correctly |
-
-## Secrets / security
-
-| Hook ID | Repo | Rev | Rationale |
-|---------|------|-----|-----------|
-| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** Scans for secrets and high-entropy strings |
-
-## Commit message
-
-| Hook ID | Repo | Rev | Stage | Rationale |
-|---------|------|-----|-------|-----------|
-| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | `commit-msg` | Enforces Conventional Commits format |
-
-When adding commit-msg hooks, also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present.
+| Hook ID | Repo | Rev | Notes |
+|---------|------|-----|-------|
+| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Recommended args: `args: [--severity=warning]` |
+| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** |
+| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | Stage `commit-msg`; also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present |
 
 ## Meta-validation (add last, after all other repos)
 
@@ -125,4 +89,4 @@ Language choices for local hooks:
 
 ## Rev pin freshness
 
-The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
+The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats these tables as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against these tables.

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

@@ -36,10 +36,7 @@ Suggestions:
 
 Cause: shellcheck found a shell script issue. The output includes the file path, line number, and SC-code.
 
-Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellcheck for a detailed explanation. The most common fixes:
-- SC2086 (unquoted variable): wrap in double quotes.
-- SC2046 (unquoted command substitution): wrap in double quotes.
-- SC2181 (check exit code of `$?`): use `if command; then` directly.
+Fix: Look up the SC-code on shellcheck.net or pass `--explain SCxxxx` to shellcheck for a detailed explanation.
 
 ## `check-hooks-apply` fails
 
@@ -53,23 +50,6 @@ Cause: An `exclude` pattern matches no files.
 
 Fix: Remove or fix the pattern.
 
-## SSH cloning fails in CI
-
-Cause: The CI environment lacks SSH credentials to clone hook repos over SSH.
-
-Fix: Export `SSH_AUTH_SOCK` in the CI environment, or switch hook repo URLs to HTTPS.
-
-## HTTP proxy needed
-
-Cause: The CI/sandbox network requires a proxy to reach hook repos.
-
-Fix:
-```bash
-export http_proxy=http://proxy.example.com:3128
-export https_proxy=http://proxy.example.com:3128
-export no_proxy=localhost,127.0.0.1
-```
-
 ## `rev` is a branch name — `autoupdate` broke it
 
 Cause: Branch refs are mutable and drift over time; pre-commit resolves them once at install time, so pinning to a branch name (instead of a tag or commit SHA) leads to silent version drift.
@@ -126,8 +106,4 @@ Or add `default_install_hook_types` to `.pre-commit-config.yaml` and re-run `pre
 
 ## `validate-config` schema error
 
-Common causes:
-- Missing `id` under a hook block
-- Missing `rev` under a non-local repo block
-- `repo: local` hook missing `language` or `entry`
-- Indentation error (valid YAML but invalid pre-commit schema)
+Common causes: missing `id` under a hook block, missing `rev` under a non-local repo block, a `repo: local` hook missing `language` or `entry`, or an indentation error (valid YAML but invalid pre-commit schema).

scripts/check-executables-allow-sync.sh

@@ -2,17 +2,11 @@
 set -euo pipefail
 
 # Fails the push when root apm.yml's executables.allow key stops naming
-# kyberforge's actual version.
-#
-# apm gates a package's hooks/ and bin/ on an EXACT dict lookup of
-# "<package>#<version>" in executables.allow (apm_cli/security/executables.py,
-# `allow_executables.get(package_key)`) — there is no wildcard and no
-# version-less form. So bumping plugins/kyberforge/apm.yml's `version:` without
-# bumping the key in root apm.yml does not error anywhere: the entry simply
-# stops matching, kyberforge's SessionStart hook stops deploying, and the apm
-# install goes quietly stale — the exact failure ADR-0019 records as live and
-# mitigates only with a comment. Nothing else in the pre-push gate compares the
-# two files, which is why this exists.
+# kyberforge's actual version. apm matches that key by exact dict lookup
+# (apm_cli/security/executables.py) — a version bump that misses the key
+# update deploys nothing, with no error anywhere. See ADR-0019, "The allow
+# key is version-pinned, and that is a live failure mode", for the full
+# argument; nothing else in the pre-push gate compares these two files.
 #
 # Run from repo root or pass REPO_ROOT as arg.
 
@@ -64,12 +58,9 @@ fi
 #   a<TAB>present|absent              exactly once — is executables.allow a mapping?
 #   k<TAB><allow key>                 zero or more
 #
-# python3 + PyYAML is preferred where importable, because it is a real parser.
-# It is deliberately NOT a hard requirement: no other hook in this repo's
-# pre-push gate needs PyYAML, and making a version-pin check the one thing that
-# can block every push on a missing pip package is a worse failure than reading
-# two known shapes by hand. The fallback below is not a YAML parser — it
-# recognises exactly the two shapes these manifests use and nothing else.
+# python3 + PyYAML is preferred where importable; the fallback below is not a
+# YAML parser, it recognises only the two shapes these manifests use. PyYAML
+# stays optional so a missing pip package can't block every push (ADR-0019).
 
 read_facts_python() {
   python3 - "$ROOT_MANIFEST" "$PLUGIN_MANIFEST" << 'PY'