From 5e226721890d2113bc12792ba6c5ba778d415f36 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 18:52:17 +0000
Subject: [PATCH 01/45] docs(kyberforge): add vale.sh research docs

Prep work for issue #84 - gathers Vale (vale.sh) config, styles/rules,
CLI, installation, and troubleshooting reference material into
plugins/kyberforge/docs/research/docs/vale/ alongside the existing
research topics.

Refs #84
---
 plugins/kyberforge/docs/README.md             |   1 +
 .../docs/research/docs/vale/cli-reference.md  |  29 +++++
 .../docs/research/docs/vale/configuration.md  | 106 ++++++++++++++++++
 .../docs/research/docs/vale/examples.md       |  52 +++++++++
 .../docs/research/docs/vale/installation.md   |  41 +++++++
 .../docs/research/docs/vale/overview.md       |  43 +++++++
 .../docs/research/docs/vale/sources.md        |   8 ++
 .../research/docs/vale/troubleshooting.md     |  56 +++++++++
 8 files changed, 336 insertions(+)
 create mode 100644 plugins/kyberforge/docs/research/docs/vale/cli-reference.md
 create mode 100644 plugins/kyberforge/docs/research/docs/vale/configuration.md
 create mode 100644 plugins/kyberforge/docs/research/docs/vale/examples.md
 create mode 100644 plugins/kyberforge/docs/research/docs/vale/installation.md
 create mode 100644 plugins/kyberforge/docs/research/docs/vale/overview.md
 create mode 100644 plugins/kyberforge/docs/research/docs/vale/sources.md
 create mode 100644 plugins/kyberforge/docs/research/docs/vale/troubleshooting.md

diff --git a/plugins/kyberforge/docs/README.md b/plugins/kyberforge/docs/README.md
index 1f646a4..8194741 100644
--- a/plugins/kyberforge/docs/README.md
+++ b/plugins/kyberforge/docs/README.md
@@ -17,4 +17,5 @@ Upstream reference material gathered during skill authoring. Not shipped with th
 |------|---------|
 | `research/docs/agentskillsio/` | agentskills.io spec, skill authoring, description optimization, eval design, scripts |
 | `research/docs/agentsmd/` | agents.md format spec and cross-tool configuration reference |
+| `research/docs/vale/` | Vale (vale.sh) prose linter — config, styles/rules/checks model, CLI reference, installation |
 | `research/examples/skill-write/` | Upstream skill examples reviewed when authoring skill-write and skill-audit |
diff --git a/plugins/kyberforge/docs/research/docs/vale/cli-reference.md b/plugins/kyberforge/docs/research/docs/vale/cli-reference.md
new file mode 100644
index 0000000..7ed35fb
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/vale/cli-reference.md
@@ -0,0 +1,29 @@
+---
+topic: cli-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Invocation
+
+```bash
+$ vale README.md
+```
+
+Lints the given file(s)/glob against the styles configured in `.vale.ini`.
+
+## Key Flags and Subcommands
+
+| Command/Flag | Purpose |
+|---|---|
+| `vale sync` | Downloads and installs packages/styles declared in `.vale.ini`. Run after install and whenever `Packages` changes. |
+| `vale ls-config` | Prints the currently active, fully-resolved configuration as JSON. Useful for debugging what settings actually apply to a file. |
+| `--output=<style>` | Sets the output format/template: `line`, `JSON`, `CLI` (default), or a custom template. |
+| `--no-exit` | Suppresses the non-zero exit code Vale normally returns when alerts are found — useful in CI pipelines that shouldn't hard-fail on lint output. |
+| `--ignore-syntax` | Treats input as plain, unformatted text, skipping syntax-aware parsing (Markdown/HTML/etc). |
+| `--minAlertLevel=<level>` | Overrides `MinAlertLevel` from the config for this run (`suggestion`, `warning`, `error`). |
+| `--version` | Prints the Vale binary version. |
+
+## Exit Codes
+
+By default, `vale` exits non-zero when it finds any alert at or above `MinAlertLevel` — this is what makes it usable as a CI gate. Pass `--no-exit` to always exit `0` regardless of findings.
diff --git a/plugins/kyberforge/docs/research/docs/vale/configuration.md b/plugins/kyberforge/docs/research/docs/vale/configuration.md
new file mode 100644
index 0000000..ef683d5
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/vale/configuration.md
@@ -0,0 +1,106 @@
+---
+topic: configuration
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## `.vale.ini` Structure
+
+Configuration is INI-formatted with three sections, in order:
+
+```ini
+# Core settings appear at the top
+# (the "global" section).
+
+[formats]
+# Format associations appear under
+# the optional "formats" section.
+
+[*]
+# Format-specific settings appear
+# under a user-provided "glob"
+# pattern.
+```
+
+Core (global) settings apply application-wide; glob sections (`[*]`, `[*.md]`, etc.) scope settings to files matching that pattern.
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+Example:
+
+```ini
+StylesPath = styles
+MinAlertLevel = suggestion
+
+[*.md]
+BasedOnStyles = Vale
+```
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser. This is an extension-level substitution only — it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Packages
+
+Third-party style packages are declared via `Packages` and then activated per glob with `BasedOnStyles`:
+
+```ini
+Packages = Google, write-good
+
+[*.md]
+BasedOnStyles = Vale, Google, write-good
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |
diff --git a/plugins/kyberforge/docs/research/docs/vale/examples.md b/plugins/kyberforge/docs/research/docs/vale/examples.md
new file mode 100644
index 0000000..a50d2ae
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/vale/examples.md
@@ -0,0 +1,52 @@
+---
+topic: examples
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Project Initialization Walkthrough
+
+```bash
+$ cd some-project
+# create .vale.ini with StylesPath + BasedOnStyles
+$ vale sync         # downloads declared packages/styles into StylesPath
+$ ls styles          # confirms styles were installed
+$ vale README.md     # lint a file
+```
+
+The `.vale.ini` file must exist before `vale sync` — it declares which packages to fetch.
+
+## Typical Project Config
+
+```ini
+StylesPath = styles
+MinAlertLevel = error
+
+[*.md]
+BasedOnStyles = ProjectStyle
+```
+
+## pre-commit Integration
+
+Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
+
+```yaml
+repos:
+  - repo: https://github.com/errata-ai/vale
+    rev: 16d3a7f
+    hooks:
+      - id: vale
+        name: vale sync
+        pass_filenames: false
+        args: [sync]
+      - id: vale
+        args: [--output=line, --minAlertLevel=error]
+```
+
+## CI Output for Machine Parsing
+
+```bash
+$ vale --output=JSON README.md
+```
+
+Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.
diff --git a/plugins/kyberforge/docs/research/docs/vale/installation.md b/plugins/kyberforge/docs/research/docs/vale/installation.md
new file mode 100644
index 0000000..3712335
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/vale/installation.md
@@ -0,0 +1,41 @@
+---
+topic: installation
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Package Managers
+
+Vale is distributed via standard OS package managers:
+
+```bash
+brew install vale      # macOS
+snap install vale      # Linux
+```
+
+```powershell
+choco install vale      # Windows
+```
+
+## Docker
+
+An official image is available on Docker Hub:
+
+```bash
+docker pull jdkato/vale
+```
+
+## Post-Install: Syncing Styles
+
+Installing the `vale` binary alone does not install any styles. After install, run `vale sync` to download and install the styles/packages declared in `.vale.ini`:
+
+```bash
+$ vale sync
+```
+
+## Format-Specific Extras
+
+Some input formats need an external converter installed separately before Vale can process them:
+
+- reStructuredText: `pip install docutils` (provides `rst2html`)
+- MDX: `npm install -g mdx2vast`
diff --git a/plugins/kyberforge/docs/research/docs/vale/overview.md b/plugins/kyberforge/docs/research/docs/vale/overview.md
new file mode 100644
index 0000000..e19e887
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/vale/overview.md
@@ -0,0 +1,43 @@
+---
+topic: overview
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## What Vale Is
+
+Vale is a cross-platform command-line tool that brings code-like linting to prose. Rather than checking general grammar, it enforces project-specific writing style rules — consistency of terminology, phrasing, and formatting — the same way a linter enforces a code style guide.
+
+## Styles, Rules, and Checks
+
+Vale's configuration model has three layers:
+
+- **Styles** — a named collection of rules (e.g. the built-in `Vale` style, or third-party styles like `Google` or `write-good`). A project can apply multiple styles at once via `BasedOnStyles`.
+- **Rules** — individual YAML files that define one specific check (e.g. flag a term, enforce a heading capitalization pattern). Each rule `extends` a check and sets a `message`, `level`, and other header fields.
+- **Checks** — the underlying functions a rule extends to perform analysis: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").
+
+## Styles Directory Layout
+
+Styles live under `StylesPath` in a nested folder structure, one subdirectory per style, each holding YAML rule files:
+
+```
+styles/
+├── base/
+│   ├── ComplexWords.yml
+│   ├── SentenceLength.yml
+├── blog/
+│   ├── TechTerms.yml
+└── docs/
+    ├── Branding.yml
+```
+
+This lets a project mix a shared base style with format- or section-specific styles, all activated per-glob in `.vale.ini`.
diff --git a/plugins/kyberforge/docs/research/docs/vale/sources.md b/plugins/kyberforge/docs/research/docs/vale/sources.md
new file mode 100644
index 0000000..383423b
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/vale/sources.md
@@ -0,0 +1,8 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, CLI commands and flags, installation across package managers and Docker, format-specific inline disable syntax, pre-commit integration, spelling ignore lists.
+- **Contributing files:** overview.md, installation.md, configuration.md, cli-reference.md, examples.md, troubleshooting.md
+- **Status:** `extracted`
diff --git a/plugins/kyberforge/docs/research/docs/vale/troubleshooting.md b/plugins/kyberforge/docs/research/docs/vale/troubleshooting.md
new file mode 100644
index 0000000..818bea2
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/vale/troubleshooting.md
@@ -0,0 +1,56 @@
+---
+topic: troubleshooting
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Suppressing False Positives Inline
+
+Vale supports inline markup comments to disable checks for a section of content. Syntax varies by format:
+
+Markdown/MDX:
+```mdx
+{/* vale off */}
+This text will be ignored.
+{/* vale on */}
+```
+
+Org mode:
+```org
+# vale off
+This text will be ignored.
+# vale on
+```
+
+## Disabling a Specific Rule for Specific Matches
+
+Rather than disabling all checks, target one rule and specific known-exception strings, then re-enable:
+
+```mdx
+{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
+This is some text ACT test
+{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
+```
+
+This is the preferred fix for recurring false positives on specific terms — it keeps the rule active everywhere else instead of disabling it project-wide.
+
+## Ignoring Words in Spell Check
+
+The `spelling` check accepts an `ignore` list of external plain-text files, so known project-specific terms don't need touching the dictionary:
+
+```yaml
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+ignore:
+  - ignore1.txt
+  - ignore2.txt
+```
+
+## Plain-Text Fallback
+
+If a file's syntax-aware parsing produces noisy/incorrect results (e.g. an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
+
+## CI Failing Unexpectedly
+
+If a CI job fails solely because Vale returns a non-zero exit code on found alerts (not because the content is actually wrong for that pipeline stage), add `--no-exit` rather than suppressing the rule itself — this preserves the lint output while not gating the build on it.
-- 
2.43.0


From d1afdbeff795a9892ab644f16cb379c0edcdec7d Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 19:11:38 +0000
Subject: [PATCH 02/45] feat(lint): add vale-config skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers Vale install and .vale.ini setup — StylesPath, built-in/
third-party/custom styles, BasedOnStyles activation. Setup half of
Vale support; vale-run (running/interpreting) is a separate skill.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
---
 .../docs/research/docs/vale/cli-reference.md  |  0
 .../docs/research/docs/vale/configuration.md  |  0
 .../docs/research/docs/vale/examples.md       |  0
 .../docs/research/docs/vale/installation.md   |  0
 .../docs/research/docs/vale/overview.md       |  0
 .../docs/research/docs/vale/sources.md        |  0
 .../research/docs/vale/troubleshooting.md     |  0
 plugins/lint/skills/vale-config/README.md     | 23 ++++++
 plugins/lint/skills/vale-config/SKILL.md      | 62 +++++++++++++++
 .../references/configuration-reference.md     | 78 +++++++++++++++++++
 .../skills/vale-config/references/sources.md  |  9 +++
 11 files changed, 172 insertions(+)
 rename plugins/{kyberforge => lint}/docs/research/docs/vale/cli-reference.md (100%)
 rename plugins/{kyberforge => lint}/docs/research/docs/vale/configuration.md (100%)
 rename plugins/{kyberforge => lint}/docs/research/docs/vale/examples.md (100%)
 rename plugins/{kyberforge => lint}/docs/research/docs/vale/installation.md (100%)
 rename plugins/{kyberforge => lint}/docs/research/docs/vale/overview.md (100%)
 rename plugins/{kyberforge => lint}/docs/research/docs/vale/sources.md (100%)
 rename plugins/{kyberforge => lint}/docs/research/docs/vale/troubleshooting.md (100%)
 create mode 100644 plugins/lint/skills/vale-config/README.md
 create mode 100644 plugins/lint/skills/vale-config/SKILL.md
 create mode 100644 plugins/lint/skills/vale-config/references/configuration-reference.md
 create mode 100644 plugins/lint/skills/vale-config/references/sources.md

diff --git a/plugins/kyberforge/docs/research/docs/vale/cli-reference.md b/plugins/lint/docs/research/docs/vale/cli-reference.md
similarity index 100%
rename from plugins/kyberforge/docs/research/docs/vale/cli-reference.md
rename to plugins/lint/docs/research/docs/vale/cli-reference.md
diff --git a/plugins/kyberforge/docs/research/docs/vale/configuration.md b/plugins/lint/docs/research/docs/vale/configuration.md
similarity index 100%
rename from plugins/kyberforge/docs/research/docs/vale/configuration.md
rename to plugins/lint/docs/research/docs/vale/configuration.md
diff --git a/plugins/kyberforge/docs/research/docs/vale/examples.md b/plugins/lint/docs/research/docs/vale/examples.md
similarity index 100%
rename from plugins/kyberforge/docs/research/docs/vale/examples.md
rename to plugins/lint/docs/research/docs/vale/examples.md
diff --git a/plugins/kyberforge/docs/research/docs/vale/installation.md b/plugins/lint/docs/research/docs/vale/installation.md
similarity index 100%
rename from plugins/kyberforge/docs/research/docs/vale/installation.md
rename to plugins/lint/docs/research/docs/vale/installation.md
diff --git a/plugins/kyberforge/docs/research/docs/vale/overview.md b/plugins/lint/docs/research/docs/vale/overview.md
similarity index 100%
rename from plugins/kyberforge/docs/research/docs/vale/overview.md
rename to plugins/lint/docs/research/docs/vale/overview.md
diff --git a/plugins/kyberforge/docs/research/docs/vale/sources.md b/plugins/lint/docs/research/docs/vale/sources.md
similarity index 100%
rename from plugins/kyberforge/docs/research/docs/vale/sources.md
rename to plugins/lint/docs/research/docs/vale/sources.md
diff --git a/plugins/kyberforge/docs/research/docs/vale/troubleshooting.md b/plugins/lint/docs/research/docs/vale/troubleshooting.md
similarity index 100%
rename from plugins/kyberforge/docs/research/docs/vale/troubleshooting.md
rename to plugins/lint/docs/research/docs/vale/troubleshooting.md
diff --git a/plugins/lint/skills/vale-config/README.md b/plugins/lint/skills/vale-config/README.md
new file mode 100644
index 0000000..2a5d0bc
--- /dev/null
+++ b/plugins/lint/skills/vale-config/README.md
@@ -0,0 +1,23 @@
+# vale-config
+
+Install and configure Vale, the prose/style linter — `.vale.ini`, `StylesPath`, built-in/third-party/custom styles, and activation via `BasedOnStyles`.
+
+## What it does
+
+Covers the setup side of Vale: getting a project from no config to a working `.vale.ini` where `vale sync` runs clean and every declared style is actually activated for the right files. Does not run Vale or interpret its output — see `vale-run` for that.
+
+## Usage
+
+```
+/vale-config
+```
+
+Describe what you want configured: initial setup, adding a third-party style package, or a custom rule. The skill covers install, `StylesPath` layout, `.vale.ini` structure, and `BasedOnStyles` activation.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/configuration-reference.md` | Full `.vale.ini` field and rule-header reference |
+| `references/sources.md` | Research sources backing the Vale configuration guidance |
diff --git a/plugins/lint/skills/vale-config/SKILL.md b/plugins/lint/skills/vale-config/SKILL.md
new file mode 100644
index 0000000..2d52429
--- /dev/null
+++ b/plugins/lint/skills/vale-config/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: vale-config
+
+description: >
+  Use when installing or configuring Vale, the cross-platform prose/style linter — setting up
+  .vale.ini, choosing a StylesPath, adding built-in, third-party, or custom styles, and activating
+  them per file glob via BasedOnStyles. Covers the setup side of Vale only: getting a project from
+  "no Vale config" to "vale sync runs clean and BasedOnStyles is wired up correctly". Use even if the
+  user doesn't say "Vale" explicitly — "set up prose linting", "lint our docs for style", "enforce a
+  vocabulary/terminology list in markdown" all apply. Do not use when the user wants to actually run
+  Vale and interpret its output on existing config — use vale-run for that.
+
+metadata:
+  category: lint
+  version: "0.1.0"
+  source_keys:
+    - context7-websites-vale-sh
+---
+
+## Gotchas
+
+- Installing the `vale` binary installs no styles. A fresh `.vale.ini` with `BasedOnStyles` set will fail or find nothing until `vale sync` runs and downloads the `Packages` it declares.
+- `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob.
+- Declaring `StylesPath` and `Packages` alone activates nothing. A style only lints files once it's listed in `BasedOnStyles` under a glob section that matches those files — this is the step people forget.
+- `Packages` (top-level, for `vale sync` to fetch) and `BasedOnStyles` (per-glob, to activate) are two different keys serving two different purposes. Both are required for a third-party style to actually run.
+
+## Setup workflow
+
+- [ ] **Install** the `vale` binary: `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or `docker pull jdkato/vale`.
+- [ ] **Pick a `StylesPath`** (conventionally `styles`) and create it. This is where all styles, dictionaries, and vocab live.
+- [ ] **Write `.vale.ini`** at the project root with at minimum:
+  ```ini
+  StylesPath = styles
+  MinAlertLevel = suggestion
+
+  [*.md]
+  BasedOnStyles = Vale
+  ```
+  `Vale` here is the built-in style (`Vale.Spelling`, `Vale.Terms`, `Vale.Avoid`, `Vale.Repetition`) — no download needed, it always works.
+- [ ] **Add third-party styles** (optional) by declaring them in `Packages`, then activating them in the same or another glob's `BasedOnStyles`:
+  ```ini
+  Packages = Google, write-good
+
+  [*.md]
+  BasedOnStyles = Vale, Google, write-good
+  ```
+- [ ] **Sync**: run `vale sync` to download everything listed in `Packages` into `StylesPath`.
+- [ ] **Verify activation**: confirm every style named in `Packages` also appears in at least one glob's `BasedOnStyles` — an unreferenced package downloads but never lints anything.
+
+For the full `.vale.ini` field reference (formats mapping, vocab, local overrides, custom rule header fields), read `references/configuration-reference.md`.
+
+## Custom styles
+
+A custom style is just a new subdirectory under `StylesPath`, holding one YAML file per rule:
+
+```
+styles/
+└── MyStyle/
+    └── NoJargon.yml
+```
+
+Each rule file needs `extends` (the check it implements, e.g. `existence`) and `message` at minimum. Activate the style the same way as any other: add `MyStyle` to `BasedOnStyles` for the relevant glob. See `references/configuration-reference.md` for the full rule header field table.
diff --git a/plugins/lint/skills/vale-config/references/configuration-reference.md b/plugins/lint/skills/vale-config/references/configuration-reference.md
new file mode 100644
index 0000000..d2bca35
--- /dev/null
+++ b/plugins/lint/skills/vale-config/references/configuration-reference.md
@@ -0,0 +1,78 @@
+---
+topic: configuration-reference
+source_keys:
+  - context7-websites-vale-sh
+---
+
+## Core Settings
+
+| Key | Type | Purpose |
+|---|---|---|
+| `StylesPath` | string | Path to all Vale-related resources (styles, dictionaries, vocab). |
+| `Packages` | string[] | Packages to download and install via `vale sync`. |
+| `Vocab` | string[] | Vocabularies to load. |
+| `MinAlertLevel` | enum | Minimum severity to report: `suggestion`, `warning`, or `error`. |
+| `IgnoredScopes` | enum | Inline-level HTML tags to ignore. |
+| `SkippedScopes` | enum | Block-level HTML tags to ignore entirely. |
+
+## Format Associations
+
+Map an unrecognized extension onto a supported one so Vale lints it with the right parser — an extension-level substitution only, it does not add new file-type support:
+
+```ini
+[formats]
+mdx = md
+```
+
+## Vocabularies
+
+Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
+
+```ini
+StylesPath = styles
+
+Vocab = Blog
+
+[*]
+BasedOnStyles = Vale, MyStyle
+```
+
+## Local Overrides
+
+A project can layer a local `.vale.ini` that overrides `StylesPath`, adds packages, and changes `BasedOnStyles` for a subset of files — local settings merge with or override the global ones:
+
+```ini
+StylesPath = localpath
+
+Packages = write-good
+
+[*.md]
+BasedOnStyles = write-good
+```
+
+## Rule Header Fields
+
+Individual rule YAML files (under a style's directory) support these header fields:
+
+| Field | Required | Default | Purpose |
+|---|---|---|---|
+| `extends` | yes | — | Check this rule extends (e.g. `existence`). |
+| `message` | yes | — | Message shown when triggered; supports `%s` formatting per check type. |
+| `level` | no | `suggestion` | Severity: `suggestion`, `warning`, or `error`. |
+| `scope` | no | `text` | Scope the rule applies to (e.g. `heading`). |
+| `link` | no | — | URL with more info about the rule. |
+| `limit` | no | — | Max number of triggers per file. |
+| `vocab` | no | `true` | Set `false` to disable active vocabularies for this rule. |
+
+## Checks
+
+The underlying functions a rule's `extends` field can reference: `existence`, `substitution`, `occurrence`, `repetition`, `consistency`, `conditional`, `capitalization`, `metric`, `spelling`, `sequence`, `script`.
+
+## Built-in Style
+
+Vale ships with a default `Vale` style containing four rules, usable without `vale sync`:
+
+- `Vale.Spelling` — spell-checks against Hunspell-compatible dictionaries in `<StylesPath>/config/dictionaries`.
+- `Vale.Terms` — enforces the project's accepted vocabulary terms.
+- `Vale.Avoid` — enforces the project's rejected vocabulary terms.
+- `Vale.Repetition` — flags repeated words (e.g. "the the").
diff --git a/plugins/lint/skills/vale-config/references/sources.md b/plugins/lint/skills/vale-config/references/sources.md
new file mode 100644
index 0000000..854fe15
--- /dev/null
+++ b/plugins/lint/skills/vale-config/references/sources.md
@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, installation across package managers and Docker.
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Contributing files:** SKILL.md, references/configuration-reference.md
+- **Status:** `extracted`
-- 
2.43.0


From 8b00728374c0f83a17a4246cfea2a4cd4c0e86f3 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 19:12:25 +0000
Subject: [PATCH 03/45] feat(lint): add vale-run skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers invoking the vale CLI and interpreting its output — output
formats, severity filtering, exit-code handling, and false-positive
triage — for an already-configured project.
---
 plugins/lint/skills/vale-run/README.md        | 23 ++++++
 plugins/lint/skills/vale-run/SKILL.md         | 61 +++++++++++++++
 .../skills/vale-run/references/sources.md     |  9 +++
 .../vale-run/references/troubleshooting.md    | 78 +++++++++++++++++++
 4 files changed, 171 insertions(+)
 create mode 100644 plugins/lint/skills/vale-run/README.md
 create mode 100644 plugins/lint/skills/vale-run/SKILL.md
 create mode 100644 plugins/lint/skills/vale-run/references/sources.md
 create mode 100644 plugins/lint/skills/vale-run/references/troubleshooting.md

diff --git a/plugins/lint/skills/vale-run/README.md b/plugins/lint/skills/vale-run/README.md
new file mode 100644
index 0000000..8572456
--- /dev/null
+++ b/plugins/lint/skills/vale-run/README.md
@@ -0,0 +1,23 @@
+# vale-run
+
+Run Vale (a prose/style linter) against an already-configured project and interpret its results.
+
+## What it does
+
+This skill covers invoking the `vale` CLI against files or directories, choosing an output format (human-readable CLI, `line`, or machine-parseable `JSON`), filtering by severity via `--minAlertLevel`, and handling exit codes in scripts and CI. It also covers resolving common runtime issues: false positives, format-specific inline suppression, and CI failures caused solely by Vale's non-zero exit code. It assumes the project already has a working `.vale.ini` and installed styles — setting those up is the sibling `vale-config` skill's job.
+
+## Usage
+
+```
+/vale-run
+```
+
+Describe what you want to lint and how (human-readable output, CI/JSON output, filtered by severity). The skill will pick the right flags and, if results include false positives, walk through the narrowest applicable fix.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Core invocation, key flags, output format guidance, false-positive triage order |
+| `references/troubleshooting.md` | Inline suppression syntax, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases |
+| `references/sources.md` | Research provenance |
diff --git a/plugins/lint/skills/vale-run/SKILL.md b/plugins/lint/skills/vale-run/SKILL.md
new file mode 100644
index 0000000..cff78af
--- /dev/null
+++ b/plugins/lint/skills/vale-run/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: vale-run
+description: >
+  Use when running Vale (a prose/style linter) against files or directories in an
+  already-configured project — one that already has a .vale.ini — and interpreting
+  or reporting its results: choosing an output format for humans vs. CI, filtering
+  by severity, handling Vale's exit codes in scripts, or resolving common runtime
+  issues like false positives and unexpected CI failures. Use even if the user
+  doesn't say "vale" explicitly, e.g. "lint the docs", "check prose style", "run
+  the style linter", "why is CI failing on the docs check". Do not use when the
+  project has no .vale.ini yet, or needs styles installed/configured — that's the
+  vale-config skill.
+metadata:
+  version: "0.1.0"
+  category: linting
+  source_keys:
+    - context7-websites-vale-sh
+---
+
+## Gotchas
+
+- Vale exits non-zero whenever it finds an alert at or above `MinAlertLevel` — that's what makes it usable as a CI gate, not a sign the invocation failed. Read the output before concluding the command errored.
+- `vale ls-config` prints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in `.vale.ini`.
+- Inline suppression syntax is format-specific: Markdown/MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. Don't assume one syntax works across formats.
+
+## Running vale
+
+Default invocation:
+
+```bash
+vale <path-or-glob>
+```
+
+Key flags:
+
+| Flag | Purpose |
+|---|---|
+| `--output=<style>` | Output format/template: `CLI` (default, human-readable), `line` (compact, one alert per line, good for grep/piping), `JSON` (for programmatic parsing), or a custom template. |
+| `--minAlertLevel=<suggestion\|warning\|error>` | Overrides `MinAlertLevel` from `.vale.ini` for this run only, without editing config. |
+| `--no-exit` | Forces exit code `0` regardless of findings. Use in CI stages that should surface lint output without hard-failing the build. |
+| `--ignore-syntax` | Treats input as plain text, skipping format-aware parsing — use when a file's syntax-aware parser produces noisy or wrong results. |
+
+`vale sync` downloads the packages/styles declared in `.vale.ini` — that's a one-time-per-change setup step (vale-config's territory), not part of a normal lint run. If a run behaves as though no styles are active, that's a sign `vale sync` hasn't been run yet, not a `vale-run` problem.
+
+Prefer `--output=JSON` whenever the caller (a script, a CI step, another agent) needs to act on individual alerts rather than just get a pass/fail signal — `CLI` and `line` are for humans reading the terminal.
+
+## Fixing false positives
+
+Scope the fix as narrowly as possible, in this order:
+
+1. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
+2. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}` ... `= YES`), rather than the whole rule.
+3. **Known project term failing spell check**: add it to the style's `ignore` list, not an inline suppression.
+
+Never disable a rule project-wide to fix one false positive — editing `.vale.ini`/`BasedOnStyles` is vale-config's job, and it silences the rule everywhere, not just the false-positive case.
+
+If output looks wrong because Vale mis-parsed a file's format, rerun with `--ignore-syntax` before assuming the rule itself is broken.
+
+For CI that fails solely because Vale returned non-zero on found alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule.
+
+If setting up Vale as a pre-commit hook or need the full inline-suppression/spelling-ignore syntax reference, read `references/troubleshooting.md`.
diff --git a/plugins/lint/skills/vale-run/references/sources.md b/plugins/lint/skills/vale-run/references/sources.md
new file mode 100644
index 0000000..279ef95
--- /dev/null
+++ b/plugins/lint/skills/vale-run/references/sources.md
@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — `.vale.ini` config reference, style/rule/check model, CLI commands and flags, installation across package managers and Docker, format-specific inline disable syntax, pre-commit integration, spelling ignore lists.
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Contributing files:** SKILL.md, references/troubleshooting.md
+- **Status:** `extracted`
diff --git a/plugins/lint/skills/vale-run/references/troubleshooting.md b/plugins/lint/skills/vale-run/references/troubleshooting.md
new file mode 100644
index 0000000..6b0167e
--- /dev/null
+++ b/plugins/lint/skills/vale-run/references/troubleshooting.md
@@ -0,0 +1,78 @@
+---
+source_keys:
+  - context7-websites-vale-sh
+---
+
+# Vale troubleshooting reference
+
+## Inline suppression syntax by format
+
+Markdown/MDX:
+```mdx
+{/* vale off */}
+This text will be ignored.
+{/* vale on */}
+```
+
+Org mode:
+```org
+# vale off
+This text will be ignored.
+# vale on
+```
+
+## Disabling a specific rule for specific matches
+
+Targets one rule and specific known-exception strings, then re-enables — the preferred fix for a recurring false positive on a specific term, since it keeps the rule active everywhere else:
+
+```mdx
+{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
+This is some text ACT test
+{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
+```
+
+## Ignoring words in spell check
+
+The `spelling` check accepts an `ignore` list of external plain-text files, so project-specific terms don't need touching the dictionary:
+
+```yaml
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+ignore:
+  - ignore1.txt
+  - ignore2.txt
+```
+
+## Plain-text fallback
+
+If a file's syntax-aware parsing produces noisy or incorrect results (an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
+
+## CI failing unexpectedly
+
+If a CI job fails solely because Vale returns a non-zero exit code on found alerts — not because the content is actually wrong for that pipeline stage — add `--no-exit` rather than suppressing the rule itself. This preserves the lint output while not gating the build on it.
+
+## pre-commit integration
+
+Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
+
+```yaml
+repos:
+  - repo: https://github.com/errata-ai/vale
+    rev: 16d3a7f
+    hooks:
+      - id: vale
+        name: vale sync
+        pass_filenames: false
+        args: [sync]
+      - id: vale
+        args: [--output=line, --minAlertLevel=error]
+```
+
+## CI output for machine parsing
+
+```bash
+$ vale --output=JSON README.md
+```
+
+Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.
-- 
2.43.0


From 59ad2a3cbda57a07487ebd117b086c3e2da3d056 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 19:17:43 +0000
Subject: [PATCH 04/45] feat(lint): add lint-runner agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Report-only agent that composes vale-config/vale-run to run a lint
sweep over a scope and return normalized findings — no Edit tool, it
flags issues rather than fixing them. Also lands the plugin manifest
scaffold (plugin.json, .claude-plugin/plugin.json) that the earlier
vale-config/vale-run skill commits assumed but didn't carry, bumped
to 1.1.0 for the new agent.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
---
 plugins/lint/.claude-plugin/plugin.json  | 18 +++++++++++
 plugins/lint/agents/lint-runner.agent.md | 38 ++++++++++++++++++++++++
 plugins/lint/agents/lint-runner.md       | 38 ++++++++++++++++++++++++
 plugins/lint/plugin.json                 | 23 ++++++++++++++
 4 files changed, 117 insertions(+)
 create mode 100644 plugins/lint/.claude-plugin/plugin.json
 create mode 100644 plugins/lint/agents/lint-runner.agent.md
 create mode 100644 plugins/lint/agents/lint-runner.md
 create mode 100644 plugins/lint/plugin.json

diff --git a/plugins/lint/.claude-plugin/plugin.json b/plugins/lint/.claude-plugin/plugin.json
new file mode 100644
index 0000000..1545578
--- /dev/null
+++ b/plugins/lint/.claude-plugin/plugin.json
@@ -0,0 +1,18 @@
+{
+  "author": {
+    "name": "Defame1297",
+    "url": "https://git.dev.rkdr.net/Defame1297/"
+  },
+  "description": "Skills and agents for configuring and running linters, starting with Vale.",
+  "displayName": "Lint",
+  "keywords": [
+    "lint",
+    "vale",
+    "style",
+    "prose",
+    "linter"
+  ],
+  "license": "MIT",
+  "name": "lint",
+  "version": "1.1.0"
+}
diff --git a/plugins/lint/agents/lint-runner.agent.md b/plugins/lint/agents/lint-runner.agent.md
new file mode 100644
index 0000000..c21c4b2
--- /dev/null
+++ b/plugins/lint/agents/lint-runner.agent.md
@@ -0,0 +1,38 @@
+---
+name: lint-runner
+
+description: Runs a linter sweep over a target file or directory scope and reports findings. Currently backs onto Vale (prose/style linting) via the vale-config and vale-run skills; built to add other linters later without changing its own contract. Use when a caller needs a lint pass run in an isolated context and wants findings back, not fixes applied.
+
+tools: ["execute", "read", "search"]
+
+---
+
+You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
+
+## Inputs
+
+- **scope:** file path, directory path, or glob to lint
+- **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini`); if none exists, say so in your report rather than inventing one
+
+## Process
+
+1. Determine whether the target scope already has linter configuration in place (e.g. `.vale.ini` for Vale). If not, use the `vale-config` skill to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `vale-run` skill to invoke the linter over the scope and interpret its raw output.
+3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
+4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), report that as a blocking finding rather than attempting to install or configure it silently.
+
+## Output
+
+Report findings as a flat list, most-severe first:
+
+```
+- file: <path>
+  line: <line number or range>
+  rule: <check/rule name>
+  severity: <error | warning | suggestion>
+  message: <finding text>
+```
+
+Follow with a one-line summary: total findings by severity, and whether the run was blocked (e.g. linter not configured). If there are zero findings, say so explicitly — do not omit the report.
diff --git a/plugins/lint/agents/lint-runner.md b/plugins/lint/agents/lint-runner.md
new file mode 100644
index 0000000..de0ebfb
--- /dev/null
+++ b/plugins/lint/agents/lint-runner.md
@@ -0,0 +1,38 @@
+---
+name: lint-runner
+
+description: Runs a linter sweep over a target file or directory scope and reports findings. Currently backs onto Vale (prose/style linting) via the vale-config and vale-run skills; built to add other linters later without changing its own contract. Use when a caller needs a lint pass run in an isolated context and wants findings back, not fixes applied.
+
+tools: Bash, Read, Grep, Glob
+
+---
+
+You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
+
+## Inputs
+
+- **scope:** file path, directory path, or glob to lint
+- **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini`); if none exists, say so in your report rather than inventing one
+
+## Process
+
+1. Determine whether the target scope already has linter configuration in place (e.g. `.vale.ini` for Vale). If not, use the `vale-config` skill to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `vale-run` skill to invoke the linter over the scope and interpret its raw output.
+3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
+4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), report that as a blocking finding rather than attempting to install or configure it silently.
+
+## Output
+
+Report findings as a flat list, most-severe first:
+
+```
+- file: <path>
+  line: <line number or range>
+  rule: <check/rule name>
+  severity: <error | warning | suggestion>
+  message: <finding text>
+```
+
+Follow with a one-line summary: total findings by severity, and whether the run was blocked (e.g. linter not configured). If there are zero findings, say so explicitly — do not omit the report.
diff --git a/plugins/lint/plugin.json b/plugins/lint/plugin.json
new file mode 100644
index 0000000..b5eae4e
--- /dev/null
+++ b/plugins/lint/plugin.json
@@ -0,0 +1,23 @@
+{
+  "agents": "agents/",
+  "author": {
+    "email": "defame1297@rkdr.net",
+    "name": "Defame1297"
+  },
+  "description": "Skills and agents for configuring and running linters, starting with Vale.",
+  "hooks": "hooks.json",
+  "keywords": [
+    "lint",
+    "vale",
+    "style",
+    "prose",
+    "linter"
+  ],
+  "license": "MIT",
+  "mcpServers": ".mcp.json",
+  "name": "lint",
+  "skills": [
+    "skills/"
+  ],
+  "version": "1.1.0"
+}
-- 
2.43.0


From 57bdfa92e8205f46514f4cd45b9f1d5566345d40 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 19:24:59 +0000
Subject: [PATCH 05/45] fix(lint): resolve audit findings on vale skills

Merge duplicate gotcha in vale-config (Packages vs BasedOnStyles was
stated twice) and align vale-run's category field with vale-config's
(lint, not linting) so sibling skills in the plugin agree.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
---
 plugins/lint/skills/vale-config/SKILL.md | 3 +--
 plugins/lint/skills/vale-run/SKILL.md    | 2 +-
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/plugins/lint/skills/vale-config/SKILL.md b/plugins/lint/skills/vale-config/SKILL.md
index 2d52429..43591c4 100644
--- a/plugins/lint/skills/vale-config/SKILL.md
+++ b/plugins/lint/skills/vale-config/SKILL.md
@@ -21,8 +21,7 @@ metadata:
 
 - Installing the `vale` binary installs no styles. A fresh `.vale.ini` with `BasedOnStyles` set will fail or find nothing until `vale sync` runs and downloads the `Packages` it declares.
 - `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob.
-- Declaring `StylesPath` and `Packages` alone activates nothing. A style only lints files once it's listed in `BasedOnStyles` under a glob section that matches those files — this is the step people forget.
-- `Packages` (top-level, for `vale sync` to fetch) and `BasedOnStyles` (per-glob, to activate) are two different keys serving two different purposes. Both are required for a third-party style to actually run.
+- `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget.
 
 ## Setup workflow
 
diff --git a/plugins/lint/skills/vale-run/SKILL.md b/plugins/lint/skills/vale-run/SKILL.md
index cff78af..8b0d78c 100644
--- a/plugins/lint/skills/vale-run/SKILL.md
+++ b/plugins/lint/skills/vale-run/SKILL.md
@@ -12,7 +12,7 @@ description: >
   vale-config skill.
 metadata:
   version: "0.1.0"
-  category: linting
+  category: lint
   source_keys:
     - context7-websites-vale-sh
 ---
-- 
2.43.0


From f326df48618822fceb70356fe1ee90589549b94a Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 19:26:42 +0000
Subject: [PATCH 06/45] chore(lint): register lint plugin in marketplace and
 document scope

Adds the lint plugin entry to both marketplace manifests and records
the resolved scope/structure decisions from grilling in CONTEXT.md:
standalone repo-agnostic plugin, split vale-config/vale-run skills,
report-only lint-runner agent, audit-pipeline wiring deferred.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
---
 .claude-plugin/marketplace.json | 7 ++++++-
 .github/plugin/marketplace.json | 7 ++++++-
 CONTEXT.md                      | 3 +++
 plugins/lint/.mcp.json          | 3 +++
 plugins/lint/hooks.json         | 3 +++
 5 files changed, 21 insertions(+), 2 deletions(-)
 create mode 100644 plugins/lint/.mcp.json
 create mode 100644 plugins/lint/hooks.json

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 4ee8774..d4877ff 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -38,7 +38,12 @@
         "repo": "mattpocock/skills",
         "source": "github"
       }
+    },
+    {
+      "description": "Skills and agents for configuring and running linters, starting with Vale.",
+      "name": "lint",
+      "source": "./plugins/lint"
     }
   ],
-  "version": "0.2.0"
+  "version": "0.3.0"
 }
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index 4ee8774..d4877ff 100644
--- a/.github/plugin/marketplace.json
+++ b/.github/plugin/marketplace.json
@@ -38,7 +38,12 @@
         "repo": "mattpocock/skills",
         "source": "github"
       }
+    },
+    {
+      "description": "Skills and agents for configuring and running linters, starting with Vale.",
+      "name": "lint",
+      "source": "./plugins/lint"
     }
   ],
-  "version": "0.2.0"
+  "version": "0.3.0"
 }
diff --git a/CONTEXT.md b/CONTEXT.md
index bb27229..e2cc184 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -66,5 +66,8 @@ A skill pair in the `core` plugin for writing, updating, and reviewing a repo's
 ### provider-adapter-author
 A companion skill (`core` plugin) that detects a target repo's provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." `agentsmd-author` calls this skill via skill composition when it detects an existing provider file with overlapping content.
 
+### lint plugin
+A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling, and not (yet) wired into `skill-audit`/`agent-audit`. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Wiring Vale into the audit pipeline as a prefilter (the original motivation captured in branch `feat/84-vale-audit-prefilter`) is deferred to a follow-up task once this plugin exists standalone. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
+
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/plugins/lint/.mcp.json b/plugins/lint/.mcp.json
new file mode 100644
index 0000000..da39e4f
--- /dev/null
+++ b/plugins/lint/.mcp.json
@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}
diff --git a/plugins/lint/hooks.json b/plugins/lint/hooks.json
new file mode 100644
index 0000000..deffac9
--- /dev/null
+++ b/plugins/lint/hooks.json
@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}
-- 
2.43.0


From cbc33d952efc4aaf605a2f3a2d447fa7af0adef6 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 20:39:25 +0000
Subject: [PATCH 07/45] feat(kyberforge): wire Vale as deterministic prefilter
 for skill-audit/agent-audit

Adds repo-root .vale.ini plus a custom Kyberforge style (description-opener,
vague-wording, and generic reference-pointer padding rules) and a
KyberforgeCopilot style scoped to .agent.md files (Use proactively check).
skill-audit and agent-audit Step 1 now run vale against the specific file(s)
being audited and defer the corresponding Description/Patterns/Body checks
to its output instead of re-deriving them by LLM judgment, per the split
proposed in issue #84.

Closes #84

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
---
 .vale.ini                                      | 11 +++++++++++
 CONTEXT.md                                     |  5 ++++-
 plugins/kyberforge/skills/agent-audit/SKILL.md | 10 +++++++---
 plugins/kyberforge/skills/skill-audit/SKILL.md | 10 +++++++---
 styles/Kyberforge/DescriptionOpener.yml        |  7 +++++++
 styles/Kyberforge/PaddingPhrase.yml            |  7 +++++++
 styles/Kyberforge/VagueWording.yml             | 10 ++++++++++
 styles/KyberforgeCopilot/ProactivePhrase.yml   |  7 +++++++
 8 files changed, 60 insertions(+), 7 deletions(-)
 create mode 100644 .vale.ini
 create mode 100644 styles/Kyberforge/DescriptionOpener.yml
 create mode 100644 styles/Kyberforge/PaddingPhrase.yml
 create mode 100644 styles/Kyberforge/VagueWording.yml
 create mode 100644 styles/KyberforgeCopilot/ProactivePhrase.yml

diff --git a/.vale.ini b/.vale.ini
new file mode 100644
index 0000000..c0d0410
--- /dev/null
+++ b/.vale.ini
@@ -0,0 +1,11 @@
+StylesPath = styles
+MinAlertLevel = suggestion
+
+[plugins/*/skills/*/SKILL.md]
+BasedOnStyles = Kyberforge
+
+[plugins/*/agents/*.md]
+BasedOnStyles = Kyberforge
+
+[plugins/*/agents/*.agent.md]
+BasedOnStyles = Kyberforge, KyberforgeCopilot
diff --git a/CONTEXT.md b/CONTEXT.md
index e2cc184..b9c1320 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -67,7 +67,10 @@ A skill pair in the `core` plugin for writing, updating, and reviewing a repo's
 A companion skill (`core` plugin) that detects a target repo's provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." `agentsmd-author` calls this skill via skill composition when it detects an existing provider file with overlapping content.
 
 ### lint plugin
-A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling, and not (yet) wired into `skill-audit`/`agent-audit`. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Wiring Vale into the audit pipeline as a prefilter (the original motivation captured in branch `feat/84-vale-audit-prefilter`) is deferred to a follow-up task once this plugin exists standalone. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
+A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
+
+### Vale audit prefilter (skill-audit / agent-audit)
+Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. Both skills' Step 1 run `vale --config .vale.ini <target>` against the specific file(s) being audited (never a repo-wide sweep) — Vale's glob matching crosses directory boundaries (`plugins/*/agents/*.md` matches nested `docs/research/examples/**/agents/*.md` too), so scoping every invocation to a known target file/dir is what keeps research-example files out of the audit's lint pass rather than the glob pattern itself. `error` alerts map to FAIL, `warning`/`suggestion` map to SUGGESTION. Vale only replaces the specific pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) — body discipline, near-miss exclusion strength, and control calibration stay LLM judgment per the issue's explicit non-goals.
 
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md
index 894a823..2897dd3 100644
--- a/plugins/kyberforge/skills/agent-audit/SKILL.md
+++ b/plugins/kyberforge/skills/agent-audit/SKILL.md
@@ -36,10 +36,13 @@ metadata:
 ```bash
 bash scripts/validate.sh <path-to-agent-file>
 bash scripts/validate-provenance.sh <path-to-agent-file>
+vale --config .vale.ini <path-to-cc-file> <path-to-copilot-file>
 ```
 
 The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
+Run `vale` from the repo root, against both files of the pair (not just the one passed in), using the repo-root `.vale.ini`. It applies the `Kyberforge` style to both files and the `KyberforgeCopilot` style to the `.agent.md` file only — that split is how the Copilot-only `Use proactively` check stays scoped to the Copilot file without a manual per-file judgment call. Map `error` alerts to `FAIL` and `warning`/`suggestion` alerts to `SUGGESTION` in the `### Description` / `### Body` dimensions below, citing the rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). If `vale` is not installed or `.vale.ini` is missing, skip this and fall back to the manual judgment calls in Step 2 — do not block the audit on tooling absence.
+
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
 If the scripts cannot run (Bash denied, python3 unavailable), perform checks manually: counterpart file exists, required fields present (`name`, `description`, non-empty body), `name` is kebab-case, Copilot CLI `.agent.md` `name` must match filename stem (CC files are exempt — the CC platform does not require name to match filename), no `FILL IN:` placeholders, no CC-only fields in Copilot file, no Copilot-only fields in CC file (read `references/field-inventory.md` for the authoritative field lists).
@@ -49,15 +52,16 @@ If the scripts cannot run (Bash denied, python3 unavailable), perform checks man
 Read both agent files. Work through each dimension internally. Collect findings only; report in Step 3.
 
 **Description (both files):**
-- Action-verb opening: description starts with a verb ("Reviews...", "Analyzes...", "Generates...") — FAIL if absent
-- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague
-- `Use proactively` in a Copilot description: CC-specific phrasing, has no effect in Copilot — SUGGESTION to remove
+- Action-verb opening: description starts with a verb ("Reviews...", "Analyzes...", "Generates...") — FAIL if absent. Vale's `Kyberforge.DescriptionOpener` alert flags the specific known-bad "This agent..." opener directly; verifying an arbitrary opening word is genuinely a strong verb still requires judgment.
+- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague. Vale's `Kyberforge.VagueWording` alert covers known filler ("helps with", "utilize", ...) directly; report those without re-deriving by judgment.
+- `Use proactively` in a Copilot description: Vale's `KyberforgeCopilot.ProactivePhrase` alert (Copilot file only) flags this directly — report it without re-deriving by judgment.
 
 If a description finding is borderline, read `references/description-quality.md`.
 
 **Body:**
 - Direct role instruction: system prompt opens with `You are a [role]. When invoked, [action].` — SUGGESTION if absent
 - One job per agent: system prompt describes a single bounded task — SUGGESTION if scope appears unbounded
+- Generic, non-specific reference pointers to the `references/` directory: Vale's `Kyberforge.PaddingPhrase` alert flags this directly — report it without re-deriving by judgment
 
 **Body/Frontmatter comments:**
 - Inspect each comment block in the YAML frontmatter. For each comment, apply: *"Would the agent get this wrong without this comment?"* Flag any that answer "no" as padding.
diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index eac4a0f..8923bb0 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -34,12 +34,15 @@ metadata:
 ```bash
 bash scripts/validate.sh <skill-dir>
 bash scripts/validate-provenance.sh <skill-dir>
+vale --config .vale.ini <skill-dir>/SKILL.md
 ```
 
 Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
+`vale` runs from the repo root against the target `SKILL.md` using the repo-root `.vale.ini` (custom `Kyberforge` style) — it is a deterministic prefilter for a subset of the Description and Patterns dimensions below, not a replacement for Step 3's qualitative pass. Map `error` alerts to `FAIL` and `warning`/`suggestion` alerts to `SUGGESTION` in the `### Description` / `### Patterns` report dimensions, citing the rule ID (e.g. `Kyberforge.DescriptionOpener`) as the finding. If `vale` is not installed or `.vale.ini` is missing, skip this and fall back to the manual judgment calls described in Step 3 — do not block the audit on tooling absence.
+
 ## Step 2 — Read all skill files
 
 Read every file in the skill directory: `SKILL.md`, `README.md` (if present), all files in `scripts/`, `references/`, `assets/`, and `tests/`. Skip binary files only. Do not skip text files — internal consistency checks require the full picture.
@@ -50,8 +53,9 @@ Work through each dimension internally. Collect findings only; report them in St
 
 ### Description
 
-- **Imperative phrasing**: does it use "Use when..." not "This skill..."?
-- **Specificity**: are capabilities stated precisely ("parses OpenAPI specs") or vaguely ("helps with APIs")?
+Vale's `Kyberforge.DescriptionOpener` (FAIL — "This skill..." openers) and `Kyberforge.VagueWording` (SUGGESTION — filler like "helps with", "utilize") alerts from Step 1 cover imperative phrasing and known vague-wording filler directly; report them as findings without re-deriving by judgment. The rest is still a judgment call:
+
+- **Specificity beyond the filler blocklist**: are capabilities stated precisely ("parses OpenAPI specs") or genuinely vaguely ("handles files")?
 - **Indirect triggers**: does it cover cases where the user doesn't name the domain directly?
 - **Near-miss exclusions**: are "Do not use when..." clauses present if a near-miss skill could steal activations?
 - **Length**: under 1024 characters?
@@ -75,7 +79,7 @@ Check each pattern is appropriate and correctly formed:
 - **Gotchas**: placed near the top; each entry is a specific fact that defies a reasonable assumption — not a general tip
 - **Prescriptive sequence**: inner code fences escaped as `\`\`\`` when nested inside a markdown block
 - **Checklists**: used for multi-step workflows, not single steps
-- **Conditional references**: specific trigger stated ("If X, read `references/file.md`") — not a generic "see references/"
+- **Conditional references**: specific trigger stated ("If X, read `references/file.md`") — not a generic "see references/". Vale's `Kyberforge.PaddingPhrase` alert from Step 1 flags the generic phrasing directly; other malformed conditional-reference forms still require judgment.
 - **Output templates**: present when the agent must produce a specific format; absent otherwise
 
 ### File structure
diff --git a/styles/Kyberforge/DescriptionOpener.yml b/styles/Kyberforge/DescriptionOpener.yml
new file mode 100644
index 0000000..d978d73
--- /dev/null
+++ b/styles/Kyberforge/DescriptionOpener.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Description opens with '%s' — use an imperative 'Use when...' opener instead"
+level: error
+scope: text.frontmatter.description
+ignorecase: true
+raw:
+  - '^This (skill|agent)\b'
diff --git a/styles/Kyberforge/PaddingPhrase.yml b/styles/Kyberforge/PaddingPhrase.yml
new file mode 100644
index 0000000..189cc66
--- /dev/null
+++ b/styles/Kyberforge/PaddingPhrase.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Generic reference pointer: '%s' — use the specific 'If X, read `references/file.md`' form instead"
+level: warning
+scope: text
+ignorecase: true
+raw:
+  - 'see references?/? for (more )?(info|information|details)\b'
diff --git a/styles/Kyberforge/VagueWording.yml b/styles/Kyberforge/VagueWording.yml
new file mode 100644
index 0000000..7490aaf
--- /dev/null
+++ b/styles/Kyberforge/VagueWording.yml
@@ -0,0 +1,10 @@
+extends: existence
+message: "Vague capability wording: '%s' — state the capability precisely instead"
+level: warning
+scope: text.frontmatter.description
+ignorecase: true
+tokens:
+  - helps with
+  - utilize
+  - assists with
+  - used for
diff --git a/styles/KyberforgeCopilot/ProactivePhrase.yml b/styles/KyberforgeCopilot/ProactivePhrase.yml
new file mode 100644
index 0000000..d23f8b7
--- /dev/null
+++ b/styles/KyberforgeCopilot/ProactivePhrase.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "'%s' is CC-specific phrasing with no effect in Copilot descriptions — remove it"
+level: warning
+scope: text.frontmatter.description
+ignorecase: true
+tokens:
+  - Use proactively
-- 
2.43.0


From 8d56290414ef9fcf49ee3281f468a62769f1103c Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Thu, 23 Jul 2026 20:51:15 +0000
Subject: [PATCH 08/45] feat(lint): wire Vale as commit-stage pre-commit hook

Adds vale-audit-prefilter as a local pre-commit hook scoped to skill/agent
markdown files, matching the invocation pattern skill-audit/agent-audit
already use. Runs at commit-stage only since it's a fast deterministic
prefilter; push-stage already covers the full test suite and manifest checks.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
---
 .pre-commit-config.yaml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 39ae3de..cb404ed 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -98,6 +98,15 @@ repos:
               fi
             done
 
+      - id: vale-audit-prefilter
+        stages: ['pre-commit']
+        name: Vale audit prefilter
+        description: Run Vale against skill/agent markdown files as a deterministic prefilter for skill-audit/agent-audit
+        entry: vale --config .vale.ini
+        language: unsupported
+        files: '^plugins/.*/(skills/.*/SKILL\.md|agents/.*\.md)$'
+        pass_filenames: true
+
   - repo: meta
     hooks:
       - id: check-hooks-apply
-- 
2.43.0


From bbb0dcd21a2f5fe53e33c7f18247798616b97764 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Fri, 24 Jul 2026 10:16:35 +0000
Subject: [PATCH 09/45] fix(lint): flatten multi-line frontmatter descriptions
 before Vale runs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Vale's text.frontmatter.description scope silently stops matching once
the description is a YAML block scalar spanning 2+ physical lines —
the style used by most skills/agents in this repo. scripts/vale-wrap.sh
flattens the description to one line in a scratch copy (preserving the
repo-relative path and total line count) before invoking real vale, and
both audit skills plus the pre-commit hook now call it instead of vale
directly. Also tightens the pre-commit hook's file glob to single path
segments so it can't cross into docs/research examples or asset
templates the way the audit skills' scoped invocations already avoid.

Addresses PR #85 review feedback.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxG5T8EJDgkABXxuneuFfn
---
 .pre-commit-config.yaml                       |  6 +-
 CONTEXT.md                                    |  4 +-
 .../kyberforge/skills/agent-audit/SKILL.md    |  4 +-
 .../kyberforge/skills/skill-audit/SKILL.md    |  4 +-
 plugins/lint/skills/vale-config/SKILL.md      |  1 +
 scripts/vale-wrap.sh                          | 79 ++++++++++++++++++
 tests/test-vale-wrap.sh                       | 83 +++++++++++++++++++
 7 files changed, 173 insertions(+), 8 deletions(-)
 create mode 100755 scripts/vale-wrap.sh
 create mode 100755 tests/test-vale-wrap.sh

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index cb404ed..586ef59 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -102,9 +102,9 @@ repos:
         stages: ['pre-commit']
         name: Vale audit prefilter
         description: Run Vale against skill/agent markdown files as a deterministic prefilter for skill-audit/agent-audit
-        entry: vale --config .vale.ini
-        language: unsupported
-        files: '^plugins/.*/(skills/.*/SKILL\.md|agents/.*\.md)$'
+        entry: scripts/vale-wrap.sh --config .vale.ini
+        language: script
+        files: '^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$'
         pass_filenames: true
 
   - repo: meta
diff --git a/CONTEXT.md b/CONTEXT.md
index b9c1320..8e9bfe8 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -70,7 +70,9 @@ A companion skill (`core` plugin) that detects a target repo's provider-specific
 A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
 
 ### Vale audit prefilter (skill-audit / agent-audit)
-Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. Both skills' Step 1 run `vale --config .vale.ini <target>` against the specific file(s) being audited (never a repo-wide sweep) — Vale's glob matching crosses directory boundaries (`plugins/*/agents/*.md` matches nested `docs/research/examples/**/agents/*.md` too), so scoping every invocation to a known target file/dir is what keeps research-example files out of the audit's lint pass rather than the glob pattern itself. `error` alerts map to FAIL, `warning`/`suggestion` map to SUGGESTION. Vale only replaces the specific pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) — body discipline, near-miss exclusion strength, and control calibration stay LLM judgment per the issue's explicit non-goals.
+Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. `error` alerts map to FAIL, `warning`/`suggestion` map to SUGGESTION. Vale only replaces the specific pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) — body discipline, near-miss exclusion strength, and control calibration stay LLM judgment per the issue's explicit non-goals.
+
+Both skills' Step 1, and the `vale-audit-prefilter` pre-commit hook, call `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched. `tests/test-vale-wrap.sh` regression-tests this. Both call sites still scope every invocation to the specific file(s) being audited, never a repo-wide sweep — Vale's glob matching crosses directory boundaries (`plugins/*/agents/*.md` matches nested `docs/research/examples/**/agents/*.md` too), so scoping is what keeps research-example files out of the audit's lint pass. The pre-commit hook's own glob is tightened to `^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$` (single-segment, not `.*`) for the same reason, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target.
 
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md
index 2897dd3..6c5786b 100644
--- a/plugins/kyberforge/skills/agent-audit/SKILL.md
+++ b/plugins/kyberforge/skills/agent-audit/SKILL.md
@@ -36,12 +36,12 @@ metadata:
 ```bash
 bash scripts/validate.sh <path-to-agent-file>
 bash scripts/validate-provenance.sh <path-to-agent-file>
-vale --config .vale.ini <path-to-cc-file> <path-to-copilot-file>
+scripts/vale-wrap.sh --config .vale.ini <path-to-cc-file> <path-to-copilot-file>
 ```
 
 The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
-Run `vale` from the repo root, against both files of the pair (not just the one passed in), using the repo-root `.vale.ini`. It applies the `Kyberforge` style to both files and the `KyberforgeCopilot` style to the `.agent.md` file only — that split is how the Copilot-only `Use proactively` check stays scoped to the Copilot file without a manual per-file judgment call. Map `error` alerts to `FAIL` and `warning`/`suggestion` alerts to `SUGGESTION` in the `### Description` / `### Body` dimensions below, citing the rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). If `vale` is not installed or `.vale.ini` is missing, skip this and fall back to the manual judgment calls in Step 2 — do not block the audit on tooling absence.
+Run `vale-wrap.sh` from the repo root against both files of the pair (not just the one passed in), using `.vale.ini`. `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in the `### Description` / `### Body` dimensions, citing the rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable.
 
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index 8923bb0..18c2084 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -34,14 +34,14 @@ metadata:
 ```bash
 bash scripts/validate.sh <skill-dir>
 bash scripts/validate-provenance.sh <skill-dir>
-vale --config .vale.ini <skill-dir>/SKILL.md
+scripts/vale-wrap.sh --config .vale.ini <skill-dir>/SKILL.md
 ```
 
 Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
-`vale` runs from the repo root against the target `SKILL.md` using the repo-root `.vale.ini` (custom `Kyberforge` style) — it is a deterministic prefilter for a subset of the Description and Patterns dimensions below, not a replacement for Step 3's qualitative pass. Map `error` alerts to `FAIL` and `warning`/`suggestion` alerts to `SUGGESTION` in the `### Description` / `### Patterns` report dimensions, citing the rule ID (e.g. `Kyberforge.DescriptionOpener`) as the finding. If `vale` is not installed or `.vale.ini` is missing, skip this and fall back to the manual judgment calls described in Step 3 — do not block the audit on tooling absence.
+`vale-wrap.sh` runs from the repo root using `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns dimensions below, not a replacement for Step 3. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in those dimensions, citing the rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable.
 
 ## Step 2 — Read all skill files
 
diff --git a/plugins/lint/skills/vale-config/SKILL.md b/plugins/lint/skills/vale-config/SKILL.md
index 43591c4..731b361 100644
--- a/plugins/lint/skills/vale-config/SKILL.md
+++ b/plugins/lint/skills/vale-config/SKILL.md
@@ -22,6 +22,7 @@ metadata:
 - Installing the `vale` binary installs no styles. A fresh `.vale.ini` with `BasedOnStyles` set will fail or find nothing until `vale sync` runs and downloads the `Packages` it declares.
 - `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob.
 - `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget.
+- A rule scoped to `text.frontmatter.<key>` (e.g. `text.frontmatter.description`) only reliably matches when that field's value is a single physical line. If it's a YAML block scalar (`>`/`|`) spanning 2+ physical lines, the scope silently stops matching — no error, just 0 findings — confirmed against Vale 3.15.2. Verify with a deliberately-bad multi-line fixture before trusting a frontmatter-scoped rule in production; if the field is commonly authored as a multi-line block scalar, flatten it to one line ahead of the `vale` call rather than relying on the scope alone.
 
 ## Setup workflow
 
diff --git a/scripts/vale-wrap.sh b/scripts/vale-wrap.sh
new file mode 100755
index 0000000..67b69fa
--- /dev/null
+++ b/scripts/vale-wrap.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Works around a Vale limitation: the `text.frontmatter.description` NLP scope
+# silently stops matching once the `description:` value is a YAML block scalar
+# (`>`/`|`) spanning 2+ physical lines — the style used by most skills/agents in
+# this repo. Flattens the description to one physical line in a scratch copy
+# (padding with blank lines so every other line number is unchanged), then runs
+# the real `vale` binary against the copies. Drop-in replacement for calling
+# `vale` directly: same args, same exit code.
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+vale_args=()
+files=()
+config_next=false
+for arg in "$@"; do
+  if [[ "$config_next" == true ]]; then
+    if [[ "$arg" == /* ]]; then
+      vale_args+=("$arg")
+    else
+      vale_args+=("$repo_root/$arg")
+    fi
+    config_next=false
+    continue
+  fi
+  if [[ "$arg" == "--config" ]]; then
+    vale_args+=("$arg")
+    config_next=true
+    continue
+  fi
+  if [[ "$arg" != -* && -f "$repo_root/$arg" ]]; then
+    files+=("$arg")
+  else
+    vale_args+=("$arg")
+  fi
+done
+
+if [[ ${#files[@]} -eq 0 ]]; then
+  exec vale "${vale_args[@]}"
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+for rel in "${files[@]}"; do
+  dest="$tmpdir/$rel"
+  mkdir -p "$(dirname "$dest")"
+  python3 - "$repo_root/$rel" "$dest" <<'PYTHON'
+import json
+import re
+import sys
+
+src, dest = sys.argv[1], sys.argv[2]
+with open(src) as fh:
+    content = fh.read()
+
+fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
+if fm_match:
+    fm = fm_match.group(2)
+    desc_m = re.search(r'^description:\s*([>|][+-]?)\n((?:[ \t]+.+\n?)+)', fm, re.MULTILINE)
+    if desc_m and desc_m.group(2).count('\n') >= 2:
+        raw = desc_m.group(2)
+        flat = re.sub(r'\s+', ' ', raw).strip()
+        # JSON string escaping is a valid subset of YAML double-quoted scalar
+        # escaping, so this is always a well-formed YAML value regardless of
+        # colons, quotes, or backslashes in the description text.
+        flat_q = json.dumps(flat)
+        pad = '\n' * raw.count('\n')
+        new_fm = fm[:desc_m.start()] + f'description: {flat_q}\n{pad}' + fm[desc_m.end():]
+        content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
+
+with open(dest, 'w') as fh:
+    fh.write(content)
+PYTHON
+done
+
+cd "$tmpdir"
+vale "${vale_args[@]}" "${files[@]}"
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
new file mode 100755
index 0000000..729c0b5
--- /dev/null
+++ b/tests/test-vale-wrap.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Regression test for scripts/vale-wrap.sh: Vale's `text.frontmatter.description`
+# NLP scope silently stops matching when the description value is a YAML block
+# scalar spanning 2+ physical lines. vale-wrap.sh flattens it to one line before
+# handing off to the real vale binary — this asserts that actually happens.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="$REPO_ROOT/scripts/vale-wrap.sh"
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+if ! command -v vale &>/dev/null; then
+  echo "vale is not installed — skipping (matches skill-audit/agent-audit's own fallback behavior)"
+  exit 0
+fi
+
+make_fixture() {
+  local dir desc_lines file
+  dir="$(mktemp -d)"
+  (cd "$dir" && git init -q)
+  mkdir -p "$dir/plugins/testplugin/skills/zzzskill"
+  desc_lines="$1"
+  file="$dir/plugins/testplugin/skills/zzzskill/SKILL.md"
+  {
+    echo "---"
+    echo "name: zzzskill"
+    echo "description: >"
+    for ((i = 1; i <= desc_lines; i++)); do
+      echo "  Line $i mentions helps with and utilize, plus a colon: like this."
+    done
+    echo "---"
+    echo ""
+    echo "Body."
+  } > "$file"
+  echo "$dir"
+}
+
+# --- 1. A known-bad single-line description is caught (sanity check on Vale itself) ---
+echo ""
+echo "--- catches vague wording in a single-line description ---"
+FIXTURE1="$(make_fixture 1)"
+trap 'rm -rf "$FIXTURE1"' EXIT
+if (cd "$FIXTURE1" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when description is a single physical line"
+else
+  fail "did not flag known-bad single-line description"
+fi
+
+# --- 2. The same known-bad wording across 2+ physical lines is still caught ---
+echo ""
+echo "--- catches vague wording in a multi-line folded description ---"
+FIXTURE2="$(make_fixture 2)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2"' EXIT
+if (cd "$FIXTURE2" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when description spans 2+ physical lines"
+else
+  fail "silently missed known-bad wording in a multi-line description — the bug this test guards against"
+fi
+
+# --- 3. Line count is preserved so unrelated report line numbers don't shift ---
+echo ""
+echo "--- preserves total line count when flattening ---"
+FIXTURE3="$(make_fixture 3)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3"' EXIT
+ORIG_LINES=$(wc -l < "$FIXTURE3/plugins/testplugin/skills/zzzskill/SKILL.md")
+OUT=$(cd "$FIXTURE3" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1 || true)
+MAX_LINE=$(echo "$OUT" | grep -oE '^[[:space:]]*[0-9]+:[0-9]+' | tr -d '[:space:]' | cut -d: -f1 | sort -n | tail -1)
+if [[ -n "$MAX_LINE" ]] && (( MAX_LINE <= ORIG_LINES )); then
+  pass "reported line numbers stay within the original file's line count"
+else
+  fail "reported line number ($MAX_LINE) exceeds original file line count ($ORIG_LINES)"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]
-- 
2.43.0


From 544392be98af5e14883aa1334e95680fffed9ea8 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Fri, 24 Jul 2026 12:24:36 +0000
Subject: [PATCH 10/45] refactor(lint): genericize lint-runner dispatch and
 manifest wording

lint-runner's description already promised other linters could be added
without changing its own contract, but Process hardcoded vale-config/
vale-run and .vale.ini by name. Switch to <linter>-config/<linter>-run
naming-convention dispatch so the promise holds. Drop the explicit
Vale callout from the plugin manifests' description/keywords to match.

Addresses a deferred item from PR #85 review.
---
 plugins/lint/.claude-plugin/plugin.json  | 5 ++---
 plugins/lint/agents/lint-runner.agent.md | 8 ++++----
 plugins/lint/agents/lint-runner.md       | 8 ++++----
 plugins/lint/plugin.json                 | 5 ++---
 4 files changed, 12 insertions(+), 14 deletions(-)

diff --git a/plugins/lint/.claude-plugin/plugin.json b/plugins/lint/.claude-plugin/plugin.json
index 1545578..b0b2c8a 100644
--- a/plugins/lint/.claude-plugin/plugin.json
+++ b/plugins/lint/.claude-plugin/plugin.json
@@ -3,16 +3,15 @@
     "name": "Defame1297",
     "url": "https://git.dev.rkdr.net/Defame1297/"
   },
-  "description": "Skills and agents for configuring and running linters, starting with Vale.",
+  "description": "Skills and agents for configuring and running linters.",
   "displayName": "Lint",
   "keywords": [
     "lint",
-    "vale",
     "style",
     "prose",
     "linter"
   ],
   "license": "MIT",
   "name": "lint",
-  "version": "1.1.0"
+  "version": "1.1.1"
 }
diff --git a/plugins/lint/agents/lint-runner.agent.md b/plugins/lint/agents/lint-runner.agent.md
index c21c4b2..6e6a35b 100644
--- a/plugins/lint/agents/lint-runner.agent.md
+++ b/plugins/lint/agents/lint-runner.agent.md
@@ -13,15 +13,15 @@ You are a linter runner. When invoked, you run the appropriate linter(s) over th
 
 - **scope:** file path, directory path, or glob to lint
 - **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
-- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini`); if none exists, say so in your report rather than inventing one
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini` for Vale, or whatever config format the requested linter expects); if none exists, say so in your report rather than inventing one
 
 ## Process
 
-1. Determine whether the target scope already has linter configuration in place (e.g. `.vale.ini` for Vale). If not, use the `vale-config` skill to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
-2. Use the `vale-run` skill to invoke the linter over the scope and interpret its raw output.
+1. Determine whether the target scope already has configuration in place for the requested `linter` (whatever config format that linter expects). If not, use the `<linter>-config` skill (e.g. `vale-config` when `linter` is `vale`) to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `<linter>-run` skill (e.g. `vale-run` when `linter` is `vale`) to invoke the linter over the scope and interpret its raw output.
 3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
 4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
-5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), report that as a blocking finding rather than attempting to install or configure it silently.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), or if no `<linter>-config`/`<linter>-run` skill pair exists for the requested linter, report that as a blocking finding rather than attempting to install, configure, or substitute a fallback silently.
 
 ## Output
 
diff --git a/plugins/lint/agents/lint-runner.md b/plugins/lint/agents/lint-runner.md
index de0ebfb..34a2fba 100644
--- a/plugins/lint/agents/lint-runner.md
+++ b/plugins/lint/agents/lint-runner.md
@@ -13,15 +13,15 @@ You are a linter runner. When invoked, you run the appropriate linter(s) over th
 
 - **scope:** file path, directory path, or glob to lint
 - **linter:** which linter to run (defaults to `vale` — the only backend currently wired up)
-- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini`); if none exists, say so in your report rather than inventing one
+- **config context:** any project-specific linter configuration already in place (e.g. an existing `.vale.ini` for Vale, or whatever config format the requested linter expects); if none exists, say so in your report rather than inventing one
 
 ## Process
 
-1. Determine whether the target scope already has linter configuration in place (e.g. `.vale.ini` for Vale). If not, use the `vale-config` skill to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
-2. Use the `vale-run` skill to invoke the linter over the scope and interpret its raw output.
+1. Determine whether the target scope already has configuration in place for the requested `linter` (whatever config format that linter expects). If not, use the `<linter>-config` skill (e.g. `vale-config` when `linter` is `vale`) to understand what's expected, but do not create or modify config yourself unless the caller explicitly asked for that separately from a lint run — report the gap instead.
+2. Use the `<linter>-run` skill (e.g. `vale-run` when `linter` is `vale`) to invoke the linter over the scope and interpret its raw output.
 3. Normalize findings into one shape regardless of backend linter: file, line, rule/check, severity, message.
 4. Do not edit, fix, or rewrite any flagged content. If a finding looks trivially fixable, note that in the report — do not act on it.
-5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), report that as a blocking finding rather than attempting to install or configure it silently.
+5. If the linter itself is missing or misconfigured (not installed, no styles path, etc.), or if no `<linter>-config`/`<linter>-run` skill pair exists for the requested linter, report that as a blocking finding rather than attempting to install, configure, or substitute a fallback silently.
 
 ## Output
 
diff --git a/plugins/lint/plugin.json b/plugins/lint/plugin.json
index b5eae4e..3af77e3 100644
--- a/plugins/lint/plugin.json
+++ b/plugins/lint/plugin.json
@@ -4,11 +4,10 @@
     "email": "defame1297@rkdr.net",
     "name": "Defame1297"
   },
-  "description": "Skills and agents for configuring and running linters, starting with Vale.",
+  "description": "Skills and agents for configuring and running linters.",
   "hooks": "hooks.json",
   "keywords": [
     "lint",
-    "vale",
     "style",
     "prose",
     "linter"
@@ -19,5 +18,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.1.0"
+  "version": "1.1.1"
 }
-- 
2.43.0


From 3324a73225233bc6f2bc9318559292fee4beb88f Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Fri, 24 Jul 2026 20:04:10 +0000
Subject: [PATCH 11/45] feat(lint): expand Vale audit prefilter into a broader
 plugin-content harness

Deferred item from PR #85 review. Per ADR-0013: cherry-picks two low-noise
rules from trialing write-good/alex against the real corpus (VagueQualifier,
SentenceOpenerThereIs) into styles/Kyberforge rather than adopting either
package wholesale (both are tuned for blog prose and were noisy on this
repo's terse, imperative instruction files - see the ADR's rejected-rule
list). Adds a new skill-size-check pre-commit hook enforcing agentskills.io's
500-line/5,000-token SKILL.md ceiling, currently unenforced. Fixes the 28
resulting violations across 20 existing SKILL.md/agent files so the
enforcing pre-commit hook lands clean.

governance.md/CONTROLS.md were evaluated and excluded as rule sources -
they're org/CI-infrastructure controls, not prose patterns Vale can express.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QUDczvw1H3eEeMD29Q9Lbi
---
 .pre-commit-config.yaml                       |  9 ++
 CONTEXT.md                                    |  2 +
 ...013-vale-harness-scope-and-rule-sources.md | 84 +++++++++++++++++++
 plugins/bin/skills/caveman/SKILL.md           |  2 +-
 plugins/bin/skills/diagnose/SKILL.md          |  4 +-
 .../improve-codebase-architecture/SKILL.md    |  2 +-
 plugins/bin/skills/prototype/SKILL.md         | 10 +--
 plugins/bin/skills/tdd/SKILL.md               |  2 +-
 plugins/bin/skills/write-docs/SKILL.md        |  2 +-
 plugins/git/skills/git-branches/SKILL.md      |  2 +-
 plugins/git/skills/pc-author/SKILL.md         |  2 +-
 plugins/gitea/skills/gitea-issues/SKILL.md    |  6 +-
 plugins/gitea/skills/gitea-prs/SKILL.md       |  2 +-
 plugins/gitea/skills/gitea-releases/SKILL.md  |  4 +-
 plugins/gitea/skills/gitea-workflow/SKILL.md  |  4 +-
 .../kyberforge/skills/agent-author/SKILL.md   |  2 +-
 plugins/kyberforge/skills/forge/SKILL.md      |  2 +-
 .../skills/marketplace-author/SKILL.md        |  2 +-
 .../kyberforge/skills/skill-author/SKILL.md   |  2 +-
 scripts/skill-size-check.sh                   | 35 ++++++++
 styles/Kyberforge/SentenceOpenerThereIs.yml   |  7 ++
 styles/Kyberforge/VagueQualifier.yml          | 36 ++++++++
 tests/test-skill-size-check.sh                | 65 ++++++++++++++
 23 files changed, 263 insertions(+), 25 deletions(-)
 create mode 100644 docs/adr/0013-vale-harness-scope-and-rule-sources.md
 create mode 100755 scripts/skill-size-check.sh
 create mode 100644 styles/Kyberforge/SentenceOpenerThereIs.yml
 create mode 100644 styles/Kyberforge/VagueQualifier.yml
 create mode 100755 tests/test-skill-size-check.sh

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 586ef59..ad1a9d6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -98,6 +98,15 @@ repos:
               fi
             done
 
+      - id: skill-size-check
+        stages: ['pre-commit']
+        name: SKILL.md size ceiling
+        description: Enforce agentskills.io's 500-line/5,000-token SKILL.md size ceiling
+        entry: scripts/skill-size-check.sh
+        language: script
+        files: '^plugins/[^/]+/skills/[^/]+/SKILL\.md$'
+        pass_filenames: true
+
       - id: vale-audit-prefilter
         stages: ['pre-commit']
         name: Vale audit prefilter
diff --git a/CONTEXT.md b/CONTEXT.md
index 8e9bfe8..5b2e90b 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -74,5 +74,7 @@ Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Descr
 
 Both skills' Step 1, and the `vale-audit-prefilter` pre-commit hook, call `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched. `tests/test-vale-wrap.sh` regression-tests this. Both call sites still scope every invocation to the specific file(s) being audited, never a repo-wide sweep — Vale's glob matching crosses directory boundaries (`plugins/*/agents/*.md` matches nested `docs/research/examples/**/agents/*.md` too), so scoping is what keeps research-example files out of the audit's lint pass. The pre-commit hook's own glob is tightened to `^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$` (single-segment, not `.*`) for the same reason, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target.
 
+This scope expands per ADR-0013: cherry-picked low-noise `write-good`/`alex` rules into `styles/Kyberforge` (still pending implementation) plus a new sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing `skill-authoring.md`'s 500-line/5,000-token `SKILL.md` ceiling — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter`, so it never lints `docs/research/examples/` reference skills. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine).
+
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/docs/adr/0013-vale-harness-scope-and-rule-sources.md b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
new file mode 100644
index 0000000..c867ab5
--- /dev/null
+++ b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
@@ -0,0 +1,84 @@
+# Vale audit prefilter expands into a plugin-content harness, scoped to prose-pattern rules only
+
+Issue #84 wired Vale as a deterministic prefilter for `skill-audit`/`agent-audit`, scoped to
+exactly four pattern-matchable checks (imperative description opener, vague capability wording,
+generic reference-pointer padding, Copilot's dead `Use proactively` phrasing), documented only in
+CONTEXT.md's "Vale audit prefilter" section — never its own ADR — and explicitly excluding body
+discipline, near-miss exclusion strength, and control calibration as non-goals. This ADR records a
+deferred PR #85 review item to broaden that coverage, retroactively captures #84's own rationale
+(since it was never recorded as a decision in its own right), and layers the expansion on top
+without reversing or weakening the original four rules.
+
+**File scope stays the same.** `SKILL.md` plus agent files (`plugins/*/agents/*.md`,
+`plugins/*/agents/*.agent.md`) only — matching the existing prefilter's globs. Skill-level
+`README.md` files and `plugin.json` manifests are not added: README.md files are navigational, not
+spec-governed content, and `plugin.json` is JSON, not prose Vale can meaningfully lint.
+
+**Rule categories are prose-pattern-matchable only.** Structural, schema, and security concerns
+stay out of this Vale-based harness because this repo already has dedicated tools for them:
+`skill-frontmatter` (required frontmatter fields), `validate-plugins`/`validate-marketplace`
+(`claude plugin validate --strict`, schema), and `gitleaks`/`detect-private-key` (secrets).
+Duplicating those concerns as Vale rules would fight tools that already own them better.
+
+**Governance docs are excluded as a rule source.** `docs/research/governance_principles/CONTROLS.md`
+and `governance.md` were investigated and found to contribute nothing minable: CONTROLS.md is
+org/CI-infrastructure controls (secret scanning, dependency/license scanning, agent permission
+scoping, audit logging, human approval gates, periodic reviews) — none of it is a prose pattern
+expressible as a Vale rule against SKILL.md/agent-file text, and what it does cover is either
+already handled elsewhere (gitleaks) or genuinely out of scope for a plugin-content prose harness
+(dependency/license scanning is a code-dependency concern, not skill authoring).
+
+**Spec-derived custom rules stay mostly as-is.** Re-reading agentskills.io's
+`optimizing-descriptions.md` and `skill-authoring.md`, plus `claude-code-plugins/agent-definition.md`
+and `github-copilot-plugins/agent-definition.md`, found that the existing four Kyberforge rules
+already cover the pattern-matchable surface those specs describe. The remaining spec guidance —
+calibrating control vs. giving freedom, avoiding menus of options, coherent skill scope, moderate
+detail level — is semantic judgment, already `skill-audit`'s job via LLM review, not new lintable
+rules. One confirmation surfaced: Claude Code's `Use proactively` phrasing is meaningful for `.md`
+agent files (it triggers auto-invocation), unlike Copilot's `.agent.md` files where it's dead
+phrasing — so `KyberforgeCopilot/ProactivePhrase`'s existing `.agent.md`-only scope is correct and
+must not be extended to `.md` files.
+
+**`write-good`/`alex` are trialed, not adopted wholesale.** These built-in/third-party Vale
+packages are tuned for general blog-style prose (passive voice, weasel words, wordy phrases) and
+are expected to be noisy against this repo's terse, imperative instruction-file corpus. Only
+individual rules proven low-noise against the existing corpus get cherry-picked into
+`styles/Kyberforge`; the packages are never referenced wholesale in `BasedOnStyles`.
+
+**A new non-Vale check closes a real gap.** `skill-authoring.md` states `SKILL.md` should stay
+under 500 lines / 5,000 tokens — currently unenforced anywhere in this repo. This is a whole-file
+length ceiling, not a text pattern, so it isn't a Vale rule — it becomes a new deterministic script
+and pre-commit hook, sibling to the existing `skill-frontmatter` hook.
+
+**Rules land directly in `styles/Kyberforge`, enforcing immediately.** No trial/report-only tier
+is introduced (see Considered Options). The implementation pass finalizes the cherry-picked
+`write-good`/`alex` rules and any new spec-derived rule wording, runs the full set against the
+existing SKILL.md/agent-file corpus, fixes any resulting violations across that corpus, and lands
+the rule changes and the corpus fixes as one atomic commit — the same enforcement model as the
+original four rules, never a partial or opt-in state.
+
+## Considered options
+
+**Phased rollout via a separate trial style + config (rejected).** A `styles/KyberforgeTrial/`
+directory plus a parallel `.vale.trial.ini` (mirroring the root config's globs but with
+`BasedOnStyles = Kyberforge, KyberforgeTrial`) would let new rules be swept report-only via
+`lint-runner`/`vale-run` before promotion into the enforcing `styles/Kyberforge` + root
+`.vale.ini`. This was considered because `BasedOnStyles = Kyberforge` activates every rule file
+under that directory automatically — there's no partial/opt-in application within a style, so a
+rule dropped straight into `styles/Kyberforge` goes live in the blocking pre-commit hook
+immediately. Rejected in favor of finalizing rules directly and fixing violations via subagent
+before committing: simpler, no new trial-config machinery to build or maintain — at the cost of no
+standing report-only tier for future candidate rules.
+
+## Consequences
+
+- `styles/Kyberforge/` will gain new rule files once the (separate, later) implementation pass
+  finalizes the exact cherry-picked `write-good`/`alex` rules and any new wording — none are named
+  by this ADR, since none have been chosen yet.
+- A new pre-commit hook (name TBD by the implementer) enforces the 500-line/5,000-token `SKILL.md`
+  ceiling, sibling to `skill-frontmatter`.
+- `styles/KyberforgeTrial/` and `.vale.trial.ini` are deliberately not created — noted here so a
+  future reader doesn't wonder if a trial tier was forgotten.
+- Follow-up work — not part of this ADR — is: syncing and trialing `write-good`/`alex`, cherry-picking
+  low-noise rules, writing the size-ceiling script and hook, fixing existing corpus violations, and
+  the atomic commit landing all of it.
diff --git a/plugins/bin/skills/caveman/SKILL.md b/plugins/bin/skills/caveman/SKILL.md
index 85770a3..632e132 100644
--- a/plugins/bin/skills/caveman/SKILL.md
+++ b/plugins/bin/skills/caveman/SKILL.md
@@ -15,7 +15,7 @@ ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drif
 
 ## Rules
 
-Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+Drop: articles (a/an/the), filler (just/really/basically/actually/literally), pleasantries (sure/certainly/no worries/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
 
 Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
 
diff --git a/plugins/bin/skills/diagnose/SKILL.md b/plugins/bin/skills/diagnose/SKILL.md
index ed55bda..9f444d5 100644
--- a/plugins/bin/skills/diagnose/SKILL.md
+++ b/plugins/bin/skills/diagnose/SKILL.md
@@ -86,7 +86,7 @@ Tool preference:
 
 **Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
 
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+**Perf branch.** For performance regressions, logs rarely reveal the cause. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
 
 ## Phase 5 — Fix + regression test
 
@@ -111,7 +111,7 @@ Required before declaring done:
 - [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
 - [ ] Regression test passes (or absence of seam is documented)
 - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] Throwaway prototypes deleted (or moved to an explicitly-marked debug location)
 - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
 
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
diff --git a/plugins/bin/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/skills/improve-codebase-architecture/SKILL.md
index 05984a6..71cee67 100644
--- a/plugins/bin/skills/improve-codebase-architecture/SKILL.md
+++ b/plugins/bin/skills/improve-codebase-architecture/SKILL.md
@@ -55,7 +55,7 @@ Present a numbered list of deepening opportunities. For each candidate:
 
 **Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
 
-**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Flag it explicitly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
 
 Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
 
diff --git a/plugins/bin/skills/prototype/SKILL.md b/plugins/bin/skills/prototype/SKILL.md
index 8bd99d8..664ec88 100644
--- a/plugins/bin/skills/prototype/SKILL.md
+++ b/plugins/bin/skills/prototype/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: prototype
-description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
+description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or multiple radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
 ---
 
 # Prototype
@@ -11,14 +11,14 @@ A prototype is **throwaway code that answers a question**. The question decides
 
 Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
 
-- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
-- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a minimal interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → [UI.md](UI.md). Generate multiple radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
 
-The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+The two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
 
 ## Rules that apply to both
 
-1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+1. **Throwaway from day one, and labeled as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so the context is unambiguous — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
 2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is *checking*, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
 4. **Skip the polish.** No tests, no error handling beyond what makes the prototype *runnable*, no abstractions. The point is to learn something fast and then delete it.
diff --git a/plugins/bin/skills/tdd/SKILL.md b/plugins/bin/skills/tdd/SKILL.md
index 7a98941..cdd0dad 100644
--- a/plugins/bin/skills/tdd/SKILL.md
+++ b/plugins/bin/skills/tdd/SKILL.md
@@ -91,7 +91,7 @@ Rules:
 After all tests pass, look for [refactor candidates](refactoring.md):
 
 - [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Deepen modules (move complexity behind narrow interfaces)
 - [ ] Apply SOLID principles where natural
 - [ ] Consider what new code reveals about existing code
 - [ ] Run tests after each refactor step
diff --git a/plugins/bin/skills/write-docs/SKILL.md b/plugins/bin/skills/write-docs/SKILL.md
index 0d2da2d..1d6ccb2 100644
--- a/plugins/bin/skills/write-docs/SKILL.md
+++ b/plugins/bin/skills/write-docs/SKILL.md
@@ -61,7 +61,7 @@ You are a technical writer that produces documentation by reading code and spec
 
 1. **Identify scope.** User names specific files or sections. If not provided, propose candidates based on the description — wait for explicit approval before reading.
 
-2. **Read and extract.** Read approved files. Extract: public API surface, described behaviour, visible constraints, non-obvious invariants. Note what the code does NOT explain (caller intent, error handling rationale, non-obvious side effects).
+2. **Read and extract.** Read approved files. Extract: public API surface, described behaviour, visible constraints, hidden invariants. Note what the code does NOT explain (caller intent, error handling rationale, hidden side effects).
 
 3. **Gap check.** Present extracted behaviour to the user. Ask them to fill only the gaps — what the code does not explain. Log any explicitly deferred gaps. If the user requests to skip this step, log the reason and proceed.
 
diff --git a/plugins/git/skills/git-branches/SKILL.md b/plugins/git/skills/git-branches/SKILL.md
index cef3f0c..ade4c06 100644
--- a/plugins/git/skills/git-branches/SKILL.md
+++ b/plugins/git/skills/git-branches/SKILL.md
@@ -48,7 +48,7 @@ Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Git
 ## Workflow
 
 - [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow.
-- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
+- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (typically `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
 - [ ] **Track remote:** If pushing, always use `git push -u origin <branch>` to establish tracking.
 - [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively.
 - [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations.
diff --git a/plugins/git/skills/pc-author/SKILL.md b/plugins/git/skills/pc-author/SKILL.md
index 3bcad4a..4449da2 100644
--- a/plugins/git/skills/pc-author/SKILL.md
+++ b/plugins/git/skills/pc-author/SKILL.md
@@ -66,7 +66,7 @@ Read `.pre-commit-config.yaml` first. Note any stale `rev` values (see **Rev sta
 1. Identify the hook entry and its repo block.
 2. State what will be removed: hook ID, and whether the parent repo block will also be deleted (if it would have zero hooks remaining). Wait for confirmation.
 3. Remove the hook entry. If the repo block now has zero hooks remaining, remove the entire repo block.
-4. Write. Run `pre-commit validate-config`. If non-zero: revert the edit, show the error, and stop — do not leave a broken config (removal edits are not safely auto-fixable, unlike a bad new hook block, which can usually be corrected in place).
+4. Write. Run `pre-commit validate-config`. If non-zero: revert the edit, show the error, and stop — do not leave a broken config (removal edits are not safely auto-fixable, unlike a bad new hook block, which can often be corrected in place).
 
 ### Configuring top-level keys
 
diff --git a/plugins/gitea/skills/gitea-issues/SKILL.md b/plugins/gitea/skills/gitea-issues/SKILL.md
index 7dfaab5..93acc02 100644
--- a/plugins/gitea/skills/gitea-issues/SKILL.md
+++ b/plugins/gitea/skills/gitea-issues/SKILL.md
@@ -31,7 +31,7 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i
 
 ## Gotchas
 
-- **`list_issues` has no `type` or `milestones` parameter — despite `api-reference.md` documenting both.** The live MCP schema (re-verified via `ToolSearch` at authoring time — see `references/sources.md`) only accepts `owner`, `repo` (required), `state` (default `"all"`), `labels` (array of label *names*), `since`, `before` (ISO 8601), `page`, `per_page` (default 30). There is no way to filter issues-vs-PRs or by milestone through this tool. Since issues and PRs share one number space, `list_issues` results can include PR entries with no client-side filter to exclude them. If you need to know whether a specific number is a PR, call `issue_read method: "get"` and check `is_pull` — that field only appears on the single-item response, never in a list item. This exact drift (a prior skill trusted the research doc's `type` param and broke) is why this skill's reference files were re-verified live rather than copied from `api-reference.md`.
+- **`list_issues` has no `type` or `milestones` parameter — despite `api-reference.md` documenting both.** The live MCP schema (re-verified via `ToolSearch` at authoring time — see `references/sources.md`) only accepts `owner`, `repo` (required), `state` (default `"all"`), `labels` (array of label *names*), `since`, `before` (ISO 8601), `page`, `per_page` (default 30). This tool provides no way to filter issues-vs-PRs or by milestone. Since issues and PRs share one number space, `list_issues` results can include PR entries with no client-side filter to exclude them. If you need to know whether a specific number is a PR, call `issue_read method: "get"` and check `is_pull` — that field only appears on the single-item response, never in a list item. This exact drift (a prior skill trusted the research doc's `type` param and broke) is why this skill's reference files were re-verified live rather than copied from `api-reference.md`.
 - **`search_issues` does have a working `type` filter** (`"issues"` | `"pulls"`) — unlike `list_issues`. Its `labels` parameter is also shaped differently: a comma-separated string, not an array of names.
 - **Labels are numeric IDs on write, name strings on read.** `issue_write`'s `labels` parameter (used by `add_labels`/`replace_labels`) takes IDs. `list_issues`/`issue_read` return names. Never resolve this yourself — compose `gitea-labels-milestones` (see `references/enrichments.md`) to get IDs.
 - **Milestone on `issue_read` is `{id, title}`** — an object, not a bare string. This skill only ever needs the `id`. (The bare-title-string case only happens on the PR side, which is `gitea-prs`' problem, not this skill's.)
@@ -72,7 +72,7 @@ Call `list_issues owner: <owner> repo: <repo> state: <"open"|"closed"|"all", def
 ### create
 
 1. Extract `title` and `body` from conversation context (the most recent task, bug description, or explicit statement). Fall back to an empty body if nothing is available.
-2. Run the enrichment sequence in `references/enrichments.md`: infer labels (composing `gitea-labels-milestones`), check for a clearly-fitting open milestone (composing the same skill), and check for a configured default assignee.
+2. Run the enrichment sequence in `references/enrichments.md`: infer labels (composing `gitea-labels-milestones`), check for a well-matched open milestone (composing the same skill), and check for a configured default assignee.
 3. Call `issue_write method: "create" owner: <owner> repo: <repo> title: <title> body: <body> labels: [<resolved IDs, or omit>] milestone: <resolved ID, or omit> assignees: [<default login, or omit>]`.
 4. Fire immediately — no confirmation step for the create itself.
 
@@ -86,7 +86,7 @@ Call `issue_read method: "get_comments" owner: <owner> repo: <repo> issue_number
 
 ### close `<N>`
 
-Call `issue_write method: "update" owner: <owner> repo: <repo> issue_number: <N> state: "closed"`. There is no `method: "close"`.
+Call `issue_write method: "update" owner: <owner> repo: <repo> issue_number: <N> state: "closed"`. No `method: "close"` exists.
 
 ### comment `<N>`
 
diff --git a/plugins/gitea/skills/gitea-prs/SKILL.md b/plugins/gitea/skills/gitea-prs/SKILL.md
index ee2c449..c0c2545 100644
--- a/plugins/gitea/skills/gitea-prs/SKILL.md
+++ b/plugins/gitea/skills/gitea-prs/SKILL.md
@@ -29,7 +29,7 @@ allowed-tools: mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp_
 
 - **Issues and PRs share one number space.** A number the user mentions (`#42`) might be an issue, not a PR — there is only one counter per repo. If you're not certain, call `pull_request_read method: "get"` and treat a 404 as "this number is an issue, not a PR" (or check `is_pull` on an `issue_read` response first if you already have one).
 - **`pull_request_read method: "get"` returns `review_scomments`, not `review_comments`.** Source-level typo in gitea-mcp v1.3.0. Never reference `review_comments` — it will always be undefined.
-- **`draft: true` on create prepends `"WIP:"` to the title.** There is no first-class draft field — Gitea implements draft PRs via title prefix. To un-draft, call `update` and pass the title without the `WIP:` prefix.
+- **`draft: true` on create prepends `"WIP:"` to the title.** Gitea has no first-class draft field — it implements draft PRs via title prefix. To un-draft, call `update` and pass the title without the `WIP:` prefix.
 - **Cross-repo fork PRs require `head` as `"fork-owner:branch-name"`.** A bare branch name causes Gitea to search the base repo for it and return 422. Same-repo PRs use a bare branch name.
 - **PR `milestone` is a bare title string, not `{id, title}`.** Unlike issues, you cannot recover a milestone's ID from a PR response. If you need the ID (e.g. to filter or to pass to another write), call into `gitea-labels-milestones` and match by title via `milestone_read method: "list"`.
 - **CI status and review/approval state are independent merge gates.** `get_status` only reports CI. Branch-protection rules (required approvals, requested-reviewer coverage, stale-approval handling) are enforced server-side by the merge call itself and will error if unmet — passing CI does not mean the merge will succeed.
diff --git a/plugins/gitea/skills/gitea-releases/SKILL.md b/plugins/gitea/skills/gitea-releases/SKILL.md
index cee7096..7bcc8e9 100644
--- a/plugins/gitea/skills/gitea-releases/SKILL.md
+++ b/plugins/gitea/skills/gitea-releases/SKILL.md
@@ -22,7 +22,7 @@ metadata:
 
 - **`delete_release` takes a numeric `id`, never a tag name.** `delete_tag` is the mirror opposite — it takes the `tag_name` string, never a numeric id. These two tools are asymmetric on purpose; passing a tag name to `delete_release` or a numeric id to `delete_tag` fails. Always resolve the numeric release id via `list_releases` or `get_release` first if you only have a tag name in hand.
 - **Deleting a release does not delete its tag.** They are separate destructive operations against separate resources — a release is a wrapper (title, notes, draft/prerelease flags, assets) around a tag, not the tag itself. If the intent is to remove both, call `delete_release` and `delete_tag` separately.
-- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. There is no auto-pagination in the MCP layer — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results.
+- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. The MCP layer does no auto-pagination — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results.
 - **`is_draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** Note the input param is `is_draft`, which maps to the `draft` field on the *response* object (see Dispatch table below and `references/call-signatures.md`) — `draft` is never a valid input key. Practitioner convention (per the `tea` CLI) uses `-beta`/`-rc` suffixes for prereleases (e.g. `v2.0.0-beta.1`), but Gitea does not enforce or infer this from the tag string. If the user names a tag that looks like a prerelease, set `is_pre_release: true` explicitly rather than assuming the flag is redundant with the name.
 - **Tag names are conventionally semver, `v`-prefixed** (`v1.2.0`, `v2.0.0-beta.1`), but this is a practitioner convention, not a Gitea constraint — don't reject or rewrite a caller-supplied tag name that doesn't follow it.
 
@@ -47,6 +47,6 @@ metadata:
 - [ ] **Creating a release:** Call `create_release` directly with `tag_name` + `target` + `title` — Gitea is assumed to create the underlying tag automatically if `tag_name` doesn't already exist (this is plausible behavior inferred from the API shape, not directly confirmed in the research docs), so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. Verify the tag exists afterward if this matters to the caller. Set `is_pre_release`/`is_draft` explicitly per the Gotchas above; don't leave them to default inference.
 - [ ] **Deleting a release safely:** Resolve the numeric id first — call `list_releases` (paginate if needed, see Gotchas) or `get_release` if the id is already known, find the entry matching the target `tag_name`, then call `delete_release` with that `id`. Never pass `tag_name` to `delete_release`.
 - [ ] **Deleting a tag along with its release:** Delete the release first (frees the id lookup), then call `delete_tag` with the `tag_name` separately — confirm both are intended before proceeding, since each is an independent irreversible operation.
-- [ ] **Listing completely:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries.
+- [ ] **Listing every page:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries.
 
 If exact response field shapes or additional conventions are needed, read `references/call-signatures.md` and `references/conventions.md`.
diff --git a/plugins/gitea/skills/gitea-workflow/SKILL.md b/plugins/gitea/skills/gitea-workflow/SKILL.md
index 92b7a6e..c374fd1 100644
--- a/plugins/gitea/skills/gitea-workflow/SKILL.md
+++ b/plugins/gitea/skills/gitea-workflow/SKILL.md
@@ -56,7 +56,7 @@ Never dispatch to `gitea-issues` or `gitea-prs` based on guessing from phrasing
 
 ## Step 3 — Route explicit but domain-unclear requests
 
-For requests that name a capability but not obviously which skill owns it, use this index:
+For requests that name a capability without a clear owning skill, use this index:
 
 | Skill | Covers |
 |---|---|
@@ -67,7 +67,7 @@ For requests that name a capability but not obviously which skill owns it, use t
 | `gitea-files` | Read/write/delete individual files, list a directory, walk the full repo tree. |
 | `gitea-releases` | Release and tag CRUD — draft/prerelease flags, release notes, semver tags. |
 
-If a request clearly names one of these (e.g. "create a milestone" → `gitea-labels-milestones`, "read this file from the repo" → `gitea-files`), invoke that skill directly rather than routing through here. Use this table only when the user or an upstream agent is unsure which skill applies.
+If a request unambiguously names one of these (e.g. "create a milestone" → `gitea-labels-milestones`, "read this file from the repo" → `gitea-files`), invoke that skill directly rather than routing through here. Use this table only when the user or an upstream agent is unsure which skill applies.
 
 ## Step 4 — Report
 
diff --git a/plugins/kyberforge/skills/agent-author/SKILL.md b/plugins/kyberforge/skills/agent-author/SKILL.md
index 936e6b7..96045f1 100644
--- a/plugins/kyberforge/skills/agent-author/SKILL.md
+++ b/plugins/kyberforge/skills/agent-author/SKILL.md
@@ -123,7 +123,7 @@ source_keys:
 
 ### Step 3 — Fill in the Copilot agent file
 
-There are **two distinct Copilot agent formats** with different paths and field sets. Choose one based on the deployment target:
+**Two distinct Copilot agent formats** exist, with different paths and field sets. Choose one based on the deployment target:
 
 **CLI format** (default — what the scaffold creates):
 - Path: `.github/agents/<name>.agent.md` (project) or `<plugin>/agents/<name>.agent.md` (plugin)
diff --git a/plugins/kyberforge/skills/forge/SKILL.md b/plugins/kyberforge/skills/forge/SKILL.md
index ea2ea5b..2b7e50b 100644
--- a/plugins/kyberforge/skills/forge/SKILL.md
+++ b/plugins/kyberforge/skills/forge/SKILL.md
@@ -32,7 +32,7 @@ This step always runs inline, in the current conversation — grilling is intera
 
 ## Step 2 — Classify the artifact type
 
-Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans several):
+Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans multiple):
 
 | Intent                                                                                                                                                                                                                               | Artifact type               | Route to                        |
 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -----------------------------| ---------------------------------|
diff --git a/plugins/kyberforge/skills/marketplace-author/SKILL.md b/plugins/kyberforge/skills/marketplace-author/SKILL.md
index 6fae3d8..a9692a0 100644
--- a/plugins/kyberforge/skills/marketplace-author/SKILL.md
+++ b/plugins/kyberforge/skills/marketplace-author/SKILL.md
@@ -182,7 +182,7 @@ Read `.claude-plugin/marketplace.json`. Identify the entry to remove. State the
 
 ### Step 2 — HITL gate
 
-State clearly before proceeding:
+State the following before proceeding:
 
 > "I will remove the `<name>` entry from both `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json`. This does not delete the plugin files. Confirm?"
 
diff --git a/plugins/kyberforge/skills/skill-author/SKILL.md b/plugins/kyberforge/skills/skill-author/SKILL.md
index 35911d0..3b84d36 100644
--- a/plugins/kyberforge/skills/skill-author/SKILL.md
+++ b/plugins/kyberforge/skills/skill-author/SKILL.md
@@ -114,7 +114,7 @@ Rename the placeholder section heading to one that fits the skill's structure 
 Ask of every sentence: "Would the agent get this wrong without it?" Cut anything that answers "no."
 
 **Include:**
-- Non-obvious sequences or ordering constraints — the agent may skip or reorder steps without this
+- Sequences or ordering constraints that aren't self-evident — the agent may skip or reorder steps without this
 - Domain conventions the agent cannot infer from general knowledge — this is the core value a skill adds
 - One default per decision point, plus one escape hatch — never a menu; menus cause the agent to pause or pick arbitrarily
 - Gotchas — facts that defy reasonable assumptions; the agent will get these wrong every time without them
diff --git a/scripts/skill-size-check.sh b/scripts/skill-size-check.sh
new file mode 100755
index 0000000..8d92692
--- /dev/null
+++ b/scripts/skill-size-check.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Enforces agentskills.io's skill-authoring.md guidance: keep SKILL.md under 500
+# lines and 5,000 tokens, so the full body doesn't crowd out conversation
+# history and other active skills once loaded into context. Vale can't express
+# a whole-file length ceiling (its checks operate on text patterns, not raw
+# file size), so this is a plain script instead of a Vale rule.
+#
+# Token counts aren't computed exactly here — word count (`wc -w`) is used as
+# a proxy. For English prose this typically runs somewhat below true BPE token
+# counts, so a 5,000-word file is already at or past 5,000 tokens in practice;
+# treat this as a conservative, cheap approximation, not an exact measure.
+
+MAX_LINES=500
+MAX_WORDS=5000
+FAIL=0
+
+for f in "$@"; do
+  [[ -f "$f" ]] || continue
+
+  lines=$(wc -l < "$f")
+  if (( lines > MAX_LINES )); then
+    echo "ERROR: $f has $lines lines, exceeding the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2
+    FAIL=1
+  fi
+
+  words=$(wc -w < "$f")
+  if (( words > MAX_WORDS )); then
+    echo "ERROR: $f has $words words (proxy for tokens), exceeding the $MAX_WORDS-token ceiling (agentskills.io skill-authoring.md)" >&2
+    FAIL=1
+  fi
+done
+
+exit $FAIL
diff --git a/styles/Kyberforge/SentenceOpenerThereIs.yml b/styles/Kyberforge/SentenceOpenerThereIs.yml
new file mode 100644
index 0000000..b636ada
--- /dev/null
+++ b/styles/Kyberforge/SentenceOpenerThereIs.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Don't start a sentence with '%s' — name the subject directly"
+level: warning
+scope: text
+ignorecase: false
+raw:
+  - '(?:[;-]\s)There\s(is|are)|\bThere\s(is|are)\b'
diff --git a/styles/Kyberforge/VagueQualifier.yml b/styles/Kyberforge/VagueQualifier.yml
new file mode 100644
index 0000000..2de0ab4
--- /dev/null
+++ b/styles/Kyberforge/VagueQualifier.yml
@@ -0,0 +1,36 @@
+extends: existence
+message: "'%s' is vague filler wording — state the point precisely instead"
+level: warning
+scope: text
+ignorecase: true
+tokens:
+  - clearly
+  - obviously
+  - obvious
+  - simply
+  - simple
+  - easily
+  - easy
+  - of course
+  - everyone knows
+  - completely
+  - exceedingly
+  - excellent
+  - extremely
+  - fairly
+  - huge
+  - interestingly
+  - largely
+  - mostly
+  - quite
+  - relatively
+  - remarkably
+  - several
+  - significantly
+  - substantially
+  - surprisingly
+  - tiny
+  - usually
+  - various
+  - vast
+  - very
diff --git a/tests/test-skill-size-check.sh b/tests/test-skill-size-check.sh
new file mode 100755
index 0000000..f43de7e
--- /dev/null
+++ b/tests/test-skill-size-check.sh
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Regression test for scripts/skill-size-check.sh: enforces agentskills.io's
+# 500-line/5,000-word(proxy-for-token) SKILL.md size ceiling.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="$REPO_ROOT/scripts/skill-size-check.sh"
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+make_fixture() {
+  local name="$1" lines="$2" words_per_line="$3" file
+  file="$TMPDIR/$name.md"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: Test fixture."
+    echo "---"
+    for ((i = 1; i <= lines; i++)); do
+      w=""
+      for ((j = 1; j <= words_per_line; j++)); do
+        w="$w word"
+      done
+      echo "$w"
+    done
+  } > "$file"
+  echo "$file"
+}
+
+echo ""
+echo "--- passes a file under both limits ---"
+SMALL="$(make_fixture small 10 5)"
+if "$SCRIPT" "$SMALL"; then
+  pass "file under both limits exits 0"
+else
+  fail "file under both limits should have exited 0"
+fi
+
+echo ""
+echo "--- fails a file over the line limit ---"
+MANY_LINES="$(make_fixture many-lines 600 1)"
+if "$SCRIPT" "$MANY_LINES" 2>/dev/null; then
+  fail "file over the 500-line ceiling should have exited non-zero"
+else
+  pass "file over the 500-line ceiling exits non-zero"
+fi
+
+echo ""
+echo "--- fails a file over the word-count limit ---"
+MANY_WORDS="$(make_fixture many-words 10 600)"
+if "$SCRIPT" "$MANY_WORDS" 2>/dev/null; then
+  fail "file over the 5,000-word ceiling should have exited non-zero"
+else
+  pass "file over the 5,000-word ceiling exits non-zero"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]
-- 
2.43.0


From 792d3e18524fce480b1ce538880c42c078f55751 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sat, 8 Aug 2026 19:24:40 +0000
Subject: [PATCH 12/45] fix(lint): resolve round-1 and round-2 review findings
 on the Vale prefilter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses PR #85's outstanding review items after grilling the open
questions against ADR-0013/CONTEXT.md/ADR-0010:

Blocking fixes:
- vale-wrap.sh: replace json.dumps() escaping (which silently defeated
  Vale's frontmatter scope on any description containing a quote,
  backslash, or non-ASCII char — ~58% of the corpus) with a single-quoted
  YAML scalar, substituting a Unicode right single quote for embedded
  apostrophes rather than '' doubling (Vale's frontmatter scanner isn't a
  full YAML parser and silently truncates on '' too).
- vale-wrap.sh: fix a blank-line-inside-a-folded-description truncation
  bug via indentation-based, blank-line-tolerant body capture; narrow
  flattening to `>`-style scalars only (`|` already works unflattened).
- skill-audit/agent-audit Step 1: make the vale-wrap.sh invocation
  cwd-independent via git rev-parse --show-toplevel, fixing a bug where
  no single cwd satisfied all three Step 1 commands.
- styles/Kyberforge/VagueQualifier.yml: prune 17 tokens verified
  false-positive-dominated on this repo's own voice via a real corpus
  sweep (obvious, clearly, usually, several, simple, easy, completely,
  simply, tiny, etc.), keep 13 with real or unattested noise. Revert the
  28 prose "fixes" those tokens drove across 14 skill files back to their
  original, correct wording, including a functional regression to
  caveman/SKILL.md's own filler-word list (a mention, not a use) — now
  guarded with vale-off comments against recurrence.

Gaps:
- --minAlertLevel=warning on the pre-commit hook and Step 1 invocation
  so warning-level rules actually surface, without collapsing the
  FAIL/SUGGESTION severity mapping skill-audit/agent-audit rely on.
- vale-wrap.sh: fix --config=<path> equals-form, absolute-path silent
  no-op, and a zero-file-argument stdin hang.
- Route vale-run and lint-runner through a documented wrapper script
  when a target repo has one, instead of unconditionally recommending
  bare `vale`.
- Wire Kyberforge.VagueQualifier/SentenceOpenerThereIs into skill-audit/
  agent-audit's dimension-mapping prose (Body discipline).
- Add plugins/lint/sources.md provenance for lint-runner (ADR-0010).
- Sync both marketplace.json lint-entry descriptions with plugin.json.
- Retune skill-size-check.sh's MAX_WORDS 5000->2900 (measured ~1.6-1.7
  tokens/word on this repo's corpus, the old value gated at ~8,500
  tokens against a stated 5,000 ceiling); fix the >/>= line-count
  boundary and wc -l undercount on files with no trailing newline.
- Document the vale binary as a Setup prerequisite in AGENTS.md.
- Fix SentenceOpenerThereIs's dead regex alternative and add a real
  sentence-start anchor/scope.
- Fix a stale docs/research/docs/vale/ index pointer in kyberforge's
  docs README (moved to plugins/lint/ in e1a5403).
- Rewrite ADR-0013's Consequences section past-tense to describe what
  actually landed, and record the styles-portability limitation
  (repo-root placement stays intentional; deferred to a separate
  session per this PR's review).

Test coverage: 9 new vale-wrap.sh fixtures (quotes, backslash/unicode,
blank-line paragraphs, --config= form, zero-arg/absolute-path handling,
literal-block no-regression) and boundary-pair tests for
skill-size-check.sh's line/word ceilings.

bash tests/run-tests.sh: 9 scripts + 125 bats assertions, all passing.
scripts/check-manifests.sh and claude plugin validate --strict: clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 .claude-plugin/marketplace.json               |   4 +-
 .github/plugin/marketplace.json               |   4 +-
 .pre-commit-config.yaml                       |   2 +-
 AGENTS.md                                     |   1 +
 CONTEXT.md                                    |   4 +-
 ...013-vale-harness-scope-and-rule-sources.md |  27 ++-
 plugins/bin/skills/caveman/SKILL.md           |   7 +-
 plugins/bin/skills/diagnose/SKILL.md          |   4 +-
 .../improve-codebase-architecture/SKILL.md    |   2 +-
 plugins/bin/skills/prototype/SKILL.md         |   8 +-
 plugins/bin/skills/tdd/SKILL.md               |   2 +-
 plugins/bin/skills/write-docs/SKILL.md        |   2 +-
 plugins/git/skills/git-branches/SKILL.md      |   2 +-
 plugins/git/skills/pc-author/SKILL.md         |   2 +-
 plugins/gitea/skills/gitea-issues/SKILL.md    |   2 +-
 plugins/gitea/skills/gitea-workflow/SKILL.md  |   4 +-
 plugins/kyberforge/docs/README.md             |   1 -
 .../kyberforge/skills/agent-audit/SKILL.md    |   5 +-
 plugins/kyberforge/skills/forge/SKILL.md      |   2 +-
 .../skills/marketplace-author/SKILL.md        |   2 +-
 .../kyberforge/skills/skill-audit/SKILL.md    |   6 +-
 .../kyberforge/skills/skill-author/SKILL.md   |   2 +-
 plugins/lint/.claude-plugin/plugin.json       |   2 +-
 plugins/lint/agents/lint-runner.agent.md      |   3 +
 plugins/lint/agents/lint-runner.md            |   3 +
 plugins/lint/plugin.json                      |   2 +-
 plugins/lint/skills/vale-run/SKILL.md         |   5 +-
 .../vale-run/references/troubleshooting.md    |  10 +
 plugins/lint/sources.md                       |   9 +
 scripts/skill-size-check.sh                   |  24 ++-
 scripts/vale-wrap.sh                          |  71 ++++--
 styles/Kyberforge/SentenceOpenerThereIs.yml   |   4 +-
 styles/Kyberforge/VagueQualifier.yml          |  19 +-
 tests/test-skill-size-check.sh                |  96 +++++++++
 tests/test-vale-wrap.sh                       | 204 ++++++++++++++++++
 35 files changed, 462 insertions(+), 85 deletions(-)
 create mode 100644 plugins/lint/sources.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d4877ff..6ed72bf 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -40,10 +40,10 @@
       }
     },
     {
-      "description": "Skills and agents for configuring and running linters, starting with Vale.",
+      "description": "Skills and agents for configuring and running linters.",
       "name": "lint",
       "source": "./plugins/lint"
     }
   ],
-  "version": "0.3.0"
+  "version": "0.3.1"
 }
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index d4877ff..6ed72bf 100644
--- a/.github/plugin/marketplace.json
+++ b/.github/plugin/marketplace.json
@@ -40,10 +40,10 @@
       }
     },
     {
-      "description": "Skills and agents for configuring and running linters, starting with Vale.",
+      "description": "Skills and agents for configuring and running linters.",
       "name": "lint",
       "source": "./plugins/lint"
     }
   ],
-  "version": "0.3.0"
+  "version": "0.3.1"
 }
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index ad1a9d6..ed9a129 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -111,7 +111,7 @@ repos:
         stages: ['pre-commit']
         name: Vale audit prefilter
         description: Run Vale against skill/agent markdown files as a deterministic prefilter for skill-audit/agent-audit
-        entry: scripts/vale-wrap.sh --config .vale.ini
+        entry: scripts/vale-wrap.sh --config .vale.ini --minAlertLevel=warning
         language: script
         files: '^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$'
         pass_filenames: true
diff --git a/AGENTS.md b/AGENTS.md
index 905626e..5781986 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,6 +22,7 @@ Fall back to raw shell only when no skill covers it.
 ## Setup and testing
 
 - Install git hooks via `git:pc-run`, wiring all three stages — this repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (tests, manifest check).
+- Install the `vale` binary — required by the `vale-audit-prefilter` pre-commit hook, which runs on every commit touching a `SKILL.md` or agent `.md` file. Without it the hook fails with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `styles/`, not downloaded packages.
 - Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed.
 - Pushing re-runs the full suite plus `scripts/check-manifests.sh` via the pre-push hook — same commands, so run them locally first.
 - Author commits with `git:git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you.
diff --git a/CONTEXT.md b/CONTEXT.md
index 5b2e90b..142f18b 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -70,11 +70,11 @@ A companion skill (`core` plugin) that detects a target repo's provider-specific
 A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
 
 ### Vale audit prefilter (skill-audit / agent-audit)
-Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. `error` alerts map to FAIL, `warning`/`suggestion` map to SUGGESTION. Vale only replaces the specific pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) — body discipline, near-miss exclusion strength, and control calibration stay LLM judgment per the issue's explicit non-goals.
+Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. `error` alerts map to FAIL, `warning`/`suggestion` map to SUGGESTION. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, two body-wide prose-pattern checks (vague-qualifier filler, "There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
 
 Both skills' Step 1, and the `vale-audit-prefilter` pre-commit hook, call `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched. `tests/test-vale-wrap.sh` regression-tests this. Both call sites still scope every invocation to the specific file(s) being audited, never a repo-wide sweep — Vale's glob matching crosses directory boundaries (`plugins/*/agents/*.md` matches nested `docs/research/examples/**/agents/*.md` too), so scoping is what keeps research-example files out of the audit's lint pass. The pre-commit hook's own glob is tightened to `^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$` (single-segment, not `.*`) for the same reason, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target.
 
-This scope expands per ADR-0013: cherry-picked low-noise `write-good`/`alex` rules into `styles/Kyberforge` (still pending implementation) plus a new sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing `skill-authoring.md`'s 500-line/5,000-token `SKILL.md` ceiling — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter`, so it never lints `docs/research/examples/` reference skills. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine).
+This scope expands per ADR-0013: cherry-picked low-noise `write-good`/`alex` rules landed in `styles/Kyberforge` as two new rule files, `Kyberforge.VagueQualifier` and `Kyberforge.SentenceOpenerThereIs`, plus a new sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter`, so it never lints `docs/research/examples/` reference skills. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine).
 
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/docs/adr/0013-vale-harness-scope-and-rule-sources.md b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
index c867ab5..3ed267e 100644
--- a/docs/adr/0013-vale-harness-scope-and-rule-sources.md
+++ b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
@@ -72,13 +72,22 @@ standing report-only tier for future candidate rules.
 
 ## Consequences
 
-- `styles/Kyberforge/` will gain new rule files once the (separate, later) implementation pass
-  finalizes the exact cherry-picked `write-good`/`alex` rules and any new wording — none are named
-  by this ADR, since none have been chosen yet.
-- A new pre-commit hook (name TBD by the implementer) enforces the 500-line/5,000-token `SKILL.md`
-  ceiling, sibling to `skill-frontmatter`.
-- `styles/KyberforgeTrial/` and `.vale.trial.ini` are deliberately not created — noted here so a
+- `styles/Kyberforge/` gained two new rule files, cherry-picked from `write-good`/`alex` as
+  low-noise against this repo's corpus: `VagueQualifier.yml` and `SentenceOpenerThereIs.yml`.
+- A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
+  500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`.
+- `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
   future reader doesn't wonder if a trial tier was forgotten.
-- Follow-up work — not part of this ADR — is: syncing and trialing `write-good`/`alex`, cherry-picking
-  low-noise rules, writing the size-ceiling script and hook, fixing existing corpus violations, and
-  the atomic commit landing all of it.
+- The styles-portability question — whether `styles/` and `.vale.ini` should move into
+  `plugins/lint/` so the prefilter also works for repos that install `kyberforge@holocron` as an
+  external plugin, rather than living at this repo's root — was deliberately deferred, not fixed,
+  in this pass. This repo-root placement remains intentional: this ADR's "File scope stays the
+  same" framing is specific to Kyberforge's own authoring conventions in this repo, not a generic
+  `lint`-plugin feature. Portability is a known limitation, tracked for a separate future session,
+  not silently forgotten.
+
+**What this ADR's implementation pass did:** synced and trialed `write-good`/`alex` against the
+existing SKILL.md/agent-file corpus, cherry-picked the two low-noise rules above into
+`styles/Kyberforge`, wrote `scripts/skill-size-check.sh` and its pre-commit hook, fixed the
+resulting corpus violations, and landed the rule changes and corpus fixes as one atomic commit —
+matching the enforcement model described above (no partial or opt-in state).
diff --git a/plugins/bin/skills/caveman/SKILL.md b/plugins/bin/skills/caveman/SKILL.md
index 632e132..72bcd66 100644
--- a/plugins/bin/skills/caveman/SKILL.md
+++ b/plugins/bin/skills/caveman/SKILL.md
@@ -15,7 +15,12 @@ ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drif
 
 ## Rules
 
-Drop: articles (a/an/the), filler (just/really/basically/actually/literally), pleasantries (sure/certainly/no worries/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+<!-- vale Kyberforge.VagueQualifier = NO -->
+<!-- vale Kyberforge.VagueWording = NO -->
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging.
+<!-- vale Kyberforge.VagueQualifier = YES -->
+<!-- vale Kyberforge.VagueWording = YES -->
+Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
 
 Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
 
diff --git a/plugins/bin/skills/diagnose/SKILL.md b/plugins/bin/skills/diagnose/SKILL.md
index 9f444d5..ed55bda 100644
--- a/plugins/bin/skills/diagnose/SKILL.md
+++ b/plugins/bin/skills/diagnose/SKILL.md
@@ -86,7 +86,7 @@ Tool preference:
 
 **Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
 
-**Perf branch.** For performance regressions, logs rarely reveal the cause. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
 
 ## Phase 5 — Fix + regression test
 
@@ -111,7 +111,7 @@ Required before declaring done:
 - [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
 - [ ] Regression test passes (or absence of seam is documented)
 - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to an explicitly-marked debug location)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
 - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
 
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
diff --git a/plugins/bin/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/skills/improve-codebase-architecture/SKILL.md
index 71cee67..05984a6 100644
--- a/plugins/bin/skills/improve-codebase-architecture/SKILL.md
+++ b/plugins/bin/skills/improve-codebase-architecture/SKILL.md
@@ -55,7 +55,7 @@ Present a numbered list of deepening opportunities. For each candidate:
 
 **Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
 
-**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Flag it explicitly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
 
 Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
 
diff --git a/plugins/bin/skills/prototype/SKILL.md b/plugins/bin/skills/prototype/SKILL.md
index 664ec88..84478e0 100644
--- a/plugins/bin/skills/prototype/SKILL.md
+++ b/plugins/bin/skills/prototype/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: prototype
-description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or multiple radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
+description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
 ---
 
 # Prototype
@@ -11,14 +11,14 @@ A prototype is **throwaway code that answers a question**. The question decides
 
 Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
 
-- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a minimal interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
-- **"What should this look like?"** → [UI.md](UI.md). Generate multiple radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
 
 The two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
 
 ## Rules that apply to both
 
-1. **Throwaway from day one, and labeled as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so the context is unambiguous — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
 2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is *checking*, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
 4. **Skip the polish.** No tests, no error handling beyond what makes the prototype *runnable*, no abstractions. The point is to learn something fast and then delete it.
diff --git a/plugins/bin/skills/tdd/SKILL.md b/plugins/bin/skills/tdd/SKILL.md
index cdd0dad..7a98941 100644
--- a/plugins/bin/skills/tdd/SKILL.md
+++ b/plugins/bin/skills/tdd/SKILL.md
@@ -91,7 +91,7 @@ Rules:
 After all tests pass, look for [refactor candidates](refactoring.md):
 
 - [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind narrow interfaces)
+- [ ] Deepen modules (move complexity behind simple interfaces)
 - [ ] Apply SOLID principles where natural
 - [ ] Consider what new code reveals about existing code
 - [ ] Run tests after each refactor step
diff --git a/plugins/bin/skills/write-docs/SKILL.md b/plugins/bin/skills/write-docs/SKILL.md
index 1d6ccb2..0d2da2d 100644
--- a/plugins/bin/skills/write-docs/SKILL.md
+++ b/plugins/bin/skills/write-docs/SKILL.md
@@ -61,7 +61,7 @@ You are a technical writer that produces documentation by reading code and spec
 
 1. **Identify scope.** User names specific files or sections. If not provided, propose candidates based on the description — wait for explicit approval before reading.
 
-2. **Read and extract.** Read approved files. Extract: public API surface, described behaviour, visible constraints, hidden invariants. Note what the code does NOT explain (caller intent, error handling rationale, hidden side effects).
+2. **Read and extract.** Read approved files. Extract: public API surface, described behaviour, visible constraints, non-obvious invariants. Note what the code does NOT explain (caller intent, error handling rationale, non-obvious side effects).
 
 3. **Gap check.** Present extracted behaviour to the user. Ask them to fill only the gaps — what the code does not explain. Log any explicitly deferred gaps. If the user requests to skip this step, log the reason and proceed.
 
diff --git a/plugins/git/skills/git-branches/SKILL.md b/plugins/git/skills/git-branches/SKILL.md
index ade4c06..cef3f0c 100644
--- a/plugins/git/skills/git-branches/SKILL.md
+++ b/plugins/git/skills/git-branches/SKILL.md
@@ -48,7 +48,7 @@ Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Git
 ## Workflow
 
 - [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow.
-- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (typically `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
+- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
 - [ ] **Track remote:** If pushing, always use `git push -u origin <branch>` to establish tracking.
 - [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively.
 - [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations.
diff --git a/plugins/git/skills/pc-author/SKILL.md b/plugins/git/skills/pc-author/SKILL.md
index 4449da2..3bcad4a 100644
--- a/plugins/git/skills/pc-author/SKILL.md
+++ b/plugins/git/skills/pc-author/SKILL.md
@@ -66,7 +66,7 @@ Read `.pre-commit-config.yaml` first. Note any stale `rev` values (see **Rev sta
 1. Identify the hook entry and its repo block.
 2. State what will be removed: hook ID, and whether the parent repo block will also be deleted (if it would have zero hooks remaining). Wait for confirmation.
 3. Remove the hook entry. If the repo block now has zero hooks remaining, remove the entire repo block.
-4. Write. Run `pre-commit validate-config`. If non-zero: revert the edit, show the error, and stop — do not leave a broken config (removal edits are not safely auto-fixable, unlike a bad new hook block, which can often be corrected in place).
+4. Write. Run `pre-commit validate-config`. If non-zero: revert the edit, show the error, and stop — do not leave a broken config (removal edits are not safely auto-fixable, unlike a bad new hook block, which can usually be corrected in place).
 
 ### Configuring top-level keys
 
diff --git a/plugins/gitea/skills/gitea-issues/SKILL.md b/plugins/gitea/skills/gitea-issues/SKILL.md
index 93acc02..8cfc6fe 100644
--- a/plugins/gitea/skills/gitea-issues/SKILL.md
+++ b/plugins/gitea/skills/gitea-issues/SKILL.md
@@ -72,7 +72,7 @@ Call `list_issues owner: <owner> repo: <repo> state: <"open"|"closed"|"all", def
 ### create
 
 1. Extract `title` and `body` from conversation context (the most recent task, bug description, or explicit statement). Fall back to an empty body if nothing is available.
-2. Run the enrichment sequence in `references/enrichments.md`: infer labels (composing `gitea-labels-milestones`), check for a well-matched open milestone (composing the same skill), and check for a configured default assignee.
+2. Run the enrichment sequence in `references/enrichments.md`: infer labels (composing `gitea-labels-milestones`), check for a clearly-fitting open milestone (composing the same skill), and check for a configured default assignee.
 3. Call `issue_write method: "create" owner: <owner> repo: <repo> title: <title> body: <body> labels: [<resolved IDs, or omit>] milestone: <resolved ID, or omit> assignees: [<default login, or omit>]`.
 4. Fire immediately — no confirmation step for the create itself.
 
diff --git a/plugins/gitea/skills/gitea-workflow/SKILL.md b/plugins/gitea/skills/gitea-workflow/SKILL.md
index c374fd1..92b7a6e 100644
--- a/plugins/gitea/skills/gitea-workflow/SKILL.md
+++ b/plugins/gitea/skills/gitea-workflow/SKILL.md
@@ -56,7 +56,7 @@ Never dispatch to `gitea-issues` or `gitea-prs` based on guessing from phrasing
 
 ## Step 3 — Route explicit but domain-unclear requests
 
-For requests that name a capability without a clear owning skill, use this index:
+For requests that name a capability but not obviously which skill owns it, use this index:
 
 | Skill | Covers |
 |---|---|
@@ -67,7 +67,7 @@ For requests that name a capability without a clear owning skill, use this index
 | `gitea-files` | Read/write/delete individual files, list a directory, walk the full repo tree. |
 | `gitea-releases` | Release and tag CRUD — draft/prerelease flags, release notes, semver tags. |
 
-If a request unambiguously names one of these (e.g. "create a milestone" → `gitea-labels-milestones`, "read this file from the repo" → `gitea-files`), invoke that skill directly rather than routing through here. Use this table only when the user or an upstream agent is unsure which skill applies.
+If a request clearly names one of these (e.g. "create a milestone" → `gitea-labels-milestones`, "read this file from the repo" → `gitea-files`), invoke that skill directly rather than routing through here. Use this table only when the user or an upstream agent is unsure which skill applies.
 
 ## Step 4 — Report
 
diff --git a/plugins/kyberforge/docs/README.md b/plugins/kyberforge/docs/README.md
index 8194741..1f646a4 100644
--- a/plugins/kyberforge/docs/README.md
+++ b/plugins/kyberforge/docs/README.md
@@ -17,5 +17,4 @@ Upstream reference material gathered during skill authoring. Not shipped with th
 |------|---------|
 | `research/docs/agentskillsio/` | agentskills.io spec, skill authoring, description optimization, eval design, scripts |
 | `research/docs/agentsmd/` | agents.md format spec and cross-tool configuration reference |
-| `research/docs/vale/` | Vale (vale.sh) prose linter — config, styles/rules/checks model, CLI reference, installation |
 | `research/examples/skill-write/` | Upstream skill examples reviewed when authoring skill-write and skill-audit |
diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md
index 6c5786b..e2e9714 100644
--- a/plugins/kyberforge/skills/agent-audit/SKILL.md
+++ b/plugins/kyberforge/skills/agent-audit/SKILL.md
@@ -36,12 +36,12 @@ metadata:
 ```bash
 bash scripts/validate.sh <path-to-agent-file>
 bash scripts/validate-provenance.sh <path-to-agent-file>
-scripts/vale-wrap.sh --config .vale.ini <path-to-cc-file> <path-to-copilot-file>
+"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini" <path-to-cc-file> <path-to-copilot-file>
 ```
 
 The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
-Run `vale-wrap.sh` from the repo root against both files of the pair (not just the one passed in), using `.vale.ini`. `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in the `### Description` / `### Body` dimensions, citing the rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable.
+`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`, so it runs correctly regardless of the caller's cwd. Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in the `### Description` / `### Body` dimensions, citing the rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable.
 
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
@@ -62,6 +62,7 @@ If a description finding is borderline, read `references/description-quality.md`
 - Direct role instruction: system prompt opens with `You are a [role]. When invoked, [action].` — SUGGESTION if absent
 - One job per agent: system prompt describes a single bounded task — SUGGESTION if scope appears unbounded
 - Generic, non-specific reference pointers to the `references/` directory: Vale's `Kyberforge.PaddingPhrase` alert flags this directly — report it without re-deriving by judgment
+- Vague filler wording and sentences that open with "There is"/"There are": Vale's `Kyberforge.VagueQualifier` and `Kyberforge.SentenceOpenerThereIs` alerts flag this directly — report them without re-deriving by judgment
 
 **Body/Frontmatter comments:**
 - Inspect each comment block in the YAML frontmatter. For each comment, apply: *"Would the agent get this wrong without this comment?"* Flag any that answer "no" as padding.
diff --git a/plugins/kyberforge/skills/forge/SKILL.md b/plugins/kyberforge/skills/forge/SKILL.md
index 2b7e50b..ea2ea5b 100644
--- a/plugins/kyberforge/skills/forge/SKILL.md
+++ b/plugins/kyberforge/skills/forge/SKILL.md
@@ -32,7 +32,7 @@ This step always runs inline, in the current conversation — grilling is intera
 
 ## Step 2 — Classify the artifact type
 
-Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans multiple):
+Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans several):
 
 | Intent                                                                                                                                                                                                                               | Artifact type               | Route to                        |
 | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -----------------------------| ---------------------------------|
diff --git a/plugins/kyberforge/skills/marketplace-author/SKILL.md b/plugins/kyberforge/skills/marketplace-author/SKILL.md
index a9692a0..6fae3d8 100644
--- a/plugins/kyberforge/skills/marketplace-author/SKILL.md
+++ b/plugins/kyberforge/skills/marketplace-author/SKILL.md
@@ -182,7 +182,7 @@ Read `.claude-plugin/marketplace.json`. Identify the entry to remove. State the
 
 ### Step 2 — HITL gate
 
-State the following before proceeding:
+State clearly before proceeding:
 
 > "I will remove the `<name>` entry from both `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json`. This does not delete the plugin files. Confirm?"
 
diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index 18c2084..3c82a51 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -34,14 +34,14 @@ metadata:
 ```bash
 bash scripts/validate.sh <skill-dir>
 bash scripts/validate-provenance.sh <skill-dir>
-scripts/vale-wrap.sh --config .vale.ini <skill-dir>/SKILL.md
+"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini" <skill-dir>/SKILL.md
 ```
 
 Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
-`vale-wrap.sh` runs from the repo root using `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns dimensions below, not a replacement for Step 3. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in those dimensions, citing the rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable.
+`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`, so it runs correctly regardless of the caller's cwd, using `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns dimensions below, not a replacement for Step 3. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in those dimensions, citing the rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable.
 
 ## Step 2 — Read all skill files
 
@@ -70,6 +70,8 @@ For each sentence in the body, apply: *"Would the agent get this wrong without t
 - **Why rationale**: include/exclude rules explain why, not just what
 - **Control calibration**: prescriptive for fragile or critical sequences (e.g. a script invocation where flag order or exact arguments must not change); flexible where multiple approaches are valid
 
+Vale's `Kyberforge.VagueQualifier` (SUGGESTION — vague filler like "clearly", "obviously") and `Kyberforge.SentenceOpenerThereIs` (SUGGESTION — sentences starting with "There is"/"There are") alerts from Step 1 cover pattern-matchable body-wide filler directly; report them as findings without re-deriving by judgment.
+
 If uncertain whether a sentence is padding or whether a control decision is correctly calibrated, read `references/body-discipline.md`.
 
 ### Patterns
diff --git a/plugins/kyberforge/skills/skill-author/SKILL.md b/plugins/kyberforge/skills/skill-author/SKILL.md
index 3b84d36..35911d0 100644
--- a/plugins/kyberforge/skills/skill-author/SKILL.md
+++ b/plugins/kyberforge/skills/skill-author/SKILL.md
@@ -114,7 +114,7 @@ Rename the placeholder section heading to one that fits the skill's structure 
 Ask of every sentence: "Would the agent get this wrong without it?" Cut anything that answers "no."
 
 **Include:**
-- Sequences or ordering constraints that aren't self-evident — the agent may skip or reorder steps without this
+- Non-obvious sequences or ordering constraints — the agent may skip or reorder steps without this
 - Domain conventions the agent cannot infer from general knowledge — this is the core value a skill adds
 - One default per decision point, plus one escape hatch — never a menu; menus cause the agent to pause or pick arbitrarily
 - Gotchas — facts that defy reasonable assumptions; the agent will get these wrong every time without them
diff --git a/plugins/lint/.claude-plugin/plugin.json b/plugins/lint/.claude-plugin/plugin.json
index b0b2c8a..d186f5f 100644
--- a/plugins/lint/.claude-plugin/plugin.json
+++ b/plugins/lint/.claude-plugin/plugin.json
@@ -13,5 +13,5 @@
   ],
   "license": "MIT",
   "name": "lint",
-  "version": "1.1.1"
+  "version": "1.1.2"
 }
diff --git a/plugins/lint/agents/lint-runner.agent.md b/plugins/lint/agents/lint-runner.agent.md
index 6e6a35b..073cc3c 100644
--- a/plugins/lint/agents/lint-runner.agent.md
+++ b/plugins/lint/agents/lint-runner.agent.md
@@ -5,6 +5,9 @@ description: Runs a linter sweep over a target file or directory scope and repor
 
 tools: ["execute", "read", "search"]
 
+source_keys:
+  - context7-websites-vale-sh
+
 ---
 
 You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
diff --git a/plugins/lint/agents/lint-runner.md b/plugins/lint/agents/lint-runner.md
index 34a2fba..c2950d9 100644
--- a/plugins/lint/agents/lint-runner.md
+++ b/plugins/lint/agents/lint-runner.md
@@ -5,6 +5,9 @@ description: Runs a linter sweep over a target file or directory scope and repor
 
 tools: Bash, Read, Grep, Glob
 
+source_keys:
+  - context7-websites-vale-sh
+
 ---
 
 You are a linter runner. When invoked, you run the appropriate linter(s) over the requested scope, collect their findings, and report them back in a structured, reviewable form. You never edit files.
diff --git a/plugins/lint/plugin.json b/plugins/lint/plugin.json
index 3af77e3..453ee26 100644
--- a/plugins/lint/plugin.json
+++ b/plugins/lint/plugin.json
@@ -18,5 +18,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.1.1"
+  "version": "1.1.2"
 }
diff --git a/plugins/lint/skills/vale-run/SKILL.md b/plugins/lint/skills/vale-run/SKILL.md
index 8b0d78c..c1f4915 100644
--- a/plugins/lint/skills/vale-run/SKILL.md
+++ b/plugins/lint/skills/vale-run/SKILL.md
@@ -11,7 +11,7 @@ description: >
   project has no .vale.ini yet, or needs styles installed/configured — that's the
   vale-config skill.
 metadata:
-  version: "0.1.0"
+  version: "0.1.1"
   category: lint
   source_keys:
     - context7-websites-vale-sh
@@ -22,10 +22,11 @@ metadata:
 - Vale exits non-zero whenever it finds an alert at or above `MinAlertLevel` — that's what makes it usable as a CI gate, not a sign the invocation failed. Read the output before concluding the command errored.
 - `vale ls-config` prints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in `.vale.ini`.
 - Inline suppression syntax is format-specific: Markdown/MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. Don't assume one syntax works across formats.
+- Before calling the `vale` binary directly, check whether the target repo documents its own wrapper script for Vale (look in its README, CONTRIBUTING docs, pre-commit config, or a `scripts/` directory). Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter fields — and calling bare `vale` in a repo that has such a wrapper silently skips whatever the wrapper works around. If a wrapper is documented, invoke it with the same arguments instead of calling `vale` directly; otherwise fall back to the default below.
 
 ## Running vale
 
-Default invocation:
+Default invocation (when the target repo has no documented Vale wrapper — see Gotchas):
 
 ```bash
 vale <path-or-glob>
diff --git a/plugins/lint/skills/vale-run/references/troubleshooting.md b/plugins/lint/skills/vale-run/references/troubleshooting.md
index 6b0167e..326dde7 100644
--- a/plugins/lint/skills/vale-run/references/troubleshooting.md
+++ b/plugins/lint/skills/vale-run/references/troubleshooting.md
@@ -69,6 +69,16 @@ repos:
         args: [--output=line, --minAlertLevel=error]
 ```
 
+If the project has documented a wrapper script for a known Vale scope/escaping limitation (see the Gotchas section of `SKILL.md`), point the second hook's `entry:` at that wrapper instead of at bare `vale`, even though the hook's `repo`/`rev`/`id` still come from the upstream definition above — only the invocation target changes:
+
+```yaml
+      - id: vale
+        entry: <path-to-project-wrapper>
+        args: [--output=line, --minAlertLevel=error]
+```
+
+Using the upstream hook's bare `vale` entry in a project that has such a wrapper reintroduces exactly the bug the wrapper exists to fix.
+
 ## CI output for machine parsing
 
 ```bash
diff --git a/plugins/lint/sources.md b/plugins/lint/sources.md
new file mode 100644
index 0000000..dfe71b5
--- /dev/null
+++ b/plugins/lint/sources.md
@@ -0,0 +1,9 @@
+# Sources
+
+## context7-websites-vale-sh
+
+- **URL:** context7:/websites/vale_sh
+- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
+- **Description:** Official Vale documentation site (vale.sh) indexed by Context7 — informed `lint-runner`'s report-only design: normalizing findings to a `file, line, rule/check, severity, message` shape and deferring linter-specific invocation to `<linter>-config`/`<linter>-run` skills, drawing on Vale's CLI output format and exit-code conventions.
+- **Contributing files:** agents/lint-runner.md, agents/lint-runner.agent.md
+- **Status:** `extracted`
diff --git a/scripts/skill-size-check.sh b/scripts/skill-size-check.sh
index 8d92692..e137a7c 100755
--- a/scripts/skill-size-check.sh
+++ b/scripts/skill-size-check.sh
@@ -2,32 +2,38 @@
 set -euo pipefail
 
 # Enforces agentskills.io's skill-authoring.md guidance: keep SKILL.md under 500
-# lines and 5,000 tokens, so the full body doesn't crowd out conversation
+# lines and roughly 5,000 tokens, so the full body doesn't crowd out conversation
 # history and other active skills once loaded into context. Vale can't express
 # a whole-file length ceiling (its checks operate on text patterns, not raw
 # file size), so this is a plain script instead of a Vale rule.
 #
 # Token counts aren't computed exactly here — word count (`wc -w`) is used as
-# a proxy. For English prose this typically runs somewhat below true BPE token
-# counts, so a 5,000-word file is already at or past 5,000 tokens in practice;
-# treat this as a conservative, cheap approximation, not an exact measure.
+# a proxy. This repo's own SKILL.md corpus measures ~5.7-6.5 characters per
+# word, which at the standard ~4-characters-per-token English approximation
+# works out to roughly 1.6-1.7 tokens per word. MAX_WORDS below is calibrated
+# from that measured ratio against the 5,000-token ceiling, with margin — it's
+# still a proxy, not exact BPE tokenization, but now grounded in actual repo
+# content rather than an unverified "conservative" assumption.
 
 MAX_LINES=500
-MAX_WORDS=5000
+MAX_WORDS=2900
 FAIL=0
 
 for f in "$@"; do
   [[ -f "$f" ]] || continue
 
-  lines=$(wc -l < "$f")
-  if (( lines > MAX_LINES )); then
-    echo "ERROR: $f has $lines lines, exceeding the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2
+  # awk's NR counts the final line even without a trailing newline, matching
+  # Python's splitlines() semantics (used by skill-audit/scripts/validate.sh
+  # for its own line count) — `wc -l` undercounts by 1 in that case.
+  lines=$(awk 'END{print NR}' "$f")
+  if (( lines >= MAX_LINES )); then
+    echo "ERROR: $f has $lines lines, at or over the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2
     FAIL=1
   fi
 
   words=$(wc -w < "$f")
   if (( words > MAX_WORDS )); then
-    echo "ERROR: $f has $words words (proxy for tokens), exceeding the $MAX_WORDS-token ceiling (agentskills.io skill-authoring.md)" >&2
+    echo "ERROR: $f has $words words (proxy for tokens), exceeding the $MAX_WORDS-word ceiling (~5,000 tokens, agentskills.io skill-authoring.md)" >&2
     FAIL=1
   fi
 done
diff --git a/scripts/vale-wrap.sh b/scripts/vale-wrap.sh
index 67b69fa..64ee5f5 100755
--- a/scripts/vale-wrap.sh
+++ b/scripts/vale-wrap.sh
@@ -29,15 +29,26 @@ for arg in "$@"; do
     config_next=true
     continue
   fi
+  if [[ "$arg" == --config=* ]]; then
+    cfg="${arg#--config=}"
+    if [[ "$cfg" == /* ]]; then
+      vale_args+=("--config=$cfg")
+    else
+      vale_args+=("--config=$repo_root/$cfg")
+    fi
+    continue
+  fi
   if [[ "$arg" != -* && -f "$repo_root/$arg" ]]; then
     files+=("$arg")
+  elif [[ "$arg" == /* && -f "$arg" && "$arg" == "$repo_root"/* ]]; then
+    files+=("${arg#"$repo_root"/}")
   else
     vale_args+=("$arg")
   fi
 done
 
 if [[ ${#files[@]} -eq 0 ]]; then
-  exec vale "${vale_args[@]}"
+  exec vale "${vale_args[@]}" < /dev/null
 fi
 
 tmpdir="$(mktemp -d)"
@@ -47,7 +58,6 @@ for rel in "${files[@]}"; do
   dest="$tmpdir/$rel"
   mkdir -p "$(dirname "$dest")"
   python3 - "$repo_root/$rel" "$dest" <<'PYTHON'
-import json
 import re
 import sys
 
@@ -58,17 +68,52 @@ with open(src) as fh:
 fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
 if fm_match:
     fm = fm_match.group(2)
-    desc_m = re.search(r'^description:\s*([>|][+-]?)\n((?:[ \t]+.+\n?)+)', fm, re.MULTILINE)
-    if desc_m and desc_m.group(2).count('\n') >= 2:
-        raw = desc_m.group(2)
-        flat = re.sub(r'\s+', ' ', raw).strip()
-        # JSON string escaping is a valid subset of YAML double-quoted scalar
-        # escaping, so this is always a well-formed YAML value regardless of
-        # colons, quotes, or backslashes in the description text.
-        flat_q = json.dumps(flat)
-        pad = '\n' * raw.count('\n')
-        new_fm = fm[:desc_m.start()] + f'description: {flat_q}\n{pad}' + fm[desc_m.end():]
-        content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
+    # Only `>`/`>-`/`>+` (folded) scalars break Vale's frontmatter-description
+    # scope. `|`/`|-`/`|+` (literal) scalars already work fine with bare vale,
+    # so they're deliberately left unmatched here.
+    header_m = re.search(r'^description:[ \t]*(>[+-]?)[ \t]*\n', fm, re.MULTILINE)
+    if header_m:
+        # Body capture is indentation-based and blank-line-tolerant, per YAML
+        # block-scalar rules: a blank line (any amount of whitespace) always
+        # stays inside the block; the indent is set by the first content line;
+        # the block ends at the first line indented less than that, or EOF.
+        rest = fm[header_m.end():]
+        indent = None
+        body_lines = []
+        for line in rest.splitlines(keepends=True):
+            text = line.rstrip('\n')
+            if text.strip() == '':
+                body_lines.append(line)
+                continue
+            line_indent = len(text) - len(text.lstrip(' \t'))
+            if indent is None:
+                indent = line_indent
+            elif line_indent < indent:
+                break
+            body_lines.append(line)
+        raw = ''.join(body_lines)
+        if raw.count('\n') >= 2:
+            flat = re.sub(r'\s+', ' ', raw).strip()
+            # YAML single-quoted scalars have no backslash-escape mechanism at
+            # all, so wrapping in single quotes sidesteps the backslash-escape
+            # bug entirely for embedded double quotes, backslashes, and
+            # non-ASCII text. The one YAML-spec-correct way to embed a literal
+            # apostrophe is to double it ('') — but Vale's own frontmatter
+            # scanner isn't a full YAML parser and doesn't understand that
+            # doubling: empirically, it silently truncates the value at the
+            # first ' it sees, hiding everything after it from the NLP scope
+            # (a different flavor of the same bug this whole script exists to
+            # work around). Since this copy is scratch-only and never written
+            # back, sidestep it by substituting a Unicode right single
+            # quotation mark (U+2019) for any literal apostrophe instead of
+            # doubling it — visually a smart quote, but never triggers a YAML
+            # escape sequence at all.
+            flat_q = "'" + flat.replace("'", "’") + "'"
+            pad = '\n' * raw.count('\n')
+            start = header_m.start()
+            end = header_m.end() + len(raw)
+            new_fm = fm[:start] + f'description: {flat_q}\n{pad}' + fm[end:]
+            content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
 
 with open(dest, 'w') as fh:
     fh.write(content)
diff --git a/styles/Kyberforge/SentenceOpenerThereIs.yml b/styles/Kyberforge/SentenceOpenerThereIs.yml
index b636ada..691baf1 100644
--- a/styles/Kyberforge/SentenceOpenerThereIs.yml
+++ b/styles/Kyberforge/SentenceOpenerThereIs.yml
@@ -1,7 +1,7 @@
 extends: existence
 message: "Don't start a sentence with '%s' — name the subject directly"
 level: warning
-scope: text
+scope: sentence
 ignorecase: false
 raw:
-  - '(?:[;-]\s)There\s(is|are)|\bThere\s(is|are)\b'
+  - '^There\s(is|are)\b'
diff --git a/styles/Kyberforge/VagueQualifier.yml b/styles/Kyberforge/VagueQualifier.yml
index 2de0ab4..d33bfe8 100644
--- a/styles/Kyberforge/VagueQualifier.yml
+++ b/styles/Kyberforge/VagueQualifier.yml
@@ -4,33 +4,16 @@ level: warning
 scope: text
 ignorecase: true
 tokens:
-  - clearly
-  - obviously
-  - obvious
-  - simply
-  - simple
   - easily
-  - easy
-  - of course
   - everyone knows
-  - completely
   - exceedingly
   - excellent
   - extremely
-  - fairly
   - huge
   - interestingly
-  - largely
-  - mostly
+  - of course
   - quite
-  - relatively
   - remarkably
-  - several
-  - significantly
-  - substantially
   - surprisingly
-  - tiny
-  - usually
-  - various
   - vast
   - very
diff --git a/tests/test-skill-size-check.sh b/tests/test-skill-size-check.sh
index f43de7e..cf7d3c8 100755
--- a/tests/test-skill-size-check.sh
+++ b/tests/test-skill-size-check.sh
@@ -60,6 +60,102 @@ else
   pass "file over the 5,000-word ceiling exits non-zero"
 fi
 
+# Boundary-pair tests below read the script's current MAX_WORDS rather than
+# hardcoding it, so they don't silently drift if the threshold changes again.
+MAX_WORDS="$(grep -oE '^MAX_WORDS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
+MAX_LINES="$(grep -oE '^MAX_LINES=[0-9]+' "$SCRIPT" | cut -d= -f2)"
+
+# make_line_fixture builds a file with an exact total line count (frontmatter
+# included), independent of word count, for the line-boundary tests.
+make_line_fixture() {
+  local name="$1" total_lines="$2" file body_lines
+  file="$TMPDIR/$name.md"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: Test fixture."
+    echo "---"
+  } > "$file"
+  body_lines=$((total_lines - 4))
+  for ((i = 1; i <= body_lines; i++)); do
+    echo "word"
+  done >> "$file"
+  echo "$file"
+}
+
+# The line ceiling is exclusive of the limit itself ("stay under $MAX_LINES
+# lines", per skill-authoring.md), enforced via `>=` — so $((MAX_LINES - 1))
+# must pass and $MAX_LINES itself must already fail.
+echo ""
+echo "--- passes a file at $((MAX_LINES - 1)) lines, just under the $MAX_LINES-line boundary ---"
+AT_LINES="$(make_line_fixture at-line-limit "$((MAX_LINES - 1))")"
+ACTUAL_LINES=$(awk 'END{print NR}' "$AT_LINES")
+if [[ "$ACTUAL_LINES" -ne "$((MAX_LINES - 1))" ]]; then
+  fail "fixture has $ACTUAL_LINES lines, expected exactly $((MAX_LINES - 1))"
+elif "$SCRIPT" "$AT_LINES"; then
+  pass "file at $((MAX_LINES - 1)) lines exits 0"
+else
+  fail "file at $((MAX_LINES - 1)) lines should have exited 0"
+fi
+
+echo ""
+echo "--- fails a file at exactly the $MAX_LINES-line boundary ---"
+OVER_LINES="$(make_line_fixture over-line-limit "$MAX_LINES")"
+ACTUAL_OVER_LINES=$(awk 'END{print NR}' "$OVER_LINES")
+if [[ "$ACTUAL_OVER_LINES" -ne "$MAX_LINES" ]]; then
+  fail "fixture has $ACTUAL_OVER_LINES lines, expected exactly $MAX_LINES"
+elif "$SCRIPT" "$OVER_LINES" 2>/dev/null; then
+  fail "file at exactly $MAX_LINES lines should have exited non-zero (>= ceiling, the boundary bug this test guards against)"
+else
+  pass "file at exactly $MAX_LINES lines exits non-zero"
+fi
+
+# make_word_fixture builds a file with an exact total word count (frontmatter
+# words included, since the script's `wc -w` counts the whole file) by padding
+# a body line with just enough "word" tokens to close the gap to the target.
+make_word_fixture() {
+  local name="$1" target="$2" file cur remaining body
+  file="$TMPDIR/$name.md"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: Test fixture."
+    echo "---"
+  } > "$file"
+  cur=$(wc -w < "$file")
+  remaining=$((target - cur))
+  body=""
+  for ((i = 1; i <= remaining; i++)); do
+    body="$body word"
+  done
+  echo "$body" >> "$file"
+  echo "$file"
+}
+
+echo ""
+echo "--- passes a file at exactly the $MAX_WORDS-word boundary ---"
+AT_WORDS="$(make_word_fixture at-word-limit "$MAX_WORDS")"
+ACTUAL_WORDS=$(wc -w < "$AT_WORDS")
+if [[ "$ACTUAL_WORDS" -ne "$MAX_WORDS" ]]; then
+  fail "fixture has $ACTUAL_WORDS words, expected exactly $MAX_WORDS"
+elif "$SCRIPT" "$AT_WORDS"; then
+  pass "file at exactly $MAX_WORDS words exits 0"
+else
+  fail "file at exactly $MAX_WORDS words should have exited 0"
+fi
+
+echo ""
+echo "--- fails a file one word over the $MAX_WORDS-word boundary ---"
+OVER_WORDS="$(make_word_fixture over-word-limit "$((MAX_WORDS + 1))")"
+ACTUAL_OVER_WORDS=$(wc -w < "$OVER_WORDS")
+if [[ "$ACTUAL_OVER_WORDS" -ne "$((MAX_WORDS + 1))" ]]; then
+  fail "fixture has $ACTUAL_OVER_WORDS words, expected exactly $((MAX_WORDS + 1))"
+elif "$SCRIPT" "$OVER_WORDS" 2>/dev/null; then
+  fail "file at $((MAX_WORDS + 1)) words should have exited non-zero"
+else
+  pass "file at $((MAX_WORDS + 1)) words exits non-zero"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index 729c0b5..2f144e0 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -78,6 +78,210 @@ else
   fail "reported line number ($MAX_LINE) exceeds original file line count ($ORIG_LINES)"
 fi
 
+# make_raw_fixture writes stdin verbatim to a fresh fixture's SKILL.md, for
+# cases where the exact description body needs to be hand-crafted rather than
+# generated from the desc_lines loop above.
+make_raw_fixture() {
+  local dir
+  dir="$(mktemp -d)"
+  (cd "$dir" && git init -q)
+  mkdir -p "$dir/plugins/testplugin/skills/zzzskill"
+  cat > "$dir/plugins/testplugin/skills/zzzskill/SKILL.md"
+  echo "$dir"
+}
+
+# --- 4. A folded description containing a double quote is still caught ---
+# This is the exact case that silently passed (zero alerts) before switching
+# from json.dumps (double-quoted, backslash-escaped) to a single-quoted scalar.
+echo ""
+echo "--- catches vague wording when the folded description contains a double quote ---"
+FIXTURE4="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the user says "audit this skill" and helps with and utilize things.
+  Second line continues the same folded scalar for flattening.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
+if (cd "$FIXTURE4" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when the description contains a double quote"
+else
+  fail "silently missed vague wording in a description containing a double quote — the bug this test guards against"
+fi
+
+# --- 5. A folded description containing an apostrophe fires and stays valid YAML ---
+echo ""
+echo "--- catches vague wording when the folded description contains an apostrophe ---"
+FIXTURE5="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the user's task helps with and utilize things across two lines.
+  Second continuation line for the fold.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
+OUT5=$(cd "$FIXTURE5" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1)
+if echo "$OUT5" | grep -q "VagueWording"; then
+  pass "flags vague wording when the description contains an apostrophe"
+else
+  fail "silently missed vague wording in a description containing an apostrophe"
+fi
+if echo "$OUT5" | grep -qi "yaml:"; then
+  fail "flattened copy with an apostrophe produced a YAML parse error"
+else
+  pass "flattened copy with an apostrophe is valid YAML (no parse error)"
+fi
+
+# --- 6. A folded description with a backslash and a non-ASCII character ---
+echo ""
+echo "--- catches vague wording when the folded description has a backslash and non-ASCII text ---"
+FIXTURE6="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the café résumé naïve thing helps with and utilize things here.
+  Path is C:\Users\test and this is the second continuation line.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6"' EXIT
+if (cd "$FIXTURE6" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+  pass "flags vague wording when the description has a backslash and non-ASCII text"
+else
+  fail "silently missed vague wording in a description with a backslash and non-ASCII text"
+fi
+
+# --- 7. A folded description with a blank line between two paragraphs ---
+echo ""
+echo "--- handles a blank line inside a folded description without crashing ---"
+FIXTURE7="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the user needs a general helper.
+
+  Do not use when this helps with and utilize things instead.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7"' EXIT
+OUT7=$(cd "$FIXTURE7" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1)
+if echo "$OUT7" | grep -q "Traceback"; then
+  fail "crashed while flattening a description with a blank line between paragraphs"
+elif echo "$OUT7" | grep -q "VagueWording"; then
+  pass "still flags vague wording in the second paragraph after a blank line"
+else
+  fail "silently missed vague wording in the second paragraph after a blank line — the bug this test guards against"
+fi
+
+# --- 8. --config=<path> (equals form) resolves the same as the two-argv form ---
+echo ""
+echo "--- --config=<path> equals form resolves from a subdirectory like the two-argv form ---"
+FIXTURE8="$(mktemp -d)"
+(cd "$FIXTURE8" && git init -q)
+cp "$REPO_ROOT/.vale.ini" "$FIXTURE8/.vale.ini"
+cp -r "$REPO_ROOT/styles" "$FIXTURE8/styles"
+mkdir -p "$FIXTURE8/plugins/testplugin/skills/zzzskill"
+{
+  echo "---"
+  echo "name: zzzskill"
+  echo "description: >"
+  echo "  Line one mentions helps with and utilize, plus a colon: like this."
+  echo "  Line two continues the same folded scalar for flattening."
+  echo "---"
+  echo ""
+  echo "Body."
+} > "$FIXTURE8/plugins/testplugin/skills/zzzskill/SKILL.md"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8"' EXIT
+SUBDIR8="$FIXTURE8/plugins/testplugin/skills/zzzskill"
+REL8="plugins/testplugin/skills/zzzskill/SKILL.md"
+OUT_EQ=$(cd "$SUBDIR8" && bash "$SCRIPT" --config=.vale.ini "$REL8" 2>&1)
+OUT_TWO=$(cd "$SUBDIR8" && bash "$SCRIPT" --config .vale.ini "$REL8" 2>&1)
+if echo "$OUT_EQ" | grep -q "VagueWording" && [[ "$OUT_EQ" == "$OUT_TWO" ]]; then
+  pass "--config=<path> from a subdirectory resolves and matches the two-argv form"
+else
+  fail "--config=<path> equals form did not resolve the same as the two-argv form"
+fi
+
+# --- 9. Zero file args (or a file list that filters to nothing) exits promptly ---
+echo ""
+echo "--- exits promptly instead of hanging on stdin when no files are passed ---"
+if timeout 5 bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" < <(sleep 100) >/dev/null 2>&1; then
+  pass "exits promptly with zero file args"
+else
+  RC=$?
+  if [[ $RC -eq 124 ]]; then
+    fail "hung waiting on stdin with zero file args — the bug this test guards against"
+  else
+    pass "exits promptly (nonzero exit) with zero file args"
+  fi
+fi
+
+echo ""
+echo "--- exits promptly when a file list filters down to nothing ---"
+if timeout 5 bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" --no-such-flag < <(sleep 100) >/dev/null 2>&1; then
+  pass "exits promptly when no file-shaped args remain"
+else
+  RC=$?
+  if [[ $RC -eq 124 ]]; then
+    fail "hung waiting on stdin when the file list filtered to nothing — the bug this test guards against"
+  else
+    pass "exits promptly (nonzero exit) when the file list filters to nothing"
+  fi
+fi
+
+# --- 10. An absolute path to the fixture SKILL.md is still linted, not skipped ---
+echo ""
+echo "--- lints an absolute path to a skill file instead of silently skipping it ---"
+FIXTURE10="$(make_fixture 2)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10"' EXIT
+ABS_FILE10="$FIXTURE10/plugins/testplugin/skills/zzzskill/SKILL.md"
+if (cd "$FIXTURE10" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" "$ABS_FILE10") | grep -q "VagueWording"; then
+  pass "an absolute path under repo_root is linted, not silently skipped"
+else
+  fail "an absolute path under repo_root was silently skipped — the bug this test guards against"
+fi
+
+# --- 11. A literal (|) block scalar passes through unflattened (no regression) ---
+echo ""
+echo "--- leaves a literal (|) block scalar untouched (narrowed >-only scope) ---"
+FIXTURE11="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: |
+  Line one mentions helps with and utilize things here.
+  Line two continues the literal block scalar for this test.
+---
+
+Body.
+EOF
+)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11"' EXIT
+REL11="plugins/testplugin/skills/zzzskill/SKILL.md"
+WRAPPED_OUT=$(cd "$FIXTURE11" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" "$REL11" 2>&1 || true)
+BARE_OUT=$(cd "$FIXTURE11" && vale --config "$REPO_ROOT/.vale.ini" "$REL11" 2>&1 || true)
+if [[ "$WRAPPED_OUT" == "$BARE_OUT" ]]; then
+  pass "literal (|) block scalar output matches bare vale exactly — untouched by flattening"
+else
+  fail "wrapper altered output for a literal (|) block scalar description — should be left untouched"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 210b19261366d381c4dc33602f35a707f77959ff Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sat, 8 Aug 2026 19:38:14 +0000
Subject: [PATCH 13/45] docs(lint): add docs index for Vale research docs

plugins/lint/docs/research/docs/vale/ had no top-level index pointing
into it, unlike plugins/kyberforge/docs/README.md which indexes its
own research directories. Add plugins/lint/docs/README.md mirroring
that convention: one line per file describing what it covers, plus a
provenance note tying the directory back to plugins/lint/sources.md
and the vale-config/vale-run skills that consume it.

Closes out a follow-up item from PR #85's review.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 plugins/lint/docs/README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 plugins/lint/docs/README.md

diff --git a/plugins/lint/docs/README.md b/plugins/lint/docs/README.md
new file mode 100644
index 0000000..371f066
--- /dev/null
+++ b/plugins/lint/docs/README.md
@@ -0,0 +1,27 @@
+# docs/
+
+Plugin documentation. Not read automatically by Claude Code or GitHub Copilot CLI — reference specific files from skill bodies or agent prompts as needed.
+
+## research/
+
+Upstream reference material gathered during skill authoring. Not shipped with the plugin — used at development time only.
+
+| Path | Purpose |
+|------|---------|
+| `research/docs/vale/` | Vale documentation (vale.sh), gathered while authoring `vale-config`/`vale-run` — see below |
+
+### research/docs/vale/
+
+| File | Covers |
+|------|--------|
+| `overview.md` | What Vale is; the style/rule/check configuration model; the built-in `Vale` style's four rules; styles directory layout |
+| `installation.md` | Installing Vale via OS package managers (Homebrew, Snap, Chocolatey) and Docker |
+| `configuration.md` | `.vale.ini` structure — global, `[formats]`, and per-glob sections |
+| `cli-reference.md` | Core invocation and key subcommands/flags (`vale sync`, `vale ls-config`, etc.) |
+| `examples.md` | Walkthroughs — project initialization, typical `.vale.ini` configs |
+| `troubleshooting.md` | Suppressing false positives via inline markup (format-specific `vale off`/`vale on` syntax, spelling ignore lists) |
+| `sources.md` | Provenance record for this directory — source URL, description, and which files above were extracted from it |
+
+Each file's frontmatter carries a `source_keys` entry keyed to the same provenance record. The plugin-level provenance file, `plugins/lint/sources.md`, cross-references this directory from the `context7-websites-vale-sh` entry and lists the agents/skills whose content drew on it.
+
+`vale-config` and `vale-run` are the skills that consume this research — read the relevant file here before changing either skill's Vale-facing behavior.
-- 
2.43.0


From 149d564f6a0aa6be71a65cd3c56befde33903aef Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sat, 8 Aug 2026 20:42:15 +0000
Subject: [PATCH 14/45] fix(lint): make the Vale gate actually gate, drop
 VagueQualifier
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-3 review of PR #85 found the "enforcing" pre-commit hook enforced
nothing. Vale's exit code keys on error-level alerts alone: five of the
six rules were level: warning, so they exited 0, and pre-commit hides
output from a passing hook — the alerts were invisible and blocked
nothing. ADR-0013 rejected a report-only trial tier and then shipped one
by accident.

Flatten every rule to level: error. Vale's own exit code is then correct,
so the hook entry drops to a bare vale-wrap.sh call and the graded
error->FAIL / warning->SUGGESTION mapping disappears from both audit
skills: every alert is a FAIL, in the gate and the audit alike. No
ignorable tier, matching shellcheck, the test suite and
conventional-pre-commit.

Delete Kyberforge.VagueQualifier. Measured against the 41 skill/agent
files as they stood before the rule ever ran: 2 hits. One marginal
("very different" -> "fundamentally different"), one an unfixable false
positive — caveman/SKILL.md quotes "of course" as an example of filler,
a mention not a use — which forced the only Vale suppression comments in
the repo. Those four lines go with it; two of them were dead anyway,
suppressing a frontmatter-scoped rule on a body line. Held-out prose (273
files) fired 15 times, 9 inside out-of-scope research examples and the
rest one word in two idioms in a single doc. SentenceOpenerThereIs
survives: 22 held-out hits, both in-corpus hits clean rewrites, zero
suppressions.

Widen .vale.ini's globs to [**/SKILL.md], [**/agents/*.md] and
[**/*.agent.md]. The plugins/*/-prefixed globs scoped nothing — Vale's *
crosses /, so they already matched docs/research/examples/**/agents/*.md
and assets/templates/SKILL.md, the two paths CONTEXT.md claimed they
excluded. Scoping is and was the hook's files: regex. The old globs also
hid a silent false negative: a skill outside plugins/ matched no section,
so Vale reported 0 files and exited 0, which both audits read as clean.
They now treat a 0-file run as NOT RUN and fall back to full judgment.

Also:
- vale-wrap.sh resolves relative --config values and file arguments
  against the caller's cwd, as vale does, instead of the repo root, which
  hard-errored from a subdirectory and silently skipped flattening for
  file args that did not resolve from the root. Absolute paths inside the
  cwd are relativized so reports cite resolvable paths, not scratch ones.
- vale-run's exit-code model was documented backwards ("exits non-zero
  whenever it finds an alert at or above MinAlertLevel") and would have
  led anyone following it to build a gate that passes everything. Its
  Markdown suppression syntax was MDX-only and does not suppress in .md;
  corrected in the skill and its troubleshooting reference, with
  backtick/fence exemption documented as the first resort.
- skill-size-check.sh fails only above 500 lines, agreeing with
  skill-audit's validate.sh <= 500 pass.
- ADR-0013 and CONTEXT.md amended to match, recording why graded
  severities cannot gate.

Verified: 9 test scripts / 15 vale-wrap cases pass; vale-audit-prefilter,
skill-size-check and shellcheck pass --all-files; check-manifests and
claude plugin validate --strict clean. New tests fail against the old
script (3 of them) and pass against the new one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 .pre-commit-config.yaml                       |   2 +-
 .vale.ini                                     |   7 +-
 CONTEXT.md                                    |   6 +-
 ...013-vale-harness-scope-and-rule-sources.md |  40 +++++--
 plugins/bin/skills/caveman/SKILL.md           |   7 +-
 .../kyberforge/skills/agent-audit/SKILL.md    |   6 +-
 .../kyberforge/skills/skill-audit/SKILL.md    |   6 +-
 plugins/lint/skills/vale-run/SKILL.md         |  17 +--
 .../vale-run/references/troubleshooting.md    |  19 ++-
 scripts/skill-size-check.sh                   |  21 ++--
 scripts/vale-wrap.sh                          | 107 ++++++++++++-----
 styles/Kyberforge/PaddingPhrase.yml           |   2 +-
 styles/Kyberforge/SentenceOpenerThereIs.yml   |   2 +-
 styles/Kyberforge/VagueQualifier.yml          |  19 ---
 styles/Kyberforge/VagueWording.yml            |   2 +-
 styles/KyberforgeCopilot/ProactivePhrase.yml  |   2 +-
 tests/test-skill-size-check.sh                |  32 +++---
 tests/test-vale-wrap.sh                       | 108 ++++++++++++++----
 18 files changed, 269 insertions(+), 136 deletions(-)
 delete mode 100644 styles/Kyberforge/VagueQualifier.yml

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index ed9a129..ad1a9d6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -111,7 +111,7 @@ repos:
         stages: ['pre-commit']
         name: Vale audit prefilter
         description: Run Vale against skill/agent markdown files as a deterministic prefilter for skill-audit/agent-audit
-        entry: scripts/vale-wrap.sh --config .vale.ini --minAlertLevel=warning
+        entry: scripts/vale-wrap.sh --config .vale.ini
         language: script
         files: '^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$'
         pass_filenames: true
diff --git a/.vale.ini b/.vale.ini
index c0d0410..f4a9999 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -1,11 +1,10 @@
 StylesPath = styles
-MinAlertLevel = suggestion
 
-[plugins/*/skills/*/SKILL.md]
+[**/SKILL.md]
 BasedOnStyles = Kyberforge
 
-[plugins/*/agents/*.md]
+[**/agents/*.md]
 BasedOnStyles = Kyberforge
 
-[plugins/*/agents/*.agent.md]
+[**/*.agent.md]
 BasedOnStyles = Kyberforge, KyberforgeCopilot
diff --git a/CONTEXT.md b/CONTEXT.md
index 142f18b..78ae023 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -70,11 +70,11 @@ A companion skill (`core` plugin) that detects a target repo's provider-specific
 A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
 
 ### Vale audit prefilter (skill-audit / agent-audit)
-Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. `error` alerts map to FAIL, `warning`/`suggestion` map to SUGGESTION. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, two body-wide prose-pattern checks (vague-qualifier filler, "There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
+Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
 
-Both skills' Step 1, and the `vale-audit-prefilter` pre-commit hook, call `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched. `tests/test-vale-wrap.sh` regression-tests this. Both call sites still scope every invocation to the specific file(s) being audited, never a repo-wide sweep — Vale's glob matching crosses directory boundaries (`plugins/*/agents/*.md` matches nested `docs/research/examples/**/agents/*.md` too), so scoping is what keeps research-example files out of the audit's lint pass. The pre-commit hook's own glob is tightened to `^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$` (single-segment, not `.*`) for the same reason, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target.
+Both skills' Step 1, and the `vale-audit-prefilter` pre-commit hook, call `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched; a relative `--config` path resolves against the caller's cwd, matching bare `vale`, not against the repo root. `tests/test-vale-wrap.sh` regression-tests this. `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]`, `[**/agents/*.md]`, `[**/*.agent.md]`) and do no scoping: Vale's `*` crosses `/`, so the older `plugins/*/`-prefixed globs already matched `plugins/*/docs/research/examples/**/agents/*.md` and `plugins/*/skills/*/assets/templates/SKILL.md`. Scoping comes from the pre-commit hook's `files:` regex, `^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$` (single-segment, not `.*`, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target), and from the audit skills passing one explicit file per invocation. The path-agnostic globs also close a silent false negative: a skill outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) matched no section, so Vale reported 0 files and exited 0 — which the audits read as clean. Both audits now treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
 
-This scope expands per ADR-0013: cherry-picked low-noise `write-good`/`alex` rules landed in `styles/Kyberforge` as two new rule files, `Kyberforge.VagueQualifier` and `Kyberforge.SentenceOpenerThereIs`, plus a new sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter`, so it never lints `docs/research/examples/` reference skills. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine).
+This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — failing only above 500 lines, matching `skill-audit/scripts/validate.sh`'s `<= 500` pass — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter`, so it never lints `docs/research/examples/` reference skills. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
 
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/docs/adr/0013-vale-harness-scope-and-rule-sources.md b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
index 3ed267e..2227a9e 100644
--- a/docs/adr/0013-vale-harness-scope-and-rule-sources.md
+++ b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
@@ -9,8 +9,8 @@ deferred PR #85 review item to broaden that coverage, retroactively captures #84
 (since it was never recorded as a decision in its own right), and layers the expansion on top
 without reversing or weakening the original four rules.
 
-**File scope stays the same.** `SKILL.md` plus agent files (`plugins/*/agents/*.md`,
-`plugins/*/agents/*.agent.md`) only — matching the existing prefilter's globs. Skill-level
+**File scope stays the same.** `SKILL.md` plus agent files (`**/agents/*.md`,
+`**/*.agent.md`) only — matching the existing prefilter's globs. Skill-level
 `README.md` files and `plugin.json` manifests are not added: README.md files are navigational, not
 spec-governed content, and `plugin.json` is JSON, not prose Vale can meaningfully lint.
 
@@ -51,7 +51,13 @@ length ceiling, not a text pattern, so it isn't a Vale rule — it becomes a new
 and pre-commit hook, sibling to the existing `skill-frontmatter` hook.
 
 **Rules land directly in `styles/Kyberforge`, enforcing immediately.** No trial/report-only tier
-is introduced (see Considered Options). The implementation pass finalizes the cherry-picked
+is introduced (see Considered Options). "Enforcing immediately" holds only because every rule in
+both styles is `level: error`: Vale's exit code keys on `error`-level alerts alone, so a
+`warning`- or `suggestion`-level rule prints an alert and still exits 0, and pre-commit suppresses
+output from hooks that pass — such a rule is invisible and blocks nothing. Every Vale alert is
+therefore a FAIL, in the audit skills and in the blocking pre-commit hook alike, with no ignorable
+tier; that matches every other gate in this repo (shellcheck, the test suite,
+conventional-pre-commit). The implementation pass finalizes the cherry-picked
 `write-good`/`alex` rules and any new spec-derived rule wording, runs the full set against the
 existing SKILL.md/agent-file corpus, fixes any resulting violations across that corpus, and lands
 the rule changes and the corpus fixes as one atomic commit — the same enforcement model as the
@@ -68,14 +74,29 @@ under that directory automatically — there's no partial/opt-in application wit
 rule dropped straight into `styles/Kyberforge` goes live in the blocking pre-commit hook
 immediately. Rejected in favor of finalizing rules directly and fixing violations via subagent
 before committing: simpler, no new trial-config machinery to build or maintain — at the cost of no
-standing report-only tier for future candidate rules.
+standing report-only tier for future candidate rules. Note that the first implementation shipped
+graded severities (`error`/`warning`/`suggestion`) and thereby recreated the rejected option by
+accident: the five non-`error` rules never affected an exit code and never surfaced output through
+a passing pre-commit hook, so they were a report-only tier that reported to nobody. Flattening
+every rule to `level: error` is what actually implements this decision.
 
 ## Consequences
 
-- `styles/Kyberforge/` gained two new rule files, cherry-picked from `write-good`/`alex` as
-  low-noise against this repo's corpus: `VagueQualifier.yml` and `SentenceOpenerThereIs.yml`.
+- `styles/Kyberforge/` gained one new rule file, cherry-picked from `write-good`/`alex` as
+  low-noise against this repo's corpus: `SentenceOpenerThereIs.yml` (22 hits across 273 held-out
+  markdown files; both in-corpus hits were clean rewrites, needing no suppression).
+- A second candidate, `VagueQualifier.yml`, was cherry-picked and then dropped. Against the 41
+  skill/agent files it hit twice: one marginal real finding (`prototype/SKILL.md`, "very different"
+  → "fundamentally different") and one false positive (`caveman/SKILL.md`, which *quotes* `of
+  course` as an example of filler — a mention, not a use) that no rewrite could clear, forcing the
+  repo's only Vale suppression comments. Of its 15 held-out hits, 9 were in `docs/research/examples/`
+  (out-of-scope upstream material) and the remaining 6 were the word "very" in two idioms in a
+  single research doc, each already adjacent to the hard number carrying the fact. One marginal
+  catch does not pay for a permanent suppression, so the rule is deleted and this ADR's
+  "cherry-picked rules" is one rule, not two.
 - A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
-  500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`.
+  500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. It fails only *above*
+  500 lines, matching `skill-audit/scripts/validate.sh`'s long-standing `<= 500` pass.
 - `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
   future reader doesn't wonder if a trial tier was forgotten.
 - The styles-portability question — whether `styles/` and `.vale.ini` should move into
@@ -87,7 +108,8 @@ standing report-only tier for future candidate rules.
   not silently forgotten.
 
 **What this ADR's implementation pass did:** synced and trialed `write-good`/`alex` against the
-existing SKILL.md/agent-file corpus, cherry-picked the two low-noise rules above into
+existing SKILL.md/agent-file corpus, cherry-picked the one low-noise rule above into
 `styles/Kyberforge`, wrote `scripts/skill-size-check.sh` and its pre-commit hook, fixed the
 resulting corpus violations, and landed the rule changes and corpus fixes as one atomic commit —
-matching the enforcement model described above (no partial or opt-in state).
+matching the enforcement model described above (no partial or opt-in state), with every rule at
+`level: error` so that model is real rather than nominal.
diff --git a/plugins/bin/skills/caveman/SKILL.md b/plugins/bin/skills/caveman/SKILL.md
index 72bcd66..85770a3 100644
--- a/plugins/bin/skills/caveman/SKILL.md
+++ b/plugins/bin/skills/caveman/SKILL.md
@@ -15,12 +15,7 @@ ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drif
 
 ## Rules
 
-<!-- vale Kyberforge.VagueQualifier = NO -->
-<!-- vale Kyberforge.VagueWording = NO -->
-Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging.
-<!-- vale Kyberforge.VagueQualifier = YES -->
-<!-- vale Kyberforge.VagueWording = YES -->
-Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
 
 Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
 
diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md
index e2e9714..f7ba49d 100644
--- a/plugins/kyberforge/skills/agent-audit/SKILL.md
+++ b/plugins/kyberforge/skills/agent-audit/SKILL.md
@@ -41,7 +41,7 @@ bash scripts/validate-provenance.sh <path-to-agent-file>
 
 The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
-`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`, so it runs correctly regardless of the caller's cwd. Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in the `### Description` / `### Body` dimensions, citing the rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable.
+`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`; pass the absolute paths shown above so the invocation holds from any cwd. Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one in the `### Description` / `### Body` dimensions citing its rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 2 judgment for the dimensions it would have covered.
 
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
@@ -53,7 +53,7 @@ Read both agent files. Work through each dimension internally. Collect findings
 
 **Description (both files):**
 - Action-verb opening: description starts with a verb ("Reviews...", "Analyzes...", "Generates...") — FAIL if absent. Vale's `Kyberforge.DescriptionOpener` alert flags the specific known-bad "This agent..." opener directly; verifying an arbitrary opening word is genuinely a strong verb still requires judgment.
-- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague. Vale's `Kyberforge.VagueWording` alert covers known filler ("helps with", "utilize", ...) directly; report those without re-deriving by judgment.
+- Specificity: is the trigger condition stated precisely? — SUGGESTION if vague. Vale's `Kyberforge.VagueWording` alert covers known filler ("helps with", "utilize", ...) directly; report those as FAILs without re-deriving by judgment.
 - `Use proactively` in a Copilot description: Vale's `KyberforgeCopilot.ProactivePhrase` alert (Copilot file only) flags this directly — report it without re-deriving by judgment.
 
 If a description finding is borderline, read `references/description-quality.md`.
@@ -62,7 +62,7 @@ If a description finding is borderline, read `references/description-quality.md`
 - Direct role instruction: system prompt opens with `You are a [role]. When invoked, [action].` — SUGGESTION if absent
 - One job per agent: system prompt describes a single bounded task — SUGGESTION if scope appears unbounded
 - Generic, non-specific reference pointers to the `references/` directory: Vale's `Kyberforge.PaddingPhrase` alert flags this directly — report it without re-deriving by judgment
-- Vague filler wording and sentences that open with "There is"/"There are": Vale's `Kyberforge.VagueQualifier` and `Kyberforge.SentenceOpenerThereIs` alerts flag this directly — report them without re-deriving by judgment
+- Sentences that open with "There is"/"There are": Vale's `Kyberforge.SentenceOpenerThereIs` alert flags this directly — report it without re-deriving by judgment
 
 **Body/Frontmatter comments:**
 - Inspect each comment block in the YAML frontmatter. For each comment, apply: *"Would the agent get this wrong without this comment?"* Flag any that answer "no" as padding.
diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index 3c82a51..d05f681 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -41,7 +41,7 @@ Note any structural FAILs — they will appear in the report as a `### Structure
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
-`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`, so it runs correctly regardless of the caller's cwd, using `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns dimensions below, not a replacement for Step 3. Map `error` → `FAIL` and `warning`/`suggestion` → `SUGGESTION` in those dimensions, citing the rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable.
+`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`; pass the absolute paths shown above so the invocation holds from any cwd. It applies `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns/Body dimensions below, not a replacement for Step 3. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one citing its rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 3 judgment for the dimensions it would have covered.
 
 ## Step 2 — Read all skill files
 
@@ -53,7 +53,7 @@ Work through each dimension internally. Collect findings only; report them in St
 
 ### Description
 
-Vale's `Kyberforge.DescriptionOpener` (FAIL — "This skill..." openers) and `Kyberforge.VagueWording` (SUGGESTION — filler like "helps with", "utilize") alerts from Step 1 cover imperative phrasing and known vague-wording filler directly; report them as findings without re-deriving by judgment. The rest is still a judgment call:
+Vale's `Kyberforge.DescriptionOpener` ("This skill..." openers) and `Kyberforge.VagueWording` (filler like "helps with", "utilize") alerts from Step 1 — both FAILs — cover imperative phrasing and known vague-wording filler directly; report them as findings without re-deriving by judgment. The rest is still a judgment call:
 
 - **Specificity beyond the filler blocklist**: are capabilities stated precisely ("parses OpenAPI specs") or genuinely vaguely ("handles files")?
 - **Indirect triggers**: does it cover cases where the user doesn't name the domain directly?
@@ -70,7 +70,7 @@ For each sentence in the body, apply: *"Would the agent get this wrong without t
 - **Why rationale**: include/exclude rules explain why, not just what
 - **Control calibration**: prescriptive for fragile or critical sequences (e.g. a script invocation where flag order or exact arguments must not change); flexible where multiple approaches are valid
 
-Vale's `Kyberforge.VagueQualifier` (SUGGESTION — vague filler like "clearly", "obviously") and `Kyberforge.SentenceOpenerThereIs` (SUGGESTION — sentences starting with "There is"/"There are") alerts from Step 1 cover pattern-matchable body-wide filler directly; report them as findings without re-deriving by judgment.
+Vale's `Kyberforge.SentenceOpenerThereIs` alert from Step 1 (FAIL — sentences starting with "There is"/"There are") covers pattern-matchable body-wide filler directly; report it as a finding without re-deriving by judgment.
 
 If uncertain whether a sentence is padding or whether a control decision is correctly calibrated, read `references/body-discipline.md`.
 
diff --git a/plugins/lint/skills/vale-run/SKILL.md b/plugins/lint/skills/vale-run/SKILL.md
index c1f4915..11f443a 100644
--- a/plugins/lint/skills/vale-run/SKILL.md
+++ b/plugins/lint/skills/vale-run/SKILL.md
@@ -19,9 +19,9 @@ metadata:
 
 ## Gotchas
 
-- Vale exits non-zero whenever it finds an alert at or above `MinAlertLevel` — that's what makes it usable as a CI gate, not a sign the invocation failed. Read the output before concluding the command errored.
+- Vale's exit code is driven by `error`-level alerts only. `warning` and `suggestion` alerts are reported but still exit `0`. `MinAlertLevel` and `--minAlertLevel` control display, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to be `level: error`. This is the single most common way a Vale gate silently passes everything.
 - `vale ls-config` prints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in `.vale.ini`.
-- Inline suppression syntax is format-specific: Markdown/MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. Don't assume one syntax works across formats.
+- Inline suppression syntax is format-specific: Markdown uses HTML comments `<!-- vale off -->` / `<!-- vale on -->`, MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. The MDX form does nothing in a plain `.md` file — the alert still fires. Don't assume one syntax works across formats.
 - Before calling the `vale` binary directly, check whether the target repo documents its own wrapper script for Vale (look in its README, CONTRIBUTING docs, pre-commit config, or a `scripts/` directory). Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter fields — and calling bare `vale` in a repo that has such a wrapper silently skips whatever the wrapper works around. If a wrapper is documented, invoke it with the same arguments instead of calling `vale` directly; otherwise fall back to the default below.
 
 ## Running vale
@@ -37,8 +37,8 @@ Key flags:
 | Flag | Purpose |
 |---|---|
 | `--output=<style>` | Output format/template: `CLI` (default, human-readable), `line` (compact, one alert per line, good for grep/piping), `JSON` (for programmatic parsing), or a custom template. |
-| `--minAlertLevel=<suggestion\|warning\|error>` | Overrides `MinAlertLevel` from `.vale.ini` for this run only, without editing config. |
-| `--no-exit` | Forces exit code `0` regardless of findings. Use in CI stages that should surface lint output without hard-failing the build. |
+| `--minAlertLevel=<suggestion\|warning\|error>` | Overrides `MinAlertLevel` from `.vale.ini` for this run only, without editing config. Filters what is displayed; does not affect the exit code. |
+| `--no-exit` | Suppresses the nonzero exit that `error`-level alerts would otherwise cause; a no-op when no rule is `error`-level. Use in CI stages that should surface lint output without hard-failing the build. |
 | `--ignore-syntax` | Treats input as plain text, skipping format-aware parsing — use when a file's syntax-aware parser produces noisy or wrong results. |
 
 `vale sync` downloads the packages/styles declared in `.vale.ini` — that's a one-time-per-change setup step (vale-config's territory), not part of a normal lint run. If a run behaves as though no styles are active, that's a sign `vale sync` hasn't been run yet, not a `vale-run` problem.
@@ -49,14 +49,15 @@ Prefer `--output=JSON` whenever the caller (a script, a CI step, another agent)
 
 Scope the fix as narrowly as possible, in this order:
 
-1. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
-2. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}` ... `= YES`), rather than the whole rule.
-3. **Known project term failing spell check**: add it to the style's `ignore` list, not an inline suppression.
+1. **Mentioning banned phrasing rather than using it**: wrap it in backticks or a fenced code block. Vale skips code spans and fences, so no suppression is needed at all. Try this before any suppression markup.
+2. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup.
+3. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->` ... `= YES`), rather than the whole rule.
+4. **Known project term failing spell check**: add it to the style's `ignore` list, not an inline suppression.
 
 Never disable a rule project-wide to fix one false positive — editing `.vale.ini`/`BasedOnStyles` is vale-config's job, and it silences the rule everywhere, not just the false-positive case.
 
 If output looks wrong because Vale mis-parsed a file's format, rerun with `--ignore-syntax` before assuming the rule itself is broken.
 
-For CI that fails solely because Vale returned non-zero on found alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule.
+For CI that fails solely because Vale returned non-zero on `error`-level alerts — not because the content is wrong for that pipeline stage — add `--no-exit` rather than disabling the rule. If the failing alerts are warnings or suggestions, Vale is not what failed the build; look elsewhere.
 
 If setting up Vale as a pre-commit hook or need the full inline-suppression/spelling-ignore syntax reference, read `references/troubleshooting.md`.
diff --git a/plugins/lint/skills/vale-run/references/troubleshooting.md b/plugins/lint/skills/vale-run/references/troubleshooting.md
index 326dde7..093280f 100644
--- a/plugins/lint/skills/vale-run/references/troubleshooting.md
+++ b/plugins/lint/skills/vale-run/references/troubleshooting.md
@@ -7,7 +7,14 @@ source_keys:
 
 ## Inline suppression syntax by format
 
-Markdown/MDX:
+Markdown uses HTML comments — the MDX `{/* */}` form does not suppress anything in a plain `.md` file:
+```markdown
+<!-- vale off -->
+This text will be ignored.
+<!-- vale on -->
+```
+
+MDX:
 ```mdx
 {/* vale off */}
 This text will be ignored.
@@ -25,6 +32,14 @@ This text will be ignored.
 
 Targets one rule and specific known-exception strings, then re-enables — the preferred fix for a recurring false positive on a specific term, since it keeps the rule active everywhere else:
 
+Markdown:
+```markdown
+<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->
+This is some text ACT test
+<!-- vale Style.Redundancy["ACT test","OTHER"] = YES -->
+```
+
+MDX:
 ```mdx
 {/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
 This is some text ACT test
@@ -50,7 +65,7 @@ If a file's syntax-aware parsing produces noisy or incorrect results (an unsuppo
 
 ## CI failing unexpectedly
 
-If a CI job fails solely because Vale returns a non-zero exit code on found alerts — not because the content is actually wrong for that pipeline stage — add `--no-exit` rather than suppressing the rule itself. This preserves the lint output while not gating the build on it.
+Only `error`-level alerts make Vale exit non-zero; `warning` and `suggestion` alerts are printed but exit `0`. If a CI job fails solely because of `error`-level alerts — not because the content is actually wrong for that pipeline stage — add `--no-exit` rather than suppressing the rule itself. This preserves the lint output while not gating the build on it. If the alerts are warnings or suggestions, Vale did not fail the job — look elsewhere.
 
 ## pre-commit integration
 
diff --git a/scripts/skill-size-check.sh b/scripts/skill-size-check.sh
index e137a7c..696f4fa 100755
--- a/scripts/skill-size-check.sh
+++ b/scripts/skill-size-check.sh
@@ -1,11 +1,18 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Enforces agentskills.io's skill-authoring.md guidance: keep SKILL.md under 500
-# lines and roughly 5,000 tokens, so the full body doesn't crowd out conversation
-# history and other active skills once loaded into context. Vale can't express
-# a whole-file length ceiling (its checks operate on text patterns, not raw
-# file size), so this is a plain script instead of a Vale rule.
+# Enforces agentskills.io's skill-authoring.md guidance: keep SKILL.md within
+# 500 lines and roughly 5,000 tokens, so the full body doesn't crowd out
+# conversation history and other active skills once loaded into context. Vale
+# can't express a whole-file length ceiling (its checks operate on text
+# patterns, not raw file size), so this is a plain script instead of a Vale
+# rule.
+#
+# Both ceilings are inclusive: a file at exactly MAX_LINES or MAX_WORDS passes,
+# and only one past it fails. That matches skill-audit/scripts/validate.sh,
+# which has always used `line_count <= 500` as its pass condition — the two
+# previously disagreed at exactly 500 lines, so a SKILL.md could pass its own
+# audit and still be blocked by the commit hook.
 #
 # Token counts aren't computed exactly here — word count (`wc -w`) is used as
 # a proxy. This repo's own SKILL.md corpus measures ~5.7-6.5 characters per
@@ -26,8 +33,8 @@ for f in "$@"; do
   # Python's splitlines() semantics (used by skill-audit/scripts/validate.sh
   # for its own line count) — `wc -l` undercounts by 1 in that case.
   lines=$(awk 'END{print NR}' "$f")
-  if (( lines >= MAX_LINES )); then
-    echo "ERROR: $f has $lines lines, at or over the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2
+  if (( lines > MAX_LINES )); then
+    echo "ERROR: $f has $lines lines, exceeding the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2
     FAIL=1
   fi
 
diff --git a/scripts/vale-wrap.sh b/scripts/vale-wrap.sh
index 64ee5f5..918f32e 100755
--- a/scripts/vale-wrap.sh
+++ b/scripts/vale-wrap.sh
@@ -8,56 +8,104 @@ set -euo pipefail
 # (padding with blank lines so every other line number is unchanged), then runs
 # the real `vale` binary against the copies. Drop-in replacement for calling
 # `vale` directly: same args, same exit code.
+#
+# "Same args" means relative paths — `--config` values and file arguments alike
+# — resolve against the caller's current directory, exactly as bare `vale`
+# resolves them. (An earlier version resolved them against the repo root, an
+# invented convention that hard-errored on `--config ../../.vale.ini` from a
+# subdirectory and, worse, silently dropped file arguments that didn't happen to
+# resolve from the repo root — skipping the flattening this script exists for.)
+#
+# Vale prints each file path exactly as it was handed to it, so the scratch tree
+# mirrors the caller's absolute cwd: a relative file argument is passed through
+# verbatim and resolves to its flattened copy, keeping the report byte-identical
+# to bare `vale`'s. An absolute file argument inside the cwd is relativized to
+# keep that property. Only an absolute path outside the cwd is rewritten to its
+# scratch copy and so reports a scratch path — unavoidable, since a file can
+# only be read from where it actually is.
 
-repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cwd="$(pwd -P)"
 
 vale_args=()
-files=()
+file_args=()
 config_next=false
 for arg in "$@"; do
   if [[ "$config_next" == true ]]; then
+    config_next=false
     if [[ "$arg" == /* ]]; then
       vale_args+=("$arg")
     else
-      vale_args+=("$repo_root/$arg")
+      vale_args+=("$cwd/$arg")
     fi
-    config_next=false
     continue
   fi
-  if [[ "$arg" == "--config" ]]; then
-    vale_args+=("$arg")
-    config_next=true
-    continue
-  fi
-  if [[ "$arg" == --config=* ]]; then
-    cfg="${arg#--config=}"
-    if [[ "$cfg" == /* ]]; then
-      vale_args+=("--config=$cfg")
+  case "$arg" in
+    --config)
+      vale_args+=("$arg")
+      config_next=true
+      continue
+      ;;
+    --config=/*)
+      vale_args+=("$arg")
+      continue
+      ;;
+    --config=*)
+      vale_args+=("--config=$cwd/${arg#--config=}")
+      continue
+      ;;
+  esac
+  # `-f` resolves relative paths against the caller's cwd, same as vale does.
+  if [[ "$arg" != -* && -f "$arg" ]]; then
+    # An absolute path inside the caller's cwd is relativized so the report cites
+    # a path that resolves against the real tree. Left absolute, it would be
+    # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
+    # path to a file that is deleted on exit, which reads as a bug in any report
+    # quoting it. Absolute paths outside the cwd have no relative form and keep
+    # the scratch-path behaviour documented above.
+    if [[ "$arg" == "$cwd"/* ]]; then
+      file_args+=("${arg#"$cwd"/}")
     else
-      vale_args+=("--config=$repo_root/$cfg")
+      file_args+=("$arg")
     fi
-    continue
-  fi
-  if [[ "$arg" != -* && -f "$repo_root/$arg" ]]; then
-    files+=("$arg")
-  elif [[ "$arg" == /* && -f "$arg" && "$arg" == "$repo_root"/* ]]; then
-    files+=("${arg#"$repo_root"/}")
   else
     vale_args+=("$arg")
   fi
 done
 
-if [[ ${#files[@]} -eq 0 ]]; then
+if [[ ${#file_args[@]} -eq 0 ]]; then
+  # Nothing to flatten. Hand off directly, with stdin closed so vale doesn't
+  # block waiting on a pipe that will never carry content.
   exec vale "${vale_args[@]}" < /dev/null
 fi
 
-tmpdir="$(mktemp -d)"
+tmpdir="$(realpath -m "$(mktemp -d)")"
 trap 'rm -rf "$tmpdir"' EXIT
 
-for rel in "${files[@]}"; do
-  dest="$tmpdir/$rel"
+# Mirror of the caller's cwd inside the scratch tree; relative file arguments
+# are resolved from here.
+mirror="$tmpdir$cwd"
+mkdir -p "$mirror"
+
+argv_files=()
+for arg in "${file_args[@]}"; do
+  if [[ "$arg" == /* ]]; then
+    dest="$tmpdir$arg"
+  else
+    dest="$mirror/$arg"
+  fi
+  dest="$(realpath -m "$dest")"
+  # A file argument with enough leading `..` to climb past the mirror root would
+  # write outside the scratch dir. The real filesystem clamps such a path at
+  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
+  case "$dest" in
+    "$tmpdir"/*) ;;
+    *)
+      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
+      exit 2
+      ;;
+  esac
   mkdir -p "$(dirname "$dest")"
-  python3 - "$repo_root/$rel" "$dest" <<'PYTHON'
+  python3 - "$arg" "$dest" <<'PYTHON'
 import re
 import sys
 
@@ -118,7 +166,12 @@ if fm_match:
 with open(dest, 'w') as fh:
     fh.write(content)
 PYTHON
+  if [[ "$arg" == /* ]]; then
+    argv_files+=("$dest")
+  else
+    argv_files+=("$arg")
+  fi
 done
 
-cd "$tmpdir"
-vale "${vale_args[@]}" "${files[@]}"
+cd "$mirror"
+vale "${vale_args[@]}" "${argv_files[@]}"
diff --git a/styles/Kyberforge/PaddingPhrase.yml b/styles/Kyberforge/PaddingPhrase.yml
index 189cc66..4c5f5ae 100644
--- a/styles/Kyberforge/PaddingPhrase.yml
+++ b/styles/Kyberforge/PaddingPhrase.yml
@@ -1,6 +1,6 @@
 extends: existence
 message: "Generic reference pointer: '%s' — use the specific 'If X, read `references/file.md`' form instead"
-level: warning
+level: error
 scope: text
 ignorecase: true
 raw:
diff --git a/styles/Kyberforge/SentenceOpenerThereIs.yml b/styles/Kyberforge/SentenceOpenerThereIs.yml
index 691baf1..c443bad 100644
--- a/styles/Kyberforge/SentenceOpenerThereIs.yml
+++ b/styles/Kyberforge/SentenceOpenerThereIs.yml
@@ -1,6 +1,6 @@
 extends: existence
 message: "Don't start a sentence with '%s' — name the subject directly"
-level: warning
+level: error
 scope: sentence
 ignorecase: false
 raw:
diff --git a/styles/Kyberforge/VagueQualifier.yml b/styles/Kyberforge/VagueQualifier.yml
deleted file mode 100644
index d33bfe8..0000000
--- a/styles/Kyberforge/VagueQualifier.yml
+++ /dev/null
@@ -1,19 +0,0 @@
-extends: existence
-message: "'%s' is vague filler wording — state the point precisely instead"
-level: warning
-scope: text
-ignorecase: true
-tokens:
-  - easily
-  - everyone knows
-  - exceedingly
-  - excellent
-  - extremely
-  - huge
-  - interestingly
-  - of course
-  - quite
-  - remarkably
-  - surprisingly
-  - vast
-  - very
diff --git a/styles/Kyberforge/VagueWording.yml b/styles/Kyberforge/VagueWording.yml
index 7490aaf..45cb87f 100644
--- a/styles/Kyberforge/VagueWording.yml
+++ b/styles/Kyberforge/VagueWording.yml
@@ -1,6 +1,6 @@
 extends: existence
 message: "Vague capability wording: '%s' — state the capability precisely instead"
-level: warning
+level: error
 scope: text.frontmatter.description
 ignorecase: true
 tokens:
diff --git a/styles/KyberforgeCopilot/ProactivePhrase.yml b/styles/KyberforgeCopilot/ProactivePhrase.yml
index d23f8b7..a057bb0 100644
--- a/styles/KyberforgeCopilot/ProactivePhrase.yml
+++ b/styles/KyberforgeCopilot/ProactivePhrase.yml
@@ -1,6 +1,6 @@
 extends: existence
 message: "'%s' is CC-specific phrasing with no effect in Copilot descriptions — remove it"
-level: warning
+level: error
 scope: text.frontmatter.description
 ignorecase: true
 tokens:
diff --git a/tests/test-skill-size-check.sh b/tests/test-skill-size-check.sh
index cf7d3c8..fd98e4b 100755
--- a/tests/test-skill-size-check.sh
+++ b/tests/test-skill-size-check.sh
@@ -83,31 +83,33 @@ make_line_fixture() {
   echo "$file"
 }
 
-# The line ceiling is exclusive of the limit itself ("stay under $MAX_LINES
-# lines", per skill-authoring.md), enforced via `>=` — so $((MAX_LINES - 1))
-# must pass and $MAX_LINES itself must already fail.
+# The line ceiling is inclusive of the limit itself, enforced via `>` — so
+# exactly $MAX_LINES must pass and $((MAX_LINES + 1)) must fail. This matches
+# skill-audit/scripts/validate.sh's `line_count <= 500` pass condition; the two
+# previously disagreed at exactly $MAX_LINES lines, so a SKILL.md could pass its
+# own audit and still be blocked by the commit hook.
 echo ""
-echo "--- passes a file at $((MAX_LINES - 1)) lines, just under the $MAX_LINES-line boundary ---"
-AT_LINES="$(make_line_fixture at-line-limit "$((MAX_LINES - 1))")"
+echo "--- passes a file at exactly the $MAX_LINES-line boundary ---"
+AT_LINES="$(make_line_fixture at-line-limit "$MAX_LINES")"
 ACTUAL_LINES=$(awk 'END{print NR}' "$AT_LINES")
-if [[ "$ACTUAL_LINES" -ne "$((MAX_LINES - 1))" ]]; then
-  fail "fixture has $ACTUAL_LINES lines, expected exactly $((MAX_LINES - 1))"
+if [[ "$ACTUAL_LINES" -ne "$MAX_LINES" ]]; then
+  fail "fixture has $ACTUAL_LINES lines, expected exactly $MAX_LINES"
 elif "$SCRIPT" "$AT_LINES"; then
-  pass "file at $((MAX_LINES - 1)) lines exits 0"
+  pass "file at exactly $MAX_LINES lines exits 0"
 else
-  fail "file at $((MAX_LINES - 1)) lines should have exited 0"
+  fail "file at exactly $MAX_LINES lines should have exited 0 (the off-by-one this test guards against)"
 fi
 
 echo ""
-echo "--- fails a file at exactly the $MAX_LINES-line boundary ---"
-OVER_LINES="$(make_line_fixture over-line-limit "$MAX_LINES")"
+echo "--- fails a file one line over the $MAX_LINES-line boundary ---"
+OVER_LINES="$(make_line_fixture over-line-limit "$((MAX_LINES + 1))")"
 ACTUAL_OVER_LINES=$(awk 'END{print NR}' "$OVER_LINES")
-if [[ "$ACTUAL_OVER_LINES" -ne "$MAX_LINES" ]]; then
-  fail "fixture has $ACTUAL_OVER_LINES lines, expected exactly $MAX_LINES"
+if [[ "$ACTUAL_OVER_LINES" -ne "$((MAX_LINES + 1))" ]]; then
+  fail "fixture has $ACTUAL_OVER_LINES lines, expected exactly $((MAX_LINES + 1))"
 elif "$SCRIPT" "$OVER_LINES" 2>/dev/null; then
-  fail "file at exactly $MAX_LINES lines should have exited non-zero (>= ceiling, the boundary bug this test guards against)"
+  fail "file at $((MAX_LINES + 1)) lines should have exited non-zero"
 else
-  pass "file at exactly $MAX_LINES lines exits non-zero"
+  pass "file at $((MAX_LINES + 1)) lines exits non-zero"
 fi
 
 # make_word_fixture builds a file with an exact total word count (frontmatter
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index 2f144e0..c40b09b 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -39,13 +39,24 @@ make_fixture() {
   echo "$dir"
 }
 
+# Every Kyberforge rule is `level: error`, so vale exits non-zero whenever a
+# fixture trips one — which is the expected outcome for nearly every case here.
+# run_wrap therefore captures output and swallows the exit status; assertions
+# are made on the report text. Cases that genuinely care about the exit code
+# capture it explicitly instead.
+run_wrap() {
+  local dir="$1"
+  shift
+  (cd "$dir" && bash "$SCRIPT" "$@" 2>&1) || true
+}
+
 # --- 1. A known-bad single-line description is caught (sanity check on Vale itself) ---
 echo ""
 echo "--- catches vague wording in a single-line description ---"
 FIXTURE1="$(make_fixture 1)"
 trap 'rm -rf "$FIXTURE1"' EXIT
-if (cd "$FIXTURE1" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
-  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+if run_wrap "$FIXTURE1" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when description is a single physical line"
 else
   fail "did not flag known-bad single-line description"
@@ -56,8 +67,8 @@ echo ""
 echo "--- catches vague wording in a multi-line folded description ---"
 FIXTURE2="$(make_fixture 2)"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2"' EXIT
-if (cd "$FIXTURE2" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
-  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+if run_wrap "$FIXTURE2" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when description spans 2+ physical lines"
 else
   fail "silently missed known-bad wording in a multi-line description — the bug this test guards against"
@@ -69,8 +80,8 @@ echo "--- preserves total line count when flattening ---"
 FIXTURE3="$(make_fixture 3)"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3"' EXIT
 ORIG_LINES=$(wc -l < "$FIXTURE3/plugins/testplugin/skills/zzzskill/SKILL.md")
-OUT=$(cd "$FIXTURE3" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
-  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1 || true)
+OUT=$(run_wrap "$FIXTURE3" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md)
 MAX_LINE=$(echo "$OUT" | grep -oE '^[[:space:]]*[0-9]+:[0-9]+' | tr -d '[:space:]' | cut -d: -f1 | sort -n | tail -1)
 if [[ -n "$MAX_LINE" ]] && (( MAX_LINE <= ORIG_LINES )); then
   pass "reported line numbers stay within the original file's line count"
@@ -107,8 +118,8 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
-if (cd "$FIXTURE4" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
-  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+if run_wrap "$FIXTURE4" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when the description contains a double quote"
 else
   fail "silently missed vague wording in a description containing a double quote — the bug this test guards against"
@@ -129,8 +140,8 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
-OUT5=$(cd "$FIXTURE5" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
-  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1)
+OUT5=$(run_wrap "$FIXTURE5" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md)
 if echo "$OUT5" | grep -q "VagueWording"; then
   pass "flags vague wording when the description contains an apostrophe"
 else
@@ -157,8 +168,8 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6"' EXIT
-if (cd "$FIXTURE6" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
-  plugins/testplugin/skills/zzzskill/SKILL.md) | grep -q "VagueWording"; then
+if run_wrap "$FIXTURE6" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when the description has a backslash and non-ASCII text"
 else
   fail "silently missed vague wording in a description with a backslash and non-ASCII text"
@@ -180,8 +191,8 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7"' EXIT
-OUT7=$(cd "$FIXTURE7" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" \
-  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1)
+OUT7=$(run_wrap "$FIXTURE7" --config "$REPO_ROOT/.vale.ini" \
+  plugins/testplugin/skills/zzzskill/SKILL.md)
 if echo "$OUT7" | grep -q "Traceback"; then
   fail "crashed while flattening a description with a blank line between paragraphs"
 elif echo "$OUT7" | grep -q "VagueWording"; then
@@ -190,9 +201,16 @@ else
   fail "silently missed vague wording in the second paragraph after a blank line — the bug this test guards against"
 fi
 
-# --- 8. --config=<path> (equals form) resolves the same as the two-argv form ---
+# --- 8. Relative paths resolve against the caller's cwd, exactly as bare vale
+# resolves them. Every path below is deliberately relative to $SUBDIR8, not to
+# the fixture's repo root: an earlier version of the wrapper resolved relative
+# paths against the git toplevel instead, which (a) hard-errored on a
+# `--config ../../..` that bare vale accepts and (b) silently dropped file
+# arguments that didn't resolve from the repo root, skipping the flattening the
+# wrapper exists to perform. The old tests only ever passed repo-root-relative
+# paths from a subdirectory, so neither failure mode was caught.
 echo ""
-echo "--- --config=<path> equals form resolves from a subdirectory like the two-argv form ---"
+echo "--- resolves a cwd-relative --config from a subdirectory (equals and two-argv forms) ---"
 FIXTURE8="$(mktemp -d)"
 (cd "$FIXTURE8" && git init -q)
 cp "$REPO_ROOT/.vale.ini" "$FIXTURE8/.vale.ini"
@@ -210,13 +228,53 @@ mkdir -p "$FIXTURE8/plugins/testplugin/skills/zzzskill"
 } > "$FIXTURE8/plugins/testplugin/skills/zzzskill/SKILL.md"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8"' EXIT
 SUBDIR8="$FIXTURE8/plugins/testplugin/skills/zzzskill"
-REL8="plugins/testplugin/skills/zzzskill/SKILL.md"
-OUT_EQ=$(cd "$SUBDIR8" && bash "$SCRIPT" --config=.vale.ini "$REL8" 2>&1)
-OUT_TWO=$(cd "$SUBDIR8" && bash "$SCRIPT" --config .vale.ini "$REL8" 2>&1)
+# Both paths are relative to $SUBDIR8 (four levels below the fixture root).
+REL_CFG8="../../../../.vale.ini"
+REL_FILE8="SKILL.md"
+OUT_EQ=$(run_wrap "$SUBDIR8" "--config=$REL_CFG8" "$REL_FILE8")
+OUT_TWO=$(run_wrap "$SUBDIR8" --config "$REL_CFG8" "$REL_FILE8")
 if echo "$OUT_EQ" | grep -q "VagueWording" && [[ "$OUT_EQ" == "$OUT_TWO" ]]; then
-  pass "--config=<path> from a subdirectory resolves and matches the two-argv form"
+  pass "cwd-relative --config resolves from a subdirectory in both argv forms"
 else
-  fail "--config=<path> equals form did not resolve the same as the two-argv form"
+  fail "cwd-relative --config did not resolve from a subdirectory (equals form vs two-argv form)"
+fi
+
+# --- 8b. A cwd-relative --config matches the equivalent absolute invocation ---
+# Regression for failure mode (a): resolving --config against the repo root made
+# `--config ../../../../.vale.ini` expand to a path above the toplevel, and vale
+# hard-errored with "does not exist" (exit 2) on args bare vale handles fine.
+echo ""
+echo "--- a cwd-relative --config produces the same result as the absolute-path form ---"
+set +e
+OUT_REL_CFG=$(cd "$SUBDIR8" && bash "$SCRIPT" --config "$REL_CFG8" "$REL_FILE8" 2>&1)
+RC_REL_CFG=$?
+OUT_ABS_CFG=$(cd "$SUBDIR8" && bash "$SCRIPT" --config "$FIXTURE8/.vale.ini" "$REL_FILE8" 2>&1)
+RC_ABS_CFG=$?
+set -e
+if echo "$OUT_REL_CFG" | grep -qi "does not exist"; then
+  fail "cwd-relative --config hard-errored ('does not exist') — the bug this test guards against"
+elif [[ "$OUT_REL_CFG" == "$OUT_ABS_CFG" && "$RC_REL_CFG" -eq "$RC_ABS_CFG" ]]; then
+  pass "cwd-relative --config matches the absolute-path invocation (output and exit code)"
+else
+  fail "cwd-relative --config (rc=$RC_REL_CFG) diverged from the absolute-path form (rc=$RC_ABS_CFG)"
+fi
+
+# --- 8c. A cwd-relative FILE argument is still flattened, not silently skipped ---
+# Regression for failure mode (b): a relative file path that didn't resolve from
+# the repo root failed the wrapper's file test, fell through to the vale flag
+# list, and left the file list empty — so the wrapper exec'd bare vale and
+# silently skipped the flattening. Bare vale reports nothing here, so asserting
+# on the alert (not just the exit code) is what makes the silence detectable.
+echo ""
+echo "--- flattens a cwd-relative file argument passed from a subdirectory ---"
+WRAPPED_REL=$(run_wrap "$SUBDIR8" --config "$FIXTURE8/.vale.ini" "$REL_FILE8")
+BARE_REL=$(cd "$SUBDIR8" && vale --config "$FIXTURE8/.vale.ini" "$REL_FILE8" 2>&1 || true)
+if ! echo "$WRAPPED_REL" | grep -q "VagueWording"; then
+  fail "cwd-relative file argument produced no alert — flattening was silently skipped, the bug this test guards against"
+elif echo "$BARE_REL" | grep -q "VagueWording"; then
+  fail "bare vale already flags this fixture, so the test can't detect a silently-skipped flattening"
+else
+  pass "cwd-relative file argument is flattened and flagged where bare vale reports nothing"
 fi
 
 # --- 9. Zero file args (or a file list that filters to nothing) exits promptly ---
@@ -252,10 +310,10 @@ echo "--- lints an absolute path to a skill file instead of silently skipping it
 FIXTURE10="$(make_fixture 2)"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10"' EXIT
 ABS_FILE10="$FIXTURE10/plugins/testplugin/skills/zzzskill/SKILL.md"
-if (cd "$FIXTURE10" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" "$ABS_FILE10") | grep -q "VagueWording"; then
-  pass "an absolute path under repo_root is linted, not silently skipped"
+if run_wrap "$FIXTURE10" --config "$REPO_ROOT/.vale.ini" "$ABS_FILE10" | grep -q "VagueWording"; then
+  pass "an absolute path is linted, not silently skipped"
 else
-  fail "an absolute path under repo_root was silently skipped — the bug this test guards against"
+  fail "an absolute path was silently skipped — the bug this test guards against"
 fi
 
 # --- 11. A literal (|) block scalar passes through unflattened (no regression) ---
@@ -274,7 +332,7 @@ EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11"' EXIT
 REL11="plugins/testplugin/skills/zzzskill/SKILL.md"
-WRAPPED_OUT=$(cd "$FIXTURE11" && bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" "$REL11" 2>&1 || true)
+WRAPPED_OUT=$(run_wrap "$FIXTURE11" --config "$REPO_ROOT/.vale.ini" "$REL11")
 BARE_OUT=$(cd "$FIXTURE11" && vale --config "$REPO_ROOT/.vale.ini" "$REL11" 2>&1 || true)
 if [[ "$WRAPPED_OUT" == "$BARE_OUT" ]]; then
   pass "literal (|) block scalar output matches bare vale exactly — untouched by flattening"
-- 
2.43.0


From aff5b6c4c8422ce97abbb5fffae7a99ec2239deb Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sat, 8 Aug 2026 20:45:13 +0000
Subject: [PATCH 15/45] chore(plugins): patch-bump bin, kyberforge and lint for
 shipped content changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The round-3 fixes changed shipped skill content in three plugins without
touching their manifests, so installed copies would keep serving the old
content from cache. plugin-author requires a patch bump for exactly this
reason: consumers use the version to detect changes.

It matters most for lint — anyone installed at 1.1.2 has a cached
vale-run/SKILL.md stating that Vale exits non-zero on warnings, which is
backwards and would lead them to build a gate that passes everything.

- bin        1.1.0 -> 1.1.1  (caveman: suppression comments removed)
- kyberforge 1.2.3 -> 1.2.4  (skill-audit/agent-audit: Vale step reworked)
- lint       1.1.2 -> 1.1.3  (vale-run: exit-code and suppression-syntax fixes)

Marketplace entries carry no per-plugin version, so both marketplace.json
files are unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 plugins/bin/.claude-plugin/plugin.json        | 2 +-
 plugins/bin/plugin.json                       | 2 +-
 plugins/kyberforge/.claude-plugin/plugin.json | 2 +-
 plugins/kyberforge/plugin.json                | 2 +-
 plugins/lint/.claude-plugin/plugin.json       | 2 +-
 plugins/lint/plugin.json                      | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/plugins/bin/.claude-plugin/plugin.json b/plugins/bin/.claude-plugin/plugin.json
index 490b0ca..e2808ac 100644
--- a/plugins/bin/.claude-plugin/plugin.json
+++ b/plugins/bin/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "bin",
-  "version": "1.1.0"
+  "version": "1.1.1"
 }
diff --git a/plugins/bin/plugin.json b/plugins/bin/plugin.json
index b0be24c..e02f8dd 100644
--- a/plugins/bin/plugin.json
+++ b/plugins/bin/plugin.json
@@ -11,5 +11,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.1.0"
+  "version": "1.1.1"
 }
diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json
index 8a5badf..67751f2 100644
--- a/plugins/kyberforge/.claude-plugin/plugin.json
+++ b/plugins/kyberforge/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.2.3"
+  "version": "1.2.4"
 }
diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json
index f540bc0..8568a8f 100644
--- a/plugins/kyberforge/plugin.json
+++ b/plugins/kyberforge/plugin.json
@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.2.3"
+  "version": "1.2.4"
 }
diff --git a/plugins/lint/.claude-plugin/plugin.json b/plugins/lint/.claude-plugin/plugin.json
index d186f5f..a7c8ec4 100644
--- a/plugins/lint/.claude-plugin/plugin.json
+++ b/plugins/lint/.claude-plugin/plugin.json
@@ -13,5 +13,5 @@
   ],
   "license": "MIT",
   "name": "lint",
-  "version": "1.1.2"
+  "version": "1.1.3"
 }
diff --git a/plugins/lint/plugin.json b/plugins/lint/plugin.json
index 453ee26..a531652 100644
--- a/plugins/lint/plugin.json
+++ b/plugins/lint/plugin.json
@@ -18,5 +18,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.1.2"
+  "version": "1.1.3"
 }
-- 
2.43.0


From 864e7c689c0342a7fb73f9de9bc5c9152ec3df40 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sat, 8 Aug 2026 20:54:19 +0000
Subject: [PATCH 16/45] docs(lessons): record three patterns from PR #85's
 review rounds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three rounds of review on the Vale prefilter surfaced patterns worth
keeping rather than just fixing.

The first has now recurred three times in a single PR — a check reporting
success because it had silently not run — so it is flagged as a
graduation candidate per LESSONS.md's own three-instance rule.

- A clean linter result can mean "nothing was checked": the frontmatter
  scope silently not matching, warning-level rules never affecting an
  exit code, and globs matching zero files all produced green results
  that were then cited as evidence of cleanliness.
- One signal, two consumers, no named distinction: Vale severities were
  tuned for the audit report while the commit gate silently inherited the
  resulting exit code, because CONTEXT.md described both as one mechanism.
- Measure a rule's false-positive rate at the severity you will ship it
  at: VagueQualifier was trialled at warning, where a false positive is
  free, and shipped at error, where it costs a blocked commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 LESSONS.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/LESSONS.md b/LESSONS.md
index b81c9d8..7925c4e 100644
--- a/LESSONS.md
+++ b/LESSONS.md
@@ -137,3 +137,15 @@ After a PR merge (with Gitea's default auto-delete-branch behavior), `git branch
 ## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts
 
 During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction.
+
+## 2026-08-08 — A clean linter result can mean "nothing was checked"
+
+Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **Graduation candidate:** three instances of one pattern.
+
+## 2026-08-08 — One signal, two consumers, no named distinction
+
+Vale's output fed two consumers with different contracts: the audit skills read severity *strings* to grade a report (`error`→FAIL, `warning`→SUGGESTION), while the pre-commit hook read the process *exit code* to allow or block a commit. Severities were tuned for the first consumer; the second silently inherited whatever exit code that produced, which was always 0. CONTEXT.md described both as a single mechanism under one heading, which is precisely why the divergence went unnoticed — there was no vocabulary in which "the gate" and "the prefilter" were different things that could disagree. Fix: when one output feeds two consumers, name them separately in the domain language and state each contract explicitly. If they cannot be given independent contracts, collapse them into one — which is what happened here: every rule became `level: error`, so the gate and the audit now share a single verdict with nothing to keep in sync.
+
+## 2026-08-08 — Measure a rule's false-positive rate at the severity you will ship it at
+
+`Kyberforge.VagueQualifier` was cherry-picked from `write-good` after being trialled as "low-noise against this repo's corpus" — but the trial ran at `level: warning`, where a false positive costs nothing because nobody ever sees it. Shipped at `error`, the same false positive costs a blocked commit and a permanent suppression comment. Re-measured at the severity it actually shipped at, the rule scored one marginal true positive and one unfixable false positive across 41 files (`caveman/SKILL.md` *quotes* filler words as its subject matter — a mention, not a use), and was deleted. Fix: trial conditions must match shipping conditions. A noise measurement taken where false positives are free does not transfer to a context where they are expensive, and "low-noise" is not a property of a rule alone — it is a property of the rule at a severity.
-- 
2.43.0


From 1164f3abad56a0c5fc86febc50257717ee6621f6 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 10:04:19 +0000
Subject: [PATCH 17/45] fix(lint): make Vale prefilter portable via the plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

skill-audit/agent-audit's Step 1 resolved vale-wrap.sh/.vale.ini via
`git rev-parse --show-toplevel`, which returns whichever repo the skill
happens to run in. Inside ai-development that works; in any external repo
that installs kyberforge@holocron as a plugin, it resolves to that repo's
own root, which has no .vale.ini — the prefilter silently fell back to
full LLM judgment. ADR-0013 named this as a deliberately deferred gap.

Vale's config/styles/wrapper now ship inside the plugin itself: a
canonical copy in agent-audit/assets/vale/ (Kyberforge + KyberforgeCopilot,
the superset agent-audit needs) and a smaller duplicate in
skill-audit/assets/vale/ (Kyberforge only) — per the no-cross-skill-path
rule already established for plugin cache-installs. Both skills resolve
these relative to their own directory, same as scripts/validate.sh
already does.

A new root .pre-commit-hooks.yaml exposes both copies plus
skill-size-check so any external repo can enforce the same rules via
`repo: <this-repo-url>, rev: <tag>` in its own pre-commit config,
independent of Claude Code entirely — the same mechanism covers CI. This
repo's own pre-commit hook now consumes the identical plugin-bundled
copies via repo: local (not a third root copy, and not a pinned
self-reference, which would lint working-tree edits against the last
tagged release instead of the change being made). Split into
vale-audit-prefilter-skill/-agent hooks after confirming, by diffing the
full corpus against both old and new config before deleting the old
files, that one combined hook pointed at only one copy silently 0-file-
skips the other file type.

scripts/check-vale-style-sync.sh guards the two copies against drift,
wired at pre-push alongside check-manifests.

ADR: 0014
---
 .pre-commit-config.yaml                       |  28 ++-
 .pre-commit-hooks.yaml                        |  20 ++
 AGENTS.md                                     |   2 +-
 CONTEXT.md                                    |   6 +-
 LESSONS.md                                    |   4 +-
 ...14-vale-prefilter-ships-from-the-plugin.md |  99 ++++++++++
 plugins/kyberforge/.claude-plugin/plugin.json |   2 +-
 plugins/kyberforge/plugin.json                |   2 +-
 .../kyberforge/skills/agent-audit/SKILL.md    |   4 +-
 .../skills/agent-audit/assets/vale/.vale.ini  |   3 -
 .../styles}/Kyberforge/DescriptionOpener.yml  |   0
 .../vale/styles}/Kyberforge/PaddingPhrase.yml |   0
 .../Kyberforge/SentenceOpenerThereIs.yml      |   0
 .../vale/styles}/Kyberforge/VagueWording.yml  |   0
 .../KyberforgeCopilot/ProactivePhrase.yml     |   0
 .../skills/agent-audit/scripts}/vale-wrap.sh  |   0
 .../kyberforge/skills/skill-audit/SKILL.md    |   4 +-
 .../skills/skill-audit/assets/vale/.vale.ini  |   4 +
 .../styles/Kyberforge/DescriptionOpener.yml   |   7 +
 .../vale/styles/Kyberforge/PaddingPhrase.yml  |   7 +
 .../Kyberforge/SentenceOpenerThereIs.yml      |   7 +
 .../vale/styles/Kyberforge/VagueWording.yml   |  10 +
 .../skills/skill-audit/scripts/vale-wrap.sh   | 177 ++++++++++++++++++
 scripts/check-vale-style-sync.sh              |  35 ++++
 tests/test-check-vale-style-sync.sh           |  91 +++++++++
 tests/test-vale-wrap.sh                       |  35 ++--
 26 files changed, 513 insertions(+), 34 deletions(-)
 create mode 100644 .pre-commit-hooks.yaml
 create mode 100644 docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
 rename .vale.ini => plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini (75%)
 rename {styles => plugins/kyberforge/skills/agent-audit/assets/vale/styles}/Kyberforge/DescriptionOpener.yml (100%)
 rename {styles => plugins/kyberforge/skills/agent-audit/assets/vale/styles}/Kyberforge/PaddingPhrase.yml (100%)
 rename {styles => plugins/kyberforge/skills/agent-audit/assets/vale/styles}/Kyberforge/SentenceOpenerThereIs.yml (100%)
 rename {styles => plugins/kyberforge/skills/agent-audit/assets/vale/styles}/Kyberforge/VagueWording.yml (100%)
 rename {styles => plugins/kyberforge/skills/agent-audit/assets/vale/styles}/KyberforgeCopilot/ProactivePhrase.yml (100%)
 rename {scripts => plugins/kyberforge/skills/agent-audit/scripts}/vale-wrap.sh (100%)
 create mode 100644 plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini
 create mode 100644 plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
 create mode 100644 plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
 create mode 100644 plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
 create mode 100644 plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml
 create mode 100755 plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
 create mode 100755 scripts/check-vale-style-sync.sh
 create mode 100755 tests/test-check-vale-style-sync.sh

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index ad1a9d6..3a7e01b 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -61,6 +61,15 @@ repos:
         pass_filenames: false
         always_run: true
 
+      - id: check-vale-style-sync
+        name: Check Vale style copies are in sync
+        description: Diff skill-audit's Vale copy against agent-audit's canonical copy
+        entry: bash scripts/check-vale-style-sync.sh
+        language: system
+        stages: [pre-push]
+        pass_filenames: false
+        always_run: true
+
       - id: validate-plugins
         name: Validate plugins
         description: Run claude plugin validate --strict on every plugin directory
@@ -107,13 +116,22 @@ repos:
         files: '^plugins/[^/]+/skills/[^/]+/SKILL\.md$'
         pass_filenames: true
 
-      - id: vale-audit-prefilter
+      - id: vale-audit-prefilter-skill
         stages: ['pre-commit']
-        name: Vale audit prefilter
-        description: Run Vale against skill/agent markdown files as a deterministic prefilter for skill-audit/agent-audit
-        entry: scripts/vale-wrap.sh --config .vale.ini
+        name: Vale audit prefilter (SKILL.md)
+        description: Run Vale against SKILL.md files as a deterministic prefilter for skill-audit, via skill-audit's own bundled copy
+        entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini
         language: script
-        files: '^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$'
+        files: '^plugins/[^/]+/skills/[^/]+/SKILL\.md$'
+        pass_filenames: true
+
+      - id: vale-audit-prefilter-agent
+        stages: ['pre-commit']
+        name: Vale audit prefilter (agent files)
+        description: Run Vale against agent markdown files as a deterministic prefilter for agent-audit, via agent-audit's own bundled copy
+        entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini
+        language: script
+        files: '^plugins/[^/]+/agents/[^/]+\.md$'
         pass_filenames: true
 
   - repo: meta
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
new file mode 100644
index 0000000..4ad76d9
--- /dev/null
+++ b/.pre-commit-hooks.yaml
@@ -0,0 +1,20 @@
+-   id: kyberforge-vale-audit-skill
+    name: Kyberforge Vale prose audit (SKILL.md)
+    description: Deterministic prose-pattern prefilter for kyberforge's skill-audit, via its own bundled Vale config/styles
+    entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini
+    language: script
+    files: '(^|/)SKILL\.md$'
+
+-   id: kyberforge-vale-audit-agent
+    name: Kyberforge Vale prose audit (agent files)
+    description: Deterministic prose-pattern prefilter for kyberforge's agent-audit, via its own bundled Vale config/styles
+    entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini
+    language: script
+    files: '(^|/)agents/[^/]+\.md$|\.agent\.md$'
+
+-   id: kyberforge-skill-size-check
+    name: SKILL.md size ceiling
+    description: Enforce agentskills.io's 500-line/5,000-token SKILL.md size ceiling
+    entry: scripts/skill-size-check.sh
+    language: script
+    files: '(^|/)SKILL\.md$'
diff --git a/AGENTS.md b/AGENTS.md
index 5781986..995a2c1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,7 +22,7 @@ Fall back to raw shell only when no skill covers it.
 ## Setup and testing
 
 - Install git hooks via `git:pc-run`, wiring all three stages — this repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (tests, manifest check).
-- Install the `vale` binary — required by the `vale-audit-prefilter` pre-commit hook, which runs on every commit touching a `SKILL.md` or agent `.md` file. Without it the hook fails with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `styles/`, not downloaded packages.
+- Install the `vale` binary — required by the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, which run on every commit touching a `SKILL.md` or agent `.md` file. Without it the hooks fail with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `plugins/kyberforge/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (see ADR-0014).
 - Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed.
 - Pushing re-runs the full suite plus `scripts/check-manifests.sh` via the pre-push hook — same commands, so run them locally first.
 - Author commits with `git:git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you.
diff --git a/CONTEXT.md b/CONTEXT.md
index 78ae023..3667991 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -70,11 +70,11 @@ A companion skill (`core` plugin) that detects a target repo's provider-specific
 A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only (no `Edit` tool) — it flags findings, it does not rewrite prose. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
 
 ### Vale audit prefilter (skill-audit / agent-audit)
-Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so its config lives at the repo root rather than inside `plugins/lint/`: `.vale.ini` plus a custom `Kyberforge` style (`styles/Kyberforge/`) covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style (`styles/KyberforgeCopilot/`) scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check. Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
+Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
 
-Both skills' Step 1, and the `vale-audit-prefilter` pre-commit hook, call `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched; a relative `--config` path resolves against the caller's cwd, matching bare `vale`, not against the repo root. `tests/test-vale-wrap.sh` regression-tests this. `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]`, `[**/agents/*.md]`, `[**/*.agent.md]`) and do no scoping: Vale's `*` crosses `/`, so the older `plugins/*/`-prefixed globs already matched `plugins/*/docs/research/examples/**/agents/*.md` and `plugins/*/skills/*/assets/templates/SKILL.md`. Scoping comes from the pre-commit hook's `files:` regex, `^plugins/[^/]+/(skills/[^/]+/SKILL\.md|agents/[^/]+\.md)$` (single-segment, not `.*`, since pre-commit invokes it automatically against whatever staged files match rather than a manually-scoped target), and from the audit skills passing one explicit file per invocation. The path-agnostic globs also close a silent false negative: a skill outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) matched no section, so Vale reported 0 files and exited 0 — which the audits read as clean. Both audits now treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
+Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched; a relative `--config` path resolves against the caller's cwd, matching bare `vale`, not against the repo root. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` (split into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type) — and from the audit skills passing one explicit file per invocation. A skill outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) matches no glob section, so Vale reports 0 files and exits 0 — which the audits read as clean. Both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
 
-This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — failing only above 500 lines, matching `skill-audit/scripts/validate.sh`'s `<= 500` pass — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter`, so it never lints `docs/research/examples/` reference skills. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
+This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — failing only above 500 lines, matching `skill-audit/scripts/validate.sh`'s `<= 500` pass — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
 
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/LESSONS.md b/LESSONS.md
index 7925c4e..d1da2ba 100644
--- a/LESSONS.md
+++ b/LESSONS.md
@@ -140,7 +140,9 @@ During write-skill refactor, an "open thread" note (about a deferred research st
 
 ## 2026-08-08 — A clean linter result can mean "nothing was checked"
 
-Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **Graduation candidate:** three instances of one pattern.
+Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **Graduated** (4th instance below).
+
+**4th instance (2026-08-09, ADR-0014):** splitting the single root `.vale.ini` into two skill-scoped copies (skill-audit: `SKILL.md` only; agent-audit: agent files only) meant a single retargeted pre-commit hook pointed at agent-audit's copy alone would have silently scanned 0 `SKILL.md` files and exited 0 — caught only because the full corpus was dry-run against both the old and new config and the outputs diffed before the old config was deleted, not because any test asserted on file counts. Standing practice going forward: when a Vale (or any linter) config that serves multiple file-glob scopes is split or moved, dry-run the full corpus through both the old and new config and diff the outputs before removing the superseded source — a hook silently scanning 0 files looks identical to a clean pass.
 
 ## 2026-08-08 — One signal, two consumers, no named distinction
 
diff --git a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
new file mode 100644
index 0000000..2ac7ebc
--- /dev/null
+++ b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
@@ -0,0 +1,99 @@
+# Kyberforge's Vale prefilter ships from the plugin, with `.pre-commit-hooks.yaml` for external git-hook/CI enforcement
+
+**Resolves:** ADR-0013's deferred "styles-portability" consequence — `.vale.ini`/`styles/` moving
+out of the repo root was deliberately deferred there, not fixed. ADR-0013's other content
+(rule scope, `level: error` model, `SentenceOpenerThereIs`/`VagueQualifier` trial outcomes) is
+unaffected and remains in force.
+
+`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`
+that's this repo; in any external repo that installs `kyberforge@holocron` as a plugin, it's that
+repo's own root, which has no `.vale.ini` or `vale-wrap.sh`. The prefilter silently fell back to
+full LLM judgment every time outside this repo — the exact gap ADR-0013 named and deferred.
+
+## Decision
+
+**Runtime (a live Claude Code session):** the Vale config, styles, and wrapper script move into
+the plugin itself, following the no-cross-skill-path rule already established in
+`skill-author/references/deployment-modes.md` (a plugin's cache-install only copies each skill's
+own files; there is no plugin-level shared directory). `agent-audit` needs both `Kyberforge` and
+`KyberforgeCopilot` (it lints `.agent.md` files), so `plugins/kyberforge/skills/agent-audit/assets/vale/`
+is the canonical, superset copy. `skill-audit` needs a second, smaller copy
+(`plugins/kyberforge/skills/skill-audit/assets/vale/`, `Kyberforge` only) since it cannot
+reference agent-audit's copy across the skill boundary. Both skills' Step 1 now resolve
+`scripts/vale-wrap.sh`/`assets/vale/.vale.ini` relative to their own directory, the same way
+`scripts/validate.sh <skill-dir>` already does — no new resolution mechanism, just applying the
+existing one consistently.
+
+**git hooks / CI outside a Claude Code session** have no plugin cache and no
+`${CLAUDE_PLUGIN_ROOT}` — a CI runner in particular is guaranteed not to have one. The mechanism
+that works there for any consumer, with or without Claude Code installed, is pre-commit's own
+hook-repo protocol: this repo now ships a root-level `.pre-commit-hooks.yaml` exposing
+`kyberforge-vale-audit-skill`, `kyberforge-vale-audit-agent`, and `kyberforge-skill-size-check`.
+Any external repo adds `repo: <this-repo-url>, rev: <tag>` to its own `.pre-commit-config.yaml`
+and gets all three, fully decoupled from Claude Code. CI is the identical `pre-commit run
+--all-files` call, so the same manifest covers "possibly CI" from the original ask.
+
+**This repo's own dev-time gate** consumes the same plugin-bundled copies instead of a third
+root-level copy — per explicit instruction, this repo should be set up like any other consumer
+would be, not dogfood a special root-only path. The existing `repo: local` hook is retargeted
+(not removed): `entry:` now points at `plugins/kyberforge/skills/{skill-audit,agent-audit}/scripts/vale-wrap.sh`.
+`repo: local` is kept rather than switching to a pinned self-reference
+(`repo: <own-url>, rev: <tag>`) — a pinned self-reference would lint working-tree edits against
+the *last tagged release*, not the change actually being made, which is wrong for the repo that
+*is* the source of the hook. This mirrors standard practice among hook-author repos (pre-commit's
+own `pre-commit-hooks`, `shellcheck-py`): `repo: local` for self-consumption, `.pre-commit-hooks.yaml`
+for everyone else, same underlying files and commands either way.
+
+**One hook per file-scope, not one combined hook.** The old root `.vale.ini` had both the
+`[**/SKILL.md]` and `[**/agents/*.md]`/`[**/*.agent.md]` glob sections in a single file, so one
+pre-commit hook covered both. Splitting the config into two skill-scoped copies means a single
+hook entry pointed at only one copy would silently 0-file-skip the other file type. Both the
+local `.pre-commit-config.yaml` hooks and the external-facing `.pre-commit-hooks.yaml` therefore
+define separate `-skill`/`-agent` hook IDs, each with a `files:` regex matching exactly what its
+target copy's glob covers. (Confirmed empirically before deleting the root files: retargeting a
+single hook at agent-audit's copy silently scanned 0 SKILL.md files.)
+
+**Vale's `StylesPath` resolves relative to the `.vale.ini` file's own location**, confirmed
+against `docs.vale.sh/keys/stylespath` — so `--config <path-into-plugin>/.vale.ini` correctly
+finds that ini's sibling `styles/` regardless of the caller's cwd, with no extra path-juggling
+needed beyond what `vale-wrap.sh` already does for its cwd-relative `--config`/file-argument
+handling.
+
+**A sync-check catches drift between the two copies.** `scripts/check-vale-style-sync.sh` diffs
+`scripts/vale-wrap.sh` and `assets/vale/styles/Kyberforge/` between skill-audit and agent-audit
+(not `.vale.ini` — those legitimately differ, scoped to different glob sections), wired at
+`pre-push` alongside `check-manifests`. `.vale.ini` itself isn't diffed since divergence there is
+by design.
+
+**External `.pre-commit-hooks.yaml` consumers pin `rev:` to a tag, not a commit SHA.** This repo
+had no tags before this change; going forward, a `vX.Y.Z` tag is cut whenever hook-relevant files
+change, matching how every other `repo:` entry in this repo's own `.pre-commit-config.yaml`
+already pins (`v2.4.0`, `v8.21.2`, ...).
+
+## Considered options
+
+**Keep a third root-level copy, dogfooded specially (rejected).** Simpler in that this repo's own
+hook wouldn't need retargeting at all. Rejected on explicit instruction: this repo should consume
+the same portability path an external repo would, not carve out a special root-only case that
+never gets exercised the way external consumers exercise it.
+
+**Publish styles as a hosted Vale package via `Packages = <zip-url>` (deferred, not rejected).**
+Vale supports fetching a style from a direct `.zip` URL via `vale sync`, fully decoupled from
+Claude Code and from pre-commit's hook-repo protocol — usable by any repo, even ones that never
+install `kyberforge` at all. This is a larger, separate investment (a release/versioning pipeline
+for the package itself) not required to satisfy the current ask; noted here so a future reader
+doesn't wonder if it was overlooked.
+
+## Consequences
+
+- Root `.vale.ini`, `styles/`, `scripts/vale-wrap.sh` are deleted. Two copies remain:
+  `plugins/kyberforge/skills/agent-audit/assets/vale/` (canonical, superset) and
+  `plugins/kyberforge/skills/skill-audit/assets/vale/` (subset, `Kyberforge` only).
+- `plugins/kyberforge`'s `plugin.json` and `.claude-plugin/plugin.json` both patch-bump to
+  `1.2.5` for the shipped content change (per ADR-0006's version-parity invariant).
+- `tests/test-vale-wrap.sh` now exercises skill-audit's copy specifically — its fixtures are all
+  `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has the matching glob section.
+- The first `vX.Y.Z` tag is cut once this change and its tests pass, giving external
+  `.pre-commit-hooks.yaml` consumers something to pin.
diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json
index 67751f2..2a52749 100644
--- a/plugins/kyberforge/.claude-plugin/plugin.json
+++ b/plugins/kyberforge/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.2.4"
+  "version": "1.2.5"
 }
diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json
index 8568a8f..aa0e590 100644
--- a/plugins/kyberforge/plugin.json
+++ b/plugins/kyberforge/plugin.json
@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.2.4"
+  "version": "1.2.5"
 }
diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md
index f7ba49d..7d82ed4 100644
--- a/plugins/kyberforge/skills/agent-audit/SKILL.md
+++ b/plugins/kyberforge/skills/agent-audit/SKILL.md
@@ -36,12 +36,12 @@ metadata:
 ```bash
 bash scripts/validate.sh <path-to-agent-file>
 bash scripts/validate-provenance.sh <path-to-agent-file>
-"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini" <path-to-cc-file> <path-to-copilot-file>
+scripts/vale-wrap.sh --config assets/vale/.vale.ini <path-to-cc-file> <path-to-copilot-file>
 ```
 
 The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
-`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`; pass the absolute paths shown above so the invocation holds from any cwd. Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one in the `### Description` / `### Body` dimensions citing its rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 2 judgment for the dimensions it would have covered.
+`vale-wrap.sh` and `.vale.ini` ship inside this skill's own `scripts/`/`assets/` — resolve them relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one in the `### Description` / `### Body` dimensions citing its rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 2 judgment for the dimensions it would have covered.
 
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
diff --git a/.vale.ini b/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini
similarity index 75%
rename from .vale.ini
rename to plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini
index f4a9999..a93c7c8 100644
--- a/.vale.ini
+++ b/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini
@@ -1,8 +1,5 @@
 StylesPath = styles
 
-[**/SKILL.md]
-BasedOnStyles = Kyberforge
-
 [**/agents/*.md]
 BasedOnStyles = Kyberforge
 
diff --git a/styles/Kyberforge/DescriptionOpener.yml b/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
similarity index 100%
rename from styles/Kyberforge/DescriptionOpener.yml
rename to plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
diff --git a/styles/Kyberforge/PaddingPhrase.yml b/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
similarity index 100%
rename from styles/Kyberforge/PaddingPhrase.yml
rename to plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
diff --git a/styles/Kyberforge/SentenceOpenerThereIs.yml b/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
similarity index 100%
rename from styles/Kyberforge/SentenceOpenerThereIs.yml
rename to plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
diff --git a/styles/Kyberforge/VagueWording.yml b/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml
similarity index 100%
rename from styles/Kyberforge/VagueWording.yml
rename to plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml
diff --git a/styles/KyberforgeCopilot/ProactivePhrase.yml b/plugins/kyberforge/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml
similarity index 100%
rename from styles/KyberforgeCopilot/ProactivePhrase.yml
rename to plugins/kyberforge/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml
diff --git a/scripts/vale-wrap.sh b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
similarity index 100%
rename from scripts/vale-wrap.sh
rename to plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index d05f681..f0c965d 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -34,14 +34,14 @@ metadata:
 ```bash
 bash scripts/validate.sh <skill-dir>
 bash scripts/validate-provenance.sh <skill-dir>
-"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini" <skill-dir>/SKILL.md
+scripts/vale-wrap.sh --config assets/vale/.vale.ini <skill-dir>/SKILL.md
 ```
 
 Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
-`vale-wrap.sh` resolves its own path and `.vale.ini` via `git rev-parse --show-toplevel`; pass the absolute paths shown above so the invocation holds from any cwd. It applies `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns/Body dimensions below, not a replacement for Step 3. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one citing its rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 3 judgment for the dimensions it would have covered.
+`vale-wrap.sh` and `.vale.ini` ship inside this skill's own `scripts/`/`assets/` — resolve them relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. It applies `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns/Body dimensions below, not a replacement for Step 3. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one citing its rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 3 judgment for the dimensions it would have covered.
 
 ## Step 2 — Read all skill files
 
diff --git a/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini b/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini
new file mode 100644
index 0000000..b7ce2e5
--- /dev/null
+++ b/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini
@@ -0,0 +1,4 @@
+StylesPath = styles
+
+[**/SKILL.md]
+BasedOnStyles = Kyberforge
diff --git a/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
new file mode 100644
index 0000000..d978d73
--- /dev/null
+++ b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Description opens with '%s' — use an imperative 'Use when...' opener instead"
+level: error
+scope: text.frontmatter.description
+ignorecase: true
+raw:
+  - '^This (skill|agent)\b'
diff --git a/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
new file mode 100644
index 0000000..4c5f5ae
--- /dev/null
+++ b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Generic reference pointer: '%s' — use the specific 'If X, read `references/file.md`' form instead"
+level: error
+scope: text
+ignorecase: true
+raw:
+  - 'see references?/? for (more )?(info|information|details)\b'
diff --git a/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
new file mode 100644
index 0000000..c443bad
--- /dev/null
+++ b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Don't start a sentence with '%s' — name the subject directly"
+level: error
+scope: sentence
+ignorecase: false
+raw:
+  - '^There\s(is|are)\b'
diff --git a/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml
new file mode 100644
index 0000000..45cb87f
--- /dev/null
+++ b/plugins/kyberforge/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml
@@ -0,0 +1,10 @@
+extends: existence
+message: "Vague capability wording: '%s' — state the capability precisely instead"
+level: error
+scope: text.frontmatter.description
+ignorecase: true
+tokens:
+  - helps with
+  - utilize
+  - assists with
+  - used for
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
new file mode 100755
index 0000000..918f32e
--- /dev/null
+++ b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Works around a Vale limitation: the `text.frontmatter.description` NLP scope
+# silently stops matching once the `description:` value is a YAML block scalar
+# (`>`/`|`) spanning 2+ physical lines — the style used by most skills/agents in
+# this repo. Flattens the description to one physical line in a scratch copy
+# (padding with blank lines so every other line number is unchanged), then runs
+# the real `vale` binary against the copies. Drop-in replacement for calling
+# `vale` directly: same args, same exit code.
+#
+# "Same args" means relative paths — `--config` values and file arguments alike
+# — resolve against the caller's current directory, exactly as bare `vale`
+# resolves them. (An earlier version resolved them against the repo root, an
+# invented convention that hard-errored on `--config ../../.vale.ini` from a
+# subdirectory and, worse, silently dropped file arguments that didn't happen to
+# resolve from the repo root — skipping the flattening this script exists for.)
+#
+# Vale prints each file path exactly as it was handed to it, so the scratch tree
+# mirrors the caller's absolute cwd: a relative file argument is passed through
+# verbatim and resolves to its flattened copy, keeping the report byte-identical
+# to bare `vale`'s. An absolute file argument inside the cwd is relativized to
+# keep that property. Only an absolute path outside the cwd is rewritten to its
+# scratch copy and so reports a scratch path — unavoidable, since a file can
+# only be read from where it actually is.
+
+cwd="$(pwd -P)"
+
+vale_args=()
+file_args=()
+config_next=false
+for arg in "$@"; do
+  if [[ "$config_next" == true ]]; then
+    config_next=false
+    if [[ "$arg" == /* ]]; then
+      vale_args+=("$arg")
+    else
+      vale_args+=("$cwd/$arg")
+    fi
+    continue
+  fi
+  case "$arg" in
+    --config)
+      vale_args+=("$arg")
+      config_next=true
+      continue
+      ;;
+    --config=/*)
+      vale_args+=("$arg")
+      continue
+      ;;
+    --config=*)
+      vale_args+=("--config=$cwd/${arg#--config=}")
+      continue
+      ;;
+  esac
+  # `-f` resolves relative paths against the caller's cwd, same as vale does.
+  if [[ "$arg" != -* && -f "$arg" ]]; then
+    # An absolute path inside the caller's cwd is relativized so the report cites
+    # a path that resolves against the real tree. Left absolute, it would be
+    # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
+    # path to a file that is deleted on exit, which reads as a bug in any report
+    # quoting it. Absolute paths outside the cwd have no relative form and keep
+    # the scratch-path behaviour documented above.
+    if [[ "$arg" == "$cwd"/* ]]; then
+      file_args+=("${arg#"$cwd"/}")
+    else
+      file_args+=("$arg")
+    fi
+  else
+    vale_args+=("$arg")
+  fi
+done
+
+if [[ ${#file_args[@]} -eq 0 ]]; then
+  # Nothing to flatten. Hand off directly, with stdin closed so vale doesn't
+  # block waiting on a pipe that will never carry content.
+  exec vale "${vale_args[@]}" < /dev/null
+fi
+
+tmpdir="$(realpath -m "$(mktemp -d)")"
+trap 'rm -rf "$tmpdir"' EXIT
+
+# Mirror of the caller's cwd inside the scratch tree; relative file arguments
+# are resolved from here.
+mirror="$tmpdir$cwd"
+mkdir -p "$mirror"
+
+argv_files=()
+for arg in "${file_args[@]}"; do
+  if [[ "$arg" == /* ]]; then
+    dest="$tmpdir$arg"
+  else
+    dest="$mirror/$arg"
+  fi
+  dest="$(realpath -m "$dest")"
+  # A file argument with enough leading `..` to climb past the mirror root would
+  # write outside the scratch dir. The real filesystem clamps such a path at
+  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
+  case "$dest" in
+    "$tmpdir"/*) ;;
+    *)
+      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
+      exit 2
+      ;;
+  esac
+  mkdir -p "$(dirname "$dest")"
+  python3 - "$arg" "$dest" <<'PYTHON'
+import re
+import sys
+
+src, dest = sys.argv[1], sys.argv[2]
+with open(src) as fh:
+    content = fh.read()
+
+fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
+if fm_match:
+    fm = fm_match.group(2)
+    # Only `>`/`>-`/`>+` (folded) scalars break Vale's frontmatter-description
+    # scope. `|`/`|-`/`|+` (literal) scalars already work fine with bare vale,
+    # so they're deliberately left unmatched here.
+    header_m = re.search(r'^description:[ \t]*(>[+-]?)[ \t]*\n', fm, re.MULTILINE)
+    if header_m:
+        # Body capture is indentation-based and blank-line-tolerant, per YAML
+        # block-scalar rules: a blank line (any amount of whitespace) always
+        # stays inside the block; the indent is set by the first content line;
+        # the block ends at the first line indented less than that, or EOF.
+        rest = fm[header_m.end():]
+        indent = None
+        body_lines = []
+        for line in rest.splitlines(keepends=True):
+            text = line.rstrip('\n')
+            if text.strip() == '':
+                body_lines.append(line)
+                continue
+            line_indent = len(text) - len(text.lstrip(' \t'))
+            if indent is None:
+                indent = line_indent
+            elif line_indent < indent:
+                break
+            body_lines.append(line)
+        raw = ''.join(body_lines)
+        if raw.count('\n') >= 2:
+            flat = re.sub(r'\s+', ' ', raw).strip()
+            # YAML single-quoted scalars have no backslash-escape mechanism at
+            # all, so wrapping in single quotes sidesteps the backslash-escape
+            # bug entirely for embedded double quotes, backslashes, and
+            # non-ASCII text. The one YAML-spec-correct way to embed a literal
+            # apostrophe is to double it ('') — but Vale's own frontmatter
+            # scanner isn't a full YAML parser and doesn't understand that
+            # doubling: empirically, it silently truncates the value at the
+            # first ' it sees, hiding everything after it from the NLP scope
+            # (a different flavor of the same bug this whole script exists to
+            # work around). Since this copy is scratch-only and never written
+            # back, sidestep it by substituting a Unicode right single
+            # quotation mark (U+2019) for any literal apostrophe instead of
+            # doubling it — visually a smart quote, but never triggers a YAML
+            # escape sequence at all.
+            flat_q = "'" + flat.replace("'", "’") + "'"
+            pad = '\n' * raw.count('\n')
+            start = header_m.start()
+            end = header_m.end() + len(raw)
+            new_fm = fm[:start] + f'description: {flat_q}\n{pad}' + fm[end:]
+            content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
+
+with open(dest, 'w') as fh:
+    fh.write(content)
+PYTHON
+  if [[ "$arg" == /* ]]; then
+    argv_files+=("$dest")
+  else
+    argv_files+=("$arg")
+  fi
+done
+
+cd "$mirror"
+vale "${vale_args[@]}" "${argv_files[@]}"
diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh
new file mode 100755
index 0000000..ac7d35e
--- /dev/null
+++ b/scripts/check-vale-style-sync.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Kyberforge's Vale prefilter is duplicated into skill-audit and agent-audit's own
+# scripts/assets (per plugins/kyberforge/skills/skill-author/references/deployment-modes.md's
+# no-cross-skill-path rule: a plugin's cache-install copy only includes each skill's own files).
+# agent-audit's copy is canonical — it's the superset (Kyberforge + KyberforgeCopilot) that the
+# repo root's own pre-commit hook and .pre-commit-hooks.yaml both consume. This fails the build
+# if skill-audit's copy has drifted from it, since nothing else would catch a rule fix landing in
+# only one of the two. Run from repo root or pass REPO_ROOT as arg.
+
+REPO_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+FAIL=0
+
+err() { echo "  FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+SKILL_AUDIT="$REPO_ROOT/plugins/kyberforge/skills/skill-audit"
+AGENT_AUDIT="$REPO_ROOT/plugins/kyberforge/skills/agent-audit"
+
+if [[ ! -d "$SKILL_AUDIT" || ! -d "$AGENT_AUDIT" ]]; then
+  exit 0
+fi
+
+if ! diff -q "$SKILL_AUDIT/scripts/vale-wrap.sh" "$AGENT_AUDIT/scripts/vale-wrap.sh" >/dev/null 2>&1; then
+  err "scripts/vale-wrap.sh differs between skill-audit and agent-audit"
+fi
+
+if ! diff -rq "$SKILL_AUDIT/assets/vale/styles/Kyberforge" "$AGENT_AUDIT/assets/vale/styles/Kyberforge" >/dev/null 2>&1; then
+  err "assets/vale/styles/Kyberforge differs between skill-audit and agent-audit"
+fi
+
+if [[ $FAIL -gt 0 ]]; then
+  echo "Vale style sync check failed: $FAIL error(s). agent-audit's copy is canonical — sync skill-audit's copy to match." >&2
+  exit 1
+fi
diff --git a/tests/test-check-vale-style-sync.sh b/tests/test-check-vale-style-sync.sh
new file mode 100755
index 0000000..d822e4b
--- /dev/null
+++ b/tests/test-check-vale-style-sync.sh
@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="$REPO_ROOT/scripts/check-vale-style-sync.sh"
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# Helper: make a fixture repo with skill-audit/agent-audit's Vale copies, in sync by default.
+make_fixture() {
+  local dir
+  dir="$(mktemp -d)"
+  local skill_audit="$dir/plugins/kyberforge/skills/skill-audit"
+  local agent_audit="$dir/plugins/kyberforge/skills/agent-audit"
+  mkdir -p "$skill_audit/scripts" "$skill_audit/assets/vale/styles/Kyberforge"
+  mkdir -p "$agent_audit/scripts" "$agent_audit/assets/vale/styles/Kyberforge"
+
+  echo '#!/usr/bin/env bash' > "$skill_audit/scripts/vale-wrap.sh"
+  echo 'echo wrap' >> "$skill_audit/scripts/vale-wrap.sh"
+  cp "$skill_audit/scripts/vale-wrap.sh" "$agent_audit/scripts/vale-wrap.sh"
+
+  echo 'extends: existence' > "$skill_audit/assets/vale/styles/Kyberforge/Rule.yml"
+  cp "$skill_audit/assets/vale/styles/Kyberforge/Rule.yml" "$agent_audit/assets/vale/styles/Kyberforge/Rule.yml"
+
+  echo "$dir"
+}
+
+# --- 1. Exits 0 when the two copies are in sync ---
+echo ""
+echo "--- exits 0 when skill-audit and agent-audit copies are in sync ---"
+FIXTURE="$(make_fixture)"
+trap 'rm -rf "$FIXTURE"' EXIT
+if bash "$SCRIPT" "$FIXTURE" > /dev/null 2>&1; then
+  pass "exits 0 when copies are in sync"
+else
+  fail "exited non-zero against in-sync copies"
+fi
+
+# --- 2. Exits 1 when vale-wrap.sh differs between the two copies ---
+echo ""
+echo "--- exits 1 when vale-wrap.sh differs ---"
+FIXTURE2="$(make_fixture)"
+trap 'rm -rf "$FIXTURE" "$FIXTURE2"' EXIT
+echo 'echo different' >> "$FIXTURE2/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh"
+if bash "$SCRIPT" "$FIXTURE2" > /dev/null 2>&1; then
+  fail "exited 0 when vale-wrap.sh copies differ — expected exit 1"
+else
+  pass "exits non-zero when vale-wrap.sh copies differ"
+fi
+
+# --- 3. Exits 1 when a style rule differs between the two copies ---
+echo ""
+echo "--- exits 1 when a Kyberforge style rule differs ---"
+FIXTURE3="$(make_fixture)"
+trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3"' EXIT
+echo 'level: error' >> "$FIXTURE3/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/Rule.yml"
+if bash "$SCRIPT" "$FIXTURE3" > /dev/null 2>&1; then
+  fail "exited 0 when a style rule differs — expected exit 1"
+else
+  pass "exits non-zero when a Kyberforge style rule differs between copies"
+fi
+
+# --- 4. Exits 1 when a rule file exists in only one copy ---
+echo ""
+echo "--- exits 1 when a rule file is missing from one copy ---"
+FIXTURE4="$(make_fixture)"
+trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
+echo 'extends: existence' > "$FIXTURE4/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/Extra.yml"
+if bash "$SCRIPT" "$FIXTURE4" > /dev/null 2>&1; then
+  fail "exited 0 when a rule file exists in only one copy — expected exit 1"
+else
+  pass "exits non-zero when a rule file is missing from one copy"
+fi
+
+# --- 5. Exits 0 (no-op) when kyberforge isn't present in the target repo ---
+echo ""
+echo "--- exits 0 when kyberforge skills are absent (no-op) ---"
+FIXTURE5="$(mktemp -d)"
+trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
+if bash "$SCRIPT" "$FIXTURE5" > /dev/null 2>&1; then
+  pass "exits 0 as a no-op when skill-audit/agent-audit don't exist"
+else
+  fail "exited non-zero when skill-audit/agent-audit are simply absent"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index c40b09b..c6f057a 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -6,7 +6,12 @@
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-SCRIPT="$REPO_ROOT/scripts/vale-wrap.sh"
+# skill-audit's copy is used here (not agent-audit's) because every fixture below is a
+# SKILL.md — only skill-audit's .vale.ini has the [**/SKILL.md] glob section. vale-wrap.sh
+# itself is an identical copy in both skills, so which one SCRIPT points at doesn't matter.
+SKILL_AUDIT="$REPO_ROOT/plugins/kyberforge/skills/skill-audit"
+SCRIPT="$SKILL_AUDIT/scripts/vale-wrap.sh"
+VALE_CONFIG="$SKILL_AUDIT/assets/vale/.vale.ini"
 PASS=0
 FAIL=0
 
@@ -55,7 +60,7 @@ echo ""
 echo "--- catches vague wording in a single-line description ---"
 FIXTURE1="$(make_fixture 1)"
 trap 'rm -rf "$FIXTURE1"' EXIT
-if run_wrap "$FIXTURE1" --config "$REPO_ROOT/.vale.ini" \
+if run_wrap "$FIXTURE1" --config "$VALE_CONFIG" \
   plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when description is a single physical line"
 else
@@ -67,7 +72,7 @@ echo ""
 echo "--- catches vague wording in a multi-line folded description ---"
 FIXTURE2="$(make_fixture 2)"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2"' EXIT
-if run_wrap "$FIXTURE2" --config "$REPO_ROOT/.vale.ini" \
+if run_wrap "$FIXTURE2" --config "$VALE_CONFIG" \
   plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when description spans 2+ physical lines"
 else
@@ -80,7 +85,7 @@ echo "--- preserves total line count when flattening ---"
 FIXTURE3="$(make_fixture 3)"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3"' EXIT
 ORIG_LINES=$(wc -l < "$FIXTURE3/plugins/testplugin/skills/zzzskill/SKILL.md")
-OUT=$(run_wrap "$FIXTURE3" --config "$REPO_ROOT/.vale.ini" \
+OUT=$(run_wrap "$FIXTURE3" --config "$VALE_CONFIG" \
   plugins/testplugin/skills/zzzskill/SKILL.md)
 MAX_LINE=$(echo "$OUT" | grep -oE '^[[:space:]]*[0-9]+:[0-9]+' | tr -d '[:space:]' | cut -d: -f1 | sort -n | tail -1)
 if [[ -n "$MAX_LINE" ]] && (( MAX_LINE <= ORIG_LINES )); then
@@ -118,7 +123,7 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
-if run_wrap "$FIXTURE4" --config "$REPO_ROOT/.vale.ini" \
+if run_wrap "$FIXTURE4" --config "$VALE_CONFIG" \
   plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when the description contains a double quote"
 else
@@ -140,7 +145,7 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
-OUT5=$(run_wrap "$FIXTURE5" --config "$REPO_ROOT/.vale.ini" \
+OUT5=$(run_wrap "$FIXTURE5" --config "$VALE_CONFIG" \
   plugins/testplugin/skills/zzzskill/SKILL.md)
 if echo "$OUT5" | grep -q "VagueWording"; then
   pass "flags vague wording when the description contains an apostrophe"
@@ -168,7 +173,7 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6"' EXIT
-if run_wrap "$FIXTURE6" --config "$REPO_ROOT/.vale.ini" \
+if run_wrap "$FIXTURE6" --config "$VALE_CONFIG" \
   plugins/testplugin/skills/zzzskill/SKILL.md | grep -q "VagueWording"; then
   pass "flags vague wording when the description has a backslash and non-ASCII text"
 else
@@ -191,7 +196,7 @@ Body.
 EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7"' EXIT
-OUT7=$(run_wrap "$FIXTURE7" --config "$REPO_ROOT/.vale.ini" \
+OUT7=$(run_wrap "$FIXTURE7" --config "$VALE_CONFIG" \
   plugins/testplugin/skills/zzzskill/SKILL.md)
 if echo "$OUT7" | grep -q "Traceback"; then
   fail "crashed while flattening a description with a blank line between paragraphs"
@@ -213,8 +218,8 @@ echo ""
 echo "--- resolves a cwd-relative --config from a subdirectory (equals and two-argv forms) ---"
 FIXTURE8="$(mktemp -d)"
 (cd "$FIXTURE8" && git init -q)
-cp "$REPO_ROOT/.vale.ini" "$FIXTURE8/.vale.ini"
-cp -r "$REPO_ROOT/styles" "$FIXTURE8/styles"
+cp "$VALE_CONFIG" "$FIXTURE8/.vale.ini"
+cp -r "$SKILL_AUDIT/assets/vale/styles" "$FIXTURE8/styles"
 mkdir -p "$FIXTURE8/plugins/testplugin/skills/zzzskill"
 {
   echo "---"
@@ -280,7 +285,7 @@ fi
 # --- 9. Zero file args (or a file list that filters to nothing) exits promptly ---
 echo ""
 echo "--- exits promptly instead of hanging on stdin when no files are passed ---"
-if timeout 5 bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" < <(sleep 100) >/dev/null 2>&1; then
+if timeout 5 bash "$SCRIPT" --config "$VALE_CONFIG" < <(sleep 100) >/dev/null 2>&1; then
   pass "exits promptly with zero file args"
 else
   RC=$?
@@ -293,7 +298,7 @@ fi
 
 echo ""
 echo "--- exits promptly when a file list filters down to nothing ---"
-if timeout 5 bash "$SCRIPT" --config "$REPO_ROOT/.vale.ini" --no-such-flag < <(sleep 100) >/dev/null 2>&1; then
+if timeout 5 bash "$SCRIPT" --config "$VALE_CONFIG" --no-such-flag < <(sleep 100) >/dev/null 2>&1; then
   pass "exits promptly when no file-shaped args remain"
 else
   RC=$?
@@ -310,7 +315,7 @@ echo "--- lints an absolute path to a skill file instead of silently skipping it
 FIXTURE10="$(make_fixture 2)"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10"' EXIT
 ABS_FILE10="$FIXTURE10/plugins/testplugin/skills/zzzskill/SKILL.md"
-if run_wrap "$FIXTURE10" --config "$REPO_ROOT/.vale.ini" "$ABS_FILE10" | grep -q "VagueWording"; then
+if run_wrap "$FIXTURE10" --config "$VALE_CONFIG" "$ABS_FILE10" | grep -q "VagueWording"; then
   pass "an absolute path is linted, not silently skipped"
 else
   fail "an absolute path was silently skipped — the bug this test guards against"
@@ -332,8 +337,8 @@ EOF
 )"
 trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11"' EXIT
 REL11="plugins/testplugin/skills/zzzskill/SKILL.md"
-WRAPPED_OUT=$(run_wrap "$FIXTURE11" --config "$REPO_ROOT/.vale.ini" "$REL11")
-BARE_OUT=$(cd "$FIXTURE11" && vale --config "$REPO_ROOT/.vale.ini" "$REL11" 2>&1 || true)
+WRAPPED_OUT=$(run_wrap "$FIXTURE11" --config "$VALE_CONFIG" "$REL11")
+BARE_OUT=$(cd "$FIXTURE11" && vale --config "$VALE_CONFIG" "$REL11" 2>&1 || true)
 if [[ "$WRAPPED_OUT" == "$BARE_OUT" ]]; then
   pass "literal (|) block scalar output matches bare vale exactly — untouched by flattening"
 else
-- 
2.43.0


From 4d018af03cc47b53ac3b94a82c28f03a064d1f3e Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 10:20:43 +0000
Subject: [PATCH 18/45] fix(lint): hard-fail on main when a release tag is
 needed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

.pre-commit-hooks.yaml now exposes hooks to external consumers pinning
rev: <tag>, but nothing enforced that a tag actually gets cut when the
files it references change — relying on memory is exactly what this
repo's governance rules say to avoid for a repeatable, deterministic
check.

scripts/check-release-needed.sh hard-fails at pre-push, but only when
PRE_COMMIT_REMOTE_BRANCH (set by pre-commit's hook-impl) is
refs/heads/main: it diffs .pre-commit-hooks.yaml's referenced paths
against the last tag reachable from HEAD, and fails if either no tag
exists yet or something changed since. It's a silent no-op on every
other branch — hard-failing on feature-branch pushes mid-review would
force a premature tag on a commit that might not survive a
squash-merge, the exact risk the repo: local (vs. pinned self-
reference) decision in ADR-0014 already avoids for this repo's own
dev-time gate.

Verified against the real git pre-push hook path (not just the script
in isolation): simulated stdin matching git's pre-push protocol through
.git/hooks/pre-push, confirmed it correctly fires and fails when
targeting main with no tag, and is silent otherwise.

ADR: 0014
Refs: #87
---
 .pre-commit-config.yaml                       |  9 ++
 ...14-vale-prefilter-ships-from-the-plugin.md | 10 ++
 scripts/check-release-needed.sh               | 56 +++++++++++
 tests/test-check-release-needed.sh            | 97 +++++++++++++++++++
 4 files changed, 172 insertions(+)
 create mode 100755 scripts/check-release-needed.sh
 create mode 100755 tests/test-check-release-needed.sh

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 3a7e01b..375ae7a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -70,6 +70,15 @@ repos:
         pass_filenames: false
         always_run: true
 
+      - id: check-release-needed
+        name: Check a release tag covers .pre-commit-hooks.yaml's paths
+        description: On push to main only, fail if files exposed via .pre-commit-hooks.yaml changed since the last tag
+        entry: bash scripts/check-release-needed.sh
+        language: system
+        stages: [pre-push]
+        pass_filenames: false
+        always_run: true
+
       - id: validate-plugins
         name: Validate plugins
         description: Run claude plugin validate --strict on every plugin directory
diff --git a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
index 2ac7ebc..13b175e 100644
--- a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
+++ b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
@@ -97,3 +97,13 @@ doesn't wonder if it was overlooked.
   `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has the matching glob section.
 - The first `vX.Y.Z` tag is cut once this change and its tests pass, giving external
   `.pre-commit-hooks.yaml` consumers something to pin.
+- **Cutting the tag is not left to memory.** `scripts/check-release-needed.sh`, wired at
+  `pre-push`, hard-fails — but only when `PRE_COMMIT_REMOTE_BRANCH` (set by pre-commit's
+  `hook-impl` for pre-push hooks) is `refs/heads/main` — if any path `.pre-commit-hooks.yaml`
+  exposes changed since the last tag reachable from `HEAD`. It is a silent no-op on every other
+  branch: hard-failing on feature-branch pushes mid-review would force a premature tag on a
+  commit that might not survive a squash-merge, the exact problem `repo: local` (above) already
+  avoids for this repo's own dev-time gate. A tag not existing at all is also a hard fail on
+  `main`, covering the very first release. This is deterministic tooling, not a standing
+  instruction to remember — consistent with `check-manifests.sh`/`check-vale-style-sync.sh`
+  already using the same pre-push, main-agnostic-elsewhere pattern.
diff --git a/scripts/check-release-needed.sh b/scripts/check-release-needed.sh
new file mode 100755
index 0000000..3f2c5a7
--- /dev/null
+++ b/scripts/check-release-needed.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Hard-fails only when pushing to main: if any file covered by .pre-commit-hooks.yaml
+# (the external git-hook/CI contract, see ADR-0014) changed since the last tag,
+# a release must be cut before landing on main, or external consumers pinning
+# `rev: <tag>` silently miss the change. Pre-commit sets PRE_COMMIT_REMOTE_BRANCH
+# for pre-push hooks; on every other branch (feature work mid-review) this is a
+# silent no-op — pushing WIP commits there must not be blocked on cutting a
+# premature tag (see ADR-0014's repo: local vs pinned self-reference decision).
+
+TARGET_BRANCH="refs/heads/main"
+
+if [[ "${PRE_COMMIT_REMOTE_BRANCH:-}" != "$TARGET_BRANCH" ]]; then
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+# Paths whose content .pre-commit-hooks.yaml exposes to external consumers.
+# Keep in sync with .pre-commit-hooks.yaml's entry: paths.
+RELEASE_PATHS=(
+  .pre-commit-hooks.yaml
+  scripts/skill-size-check.sh
+  plugins/kyberforge/skills/skill-audit/scripts
+  plugins/kyberforge/skills/skill-audit/assets/vale
+  plugins/kyberforge/skills/agent-audit/scripts
+  plugins/kyberforge/skills/agent-audit/assets/vale
+)
+
+LAST_TAG="$(git describe --tags --abbrev=0 2>/dev/null || true)"
+
+if [[ -z "$LAST_TAG" ]]; then
+  echo "FAIL: no release tag exists yet, but .pre-commit-hooks.yaml already exposes hooks to external consumers." >&2
+  echo "  Fix: cut the first release tag (e.g. v1.0.0) before this lands on main." >&2
+  exit 1
+fi
+
+EXISTING_PATHS=()
+for p in "${RELEASE_PATHS[@]}"; do
+  [[ -e "$p" ]] && EXISTING_PATHS+=("$p")
+done
+
+if [[ ${#EXISTING_PATHS[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+CHANGED="$(git diff --name-only "$LAST_TAG"..HEAD -- "${EXISTING_PATHS[@]}" 2>/dev/null || true)"
+
+if [[ -n "$CHANGED" ]]; then
+  echo "FAIL: files covered by .pre-commit-hooks.yaml changed since $LAST_TAG:" >&2
+  echo "$CHANGED" | sed 's/^/    /' >&2
+  echo "  Fix: cut a new release tag — external consumers pinning rev: $LAST_TAG would miss this change." >&2
+  exit 1
+fi
diff --git a/tests/test-check-release-needed.sh b/tests/test-check-release-needed.sh
new file mode 100755
index 0000000..53f4041
--- /dev/null
+++ b/tests/test-check-release-needed.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="$REPO_ROOT/scripts/check-release-needed.sh"
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# Helper: a fixture repo with one release-relevant file, committed and tagged.
+make_tagged_fixture() {
+  local dir
+  dir="$(mktemp -d)"
+  (cd "$dir" && git init -q && git config user.email t@t.t && git config user.name t)
+  mkdir -p "$dir/scripts"
+  echo "v1" > "$dir/scripts/skill-size-check.sh"
+  (cd "$dir" && git add -A && git commit -q -m "initial" && git tag v1.0.0)
+  echo "$dir"
+}
+
+run_check() {
+  local dir="$1" branch="$2"
+  (cd "$dir" && PRE_COMMIT_REMOTE_BRANCH="$branch" bash "$SCRIPT" 2>&1)
+}
+
+# --- 1. Not targeting main: silent no-op regardless of state ---
+echo ""
+echo "--- exits 0 when not pushing to main, even with no tags ---"
+FIXTURE1="$(mktemp -d)"
+trap 'rm -rf "$FIXTURE1"' EXIT
+(cd "$FIXTURE1" && git init -q)
+if run_check "$FIXTURE1" "refs/heads/feature-branch" > /dev/null; then
+  pass "exits 0 when target branch isn't main"
+else
+  fail "exited non-zero on a non-main target branch"
+fi
+
+# --- 2. Targeting main, no tag exists at all: hard fail ---
+echo ""
+echo "--- exits 1 when targeting main and no tag exists ---"
+FIXTURE2="$(mktemp -d)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2"' EXIT
+(cd "$FIXTURE2" && git init -q && git config user.email t@t.t && git config user.name t)
+mkdir -p "$FIXTURE2/scripts"
+echo "v1" > "$FIXTURE2/scripts/skill-size-check.sh"
+(cd "$FIXTURE2" && git add -A && git commit -q -m "initial")
+if run_check "$FIXTURE2" "refs/heads/main" > /dev/null; then
+  fail "exited 0 when targeting main with no tag — expected exit 1"
+else
+  pass "exits non-zero when targeting main and no tag exists yet"
+fi
+
+# --- 3. Targeting main, tag exists, no release-relevant changes since: passes ---
+echo ""
+echo "--- exits 0 when targeting main and nothing release-relevant changed since the tag ---"
+FIXTURE3="$(make_tagged_fixture)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3"' EXIT
+echo "unrelated" > "$FIXTURE3/README.md"
+(cd "$FIXTURE3" && git add -A && git commit -q -m "unrelated change")
+if run_check "$FIXTURE3" "refs/heads/main" > /dev/null; then
+  pass "exits 0 when only unrelated files changed since the tag"
+else
+  fail "exited non-zero despite no release-relevant changes since the tag"
+fi
+
+# --- 4. Targeting main, tag exists, a release-relevant file changed since: hard fail ---
+echo ""
+echo "--- exits 1 when a release-relevant file changed since the tag ---"
+FIXTURE4="$(make_tagged_fixture)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
+echo "v2" > "$FIXTURE4/scripts/skill-size-check.sh"
+(cd "$FIXTURE4" && git add -A && git commit -q -m "update release-relevant script")
+OUT4=$(run_check "$FIXTURE4" "refs/heads/main" || true)
+if echo "$OUT4" | grep -q "skill-size-check.sh"; then
+  pass "exits non-zero and names the changed file when a release-relevant path changed since the tag"
+else
+  fail "did not flag the release-relevant file that changed since the tag"
+fi
+
+# --- 5. Not targeting main even with release-relevant changes and a tag: still a no-op ---
+echo ""
+echo "--- exits 0 on a feature branch even with release-relevant changes since the tag ---"
+FIXTURE5="$(make_tagged_fixture)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
+echo "v2" > "$FIXTURE5/scripts/skill-size-check.sh"
+(cd "$FIXTURE5" && git add -A && git commit -q -m "update release-relevant script")
+if run_check "$FIXTURE5" "refs/heads/some-feature" > /dev/null; then
+  pass "exits 0 on a feature branch regardless of un-tagged release-relevant changes"
+else
+  fail "hard-failed on a feature branch — should only ever fail when targeting main"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]
-- 
2.43.0


From acd2f1d4220bf41bad10a5ae519bf3890fa12e2e Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 11:20:55 +0000
Subject: [PATCH 19/45] fix(lint): harden check-release-needed.sh, script the
 vale-style sync
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A review of PR #85's last two commits (1164f3a, 4d018af) found the new
release-gate script fails open in four separate ways, and the new drift
check for the duplicated Vale styles only ever detects drift after a
human already hand-edited both copies out of sync.

check-release-needed.sh:
- The `-e` existence filter dropped a RELEASE_PATHS entry from the diff
  pathspec once it was deleted from the tree, so deleting a path exposed
  via .pre-commit-hooks.yaml since the last tag passed the gate clean —
  exactly the breakage the gate exists to catch. git diff reports
  deletions fine without an existence check; the filter is gone.
- `git diff ... 2>/dev/null || true` turned any git failure (a shallow
  clone missing the tag's objects, a corrupted ref) into an empty,
  falsely-clean diff. The diff result is no longer swallowed: a failure
  now hard-fails with the underlying git error visible.
- RELEASE_PATHS was a hand-maintained array duplicating
  .pre-commit-hooks.yaml's entry: paths with only a comment holding them
  in sync, and was already over-broad (it swept in validate.sh /
  validate-provenance.sh, which no hook entry references). It's now
  parsed straight from .pre-commit-hooks.yaml's entry: lines at
  runtime, so it can't drift from the manifest and only tracks what a
  hook actually exposes.
- `git describe --tags --abbrev=0` accepted any tag reachable from HEAD
  as the diff baseline, not just release tags. Added
  `--match 'v[0-9]*.[0-9]*.[0-9]*'` so an incidental checkpoint tag
  can't shift the baseline and mask a real release-relevant change.

check-vale-style-sync.sh still only detects drift between skill-audit's
and agent-audit's duplicated vale-wrap.sh/styles/Kyberforge copies
(both copies must exist independently per the plugin's no-cross-skill-
path packaging rule — a symlink would break at install time). Added
scripts/sync-vale-styles.sh to regenerate skill-audit's copy from
agent-audit's canonical one on demand, and pointed the sync check's
failure message at it, so fixing drift is one command instead of a
hand diff across two files.

Also recorded, rather than silently left unfixed: check-release-needed.sh
only fires on a local `git push` through pre-commit's pre-push hook — a
PR merged via Gitea's merge button, or CI invoking
`pre-commit run --hook-stage pre-push` directly, never sets
PRE_COMMIT_REMOTE_BRANCH and skips the gate entirely. Closing that needs
a server-side CI job this repo doesn't have yet; documented as a known
limitation in ADR-0014 rather than papered over.

Separately, LESSONS.md's "a clean check can mean nothing ran" entry was
marked **Graduated** without ever being promoted per the repo's own
graduation rule (3+ instances → a standing doc, marked
`[graduated → target file]`). Actually promoted it into
core/instructions/testing.md and fixed the marker.

tests/test-check-release-needed.sh gained 4 regression tests, one per
check-release-needed.sh fix above, each verified to fail against the
pre-fix script and pass against the current one.

Verification: bash tests/run-tests.sh (11 scripts + 125 bats, all
passing), pre-commit run --all-files, and
pre-commit run --all-files --hook-stage pre-push all clean.

ADR: 0014
---
 LESSONS.md                                    |  2 +-
 core/instructions/testing.md                  |  1 +
 ...14-vale-prefilter-ships-from-the-plugin.md | 10 ++
 scripts/check-release-needed.sh               | 62 ++++++++----
 scripts/check-vale-style-sync.sh              |  2 +-
 scripts/sync-vale-styles.sh                   | 21 ++++
 tests/test-check-release-needed.sh            | 96 ++++++++++++++++---
 7 files changed, 161 insertions(+), 33 deletions(-)
 create mode 100755 scripts/sync-vale-styles.sh

diff --git a/LESSONS.md b/LESSONS.md
index d1da2ba..234d3d9 100644
--- a/LESSONS.md
+++ b/LESSONS.md
@@ -140,7 +140,7 @@ During write-skill refactor, an "open thread" note (about a deferred research st
 
 ## 2026-08-08 — A clean linter result can mean "nothing was checked"
 
-Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **Graduated** (4th instance below).
+Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **[graduated → core/instructions/testing.md]** (4th instance below, kept for audit trail).
 
 **4th instance (2026-08-09, ADR-0014):** splitting the single root `.vale.ini` into two skill-scoped copies (skill-audit: `SKILL.md` only; agent-audit: agent files only) meant a single retargeted pre-commit hook pointed at agent-audit's copy alone would have silently scanned 0 `SKILL.md` files and exited 0 — caught only because the full corpus was dry-run against both the old and new config and the outputs diffed before the old config was deleted, not because any test asserted on file counts. Standing practice going forward: when a Vale (or any linter) config that serves multiple file-glob scopes is split or moved, dry-run the full corpus through both the old and new config and diff the outputs before removing the superseded source — a hook silently scanning 0 files looks identical to a clean pass.
 
diff --git a/core/instructions/testing.md b/core/instructions/testing.md
index 69566d5..33fa97b 100644
--- a/core/instructions/testing.md
+++ b/core/instructions/testing.md
@@ -4,3 +4,4 @@
 - Automate everything automatable. Manual testing only for nuanced UI/UX or agent interaction behaviour requiring human judgment.
 - Test observable end-state, not implementation internals. Tests must survive refactoring.
 - No test is better than a wrong test. A passing mock that masks a real failure is actively harmful.
+- A clean result can mean nothing ran. Before trusting a new check, prove it fails against a deliberately-bad fixture, then run it against the real target. Where a check can scan zero inputs, assert on the input count, not just the exit code — a zero-file run and a real clean pass look identical otherwise.
diff --git a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
index 13b175e..10ac2c0 100644
--- a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
+++ b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
@@ -107,3 +107,13 @@ doesn't wonder if it was overlooked.
   `main`, covering the very first release. This is deterministic tooling, not a standing
   instruction to remember — consistent with `check-manifests.sh`/`check-vale-style-sync.sh`
   already using the same pre-push, main-agnostic-elsewhere pattern.
+- **Known limitation, not yet closed:** `check-release-needed.sh` only fires when a human runs
+  `git push` locally with pre-commit's hooks installed — `PRE_COMMIT_REMOTE_BRANCH` is set by
+  pre-commit's client-side `hook-impl` script parsing `git push`'s stdin protocol. A PR merged
+  through Gitea's merge button (server-side, no local push) or a CI runner invoking
+  `pre-commit run --hook-stage pre-push` directly never sets it, so the gate silently doesn't run
+  in either path. This repo has no CI workflow yet (`has_actions` is enabled but unused), so
+  closing this gap needs a server-side job re-running the same script on merge to `main` — deferred
+  as a separate piece of infrastructure, not fixed here. `RELEASE_PATHS` is derived from
+  `.pre-commit-hooks.yaml`'s own `entry:` lines rather than hand-maintained, so at least the set of
+  paths it checks can't drift from the manifest on its own.
diff --git a/scripts/check-release-needed.sh b/scripts/check-release-needed.sh
index 3f2c5a7..8f1f285 100755
--- a/scripts/check-release-needed.sh
+++ b/scripts/check-release-needed.sh
@@ -8,6 +8,12 @@ set -euo pipefail
 # for pre-push hooks; on every other branch (feature work mid-review) this is a
 # silent no-op — pushing WIP commits there must not be blocked on cutting a
 # premature tag (see ADR-0014's repo: local vs pinned self-reference decision).
+#
+# Known gap: this only fires on a local `git push` through pre-commit's pre-push
+# hook. A PR merged via Gitea's merge button (server-side, no local push) or a
+# CI runner invoking `pre-commit run --hook-stage pre-push` directly does not set
+# PRE_COMMIT_REMOTE_BRANCH and will not trigger this check — closing that
+# requires a server-side CI job, which this repo does not have yet.
 
 TARGET_BRANCH="refs/heads/main"
 
@@ -18,18 +24,34 @@ fi
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 cd "$REPO_ROOT"
 
-# Paths whose content .pre-commit-hooks.yaml exposes to external consumers.
-# Keep in sync with .pre-commit-hooks.yaml's entry: paths.
-RELEASE_PATHS=(
-  .pre-commit-hooks.yaml
-  scripts/skill-size-check.sh
-  plugins/kyberforge/skills/skill-audit/scripts
-  plugins/kyberforge/skills/skill-audit/assets/vale
-  plugins/kyberforge/skills/agent-audit/scripts
-  plugins/kyberforge/skills/agent-audit/assets/vale
-)
+HOOKS_MANIFEST=".pre-commit-hooks.yaml"
 
-LAST_TAG="$(git describe --tags --abbrev=0 2>/dev/null || true)"
+if [[ ! -f "$HOOKS_MANIFEST" ]]; then
+  exit 0
+fi
+
+# Derive release-relevant paths from .pre-commit-hooks.yaml's own entry: lines
+# instead of hand-maintaining a parallel list — the manifest is the single
+# source of truth for what external consumers actually pull at a pinned rev,
+# so a hook added/removed/renamed there can't silently drift out of sync here.
+# Each entry is "<script> [--config <path>] [...]"; the script itself and the
+# directory holding any --config target (vale-wrap.sh needs its .vale.ini's
+# sibling styles/ tree, not just the ini file) are release-relevant.
+RELEASE_PATHS=("$HOOKS_MANIFEST")
+while IFS= read -r entry; do
+  read -ra tokens <<< "$entry"
+  [[ ${#tokens[@]} -eq 0 ]] && continue
+  RELEASE_PATHS+=("${tokens[0]}")
+  for ((i = 1; i < ${#tokens[@]}; i++)); do
+    if [[ "${tokens[i]}" == "--config" && -n "${tokens[i + 1]:-}" ]]; then
+      RELEASE_PATHS+=("$(dirname "${tokens[i + 1]}")")
+    fi
+  done
+done < <(sed -n 's/^[[:space:]]*entry:[[:space:]]*//p' "$HOOKS_MANIFEST")
+
+# Only vX.Y.Z release tags count as a baseline — an incidental checkpoint or
+# experiment tag reachable from HEAD must not shift the diff baseline.
+LAST_TAG="$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' 2>/dev/null || true)"
 
 if [[ -z "$LAST_TAG" ]]; then
   echo "FAIL: no release tag exists yet, but .pre-commit-hooks.yaml already exposes hooks to external consumers." >&2
@@ -37,17 +59,17 @@ if [[ -z "$LAST_TAG" ]]; then
   exit 1
 fi
 
-EXISTING_PATHS=()
-for p in "${RELEASE_PATHS[@]}"; do
-  [[ -e "$p" ]] && EXISTING_PATHS+=("$p")
-done
-
-if [[ ${#EXISTING_PATHS[@]} -eq 0 ]]; then
-  exit 0
+# No -e/existence filtering: a path deleted since $LAST_TAG is exactly the case
+# that must be caught (external consumers pinning the old tag would hit a
+# missing file), and `git diff` reports deletions fine without it existing at
+# HEAD. A git failure (e.g. a shallow clone missing $LAST_TAG's history) must
+# fail closed, not be swallowed into an empty, falsely-clean diff.
+if ! CHANGED="$(git diff --name-only "$LAST_TAG"..HEAD -- "${RELEASE_PATHS[@]}")"; then
+  echo "FAIL: could not diff $LAST_TAG..HEAD to check for release-relevant changes (see git error above)." >&2
+  echo "  Fix: ensure full tag history is available (e.g. git fetch --unshallow) and retry." >&2
+  exit 1
 fi
 
-CHANGED="$(git diff --name-only "$LAST_TAG"..HEAD -- "${EXISTING_PATHS[@]}" 2>/dev/null || true)"
-
 if [[ -n "$CHANGED" ]]; then
   echo "FAIL: files covered by .pre-commit-hooks.yaml changed since $LAST_TAG:" >&2
   echo "$CHANGED" | sed 's/^/    /' >&2
diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh
index ac7d35e..029bb92 100755
--- a/scripts/check-vale-style-sync.sh
+++ b/scripts/check-vale-style-sync.sh
@@ -30,6 +30,6 @@ if ! diff -rq "$SKILL_AUDIT/assets/vale/styles/Kyberforge" "$AGENT_AUDIT/assets/
 fi
 
 if [[ $FAIL -gt 0 ]]; then
-  echo "Vale style sync check failed: $FAIL error(s). agent-audit's copy is canonical — sync skill-audit's copy to match." >&2
+  echo "Vale style sync check failed: $FAIL error(s). agent-audit's copy is canonical — run scripts/sync-vale-styles.sh to regenerate skill-audit's copy, then commit both." >&2
   exit 1
 fi
diff --git a/scripts/sync-vale-styles.sh b/scripts/sync-vale-styles.sh
new file mode 100755
index 0000000..baedeb3
--- /dev/null
+++ b/scripts/sync-vale-styles.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Regenerates skill-audit's Vale copy from agent-audit's canonical copy (see
+# scripts/check-vale-style-sync.sh / ADR-0014). Both copies must exist on disk
+# independently — a plugin's cache-install only copies each skill's own files,
+# so a symlink or shared path would break at install time — but that doesn't
+# mean the copy step has to be manual. Run this after editing agent-audit's
+# vale-wrap.sh or styles/Kyberforge, review the diff, then commit both trees
+# together.
+
+REPO_ROOT="${1:-$(git rev-parse --show-toplevel)}"
+SKILL_AUDIT="$REPO_ROOT/plugins/kyberforge/skills/skill-audit"
+AGENT_AUDIT="$REPO_ROOT/plugins/kyberforge/skills/agent-audit"
+
+cp "$AGENT_AUDIT/scripts/vale-wrap.sh" "$SKILL_AUDIT/scripts/vale-wrap.sh"
+rm -rf "$SKILL_AUDIT/assets/vale/styles/Kyberforge"
+cp -r "$AGENT_AUDIT/assets/vale/styles/Kyberforge" "$SKILL_AUDIT/assets/vale/styles/Kyberforge"
+
+echo "Synced skill-audit's vale-wrap.sh and styles/Kyberforge from agent-audit's canonical copy."
+echo "Review the diff, then commit both directories together."
diff --git a/tests/test-check-release-needed.sh b/tests/test-check-release-needed.sh
index 53f4041..8a53f25 100755
--- a/tests/test-check-release-needed.sh
+++ b/tests/test-check-release-needed.sh
@@ -9,13 +9,32 @@ FAIL=0
 pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
 fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
 
-# Helper: a fixture repo with one release-relevant file, committed and tagged.
+# Helper: write a minimal .pre-commit-hooks.yaml exposing one script entry and
+# one --config-bearing entry, so RELEASE_PATHS (derived from the manifest, not
+# hand-maintained) has both shapes to parse.
+write_manifest() {
+  local dir="$1"
+  mkdir -p "$dir/vale"
+  cat > "$dir/.pre-commit-hooks.yaml" <<'EOF'
+-   id: fake-size-check
+    entry: scripts/skill-size-check.sh
+    language: script
+-   id: fake-vale-check
+    entry: scripts/vale-wrap.sh --config vale/.vale.ini
+    language: script
+EOF
+}
+
+# Helper: a fixture repo with a manifest and its two referenced release-relevant
+# paths, committed and tagged v1.0.0.
 make_tagged_fixture() {
   local dir
   dir="$(mktemp -d)"
   (cd "$dir" && git init -q && git config user.email t@t.t && git config user.name t)
+  write_manifest "$dir"
   mkdir -p "$dir/scripts"
   echo "v1" > "$dir/scripts/skill-size-check.sh"
+  echo "cfg" > "$dir/vale/.vale.ini"
   (cd "$dir" && git add -A && git commit -q -m "initial" && git tag v1.0.0)
   echo "$dir"
 }
@@ -25,11 +44,14 @@ run_check() {
   (cd "$dir" && PRE_COMMIT_REMOTE_BRANCH="$branch" bash "$SCRIPT" 2>&1)
 }
 
+CLEANUP_DIRS=()
+trap 'rm -rf "${CLEANUP_DIRS[@]}"' EXIT
+track() { CLEANUP_DIRS+=("$1"); }
+
 # --- 1. Not targeting main: silent no-op regardless of state ---
 echo ""
 echo "--- exits 0 when not pushing to main, even with no tags ---"
-FIXTURE1="$(mktemp -d)"
-trap 'rm -rf "$FIXTURE1"' EXIT
+FIXTURE1="$(mktemp -d)"; track "$FIXTURE1"
 (cd "$FIXTURE1" && git init -q)
 if run_check "$FIXTURE1" "refs/heads/feature-branch" > /dev/null; then
   pass "exits 0 when target branch isn't main"
@@ -40,11 +62,12 @@ fi
 # --- 2. Targeting main, no tag exists at all: hard fail ---
 echo ""
 echo "--- exits 1 when targeting main and no tag exists ---"
-FIXTURE2="$(mktemp -d)"
-trap 'rm -rf "$FIXTURE1" "$FIXTURE2"' EXIT
+FIXTURE2="$(mktemp -d)"; track "$FIXTURE2"
 (cd "$FIXTURE2" && git init -q && git config user.email t@t.t && git config user.name t)
+write_manifest "$FIXTURE2"
 mkdir -p "$FIXTURE2/scripts"
 echo "v1" > "$FIXTURE2/scripts/skill-size-check.sh"
+echo "cfg" > "$FIXTURE2/vale/.vale.ini"
 (cd "$FIXTURE2" && git add -A && git commit -q -m "initial")
 if run_check "$FIXTURE2" "refs/heads/main" > /dev/null; then
   fail "exited 0 when targeting main with no tag — expected exit 1"
@@ -55,8 +78,7 @@ fi
 # --- 3. Targeting main, tag exists, no release-relevant changes since: passes ---
 echo ""
 echo "--- exits 0 when targeting main and nothing release-relevant changed since the tag ---"
-FIXTURE3="$(make_tagged_fixture)"
-trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3"' EXIT
+FIXTURE3="$(make_tagged_fixture)"; track "$FIXTURE3"
 echo "unrelated" > "$FIXTURE3/README.md"
 (cd "$FIXTURE3" && git add -A && git commit -q -m "unrelated change")
 if run_check "$FIXTURE3" "refs/heads/main" > /dev/null; then
@@ -68,8 +90,7 @@ fi
 # --- 4. Targeting main, tag exists, a release-relevant file changed since: hard fail ---
 echo ""
 echo "--- exits 1 when a release-relevant file changed since the tag ---"
-FIXTURE4="$(make_tagged_fixture)"
-trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
+FIXTURE4="$(make_tagged_fixture)"; track "$FIXTURE4"
 echo "v2" > "$FIXTURE4/scripts/skill-size-check.sh"
 (cd "$FIXTURE4" && git add -A && git commit -q -m "update release-relevant script")
 OUT4=$(run_check "$FIXTURE4" "refs/heads/main" || true)
@@ -82,8 +103,7 @@ fi
 # --- 5. Not targeting main even with release-relevant changes and a tag: still a no-op ---
 echo ""
 echo "--- exits 0 on a feature branch even with release-relevant changes since the tag ---"
-FIXTURE5="$(make_tagged_fixture)"
-trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
+FIXTURE5="$(make_tagged_fixture)"; track "$FIXTURE5"
 echo "v2" > "$FIXTURE5/scripts/skill-size-check.sh"
 (cd "$FIXTURE5" && git add -A && git commit -q -m "update release-relevant script")
 if run_check "$FIXTURE5" "refs/heads/some-feature" > /dev/null; then
@@ -92,6 +112,60 @@ else
   fail "hard-failed on a feature branch — should only ever fail when targeting main"
 fi
 
+# --- 6. A release-relevant path deleted since the tag is still flagged ---
+echo ""
+echo "--- exits 1 when a release-relevant path was deleted since the tag, not just modified ---"
+FIXTURE6="$(make_tagged_fixture)"; track "$FIXTURE6"
+rm -rf "$FIXTURE6/vale"
+(cd "$FIXTURE6" && git add -A && git commit -q -m "delete the vale config dir")
+OUT6=$(run_check "$FIXTURE6" "refs/heads/main" || true)
+if echo "$OUT6" | grep -q "vale/.vale.ini"; then
+  pass "flags a deleted release-relevant path instead of silently dropping it from the diff"
+else
+  fail "did not flag deletion of a release-relevant path since the tag"
+fi
+
+# --- 7. A git diff failure hard-fails instead of reading as a clean pass ---
+echo ""
+echo "--- exits 1 (not a silent pass) when the underlying git diff errors out ---"
+FIXTURE7="$(make_tagged_fixture)"; track "$FIXTURE7"
+TAG_TREE="$(cd "$FIXTURE7" && git rev-parse 'v1.0.0^{tree}')"
+echo "v2" > "$FIXTURE7/scripts/skill-size-check.sh"
+(cd "$FIXTURE7" && git add -A && git commit -q -m "advance past the tag")
+rm -f "$FIXTURE7/.git/objects/${TAG_TREE:0:2}/${TAG_TREE:2}"
+if run_check "$FIXTURE7" "refs/heads/main" > /dev/null; then
+  fail "silently exited 0 when the underlying git diff failed"
+else
+  pass "hard-fails instead of silently passing when git diff can't be computed"
+fi
+
+# --- 8. A non-version tag reachable from HEAD does not become the diff baseline ---
+echo ""
+echo "--- ignores a non-vX.Y.Z tag and still flags a change since the real release tag ---"
+FIXTURE8="$(make_tagged_fixture)"; track "$FIXTURE8"
+echo "checkpoint" > "$FIXTURE8/scripts/skill-size-check.sh"
+(cd "$FIXTURE8" && git add -A && git commit -q -m "checkpoint work" && git tag checkpoint-1)
+echo "v2" > "$FIXTURE8/scripts/skill-size-check.sh"
+(cd "$FIXTURE8" && git add -A && git commit -q -m "real release-relevant change")
+OUT8=$(run_check "$FIXTURE8" "refs/heads/main" || true)
+if echo "$OUT8" | grep -q "skill-size-check.sh"; then
+  pass "still flags the release-relevant change since v1.0.0, ignoring the non-version checkpoint tag"
+else
+  fail "an incidental non-version tag shifted the baseline and hid a real release-relevant change"
+fi
+
+# --- 9. A file outside every manifest entry does not trigger a fail ---
+echo ""
+echo "--- exits 0 when a changed file sits near, but isn't referenced by, a manifest entry ---"
+FIXTURE9="$(make_tagged_fixture)"; track "$FIXTURE9"
+echo "irrelevant" > "$FIXTURE9/scripts/unrelated-helper.sh"
+(cd "$FIXTURE9" && git add -A && git commit -q -m "add an unrelated script alongside the exposed one")
+if run_check "$FIXTURE9" "refs/heads/main" > /dev/null; then
+  pass "exits 0 for a file that lives alongside, but isn't referenced by, any manifest entry"
+else
+  fail "flagged a file that no .pre-commit-hooks.yaml entry actually exposes"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 8c570e96596812e9cdba4fb4e6157319d1788185 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:06:23 +0000
Subject: [PATCH 20/45] fix(lint): make the Vale prefilter work for external
 consumers

pre-commit prefixes only entry[0] with the hook-repo clone path
(cmd = (prefix.path(cmd[0]), *cmd[1:])), so the --config argument in
.pre-commit-hooks.yaml resolved against the *consuming* repo's root
and hard-failed every external run with E100. Two of the three hooks
ADR-0014 promises were unusable.

vale-wrap.sh now self-locates its config from BASH_SOURCE when no
--config is supplied; an explicit --config still wins in all three
argv forms and stays cwd-relative. Both manifests drop the argument
and are kept byte-identical: the local repo: local config resolved
--config correctly only because the consuming repo *was* this repo,
and that divergence is why three review rounds missed the defect.

Also in the wrapper:
- replace GNU-only `realpath -m` with a portable abspath helper; -m is
  load-bearing (dest does not exist yet), so BSD realpath aborted the
  script under set -e on macOS
- walk directory arguments instead of passing them through unflattened,
  which reported a clean 0-error run for files that fail when named
  explicitly
- read/write with errors='surrogateescape' so one non-UTF-8 .md under a
  directory argument cannot abort the hook

New test-vale-hooks-consumer.sh builds the hook repo from the working
tree and points a file:// consumer at it, covering the manifest as a
hook repo for the first time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 .pre-commit-config.yaml                       |   4 +-
 .pre-commit-hooks.yaml                        |   4 +-
 .../skills/agent-audit/scripts/vale-wrap.sh   | 136 ++++++++++++------
 .../skills/skill-audit/scripts/vale-wrap.sh   | 136 ++++++++++++------
 tests/run-tests.sh                            |  19 ++-
 tests/test-vale-hooks-consumer.sh             | 127 ++++++++++++++++
 tests/test-vale-wrap.sh                       |  84 ++++++++++-
 7 files changed, 412 insertions(+), 98 deletions(-)
 create mode 100755 tests/test-vale-hooks-consumer.sh

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 375ae7a..165ea75 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -129,7 +129,7 @@ repos:
         stages: ['pre-commit']
         name: Vale audit prefilter (SKILL.md)
         description: Run Vale against SKILL.md files as a deterministic prefilter for skill-audit, via skill-audit's own bundled copy
-        entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini
+        entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
         language: script
         files: '^plugins/[^/]+/skills/[^/]+/SKILL\.md$'
         pass_filenames: true
@@ -138,7 +138,7 @@ repos:
         stages: ['pre-commit']
         name: Vale audit prefilter (agent files)
         description: Run Vale against agent markdown files as a deterministic prefilter for agent-audit, via agent-audit's own bundled copy
-        entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini
+        entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
         language: script
         files: '^plugins/[^/]+/agents/[^/]+\.md$'
         pass_filenames: true
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index 4ad76d9..eee3986 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -1,14 +1,14 @@
 -   id: kyberforge-vale-audit-skill
     name: Kyberforge Vale prose audit (SKILL.md)
     description: Deterministic prose-pattern prefilter for kyberforge's skill-audit, via its own bundled Vale config/styles
-    entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini
+    entry: plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
     language: script
     files: '(^|/)SKILL\.md$'
 
 -   id: kyberforge-vale-audit-agent
     name: Kyberforge Vale prose audit (agent files)
     description: Deterministic prose-pattern prefilter for kyberforge's agent-audit, via its own bundled Vale config/styles
-    entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh --config plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini
+    entry: plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
     language: script
     files: '(^|/)agents/[^/]+\.md$|\.agent\.md$'
 
diff --git a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
index 918f32e..9e22cb8 100755
--- a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
@@ -9,26 +9,35 @@ set -euo pipefail
 # the real `vale` binary against the copies. Drop-in replacement for calling
 # `vale` directly: same args, same exit code.
 #
-# "Same args" means relative paths — `--config` values and file arguments alike
+# "Same args" means relative paths — `--config` values and path arguments alike
 # — resolve against the caller's current directory, exactly as bare `vale`
 # resolves them. (An earlier version resolved them against the repo root, an
 # invented convention that hard-errored on `--config ../../.vale.ini` from a
 # subdirectory and, worse, silently dropped file arguments that didn't happen to
 # resolve from the repo root — skipping the flattening this script exists for.)
 #
-# Vale prints each file path exactly as it was handed to it, so the scratch tree
-# mirrors the caller's absolute cwd: a relative file argument is passed through
+# The one addition to bare `vale`'s argument handling: with no `--config` at
+# all, this script's own sibling `assets/vale/.vale.ini` is used instead of
+# vale's upward search. pre-commit prefixes only `entry[0]` with the hook-repo
+# clone path, so a `--config` in `.pre-commit-hooks.yaml` would resolve against
+# the *consuming* repo and hard-fail (E100) for every external consumer. The
+# manifest therefore passes the script alone, and an explicit `--config` from
+# any other caller still wins.
+#
+# Vale prints each path exactly as it was handed to it, so the scratch tree
+# mirrors the caller's absolute cwd: a relative path argument is passed through
 # verbatim and resolves to its flattened copy, keeping the report byte-identical
-# to bare `vale`'s. An absolute file argument inside the cwd is relativized to
-# keep that property. Only an absolute path outside the cwd is rewritten to its
-# scratch copy and so reports a scratch path — unavoidable, since a file can
-# only be read from where it actually is.
+# to bare `vale`'s. An absolute path inside the cwd is relativized to keep that
+# property. Only an absolute path outside the cwd is rewritten to its scratch
+# copy and so reports a scratch path — unavoidable, since a file can only be
+# read from where it actually is.
 
 cwd="$(pwd -P)"
 
 vale_args=()
-file_args=()
+path_args=()
 config_next=false
+config_given=false
 for arg in "$@"; do
   if [[ "$config_next" == true ]]; then
     config_next=false
@@ -43,19 +52,24 @@ for arg in "$@"; do
     --config)
       vale_args+=("$arg")
       config_next=true
+      config_given=true
       continue
       ;;
     --config=/*)
       vale_args+=("$arg")
+      config_given=true
       continue
       ;;
     --config=*)
       vale_args+=("--config=$cwd/${arg#--config=}")
+      config_given=true
       continue
       ;;
   esac
-  # `-f` resolves relative paths against the caller's cwd, same as vale does.
-  if [[ "$arg" != -* && -f "$arg" ]]; then
+  # `-f`/`-d` resolve relative paths against the caller's cwd, same as vale does.
+  # A path that doesn't exist is left for vale to report on, exactly as bare
+  # vale would.
+  if [[ "$arg" != -* && ( -f "$arg" || -d "$arg" ) ]]; then
     # An absolute path inside the caller's cwd is relativized so the report cites
     # a path that resolves against the real tree. Left absolute, it would be
     # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
@@ -63,54 +77,41 @@ for arg in "$@"; do
     # quoting it. Absolute paths outside the cwd have no relative form and keep
     # the scratch-path behaviour documented above.
     if [[ "$arg" == "$cwd"/* ]]; then
-      file_args+=("${arg#"$cwd"/}")
+      path_args+=("${arg#"$cwd"/}")
     else
-      file_args+=("$arg")
+      path_args+=("$arg")
     fi
   else
     vale_args+=("$arg")
   fi
 done
 
-if [[ ${#file_args[@]} -eq 0 ]]; then
+if [[ "$config_given" == false ]]; then
+  vale_args+=(--config "$(cd "$(dirname "${BASH_SOURCE[0]}")/../assets/vale" && pwd)/.vale.ini")
+fi
+
+if [[ ${#path_args[@]} -eq 0 ]]; then
   # Nothing to flatten. Hand off directly, with stdin closed so vale doesn't
   # block waiting on a pipe that will never carry content.
   exec vale "${vale_args[@]}" < /dev/null
 fi
 
-tmpdir="$(realpath -m "$(mktemp -d)")"
-trap 'rm -rf "$tmpdir"' EXIT
+# `realpath -m` would be the obvious normalizer, but `-m` (canonicalize-missing)
+# is a GNU extension the BSD realpath on macOS doesn't have — and every dest
+# below is a path that doesn't exist yet. python3 is already a hard dependency.
+abspath() {
+  python3 -c 'import os, sys; print(os.path.abspath(sys.argv[1]))' "$1"
+}
 
-# Mirror of the caller's cwd inside the scratch tree; relative file arguments
-# are resolved from here.
-mirror="$tmpdir$cwd"
-mkdir -p "$mirror"
-
-argv_files=()
-for arg in "${file_args[@]}"; do
-  if [[ "$arg" == /* ]]; then
-    dest="$tmpdir$arg"
-  else
-    dest="$mirror/$arg"
-  fi
-  dest="$(realpath -m "$dest")"
-  # A file argument with enough leading `..` to climb past the mirror root would
-  # write outside the scratch dir. The real filesystem clamps such a path at
-  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
-  case "$dest" in
-    "$tmpdir"/*) ;;
-    *)
-      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
-      exit 2
-      ;;
-  esac
-  mkdir -p "$(dirname "$dest")"
-  python3 - "$arg" "$dest" <<'PYTHON'
+flatten() {
+  python3 - "$1" "$2" <<'PYTHON'
 import re
 import sys
 
 src, dest = sys.argv[1], sys.argv[2]
-with open(src) as fh:
+# surrogateescape keeps a non-UTF-8 file (reachable via a directory argument)
+# a byte-for-byte round trip instead of aborting the whole run on a decode error.
+with open(src, encoding='utf-8', errors='surrogateescape') as fh:
     content = fh.read()
 
 fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
@@ -163,15 +164,60 @@ if fm_match:
             new_fm = fm[:start] + f'description: {flat_q}\n{pad}' + fm[end:]
             content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
 
-with open(dest, 'w') as fh:
+with open(dest, 'w', encoding='utf-8', errors='surrogateescape') as fh:
     fh.write(content)
 PYTHON
+}
+
+tmpdir="$(cd "$(mktemp -d)" && pwd -P)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+# Mirror of the caller's cwd inside the scratch tree; relative path arguments
+# are resolved from here.
+mirror="$tmpdir$cwd"
+mkdir -p "$mirror"
+
+argv_paths=()
+for arg in "${path_args[@]}"; do
   if [[ "$arg" == /* ]]; then
-    argv_files+=("$dest")
+    dest="$tmpdir$arg"
   else
-    argv_files+=("$arg")
+    dest="$mirror/$arg"
+  fi
+  dest="$(abspath "$dest")"
+  # A path argument with enough leading `..` to climb past the mirror root would
+  # write outside the scratch dir. The real filesystem clamps such a path at
+  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
+  case "$dest" in
+    "$tmpdir"/*) ;;
+    *)
+      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
+      exit 2
+      ;;
+  esac
+  mkdir -p "$(dirname "$dest")"
+  if [[ -d "$arg" ]]; then
+    # A directory is mirrored whole — vale applies its own format filtering to
+    # the tree, so any file dropped here would be silently unlinted — and then
+    # every markdown file in the copy is flattened in place. `.git` is pruned:
+    # vale never lints it and copying it can dwarf the rest of the tree.
+    mkdir -p "$dest"
+    while IFS= read -r -d '' rel; do
+      mkdir -p "$dest/$(dirname "$rel")"
+      cp "$arg/$rel" "$dest/$rel"
+    done < <(cd "$arg" && find . -name .git -prune -o -type f -print0)
+    while IFS= read -r -d '' md; do
+      flatten "$md" "$md"
+    done < <(find "$dest" -type f -name '*.md' -print0)
+  else
+    flatten "$arg" "$dest"
+  fi
+  if [[ "$arg" == /* ]]; then
+    argv_paths+=("$dest")
+  else
+    argv_paths+=("$arg")
   fi
 done
 
 cd "$mirror"
-vale "${vale_args[@]}" "${argv_files[@]}"
+vale "${vale_args[@]}" "${argv_paths[@]}"
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
index 918f32e..9e22cb8 100755
--- a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
@@ -9,26 +9,35 @@ set -euo pipefail
 # the real `vale` binary against the copies. Drop-in replacement for calling
 # `vale` directly: same args, same exit code.
 #
-# "Same args" means relative paths — `--config` values and file arguments alike
+# "Same args" means relative paths — `--config` values and path arguments alike
 # — resolve against the caller's current directory, exactly as bare `vale`
 # resolves them. (An earlier version resolved them against the repo root, an
 # invented convention that hard-errored on `--config ../../.vale.ini` from a
 # subdirectory and, worse, silently dropped file arguments that didn't happen to
 # resolve from the repo root — skipping the flattening this script exists for.)
 #
-# Vale prints each file path exactly as it was handed to it, so the scratch tree
-# mirrors the caller's absolute cwd: a relative file argument is passed through
+# The one addition to bare `vale`'s argument handling: with no `--config` at
+# all, this script's own sibling `assets/vale/.vale.ini` is used instead of
+# vale's upward search. pre-commit prefixes only `entry[0]` with the hook-repo
+# clone path, so a `--config` in `.pre-commit-hooks.yaml` would resolve against
+# the *consuming* repo and hard-fail (E100) for every external consumer. The
+# manifest therefore passes the script alone, and an explicit `--config` from
+# any other caller still wins.
+#
+# Vale prints each path exactly as it was handed to it, so the scratch tree
+# mirrors the caller's absolute cwd: a relative path argument is passed through
 # verbatim and resolves to its flattened copy, keeping the report byte-identical
-# to bare `vale`'s. An absolute file argument inside the cwd is relativized to
-# keep that property. Only an absolute path outside the cwd is rewritten to its
-# scratch copy and so reports a scratch path — unavoidable, since a file can
-# only be read from where it actually is.
+# to bare `vale`'s. An absolute path inside the cwd is relativized to keep that
+# property. Only an absolute path outside the cwd is rewritten to its scratch
+# copy and so reports a scratch path — unavoidable, since a file can only be
+# read from where it actually is.
 
 cwd="$(pwd -P)"
 
 vale_args=()
-file_args=()
+path_args=()
 config_next=false
+config_given=false
 for arg in "$@"; do
   if [[ "$config_next" == true ]]; then
     config_next=false
@@ -43,19 +52,24 @@ for arg in "$@"; do
     --config)
       vale_args+=("$arg")
       config_next=true
+      config_given=true
       continue
       ;;
     --config=/*)
       vale_args+=("$arg")
+      config_given=true
       continue
       ;;
     --config=*)
       vale_args+=("--config=$cwd/${arg#--config=}")
+      config_given=true
       continue
       ;;
   esac
-  # `-f` resolves relative paths against the caller's cwd, same as vale does.
-  if [[ "$arg" != -* && -f "$arg" ]]; then
+  # `-f`/`-d` resolve relative paths against the caller's cwd, same as vale does.
+  # A path that doesn't exist is left for vale to report on, exactly as bare
+  # vale would.
+  if [[ "$arg" != -* && ( -f "$arg" || -d "$arg" ) ]]; then
     # An absolute path inside the caller's cwd is relativized so the report cites
     # a path that resolves against the real tree. Left absolute, it would be
     # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
@@ -63,54 +77,41 @@ for arg in "$@"; do
     # quoting it. Absolute paths outside the cwd have no relative form and keep
     # the scratch-path behaviour documented above.
     if [[ "$arg" == "$cwd"/* ]]; then
-      file_args+=("${arg#"$cwd"/}")
+      path_args+=("${arg#"$cwd"/}")
     else
-      file_args+=("$arg")
+      path_args+=("$arg")
     fi
   else
     vale_args+=("$arg")
   fi
 done
 
-if [[ ${#file_args[@]} -eq 0 ]]; then
+if [[ "$config_given" == false ]]; then
+  vale_args+=(--config "$(cd "$(dirname "${BASH_SOURCE[0]}")/../assets/vale" && pwd)/.vale.ini")
+fi
+
+if [[ ${#path_args[@]} -eq 0 ]]; then
   # Nothing to flatten. Hand off directly, with stdin closed so vale doesn't
   # block waiting on a pipe that will never carry content.
   exec vale "${vale_args[@]}" < /dev/null
 fi
 
-tmpdir="$(realpath -m "$(mktemp -d)")"
-trap 'rm -rf "$tmpdir"' EXIT
+# `realpath -m` would be the obvious normalizer, but `-m` (canonicalize-missing)
+# is a GNU extension the BSD realpath on macOS doesn't have — and every dest
+# below is a path that doesn't exist yet. python3 is already a hard dependency.
+abspath() {
+  python3 -c 'import os, sys; print(os.path.abspath(sys.argv[1]))' "$1"
+}
 
-# Mirror of the caller's cwd inside the scratch tree; relative file arguments
-# are resolved from here.
-mirror="$tmpdir$cwd"
-mkdir -p "$mirror"
-
-argv_files=()
-for arg in "${file_args[@]}"; do
-  if [[ "$arg" == /* ]]; then
-    dest="$tmpdir$arg"
-  else
-    dest="$mirror/$arg"
-  fi
-  dest="$(realpath -m "$dest")"
-  # A file argument with enough leading `..` to climb past the mirror root would
-  # write outside the scratch dir. The real filesystem clamps such a path at
-  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
-  case "$dest" in
-    "$tmpdir"/*) ;;
-    *)
-      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
-      exit 2
-      ;;
-  esac
-  mkdir -p "$(dirname "$dest")"
-  python3 - "$arg" "$dest" <<'PYTHON'
+flatten() {
+  python3 - "$1" "$2" <<'PYTHON'
 import re
 import sys
 
 src, dest = sys.argv[1], sys.argv[2]
-with open(src) as fh:
+# surrogateescape keeps a non-UTF-8 file (reachable via a directory argument)
+# a byte-for-byte round trip instead of aborting the whole run on a decode error.
+with open(src, encoding='utf-8', errors='surrogateescape') as fh:
     content = fh.read()
 
 fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
@@ -163,15 +164,60 @@ if fm_match:
             new_fm = fm[:start] + f'description: {flat_q}\n{pad}' + fm[end:]
             content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
 
-with open(dest, 'w') as fh:
+with open(dest, 'w', encoding='utf-8', errors='surrogateescape') as fh:
     fh.write(content)
 PYTHON
+}
+
+tmpdir="$(cd "$(mktemp -d)" && pwd -P)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+# Mirror of the caller's cwd inside the scratch tree; relative path arguments
+# are resolved from here.
+mirror="$tmpdir$cwd"
+mkdir -p "$mirror"
+
+argv_paths=()
+for arg in "${path_args[@]}"; do
   if [[ "$arg" == /* ]]; then
-    argv_files+=("$dest")
+    dest="$tmpdir$arg"
   else
-    argv_files+=("$arg")
+    dest="$mirror/$arg"
+  fi
+  dest="$(abspath "$dest")"
+  # A path argument with enough leading `..` to climb past the mirror root would
+  # write outside the scratch dir. The real filesystem clamps such a path at
+  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
+  case "$dest" in
+    "$tmpdir"/*) ;;
+    *)
+      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
+      exit 2
+      ;;
+  esac
+  mkdir -p "$(dirname "$dest")"
+  if [[ -d "$arg" ]]; then
+    # A directory is mirrored whole — vale applies its own format filtering to
+    # the tree, so any file dropped here would be silently unlinted — and then
+    # every markdown file in the copy is flattened in place. `.git` is pruned:
+    # vale never lints it and copying it can dwarf the rest of the tree.
+    mkdir -p "$dest"
+    while IFS= read -r -d '' rel; do
+      mkdir -p "$dest/$(dirname "$rel")"
+      cp "$arg/$rel" "$dest/$rel"
+    done < <(cd "$arg" && find . -name .git -prune -o -type f -print0)
+    while IFS= read -r -d '' md; do
+      flatten "$md" "$md"
+    done < <(find "$dest" -type f -name '*.md' -print0)
+  else
+    flatten "$arg" "$dest"
+  fi
+  if [[ "$arg" == /* ]]; then
+    argv_paths+=("$dest")
+  else
+    argv_paths+=("$arg")
   fi
 done
 
 cd "$mirror"
-vale "${vale_args[@]}" "${argv_files[@]}"
+vale "${vale_args[@]}" "${argv_paths[@]}"
diff --git a/tests/run-tests.sh b/tests/run-tests.sh
index 51464ab..1f3c067 100755
--- a/tests/run-tests.sh
+++ b/tests/run-tests.sh
@@ -2,6 +2,9 @@
 # Run all test-*.sh files in the repo (including plugins) and the bats suite.
 # Usage: bash tests/run-tests.sh [--bats-only]
 #
+# A script exiting 77 (the automake convention) is reported as SKIPPED, not
+# passed — a suite that can't run for lack of a binary must not read as green.
+#
 # TEST_DIR — override root to search for test-*.sh (default: REPO_ROOT); used by tests.
 set -euo pipefail
 
@@ -13,7 +16,9 @@ BATS_ONLY=false
 SEARCH_ROOT="${TEST_DIR:-$REPO_ROOT}"
 
 FAILED=()
+SKIPPED=()
 PASSED=0
+SKIP_EXIT=77
 
 run_bats() {
   if [[ -x "$BATS" ]]; then
@@ -40,15 +45,25 @@ mapfile -t SCRIPTS < <(
 for script in "${SCRIPTS[@]}"; do
   rel="${script#"$SEARCH_ROOT/"}"
   echo "=== $rel ==="
-  if bash "$script"; then
+  rc=0
+  bash "$script" || rc=$?
+  if [[ $rc -eq 0 ]]; then
     PASSED=$((PASSED + 1))
+  elif [[ $rc -eq $SKIP_EXIT ]]; then
+    SKIPPED+=("$rel")
   else
     FAILED+=("$rel")
   fi
   echo ""
 done
 
-echo "=== Summary: $PASSED passed, ${#FAILED[@]} failed ==="
+echo "=== Summary: $PASSED passed, ${#SKIPPED[@]} skipped, ${#FAILED[@]} failed ==="
+if [[ ${#SKIPPED[@]} -gt 0 ]]; then
+  echo "Skipped scripts:"
+  for s in "${SKIPPED[@]}"; do
+    echo "  $s"
+  done
+fi
 if [[ ${#FAILED[@]} -gt 0 ]]; then
   echo "Failed scripts:"
   for s in "${FAILED[@]}"; do
diff --git a/tests/test-vale-hooks-consumer.sh b/tests/test-vale-hooks-consumer.sh
new file mode 100755
index 0000000..ef05a51
--- /dev/null
+++ b/tests/test-vale-hooks-consumer.sh
@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Integration test for .pre-commit-hooks.yaml as an EXTERNAL hook repo — the
+# contract ADR-0014 exists to provide, and the one thing running pre-commit
+# inside this repo can never exercise: `repo: local` makes pre-commit's clone
+# prefix equal to the consuming repo's root, so a hook entry that only works
+# because those two coincide passes here and hard-fails everywhere else.
+# (It did: every argument after entry[0] resolves against the CONSUMING repo,
+# so a `--config plugins/.../.vale.ini` argument gave external consumers
+# `E100 [--config] Runtime error ... does not exist`, exit 2, on both Vale hooks.)
+#
+# The hook repo is built from the WORKING TREE, not from HEAD, so an uncommitted
+# change to the manifest or the wrapper is what gets tested.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PASS=0
+FAIL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+for bin in pre-commit vale git; do
+  if ! command -v "$bin" &>/dev/null; then
+    echo "SKIP: $bin is not installed — cannot stand up a consumer repo"
+    exit 77
+  fi
+done
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+HOOK_REPO="$WORK/hookrepo"
+CONSUMER="$WORK/consumer"
+export PRE_COMMIT_HOME="$WORK/pc-home"
+
+mkdir -p "$HOOK_REPO/plugins/kyberforge/skills" "$HOOK_REPO/scripts"
+cp "$REPO_ROOT/.pre-commit-hooks.yaml" "$HOOK_REPO/"
+cp "$REPO_ROOT/scripts/skill-size-check.sh" "$HOOK_REPO/scripts/"
+for skill in skill-audit agent-audit; do
+  mkdir -p "$HOOK_REPO/plugins/kyberforge/skills/$skill"
+  cp -R "$REPO_ROOT/plugins/kyberforge/skills/$skill/scripts" \
+    "$REPO_ROOT/plugins/kyberforge/skills/$skill/assets" \
+    "$HOOK_REPO/plugins/kyberforge/skills/$skill/"
+done
+git -C "$HOOK_REPO" init -q
+git -C "$HOOK_REPO" add -A
+git -C "$HOOK_REPO" -c user.email=test@example.invalid -c user.name=test commit -qm "hook repo"
+HOOK_REV="$(git -C "$HOOK_REPO" rev-parse HEAD)"
+
+# The two Vale hooks scope by filename, so the consumer needs one file of each
+# shape: a hook with nothing to match reports `Skipped` and proves nothing.
+mkdir -p "$CONSUMER/skills/demo" "$CONSUMER/agents"
+git -C "$CONSUMER" init -q
+cat > "$CONSUMER/.pre-commit-config.yaml" <<EOF
+repos:
+  - repo: file://$HOOK_REPO
+    rev: $HOOK_REV
+    hooks:
+      - id: kyberforge-vale-audit-skill
+      - id: kyberforge-vale-audit-agent
+EOF
+
+write_fixtures() {
+  local body="$1"
+  cat > "$CONSUMER/skills/demo/SKILL.md" <<EOF
+---
+name: demo
+description: >
+  Use when the caller wants a demonstration skill $body across two
+  physical lines of one folded block scalar.
+---
+
+Body.
+EOF
+  cat > "$CONSUMER/agents/demo.md" <<EOF
+---
+name: demo
+description: >
+  Use when the caller wants a demonstration agent $body across two
+  physical lines of one folded block scalar.
+---
+
+Body.
+EOF
+  git -C "$CONSUMER" add -A
+}
+
+run_hooks() {
+  (cd "$CONSUMER" && pre-commit run --all-files 2>&1) || true
+}
+
+# --- 1. Both hooks resolve their config and actually gate on a bad file ---
+echo ""
+echo "--- both Vale hooks run and fail a bad file in an external consumer repo ---"
+write_fixtures "that helps with and utilize things"
+OUT_BAD="$(run_hooks)"
+if echo "$OUT_BAD" | grep -q "does not exist"; then
+  fail "hooks hard-errored on a path resolved against the consumer repo (E100) — the bug this test guards against"
+  echo "$OUT_BAD" | sed 's/^/    /'
+elif echo "$OUT_BAD" | grep -q "Skipped"; then
+  fail "a hook matched no files, so it proved nothing"
+  echo "$OUT_BAD" | sed 's/^/    /'
+elif [[ "$(echo "$OUT_BAD" | grep -c "VagueWording")" -ge 2 ]]; then
+  pass "both hooks flatten and flag the folded description in a consumer repo"
+else
+  fail "hooks did not flag both fixtures"
+  echo "$OUT_BAD" | sed 's/^/    /'
+fi
+
+# --- 2. Clean files pass — the hooks gate, they don't just always fail ---
+echo ""
+echo "--- both Vale hooks pass clean files in an external consumer repo ---"
+write_fixtures "of the packaged hook contract"
+set +e
+(cd "$CONSUMER" && pre-commit run --all-files > "$WORK/clean.log" 2>&1)
+RC_CLEAN=$?
+set -e
+if [[ $RC_CLEAN -eq 0 ]]; then
+  pass "both hooks exit 0 on clean files"
+else
+  fail "hooks failed on clean files (rc=$RC_CLEAN)"
+  sed 's/^/    /' "$WORK/clean.log"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]]
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index c6f057a..9816125 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -19,8 +19,8 @@ pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
 fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
 
 if ! command -v vale &>/dev/null; then
-  echo "vale is not installed — skipping (matches skill-audit/agent-audit's own fallback behavior)"
-  exit 0
+  echo "SKIP: vale is not installed — skipping (matches skill-audit/agent-audit's own fallback behavior)"
+  exit 77
 fi
 
 make_fixture() {
@@ -345,6 +345,86 @@ else
   fail "wrapper altered output for a literal (|) block scalar description — should be left untouched"
 fi
 
+# --- 12. With no --config at all, the wrapper falls back to its own sibling
+# assets/vale/.vale.ini. `.pre-commit-hooks.yaml` relies on this: pre-commit
+# prefixes only entry[0] with the hook-repo clone path, so a --config argument
+# there resolves against the consuming repo and hard-errors (E100) for every
+# external consumer.
+echo ""
+echo "--- defaults --config to the wrapper's own sibling assets/vale/.vale.ini ---"
+FIXTURE12="$(make_fixture 2)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11" "$FIXTURE12"' EXIT
+OUT12=$(run_wrap "$FIXTURE12" plugins/testplugin/skills/zzzskill/SKILL.md)
+if echo "$OUT12" | grep -q "VagueWording"; then
+  pass "a --config-less invocation uses the wrapper's bundled config"
+else
+  fail "a --config-less invocation found no config — external pre-commit consumers get E100, the bug this test guards against"
+fi
+
+# --- 13. No GNU-only `realpath -m`. macOS ships the BSD realpath, which has no
+# -m (canonicalize-missing) — and every scratch destination is a path that does
+# not exist yet, so a plain `realpath` exits 1 and set -e aborts the hook.
+echo ""
+echo "--- runs with a BSD realpath that has no -m option ---"
+STUB13="$(mktemp -d)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11" "$FIXTURE12" "$STUB13"' EXIT
+REAL_REALPATH="$(command -v realpath || echo /bin/false)"
+cat > "$STUB13/realpath" <<EOF
+#!/usr/bin/env bash
+for a in "\$@"; do
+  case "\$a" in
+    -m|--canonicalize-missing)
+      echo "realpath: illegal option -- m" >&2
+      exit 1
+      ;;
+  esac
+done
+exec "$REAL_REALPATH" "\$@"
+EOF
+chmod +x "$STUB13/realpath"
+OUT13=$(cd "$FIXTURE12" && PATH="$STUB13:$PATH" bash "$SCRIPT" --config "$VALE_CONFIG" \
+  plugins/testplugin/skills/zzzskill/SKILL.md 2>&1 || true)
+if echo "$OUT13" | grep -q "illegal option"; then
+  fail "invoked realpath -m — fails on macOS's BSD realpath, the bug this test guards against"
+elif echo "$OUT13" | grep -q "VagueWording"; then
+  pass "flattens and flags with no GNU realpath available"
+else
+  fail "produced no alert under a BSD-style realpath: $OUT13"
+fi
+
+# --- 14. A directory argument is walked and its files flattened. The classifier
+# used to accept only regular files, so a directory fell through to the vale
+# flag list, left the file list empty, and exec'd bare vale — silently skipping
+# the flattening. `lint`'s vale-run skill documents `vale <path-or-glob>` as
+# normal usage, so this is a reachable path.
+echo ""
+echo "--- flattens files reached through a directory argument ---"
+FIXTURE14="$(make_fixture 2)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11" "$FIXTURE12" "$STUB13" "$FIXTURE14"' EXIT
+WRAPPED_DIR=$(run_wrap "$FIXTURE14" --config "$VALE_CONFIG" plugins)
+BARE_DIR=$(cd "$FIXTURE14" && vale --config "$VALE_CONFIG" plugins 2>&1 || true)
+if ! echo "$WRAPPED_DIR" | grep -q "VagueWording"; then
+  fail "a directory argument produced no alert — flattening was silently skipped, the bug this test guards against"
+elif echo "$BARE_DIR" | grep -q "VagueWording"; then
+  fail "bare vale already flags this fixture, so the test can't detect a silently-skipped flattening"
+else
+  pass "a directory argument is walked and its files flattened"
+fi
+
+# --- 15. Directory walking must survive paths with spaces ---
+echo ""
+echo "--- walks a directory containing a path with spaces ---"
+SPACED15="$FIXTURE14/plugins/testplugin/skills/zzz skill"
+mkdir -p "$SPACED15"
+cp "$FIXTURE14/plugins/testplugin/skills/zzzskill/SKILL.md" "$SPACED15/SKILL.md"
+rm -rf "$FIXTURE14/plugins/testplugin/skills/zzzskill"
+OUT15=$(run_wrap "$FIXTURE14" --config "$VALE_CONFIG" plugins/testplugin/skills)
+if echo "$OUT15" | grep -q "zzz skill" && echo "$OUT15" | grep -q "VagueWording"; then
+  pass "a file under a directory whose name contains a space is walked and flattened"
+else
+  fail "a path with a space was dropped from the directory walk"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 714e8a0c78cd7bdf09433f25f1abd915ea2ae632 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:06:36 +0000
Subject: [PATCH 21/45] fix(lint): fail the style-sync check when one copy is
 missing

The guard used `||`, so exactly one of the two audit skill directories
missing also exited 0, where the intended silent no-op is both absent.
A renamed skill-audit reported green instead of flagging that a
canonical style copy had lost its counterpart.

One-present now exits 1 naming the missing side and the remedy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 scripts/check-vale-style-sync.sh    | 14 +++++++++++++-
 tests/test-check-vale-style-sync.sh | 21 +++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh
index 029bb92..4f9dd1c 100755
--- a/scripts/check-vale-style-sync.sh
+++ b/scripts/check-vale-style-sync.sh
@@ -17,10 +17,22 @@ err() { echo "  FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
 SKILL_AUDIT="$REPO_ROOT/plugins/kyberforge/skills/skill-audit"
 AGENT_AUDIT="$REPO_ROOT/plugins/kyberforge/skills/agent-audit"
 
-if [[ ! -d "$SKILL_AUDIT" || ! -d "$AGENT_AUDIT" ]]; then
+if [[ ! -d "$SKILL_AUDIT" && ! -d "$AGENT_AUDIT" ]]; then
   exit 0
 fi
 
+# Exactly one present is drift, not absence: the missing copy can't be in sync
+# with the surviving one, and treating it as a no-op is how a deleted or
+# renamed copy would slip through silently.
+if [[ ! -d "$SKILL_AUDIT" ]]; then
+  echo "Vale style sync check failed: $AGENT_AUDIT exists but $SKILL_AUDIT does not — run scripts/sync-vale-styles.sh to regenerate skill-audit's copy." >&2
+  exit 1
+fi
+if [[ ! -d "$AGENT_AUDIT" ]]; then
+  echo "Vale style sync check failed: $SKILL_AUDIT exists but $AGENT_AUDIT does not — agent-audit holds the canonical copy, so restore it before syncing." >&2
+  exit 1
+fi
+
 if ! diff -q "$SKILL_AUDIT/scripts/vale-wrap.sh" "$AGENT_AUDIT/scripts/vale-wrap.sh" >/dev/null 2>&1; then
   err "scripts/vale-wrap.sh differs between skill-audit and agent-audit"
 fi
diff --git a/tests/test-check-vale-style-sync.sh b/tests/test-check-vale-style-sync.sh
index d822e4b..a0d82b1 100755
--- a/tests/test-check-vale-style-sync.sh
+++ b/tests/test-check-vale-style-sync.sh
@@ -86,6 +86,27 @@ else
   fail "exited non-zero when skill-audit/agent-audit are simply absent"
 fi
 
+# --- 6. Exits 1 when only one of the two copies is present ---
+# The no-op guard used `||`, so a single missing copy also exited 0 — a deleted
+# or renamed copy passed the sync check silently.
+echo ""
+echo "--- exits 1 when only one of the two copies is present ---"
+FIXTURE6="$(make_fixture)"
+FIXTURE7="$(make_fixture)"
+trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7"' EXIT
+rm -rf "$FIXTURE6/plugins/kyberforge/skills/skill-audit"
+rm -rf "$FIXTURE7/plugins/kyberforge/skills/agent-audit"
+if bash "$SCRIPT" "$FIXTURE6" > /dev/null 2>&1; then
+  fail "exited 0 when only agent-audit is present — expected exit 1"
+else
+  pass "exits non-zero when skill-audit's copy is missing but agent-audit's is present"
+fi
+if bash "$SCRIPT" "$FIXTURE7" > /dev/null 2>&1; then
+  fail "exited 0 when only skill-audit is present — expected exit 1"
+else
+  pass "exits non-zero when agent-audit's canonical copy is missing but skill-audit's is present"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 348dd9f6654606073a81fe1cc649f1f5e15c674f Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:06:37 +0000
Subject: [PATCH 22/45] fix(lint): restore release-gate coverage of bundled
 Vale assets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The gate derived release-relevant paths from the dirname of each
entry's --config target. Dropping --config from .pre-commit-hooks.yaml
left that loop dead, silently removing both assets/vale/ trees from
coverage — a Vale rule change could land on main without demanding a
release tag, leaving consumers pinned to an old rev: with stale rules.

Coverage now derives from tokens[0] instead: double-dirname for the ..
normalization, guarded on the tree existing and on the bundle root not
resolving to "." so skill-size-check.sh cannot invent a bogus path.

The --config branch is removed rather than kept as dead code. Since
pre-commit rewrites only entry[0], no argument in any entry can ever
name a file this repo ships, so that shape is broken by design.

Known gap: deleting a hook's entire assets/ tree is not flagged, as the
candidate path stops existing. Deletions within a surviving tree are.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 scripts/check-release-needed.sh    | 26 +++++++---
 tests/test-check-release-needed.sh | 79 +++++++++++++++++++++++-------
 2 files changed, 80 insertions(+), 25 deletions(-)

diff --git a/scripts/check-release-needed.sh b/scripts/check-release-needed.sh
index 8f1f285..cc1927f 100755
--- a/scripts/check-release-needed.sh
+++ b/scripts/check-release-needed.sh
@@ -34,19 +34,29 @@ fi
 # instead of hand-maintaining a parallel list — the manifest is the single
 # source of truth for what external consumers actually pull at a pinned rev,
 # so a hook added/removed/renamed there can't silently drift out of sync here.
-# Each entry is "<script> [--config <path>] [...]"; the script itself and the
-# directory holding any --config target (vale-wrap.sh needs its .vale.ini's
-# sibling styles/ tree, not just the ini file) are release-relevant.
+# Everything is derived from tokens[0], the hook's script: pre-commit prefixes
+# only entry[0] with the hook-repo clone path, so any later token that looks
+# like a path resolves against the *consuming* repo and can never name a file
+# this repo ships. A hook's bundled data therefore has to be self-located
+# relative to the script — vale-wrap.sh reads its own
+# <script-dir>/../assets/vale/.vale.ini plus the sibling styles/ tree — which
+# makes <script-dir>/../assets release-relevant alongside the script itself.
+# The ../ is normalised by stripping a path component rather than with
+# `realpath -m`, which is a GNU-only extension. Two guards keep the derivation
+# from inventing paths: a bundle root of "." is skipped, because a script in a
+# top-level directory (scripts/skill-size-check.sh) would derive the repo's own
+# shared assets/, which no hook owns and whose churn must not demand a release;
+# and the directory is added only when it exists, since a hook that bundles
+# nothing must not contribute a pathspec matching nothing.
 RELEASE_PATHS=("$HOOKS_MANIFEST")
 while IFS= read -r entry; do
   read -ra tokens <<< "$entry"
   [[ ${#tokens[@]} -eq 0 ]] && continue
   RELEASE_PATHS+=("${tokens[0]}")
-  for ((i = 1; i < ${#tokens[@]}; i++)); do
-    if [[ "${tokens[i]}" == "--config" && -n "${tokens[i + 1]:-}" ]]; then
-      RELEASE_PATHS+=("$(dirname "${tokens[i + 1]}")")
-    fi
-  done
+  bundle_root="$(dirname "$(dirname "${tokens[0]}")")"
+  if [[ "$bundle_root" != "." && -d "$bundle_root/assets" ]]; then
+    RELEASE_PATHS+=("$bundle_root/assets")
+  fi
 done < <(sed -n 's/^[[:space:]]*entry:[[:space:]]*//p' "$HOOKS_MANIFEST")
 
 # Only vX.Y.Z release tags count as a baseline — an incidental checkpoint or
diff --git a/tests/test-check-release-needed.sh b/tests/test-check-release-needed.sh
index 8a53f25..ba473bf 100755
--- a/tests/test-check-release-needed.sh
+++ b/tests/test-check-release-needed.sh
@@ -9,32 +9,45 @@ FAIL=0
 pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
 fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
 
-# Helper: write a minimal .pre-commit-hooks.yaml exposing one script entry and
-# one --config-bearing entry, so RELEASE_PATHS (derived from the manifest, not
-# hand-maintained) has both shapes to parse.
+# Both entry shapes the real .pre-commit-hooks.yaml ships: a bare script with no
+# bundled data, and a bare script whose sibling assets/ tree it self-locates at
+# runtime. Neither carries arguments — pre-commit only rewrites entry[0] to the
+# hook-repo clone path, so an argument path would resolve against the consuming
+# repo. RELEASE_PATHS is derived from the manifest rather than hand-maintained,
+# so it has to cope with both.
+HOOK_DIR="plugins/demo/skills/demo-audit"
+
 write_manifest() {
   local dir="$1"
-  mkdir -p "$dir/vale"
-  cat > "$dir/.pre-commit-hooks.yaml" <<'EOF'
+  cat > "$dir/.pre-commit-hooks.yaml" <<EOF
 -   id: fake-size-check
     entry: scripts/skill-size-check.sh
     language: script
 -   id: fake-vale-check
-    entry: scripts/vale-wrap.sh --config vale/.vale.ini
+    entry: $HOOK_DIR/scripts/vale-wrap.sh
     language: script
 EOF
 }
 
-# Helper: a fixture repo with a manifest and its two referenced release-relevant
-# paths, committed and tagged v1.0.0.
+# Helper: writes the files both manifest entries expose — the two hook scripts
+# plus the bundled Vale config and style rule the second one self-locates.
+write_release_paths() {
+  local dir="$1"
+  mkdir -p "$dir/scripts" "$dir/$HOOK_DIR/scripts" "$dir/$HOOK_DIR/assets/vale/styles/Kyberforge"
+  echo "v1" > "$dir/scripts/skill-size-check.sh"
+  echo "v1" > "$dir/$HOOK_DIR/scripts/vale-wrap.sh"
+  echo "cfg" > "$dir/$HOOK_DIR/assets/vale/.vale.ini"
+  echo "rule: v1" > "$dir/$HOOK_DIR/assets/vale/styles/Kyberforge/DemoRule.yml"
+}
+
+# Helper: a fixture repo with a manifest and every release-relevant path it
+# exposes, committed and tagged v1.0.0.
 make_tagged_fixture() {
   local dir
   dir="$(mktemp -d)"
   (cd "$dir" && git init -q && git config user.email t@t.t && git config user.name t)
   write_manifest "$dir"
-  mkdir -p "$dir/scripts"
-  echo "v1" > "$dir/scripts/skill-size-check.sh"
-  echo "cfg" > "$dir/vale/.vale.ini"
+  write_release_paths "$dir"
   (cd "$dir" && git add -A && git commit -q -m "initial" && git tag v1.0.0)
   echo "$dir"
 }
@@ -65,9 +78,7 @@ echo "--- exits 1 when targeting main and no tag exists ---"
 FIXTURE2="$(mktemp -d)"; track "$FIXTURE2"
 (cd "$FIXTURE2" && git init -q && git config user.email t@t.t && git config user.name t)
 write_manifest "$FIXTURE2"
-mkdir -p "$FIXTURE2/scripts"
-echo "v1" > "$FIXTURE2/scripts/skill-size-check.sh"
-echo "cfg" > "$FIXTURE2/vale/.vale.ini"
+write_release_paths "$FIXTURE2"
 (cd "$FIXTURE2" && git add -A && git commit -q -m "initial")
 if run_check "$FIXTURE2" "refs/heads/main" > /dev/null; then
   fail "exited 0 when targeting main with no tag — expected exit 1"
@@ -116,10 +127,10 @@ fi
 echo ""
 echo "--- exits 1 when a release-relevant path was deleted since the tag, not just modified ---"
 FIXTURE6="$(make_tagged_fixture)"; track "$FIXTURE6"
-rm -rf "$FIXTURE6/vale"
-(cd "$FIXTURE6" && git add -A && git commit -q -m "delete the vale config dir")
+rm -f "$FIXTURE6/$HOOK_DIR/assets/vale/.vale.ini"
+(cd "$FIXTURE6" && git add -A && git commit -q -m "delete the bundled vale config")
 OUT6=$(run_check "$FIXTURE6" "refs/heads/main" || true)
-if echo "$OUT6" | grep -q "vale/.vale.ini"; then
+if echo "$OUT6" | grep -q "assets/vale/.vale.ini"; then
   pass "flags a deleted release-relevant path instead of silently dropping it from the diff"
 else
   fail "did not flag deletion of a release-relevant path since the tag"
@@ -166,6 +177,40 @@ else
   fail "flagged a file that no .pre-commit-hooks.yaml entry actually exposes"
 fi
 
+# --- 10. A change confined to a hook's bundled styles/ tree is release-relevant ---
+# The manifest entry names only the wrapper script; the Vale rules it enforces
+# live in the sibling assets/ tree it self-locates at runtime. If that tree is
+# not covered, editing a rule and landing it on main demands no new tag, and a
+# consumer pinned to the old rev keeps the stale rules forever.
+echo ""
+echo "--- exits 1 when only a bundled Vale style rule changed since the tag ---"
+FIXTURE10="$(make_tagged_fixture)"; track "$FIXTURE10"
+echo "rule: v2" > "$FIXTURE10/$HOOK_DIR/assets/vale/styles/Kyberforge/DemoRule.yml"
+(cd "$FIXTURE10" && git add -A && git commit -q -m "tighten a vale rule")
+OUT10=$(run_check "$FIXTURE10" "refs/heads/main" || true)
+if echo "$OUT10" | grep -q "assets/vale/styles/Kyberforge/DemoRule.yml"; then
+  pass "flags a change confined to a hook's bundled assets/vale/styles/ tree"
+else
+  fail "a bundled Vale style rule changed since the tag without demanding a release"
+fi
+
+# --- 11. The assets/ derivation must not invent a path for a bundle-less hook ---
+# scripts/skill-size-check.sh has no sibling assets/ tree, so its derived
+# candidate normalises to a bare top-level assets/ — a directory this repo does
+# not ship. Adding it unconditionally would make any unrelated repo-root
+# assets/ file falsely demand a release.
+echo ""
+echo "--- exits 0 when a top-level assets/ file changed but no hook bundles one ---"
+FIXTURE11="$(make_tagged_fixture)"; track "$FIXTURE11"
+mkdir -p "$FIXTURE11/assets"
+echo "unrelated" > "$FIXTURE11/assets/logo.txt"
+(cd "$FIXTURE11" && git add -A && git commit -q -m "add an unrelated top-level assets file")
+if run_check "$FIXTURE11" "refs/heads/main" > /dev/null; then
+  pass "exits 0 for a top-level assets/ file that no manifest entry bundles"
+else
+  fail "invented a bogus assets/ path for a hook script with no bundled tree"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From e9234f6d8a81e2c2112adeb971cf9875390590e3 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:06:52 +0000
Subject: [PATCH 23/45] docs(lint): correct the Vale exit-code and glob-scoping
 claims
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cli-reference.md said vale exits non-zero for any alert at or above
MinAlertLevel. The exit code keys on error-level alerts alone;
MinAlertLevel filters display only. LESSONS.md records this exact
misconception as costing two review rounds, and this research doc is
the cited provenance source for the skills that state it correctly.

CONTEXT.md claimed a SKILL.md outside plugins/ matches no glob section.
[**/SKILL.md] matches any path ending in SKILL.md — the sentence is a
stale leftover from the path-scoped globs at cbc33d9, and contradicted
its own paragraph two sentences earlier. The NOT-RUN 0-files guard it
justifies is correct and is unchanged; only the rationale was wrong.
CONTEXT.md also cited the local files: regex as the scoping mechanism,
where the shipped manifest deliberately stays layout-agnostic.

ADR-0014 records the entry[0]-only prefixing constraint as the reason
the self-locating design is required, and that no entry may grow a
repo-internal path argument.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 CONTEXT.md                                    |  2 +-
 ...14-vale-prefilter-ships-from-the-plugin.md | 49 ++++++++++++++++---
 .../docs/research/docs/vale/cli-reference.md  |  6 +--
 .../research/docs/vale/troubleshooting.md     |  4 +-
 4 files changed, 50 insertions(+), 11 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index 3667991..143bf74 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -72,7 +72,7 @@ A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running
 ### Vale audit prefilter (skill-audit / agent-audit)
 Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
 
-Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched; a relative `--config` path resolves against the caller's cwd, matching bare `vale`, not against the repo root. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` (split into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type) — and from the audit skills passing one explicit file per invocation. A skill outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) matches no glob section, so Vale reports 0 files and exits 0 — which the audits read as clean. Both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
+Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root; both audit skills' Step 1 still passes `--config assets/vale/.vale.ini` and is unaffected. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
 
 This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — failing only above 500 lines, matching `skill-audit/scripts/validate.sh`'s `<= 500` pass — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
 
diff --git a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
index 10ac2c0..ccdb972 100644
--- a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
+++ b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
@@ -55,11 +55,27 @@ define separate `-skill`/`-agent` hook IDs, each with a `files:` regex matching
 target copy's glob covers. (Confirmed empirically before deleting the root files: retargeting a
 single hook at agent-audit's copy silently scanned 0 SKILL.md files.)
 
+**The hook `entry:` is the wrapper alone; the wrapper self-locates its config.** pre-commit
+prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`);
+every later argument is handed to the process untouched and so resolves against the *consuming*
+repo's root. A `--config plugins/kyberforge/skills/…/assets/vale/.vale.ini` in
+`.pre-commit-hooks.yaml` therefore named a path no consumer has, and every external run died with
+`E100 [--config] Runtime error`. The external-consumer contract this ADR exists to establish
+cannot be expressed as a `--config` argument at all — the config path has to be derived inside
+the process, from the script's own location. `vale-wrap.sh` accordingly defaults to its sibling
+`assets/vale/.vale.ini`, resolved from `${BASH_SOURCE[0]}`, whenever no `--config` is supplied;
+an explicit `--config` from any other caller still wins and still resolves against the caller's
+cwd, so both audit skills' Step 1 (`--config assets/vale/.vale.ini`) is unaffected. Both
+manifests now carry the identical argument-free `entry:`. Keeping them identical is part of the
+decision: the local `repo: local` hook resolved its `--config` correctly only because the
+consuming repo *was* this repo, and that one difference is why three review rounds exercised a
+code path no external consumer ever takes.
+
 **Vale's `StylesPath` resolves relative to the `.vale.ini` file's own location**, confirmed
-against `docs.vale.sh/keys/stylespath` — so `--config <path-into-plugin>/.vale.ini` correctly
-finds that ini's sibling `styles/` regardless of the caller's cwd, with no extra path-juggling
-needed beyond what `vale-wrap.sh` already does for its cwd-relative `--config`/file-argument
-handling.
+against `docs.vale.sh/keys/stylespath` — so a config path into the plugin finds that ini's
+sibling `styles/` regardless of the caller's cwd, whether it arrives as an explicit `--config` or
+as the wrapper's self-located default. No extra path-juggling is needed beyond `vale-wrap.sh`'s
+cwd-relative `--config`/path-argument handling and that fallback.
 
 **A sync-check catches drift between the two copies.** `scripts/check-vale-style-sync.sh` diffs
 `scripts/vale-wrap.sh` and `assets/vale/styles/Kyberforge/` between skill-audit and agent-audit
@@ -91,8 +107,18 @@ doesn't wonder if it was overlooked.
 - Root `.vale.ini`, `styles/`, `scripts/vale-wrap.sh` are deleted. Two copies remain:
   `plugins/kyberforge/skills/agent-audit/assets/vale/` (canonical, superset) and
   `plugins/kyberforge/skills/skill-audit/assets/vale/` (subset, `Kyberforge` only).
-- `plugins/kyberforge`'s `plugin.json` and `.claude-plugin/plugin.json` both patch-bump to
-  `1.2.5` for the shipped content change (per ADR-0006's version-parity invariant).
+- `plugins/kyberforge`'s `plugin.json` and `.claude-plugin/plugin.json` both patch-bump for every
+  shipped content change (per ADR-0006's version-parity invariant): `1.2.5` for the relocation
+  itself, `1.2.6` for the self-locating `vale-wrap.sh` that followed.
+- **`.pre-commit-hooks.yaml` entries are a bare script path and nothing else — a constraint, not a
+  house style, and it binds every future hook here, not just the Vale two.** Since pre-commit
+  rewrites only `entry[0]` into the hook-repo clone, no argument token in any entry can reference
+  a file this repo ships: a relative path resolves against the *consuming* repo and hard-fails,
+  and the absolute path is unknowable at author time. A hook that needs one of its own bundled
+  files must have the script self-locate it from `$0`/`${BASH_SOURCE[0]}`, exactly as
+  `vale-wrap.sh` now does for `.vale.ini`. Anything else rediscovers this as another `E100`.
+  `.pre-commit-config.yaml` stays byte-identical to the shipped manifest on those `entry:` lines
+  so the local gate keeps exercising the same resolution path a consumer does.
 - `tests/test-vale-wrap.sh` now exercises skill-audit's copy specifically — its fixtures are all
   `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has the matching glob section.
 - The first `vX.Y.Z` tag is cut once this change and its tests pass, giving external
@@ -117,3 +143,14 @@ doesn't wonder if it was overlooked.
   as a separate piece of infrastructure, not fixed here. `RELEASE_PATHS` is derived from
   `.pre-commit-hooks.yaml`'s own `entry:` lines rather than hand-maintained, so at least the set of
   paths it checks can't drift from the manifest on its own.
+- **Dropping `--config` moved the release gate's path derivation too.** `check-release-needed.sh`
+  used to reach each hook's bundled assets through the `dirname` of its `--config` target. With
+  no `--config` token left, that loop went dead and silently dropped both `assets/vale/` trees
+  from release coverage — a Vale *rule* change could then land on `main` without demanding a tag,
+  leaving consumers pinned to an old `rev:` running stale rules while the gate stayed green. The
+  script now derives the bundle's `assets/` tree from `tokens[0]` instead (double-`dirname`,
+  guarded on the candidate existing and on not resolving to `.`), which is the only derivation
+  compatible with the argument-free `entry:` contract above.
+- **Accepted residual in the release gate:** deleting a hook's *entire* `assets/` tree is not
+  flagged — the derived candidate path stops existing, so the guard drops it before it reaches
+  the pathspec. Deleting individual files inside a surviving tree is flagged, and tested.
diff --git a/plugins/lint/docs/research/docs/vale/cli-reference.md b/plugins/lint/docs/research/docs/vale/cli-reference.md
index 7ed35fb..16b6fdb 100644
--- a/plugins/lint/docs/research/docs/vale/cli-reference.md
+++ b/plugins/lint/docs/research/docs/vale/cli-reference.md
@@ -19,11 +19,11 @@ Lints the given file(s)/glob against the styles configured in `.vale.ini`.
 | `vale sync` | Downloads and installs packages/styles declared in `.vale.ini`. Run after install and whenever `Packages` changes. |
 | `vale ls-config` | Prints the currently active, fully-resolved configuration as JSON. Useful for debugging what settings actually apply to a file. |
 | `--output=<style>` | Sets the output format/template: `line`, `JSON`, `CLI` (default), or a custom template. |
-| `--no-exit` | Suppresses the non-zero exit code Vale normally returns when alerts are found — useful in CI pipelines that shouldn't hard-fail on lint output. |
+| `--no-exit` | Suppresses the non-zero exit code Vale normally returns when `error`-level alerts are found — useful in CI pipelines that shouldn't hard-fail on lint output. |
 | `--ignore-syntax` | Treats input as plain, unformatted text, skipping syntax-aware parsing (Markdown/HTML/etc). |
-| `--minAlertLevel=<level>` | Overrides `MinAlertLevel` from the config for this run (`suggestion`, `warning`, `error`). |
+| `--minAlertLevel=<level>` | Overrides `MinAlertLevel` from the config for this run (`suggestion`, `warning`, `error`). Filters what is displayed; does not affect the exit code. |
 | `--version` | Prints the Vale binary version. |
 
 ## Exit Codes
 
-By default, `vale` exits non-zero when it finds any alert at or above `MinAlertLevel` — this is what makes it usable as a CI gate. Pass `--no-exit` to always exit `0` regardless of findings.
+By default, `vale` exits non-zero only when it finds at least one `error`-level alert — this is what makes it usable as a CI gate. `warning` and `suggestion` alerts are printed but still exit `0`, so a rule that must gate CI or a commit hook has to be `level: error`. `MinAlertLevel` and `--minAlertLevel` filter which alerts are displayed and never affect the exit code. Pass `--no-exit` to always exit `0` regardless of findings.
diff --git a/plugins/lint/docs/research/docs/vale/troubleshooting.md b/plugins/lint/docs/research/docs/vale/troubleshooting.md
index 818bea2..b5cd1ca 100644
--- a/plugins/lint/docs/research/docs/vale/troubleshooting.md
+++ b/plugins/lint/docs/research/docs/vale/troubleshooting.md
@@ -53,4 +53,6 @@ If a file's syntax-aware parsing produces noisy/incorrect results (e.g. an unsup
 
 ## CI Failing Unexpectedly
 
-If a CI job fails solely because Vale returns a non-zero exit code on found alerts (not because the content is actually wrong for that pipeline stage), add `--no-exit` rather than suppressing the rule itself — this preserves the lint output while not gating the build on it.
+If a CI job fails solely because Vale returns a non-zero exit code on `error`-level alerts (not because the content is actually wrong for that pipeline stage), add `--no-exit` rather than suppressing the rule itself — this preserves the lint output while not gating the build on it. Raising `MinAlertLevel` is not an alternative: it only filters which alerts print, so an `error`-level alert still exits non-zero.
+
+The mirror-image failure is a Vale gate that never fails. Only `error`-level alerts drive the exit code, so a `warning`- or `suggestion`-level rule prints its alert and still exits `0` — invisible in any CI stage that hides passing output. If a rule must block, give it `level: error`.
-- 
2.43.0


From cc5f366450ad8b93fbe6375cfe7d9627aa7da302 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:06:53 +0000
Subject: [PATCH 24/45] chore(plugins): patch-bump kyberforge and lint for
 shipped changes

kyberforge 1.2.5 -> 1.2.6 for the self-locating vale-wrap.sh.
lint 1.1.3 -> 1.1.4 for the corrected Vale exit-code semantics: a
consumer cached at 1.1.3 holds docs that lead to building a gate which
passes everything.

Both provider manifests bumped in parity per ADR-0006. Marketplace
entries carry no per-plugin version, so neither file changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 plugins/kyberforge/.claude-plugin/plugin.json | 2 +-
 plugins/kyberforge/plugin.json                | 2 +-
 plugins/lint/.claude-plugin/plugin.json       | 2 +-
 plugins/lint/plugin.json                      | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json
index 2a52749..2a76c69 100644
--- a/plugins/kyberforge/.claude-plugin/plugin.json
+++ b/plugins/kyberforge/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.2.5"
+  "version": "1.2.6"
 }
diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json
index aa0e590..367ddb4 100644
--- a/plugins/kyberforge/plugin.json
+++ b/plugins/kyberforge/plugin.json
@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.2.5"
+  "version": "1.2.6"
 }
diff --git a/plugins/lint/.claude-plugin/plugin.json b/plugins/lint/.claude-plugin/plugin.json
index a7c8ec4..81b9cf1 100644
--- a/plugins/lint/.claude-plugin/plugin.json
+++ b/plugins/lint/.claude-plugin/plugin.json
@@ -13,5 +13,5 @@
   ],
   "license": "MIT",
   "name": "lint",
-  "version": "1.1.3"
+  "version": "1.1.4"
 }
diff --git a/plugins/lint/plugin.json b/plugins/lint/plugin.json
index a531652..f4c1a12 100644
--- a/plugins/lint/plugin.json
+++ b/plugins/lint/plugin.json
@@ -18,5 +18,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.1.3"
+  "version": "1.1.4"
 }
-- 
2.43.0


From 14c2c91521080a06538d6a2db7afab141e13ac60 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:32:30 +0000
Subject: [PATCH 25/45] fix(lint): flag release-relevant paths retired since
 the last tag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Coverage was derived from the worktree alone, so the -d guard on a
hook's bundled assets/ tree meant deleting the whole tree removed it
from the pathspec instead of flagging it — the gate stayed silent
about a change that breaks every consumer at the next rev:.

The path set is now derived twice, from the worktree manifest and from
the manifest at $LAST_TAG, then unioned. A path the tag exposed but
HEAD no longer does is a removal pinned consumers must be told about;
a path only HEAD exposes is new contract surface. Both need flagging.

Fails closed on an unreadable tagged tree (shallow clone), and treats
a readable root tree with no manifest as "added since the tag".

tokens[0] needed no exit-code fix — it carries no existence guard, so
both deletion cases already exited non-zero. What was wrong was the
reporting: a fully retired hook could no longer be named in the
failure message. The tagged manifest fixes that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 scripts/check-release-needed.sh    | 82 +++++++++++++++++++++++-------
 tests/test-check-release-needed.sh | 57 +++++++++++++++++++++
 2 files changed, 122 insertions(+), 17 deletions(-)

diff --git a/scripts/check-release-needed.sh b/scripts/check-release-needed.sh
index cc1927f..63b1d3f 100755
--- a/scripts/check-release-needed.sh
+++ b/scripts/check-release-needed.sh
@@ -30,6 +30,16 @@ if [[ ! -f "$HOOKS_MANIFEST" ]]; then
   exit 0
 fi
 
+# Only vX.Y.Z release tags count as a baseline — an incidental checkpoint or
+# experiment tag reachable from HEAD must not shift the diff baseline.
+LAST_TAG="$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' 2>/dev/null || true)"
+
+if [[ -z "$LAST_TAG" ]]; then
+  echo "FAIL: no release tag exists yet, but .pre-commit-hooks.yaml already exposes hooks to external consumers." >&2
+  echo "  Fix: cut the first release tag (e.g. v1.0.0) before this lands on main." >&2
+  exit 1
+fi
+
 # Derive release-relevant paths from .pre-commit-hooks.yaml's own entry: lines
 # instead of hand-maintaining a parallel list — the manifest is the single
 # source of truth for what external consumers actually pull at a pinned rev,
@@ -46,26 +56,64 @@ fi
 # from inventing paths: a bundle root of "." is skipped, because a script in a
 # top-level directory (scripts/skill-size-check.sh) would derive the repo's own
 # shared assets/, which no hook owns and whose churn must not demand a release;
-# and the directory is added only when it exists, since a hook that bundles
-# nothing must not contribute a pathspec matching nothing.
+# and the assets/ directory is added only where it is known to exist, since a
+# hook that bundles nothing must not contribute a pathspec matching nothing.
 RELEASE_PATHS=("$HOOKS_MANIFEST")
-while IFS= read -r entry; do
-  read -ra tokens <<< "$entry"
-  [[ ${#tokens[@]} -eq 0 ]] && continue
-  RELEASE_PATHS+=("${tokens[0]}")
-  bundle_root="$(dirname "$(dirname "${tokens[0]}")")"
-  if [[ "$bundle_root" != "." && -d "$bundle_root/assets" ]]; then
-    RELEASE_PATHS+=("$bundle_root/assets")
-  fi
-done < <(sed -n 's/^[[:space:]]*entry:[[:space:]]*//p' "$HOOKS_MANIFEST")
 
-# Only vX.Y.Z release tags count as a baseline — an incidental checkpoint or
-# experiment tag reachable from HEAD must not shift the diff baseline.
-LAST_TAG="$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' 2>/dev/null || true)"
+add_release_path() {
+  local candidate="$1" existing
+  for existing in "${RELEASE_PATHS[@]}"; do
+    [[ "$existing" == "$candidate" ]] && return 0
+  done
+  RELEASE_PATHS+=("$candidate")
+}
 
-if [[ -z "$LAST_TAG" ]]; then
-  echo "FAIL: no release tag exists yet, but .pre-commit-hooks.yaml already exposes hooks to external consumers." >&2
-  echo "  Fix: cut the first release tag (e.g. v1.0.0) before this lands on main." >&2
+# $1 selects where the "does this hook bundle an assets/ tree?" guard looks:
+# "worktree" probes the filesystem, anything else is a rev whose tree is probed
+# with git plumbing. Reading entry lines from stdin keeps one derivation for
+# both the tagged manifest and the current one.
+collect_release_paths() {
+  local scope="$1" entry bundle_root
+  local -a tokens
+  while IFS= read -r entry; do
+    read -ra tokens <<< "$entry"
+    [[ ${#tokens[@]} -eq 0 ]] && continue
+    add_release_path "${tokens[0]}"
+    bundle_root="$(dirname "$(dirname "${tokens[0]}")")"
+    [[ "$bundle_root" == "." ]] && continue
+    if [[ "$scope" == "worktree" ]]; then
+      [[ -d "$bundle_root/assets" ]] && add_release_path "$bundle_root/assets"
+    else
+      git cat-file -e "$scope:$bundle_root/assets" 2>/dev/null && add_release_path "$bundle_root/assets"
+    fi
+  done
+  return 0
+}
+
+# The worktree alone is not enough: a path is release-relevant if it was part of
+# the contract at $LAST_TAG *or* is part of it at HEAD, so both trees have to be
+# derived and unioned. Deriving only from the worktree meant that deleting a
+# hook's entire assets/ tree made the `-d` guard drop the path from the pathspec
+# altogether, and the deletion — which breaks every consumer at the next rev —
+# diffed clean. The two manifests can genuinely disagree (an entry added,
+# removed, or renamed since the tag), and the union is the conservative side of
+# that disagreement: a path the tag exposed and HEAD no longer does is a removal
+# consumers must be told about, and a path only HEAD exposes is new contract
+# surface they cannot reach without a new tag. The union never over-fires on its
+# own, either — any manifest edit that makes the two disagree already changes
+# $HOOKS_MANIFEST, which is itself a release-relevant path.
+collect_release_paths worktree < <(sed -n 's/^[[:space:]]*entry:[[:space:]]*//p' "$HOOKS_MANIFEST")
+
+# A missing manifest at the tag is legitimate (the manifest was added since) but
+# is indistinguishable from an unreadable tagged tree by its exit status alone,
+# so the tag's root tree is verified separately. An absent tree object — a
+# shallow clone, a truncated fetch — fails closed exactly like a `git diff`
+# failure does, rather than silently degrading to worktree-only derivation.
+if MANIFEST_AT_TAG="$(git cat-file -p "$LAST_TAG:$HOOKS_MANIFEST" 2>/dev/null)"; then
+  collect_release_paths "$LAST_TAG" < <(printf '%s\n' "$MANIFEST_AT_TAG" | sed -n 's/^[[:space:]]*entry:[[:space:]]*//p')
+elif ! git cat-file -e "$LAST_TAG^{tree}" 2>/dev/null; then
+  echo "FAIL: could not read the tree at $LAST_TAG to determine which paths that release exposed." >&2
+  echo "  Fix: ensure full tag history is available (e.g. git fetch --unshallow) and retry." >&2
   exit 1
 fi
 
diff --git a/tests/test-check-release-needed.sh b/tests/test-check-release-needed.sh
index ba473bf..c1b1d2f 100755
--- a/tests/test-check-release-needed.sh
+++ b/tests/test-check-release-needed.sh
@@ -211,6 +211,63 @@ else
   fail "invented a bogus assets/ path for a hook script with no bundled tree"
 fi
 
+# --- 12. Deleting a hook's entire bundled assets/ tree is release-relevant ---
+# The worktree-only derivation guarded the assets/ path on the directory still
+# existing, so wiping the whole tree removed the path from the pathspec instead
+# of diffing it: the single most consumer-breaking change possible diffed clean.
+# The path list therefore has to be unioned with what $LAST_TAG exposed.
+echo ""
+echo "--- exits 1 when a hook's entire bundled assets/ tree was deleted since the tag ---"
+FIXTURE12="$(make_tagged_fixture)"; track "$FIXTURE12"
+rm -rf "${FIXTURE12:?}/$HOOK_DIR/assets"
+(cd "$FIXTURE12" && git add -A && git commit -q -m "delete the whole bundled assets tree")
+OUT12=$(run_check "$FIXTURE12" "refs/heads/main" || true)
+if echo "$OUT12" | grep -q "assets/vale/.vale.ini"; then
+  pass "flags a wholesale deletion of a hook's bundled assets/ tree"
+else
+  fail "a hook's entire bundled assets/ tree vanished since the tag without demanding a release"
+fi
+
+# --- 13. A hook script deleted while its manifest entry survives is flagged ---
+# Characterisation test, not a bug fix: tokens[0] is added to the pathspec
+# unconditionally (no existence guard), so this case was already covered. It is
+# pinned here so the tagged-tree union can't accidentally introduce an existence
+# guard on tokens[0] and reopen the hole its assets/ sibling had.
+echo ""
+echo "--- exits 1 when a hook script was deleted but its manifest entry remains ---"
+FIXTURE13="$(make_tagged_fixture)"; track "$FIXTURE13"
+rm -f "$FIXTURE13/$HOOK_DIR/scripts/vale-wrap.sh"
+(cd "$FIXTURE13" && git add -A && git commit -q -m "delete a hook script, keep its manifest entry")
+OUT13=$(run_check "$FIXTURE13" "refs/heads/main" || true)
+if echo "$OUT13" | grep -q "vale-wrap.sh"; then
+  pass "flags a hook script deleted out from under a surviving manifest entry"
+else
+  fail "a manifest entry's script vanished since the tag without demanding a release"
+fi
+
+# --- 14. Retiring a whole hook names what the tag exposed, not just the manifest ---
+# Removing the entry and everything it shipped changes $HOOKS_MANIFEST, so the
+# gate fires either way — but a derivation that only reads the current manifest
+# can no longer name the retired script or its assets, and the failure message
+# understates the breakage to consumers pinned at the old rev. The tagged
+# manifest is what makes those paths reportable.
+echo ""
+echo "--- names the retired hook's own paths when an entry and its files are removed together ---"
+FIXTURE14="$(make_tagged_fixture)"; track "$FIXTURE14"
+cat > "$FIXTURE14/.pre-commit-hooks.yaml" <<'EOF'
+-   id: fake-size-check
+    entry: scripts/skill-size-check.sh
+    language: script
+EOF
+rm -rf "${FIXTURE14:?}/$HOOK_DIR"
+(cd "$FIXTURE14" && git add -A && git commit -q -m "retire the vale hook entirely")
+OUT14=$(run_check "$FIXTURE14" "refs/heads/main" || true)
+if echo "$OUT14" | grep -q "vale-wrap.sh" && echo "$OUT14" | grep -q "assets/vale/.vale.ini"; then
+  pass "names the retired hook's script and bundled assets, not just the manifest edit"
+else
+  fail "reported only the manifest change and hid which shipped paths the retirement removed"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 16c038b1783ad235853198eea6092db28a5de0de Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:32:30 +0000
Subject: [PATCH 26/45] fix(lint): guard empty array expansions in vale-wrap.sh
 for bash 3.2

Under set -u, "${arr[@]}" on an empty array aborts on bash before 4.4,
which is what macOS ships as /bin/bash. Three expansion sites now use
${arr[@]+"${arr[@]}"} consistently.

The hazard is not currently reachable: verified on a bash 3.2.57 built
from source that all seven invocation shapes succeed against the
previous code, including zero args, flags-only and an empty directory.
vale_args is provably non-empty at every site because the default
--config branch always appends first. The guard is kept because that
invariant is non-local and untested, so an edit to the default-config
branch would reintroduce a macOS-only crash silently.

Test fidelity is deliberately mixed. Case 16 is static and is the only
one that fails against the previous code, since no bash 5 host can
reproduce the abort at runtime. Case 17 runs the emptiest invocations
under the oldest bash it can find and names that shell in its output
so it cannot overclaim. Case 18 guards against the tempting wrong fix
of dropping the quotes, which also silences the abort but word-splits
a path containing a space.

No other bash 4.x construct is present; swept for mapfile, declare -A,
case modification, negative indices, globstar, wait -n and namerefs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 plugins/kyberforge/.claude-plugin/plugin.json |  2 +-
 plugins/kyberforge/plugin.json                |  2 +-
 .../skills/agent-audit/scripts/vale-wrap.sh   | 11 ++-
 .../skills/skill-audit/scripts/vale-wrap.sh   | 11 ++-
 tests/test-vale-wrap.sh                       | 75 +++++++++++++++++++
 5 files changed, 93 insertions(+), 8 deletions(-)

diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json
index 2a76c69..2c67fcb 100644
--- a/plugins/kyberforge/.claude-plugin/plugin.json
+++ b/plugins/kyberforge/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.2.6"
+  "version": "1.2.7"
 }
diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json
index 367ddb4..7609ef2 100644
--- a/plugins/kyberforge/plugin.json
+++ b/plugins/kyberforge/plugin.json
@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.2.6"
+  "version": "1.2.7"
 }
diff --git a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
index 9e22cb8..f3d891b 100755
--- a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
@@ -34,6 +34,11 @@ set -euo pipefail
 
 cwd="$(pwd -P)"
 
+# Every array below is expanded as `${arr[@]+"${arr[@]}"}`: bash before 4.4 —
+# including the 3.2 that macOS still ships as /bin/bash — treats `"${arr[@]}"`
+# on an empty array as an unbound variable under `set -u`. No expansion site is
+# reachable while empty on today's control flow, so this is insurance against a
+# later edit breaking that invariant, not a live fix.
 vale_args=()
 path_args=()
 config_next=false
@@ -93,7 +98,7 @@ fi
 if [[ ${#path_args[@]} -eq 0 ]]; then
   # Nothing to flatten. Hand off directly, with stdin closed so vale doesn't
   # block waiting on a pipe that will never carry content.
-  exec vale "${vale_args[@]}" < /dev/null
+  exec vale ${vale_args[@]+"${vale_args[@]}"} < /dev/null
 fi
 
 # `realpath -m` would be the obvious normalizer, but `-m` (canonicalize-missing)
@@ -178,7 +183,7 @@ mirror="$tmpdir$cwd"
 mkdir -p "$mirror"
 
 argv_paths=()
-for arg in "${path_args[@]}"; do
+for arg in ${path_args[@]+"${path_args[@]}"}; do
   if [[ "$arg" == /* ]]; then
     dest="$tmpdir$arg"
   else
@@ -220,4 +225,4 @@ for arg in "${path_args[@]}"; do
 done
 
 cd "$mirror"
-vale "${vale_args[@]}" "${argv_paths[@]}"
+vale ${vale_args[@]+"${vale_args[@]}"} ${argv_paths[@]+"${argv_paths[@]}"}
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
index 9e22cb8..f3d891b 100755
--- a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
@@ -34,6 +34,11 @@ set -euo pipefail
 
 cwd="$(pwd -P)"
 
+# Every array below is expanded as `${arr[@]+"${arr[@]}"}`: bash before 4.4 —
+# including the 3.2 that macOS still ships as /bin/bash — treats `"${arr[@]}"`
+# on an empty array as an unbound variable under `set -u`. No expansion site is
+# reachable while empty on today's control flow, so this is insurance against a
+# later edit breaking that invariant, not a live fix.
 vale_args=()
 path_args=()
 config_next=false
@@ -93,7 +98,7 @@ fi
 if [[ ${#path_args[@]} -eq 0 ]]; then
   # Nothing to flatten. Hand off directly, with stdin closed so vale doesn't
   # block waiting on a pipe that will never carry content.
-  exec vale "${vale_args[@]}" < /dev/null
+  exec vale ${vale_args[@]+"${vale_args[@]}"} < /dev/null
 fi
 
 # `realpath -m` would be the obvious normalizer, but `-m` (canonicalize-missing)
@@ -178,7 +183,7 @@ mirror="$tmpdir$cwd"
 mkdir -p "$mirror"
 
 argv_paths=()
-for arg in "${path_args[@]}"; do
+for arg in ${path_args[@]+"${path_args[@]}"}; do
   if [[ "$arg" == /* ]]; then
     dest="$tmpdir$arg"
   else
@@ -220,4 +225,4 @@ for arg in "${path_args[@]}"; do
 done
 
 cd "$mirror"
-vale "${vale_args[@]}" "${argv_paths[@]}"
+vale ${vale_args[@]+"${vale_args[@]}"} ${argv_paths[@]+"${argv_paths[@]}"}
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index 9816125..3fc4d0a 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -425,6 +425,81 @@ else
   fail "a path with a space was dropped from the directory walk"
 fi
 
+# --- 16. No unguarded `"${arr[@]}"` expansion survives in the wrapper. bash
+# before 4.4 — including the 3.2 that macOS still ships as /bin/bash — treats
+# that form on an empty array as an unbound variable under `set -u` and aborts.
+# The portable form is `${arr[@]+"${arr[@]}"}`. This is a static check because
+# no bash 5 host can reproduce the abort at runtime: the construct is only fatal
+# on the older shell, so absence of the construct is the property to assert.
+# `${#arr[@]}` is deliberately not flagged — the count form is safe on 3.2.
+echo ""
+echo "--- no unguarded array expansion remains in vale-wrap.sh ---"
+unguarded_expansions() {
+  # Blank out whole-line comments (keeping line numbers), delete every correctly
+  # guarded expansion, then anything still matching is a real hazard.
+  awk '{ if ($0 ~ /^[[:space:]]*#/) print ""; else print }' "$1" \
+    | sed -E 's/\$\{([A-Za-z_][A-Za-z0-9_]*)\[@\]\+"\$\{\1\[@\]\}"\}//g' \
+    | grep -nE '\$\{[A-Za-z_][A-Za-z0-9_]*\[@\]\}' || true
+}
+HAZARDS16="$(unguarded_expansions "$SCRIPT")"
+if [[ -n "$HAZARDS16" ]]; then
+  fail "unguarded array expansion(s) abort on bash < 4.4 under set -u: $(echo "$HAZARDS16" | tr '\n' ' ')"
+else
+  pass "every array expansion uses the bash-3.2-safe \${arr[@]+\"\${arr[@]}\"} form"
+fi
+
+# --- 17. The invocations whose arrays are closest to empty actually run. Under
+# a bash older than 4.4 this is genuine macOS-shell coverage; on a modern bash it
+# degrades to a smoke test, so the pass message names the shell that really ran.
+# Point VALE_WRAP_TEST_BASH at a 3.2 build to get the real thing in CI.
+echo ""
+echo "--- degenerate invocations survive on the oldest available bash ---"
+OLD_BASH="bash"
+OLD_BASH_VER="$(bash -c 'echo "${BASH_VERSINFO[0]}.${BASH_VERSINFO[1]}"')"
+for CAND in "${VALE_WRAP_TEST_BASH:-}" bash-3.2 bash3 /bin/bash /usr/local/bin/bash; do
+  [[ -n "$CAND" ]] && command -v "$CAND" >/dev/null 2>&1 || continue
+  CAND_VER="$("$CAND" -c 'echo "${BASH_VERSINFO[0]}.${BASH_VERSINFO[1]}"' 2>/dev/null)" || continue
+  [[ -n "$CAND_VER" ]] || continue
+  if (( ${CAND_VER%.*} * 100 + ${CAND_VER#*.} < ${OLD_BASH_VER%.*} * 100 + ${OLD_BASH_VER#*.} )); then
+    OLD_BASH="$CAND"
+    OLD_BASH_VER="$CAND_VER"
+  fi
+done
+FIXTURE17="$(make_fixture 2)"
+mkdir -p "$FIXTURE17/emptydir"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11" "$FIXTURE12" "$STUB13" "$FIXTURE14" "$FIXTURE17"' EXIT
+# Zero args, flags with no path, and a directory that walks to nothing are the
+# three shapes that leave vale_args/path_args/argv_paths at their emptiest.
+OUT17=""
+for ARGS17 in "" "--config $VALE_CONFIG" "--config $VALE_CONFIG emptydir"; do
+  # shellcheck disable=SC2086 # deliberate word splitting of the argv fixture
+  OUT17+="$( (cd "$FIXTURE17" && "$OLD_BASH" "$SCRIPT" $ARGS17 </dev/null 2>&1) || true)"
+done
+if echo "$OUT17" | grep -q "unbound variable"; then
+  fail "aborted with 'unbound variable' on bash $OLD_BASH_VER — the bug this test guards against"
+else
+  pass "degenerate invocations run clean under bash $OLD_BASH_VER ($OLD_BASH)"
+fi
+
+# --- 18. The guarded expansion must keep argv word boundaries intact. Dropping
+# the quotes (`${arr[@]}`) also silences the unbound-variable abort, so it is the
+# tempting wrong fix — and it splits any path containing a space into two bogus
+# arguments. Case 15 covers spaces found by the directory walk; this covers a
+# space in the path argument itself, which is what argv_paths expands.
+echo ""
+echo "--- a path argument containing a space survives the guarded expansion ---"
+FIXTURE18="$(make_fixture 2)"
+trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11" "$FIXTURE12" "$STUB13" "$FIXTURE14" "$FIXTURE17" "$FIXTURE18"' EXIT
+SPACED18="$FIXTURE18/plugins/testplugin/skills/zzz skill dir"
+mkdir -p "$SPACED18"
+mv "$FIXTURE18/plugins/testplugin/skills/zzzskill/SKILL.md" "$SPACED18/SKILL.md"
+OUT18=$(run_wrap "$FIXTURE18" --config "$VALE_CONFIG" "plugins/testplugin/skills/zzz skill dir/SKILL.md")
+if echo "$OUT18" | grep -q "zzz skill dir/SKILL.md" && echo "$OUT18" | grep -q "VagueWording"; then
+  pass "a path argument with a space is passed to vale as one word"
+else
+  fail "a path argument with a space was split by the array expansion: $OUT18"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From afc2b7fdfd59c92875dfa71e37aaad8557fe180e Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 13:32:32 +0000
Subject: [PATCH 27/45] docs(lessons): record two patterns from PR #85's round
 4

A config's local mode can prove nothing about the mode that ships:
repo: local collapses the clone prefix, cwd and repo root into one
directory, so a byte-identical entry: string worked locally for a
reason that exists only locally, through three review rounds.

Deleting a token from a shared artifact breaks whatever parses it,
silently: dropping --config killed the loop that gave the bundled
Vale styles release coverage, shrinking a derived path list with no
error and no failing test.

Kept separate from the adjacent "clean linter result" and "one signal,
two consumers" entries, which describe different failure modes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
---
 LESSONS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/LESSONS.md b/LESSONS.md
index 234d3d9..a95342c 100644
--- a/LESSONS.md
+++ b/LESSONS.md
@@ -151,3 +151,11 @@ Vale's output fed two consumers with different contracts: the audit skills read
 ## 2026-08-08 — Measure a rule's false-positive rate at the severity you will ship it at
 
 `Kyberforge.VagueQualifier` was cherry-picked from `write-good` after being trialled as "low-noise against this repo's corpus" — but the trial ran at `level: warning`, where a false positive costs nothing because nobody ever sees it. Shipped at `error`, the same false positive costs a blocked commit and a permanent suppression comment. Re-measured at the severity it actually shipped at, the rule scored one marginal true positive and one unfixable false positive across 41 files (`caveman/SKILL.md` *quotes* filler words as its subject matter — a mention, not a use), and was deleted. Fix: trial conditions must match shipping conditions. A noise measurement taken where false positives are free does not transfer to a context where they are expensive, and "low-noise" is not a property of a rule alone — it is a property of the rule at a severity.
+
+## 2026-08-09 — Exercising a config's "local" mode proves nothing about the mode that ships
+
+The root `.pre-commit-hooks.yaml` shipped Vale hooks whose `entry:` carried a `--config <repo-relative-path>` argument. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: each external consumer hard-failed with `E100 [--config] Runtime error ... does not exist`, and two of the three hooks ADR-0014 promised were unusable. The defect survived three review rounds of PR #85 and a green `pre-commit run --all-files` every time, because this repo consumes the same hooks through `repo: local`, where the clone prefix, the cwd, and the repo root are one directory — the byte-identical `entry:` string worked locally for a reason that exists only locally. Nothing under `tests/` exercised the manifest as a hook repo at all. The sharp part: the local run was not weaker evidence of the same thing, it was evidence of a different thing, and the two were indistinguishable by reading either file. Fix: when a config has a local mode whose resolution semantics differ from the shipped mode, test the shipped mode against a real consumer — `tests/test-vale-hooks-consumer.sh` stands up a `file://` clone of this repo and runs the hooks from it — and then delete the divergence rather than living with it: `vale-wrap.sh` now self-locates its config from `${BASH_SOURCE[0]}`, and the local and shipped `entry:` lines are identical, so the local run no longer exercises a path no consumer takes.
+
+## 2026-08-09 — Deleting a token from a shared artifact breaks whatever parses it, silently
+
+Dropping the `--config` argument from `.pre-commit-hooks.yaml` was the right fix, but `scripts/check-release-needed.sh` derived its release-relevant path list by scanning those same `entry:` lines for `--config` and taking the target's `dirname` — that parse was the only thing giving the bundled `.vale.ini` and its sibling `styles/` tree release coverage. With the token gone the loop simply never fired: no error, no failing test, no warning, just a path list that shrank from six entries to four and lost both `assets/vale/` trees. Consequence: a change to a Vale *rule* could land on `main` without demanding a release tag, leaving external consumers pinned to an old `rev:` with stale rules — the exact drift the gate exists to prevent. It surfaced only because the agent making the change reported it as a suspected side effect of its own edit, and was confirmed by diffing the derived path list before and after. Fix: before removing a token from an artifact more than one script reads, grep for everything that *parses* the artifact, not just everything that consumes its documented purpose. The smell to watch for is a loop that builds a list, where an empty or short list is indistinguishable from a correct one — assert on the expected members, so a derivation whose input vanished fails loudly instead of quietly covering less.
-- 
2.43.0


From aa8cc22695812e00765f01240b4e661d97eaa897 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 15:44:04 +0000
Subject: [PATCH 28/45] fix(lint): flatten every multi-line description form in
 vale-wrap.sh
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Vale locates a frontmatter description by matching the parsed YAML value back
against the source text, so any scalar whose value is not spelled out verbatim
loses the `text.frontmatter.description` scope entirely. The wrapper only
flattened `>` folded scalars, so plain, double-quoted and single-quoted
multi-line descriptions silently reported zero alerts and exit 0 — a clean pass
indistinguishable from a real one, in a prefilter whose callers are instructed
not to re-derive its verdict by judgment.

Implementation notes:

- Classify the scalar kind after `^description:[ \t]*` and reuse one shared
  continuation-line generator for every form; `|` literal blocks keep their
  line breaks, stay verbatim-matchable, and are still left untouched.
- Emit the flattened value in whichever scalar form needs no escape at all
  (plain, then single-quoted, then double-quoted), because any escape breaks
  the verbatim match. The old blanket `'` -> U+2019 substitution silently made
  apostrophe-bearing rule tokens unmatchable across 63% of the corpus; it now
  survives only for the one combination no YAML scalar can carry verbatim.
- Terminate continuations at a line flush with the key, not only on a shallower
  indent — a `description:` followed by a flush-left line previously swallowed
  the rest of the frontmatter.
- Route vale's value-taking flags explicitly instead of inferring targets by
  file existence, and absolutize relative `--output`/`--path` values the way
  `--config` already was, since the run `cd`s into the scratch mirror.
- Fail loudly on a nonexistent path instead of inheriting bare vale's fallback
  to stdin, which rendered a typo'd path as `0 errors ... in stdin`, exit 0 —
  a form the callers' `0 files` NOT-RUN guard cannot match.
- Follow symlinks when walking a directory argument, matching bare vale.

Refs: #85
---
 .../skills/agent-audit/scripts/vale-wrap.sh   | 416 ++++++++++++++----
 .../skills/skill-audit/scripts/vale-wrap.sh   | 416 ++++++++++++++----
 tests/test-vale-wrap.sh                       | 298 ++++++++++++-
 3 files changed, 934 insertions(+), 196 deletions(-)

diff --git a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
index f3d891b..66f3057 100755
--- a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
@@ -2,27 +2,45 @@
 set -euo pipefail
 
 # Works around a Vale limitation: the `text.frontmatter.description` NLP scope
-# silently stops matching once the `description:` value is a YAML block scalar
-# (`>`/`|`) spanning 2+ physical lines — the style used by most skills/agents in
-# this repo. Flattens the description to one physical line in a scratch copy
-# (padding with blank lines so every other line number is unchanged), then runs
-# the real `vale` binary against the copies. Drop-in replacement for calling
-# `vale` directly: same args, same exit code.
+# silently stops matching once the `description:` value spans 2+ physical lines
+# in any form YAML joins back into one string — a `>`/`>-`/`>+` folded block
+# scalar (the style used by most skills/agents in this repo), a plain scalar
+# wrapped onto continuation lines, or a double- or single-quoted scalar wrapped
+# the same way. A `|`/`|-`/`|+` literal block scalar is NOT affected: its parsed
+# value keeps exactly the line breaks the source has, and vale matches it fine
+# (verified against vale 3.15.2), so literal blocks are deliberately left alone.
+# This script flattens an affected description to one physical line in a scratch
+# copy (padding with blank lines so every other line number is unchanged), then
+# runs the real `vale` binary against the copies. Drop-in replacement for calling
+# `vale` directly: same args, same exit code, bar the two documented divergences
+# below.
 #
-# "Same args" means relative paths — `--config` values and path arguments alike
-# — resolve against the caller's current directory, exactly as bare `vale`
-# resolves them. (An earlier version resolved them against the repo root, an
-# invented convention that hard-errored on `--config ../../.vale.ini` from a
-# subdirectory and, worse, silently dropped file arguments that didn't happen to
-# resolve from the repo root — skipping the flattening this script exists for.)
+# "Same args" means relative paths — path arguments and the values of the
+# path-valued flags (`--config`, `--output`, `--path`) alike — resolve against
+# the caller's current directory, exactly as bare `vale` resolves them. The flag
+# values are rewritten to absolute form because the run ends up `cd`'d into the
+# scratch mirror, where a relative one would no longer resolve. (An earlier
+# version resolved path arguments against the repo root, an invented convention
+# that hard-errored on `--config ../../.vale.ini` from a subdirectory and, worse,
+# silently dropped file arguments that didn't happen to resolve from the repo
+# root — skipping the flattening this script exists for.)
 #
-# The one addition to bare `vale`'s argument handling: with no `--config` at
-# all, this script's own sibling `assets/vale/.vale.ini` is used instead of
-# vale's upward search. pre-commit prefixes only `entry[0]` with the hook-repo
-# clone path, so a `--config` in `.pre-commit-hooks.yaml` would resolve against
-# the *consuming* repo and hard-fail (E100) for every external consumer. The
-# manifest therefore passes the script alone, and an explicit `--config` from
-# any other caller still wins.
+# Divergence 1: with no `--config` at all, this script's own sibling
+# `assets/vale/.vale.ini` is used instead of vale's upward search. pre-commit
+# prefixes only `entry[0]` with the hook-repo clone path, so a `--config` in
+# `.pre-commit-hooks.yaml` would resolve against the *consuming* repo and
+# hard-fail (E100) for every external consumer. The manifest therefore passes the
+# script alone, and an explicit `--config` from any other caller still wins.
+#
+# Divergence 2: a path-shaped argument that does not exist is a hard error
+# (exit 2). Bare vale drops it, falls back to reading stdin, and prints
+# `0 errors ... in stdin` with exit 0 — a typo'd target is then indistinguishable
+# from a clean run. Both audit skills treat a `0 files` report as NOT RUN rather
+# than clean, and `in stdin` does not match that guard, so the silent form would
+# read as "prefilter clean" and skip the LLM fallback. Erroring is the only way
+# to keep that guard honest. Linting prose piped on stdin is therefore
+# unsupported here — it already was, since the no-path handoff closes stdin so
+# vale can't block on a pipe that will never carry content.
 #
 # Vale prints each path exactly as it was handed to it, so the scratch tree
 # mirrors the caller's absolute cwd: a relative path argument is passed through
@@ -41,22 +59,44 @@ cwd="$(pwd -P)"
 # later edit breaking that invariant, not a live fix.
 vale_args=()
 path_args=()
-config_next=false
+pending_flag=""
 config_given=false
 for arg in "$@"; do
-  if [[ "$config_next" == true ]]; then
-    config_next=false
-    if [[ "$arg" == /* ]]; then
-      vale_args+=("$arg")
-    else
-      vale_args+=("$cwd/$arg")
-    fi
+  if [[ -n "$pending_flag" ]]; then
+    # Value of a separated two-argv flag. It is never a lint target, however
+    # file-like it looks. The run ends up `cd`'d into the scratch mirror, so a
+    # value naming a file has to be absolutized here or it stops resolving.
+    case "$pending_flag" in
+      --config)
+        # Always a path, and required to exist.
+        if [[ "$arg" == /* ]]; then
+          vale_args+=("$arg")
+        else
+          vale_args+=("$cwd/$arg")
+        fi
+        ;;
+      --output|--path)
+        # `--output` is either a built-in style name (`line`, `JSON`) or a
+        # template file; only the file form needs resolving. `--path` is
+        # likewise a path. Anything that names nothing is passed through and
+        # left for vale to interpret.
+        if [[ "$arg" != /* && -e "$arg" ]]; then
+          vale_args+=("$cwd/$arg")
+        else
+          vale_args+=("$arg")
+        fi
+        ;;
+      *)
+        vale_args+=("$arg")
+        ;;
+    esac
+    pending_flag=""
     continue
   fi
   case "$arg" in
     --config)
       vale_args+=("$arg")
-      config_next=true
+      pending_flag="$arg"
       config_given=true
       continue
       ;;
@@ -70,24 +110,60 @@ for arg in "$@"; do
       config_given=true
       continue
       ;;
+    # Same cwd-relative resolution for the `--flag=value` spelling of the two
+    # other path-valued flags.
+    --output=*|--path=*)
+      flag_val="${arg#*=}"
+      if [[ "$flag_val" != /* && -n "$flag_val" && -e "$flag_val" ]]; then
+        vale_args+=("${arg%%=*}=$cwd/$flag_val")
+      else
+        vale_args+=("$arg")
+      fi
+      continue
+      ;;
+    # Vale's remaining value-taking flags, per `vale --help` (3.x). In the
+    # separated two-argv form the value must not be classified as a lint target
+    # — `--output tmpl.tmpl` names a real template file, and treating it as
+    # input both lints the template and reorders argv so vale sees
+    # `--output --no-wrap`. The `--flag=value` form needs no entry here: it
+    # starts with `-` and falls through to vale untouched. A value flag added by
+    # some future vale release is simply absent from this list and lands back on
+    # today's behaviour, so this list going stale is never worse than not having
+    # it.
+    --ext|--filter|--glob|--minAlertLevel|--output|--path)
+      vale_args+=("$arg")
+      pending_flag="$arg"
+      continue
+      ;;
+    # Vale's subcommands are bare words that name no file, so they would trip
+    # the not-found error below. A lint target literally named `sync` (no
+    # extension, no slash) is misread as the subcommand — accepted, because the
+    # alternative is failing every `vale-wrap.sh ls-config`.
+    ls-config|ls-dirs|ls-metrics|ls-vars|sync)
+      vale_args+=("$arg")
+      continue
+      ;;
   esac
-  # `-f`/`-d` resolve relative paths against the caller's cwd, same as vale does.
-  # A path that doesn't exist is left for vale to report on, exactly as bare
-  # vale would.
-  if [[ "$arg" != -* && ( -f "$arg" || -d "$arg" ) ]]; then
-    # An absolute path inside the caller's cwd is relativized so the report cites
-    # a path that resolves against the real tree. Left absolute, it would be
-    # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
-    # path to a file that is deleted on exit, which reads as a bug in any report
-    # quoting it. Absolute paths outside the cwd have no relative form and keep
-    # the scratch-path behaviour documented above.
-    if [[ "$arg" == "$cwd"/* ]]; then
-      path_args+=("${arg#"$cwd"/}")
-    else
-      path_args+=("$arg")
-    fi
-  else
+  if [[ "$arg" == -* ]]; then
     vale_args+=("$arg")
+    continue
+  fi
+  # Everything left is a lint target: `vale [options] [input...]` has no third
+  # kind of argument. See divergence 2 above for why a missing one is fatal here.
+  if [[ ! -e "$arg" ]]; then
+    echo "vale-wrap.sh: no such file or directory: $arg" >&2
+    exit 2
+  fi
+  # An absolute path inside the caller's cwd is relativized so the report cites
+  # a path that resolves against the real tree. Left absolute, it would be
+  # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
+  # path to a file that is deleted on exit, which reads as a bug in any report
+  # quoting it. Absolute paths outside the cwd have no relative form and keep
+  # the scratch-path behaviour documented above.
+  if [[ "$arg" == "$cwd"/* ]]; then
+    path_args+=("${arg#"$cwd"/}")
+  else
+    path_args+=("$arg")
   fi
 done
 
@@ -119,55 +195,210 @@ src, dest = sys.argv[1], sys.argv[2]
 with open(src, encoding='utf-8', errors='surrogateescape') as fh:
     content = fh.read()
 
+# YAML 1.2 double-quoted escapes (spec 5.7 / 7.3.1). `\<newline>` is handled
+# separately in unescape_double because it also swallows the next indentation.
+DQ_ESCAPES = {
+    '0': '\0', 'a': '\a', 'b': '\b', 't': '\t', '\t': '\t', 'n': '\n',
+    'v': '\v', 'f': '\f', 'r': '\r', 'e': '\x1b', ' ': ' ', '"': '"',
+    '/': '/', '\\': '\\', 'N': '\x85', '_': '\xa0', 'L': '\u2028',
+    'P': '\u2029',
+}
+
+# First characters that make a plain (unquoted) scalar mean something other than
+# text: YAML's c-indicator set.
+PLAIN_UNSAFE_FIRST = '-?:,[]{}#&*!|>\'"%@`'
+
+
+def unescape_double(text):
+    """Decode a double-quoted YAML scalar's body to the string YAML parses."""
+    out = []
+    i = 0
+    while i < len(text):
+        char = text[i]
+        if char != '\\':
+            out.append(char)
+            i += 1
+            continue
+        i += 1
+        if i >= len(text):
+            break
+        esc = text[i]
+        if esc == '\n':
+            i += 1
+            while i < len(text) and text[i] in ' \t':
+                i += 1
+            continue
+        if esc in 'xuU':
+            width = {'x': 2, 'u': 4, 'U': 8}[esc]
+            digits = text[i + 1:i + 1 + width]
+            if len(digits) == width:
+                try:
+                    out.append(chr(int(digits, 16)))
+                except ValueError:
+                    pass
+                else:
+                    i += 1 + width
+                    continue
+        out.append(DQ_ESCAPES.get(esc, esc))
+        i += 1
+    return ''.join(out)
+
+
+def close_quote(text, quote):
+    """Index of the closing `quote` in `text`, which starts just past the
+    opening one. None while the scalar is still unterminated."""
+    i = 0
+    while i < len(text):
+        char = text[i]
+        if quote == '"' and char == '\\':
+            i += 2
+            continue
+        if char == quote:
+            if quote == "'" and text[i + 1:i + 2] == "'":
+                i += 2
+                continue
+            return i
+        i += 1
+    return None
+
+
+def continuation_lines(rest):
+    """Yield the physical lines of `rest` that continue the value started on the
+    `description:` line. Indentation-based and blank-line-tolerant, per YAML:
+    a blank line (any amount of whitespace) always stays inside; the indent is
+    set by the first content line; the value ends at the first line indented
+    less than that, at any line flush with the key (that is the next mapping
+    key, not a continuation), or at EOF."""
+    indent = None
+    for line in rest.splitlines(keepends=True):
+        text = line.rstrip('\n')
+        if text.strip() == '':
+            yield line
+            continue
+        line_indent = len(text) - len(text.lstrip(' \t'))
+        if line_indent == 0:
+            return
+        if indent is None:
+            indent = line_indent
+        elif line_indent < indent:
+            return
+        yield line
+
+
+def emit(value):
+    """Render `value` as a one-line YAML scalar whose source text spells the
+    value out verbatim. Vale locates the description by matching the parsed
+    value back against the source, so a scalar carrying any escape — `''` in a
+    single-quoted scalar, `\\"` or `\\\\` in a double-quoted one — makes the
+    whole `text.frontmatter.description` scope vanish, the same failure this
+    script exists to work around. Verbatim forms only, therefore, tried in
+    descending order of fidelity."""
+    if (value
+            and value[0] not in PLAIN_UNSAFE_FIRST
+            and ': ' not in value
+            and not value.endswith(':')
+            and ' #' not in value):
+        return value                    # plain: nothing needs escaping at all
+    if "'" not in value:
+        return "'" + value + "'"        # single-quoted: only `'` would escape
+    if '"' not in value and '\\' not in value:
+        return '"' + value + '"'        # double-quoted: only `"`/`\` would
+    # Last resort: the value needs quoting AND holds an apostrophe AND a double
+    # quote or backslash, so no verbatim YAML scalar can carry it. Substituting
+    # U+2019 for the apostrophe keeps the scope alive, at the cost of any style
+    # rule whose token contains a literal ASCII apostrophe. Scratch-copy only —
+    # never written back to the real file.
+    return "'" + value.replace("'", '’') + "'"
+
+
 fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
 if fm_match:
     fm = fm_match.group(2)
-    # Only `>`/`>-`/`>+` (folded) scalars break Vale's frontmatter-description
-    # scope. `|`/`|-`/`|+` (literal) scalars already work fine with bare vale,
-    # so they're deliberately left unmatched here.
-    header_m = re.search(r'^description:[ \t]*(>[+-]?)[ \t]*\n', fm, re.MULTILINE)
-    if header_m:
-        # Body capture is indentation-based and blank-line-tolerant, per YAML
-        # block-scalar rules: a blank line (any amount of whitespace) always
-        # stays inside the block; the indent is set by the first content line;
-        # the block ends at the first line indented less than that, or EOF.
-        rest = fm[header_m.end():]
-        indent = None
-        body_lines = []
-        for line in rest.splitlines(keepends=True):
-            text = line.rstrip('\n')
-            if text.strip() == '':
-                body_lines.append(line)
-                continue
-            line_indent = len(text) - len(text.lstrip(' \t'))
-            if indent is None:
-                indent = line_indent
-            elif line_indent < indent:
+    header_m = re.search(r'^description:[ \t]*', fm, re.MULTILINE)
+else:
+    header_m = None
+
+if header_m:
+    head_start = header_m.start()
+    value_start = header_m.end()
+    header_end = fm.find('\n', value_start)
+    header_end = len(fm) if header_end == -1 else header_end
+    first = fm[value_start:header_end]
+    body_start = header_end + 1
+    indicator = first.rstrip()
+
+    block_m = re.fullmatch(r'([|>])([+-]?[0-9]*|[0-9]*[+-]?)', indicator)
+    if block_m and block_m.group(1) == '|':
+        kind = None       # literal blocks keep their line breaks; vale is fine
+    elif block_m:
+        kind = 'block'    # folded (`>`): the value starts on the next line
+    elif indicator == '':
+        kind = 'block'    # bare `description:`: a plain scalar on later lines
+    elif first[:1] == '"':
+        kind = 'double'
+    elif first[:1] == "'":
+        kind = 'single'
+    elif first[:1] in '#&*!':
+        kind = None       # comment, anchor, alias or tag — not a plain scalar
+    else:
+        kind = 'plain'
+
+    text = ''
+    value_end = value_start
+    value_lines = 0
+    if kind in ('block', 'plain'):
+        body = ''.join(continuation_lines(fm[body_start:]))
+        value_end = body_start + len(body)
+        if kind == 'block':
+            text = body
+            value_lines = body.count('\n')
+        else:
+            text = fm[value_start:value_end]
+            value_lines = 1 + body.count('\n')
+            if ' #' in text or text.lstrip().startswith('#'):
+                # A `#` opens a comment inside a plain scalar. Folding it in
+                # would lint text YAML never treats as part of the value, so
+                # leave the file alone rather than lint the wrong string.
+                kind = None
+    elif kind in ('double', 'single'):
+        quote = '"' if kind == 'double' else "'"
+        inner_start = value_start + 1
+        acc = fm[inner_start:body_start]
+        idx = close_quote(acc, quote)
+        lines = continuation_lines(fm[body_start:])
+        while idx is None:
+            try:
+                acc += next(lines)
+            except StopIteration:
                 break
-            body_lines.append(line)
-        raw = ''.join(body_lines)
-        if raw.count('\n') >= 2:
-            flat = re.sub(r'\s+', ' ', raw).strip()
-            # YAML single-quoted scalars have no backslash-escape mechanism at
-            # all, so wrapping in single quotes sidesteps the backslash-escape
-            # bug entirely for embedded double quotes, backslashes, and
-            # non-ASCII text. The one YAML-spec-correct way to embed a literal
-            # apostrophe is to double it ('') — but Vale's own frontmatter
-            # scanner isn't a full YAML parser and doesn't understand that
-            # doubling: empirically, it silently truncates the value at the
-            # first ' it sees, hiding everything after it from the NLP scope
-            # (a different flavor of the same bug this whole script exists to
-            # work around). Since this copy is scratch-only and never written
-            # back, sidestep it by substituting a Unicode right single
-            # quotation mark (U+2019) for any literal apostrophe instead of
-            # doubling it — visually a smart quote, but never triggers a YAML
-            # escape sequence at all.
-            flat_q = "'" + flat.replace("'", "’") + "'"
-            pad = '\n' * raw.count('\n')
-            start = header_m.start()
-            end = header_m.end() + len(raw)
-            new_fm = fm[:start] + f'description: {flat_q}\n{pad}' + fm[end:]
-            content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
+            idx = close_quote(acc, quote)
+        if idx is None:
+            kind = None   # unterminated quote: invalid YAML, leave it to vale
+        else:
+            inner = acc[:idx]
+            value_end = inner_start + idx + 1
+            text = unescape_double(inner) if quote == '"' else inner.replace("''", "'")
+            value_lines = 1 + inner.count('\n')
+
+    flat = re.sub(r'\s+', ' ', text).strip()
+    if kind and flat and value_lines >= 2:
+        # `value_end` can land mid-line, just past a closing quote, so extend to
+        # the end of that physical line and carry whatever follows (a trailing
+        # comment) across unchanged.
+        if value_end > 0 and fm[value_end - 1] == '\n':
+            span_end = value_end
+            trailer = ''
+        else:
+            newline = fm.find('\n', value_end)
+            span_end = len(fm) if newline == -1 else newline + 1
+            trailer = fm[value_end:span_end].rstrip('\n')
+        # One line replaces the span, so the blank-line pad is one short of the
+        # newline count it displaced — every later line number is unchanged.
+        pad = '\n' * (fm[head_start:span_end].count('\n') - 1)
+        new_fm = (fm[:head_start] + 'description: ' + emit(flat) + trailer
+                  + '\n' + pad + fm[span_end:])
+        content = (fm_match.group(1) + new_fm + fm_match.group(3)
+                   + content[fm_match.end():])
 
 with open(dest, 'w', encoding='utf-8', errors='surrogateescape') as fh:
     fh.write(content)
@@ -206,11 +437,16 @@ for arg in ${path_args[@]+"${path_args[@]}"}; do
     # the tree, so any file dropped here would be silently unlinted — and then
     # every markdown file in the copy is flattened in place. `.git` is pruned:
     # vale never lints it and copying it can dwarf the rest of the tree.
+    # `find -L` follows symlinks because vale does: it lints both a symlinked
+    # file and a file under a symlinked directory, and a bare `-type f` walk
+    # would report "0 files" where bare vale reports one. (A symlink loop makes
+    # `find` warn on stderr and carry on, which is also what vale does.) The
+    # second walk needs no `-L`: the mirror is all real files by construction.
     mkdir -p "$dest"
     while IFS= read -r -d '' rel; do
       mkdir -p "$dest/$(dirname "$rel")"
       cp "$arg/$rel" "$dest/$rel"
-    done < <(cd "$arg" && find . -name .git -prune -o -type f -print0)
+    done < <(cd "$arg" && find -L . -name .git -prune -o -type f -print0)
     while IFS= read -r -d '' md; do
       flatten "$md" "$md"
     done < <(find "$dest" -type f -name '*.md' -print0)
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
index f3d891b..66f3057 100755
--- a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
@@ -2,27 +2,45 @@
 set -euo pipefail
 
 # Works around a Vale limitation: the `text.frontmatter.description` NLP scope
-# silently stops matching once the `description:` value is a YAML block scalar
-# (`>`/`|`) spanning 2+ physical lines — the style used by most skills/agents in
-# this repo. Flattens the description to one physical line in a scratch copy
-# (padding with blank lines so every other line number is unchanged), then runs
-# the real `vale` binary against the copies. Drop-in replacement for calling
-# `vale` directly: same args, same exit code.
+# silently stops matching once the `description:` value spans 2+ physical lines
+# in any form YAML joins back into one string — a `>`/`>-`/`>+` folded block
+# scalar (the style used by most skills/agents in this repo), a plain scalar
+# wrapped onto continuation lines, or a double- or single-quoted scalar wrapped
+# the same way. A `|`/`|-`/`|+` literal block scalar is NOT affected: its parsed
+# value keeps exactly the line breaks the source has, and vale matches it fine
+# (verified against vale 3.15.2), so literal blocks are deliberately left alone.
+# This script flattens an affected description to one physical line in a scratch
+# copy (padding with blank lines so every other line number is unchanged), then
+# runs the real `vale` binary against the copies. Drop-in replacement for calling
+# `vale` directly: same args, same exit code, bar the two documented divergences
+# below.
 #
-# "Same args" means relative paths — `--config` values and path arguments alike
-# — resolve against the caller's current directory, exactly as bare `vale`
-# resolves them. (An earlier version resolved them against the repo root, an
-# invented convention that hard-errored on `--config ../../.vale.ini` from a
-# subdirectory and, worse, silently dropped file arguments that didn't happen to
-# resolve from the repo root — skipping the flattening this script exists for.)
+# "Same args" means relative paths — path arguments and the values of the
+# path-valued flags (`--config`, `--output`, `--path`) alike — resolve against
+# the caller's current directory, exactly as bare `vale` resolves them. The flag
+# values are rewritten to absolute form because the run ends up `cd`'d into the
+# scratch mirror, where a relative one would no longer resolve. (An earlier
+# version resolved path arguments against the repo root, an invented convention
+# that hard-errored on `--config ../../.vale.ini` from a subdirectory and, worse,
+# silently dropped file arguments that didn't happen to resolve from the repo
+# root — skipping the flattening this script exists for.)
 #
-# The one addition to bare `vale`'s argument handling: with no `--config` at
-# all, this script's own sibling `assets/vale/.vale.ini` is used instead of
-# vale's upward search. pre-commit prefixes only `entry[0]` with the hook-repo
-# clone path, so a `--config` in `.pre-commit-hooks.yaml` would resolve against
-# the *consuming* repo and hard-fail (E100) for every external consumer. The
-# manifest therefore passes the script alone, and an explicit `--config` from
-# any other caller still wins.
+# Divergence 1: with no `--config` at all, this script's own sibling
+# `assets/vale/.vale.ini` is used instead of vale's upward search. pre-commit
+# prefixes only `entry[0]` with the hook-repo clone path, so a `--config` in
+# `.pre-commit-hooks.yaml` would resolve against the *consuming* repo and
+# hard-fail (E100) for every external consumer. The manifest therefore passes the
+# script alone, and an explicit `--config` from any other caller still wins.
+#
+# Divergence 2: a path-shaped argument that does not exist is a hard error
+# (exit 2). Bare vale drops it, falls back to reading stdin, and prints
+# `0 errors ... in stdin` with exit 0 — a typo'd target is then indistinguishable
+# from a clean run. Both audit skills treat a `0 files` report as NOT RUN rather
+# than clean, and `in stdin` does not match that guard, so the silent form would
+# read as "prefilter clean" and skip the LLM fallback. Erroring is the only way
+# to keep that guard honest. Linting prose piped on stdin is therefore
+# unsupported here — it already was, since the no-path handoff closes stdin so
+# vale can't block on a pipe that will never carry content.
 #
 # Vale prints each path exactly as it was handed to it, so the scratch tree
 # mirrors the caller's absolute cwd: a relative path argument is passed through
@@ -41,22 +59,44 @@ cwd="$(pwd -P)"
 # later edit breaking that invariant, not a live fix.
 vale_args=()
 path_args=()
-config_next=false
+pending_flag=""
 config_given=false
 for arg in "$@"; do
-  if [[ "$config_next" == true ]]; then
-    config_next=false
-    if [[ "$arg" == /* ]]; then
-      vale_args+=("$arg")
-    else
-      vale_args+=("$cwd/$arg")
-    fi
+  if [[ -n "$pending_flag" ]]; then
+    # Value of a separated two-argv flag. It is never a lint target, however
+    # file-like it looks. The run ends up `cd`'d into the scratch mirror, so a
+    # value naming a file has to be absolutized here or it stops resolving.
+    case "$pending_flag" in
+      --config)
+        # Always a path, and required to exist.
+        if [[ "$arg" == /* ]]; then
+          vale_args+=("$arg")
+        else
+          vale_args+=("$cwd/$arg")
+        fi
+        ;;
+      --output|--path)
+        # `--output` is either a built-in style name (`line`, `JSON`) or a
+        # template file; only the file form needs resolving. `--path` is
+        # likewise a path. Anything that names nothing is passed through and
+        # left for vale to interpret.
+        if [[ "$arg" != /* && -e "$arg" ]]; then
+          vale_args+=("$cwd/$arg")
+        else
+          vale_args+=("$arg")
+        fi
+        ;;
+      *)
+        vale_args+=("$arg")
+        ;;
+    esac
+    pending_flag=""
     continue
   fi
   case "$arg" in
     --config)
       vale_args+=("$arg")
-      config_next=true
+      pending_flag="$arg"
       config_given=true
       continue
       ;;
@@ -70,24 +110,60 @@ for arg in "$@"; do
       config_given=true
       continue
       ;;
+    # Same cwd-relative resolution for the `--flag=value` spelling of the two
+    # other path-valued flags.
+    --output=*|--path=*)
+      flag_val="${arg#*=}"
+      if [[ "$flag_val" != /* && -n "$flag_val" && -e "$flag_val" ]]; then
+        vale_args+=("${arg%%=*}=$cwd/$flag_val")
+      else
+        vale_args+=("$arg")
+      fi
+      continue
+      ;;
+    # Vale's remaining value-taking flags, per `vale --help` (3.x). In the
+    # separated two-argv form the value must not be classified as a lint target
+    # — `--output tmpl.tmpl` names a real template file, and treating it as
+    # input both lints the template and reorders argv so vale sees
+    # `--output --no-wrap`. The `--flag=value` form needs no entry here: it
+    # starts with `-` and falls through to vale untouched. A value flag added by
+    # some future vale release is simply absent from this list and lands back on
+    # today's behaviour, so this list going stale is never worse than not having
+    # it.
+    --ext|--filter|--glob|--minAlertLevel|--output|--path)
+      vale_args+=("$arg")
+      pending_flag="$arg"
+      continue
+      ;;
+    # Vale's subcommands are bare words that name no file, so they would trip
+    # the not-found error below. A lint target literally named `sync` (no
+    # extension, no slash) is misread as the subcommand — accepted, because the
+    # alternative is failing every `vale-wrap.sh ls-config`.
+    ls-config|ls-dirs|ls-metrics|ls-vars|sync)
+      vale_args+=("$arg")
+      continue
+      ;;
   esac
-  # `-f`/`-d` resolve relative paths against the caller's cwd, same as vale does.
-  # A path that doesn't exist is left for vale to report on, exactly as bare
-  # vale would.
-  if [[ "$arg" != -* && ( -f "$arg" || -d "$arg" ) ]]; then
-    # An absolute path inside the caller's cwd is relativized so the report cites
-    # a path that resolves against the real tree. Left absolute, it would be
-    # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
-    # path to a file that is deleted on exit, which reads as a bug in any report
-    # quoting it. Absolute paths outside the cwd have no relative form and keep
-    # the scratch-path behaviour documented above.
-    if [[ "$arg" == "$cwd"/* ]]; then
-      path_args+=("${arg#"$cwd"/}")
-    else
-      path_args+=("$arg")
-    fi
-  else
+  if [[ "$arg" == -* ]]; then
     vale_args+=("$arg")
+    continue
+  fi
+  # Everything left is a lint target: `vale [options] [input...]` has no third
+  # kind of argument. See divergence 2 above for why a missing one is fatal here.
+  if [[ ! -e "$arg" ]]; then
+    echo "vale-wrap.sh: no such file or directory: $arg" >&2
+    exit 2
+  fi
+  # An absolute path inside the caller's cwd is relativized so the report cites
+  # a path that resolves against the real tree. Left absolute, it would be
+  # rewritten to its scratch copy and printed as `/tmp/tmp.XXXX/...` — a real
+  # path to a file that is deleted on exit, which reads as a bug in any report
+  # quoting it. Absolute paths outside the cwd have no relative form and keep
+  # the scratch-path behaviour documented above.
+  if [[ "$arg" == "$cwd"/* ]]; then
+    path_args+=("${arg#"$cwd"/}")
+  else
+    path_args+=("$arg")
   fi
 done
 
@@ -119,55 +195,210 @@ src, dest = sys.argv[1], sys.argv[2]
 with open(src, encoding='utf-8', errors='surrogateescape') as fh:
     content = fh.read()
 
+# YAML 1.2 double-quoted escapes (spec 5.7 / 7.3.1). `\<newline>` is handled
+# separately in unescape_double because it also swallows the next indentation.
+DQ_ESCAPES = {
+    '0': '\0', 'a': '\a', 'b': '\b', 't': '\t', '\t': '\t', 'n': '\n',
+    'v': '\v', 'f': '\f', 'r': '\r', 'e': '\x1b', ' ': ' ', '"': '"',
+    '/': '/', '\\': '\\', 'N': '\x85', '_': '\xa0', 'L': '\u2028',
+    'P': '\u2029',
+}
+
+# First characters that make a plain (unquoted) scalar mean something other than
+# text: YAML's c-indicator set.
+PLAIN_UNSAFE_FIRST = '-?:,[]{}#&*!|>\'"%@`'
+
+
+def unescape_double(text):
+    """Decode a double-quoted YAML scalar's body to the string YAML parses."""
+    out = []
+    i = 0
+    while i < len(text):
+        char = text[i]
+        if char != '\\':
+            out.append(char)
+            i += 1
+            continue
+        i += 1
+        if i >= len(text):
+            break
+        esc = text[i]
+        if esc == '\n':
+            i += 1
+            while i < len(text) and text[i] in ' \t':
+                i += 1
+            continue
+        if esc in 'xuU':
+            width = {'x': 2, 'u': 4, 'U': 8}[esc]
+            digits = text[i + 1:i + 1 + width]
+            if len(digits) == width:
+                try:
+                    out.append(chr(int(digits, 16)))
+                except ValueError:
+                    pass
+                else:
+                    i += 1 + width
+                    continue
+        out.append(DQ_ESCAPES.get(esc, esc))
+        i += 1
+    return ''.join(out)
+
+
+def close_quote(text, quote):
+    """Index of the closing `quote` in `text`, which starts just past the
+    opening one. None while the scalar is still unterminated."""
+    i = 0
+    while i < len(text):
+        char = text[i]
+        if quote == '"' and char == '\\':
+            i += 2
+            continue
+        if char == quote:
+            if quote == "'" and text[i + 1:i + 2] == "'":
+                i += 2
+                continue
+            return i
+        i += 1
+    return None
+
+
+def continuation_lines(rest):
+    """Yield the physical lines of `rest` that continue the value started on the
+    `description:` line. Indentation-based and blank-line-tolerant, per YAML:
+    a blank line (any amount of whitespace) always stays inside; the indent is
+    set by the first content line; the value ends at the first line indented
+    less than that, at any line flush with the key (that is the next mapping
+    key, not a continuation), or at EOF."""
+    indent = None
+    for line in rest.splitlines(keepends=True):
+        text = line.rstrip('\n')
+        if text.strip() == '':
+            yield line
+            continue
+        line_indent = len(text) - len(text.lstrip(' \t'))
+        if line_indent == 0:
+            return
+        if indent is None:
+            indent = line_indent
+        elif line_indent < indent:
+            return
+        yield line
+
+
+def emit(value):
+    """Render `value` as a one-line YAML scalar whose source text spells the
+    value out verbatim. Vale locates the description by matching the parsed
+    value back against the source, so a scalar carrying any escape — `''` in a
+    single-quoted scalar, `\\"` or `\\\\` in a double-quoted one — makes the
+    whole `text.frontmatter.description` scope vanish, the same failure this
+    script exists to work around. Verbatim forms only, therefore, tried in
+    descending order of fidelity."""
+    if (value
+            and value[0] not in PLAIN_UNSAFE_FIRST
+            and ': ' not in value
+            and not value.endswith(':')
+            and ' #' not in value):
+        return value                    # plain: nothing needs escaping at all
+    if "'" not in value:
+        return "'" + value + "'"        # single-quoted: only `'` would escape
+    if '"' not in value and '\\' not in value:
+        return '"' + value + '"'        # double-quoted: only `"`/`\` would
+    # Last resort: the value needs quoting AND holds an apostrophe AND a double
+    # quote or backslash, so no verbatim YAML scalar can carry it. Substituting
+    # U+2019 for the apostrophe keeps the scope alive, at the cost of any style
+    # rule whose token contains a literal ASCII apostrophe. Scratch-copy only —
+    # never written back to the real file.
+    return "'" + value.replace("'", '’') + "'"
+
+
 fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
 if fm_match:
     fm = fm_match.group(2)
-    # Only `>`/`>-`/`>+` (folded) scalars break Vale's frontmatter-description
-    # scope. `|`/`|-`/`|+` (literal) scalars already work fine with bare vale,
-    # so they're deliberately left unmatched here.
-    header_m = re.search(r'^description:[ \t]*(>[+-]?)[ \t]*\n', fm, re.MULTILINE)
-    if header_m:
-        # Body capture is indentation-based and blank-line-tolerant, per YAML
-        # block-scalar rules: a blank line (any amount of whitespace) always
-        # stays inside the block; the indent is set by the first content line;
-        # the block ends at the first line indented less than that, or EOF.
-        rest = fm[header_m.end():]
-        indent = None
-        body_lines = []
-        for line in rest.splitlines(keepends=True):
-            text = line.rstrip('\n')
-            if text.strip() == '':
-                body_lines.append(line)
-                continue
-            line_indent = len(text) - len(text.lstrip(' \t'))
-            if indent is None:
-                indent = line_indent
-            elif line_indent < indent:
+    header_m = re.search(r'^description:[ \t]*', fm, re.MULTILINE)
+else:
+    header_m = None
+
+if header_m:
+    head_start = header_m.start()
+    value_start = header_m.end()
+    header_end = fm.find('\n', value_start)
+    header_end = len(fm) if header_end == -1 else header_end
+    first = fm[value_start:header_end]
+    body_start = header_end + 1
+    indicator = first.rstrip()
+
+    block_m = re.fullmatch(r'([|>])([+-]?[0-9]*|[0-9]*[+-]?)', indicator)
+    if block_m and block_m.group(1) == '|':
+        kind = None       # literal blocks keep their line breaks; vale is fine
+    elif block_m:
+        kind = 'block'    # folded (`>`): the value starts on the next line
+    elif indicator == '':
+        kind = 'block'    # bare `description:`: a plain scalar on later lines
+    elif first[:1] == '"':
+        kind = 'double'
+    elif first[:1] == "'":
+        kind = 'single'
+    elif first[:1] in '#&*!':
+        kind = None       # comment, anchor, alias or tag — not a plain scalar
+    else:
+        kind = 'plain'
+
+    text = ''
+    value_end = value_start
+    value_lines = 0
+    if kind in ('block', 'plain'):
+        body = ''.join(continuation_lines(fm[body_start:]))
+        value_end = body_start + len(body)
+        if kind == 'block':
+            text = body
+            value_lines = body.count('\n')
+        else:
+            text = fm[value_start:value_end]
+            value_lines = 1 + body.count('\n')
+            if ' #' in text or text.lstrip().startswith('#'):
+                # A `#` opens a comment inside a plain scalar. Folding it in
+                # would lint text YAML never treats as part of the value, so
+                # leave the file alone rather than lint the wrong string.
+                kind = None
+    elif kind in ('double', 'single'):
+        quote = '"' if kind == 'double' else "'"
+        inner_start = value_start + 1
+        acc = fm[inner_start:body_start]
+        idx = close_quote(acc, quote)
+        lines = continuation_lines(fm[body_start:])
+        while idx is None:
+            try:
+                acc += next(lines)
+            except StopIteration:
                 break
-            body_lines.append(line)
-        raw = ''.join(body_lines)
-        if raw.count('\n') >= 2:
-            flat = re.sub(r'\s+', ' ', raw).strip()
-            # YAML single-quoted scalars have no backslash-escape mechanism at
-            # all, so wrapping in single quotes sidesteps the backslash-escape
-            # bug entirely for embedded double quotes, backslashes, and
-            # non-ASCII text. The one YAML-spec-correct way to embed a literal
-            # apostrophe is to double it ('') — but Vale's own frontmatter
-            # scanner isn't a full YAML parser and doesn't understand that
-            # doubling: empirically, it silently truncates the value at the
-            # first ' it sees, hiding everything after it from the NLP scope
-            # (a different flavor of the same bug this whole script exists to
-            # work around). Since this copy is scratch-only and never written
-            # back, sidestep it by substituting a Unicode right single
-            # quotation mark (U+2019) for any literal apostrophe instead of
-            # doubling it — visually a smart quote, but never triggers a YAML
-            # escape sequence at all.
-            flat_q = "'" + flat.replace("'", "’") + "'"
-            pad = '\n' * raw.count('\n')
-            start = header_m.start()
-            end = header_m.end() + len(raw)
-            new_fm = fm[:start] + f'description: {flat_q}\n{pad}' + fm[end:]
-            content = fm_match.group(1) + new_fm + fm_match.group(3) + content[fm_match.end():]
+            idx = close_quote(acc, quote)
+        if idx is None:
+            kind = None   # unterminated quote: invalid YAML, leave it to vale
+        else:
+            inner = acc[:idx]
+            value_end = inner_start + idx + 1
+            text = unescape_double(inner) if quote == '"' else inner.replace("''", "'")
+            value_lines = 1 + inner.count('\n')
+
+    flat = re.sub(r'\s+', ' ', text).strip()
+    if kind and flat and value_lines >= 2:
+        # `value_end` can land mid-line, just past a closing quote, so extend to
+        # the end of that physical line and carry whatever follows (a trailing
+        # comment) across unchanged.
+        if value_end > 0 and fm[value_end - 1] == '\n':
+            span_end = value_end
+            trailer = ''
+        else:
+            newline = fm.find('\n', value_end)
+            span_end = len(fm) if newline == -1 else newline + 1
+            trailer = fm[value_end:span_end].rstrip('\n')
+        # One line replaces the span, so the blank-line pad is one short of the
+        # newline count it displaced — every later line number is unchanged.
+        pad = '\n' * (fm[head_start:span_end].count('\n') - 1)
+        new_fm = (fm[:head_start] + 'description: ' + emit(flat) + trailer
+                  + '\n' + pad + fm[span_end:])
+        content = (fm_match.group(1) + new_fm + fm_match.group(3)
+                   + content[fm_match.end():])
 
 with open(dest, 'w', encoding='utf-8', errors='surrogateescape') as fh:
     fh.write(content)
@@ -206,11 +437,16 @@ for arg in ${path_args[@]+"${path_args[@]}"}; do
     # the tree, so any file dropped here would be silently unlinted — and then
     # every markdown file in the copy is flattened in place. `.git` is pruned:
     # vale never lints it and copying it can dwarf the rest of the tree.
+    # `find -L` follows symlinks because vale does: it lints both a symlinked
+    # file and a file under a symlinked directory, and a bare `-type f` walk
+    # would report "0 files" where bare vale reports one. (A symlink loop makes
+    # `find` warn on stderr and carry on, which is also what vale does.) The
+    # second walk needs no `-L`: the mirror is all real files by construction.
     mkdir -p "$dest"
     while IFS= read -r -d '' rel; do
       mkdir -p "$dest/$(dirname "$rel")"
       cp "$arg/$rel" "$dest/$rel"
-    done < <(cd "$arg" && find . -name .git -prune -o -type f -print0)
+    done < <(cd "$arg" && find -L . -name .git -prune -o -type f -print0)
     while IFS= read -r -d '' md; do
       flatten "$md" "$md"
     done < <(find "$dest" -type f -name '*.md' -print0)
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index 3fc4d0a..fa1cc48 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -321,7 +321,12 @@ else
   fail "an absolute path was silently skipped — the bug this test guards against"
 fi
 
-# --- 11. A literal (|) block scalar passes through unflattened (no regression) ---
+# --- 11. A literal (|) block scalar passes through unflattened. Unlike every
+# other multi-line form, `|` is not broken in Vale: its parsed value keeps the
+# same line breaks the source has, so the description scope still matches. The
+# second assertion pins that down — without it, a wrapper that broke `|` and a
+# Vale that never matched `|` would agree on zero alerts and the comparison
+# would pass vacuously.
 echo ""
 echo "--- leaves a literal (|) block scalar untouched (narrowed >-only scope) ---"
 FIXTURE11="$(make_raw_fixture <<'EOF'
@@ -339,7 +344,9 @@ trap 'rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTU
 REL11="plugins/testplugin/skills/zzzskill/SKILL.md"
 WRAPPED_OUT=$(run_wrap "$FIXTURE11" --config "$VALE_CONFIG" "$REL11")
 BARE_OUT=$(cd "$FIXTURE11" && vale --config "$VALE_CONFIG" "$REL11" 2>&1 || true)
-if [[ "$WRAPPED_OUT" == "$BARE_OUT" ]]; then
+if ! echo "$BARE_OUT" | grep -q "VagueWording"; then
+  fail "bare vale reports nothing for a literal (|) block scalar — the 'literal blocks are not broken' premise is wrong"
+elif [[ "$WRAPPED_OUT" == "$BARE_OUT" ]]; then
   pass "literal (|) block scalar output matches bare vale exactly — untouched by flattening"
 else
   fail "wrapper altered output for a literal (|) block scalar description — should be left untouched"
@@ -425,23 +432,50 @@ else
   fail "a path with a space was dropped from the directory walk"
 fi
 
-# --- 16. No unguarded `"${arr[@]}"` expansion survives in the wrapper. bash
-# before 4.4 — including the 3.2 that macOS still ships as /bin/bash — treats
-# that form on an empty array as an unbound variable under `set -u` and aborts.
-# The portable form is `${arr[@]+"${arr[@]}"}`. This is a static check because
-# no bash 5 host can reproduce the abort at runtime: the construct is only fatal
-# on the older shell, so absence of the construct is the property to assert.
-# `${#arr[@]}` is deliberately not flagged — the count form is safe on 3.2.
+# --- 16. No unguarded `"${arr[@]}"` expansion survives in any script that runs
+# on macOS. bash before 4.4 — including the 3.2 that macOS still ships as
+# /bin/bash — treats that form on an *empty* array as an unbound variable under
+# `set -u` and aborts. The portable form is `${arr[@]+"${arr[@]}"}`. This is a
+# static check because no bash 5 host can reproduce the abort at runtime: the
+# construct is only fatal on the older shell, so absence of the construct is the
+# property to assert. `${#arr[@]}` is deliberately not flagged — the count form
+# is safe on 3.2. Neither is an array seeded with at least one element where it
+# is declared and never reset to empty: it cannot be empty at any expansion
+# site, so the construct is not a hazard there and demanding the guarded form
+# would be a wrong test. The file list covers every script this repo ships or
+# runs that a macOS user reaches: the wrapper itself plus the two pre-commit
+# hook scripts.
 echo ""
-echo "--- no unguarded array expansion remains in vale-wrap.sh ---"
+echo "--- no unguarded array expansion remains in the macOS-facing scripts ---"
 unguarded_expansions() {
-  # Blank out whole-line comments (keeping line numbers), delete every correctly
-  # guarded expansion, then anything still matching is a real hazard.
-  awk '{ if ($0 ~ /^[[:space:]]*#/) print ""; else print }' "$1" \
-    | sed -E 's/\$\{([A-Za-z_][A-Za-z0-9_]*)\[@\]\+"\$\{\1\[@\]\}"\}//g' \
-    | grep -nE '\$\{[A-Za-z_][A-Za-z0-9_]*\[@\]\}' || true
+  local file="$1" hit name
+  while IFS= read -r hit; do
+    name="$(printf '%s\n' "$hit" \
+      | grep -oE '\$\{[A-Za-z_][A-Za-z0-9_]*\[@\]\}' | head -1 \
+      | sed -E 's/^\$\{//; s/\[@\]\}$//')"
+    if grep -qE "^[[:space:]]*((local|declare|readonly)[[:space:]]+)?(-a[[:space:]]+)?$name=\([^)]" "$file" \
+      && ! grep -qE "^[[:space:]]*$name=\(\)" "$file"; then
+      continue
+    fi
+    printf '%s:%s\n' "${file##*/}" "$hit"
+  done < <(
+    # Blank out whole-line comments (keeping line numbers), delete every
+    # correctly guarded expansion, then anything still matching is a candidate.
+    awk '{ if ($0 ~ /^[[:space:]]*#/) print ""; else print }' "$file" \
+      | sed -E 's/\$\{([A-Za-z_][A-Za-z0-9_]*)\[@\]\+"\$\{\1\[@\]\}"\}//g' \
+      | grep -nE '\$\{[A-Za-z_][A-Za-z0-9_]*\[@\]\}' || true
+  )
 }
-HAZARDS16="$(unguarded_expansions "$SCRIPT")"
+HAZARDS16=""
+for BASH32_SCRIPT in \
+  "$SCRIPT" \
+  "$REPO_ROOT/scripts/skill-size-check.sh" \
+  "$REPO_ROOT/scripts/check-release-needed.sh"; do
+  FOUND16="$(unguarded_expansions "$BASH32_SCRIPT")"
+  if [[ -n "$FOUND16" ]]; then
+    HAZARDS16+="$FOUND16 "
+  fi
+done
 if [[ -n "$HAZARDS16" ]]; then
   fail "unguarded array expansion(s) abort on bash < 4.4 under set -u: $(echo "$HAZARDS16" | tr '\n' ' ')"
 else
@@ -500,6 +534,238 @@ else
   fail "a path argument with a space was split by the array expansion: $OUT18"
 fi
 
+# The cases below share one cleanup list. The per-case trap rebuilding above
+# does not scale past the fixture count it already carries, and this trap is
+# installed last, so it is the one that runs.
+EXTRA_FIXTURES=()
+new_fixture() { EXTRA_FIXTURES+=("$1"); }
+cleanup_all() {
+  rm -rf "$FIXTURE1" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" \
+    "$FIXTURE7" "$FIXTURE8" "$FIXTURE10" "$FIXTURE11" "$FIXTURE12" "$STUB13" \
+    "$FIXTURE14" "$FIXTURE17" "$FIXTURE18" \
+    ${EXTRA_FIXTURES[@]+"${EXTRA_FIXTURES[@]}"}
+}
+trap cleanup_all EXIT
+
+# --- 19. Every YAML form whose parsed value is joined back out of 2+ physical
+# lines breaks the `text.frontmatter.description` scope identically, not just
+# the `>` folded block the flattener originally handled: a plain scalar wrapped
+# onto continuation lines, a double-quoted one, a single-quoted one, and a bare
+# `description:` whose value starts on the next line all report zero alerts
+# under bare vale. Each must come back with the same alerts as the single-line
+# spelling of the same sentence. Line and column numbers legitimately move (the
+# value lands on one physical line), so the comparison drops the `line:col`
+# prefix and compares the alert text — message, matched token, and rule name.
+REL_SKILL19="plugins/testplugin/skills/zzzskill/SKILL.md"
+DESC19_A="Use when the caller helps with a specific job"
+DESC19_B="and the second physical line will utilize the wrap"
+
+# make_form_fixture spells the same two-clause description in one YAML scalar
+# form: single, folded, plain, dquote, squote, or keyonly.
+make_form_fixture() {
+  local form="$1" dir
+  dir="$(mktemp -d)"
+  new_fixture "$dir"
+  (cd "$dir" && git init -q)
+  mkdir -p "$dir/plugins/testplugin/skills/zzzskill"
+  {
+    echo "---"
+    echo "name: zzzskill"
+    case "$form" in
+      single) echo "description: $DESC19_A $DESC19_B" ;;
+      folded) echo "description: >"; echo "  $DESC19_A"; echo "  $DESC19_B" ;;
+      plain) echo "description: $DESC19_A"; echo "  $DESC19_B" ;;
+      dquote) echo "description: \"$DESC19_A"; echo "  $DESC19_B\"" ;;
+      squote) echo "description: '$DESC19_A"; echo "  $DESC19_B'" ;;
+      keyonly) echo "description:"; echo "  $DESC19_A"; echo "  $DESC19_B" ;;
+      *) echo "make_form_fixture: unknown form '$form'" >&2; exit 1 ;;
+    esac
+    echo "---"
+    echo ""
+    echo "Body."
+  } > "$dir/plugins/testplugin/skills/zzzskill/SKILL.md"
+  echo "$dir"
+}
+
+# Alert text with the `line:col` prefix and ANSI colouring stripped, sorted.
+alert_text() {
+  echo "$1" \
+    | sed -E 's/\x1b\[[0-9;]*m//g' \
+    | grep -oE '(error|warning|suggestion)[[:space:]]+.*' \
+    | sed -E 's/[[:space:]]+/ /g' \
+    | sort
+}
+
+echo ""
+echo "--- every multi-line description form reports what its single-line form reports ---"
+FIXTURE19_SINGLE="$(make_form_fixture single)"
+BASELINE19="$(alert_text "$(run_wrap "$FIXTURE19_SINGLE" --config "$VALE_CONFIG" "$REL_SKILL19")")"
+if [[ -z "$BASELINE19" ]]; then
+  fail "the single-line baseline reported nothing — the comparison below would be vacuous"
+fi
+for FORM19 in folded plain dquote squote keyonly; do
+  DIR19="$(make_form_fixture "$FORM19")"
+  BARE19="$(cd "$DIR19" && vale --config "$VALE_CONFIG" "$REL_SKILL19" 2>&1 || true)"
+  GOT19="$(alert_text "$(run_wrap "$DIR19" --config "$VALE_CONFIG" "$REL_SKILL19")")"
+  if echo "$BARE19" | grep -q "VagueWording"; then
+    fail "bare vale already flags the $FORM19 form, so this case can't detect a silently-skipped flattening"
+  elif [[ "$GOT19" == "$BASELINE19" ]]; then
+    pass "a $FORM19 multi-line description reports the same alerts as its single-line form"
+  else
+    fail "a $FORM19 multi-line description diverged from its single-line form: got [$GOT19]"
+  fi
+done
+
+# --- 20. A style token containing an ASCII apostrophe matches inside a
+# flattened description. The flattener used to substitute U+2019 for every `'`
+# before writing the scratch copy, so no rule whose token carried an apostrophe
+# could ever fire on a flattened description — a silent, rule-shaped blind spot.
+# Both branches that can hold an apostrophe verbatim are exercised: a value that
+# is safe unquoted, and one that must be quoted (it contains `: `) and so has to
+# land in a double-quoted scalar, since a single-quoted one would need the `''`
+# escape that kills the scope outright.
+echo ""
+echo "--- a style token containing an apostrophe matches in a flattened description ---"
+APOS_STYLE="$(mktemp -d)"
+new_fixture "$APOS_STYLE"
+mkdir -p "$APOS_STYLE/styles/Apostrophe"
+cat > "$APOS_STYLE/styles/Apostrophe/Token.yml" <<'EOF'
+extends: existence
+message: "apostrophe token: '%s'"
+level: error
+scope: text.frontmatter.description
+ignorecase: true
+tokens:
+  - "user's task"
+EOF
+cat > "$APOS_STYLE/.vale.ini" <<'EOF'
+StylesPath = styles
+
+[**/SKILL.md]
+BasedOnStyles = Apostrophe
+EOF
+FIXTURE20_PLAIN="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Use when the user's task needs handling, and a second physical
+  line continues the folded scalar.
+---
+
+Body.
+EOF
+)"
+new_fixture "$FIXTURE20_PLAIN"
+FIXTURE20_QUOTED="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Triggers on: the user's task needing handling, and a second
+  physical line continues the folded scalar.
+---
+
+Body.
+EOF
+)"
+new_fixture "$FIXTURE20_QUOTED"
+for CASE20 in "unquoted:$FIXTURE20_PLAIN" "double-quoted:$FIXTURE20_QUOTED"; do
+  if run_wrap "${CASE20#*:}" --config "$APOS_STYLE/.vale.ini" "$REL_SKILL19" \
+    | grep -q "Apostrophe.Token"; then
+    pass "an apostrophe-bearing token matches in a flattened ${CASE20%%:*} description"
+  else
+    fail "an apostrophe-bearing token was rewritten out of a flattened ${CASE20%%:*} description"
+  fi
+done
+
+# --- 20b. The one combination no verbatim YAML scalar can carry — needs
+# quoting, holds an apostrophe, and holds a double quote — falls back to the
+# lossy U+2019 substitution. Apostrophe-bearing tokens are lost there by
+# design, but the scope must stay alive so every other rule still fires.
+echo ""
+echo "--- the unrepresentable combination keeps the description scope alive ---"
+FIXTURE20C="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Triggers on: the user's "audit this" phrasing, which helps with
+  and utilize things across a second physical line.
+---
+
+Body.
+EOF
+)"
+new_fixture "$FIXTURE20C"
+if run_wrap "$FIXTURE20C" --config "$VALE_CONFIG" "$REL_SKILL19" | grep -q "VagueWording"; then
+  pass "a description needing quotes with both an apostrophe and a double quote is still linted"
+else
+  fail "a description needing quotes with both an apostrophe and a double quote produced no alerts"
+fi
+
+# --- 21. A symlinked file inside a directory argument is mirrored and linted.
+# Vale follows symlinks (both a symlinked file and a file under a symlinked
+# directory), so a `-type f` walk of the tree reported "0 files" where bare vale
+# reports one — and the audit skills read a "0 files" report as NOT RUN.
+echo ""
+echo "--- mirrors a symlinked file reached through a directory argument ---"
+FIXTURE21="$(make_fixture 2)"
+new_fixture "$FIXTURE21"
+mkdir -p "$FIXTURE21/real"
+mv "$FIXTURE21/$REL_SKILL19" "$FIXTURE21/real/SKILL.md"
+ln -s ../../../../real/SKILL.md "$FIXTURE21/$REL_SKILL19"
+BARE21="$(cd "$FIXTURE21" && vale --config "$VALE_CONFIG" plugins 2>&1 || true)"
+WRAPPED21="$(run_wrap "$FIXTURE21" --config "$VALE_CONFIG" plugins)"
+BARE21_FILES="$(echo "$BARE21" | sed -E 's/\x1b\[[0-9;]*m//g' | grep -oE 'in [0-9]+ files?' | tail -1)"
+WRAPPED21_FILES="$(echo "$WRAPPED21" | sed -E 's/\x1b\[[0-9;]*m//g' | grep -oE 'in [0-9]+ files?' | tail -1)"
+if [[ "$BARE21_FILES" != "in 1 file" ]]; then
+  fail "bare vale did not lint the symlinked file ($BARE21_FILES), so this case can't detect the walk dropping it"
+elif [[ "$WRAPPED21_FILES" != "$BARE21_FILES" ]]; then
+  fail "the directory walk dropped a symlinked file: wrapper saw '$WRAPPED21_FILES', bare vale '$BARE21_FILES'"
+elif echo "$WRAPPED21" | grep -q "VagueWording"; then
+  pass "a symlinked file under a directory argument is mirrored, flattened and flagged"
+else
+  fail "a symlinked file was mirrored but not flattened — no alert came back"
+fi
+
+# --- 22. The value of a separated two-argv flag is never treated as a lint
+# target, however file-like it looks. `--output tmpl.tmpl` names a real
+# template file: classifying it as input both linted the template and reordered
+# argv, so vale received `--output --no-wrap` and died on `open :`.
+echo ""
+echo "--- a separated flag value that names a real file is not linted as a target ---"
+FIXTURE22="$(make_fixture 1)"
+new_fixture "$FIXTURE22"
+printf 'TMPL{{range .Files}} {{.Path}}{{end}}\n' > "$FIXTURE22/tmpl.tmpl"
+WRAPPED22="$(run_wrap "$FIXTURE22" --config "$VALE_CONFIG" --output tmpl.tmpl --no-wrap "$REL_SKILL19")"
+BARE22="$(cd "$FIXTURE22" && vale --config "$VALE_CONFIG" --output tmpl.tmpl --no-wrap "$REL_SKILL19" 2>&1 || true)"
+# The fixture's description is a single physical line, so flattening is a no-op
+# and the two invocations must agree byte for byte.
+if [[ "$WRAPPED22" == "$BARE22" ]]; then
+  pass "a separated --output value is passed through to vale, not linted"
+else
+  fail "a separated --output value was misrouted: wrapper gave [$WRAPPED22], bare vale [$BARE22]"
+fi
+
+# --- 23. A path argument that does not exist is a hard error. Bare vale drops
+# it, falls back to stdin and prints `0 errors ... in stdin` with exit 0, so a
+# typo'd target is indistinguishable from a clean run — and the audit skills'
+# NOT RUN guard string-matches `0 files`, which `in stdin` never produces. This
+# is a deliberate divergence from bare vale, documented in the wrapper header.
+echo ""
+echo "--- a nonexistent path argument fails loudly instead of falling back to stdin ---"
+set +e
+OUT23="$(cd "$FIXTURE22" && bash "$SCRIPT" --config "$VALE_CONFIG" plugins/testplugin/skills/zzzskill/SKILLL.md 2>&1)"
+RC23=$?
+set -e
+if [[ $RC23 -eq 0 ]]; then
+  fail "a typo'd path exited 0 — indistinguishable from a clean run, the bug this test guards against"
+elif echo "$OUT23" | grep -q "in stdin"; then
+  fail "a typo'd path fell back to reading stdin and reported 'in stdin' instead of erroring"
+elif echo "$OUT23" | grep -q "SKILLL.md"; then
+  pass "a typo'd path exits nonzero with a message naming the path"
+else
+  fail "a typo'd path exited $RC23 but the message does not name it: $OUT23"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 4ae24298407cdcecfbb337de0d995e9ada0b6451 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 15:44:16 +0000
Subject: [PATCH 29/45] fix(kyberforge): align the audit word ceiling and drop
 the fragile --config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three divergences between what the audit skills claim and what the hooks
enforce, each of which fails silently rather than loudly:

- `skill-size-check.sh` blocked at 2900 words while `validate.sh` checked only
  the 500-line ceiling, so `/skill-audit` could report a skill ready to ship
  that the commit hook then rejected. `validate.sh` now checks the same pair on
  the same inclusive terms; the constants are duplicated with a comment naming
  the other file, because a plugin skill's scripts cannot read outside the
  plugin directory once installed to the cache.
- Both audit skills' Step 1 passed `--config assets/vale/.vale.ini`, which is
  redundant (the wrapper self-locates its sibling config) and fragile: an agent
  that resolves the script path against the skill directory but not the config
  path gets E100, exit 2, which the surrounding fallback clause misreads as
  "vale unavailable" and downgrades to full LLM judgment with no signal.
- The external-consumer test registered only the two Vale hooks, never the
  third shipped hook, so a lost executable bit would have broken every consumer
  while the local suite stayed green. Verified by mutation: `chmod 644` on the
  copied script now turns three passes into two failures.

Also corrects the size hook's calibration comment, which claimed ~5.7-6.5
characters per word against a corpus whose measured median is 6.79 — the stated
upper bound sat below the median, so the "calibrated with margin" claim was
inverted for prose-dense files. MAX_WORDS is unchanged pending a decision; the
comment is now explicit that the gate holds under 5,000 tokens for typical
prose density, not for any file.

Refs: #85
---
 .../kyberforge/skills/agent-audit/SKILL.md    |  4 +-
 .../kyberforge/skills/skill-audit/SKILL.md    |  4 +-
 .../skills/skill-audit/scripts/validate.sh    | 24 ++++++++--
 scripts/skill-size-check.sh                   | 23 +++++++---
 tests/test-skill-size-check.sh                |  8 ++--
 tests/test-vale-hooks-consumer.sh             | 44 ++++++++++++++++---
 6 files changed, 85 insertions(+), 22 deletions(-)

diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md
index 7d82ed4..08cc88d 100644
--- a/plugins/kyberforge/skills/agent-audit/SKILL.md
+++ b/plugins/kyberforge/skills/agent-audit/SKILL.md
@@ -36,12 +36,12 @@ metadata:
 ```bash
 bash scripts/validate.sh <path-to-agent-file>
 bash scripts/validate-provenance.sh <path-to-agent-file>
-scripts/vale-wrap.sh --config assets/vale/.vale.ini <path-to-cc-file> <path-to-copilot-file>
+scripts/vale-wrap.sh <path-to-cc-file> <path-to-copilot-file>
 ```
 
 The script accepts either the CC file or the Copilot file. It detects provider from extension, derives the counterpart, and runs all structural checks. Note FAILs and SUGGESTIONs for the `### Structure` and `### Provider safety` report dimensions. Findings about missing fields, bad name format, empty body, or missing frontmatter → `### Structure`. Findings about CC-only fields in a Copilot file, Copilot-only fields in a CC file, plugin-silently-ignored fields, body length, or subagent-unavailable tools → `### Provider safety`. A missing counterpart file → `### Pair consistency`.
 
-`vale-wrap.sh` and `.vale.ini` ship inside this skill's own `scripts/`/`assets/` — resolve them relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one in the `### Description` / `### Body` dimensions citing its rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 2 judgment for the dimensions it would have covered.
+`vale-wrap.sh` ships inside this skill's own `scripts/` — resolve it relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. Pass no `--config`: handed none, the wrapper loads its own sibling `assets/vale/.vale.ini`, located from the script's path rather than from the cwd. Adding an explicit relative `--config` breaks exactly the case the self-location covers — a resolved script path plus an unresolved config path yields `E100 Runtime error ... does not exist`, exit 2, which the fallback below then misreads as "vale unavailable". Run it against both files of the pair (not just the one passed in). `Kyberforge` applies to both files; `KyberforgeCopilot` applies to the `.agent.md` file only, since its one rule (`Use proactively`) flags CC-specific phrasing that's meaningless in a Copilot description — there's nothing to flag in the CC file, so it isn't scoped there. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one in the `### Description` / `### Body` dimensions citing its rule ID (e.g. `KyberforgeCopilot.ProactivePhrase`). Skip and fall back to Step 2 judgment if the `vale` binary is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 2 judgment for the dimensions it would have covered.
 
 `validate-provenance.sh` validates the provenance chain between the agent pair's `source_keys` and the plugin-scoped `sources.md` (plugin root — see ADR-0010). It exits 0 silently for non-plugin-scope agents and when no provenance data exists. Note FAILs from this script for the `### Provenance` dimension — surface them verbatim with Why and Fix.
 
diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index f0c965d..6f71299 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -34,14 +34,14 @@ metadata:
 ```bash
 bash scripts/validate.sh <skill-dir>
 bash scripts/validate-provenance.sh <skill-dir>
-scripts/vale-wrap.sh --config assets/vale/.vale.ini <skill-dir>/SKILL.md
+scripts/vale-wrap.sh <skill-dir>/SKILL.md
 ```
 
 Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
-`vale-wrap.sh` and `.vale.ini` ship inside this skill's own `scripts/`/`assets/` — resolve them relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. It applies `.vale.ini`'s `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns/Body dimensions below, not a replacement for Step 3. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one citing its rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if vale or `.vale.ini` is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 3 judgment for the dimensions it would have covered.
+`vale-wrap.sh` ships inside this skill's own `scripts/` — resolve it relative to this skill's directory the same way `scripts/validate.sh` is resolved above, so the invocation works whether this skill is running from this repo or from an installed plugin cache. Pass no `--config`: handed none, the wrapper loads its own sibling `assets/vale/.vale.ini`, located from the script's path rather than from the cwd. Adding an explicit relative `--config` breaks exactly the case the self-location covers — a resolved script path plus an unresolved config path yields `E100 Runtime error ... does not exist`, exit 2, which the fallback below then misreads as "vale unavailable". It applies that config's `Kyberforge` style — a deterministic prefilter for a subset of the Description/Patterns/Body dimensions below, not a replacement for Step 3. Every Vale alert is a `FAIL` — all rules are graded `error` — so report each one citing its rule ID (e.g. `Kyberforge.DescriptionOpener`). Skip and fall back to Step 3 judgment if the `vale` binary is unavailable. If Vale reports `0 files` scanned, treat the pass as NOT RUN — not as clean — and fall back to full Step 3 judgment for the dimensions it would have covered.
 
 ## Step 2 — Read all skill files
 
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/validate.sh b/plugins/kyberforge/skills/skill-audit/scripts/validate.sh
index 5203bad..e9ac95b 100755
--- a/plugins/kyberforge/skills/skill-audit/scripts/validate.sh
+++ b/plugins/kyberforge/skills/skill-audit/scripts/validate.sh
@@ -133,12 +133,28 @@ else:
     if desc:
         ok("description has no unfilled placeholders")
 
-# SKILL.md line count
+# SKILL.md size ceilings (agentskills.io skill-authoring.md: 500 lines,
+# ~5,000 tokens). Both constants are DUPLICATED from the repo-root pre-commit
+# hook scripts/skill-size-check.sh — a plugin skill's scripts cannot read files
+# outside the plugin directory once the plugin is cache-installed, so there is
+# no single source to share. Keep the two in sync by hand: if they drift, this
+# audit will report a skill ready to ship that the commit hook then rejects.
+MAX_LINES = 500
+MAX_WORDS = 2900  # word-count proxy for the ~5,000-token ceiling
+
 line_count = len(content.splitlines())
-if line_count <= 500:
-    ok(f"SKILL.md line count {line_count} (limit: 500)")
+if line_count <= MAX_LINES:
+    ok(f"SKILL.md line count {line_count} (limit: {MAX_LINES})")
 else:
-    fail(f"SKILL.md line count {line_count} — exceeds 500-line limit")
+    fail(f"SKILL.md line count {line_count} — exceeds {MAX_LINES}-line limit")
+
+# str.split() with no argument splits on runs of whitespace, matching the
+# `wc -w` the hook uses, and counts the whole file including frontmatter.
+word_count = len(content.split())
+if word_count <= MAX_WORDS:
+    ok(f"SKILL.md word count {word_count} (limit: {MAX_WORDS}, proxy for ~5,000 tokens)")
+else:
+    fail(f"SKILL.md word count {word_count} — exceeds {MAX_WORDS}-word limit (proxy for ~5,000 tokens)")
 
 # Body unfilled placeholders
 body = content[body_start:]
diff --git a/scripts/skill-size-check.sh b/scripts/skill-size-check.sh
index 696f4fa..3f877b4 100755
--- a/scripts/skill-size-check.sh
+++ b/scripts/skill-size-check.sh
@@ -15,12 +15,23 @@ set -euo pipefail
 # audit and still be blocked by the commit hook.
 #
 # Token counts aren't computed exactly here — word count (`wc -w`) is used as
-# a proxy. This repo's own SKILL.md corpus measures ~5.7-6.5 characters per
-# word, which at the standard ~4-characters-per-token English approximation
-# works out to roughly 1.6-1.7 tokens per word. MAX_WORDS below is calibrated
-# from that measured ratio against the 5,000-token ceiling, with margin — it's
-# still a proxy, not exact BPE tokenization, but now grounded in actual repo
-# content rather than an unverified "conservative" assumption.
+# a proxy. Measured over this repo's 39 in-scope SKILL.md files, characters per
+# word runs min 5.97 / median 6.79 / mean 6.77 / max 7.22. At the standard
+# ~4-characters-per-token English approximation that is 1.49 / 1.70 / 1.69 /
+# 1.81 tokens per word.
+#
+# MAX_WORDS=2900 is therefore calibrated to the corpus MEDIAN, not to its worst
+# case, and carries no margin: 2900 x 1.70 = ~4,900 tokens for a median-density
+# file, but 2900 x 1.81 = ~5,240 tokens for the densest file in the corpus. So
+# what this gate actually guarantees is "under 5,000 tokens for a file of
+# typical prose density"; a prose-dense SKILL.md can sit at exactly MAX_WORDS
+# and still be a few hundred tokens over the agentskills.io ceiling. Holding
+# the worst observed ratio under 5,000 tokens would need MAX_WORDS ~2770.
+#
+# It is a one-sided proxy in the useful direction — nothing under the word
+# ceiling is wildly over the token ceiling — but it is not exact BPE
+# tokenization and does not replace one. Re-measure the corpus before treating
+# any of these numbers as still current.
 
 MAX_LINES=500
 MAX_WORDS=2900
diff --git a/tests/test-skill-size-check.sh b/tests/test-skill-size-check.sh
index fd98e4b..32133db 100755
--- a/tests/test-skill-size-check.sh
+++ b/tests/test-skill-size-check.sh
@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 # Regression test for scripts/skill-size-check.sh: enforces agentskills.io's
-# 500-line/5,000-word(proxy-for-token) SKILL.md size ceiling.
+# 500-line/5,000-token SKILL.md size ceiling. The token half is enforced via a
+# word-count proxy (MAX_WORDS, currently 2900) — 5,000 is the token ceiling,
+# 2,900 is the word budget the script derives from it.
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -55,9 +57,9 @@ echo ""
 echo "--- fails a file over the word-count limit ---"
 MANY_WORDS="$(make_fixture many-words 10 600)"
 if "$SCRIPT" "$MANY_WORDS" 2>/dev/null; then
-  fail "file over the 5,000-word ceiling should have exited non-zero"
+  fail "file over the word ceiling should have exited non-zero"
 else
-  pass "file over the 5,000-word ceiling exits non-zero"
+  pass "file over the word ceiling exits non-zero"
 fi
 
 # Boundary-pair tests below read the script's current MAX_WORDS rather than
diff --git a/tests/test-vale-hooks-consumer.sh b/tests/test-vale-hooks-consumer.sh
index ef05a51..c0eb6a7 100755
--- a/tests/test-vale-hooks-consumer.sh
+++ b/tests/test-vale-hooks-consumer.sh
@@ -47,8 +47,11 @@ git -C "$HOOK_REPO" add -A
 git -C "$HOOK_REPO" -c user.email=test@example.invalid -c user.name=test commit -qm "hook repo"
 HOOK_REV="$(git -C "$HOOK_REPO" rev-parse HEAD)"
 
-# The two Vale hooks scope by filename, so the consumer needs one file of each
-# shape: a hook with nothing to match reports `Skipped` and proves nothing.
+# Every hook scopes by filename, so the consumer needs one file of each shape:
+# a hook with nothing to match reports `Skipped` and proves nothing. All three
+# hooks .pre-commit-hooks.yaml ships are registered — an unregistered one would
+# let a regression (a lost `100755` bit, a bad entry path) reach every external
+# consumer while this repo's own `repo: local` runs stayed green.
 mkdir -p "$CONSUMER/skills/demo" "$CONSUMER/agents"
 git -C "$CONSUMER" init -q
 cat > "$CONSUMER/.pre-commit-config.yaml" <<EOF
@@ -58,6 +61,7 @@ repos:
     hooks:
       - id: kyberforge-vale-audit-skill
       - id: kyberforge-vale-audit-agent
+      - id: kyberforge-skill-size-check
 EOF
 
 write_fixtures() {
@@ -109,19 +113,49 @@ fi
 
 # --- 2. Clean files pass — the hooks gate, they don't just always fail ---
 echo ""
-echo "--- both Vale hooks pass clean files in an external consumer repo ---"
+echo "--- all three hooks pass clean files in an external consumer repo ---"
 write_fixtures "of the packaged hook contract"
 set +e
 (cd "$CONSUMER" && pre-commit run --all-files > "$WORK/clean.log" 2>&1)
 RC_CLEAN=$?
 set -e
-if [[ $RC_CLEAN -eq 0 ]]; then
-  pass "both hooks exit 0 on clean files"
+if grep -q "Skipped" "$WORK/clean.log"; then
+  fail "a hook matched no files on the clean run, so it proved nothing"
+  sed 's/^/    /' "$WORK/clean.log"
+elif [[ $RC_CLEAN -eq 0 ]]; then
+  pass "all three hooks exit 0 on clean files"
 else
   fail "hooks failed on clean files (rc=$RC_CLEAN)"
   sed 's/^/    /' "$WORK/clean.log"
 fi
 
+# --- 3. The size hook gates too. It ran clean above, which is what proves it
+# is executable and its entry path resolves; this half proves it still fails a
+# file that breaks the ceiling rather than passing everything. ---
+echo ""
+echo "--- kyberforge-skill-size-check fails an oversized SKILL.md in an external consumer repo ---"
+mkdir -p "$CONSUMER/skills/oversized"
+{
+  echo "---"
+  echo "name: oversized"
+  echo "description: Use when the caller wants an oversized fixture."
+  echo "---"
+  for ((i = 1; i <= 600; i++)); do
+    echo "word"
+  done
+} > "$CONSUMER/skills/oversized/SKILL.md"
+git -C "$CONSUMER" add -A
+set +e
+(cd "$CONSUMER" && pre-commit run kyberforge-skill-size-check --all-files > "$WORK/size.log" 2>&1)
+RC_SIZE=$?
+set -e
+if [[ $RC_SIZE -ne 0 ]] && grep -q "500-line ceiling" "$WORK/size.log"; then
+  pass "kyberforge-skill-size-check exits non-zero and names the ceiling it broke"
+else
+  fail "kyberforge-skill-size-check did not gate an oversized SKILL.md (rc=$RC_SIZE)"
+  sed 's/^/    /' "$WORK/size.log"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 57654c4b02d5e62e1d7fe00235d90ed55631f7aa Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 15:44:28 +0000
Subject: [PATCH 30/45] docs(lint): correct the Vale scalar, size-ceiling and
 release-gate claims
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four claims in shipped agent-facing docs did not match verified behaviour.
These are read as ground truth by agents in other repos, so each was
reproduced against vale 3.15.2 before rewriting:

- CONTEXT.md and `vale-config/SKILL.md` said both `>` and `|` block scalars
  break the description scope. `|` does not — it lints normally and fires every
  alert, while `>` yields zero. An agent following the old text would rewrite a
  working `|` description into a plain multi-line scalar, which genuinely does
  break, inverting the intended remediation. Both now name the forms that do
  break and state that `|` does not.
- CONTEXT.md and ADR-0013 described the size hook as failing only above 500
  lines, omitting the 2900-word gate it also enforces. Both now describe the
  pair and state that `validate.sh` checks the same two.
- ADR-0014 recorded an accepted residual — a wholesale `assets/` deletion going
  unflagged — that commit 14c2c91 closed. Left as the point-in-time record and
  amended with an update describing the union-with-tag-manifest mechanism,
  following the amendment precedent in ADR-0005.
- `vale-config/SKILL.md` asserted a fresh `.vale.ini` fails until `vale sync`
  runs, contradicting its own note that built-in styles need no download. The
  claim is now scoped to package styles; this repo's two configs declare no
  packages and lint clean with zero syncs.

Also repoints AGENTS.md at the seven `gitea:*` skills — the `bin:gitea` route
it named no longer exists.

Refs: #85
---
 AGENTS.md                                     |  2 +-
 CONTEXT.md                                    |  4 ++--
 ...013-vale-harness-scope-and-rule-sources.md |  9 +++++++--
 ...14-vale-prefilter-ships-from-the-plugin.md | 20 ++++++++++++++++---
 plugins/lint/skills/vale-config/SKILL.md      |  4 ++--
 5 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 995a2c1..d169ff3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,7 @@ This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint t
 
 - Commits, branches, history, worktrees, remotes → `git:git-commits`, `git:git-branches`, `git:git-history`, `git:git-worktrees`, `git:git-remotes`
 - Pre-commit hook install/config/troubleshooting → `git:pc-run` / `git:pc-author`
-- Issues, PRs, labels, milestones → `bin:gitea`
+- Issues, PRs, labels, milestones → `gitea:gitea-issues`, `gitea:gitea-prs`, `gitea:gitea-labels-milestones`; also `gitea:gitea-branches`, `gitea:gitea-files`, `gitea:gitea-releases`, or `gitea:gitea-workflow` when the domain is ambiguous
 - Vale prose linting → `lint:vale-config` / `lint:vale-run`
 - This repo's own AGENTS.md → `core:agentsmd-author` / `core:agentsmd-audit`
 
diff --git a/CONTEXT.md b/CONTEXT.md
index 143bf74..b386d21 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -72,9 +72,9 @@ A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running
 ### Vale audit prefilter (skill-audit / agent-audit)
 Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
 
-Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching once the description is a YAML block scalar (`>`/`|`) spanning 2+ physical lines, which is how most skills/agents in this repo write it. The wrapper flattens the description to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; single-line descriptions pass through untouched. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root; both audit skills' Step 1 still passes `--config assets/vale/.vale.ini` and is unaffected. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
+Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions. Verified by reproduction, not assumed: `>` folded scalars, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars all yield 0 alerts and exit 0 on a deliberately-bad fixture, while a `|` literal block spanning the same 2+ lines lints normally (alerts fire, exit 1). The wrapper flattens those three broken forms to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; `|` literal blocks and single-line descriptions pass through untouched, already linting correctly. The plain and quoted forms previously passed silently — unflattened and unmatched — so a bad description in either sailed through the prefilter. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root. Both audit skills' Step 1 now passes no `--config` either: it resolves the script relative to the skill's own directory so the call works from an installed plugin cache, but a relative `--config` alongside it would still resolve against the cwd, yielding `E100 Runtime error ... does not exist` and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to full LLM judgment. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
 
-This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's 500-line/5,000-token `SKILL.md` ceiling — failing only above 500 lines, matching `skill-audit/scripts/validate.sh`'s `<= 500` pass — scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
+This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's `SKILL.md` ceiling as two blocking gates: `MAX_LINES=500` and `MAX_WORDS=2900` (a word-count proxy for the 5,000-token limit, calibrated from this repo's measured ~1.6-1.7 tokens per word). Both are inclusive, and `skill-audit/scripts/validate.sh` checks the same pair on the same terms, so a `SKILL.md` can no longer pass its own audit yet be blocked by the commit hook. Scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
 
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/docs/adr/0013-vale-harness-scope-and-rule-sources.md b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
index 2227a9e..1774b89 100644
--- a/docs/adr/0013-vale-harness-scope-and-rule-sources.md
+++ b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
@@ -95,8 +95,13 @@ every rule to `level: error` is what actually implements this decision.
   catch does not pay for a permanent suppression, so the rule is deleted and this ADR's
   "cherry-picked rules" is one rule, not two.
 - A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
-  500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. It fails only *above*
-  500 lines, matching `skill-audit/scripts/validate.sh`'s long-standing `<= 500` pass.
+  500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. Both halves of that
+  ceiling are blocking gates, not just the line count: `MAX_LINES=500`, and `MAX_WORDS=2900` as a
+  word-count proxy for the 5,000-token limit (calibrated from this repo's measured ~1.6-1.7 tokens
+  per word — `wc -w` is not BPE tokenization). Either one exceeded fails the hook. Both are
+  inclusive: a file at exactly 500 lines or exactly 2,900 words passes, and only one past a ceiling
+  fails. `skill-audit/scripts/validate.sh` enforces the same pair on the same inclusive terms, so
+  the audit and the commit hook cannot disagree about whether a given `SKILL.md` is over size.
 - `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
   future reader doesn't wonder if a trial tier was forgotten.
 - The styles-portability question — whether `styles/` and `.vale.ini` should move into
diff --git a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
index ccdb972..7226dea 100644
--- a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
+++ b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
@@ -151,6 +151,20 @@ doesn't wonder if it was overlooked.
   script now derives the bundle's `assets/` tree from `tokens[0]` instead (double-`dirname`,
   guarded on the candidate existing and on not resolving to `.`), which is the only derivation
   compatible with the argument-free `entry:` contract above.
-- **Accepted residual in the release gate:** deleting a hook's *entire* `assets/` tree is not
-  flagged — the derived candidate path stops existing, so the guard drops it before it reaches
-  the pathspec. Deleting individual files inside a surviving tree is flagged, and tested.
+- **Accepted residual in the release gate (closed — see the update below):** deleting a hook's
+  *entire* `assets/` tree is not flagged — the derived candidate path stops existing, so the guard
+  drops it before it reaches the pathspec. Deleting individual files inside a surviving tree is
+  flagged, and tested.
+
+**Update (commit `14c2c91`):** the accepted residual above no longer holds and is recorded here
+only as the state at the time this ADR was written. `check-release-needed.sh` no longer derives
+release-relevant paths from the worktree alone. It runs `collect_release_paths` twice — once over
+the worktree's `.pre-commit-hooks.yaml`, once over the manifest read back from `$LAST_TAG` via
+`git cat-file -p "$LAST_TAG:$HOOKS_MANIFEST"` — and unions the two path sets, so a path the tag
+exposed stays in the pathspec even after the worktree's `-d` guard drops it. Wholesale deletion of
+a hook's bundled `assets/` tree is therefore flagged, and `tests/test-check-release-needed.sh`
+(case 12) asserts exit 1 for exactly that case. The union does not over-fire: any manifest edit
+that makes the two disagree already touches `$HOOKS_MANIFEST`, itself a release-relevant path. An
+unreadable tagged tree (shallow clone, truncated fetch) fails closed rather than silently degrading
+to worktree-only derivation; a manifest simply absent at the tag — legitimate, it was added since —
+does not.
diff --git a/plugins/lint/skills/vale-config/SKILL.md b/plugins/lint/skills/vale-config/SKILL.md
index 731b361..c5b192f 100644
--- a/plugins/lint/skills/vale-config/SKILL.md
+++ b/plugins/lint/skills/vale-config/SKILL.md
@@ -19,10 +19,10 @@ metadata:
 
 ## Gotchas
 
-- Installing the `vale` binary installs no styles. A fresh `.vale.ini` with `BasedOnStyles` set will fail or find nothing until `vale sync` runs and downloads the `Packages` it declares.
+- Installing the `vale` binary installs no styles, but only *package* styles need fetching. A fresh `.vale.ini` naming a style in `BasedOnStyles` that is declared in `Packages` will fail or find nothing until `vale sync` downloads it. A built-in style (`Vale`) or a style whose YAML rule files are already committed under `StylesPath` lints immediately, with no `Packages` entry and no sync.
 - `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob.
 - `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget.
-- A rule scoped to `text.frontmatter.<key>` (e.g. `text.frontmatter.description`) only reliably matches when that field's value is a single physical line. If it's a YAML block scalar (`>`/`|`) spanning 2+ physical lines, the scope silently stops matching — no error, just 0 findings — confirmed against Vale 3.15.2. Verify with a deliberately-bad multi-line fixture before trusting a frontmatter-scoped rule in production; if the field is commonly authored as a multi-line block scalar, flatten it to one line ahead of the `vale` call rather than relying on the scope alone.
+- A rule scoped to `text.frontmatter.<key>` (e.g. `text.frontmatter.description`) matches reliably when that field's value is a single physical line, and breaks on most — not all — multi-line forms. Confirmed against Vale 3.15.2 with a deliberately-bad fixture: a `>` folded block scalar, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars each yield 0 findings and exit 0, silently and with no error; a `|` literal block scalar spanning the same 2+ lines lints normally and exits 1. Do not assume `|` and `>` behave alike — reproduce both against your own config before trusting a frontmatter-scoped rule in production. If the field is commonly authored in one of the broken forms, flatten it to one physical line ahead of the `vale` call rather than relying on the scope alone.
 
 ## Setup workflow
 
-- 
2.43.0


From d25355077fc0146f04ebc7a307d3c3544e22593f Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 17:23:10 +0000
Subject: [PATCH 31/45] fix(lint): attribute Vale alerts per hook and cover
 .vale.ini in the sync check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The external-consumer test asserted a combined alert count (>=2) across both
shipped Vale hooks, but the SKILL.md fixture alone raises two alerts — so one
working hook satisfied the threshold. Retargeting agent-audit's glob to match
nothing left the suite reporting "3 passed" under the message "both hooks
flatten and flag". The Skipped guard does not catch this: the hook still
matches the file, Vale lints nothing, reports 0 errors in 1 file and exits 0,
which pre-commit renders as Passed. An assertion aggregating over N subjects
proves nothing about any individual subject.

Each hook now runs individually and its alerts are attributed to the nearest
preceding path header, so an alert is checked by path rather than by presence
in the combined blob. The two fixtures carry distinct VagueWording tokens, so
one hook's alert cannot be credited to another.

Nothing in the repo read either .vale.ini — the sync check diffed only
vale-wrap.sh and styles/Kyberforge, so a one-line glob typo silently disabled
the prefilter for a whole file type. That was the enabling half of the same
defect. The check now asserts the shared lines both copies must carry
(StylesPath, a section naming Kyberforge as a whole word) without flagging
their intentional divergence, and probes each glob section by asking Vale
itself to lint a representative path. Regex-to-glob comparison was rejected as
it means reimplementing doublestar semantics in bash; a file-count dry-run was
rejected because a section whose glob matches but whose BasedOnStyles lost
Kyberforge reports "1 file" with no alerts and would pass it.

Every new assertion is bound to a failing case in both directions: breaking the
artifact fails the suite, and neutering the assertion fails exactly one case.
That reverse sweep exposed two assertions bound to no failing case at all, one
masked by a stronger check running first.

Refs: #85
---
 scripts/check-vale-style-sync.sh    | 126 ++++++++++++++-
 tests/test-check-vale-style-sync.sh | 227 ++++++++++++++++++++++++++--
 tests/test-vale-hooks-consumer.sh   |  76 +++++++---
 3 files changed, 395 insertions(+), 34 deletions(-)

diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh
index 4f9dd1c..f6ede61 100755
--- a/scripts/check-vale-style-sync.sh
+++ b/scripts/check-vale-style-sync.sh
@@ -10,6 +10,11 @@ set -euo pipefail
 # only one of the two. Run from repo root or pass REPO_ROOT as arg.
 
 REPO_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+# Absolutized because the glob probe below `cd`s into a scratch tree, where a
+# relative --config path would stop resolving.
+if [[ -d "$REPO_ROOT" ]]; then
+  REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+fi
 FAIL=0
 
 err() { echo "  FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
@@ -41,7 +46,126 @@ if ! diff -rq "$SKILL_AUDIT/assets/vale/styles/Kyberforge" "$AGENT_AUDIT/assets/
   err "assets/vale/styles/Kyberforge differs between skill-audit and agent-audit"
 fi
 
+# --- .vale.ini coverage ------------------------------------------------------
+# The two .vale.ini files are deliberately NOT identical — agent-audit's carries
+# an extra [**/*.agent.md] section and the KyberforgeCopilot style — so they
+# cannot be diffed like the styles above. Nothing else in the repo read them at
+# all, and that is what let a one-character glob typo silently disable the
+# prefilter for a whole file type: the hook still MATCHES the file via its
+# `files:` regex, so pre-commit reports neither `Skipped` nor an error; vale
+# lints zero files, prints `0 errors ... in 1 file` and exits 0, and the hook
+# shows `Passed`. So check the parts that must hold in both, not equality.
+
+SKILL_INI="$SKILL_AUDIT/assets/vale/.vale.ini"
+AGENT_INI="$AGENT_AUDIT/assets/vale/.vale.ini"
+
+for ini in "$SKILL_INI" "$AGENT_INI"; do
+  rel_ini="${ini#"$REPO_ROOT"/}"
+  if [[ ! -f "$ini" ]]; then
+    err "$rel_ini is missing — without it vale falls back to an upward config search and lints with whatever it finds"
+    continue
+  fi
+  # StylesPath is resolved relative to the .vale.ini, which is the only reason
+  # the bundled styles are found from a consuming repo's clone prefix.
+  if ! grep -Eq '^[[:space:]]*StylesPath[[:space:]]*=[[:space:]]*styles[[:space:]]*$' "$ini"; then
+    err "$rel_ini has no 'StylesPath = styles' — the bundled styles/ directory would not be found"
+  fi
+  # Matches `Kyberforge` as a whole name, so `KyberforgeCopilot` alone does not
+  # satisfy it. Avoids \b, which is a GNU grep extension.
+  if ! grep -Eq '^[[:space:]]*BasedOnStyles[[:space:]]*=.*Kyberforge([[:space:],]|$)' "$ini"; then
+    err "$rel_ini has no section whose BasedOnStyles names Kyberforge — every rule the audit prefilters on lives in that style"
+  fi
+done
+
+# Prints the `files:` regex of every hook, in either manifest, whose entry is
+# $1's vale-wrap.sh. Records are delimited by their `- id:` line, so the check
+# does not depend on `entry:` preceding `files:` within a record.
+hook_file_regexes() {
+  local skill="$1" manifest raw
+  for manifest in "$REPO_ROOT/.pre-commit-hooks.yaml" "$REPO_ROOT/.pre-commit-config.yaml"; do
+    [[ -f "$manifest" ]] || continue
+    awk -v skill="$skill" '
+      function flush() {
+        if (entry ~ skill "/scripts/vale-wrap.sh" && files != "") print files
+        entry = ""; files = ""
+      }
+      /^[ \t]*-[ \t]*id:/ { flush() }
+      /^[ \t]*entry:/ { entry = $0 }
+      /^[ \t]*files:/ { files = $0; sub(/^[ \t]*files:[ \t]*/, "", files) }
+      END { flush() }
+    ' "$manifest"
+  done | while IFS= read -r raw; do
+    # Strip the surrounding YAML quotes; the regex itself never carries them.
+    raw="${raw%\'}"; raw="${raw#\'}"
+    raw="${raw%\"}"; raw="${raw#\"}"
+    printf '%s\n' "$raw"
+  done
+}
+
+# Asks vale — the thing that actually applies these globs — whether a config
+# covers a path, rather than reimplementing doublestar matching. The probe file
+# carries a description with a token Kyberforge.VagueWording flags, so a config
+# whose glob matches but whose BasedOnStyles lost Kyberforge fails too: it would
+# lint the file and report nothing.
+vale_flags_path() {
+  local cfg="$1" rel="$2" tmp out
+  tmp="$(mktemp -d)"
+  mkdir -p "$tmp/$(dirname "$rel")"
+  {
+    echo "---"
+    echo "name: probe"
+    echo "description: Use when the caller wants a probe that helps with things."
+    echo "---"
+    echo ""
+    echo "Body."
+  } > "$tmp/$rel"
+  out="$(cd "$tmp" && vale --config "$cfg" "$rel" 2>&1)" || true
+  rm -rf "$tmp"
+  printf '%s\n' "$out" | grep -qF "Kyberforge.VagueWording"
+}
+
+VALE_AVAILABLE=true
+if ! command -v vale >/dev/null 2>&1; then
+  VALE_AVAILABLE=false
+  echo "  WARNING: vale is not installed — .vale.ini glob coverage was NOT verified. Install it (https://vale.sh/docs/vale-cli/installation/) before trusting a clean run." >&2
+fi
+
+# One representative path per file shape the prefilter is supposed to cover. Each
+# is cross-checked against the shipped hooks' `files:` regexes first, so a path
+# that goes stale because a hook was rescoped fails loudly here instead of
+# quietly probing a shape nothing lints any more.
+while IFS='|' read -r skill rel; do
+  [[ -n "$skill" ]] || continue
+  dir="$REPO_ROOT/plugins/kyberforge/skills/$skill"
+  ini="$dir/assets/vale/.vale.ini"
+  [[ -f "$ini" ]] || continue
+
+  regexes="$(hook_file_regexes "$skill")"
+  if [[ -n "$regexes" ]]; then
+    in_scope=false
+    while IFS= read -r re; do
+      [[ -n "$re" ]] || continue
+      if printf '%s\n' "$rel" | grep -Eq "$re"; then
+        in_scope=true
+      fi
+    done <<EOF_RE
+$regexes
+EOF_RE
+    if [[ "$in_scope" == false ]]; then
+      err "$rel matches no 'files:' regex of any $skill hook — the probe path is stale, or the hook was rescoped away from a shape it still needs to lint"
+    fi
+  fi
+
+  if [[ "$VALE_AVAILABLE" == true ]] && ! vale_flags_path "$ini" "$rel"; then
+    err "$skill/assets/vale/.vale.ini raises no Kyberforge alert on $rel — its glob sections do not cover a path its own pre-commit hook is scoped to, so the hook passes that shape without linting it"
+  fi
+done <<'EOF_PROBE'
+skill-audit|plugins/demo/skills/demo/SKILL.md
+agent-audit|plugins/demo/agents/demo.md
+agent-audit|copilot/demo.agent.md
+EOF_PROBE
+
 if [[ $FAIL -gt 0 ]]; then
-  echo "Vale style sync check failed: $FAIL error(s). agent-audit's copy is canonical — run scripts/sync-vale-styles.sh to regenerate skill-audit's copy, then commit both." >&2
+  echo "Vale style sync check failed: $FAIL error(s). For a drifted wrapper or style, agent-audit's copy is canonical — run scripts/sync-vale-styles.sh to regenerate skill-audit's copy, then commit both. A .vale.ini finding is not drift and sync-vale-styles.sh will not fix it: edit that file's own StylesPath, BasedOnStyles or glob sections." >&2
   exit 1
 fi
diff --git a/tests/test-check-vale-style-sync.sh b/tests/test-check-vale-style-sync.sh
index a0d82b1..c4f88bb 100755
--- a/tests/test-check-vale-style-sync.sh
+++ b/tests/test-check-vale-style-sync.sh
@@ -9,41 +9,72 @@ FAIL=0
 pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
 fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
 
+# One trap over a registry, rather than rebuilding the trap line per fixture:
+# the guard is there because bash 3.2 treats "${arr[@]}" on an empty array as
+# unbound under `set -u`.
+FIXTURES=()
+cleanup() { [[ ${#FIXTURES[@]} -eq 0 ]] || rm -rf "${FIXTURES[@]}"; }
+trap cleanup EXIT
+
 # Helper: make a fixture repo with skill-audit/agent-audit's Vale copies, in sync by default.
+# The wrapper is a stub — the script only diffs it — but the Vale assets and both
+# pre-commit manifests are the repo's real ones, because the .vale.ini checks ask
+# vale to apply those globs for real and cross-check them against the shipped
+# hooks' `files:` regexes. A synthetic style or manifest would prove nothing, and
+# copying the real ones keeps agent-audit's intentional KyberforgeCopilot
+# divergence in the fixture instead of a sanitized stand-in for it.
 make_fixture() {
   local dir
   dir="$(mktemp -d)"
   local skill_audit="$dir/plugins/kyberforge/skills/skill-audit"
   local agent_audit="$dir/plugins/kyberforge/skills/agent-audit"
-  mkdir -p "$skill_audit/scripts" "$skill_audit/assets/vale/styles/Kyberforge"
-  mkdir -p "$agent_audit/scripts" "$agent_audit/assets/vale/styles/Kyberforge"
+  mkdir -p "$skill_audit/scripts" "$agent_audit/scripts"
 
   echo '#!/usr/bin/env bash' > "$skill_audit/scripts/vale-wrap.sh"
   echo 'echo wrap' >> "$skill_audit/scripts/vale-wrap.sh"
   cp "$skill_audit/scripts/vale-wrap.sh" "$agent_audit/scripts/vale-wrap.sh"
 
-  echo 'extends: existence' > "$skill_audit/assets/vale/styles/Kyberforge/Rule.yml"
-  cp "$skill_audit/assets/vale/styles/Kyberforge/Rule.yml" "$agent_audit/assets/vale/styles/Kyberforge/Rule.yml"
+  cp -R "$REPO_ROOT/plugins/kyberforge/skills/skill-audit/assets" "$skill_audit/"
+  cp -R "$REPO_ROOT/plugins/kyberforge/skills/agent-audit/assets" "$agent_audit/"
+  cp "$REPO_ROOT/.pre-commit-hooks.yaml" "$REPO_ROOT/.pre-commit-config.yaml" "$dir/"
 
   echo "$dir"
 }
 
+# Helper: rewrite a glob section header in one copy's .vale.ini, leaving every
+# other line — StylesPath, BasedOnStyles — intact. This is the shape of the
+# typo the check exists to catch: the hook still matches the file via its
+# `files:` regex, vale lints nothing, and pre-commit reports `Passed`.
+break_glob() {
+  local ini="$1" old="$2" new="$3"
+  python3 - "$ini" "$old" "$new" <<'PYTHON'
+import sys
+path, old, new = sys.argv[1], sys.argv[2], sys.argv[3]
+with open(path, encoding='utf-8') as fh:
+    content = fh.read()
+assert old in content, f"{old} not found in {path}"
+with open(path, 'w', encoding='utf-8') as fh:
+    fh.write(content.replace(old, new))
+PYTHON
+}
+
 # --- 1. Exits 0 when the two copies are in sync ---
 echo ""
 echo "--- exits 0 when skill-audit and agent-audit copies are in sync ---"
 FIXTURE="$(make_fixture)"
-trap 'rm -rf "$FIXTURE"' EXIT
+FIXTURES+=("$FIXTURE")
 if bash "$SCRIPT" "$FIXTURE" > /dev/null 2>&1; then
   pass "exits 0 when copies are in sync"
 else
   fail "exited non-zero against in-sync copies"
+  bash "$SCRIPT" "$FIXTURE" 2>&1 | sed 's/^/    /' || true
 fi
 
 # --- 2. Exits 1 when vale-wrap.sh differs between the two copies ---
 echo ""
 echo "--- exits 1 when vale-wrap.sh differs ---"
 FIXTURE2="$(make_fixture)"
-trap 'rm -rf "$FIXTURE" "$FIXTURE2"' EXIT
+FIXTURES+=("$FIXTURE2")
 echo 'echo different' >> "$FIXTURE2/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh"
 if bash "$SCRIPT" "$FIXTURE2" > /dev/null 2>&1; then
   fail "exited 0 when vale-wrap.sh copies differ — expected exit 1"
@@ -55,8 +86,8 @@ fi
 echo ""
 echo "--- exits 1 when a Kyberforge style rule differs ---"
 FIXTURE3="$(make_fixture)"
-trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3"' EXIT
-echo 'level: error' >> "$FIXTURE3/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/Rule.yml"
+FIXTURES+=("$FIXTURE3")
+echo '  - divergent token' >> "$FIXTURE3/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml"
 if bash "$SCRIPT" "$FIXTURE3" > /dev/null 2>&1; then
   fail "exited 0 when a style rule differs — expected exit 1"
 else
@@ -67,8 +98,14 @@ fi
 echo ""
 echo "--- exits 1 when a rule file is missing from one copy ---"
 FIXTURE4="$(make_fixture)"
-trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4"' EXIT
-echo 'extends: existence' > "$FIXTURE4/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/Extra.yml"
+FIXTURES+=("$FIXTURE4")
+cat > "$FIXTURE4/plugins/kyberforge/skills/agent-audit/assets/vale/styles/Kyberforge/Extra.yml" <<'EOF'
+extends: existence
+message: "Extra: '%s'"
+level: error
+tokens:
+  - divergent token
+EOF
 if bash "$SCRIPT" "$FIXTURE4" > /dev/null 2>&1; then
   fail "exited 0 when a rule file exists in only one copy — expected exit 1"
 else
@@ -79,7 +116,7 @@ fi
 echo ""
 echo "--- exits 0 when kyberforge skills are absent (no-op) ---"
 FIXTURE5="$(mktemp -d)"
-trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5"' EXIT
+FIXTURES+=("$FIXTURE5")
 if bash "$SCRIPT" "$FIXTURE5" > /dev/null 2>&1; then
   pass "exits 0 as a no-op when skill-audit/agent-audit don't exist"
 else
@@ -93,7 +130,7 @@ echo ""
 echo "--- exits 1 when only one of the two copies is present ---"
 FIXTURE6="$(make_fixture)"
 FIXTURE7="$(make_fixture)"
-trap 'rm -rf "$FIXTURE" "$FIXTURE2" "$FIXTURE3" "$FIXTURE4" "$FIXTURE5" "$FIXTURE6" "$FIXTURE7"' EXIT
+FIXTURES+=("$FIXTURE6" "$FIXTURE7")
 rm -rf "$FIXTURE6/plugins/kyberforge/skills/skill-audit"
 rm -rf "$FIXTURE7/plugins/kyberforge/skills/agent-audit"
 if bash "$SCRIPT" "$FIXTURE6" > /dev/null 2>&1; then
@@ -107,6 +144,172 @@ else
   pass "exits non-zero when agent-audit's canonical copy is missing but skill-audit's is present"
 fi
 
+# --- 7. Exits 1 when a .vale.ini is missing entirely ---
+# Without it vale falls back to an upward config search and lints the file with
+# whatever config it happens to find, which is not a failure anyone sees.
+echo ""
+echo "--- exits 1 when a .vale.ini is missing ---"
+FIXTURE8="$(make_fixture)"
+FIXTURES+=("$FIXTURE8")
+rm -f "$FIXTURE8/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini"
+if bash "$SCRIPT" "$FIXTURE8" > /dev/null 2>&1; then
+  fail "exited 0 when skill-audit's .vale.ini is missing — expected exit 1"
+else
+  pass "exits non-zero when a .vale.ini is missing"
+fi
+
+# --- 8. Exits 1 when the shared StylesPath line is dropped from either copy ---
+# StylesPath resolves relative to the .vale.ini, which is the only reason the
+# bundled styles are found from a consuming repo's clone prefix.
+echo ""
+echo "--- exits 1 when StylesPath is missing from either .vale.ini ---"
+FIXTURE9="$(make_fixture)"
+FIXTURE10="$(make_fixture)"
+FIXTURES+=("$FIXTURE9" "$FIXTURE10")
+break_glob "$FIXTURE9/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini" \
+  'StylesPath = styles' 'StylesPath = elsewhere'
+break_glob "$FIXTURE10/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini" \
+  'StylesPath = styles' 'StylesPath = elsewhere'
+if bash "$SCRIPT" "$FIXTURE9" > /dev/null 2>&1; then
+  fail "exited 0 when skill-audit's .vale.ini lost StylesPath — expected exit 1"
+else
+  pass "exits non-zero when skill-audit's .vale.ini lost StylesPath"
+fi
+if bash "$SCRIPT" "$FIXTURE10" > /dev/null 2>&1; then
+  fail "exited 0 when agent-audit's .vale.ini lost StylesPath — expected exit 1"
+else
+  pass "exits non-zero when agent-audit's .vale.ini lost StylesPath"
+fi
+
+# --- 9. Exits 1 when no section's BasedOnStyles names Kyberforge ---
+# Every rule the prefilter gates on lives in that style, so a section that keeps
+# its glob but loses the style lints the file and reports nothing.
+echo ""
+echo "--- exits 1 when BasedOnStyles no longer names Kyberforge ---"
+FIXTURE11="$(make_fixture)"
+FIXTURES+=("$FIXTURE11")
+break_glob "$FIXTURE11/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini" \
+  'BasedOnStyles = Kyberforge' 'BasedOnStyles = KyberforgeCopilot'
+if bash "$SCRIPT" "$FIXTURE11" > /dev/null 2>&1; then
+  fail "exited 0 when agent-audit's .vale.ini stopped naming Kyberforge — expected exit 1"
+else
+  pass "exits non-zero when a .vale.ini no longer names the Kyberforge style"
+fi
+
+# --- 10. Exits 1 when a glob section stops matching the shape its hook lints ---
+# One case per glob section, because each covers a file shape the others don't:
+# agent-audit's [**/*.agent.md] is the only section covering a Copilot agent file
+# outside an agents/ directory, so breaking it alone is invisible to the others.
+echo ""
+echo "--- exits 1 when a .vale.ini glob no longer matches its hook's file shape ---"
+FIXTURE12="$(make_fixture)"
+FIXTURE13="$(make_fixture)"
+FIXTURE14="$(make_fixture)"
+FIXTURES+=("$FIXTURE12" "$FIXTURE13" "$FIXTURE14")
+break_glob "$FIXTURE12/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini" \
+  '[**/SKILL.md]' '[**/NOMATCH.md]'
+break_glob "$FIXTURE13/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini" \
+  '[**/agents/*.md]' '[**/NOMATCH-agents/*.md]'
+break_glob "$FIXTURE14/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini" \
+  '[**/*.agent.md]' '[**/*.NOMATCH.md]'
+if bash "$SCRIPT" "$FIXTURE12" > /dev/null 2>&1; then
+  fail "exited 0 when skill-audit's SKILL.md glob matched nothing — expected exit 1"
+else
+  pass "exits non-zero when skill-audit's SKILL.md glob matches nothing"
+fi
+if bash "$SCRIPT" "$FIXTURE13" > /dev/null 2>&1; then
+  fail "exited 0 when agent-audit's agents/*.md glob matched nothing — expected exit 1"
+else
+  pass "exits non-zero when agent-audit's agents/*.md glob matches nothing"
+fi
+if bash "$SCRIPT" "$FIXTURE14" > /dev/null 2>&1; then
+  fail "exited 0 when agent-audit's *.agent.md glob matched nothing — expected exit 1"
+else
+  pass "exits non-zero when agent-audit's *.agent.md glob matches nothing"
+fi
+
+# --- 11. Exits 1 when a probe path falls out of every hook's `files:` regex ---
+# The probe paths are hardcoded, so they can silently stop representing anything
+# the hooks lint. Rescoping the shipped agent hook away from the `.agent.md`
+# shape has to fail here rather than leave a probe testing a shape no hook
+# matches any more.
+echo ""
+echo "--- exits 1 when a probe path matches no hook's files: regex ---"
+FIXTURE16="$(make_fixture)"
+FIXTURES+=("$FIXTURE16")
+break_glob "$FIXTURE16/.pre-commit-hooks.yaml" \
+  "files: '(^|/)agents/[^/]+\\.md\$|\\.agent\\.md\$'" "files: '(^|/)agents/[^/]+\\.md\$'"
+if bash "$SCRIPT" "$FIXTURE16" > /dev/null 2>&1; then
+  fail "exited 0 when the agent hook was rescoped away from .agent.md — expected exit 1"
+else
+  pass "exits non-zero when a probe path is in no hook's scope any more"
+fi
+
+# --- 12. The text-level assertions hold on a machine without vale ---
+# They are the fallback when the glob probe cannot run. With vale on PATH the
+# probe fails on these same mutations, so it would mask them: only masking vale
+# proves a clean run here means the text assertions themselves ran.
+echo ""
+echo "--- the StylesPath / BasedOnStyles assertions still gate with vale masked off PATH ---"
+VALE_DIR="$(dirname "$(command -v vale 2>/dev/null || echo /nonexistent/vale)")"
+PATH_NO_VALE="$(printf '%s' "$PATH" | tr ':' '\n' | grep -vxF "$VALE_DIR" | paste -sd: -)"
+if (PATH="$PATH_NO_VALE"; command -v vale >/dev/null 2>&1); then
+  fail "could not mask vale off PATH — the vale-absent fallback was not exercised"
+else
+  FIXTURE17="$(make_fixture)"
+  FIXTURE18="$(make_fixture)"
+  FIXTURE19="$(make_fixture)"
+  FIXTURES+=("$FIXTURE17" "$FIXTURE18" "$FIXTURE19")
+  break_glob "$FIXTURE18/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini" \
+    'StylesPath = styles' 'StylesPath = elsewhere'
+  break_glob "$FIXTURE19/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini" \
+    'BasedOnStyles = Kyberforge' 'BasedOnStyles = KyberforgeCopilot'
+  if PATH="$PATH_NO_VALE" bash "$SCRIPT" "$FIXTURE17" > /dev/null 2>&1; then
+    pass "exits 0 on in-sync copies with vale unavailable"
+  else
+    fail "exited non-zero on in-sync copies with vale unavailable — the missing binary must warn, not fail"
+  fi
+  if PATH="$PATH_NO_VALE" bash "$SCRIPT" "$FIXTURE18" > /dev/null 2>&1; then
+    fail "exited 0 on a dropped StylesPath with vale unavailable — expected exit 1"
+  else
+    pass "exits non-zero on a dropped StylesPath with vale unavailable"
+  fi
+  if PATH="$PATH_NO_VALE" bash "$SCRIPT" "$FIXTURE19" > /dev/null 2>&1; then
+    fail "exited 0 on a BasedOnStyles that dropped Kyberforge with vale unavailable — expected exit 1"
+  else
+    pass "exits non-zero on a BasedOnStyles that dropped Kyberforge with vale unavailable"
+  fi
+  # A clean run without vale must say so — silence would read as verified.
+  if PATH="$PATH_NO_VALE" bash "$SCRIPT" "$FIXTURE17" 2>&1 | grep -q "vale is not installed"; then
+    pass "warns that glob coverage was not verified when vale is unavailable"
+  else
+    fail "exited clean without vale and said nothing — an unverified run looks identical to a verified one"
+  fi
+fi
+
+# --- 13. The intentional agent-audit-only divergence is NOT flagged ---
+# The two .vale.ini files are deliberately different: agent-audit ships an extra
+# [**/*.agent.md] section and the KyberforgeCopilot style. A check that diffed
+# them would fail the repo as it stands, so assert the divergence is really in
+# the fixture before asserting the check tolerates it — otherwise this case would
+# still pass if the fixture had quietly stopped carrying it.
+echo ""
+echo "--- exits 0 despite agent-audit's KyberforgeCopilot divergence ---"
+FIXTURE15="$(make_fixture)"
+FIXTURES+=("$FIXTURE15")
+AGENT_INI15="$FIXTURE15/plugins/kyberforge/skills/agent-audit/assets/vale/.vale.ini"
+SKILL_INI15="$FIXTURE15/plugins/kyberforge/skills/skill-audit/assets/vale/.vale.ini"
+if ! grep -q "KyberforgeCopilot" "$AGENT_INI15" \
+  || grep -q "KyberforgeCopilot" "$SKILL_INI15" \
+  || [[ ! -d "$FIXTURE15/plugins/kyberforge/skills/agent-audit/assets/vale/styles/KyberforgeCopilot" ]]; then
+  fail "the fixture no longer carries the agent-audit-only KyberforgeCopilot divergence, so tolerating it proves nothing"
+elif bash "$SCRIPT" "$FIXTURE15" > /dev/null 2>&1; then
+  pass "exits 0 with agent-audit's extra KyberforgeCopilot section and style present"
+else
+  fail "flagged the intentional agent-audit-only KyberforgeCopilot divergence — expected exit 0"
+  bash "$SCRIPT" "$FIXTURE15" 2>&1 | sed 's/^/    /' || true
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
diff --git a/tests/test-vale-hooks-consumer.sh b/tests/test-vale-hooks-consumer.sh
index c0eb6a7..b62d519 100755
--- a/tests/test-vale-hooks-consumer.sh
+++ b/tests/test-vale-hooks-consumer.sh
@@ -64,13 +64,18 @@ repos:
       - id: kyberforge-skill-size-check
 EOF
 
+# The two fixtures carry DIFFERENT flagged tokens so an alert can never be
+# credited to the hook that did not raise it. Both bodies land mid-sentence in a
+# folded block scalar that still spans two physical lines, which is the
+# flattening the wrapper exists to do.
 write_fixtures() {
-  local body="$1"
+  local skill_body="$1"
+  local agent_body="${2:-$1}"
   cat > "$CONSUMER/skills/demo/SKILL.md" <<EOF
 ---
 name: demo
 description: >
-  Use when the caller wants a demonstration skill $body across two
+  Use when the caller wants a demonstration skill $skill_body across two
   physical lines of one folded block scalar.
 ---
 
@@ -80,7 +85,7 @@ EOF
 ---
 name: demo
 description: >
-  Use when the caller wants a demonstration agent $body across two
+  Use when the caller wants a demonstration agent $agent_body across two
   physical lines of one folded block scalar.
 ---
 
@@ -89,27 +94,56 @@ EOF
   git -C "$CONSUMER" add -A
 }
 
-run_hooks() {
-  (cd "$CONSUMER" && pre-commit run --all-files 2>&1) || true
+# Vale prints each linted path as its own header line with that file's alerts
+# indented beneath it, so an alert belongs to the nearest preceding path line.
+# Reads a hook log on stdin and prints only the alert lines filed under `$1`.
+# The `sed` strips vale's ANSI colouring, which it emits into pre-commit's pipe
+# too, so the header lines compare as plain paths.
+alerts_for() {
+  sed $'s/\033\\[[0-9;]*m//g' | awk -v want="$1" '
+    /^[^[:space:]].*\.md$/ { cur = $0; next }
+    /^[[:space:]]*[0-9]+:[0-9]+[[:space:]]/ { if (cur == want) print }
+  '
 }
 
-# --- 1. Both hooks resolve their config and actually gate on a bad file ---
+# --- 1. Each Vale hook resolves its config and gates its own file shape ---
+# Asserted per hook, against that hook's own fixture path and its own token. An
+# aggregate alert count over both hooks' combined output does not prove this:
+# one fixture description carries every flagged token, so ONE working hook
+# already clears a `>= 2` threshold. And a hook whose .vale.ini globs match
+# nothing reaches neither of the guards below — it still MATCHES the file via
+# its `files:` regex, so pre-commit does not report `Skipped`; vale simply lints
+# nothing, prints `0 errors ... in 1 file` and exits 0, and the hook shows
+# `Passed`. Attribution is the only thing that catches it.
 echo ""
-echo "--- both Vale hooks run and fail a bad file in an external consumer repo ---"
-write_fixtures "that helps with and utilize things"
-OUT_BAD="$(run_hooks)"
-if echo "$OUT_BAD" | grep -q "does not exist"; then
-  fail "hooks hard-errored on a path resolved against the consumer repo (E100) — the bug this test guards against"
-  echo "$OUT_BAD" | sed 's/^/    /'
-elif echo "$OUT_BAD" | grep -q "Skipped"; then
-  fail "a hook matched no files, so it proved nothing"
-  echo "$OUT_BAD" | sed 's/^/    /'
-elif [[ "$(echo "$OUT_BAD" | grep -c "VagueWording")" -ge 2 ]]; then
-  pass "both hooks flatten and flag the folded description in a consumer repo"
-else
-  fail "hooks did not flag both fixtures"
-  echo "$OUT_BAD" | sed 's/^/    /'
-fi
+echo "--- each Vale hook flags its own fixture in an external consumer repo ---"
+write_fixtures "that helps with things" "that will utilize things"
+while IFS='|' read -r HOOK_ID FIXTURE TOKEN; do
+  [[ -n "$HOOK_ID" ]] || continue
+  LOG="$WORK/$HOOK_ID.log"
+  set +e
+  (cd "$CONSUMER" && pre-commit run "$HOOK_ID" --all-files > "$LOG" 2>&1)
+  RC_HOOK=$?
+  set -e
+  if grep -q "does not exist" "$LOG"; then
+    fail "$HOOK_ID hard-errored on a path resolved against the consumer repo (E100) — the bug this test guards against"
+    sed 's/^/    /' "$LOG"
+  elif grep -q "Skipped" "$LOG"; then
+    fail "$HOOK_ID matched no files, so it proved nothing"
+    sed 's/^/    /' "$LOG"
+  elif [[ $RC_HOOK -eq 0 ]]; then
+    fail "$HOOK_ID passed $FIXTURE despite its flagged '$TOKEN' — a .vale.ini glob matching nothing lints zero files and exits 0"
+    sed 's/^/    /' "$LOG"
+  elif alerts_for "$FIXTURE" < "$LOG" | grep -qF "'$TOKEN'"; then
+    pass "$HOOK_ID flattens $FIXTURE and flags its '$TOKEN' in a consumer repo"
+  else
+    fail "$HOOK_ID failed, but no alert quoting '$TOKEN' was filed under $FIXTURE"
+    sed 's/^/    /' "$LOG"
+  fi
+done <<'EOF'
+kyberforge-vale-audit-skill|skills/demo/SKILL.md|helps with
+kyberforge-vale-audit-agent|agents/demo.md|utilize
+EOF
 
 # --- 2. Clean files pass — the hooks gate, they don't just always fail ---
 echo ""
-- 
2.43.0


From ad1e5aaa9bf0e339982ea23f69bae935a28c47b9 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 17:23:24 +0000
Subject: [PATCH 32/45] fix(kyberforge): carry apostrophes verbatim through a
 |- literal block
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The flattener's last-resort branch rewrote ASCII ' to U+2019, justified as the
one combination no YAML scalar can carry verbatim. That claim was false: a |-
literal block with a single indented content line carries ', ", \ and ": "
verbatim and keeps text.frontmatter.description matching — as the wrapper's own
docstring already said of literal blocks. The rewrite fired on 12 of 54
in-scope files, silently disabling every rule whose token contains an
apostrophe. Case 20 pinned only that the scope stayed alive, so it passed
either way.

The emission site now splits the emitted scalar on its first newline so a
carried-over trailing comment stays on the "description: |-" header line rather
than becoming part of the value, and pads by span_lines - 1 - newlines. The pad
stays non-negative because the branch is only reachable when the original span
is at least two lines. Verified across all 73 in-scope files: no line-count
changes, and exactly the 12 expected files take the new branch.

One reported position moves: an alert on a description that is itself flagged
shifts from the key line to the block's content line, both inside the original
span. YAML cannot put a literal block's content on the key's own line, so this
is unavoidable; no line at or after the end of any description span moves.

Also: --output no longer absolutises the built-in style names line, JSON and
CLI, which a same-named file or directory in cwd turned into a template path
(exit 2, E100 Runtime error). And case 19's empty-baseline guard no longer
lets five dependent comparisons print vacuous passes — while fixing it the
guard turned out to be unreachable, since under pipefail an alert-free report
aborted the script at the assignment.

Refs: #85
ADR: 0014
---
 ...14-vale-prefilter-ships-from-the-plugin.md |  18 ++
 .../skills/agent-audit/scripts/vale-wrap.sh   |  75 ++++++---
 .../skills/skill-audit/scripts/vale-wrap.sh   |  75 ++++++---
 tests/test-vale-wrap.sh                       | 156 +++++++++++++-----
 4 files changed, 242 insertions(+), 82 deletions(-)

diff --git a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
index 7226dea..91a6e91 100644
--- a/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
+++ b/docs/adr/0014-vale-prefilter-ships-from-the-plugin.md
@@ -168,3 +168,21 @@ that makes the two disagree already touches `$HOOKS_MANIFEST`, itself a release-
 unreadable tagged tree (shallow clone, truncated fetch) fails closed rather than silently degrading
 to worktree-only derivation; a manifest simply absent at the tag — legitimate, it was added since —
 does not.
+
+**Update — the flattener rewrites no characters.** This ADR never recorded it as a decision, but
+`vale-wrap.sh`'s flattener carried a lossy last-resort branch: when a description needed quoting
+*and* held an ASCII apostrophe *and* held a double quote or backslash, it substituted U+2019 (`’`)
+for every `'` before writing the scratch copy, on the stated rationale that no verbatim YAML scalar
+could carry that combination. The rationale was wrong. A `|-` literal block with a single indented
+content line carries `'`, `"`, `\` and `: ` byte for byte — a block scalar's body has no escape
+syntax at all — and vale's `text.frontmatter.description` scope still matches and fires rules on it
+(verified against vale 3.15.2; it is the same property that makes the `|` blocks in the wrapper's
+header safe to leave unflattened). The branch fired on 12 of the 54 in-scope files in this repo,
+silently disabling every rule whose token contains an apostrophe on each of them. The flattener now
+emits that literal block instead, so its output is verbatim in all four forms and no Vale rule can
+be silently disabled by the prefilter. The `|-` form is two physical lines where the three inline
+forms are one, so the blank-line pad that preserves later line numbers drops by one — reachable
+only when the original span is already two or more lines, so the pad count stays non-negative.
+`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.
diff --git a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
index 66f3057..dae60b4 100755
--- a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
@@ -9,8 +9,10 @@ set -euo pipefail
 # the same way. A `|`/`|-`/`|+` literal block scalar is NOT affected: its parsed
 # value keeps exactly the line breaks the source has, and vale matches it fine
 # (verified against vale 3.15.2), so literal blocks are deliberately left alone.
-# This script flattens an affected description to one physical line in a scratch
-# copy (padding with blank lines so every other line number is unchanged), then
+# This script flattens an affected description to a one-line scalar in a scratch
+# copy — or, for the rare value no inline scalar can spell out verbatim, to a
+# `|-` literal block with a single content line, which vale matches just as well
+# (padding with blank lines so every other line number is unchanged), then
 # runs the real `vale` binary against the copies. Drop-in replacement for calling
 # `vale` directly: same args, same exit code, bar the two documented divergences
 # below.
@@ -61,6 +63,20 @@ vale_args=()
 path_args=()
 pending_flag=""
 config_given=false
+
+# `--output` takes either one of vale's built-in style names or a template file
+# path. Only the file form needs absolutizing, and the built-in names have to be
+# excluded by name *before* the existence test below: a file or directory
+# literally called `line` in the caller's cwd would otherwise rewrite the
+# built-in into `$cwd/line`, flipping vale into template mode (`E100 [template]
+# Runtime error`) where bare vale just uses the built-in. `--path` has no such
+# names — it is always a path — so the check is keyed on the flag too.
+is_builtin_output() {
+  case "$2" in
+    line|JSON|CLI) [[ "$1" == "--output" ]] ;;
+    *) false ;;
+  esac
+}
 for arg in "$@"; do
   if [[ -n "$pending_flag" ]]; then
     # Value of a separated two-argv flag. It is never a lint target, however
@@ -76,11 +92,12 @@ for arg in "$@"; do
         fi
         ;;
       --output|--path)
-        # `--output` is either a built-in style name (`line`, `JSON`) or a
-        # template file; only the file form needs resolving. `--path` is
-        # likewise a path. Anything that names nothing is passed through and
+        # See `is_builtin_output` above for why the built-in `--output` names
+        # are excluded first. Anything that names nothing is passed through and
         # left for vale to interpret.
-        if [[ "$arg" != /* && -e "$arg" ]]; then
+        if is_builtin_output "$pending_flag" "$arg"; then
+          vale_args+=("$arg")
+        elif [[ "$arg" != /* && -e "$arg" ]]; then
           vale_args+=("$cwd/$arg")
         else
           vale_args+=("$arg")
@@ -114,7 +131,9 @@ for arg in "$@"; do
     # other path-valued flags.
     --output=*|--path=*)
       flag_val="${arg#*=}"
-      if [[ "$flag_val" != /* && -n "$flag_val" && -e "$flag_val" ]]; then
+      if is_builtin_output "${arg%%=*}" "$flag_val"; then
+        vale_args+=("$arg")
+      elif [[ "$flag_val" != /* && -n "$flag_val" && -e "$flag_val" ]]; then
         vale_args+=("${arg%%=*}=$cwd/$flag_val")
       else
         vale_args+=("$arg")
@@ -286,13 +305,14 @@ def continuation_lines(rest):
 
 
 def emit(value):
-    """Render `value` as a one-line YAML scalar whose source text spells the
-    value out verbatim. Vale locates the description by matching the parsed
-    value back against the source, so a scalar carrying any escape — `''` in a
+    """Render `value` as a YAML scalar whose source text spells the value out
+    verbatim. Vale locates the description by matching the parsed value back
+    against the source, so a scalar carrying any escape — `''` in a
     single-quoted scalar, `\\"` or `\\\\` in a double-quoted one — makes the
     whole `text.frontmatter.description` scope vanish, the same failure this
     script exists to work around. Verbatim forms only, therefore, tried in
-    descending order of fidelity."""
+    descending order of fidelity. The first three occupy one physical line; the
+    `|-` fallback occupies two, which the caller accounts for when padding."""
     if (value
             and value[0] not in PLAIN_UNSAFE_FIRST
             and ': ' not in value
@@ -304,11 +324,14 @@ def emit(value):
     if '"' not in value and '\\' not in value:
         return '"' + value + '"'        # double-quoted: only `"`/`\` would
     # Last resort: the value needs quoting AND holds an apostrophe AND a double
-    # quote or backslash, so no verbatim YAML scalar can carry it. Substituting
-    # U+2019 for the apostrophe keeps the scope alive, at the cost of any style
-    # rule whose token contains a literal ASCII apostrophe. Scratch-copy only —
-    # never written back to the real file.
-    return "'" + value.replace("'", '’') + "'"
+    # quote or backslash, so no *inline* scalar can carry it verbatim. A `|-`
+    # literal block can — a block scalar's body has no escape syntax at all, so
+    # `'`, `"`, `\` and `: ` all survive byte for byte, and vale still matches
+    # the description scope against it (the header above says the same of the
+    # `|` blocks this script deliberately leaves alone; verified against vale
+    # 3.15.2). One content line, indented two spaces, `-`-chomped so the parsed
+    # value is exactly `value` with no trailing newline.
+    return '|-\n  ' + value
 
 
 fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
@@ -392,11 +415,21 @@ if header_m:
             newline = fm.find('\n', value_end)
             span_end = len(fm) if newline == -1 else newline + 1
             trailer = fm[value_end:span_end].rstrip('\n')
-        # One line replaces the span, so the blank-line pad is one short of the
-        # newline count it displaced — every later line number is unchanged.
-        pad = '\n' * (fm[head_start:span_end].count('\n') - 1)
-        new_fm = (fm[:head_start] + 'description: ' + emit(flat) + trailer
-                  + '\n' + pad + fm[span_end:])
+        scalar = emit(flat)
+        # A trailing comment carried across from the original line stays on the
+        # `description:` line itself: after a block scalar's `|-` header it is
+        # still a comment, but inside the block body it would become part of the
+        # value.
+        head, newline_sep, block_body = scalar.partition('\n')
+        # The replacement displaces the whole span, so the blank-line pad makes
+        # up the difference between the lines it displaced and the lines it
+        # occupies — every later line number is unchanged. That is one line for
+        # the three inline forms and two for the `|-` block; the span itself is
+        # at least two lines here (`value_lines >= 2` is a precondition), so the
+        # pad count never goes negative.
+        pad = '\n' * (fm[head_start:span_end].count('\n') - 1 - scalar.count('\n'))
+        new_fm = (fm[:head_start] + 'description: ' + head + trailer
+                  + newline_sep + block_body + '\n' + pad + fm[span_end:])
         content = (fm_match.group(1) + new_fm + fm_match.group(3)
                    + content[fm_match.end():])
 
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
index 66f3057..dae60b4 100755
--- a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
@@ -9,8 +9,10 @@ set -euo pipefail
 # the same way. A `|`/`|-`/`|+` literal block scalar is NOT affected: its parsed
 # value keeps exactly the line breaks the source has, and vale matches it fine
 # (verified against vale 3.15.2), so literal blocks are deliberately left alone.
-# This script flattens an affected description to one physical line in a scratch
-# copy (padding with blank lines so every other line number is unchanged), then
+# This script flattens an affected description to a one-line scalar in a scratch
+# copy — or, for the rare value no inline scalar can spell out verbatim, to a
+# `|-` literal block with a single content line, which vale matches just as well
+# (padding with blank lines so every other line number is unchanged), then
 # runs the real `vale` binary against the copies. Drop-in replacement for calling
 # `vale` directly: same args, same exit code, bar the two documented divergences
 # below.
@@ -61,6 +63,20 @@ vale_args=()
 path_args=()
 pending_flag=""
 config_given=false
+
+# `--output` takes either one of vale's built-in style names or a template file
+# path. Only the file form needs absolutizing, and the built-in names have to be
+# excluded by name *before* the existence test below: a file or directory
+# literally called `line` in the caller's cwd would otherwise rewrite the
+# built-in into `$cwd/line`, flipping vale into template mode (`E100 [template]
+# Runtime error`) where bare vale just uses the built-in. `--path` has no such
+# names — it is always a path — so the check is keyed on the flag too.
+is_builtin_output() {
+  case "$2" in
+    line|JSON|CLI) [[ "$1" == "--output" ]] ;;
+    *) false ;;
+  esac
+}
 for arg in "$@"; do
   if [[ -n "$pending_flag" ]]; then
     # Value of a separated two-argv flag. It is never a lint target, however
@@ -76,11 +92,12 @@ for arg in "$@"; do
         fi
         ;;
       --output|--path)
-        # `--output` is either a built-in style name (`line`, `JSON`) or a
-        # template file; only the file form needs resolving. `--path` is
-        # likewise a path. Anything that names nothing is passed through and
+        # See `is_builtin_output` above for why the built-in `--output` names
+        # are excluded first. Anything that names nothing is passed through and
         # left for vale to interpret.
-        if [[ "$arg" != /* && -e "$arg" ]]; then
+        if is_builtin_output "$pending_flag" "$arg"; then
+          vale_args+=("$arg")
+        elif [[ "$arg" != /* && -e "$arg" ]]; then
           vale_args+=("$cwd/$arg")
         else
           vale_args+=("$arg")
@@ -114,7 +131,9 @@ for arg in "$@"; do
     # other path-valued flags.
     --output=*|--path=*)
       flag_val="${arg#*=}"
-      if [[ "$flag_val" != /* && -n "$flag_val" && -e "$flag_val" ]]; then
+      if is_builtin_output "${arg%%=*}" "$flag_val"; then
+        vale_args+=("$arg")
+      elif [[ "$flag_val" != /* && -n "$flag_val" && -e "$flag_val" ]]; then
         vale_args+=("${arg%%=*}=$cwd/$flag_val")
       else
         vale_args+=("$arg")
@@ -286,13 +305,14 @@ def continuation_lines(rest):
 
 
 def emit(value):
-    """Render `value` as a one-line YAML scalar whose source text spells the
-    value out verbatim. Vale locates the description by matching the parsed
-    value back against the source, so a scalar carrying any escape — `''` in a
+    """Render `value` as a YAML scalar whose source text spells the value out
+    verbatim. Vale locates the description by matching the parsed value back
+    against the source, so a scalar carrying any escape — `''` in a
     single-quoted scalar, `\\"` or `\\\\` in a double-quoted one — makes the
     whole `text.frontmatter.description` scope vanish, the same failure this
     script exists to work around. Verbatim forms only, therefore, tried in
-    descending order of fidelity."""
+    descending order of fidelity. The first three occupy one physical line; the
+    `|-` fallback occupies two, which the caller accounts for when padding."""
     if (value
             and value[0] not in PLAIN_UNSAFE_FIRST
             and ': ' not in value
@@ -304,11 +324,14 @@ def emit(value):
     if '"' not in value and '\\' not in value:
         return '"' + value + '"'        # double-quoted: only `"`/`\` would
     # Last resort: the value needs quoting AND holds an apostrophe AND a double
-    # quote or backslash, so no verbatim YAML scalar can carry it. Substituting
-    # U+2019 for the apostrophe keeps the scope alive, at the cost of any style
-    # rule whose token contains a literal ASCII apostrophe. Scratch-copy only —
-    # never written back to the real file.
-    return "'" + value.replace("'", '’') + "'"
+    # quote or backslash, so no *inline* scalar can carry it verbatim. A `|-`
+    # literal block can — a block scalar's body has no escape syntax at all, so
+    # `'`, `"`, `\` and `: ` all survive byte for byte, and vale still matches
+    # the description scope against it (the header above says the same of the
+    # `|` blocks this script deliberately leaves alone; verified against vale
+    # 3.15.2). One content line, indented two spaces, `-`-chomped so the parsed
+    # value is exactly `value` with no trailing newline.
+    return '|-\n  ' + value
 
 
 fm_match = re.match(r'^(---\n)(.*?\n)(---\n)', content, re.DOTALL)
@@ -392,11 +415,21 @@ if header_m:
             newline = fm.find('\n', value_end)
             span_end = len(fm) if newline == -1 else newline + 1
             trailer = fm[value_end:span_end].rstrip('\n')
-        # One line replaces the span, so the blank-line pad is one short of the
-        # newline count it displaced — every later line number is unchanged.
-        pad = '\n' * (fm[head_start:span_end].count('\n') - 1)
-        new_fm = (fm[:head_start] + 'description: ' + emit(flat) + trailer
-                  + '\n' + pad + fm[span_end:])
+        scalar = emit(flat)
+        # A trailing comment carried across from the original line stays on the
+        # `description:` line itself: after a block scalar's `|-` header it is
+        # still a comment, but inside the block body it would become part of the
+        # value.
+        head, newline_sep, block_body = scalar.partition('\n')
+        # The replacement displaces the whole span, so the blank-line pad makes
+        # up the difference between the lines it displaced and the lines it
+        # occupies — every later line number is unchanged. That is one line for
+        # the three inline forms and two for the `|-` block; the span itself is
+        # at least two lines here (`value_lines >= 2` is a precondition), so the
+        # pad count never goes negative.
+        pad = '\n' * (fm[head_start:span_end].count('\n') - 1 - scalar.count('\n'))
+        new_fm = (fm[:head_start] + 'description: ' + head + trailer
+                  + newline_sep + block_body + '\n' + pad + fm[span_end:])
         content = (fm_match.group(1) + new_fm + fm_match.group(3)
                    + content[fm_match.end():])
 
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index fa1cc48..c823a38 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -443,8 +443,11 @@ fi
 # is declared and never reset to empty: it cannot be empty at any expansion
 # site, so the construct is not a hazard there and demanding the guarded form
 # would be a wrong test. The file list covers every script this repo ships or
-# runs that a macOS user reaches: the wrapper itself plus the two pre-commit
-# hook scripts.
+# runs that a macOS user reaches: the wrapper itself, the two pre-commit hook
+# scripts, and the test runner AGENTS.md tells contributors to run by hand.
+# `mapfile` is checked alongside, because it is bash 4.0+ and the expansion scan
+# cannot see it — run-tests.sh carried one until it was replaced with a
+# `while read` loop, and nothing would have caught its return.
 echo ""
 echo "--- no unguarded array expansion remains in the macOS-facing scripts ---"
 unguarded_expansions() {
@@ -470,11 +473,19 @@ HAZARDS16=""
 for BASH32_SCRIPT in \
   "$SCRIPT" \
   "$REPO_ROOT/scripts/skill-size-check.sh" \
-  "$REPO_ROOT/scripts/check-release-needed.sh"; do
+  "$REPO_ROOT/scripts/check-release-needed.sh" \
+  "$REPO_ROOT/tests/run-tests.sh"; do
   FOUND16="$(unguarded_expansions "$BASH32_SCRIPT")"
   if [[ -n "$FOUND16" ]]; then
     HAZARDS16+="$FOUND16 "
   fi
+  # `mapfile`/`readarray` are bash 4.0+ builtins with no 3.2 fallback. Whole-line
+  # comments are blanked first so prose naming the builtin is not a hit.
+  FOUND16B="$(awk '{ if ($0 ~ /^[[:space:]]*#/) print ""; else print }' "$BASH32_SCRIPT" \
+    | grep -nE '(^|[^[:alnum:]_])(mapfile|readarray)[[:space:]]' || true)"
+  if [[ -n "$FOUND16B" ]]; then
+    HAZARDS16+="${BASH32_SCRIPT##*/}:$FOUND16B "
+  fi
 done
 if [[ -n "$HAZARDS16" ]]; then
   fail "unguarded array expansion(s) abort on bash < 4.4 under set -u: $(echo "$HAZARDS16" | tr '\n' ' ')"
@@ -588,10 +599,15 @@ make_form_fixture() {
 }
 
 # Alert text with the `line:col` prefix and ANSI colouring stripped, sorted.
+# The `|| true` matters under this file's `set -o pipefail`: a report with no
+# alerts at all makes grep exit 1, which would abort the whole run inside the
+# command substitutions below — silently, before the empty-baseline guard could
+# print anything. Returning empty output instead is what makes that guard
+# reachable.
 alert_text() {
   echo "$1" \
     | sed -E 's/\x1b\[[0-9;]*m//g' \
-    | grep -oE '(error|warning|suggestion)[[:space:]]+.*' \
+    | { grep -oE '(error|warning|suggestion)[[:space:]]+.*' || true; } \
     | sed -E 's/[[:space:]]+/ /g' \
     | sort
 }
@@ -601,29 +617,35 @@ echo "--- every multi-line description form reports what its single-line form re
 FIXTURE19_SINGLE="$(make_form_fixture single)"
 BASELINE19="$(alert_text "$(run_wrap "$FIXTURE19_SINGLE" --config "$VALE_CONFIG" "$REL_SKILL19")")"
 if [[ -z "$BASELINE19" ]]; then
-  fail "the single-line baseline reported nothing — the comparison below would be vacuous"
+  # The loop below has to be skipped, not merely reported on: an empty baseline
+  # compares equal to five empty results, so it would print five vacuous PASSes
+  # alongside this one FAIL. The FAIL alone still fails the run at the end.
+  fail "the single-line baseline reported nothing — the comparisons below would be vacuous, so they are skipped"
+else
+  for FORM19 in folded plain dquote squote keyonly; do
+    DIR19="$(make_form_fixture "$FORM19")"
+    BARE19="$(cd "$DIR19" && vale --config "$VALE_CONFIG" "$REL_SKILL19" 2>&1 || true)"
+    GOT19="$(alert_text "$(run_wrap "$DIR19" --config "$VALE_CONFIG" "$REL_SKILL19")")"
+    if echo "$BARE19" | grep -q "VagueWording"; then
+      fail "bare vale already flags the $FORM19 form, so this case can't detect a silently-skipped flattening"
+    elif [[ "$GOT19" == "$BASELINE19" ]]; then
+      pass "a $FORM19 multi-line description reports the same alerts as its single-line form"
+    else
+      fail "a $FORM19 multi-line description diverged from its single-line form: got [$GOT19]"
+    fi
+  done
 fi
-for FORM19 in folded plain dquote squote keyonly; do
-  DIR19="$(make_form_fixture "$FORM19")"
-  BARE19="$(cd "$DIR19" && vale --config "$VALE_CONFIG" "$REL_SKILL19" 2>&1 || true)"
-  GOT19="$(alert_text "$(run_wrap "$DIR19" --config "$VALE_CONFIG" "$REL_SKILL19")")"
-  if echo "$BARE19" | grep -q "VagueWording"; then
-    fail "bare vale already flags the $FORM19 form, so this case can't detect a silently-skipped flattening"
-  elif [[ "$GOT19" == "$BASELINE19" ]]; then
-    pass "a $FORM19 multi-line description reports the same alerts as its single-line form"
-  else
-    fail "a $FORM19 multi-line description diverged from its single-line form: got [$GOT19]"
-  fi
-done
 
 # --- 20. A style token containing an ASCII apostrophe matches inside a
 # flattened description. The flattener used to substitute U+2019 for every `'`
 # before writing the scratch copy, so no rule whose token carried an apostrophe
 # could ever fire on a flattened description — a silent, rule-shaped blind spot.
-# Both branches that can hold an apostrophe verbatim are exercised: a value that
-# is safe unquoted, and one that must be quoted (it contains `: `) and so has to
-# land in a double-quoted scalar, since a single-quoted one would need the `''`
-# escape that kills the scope outright.
+# All three branches that can hold an apostrophe are exercised: a value that is
+# safe unquoted; one that must be quoted (it contains `: `) and so lands in a
+# double-quoted scalar, since a single-quoted one would need the `''` escape
+# that kills the scope outright; and one that also holds a double quote, which
+# no inline scalar can spell verbatim and which therefore lands in a `|-`
+# literal block.
 echo ""
 echo "--- a style token containing an apostrophe matches in a flattened description ---"
 APOS_STYLE="$(mktemp -d)"
@@ -638,6 +660,17 @@ ignorecase: true
 tokens:
   - "user's task"
 EOF
+# A body-scoped companion rule, used by case 20b to read back the line number of
+# a line *after* the frontmatter — the only way to catch the blank-line pad
+# being off in either direction.
+cat > "$APOS_STYLE/styles/Apostrophe/Body.yml" <<'EOF'
+extends: existence
+message: "body token: '%s'"
+level: error
+scope: text
+tokens:
+  - flattening marker phrase
+EOF
 cat > "$APOS_STYLE/.vale.ini" <<'EOF'
 StylesPath = styles
 
@@ -668,7 +701,23 @@ Body.
 EOF
 )"
 new_fixture "$FIXTURE20_QUOTED"
-for CASE20 in "unquoted:$FIXTURE20_PLAIN" "double-quoted:$FIXTURE20_QUOTED"; do
+# Needs quoting (`: `), holds an apostrophe AND a double quote — the one
+# combination no inline scalar can carry, so this is the `|-` literal-block
+# branch. The VagueWording tokens are there for case 20b, which reuses it.
+FIXTURE20_BLOCK="$(make_raw_fixture <<'EOF'
+---
+name: zzzskill
+description: >
+  Triggers on: the user's task and "audit this" phrasing, which helps
+  with and utilize things across a second physical line.
+---
+
+Body carrying a flattening marker phrase for the line-number check.
+EOF
+)"
+new_fixture "$FIXTURE20_BLOCK"
+for CASE20 in "unquoted:$FIXTURE20_PLAIN" "double-quoted:$FIXTURE20_QUOTED" \
+  "literal-block:$FIXTURE20_BLOCK"; do
   if run_wrap "${CASE20#*:}" --config "$APOS_STYLE/.vale.ini" "$REL_SKILL19" \
     | grep -q "Apostrophe.Token"; then
     pass "an apostrophe-bearing token matches in a flattened ${CASE20%%:*} description"
@@ -677,29 +726,31 @@ for CASE20 in "unquoted:$FIXTURE20_PLAIN" "double-quoted:$FIXTURE20_QUOTED"; do
   fi
 done
 
-# --- 20b. The one combination no verbatim YAML scalar can carry — needs
-# quoting, holds an apostrophe, and holds a double quote — falls back to the
-# lossy U+2019 substitution. Apostrophe-bearing tokens are lost there by
-# design, but the scope must stay alive so every other rule still fires.
+# --- 20b. The `|-` literal-block branch that case 20 just proved lossless must
+# also keep the rest of the scope working and keep the line accounting right.
+# The block is 2 physical lines where every inline form is 1, so the blank-line
+# pad that preserves later line numbers has to drop by one. The second
+# assertion pins that arithmetic against the body line's true number: case 3's
+# `<= original line count` bound would not, since a pad that is one line short
+# shifts every later line *up*, staying inside the bound while still lying.
 echo ""
-echo "--- the unrepresentable combination keeps the description scope alive ---"
-FIXTURE20C="$(make_raw_fixture <<'EOF'
----
-name: zzzskill
-description: >
-  Triggers on: the user's "audit this" phrasing, which helps with
-  and utilize things across a second physical line.
----
-
-Body.
-EOF
-)"
-new_fixture "$FIXTURE20C"
-if run_wrap "$FIXTURE20C" --config "$VALE_CONFIG" "$REL_SKILL19" | grep -q "VagueWording"; then
+echo "--- the |- literal-block fallback lints normally and preserves line numbers ---"
+OUT20B=$(run_wrap "$FIXTURE20_BLOCK" --config "$VALE_CONFIG" "$REL_SKILL19")
+if echo "$OUT20B" | grep -q "VagueWording"; then
   pass "a description needing quotes with both an apostrophe and a double quote is still linted"
 else
   fail "a description needing quotes with both an apostrophe and a double quote produced no alerts"
 fi
+WANT20B_LINE="$(grep -n 'flattening marker phrase' "$FIXTURE20_BLOCK/$REL_SKILL19" | cut -d: -f1)"
+# `--output line` prints `file:line:col:Rule:message`, so the line number reads
+# back without any wrapping or colour to strip.
+GOT20B_LINE="$(run_wrap "$FIXTURE20_BLOCK" --config "$APOS_STYLE/.vale.ini" --output line "$REL_SKILL19" \
+  | grep 'Apostrophe.Body' | head -1 | cut -d: -f2)"
+if [[ "$GOT20B_LINE" == "$WANT20B_LINE" ]]; then
+  pass "a body line after a |- flattened description keeps its original line number ($WANT20B_LINE)"
+else
+  fail "the |- block's blank-line pad shifted the body: vale reported line $GOT20B_LINE, the file has it at $WANT20B_LINE"
+fi
 
 # --- 21. A symlinked file inside a directory argument is mirrored and linted.
 # Vale follows symlinks (both a symlinked file and a file under a symlinked
@@ -766,6 +817,31 @@ else
   fail "a typo'd path exited $RC23 but the message does not name it: $OUT23"
 fi
 
+# --- 24. `--output`'s built-in style names must not be path-absolutized. The
+# wrapper rewrites path-valued flag values to absolute form so they still
+# resolve after the `cd` into the scratch mirror, deciding with an `-e`
+# existence test — but `line`, `JSON` and `CLI` are style names, not paths. With
+# a file or directory of that name sitting in the caller's cwd the test hit, the
+# built-in became `$cwd/line`, and vale flipped into template mode and died with
+# `E100 [template] Runtime error` where bare vale prints a normal report.
+echo ""
+echo "--- a built-in --output style name survives a same-named entry in the cwd ---"
+FIXTURE24="$(make_fixture 2)"
+new_fixture "$FIXTURE24"
+mkdir -p "$FIXTURE24/line"
+: > "$FIXTURE24/JSON"
+for FORM24 in "--output line" "--output=line" "--output JSON" "--output=JSON"; do
+  # shellcheck disable=SC2086 # deliberate word splitting of the argv fixture
+  OUT24="$(run_wrap "$FIXTURE24" --config "$VALE_CONFIG" $FORM24 "$REL_SKILL19")"
+  if echo "$OUT24" | grep -q "E100"; then
+    fail "'$FORM24' was rewritten to a cwd path and vale flipped into template mode — the bug this test guards against"
+  elif echo "$OUT24" | grep -q "VagueWording"; then
+    pass "'$FORM24' is passed through as a built-in style name"
+  else
+    fail "'$FORM24' produced no alert: $OUT24"
+  fi
+done
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From f6eb0d295e0ff7025ea168494be52b98fea10c4f Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 17:23:36 +0000
Subject: [PATCH 33/45] fix(lint): derive the release gate from the pushed ref,
 reject multi-token entries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The gate hardcoded HEAD as its diff tip, but pre-commit exports
PRE_COMMIT_TO_REF for exactly this. Pushing "somebranch:main" from another
checkout diffed the wrong tip — a false negative when HEAD is older, a false
positive when newer. Fixing only the diff tip leaves a second bug: git describe
took the tag baseline from HEAD too, so a tag reachable only from HEAD becomes
a baseline the pushed ref never saw. Both now resolve from the pushed ref, and
an all-zeros ref (branch deletion) short-circuits before any rev resolution
rather than surfacing as "could not diff".

PRE_COMMIT_FROM_REF is deliberately not used: it is the remote's current tip,
so diffing from it would let an untagged release-relevant commit already on
main excuse the next push from cutting a tag — the drift this gate exists to
catch. The baseline must stay the last release tag.

collect_release_paths took tokens[0] as a path unconditionally. ADR-0014 makes
bare single-path entries a binding constraint, but nothing enforced it, and the
sibling .pre-commit-config.yaml already ships "entry: bash <script>". Under
that shape add_release_path takes "bash", git diff accepts the non-matching
pathspec silently, bundle_root becomes "." and is skipped — the hook's whole
surface leaves the gate with no error, the same shape as the --config
regression in LESSONS.md. Multi-token entries now fail loudly naming the hook
and the ADR, and tokens[0] must resolve at HEAD or at the tag (the union is
load-bearing: a per-scope check would reject the deletion cases).

Six mutations verified, each restored. One correction worth recording: the
first multi-token test passed with its guard removed, because the existence
guard caught "bash" and printed a similar message. It now requires the verbatim
entry text that only the multi-token diagnostic emits.

Refs: #85
ADR: 0014
---
 scripts/check-release-needed.sh    | 129 +++++++++++++++++++++++---
 tests/test-check-release-needed.sh | 144 ++++++++++++++++++++++++++++-
 2 files changed, 258 insertions(+), 15 deletions(-)

diff --git a/scripts/check-release-needed.sh b/scripts/check-release-needed.sh
index 63b1d3f..61b8b27 100755
--- a/scripts/check-release-needed.sh
+++ b/scripts/check-release-needed.sh
@@ -21,6 +21,27 @@ if [[ "${PRE_COMMIT_REMOTE_BRANCH:-}" != "$TARGET_BRANCH" ]]; then
   exit 0
 fi
 
+# What is actually being pushed, which is only HEAD for the common
+# `git push <remote> <current-branch>` case. pre-commit's pre-push hook-impl
+# exports the local sha of each pushed ref as PRE_COMMIT_TO_REF; a
+# `git push <remote> topic:main` from a different checkout would otherwise be
+# gated on the wrong tip — a false negative when HEAD is behind the pushed ref
+# (unreleased changes sail through), a false positive when it is ahead.
+# PRE_COMMIT_FROM_REF, the *remote's* current tip, is deliberately not used
+# anywhere here: the baseline is the last release tag, not what the remote
+# already has. Diffing from the remote tip would let an untagged
+# release-relevant commit already on main excuse the next push from cutting a
+# tag, which is precisely the drift this gate exists to catch.
+PUSHED_REF="${PRE_COMMIT_TO_REF:-HEAD}"
+
+# pre-commit passes an all-zeros sha (40 hex zeros under sha1, 64 under sha256)
+# as the "to" ref when the push deletes a branch. Nothing is being shipped, and
+# every rev-taking command below would fail on an unresolvable sha, so bail out
+# rather than turning a branch deletion into a confusing "could not diff".
+if [[ "$PUSHED_REF" =~ ^0+$ ]]; then
+  exit 0
+fi
+
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 cd "$REPO_ROOT"
 
@@ -31,8 +52,10 @@ if [[ ! -f "$HOOKS_MANIFEST" ]]; then
 fi
 
 # Only vX.Y.Z release tags count as a baseline — an incidental checkpoint or
-# experiment tag reachable from HEAD must not shift the diff baseline.
-LAST_TAG="$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' 2>/dev/null || true)"
+# experiment tag reachable from the pushed ref must not shift the diff baseline.
+# The tag is resolved from $PUSHED_REF, not HEAD, for the same reason the diff
+# is: a tag reachable only from HEAD is not part of the history being pushed.
+LAST_TAG="$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' "$PUSHED_REF" 2>/dev/null || true)"
 
 if [[ -z "$LAST_TAG" ]]; then
   echo "FAIL: no release tag exists yet, but .pre-commit-hooks.yaml already exposes hooks to external consumers." >&2
@@ -68,16 +91,93 @@ add_release_path() {
   RELEASE_PATHS+=("$candidate")
 }
 
+# Emits one "<hook id><TAB><entry value>" line per hook so a rejected entry can
+# name the hook a human has to go fix. The id sits on its own line above its
+# entry: in YAML, so it is carried forward and then cleared; a hook that somehow
+# has no id still reports something printable rather than an empty name. Kept in
+# bash rather than awk: matching `[[:space:]]` inside a bracket expression is
+# reliable in bash's own globs but not in the BWK awk macOS ships. `read -r` with
+# a single variable is the trimmer — it strips leading and trailing whitespace
+# while preserving anything in between, so a multi-token entry survives intact
+# for the error message to quote back.
+manifest_entries() {
+  local line id="" value
+  while IFS= read -r line; do
+    # Drop the indentation and the optional list dash, so that `-   id: x` and
+    # `    entry: y` both reduce to the same bare "key: value" shape.
+    line="${line#"${line%%[![:space:]]*}"}"
+    if [[ "$line" == -* ]]; then
+      line="${line#-}"
+      line="${line#"${line%%[![:space:]]*}"}"
+    fi
+    case "$line" in
+      id:*)
+        read -r id <<< "${line#id:}"
+        ;;
+      entry:*)
+        read -r value <<< "${line#entry:}"
+        printf '%s\t%s\n' "${id:-(unnamed hook)}" "$value"
+        id=""
+        ;;
+    esac
+  done
+}
+
+# A hook's script is legitimate if it exists in the working tree *or* at
+# $LAST_TAG — the same union the pathspec itself spans. Checking per-scope
+# instead would reject exactly the case this gate exists to flag: a script
+# deleted since the tag while its entry survives (see the no -e filtering note
+# further down) is a real deletion to report, not a malformed manifest.
+entry_path_exists() {
+  local candidate="$1"
+  [[ -e "$candidate" ]] && return 0
+  git cat-file -e "$LAST_TAG:$candidate" 2>/dev/null && return 0
+  return 1
+}
+
 # $1 selects where the "does this hook bundle an assets/ tree?" guard looks:
 # "worktree" probes the filesystem, anything else is a rev whose tree is probed
 # with git plumbing. Reading entry lines from stdin keeps one derivation for
 # both the tagged manifest and the current one.
 collect_release_paths() {
-  local scope="$1" entry bundle_root
+  local scope="$1" line hook_id entry bundle_root where
   local -a tokens
-  while IFS= read -r entry; do
+  if [[ "$scope" == "worktree" ]]; then
+    where="the working tree's $HOOKS_MANIFEST"
+  else
+    where="$HOOKS_MANIFEST at $scope"
+  fi
+  while IFS= read -r line; do
+    hook_id="${line%%$'\t'*}"
+    entry="${line#*$'\t'}"
     read -ra tokens <<< "$entry"
     [[ ${#tokens[@]} -eq 0 ]] && continue
+    # ADR-0014 binds every entry to a bare script path and nothing else, because
+    # pre-commit rewrites only entry[0] into the hook-repo clone. That is a
+    # constraint nothing else enforces, and the sibling .pre-commit-config.yaml
+    # already ships the multi-token `bash <script>` shape one copy-paste away —
+    # so an entry like `bash scripts/foo.sh` would add "bash" as a pathspec that
+    # matches nothing and derive a bundle root of ".", dropping that hook's
+    # entire surface out of the gate silently. Both malformed shapes below fail
+    # loudly instead: silent degradation here is the same class of defect as the
+    # --config token already recorded in LESSONS.md.
+    if [[ ${#tokens[@]} -gt 1 ]]; then
+      echo "FAIL: hook '$hook_id' in $where has a multi-token entry: $entry" >&2
+      echo "  Why: pre-commit rewrites only entry[0] into the hook-repo clone, so every later" >&2
+      echo "       token resolves against the *consuming* repo and can never name a file this" >&2
+      echo "       repo ships — and this gate would derive its release paths from '${tokens[0]}'." >&2
+      echo "  Fix: make the entry a bare script path and have the script self-locate anything" >&2
+      echo "       else from \${BASH_SOURCE[0]} (see ADR-0014, 'Consequences')." >&2
+      exit 1
+    fi
+    if ! entry_path_exists "${tokens[0]}"; then
+      echo "FAIL: hook '$hook_id' in $where names a path that exists neither in the working tree nor at $LAST_TAG: ${tokens[0]}" >&2
+      echo "  Why: this gate derives its release-relevant pathspec from that path, so a name" >&2
+      echo "       that resolves to no file silently drops the hook's whole surface from the diff." >&2
+      echo "  Fix: point the entry at a script path this repo actually ships (see ADR-0014," >&2
+      echo "       'Consequences'); a bare command name is not a valid entry here." >&2
+      exit 1
+    fi
     add_release_path "${tokens[0]}"
     bundle_root="$(dirname "$(dirname "${tokens[0]}")")"
     [[ "$bundle_root" == "." ]] && continue
@@ -91,7 +191,7 @@ collect_release_paths() {
 }
 
 # The worktree alone is not enough: a path is release-relevant if it was part of
-# the contract at $LAST_TAG *or* is part of it at HEAD, so both trees have to be
+# the contract at $LAST_TAG *or* is part of it now, so both trees have to be
 # derived and unioned. Deriving only from the worktree meant that deleting a
 # hook's entire assets/ tree made the `-d` guard drop the path from the pathspec
 # altogether, and the deletion — which breaks every consumer at the next rev —
@@ -102,7 +202,7 @@ collect_release_paths() {
 # surface they cannot reach without a new tag. The union never over-fires on its
 # own, either — any manifest edit that makes the two disagree already changes
 # $HOOKS_MANIFEST, which is itself a release-relevant path.
-collect_release_paths worktree < <(sed -n 's/^[[:space:]]*entry:[[:space:]]*//p' "$HOOKS_MANIFEST")
+collect_release_paths worktree < <(manifest_entries < "$HOOKS_MANIFEST")
 
 # A missing manifest at the tag is legitimate (the manifest was added since) but
 # is indistinguishable from an unreadable tagged tree by its exit status alone,
@@ -110,20 +210,21 @@ collect_release_paths worktree < <(sed -n 's/^[[:space:]]*entry:[[:space:]]*//p'
 # shallow clone, a truncated fetch — fails closed exactly like a `git diff`
 # failure does, rather than silently degrading to worktree-only derivation.
 if MANIFEST_AT_TAG="$(git cat-file -p "$LAST_TAG:$HOOKS_MANIFEST" 2>/dev/null)"; then
-  collect_release_paths "$LAST_TAG" < <(printf '%s\n' "$MANIFEST_AT_TAG" | sed -n 's/^[[:space:]]*entry:[[:space:]]*//p')
+  collect_release_paths "$LAST_TAG" < <(printf '%s\n' "$MANIFEST_AT_TAG" | manifest_entries)
 elif ! git cat-file -e "$LAST_TAG^{tree}" 2>/dev/null; then
   echo "FAIL: could not read the tree at $LAST_TAG to determine which paths that release exposed." >&2
   echo "  Fix: ensure full tag history is available (e.g. git fetch --unshallow) and retry." >&2
   exit 1
 fi
 
-# No -e/existence filtering: a path deleted since $LAST_TAG is exactly the case
-# that must be caught (external consumers pinning the old tag would hit a
-# missing file), and `git diff` reports deletions fine without it existing at
-# HEAD. A git failure (e.g. a shallow clone missing $LAST_TAG's history) must
-# fail closed, not be swallowed into an empty, falsely-clean diff.
-if ! CHANGED="$(git diff --name-only "$LAST_TAG"..HEAD -- "${RELEASE_PATHS[@]}")"; then
-  echo "FAIL: could not diff $LAST_TAG..HEAD to check for release-relevant changes (see git error above)." >&2
+# No -e/existence filtering on the pathspec: a path deleted since $LAST_TAG is
+# exactly the case that must be caught (external consumers pinning the old tag
+# would hit a missing file), and `git diff` reports deletions fine without it
+# existing at the pushed ref. A git failure (e.g. a shallow clone missing
+# $LAST_TAG's history) must fail closed, not be swallowed into an empty,
+# falsely-clean diff.
+if ! CHANGED="$(git diff --name-only "$LAST_TAG".."$PUSHED_REF" -- "${RELEASE_PATHS[@]}")"; then
+  echo "FAIL: could not diff $LAST_TAG..$PUSHED_REF to check for release-relevant changes (see git error above)." >&2
   echo "  Fix: ensure full tag history is available (e.g. git fetch --unshallow) and retry." >&2
   exit 1
 fi
diff --git a/tests/test-check-release-needed.sh b/tests/test-check-release-needed.sh
index c1b1d2f..75d15e2 100755
--- a/tests/test-check-release-needed.sh
+++ b/tests/test-check-release-needed.sh
@@ -52,9 +52,37 @@ make_tagged_fixture() {
   echo "$dir"
 }
 
+# Helper: a fixture whose manifest carries one malformed entry: at the tag *and*
+# at HEAD, plus a post-tag change to the file that entry was meant to cover.
+# Committing the bad entry before the tag is what makes the assertion sharp — an
+# edited manifest is itself release-relevant, so the gate would fail for the
+# wrong reason and hide a parser that degrades silently.
+make_malformed_fixture() {
+  local entry="$1" dir
+  dir="$(mktemp -d)"
+  (cd "$dir" && git init -q && git config user.email t@t.t && git config user.name t)
+  write_release_paths "$dir"
+  cat > "$dir/.pre-commit-hooks.yaml" <<EOF
+-   id: fake-size-check
+    entry: $entry
+    language: script
+EOF
+  (cd "$dir" && git add -A && git commit -q -m "initial" && git tag v1.0.0)
+  echo "v2" > "$dir/scripts/skill-size-check.sh"
+  (cd "$dir" && git add -A && git commit -q -m "change the file the malformed entry should cover")
+  echo "$dir"
+}
+
+# $3 is optional: pre-commit's PRE_COMMIT_TO_REF, the local sha being pushed.
+# Left off entirely, the variable stays unset and the script falls back to HEAD,
+# exactly as a plain `git push <remote> <current-branch>` behaves.
 run_check() {
   local dir="$1" branch="$2"
-  (cd "$dir" && PRE_COMMIT_REMOTE_BRANCH="$branch" bash "$SCRIPT" 2>&1)
+  if [[ $# -ge 3 ]]; then
+    (cd "$dir" && PRE_COMMIT_REMOTE_BRANCH="$branch" PRE_COMMIT_TO_REF="$3" bash "$SCRIPT" 2>&1)
+  else
+    (cd "$dir" && PRE_COMMIT_REMOTE_BRANCH="$branch" bash "$SCRIPT" 2>&1)
+  fi
 }
 
 CLEANUP_DIRS=()
@@ -268,6 +296,120 @@ else
   fail "reported only the manifest change and hid which shipped paths the retirement removed"
 fi
 
+# --- 15. A multi-token entry: is rejected loudly, not silently mis-parsed ---
+# ADR-0014 binds entries to a bare script path, but nothing enforced it, and the
+# sibling .pre-commit-config.yaml already ships `entry: bash <script>`. Under the
+# old parser tokens[0] became "bash": a pathspec matching nothing (which git diff
+# accepts in silence) and a bundle root of "." (skipped), so the hook's whole
+# surface dropped out of the gate and the post-tag change below diffed clean.
+echo ""
+echo "--- exits 1 naming the hook when an entry: carries more than one token ---"
+# The entry is quoted back verbatim, not just its first token: that is what makes
+# the diagnostic point at the argument the author has to remove, and what
+# distinguishes this from the unresolvable-path rejection test 16 covers.
+FIXTURE15="$(make_malformed_fixture "bash scripts/skill-size-check.sh")"; track "$FIXTURE15"
+OUT15=$(run_check "$FIXTURE15" "refs/heads/main" || true)
+if run_check "$FIXTURE15" "refs/heads/main" > /dev/null; then
+  fail "silently exited 0 on a multi-token entry, dropping that hook's paths from the gate"
+elif echo "$OUT15" | grep -q "fake-size-check" \
+  && echo "$OUT15" | grep -q "bash scripts/skill-size-check.sh" \
+  && echo "$OUT15" | grep -q "ADR-0014"; then
+  pass "rejects a multi-token entry, quoting it back and naming the hook and ADR-0014"
+else
+  fail "rejected the multi-token entry without naming the hook, the entry, and ADR-0014"
+fi
+
+# --- 16. An entry naming no file this repo ships is rejected loudly ---
+# The token-count guard alone still lets a single bare command name (`entry:
+# vale`, valid for language: system) through as a pathspec matching nothing.
+# Existence is checked against the union of the worktree and $LAST_TAG, so this
+# cannot misfire on the deletion cases tests 12-14 pin.
+echo ""
+echo "--- exits 1 naming the hook when an entry: names no file in the worktree or at the tag ---"
+FIXTURE16="$(make_malformed_fixture "vale")"; track "$FIXTURE16"
+OUT16=$(run_check "$FIXTURE16" "refs/heads/main" || true)
+if run_check "$FIXTURE16" "refs/heads/main" > /dev/null; then
+  fail "silently exited 0 on an entry that names no shipped file"
+elif echo "$OUT16" | grep -q "fake-size-check" && echo "$OUT16" | grep -q "ADR-0014"; then
+  pass "rejects an entry that resolves to no file, naming the hook and the ADR-0014 constraint"
+else
+  fail "rejected the unresolvable entry without naming the hook and the ADR-0014 constraint"
+fi
+
+# --- 17. The pushed ref, not HEAD, is what gets gated ---
+# pre-commit exports the local sha of each pushed ref as PRE_COMMIT_TO_REF.
+# `git push <remote> pushed-tip:main` from a checkout sitting on an older commit
+# is the false-negative direction: HEAD is still at the tag and diffs clean while
+# the branch actually landing on main carries an untagged, release-relevant
+# change. HEAD is reset back to the tag so the two genuinely differ.
+echo ""
+echo "--- exits 1 on a release-relevant change reachable only from PRE_COMMIT_TO_REF ---"
+FIXTURE17="$(make_tagged_fixture)"; track "$FIXTURE17"
+echo "v2" > "$FIXTURE17/scripts/skill-size-check.sh"
+(cd "$FIXTURE17" && git add -A && git commit -q -m "release-relevant change" \
+  && git branch pushed-tip && git reset -q --hard v1.0.0)
+OUT17=$(run_check "$FIXTURE17" "refs/heads/main" "pushed-tip" || true)
+if echo "$OUT17" | grep -q "skill-size-check.sh"; then
+  pass "gates the pushed ref's tip, not HEAD, when HEAD is behind it"
+else
+  fail "diffed HEAD instead of PRE_COMMIT_TO_REF and missed a release-relevant change"
+fi
+
+# --- 18. Neither the diff tip nor the tag baseline may come from a newer HEAD ---
+# The false-positive direction: HEAD has moved past a v2.0.0 that the pushed ref
+# never saw. Reading either end of the diff off HEAD fails a push that is clean
+# since its own baseline — diffing v2.0.0..HEAD flags HEAD's untagged commit, and
+# resolving the tag from HEAD while diffing pushed-tip flags v2.0.0's change.
+echo ""
+echo "--- exits 0 when the pushed ref is clean since its own tag but HEAD has moved on ---"
+FIXTURE18="$(make_tagged_fixture)"; track "$FIXTURE18"
+(cd "$FIXTURE18" && git branch pushed-tip)
+echo "v2" > "$FIXTURE18/scripts/skill-size-check.sh"
+(cd "$FIXTURE18" && git add -A && git commit -q -m "released change" && git tag v2.0.0)
+echo "v3" > "$FIXTURE18/scripts/skill-size-check.sh"
+(cd "$FIXTURE18" && git add -A && git commit -q -m "unreleased change on HEAD's line")
+if run_check "$FIXTURE18" "refs/heads/main" "pushed-tip" > /dev/null; then
+  pass "exits 0 for a pushed ref clean since the tag reachable from it, ignoring HEAD's line"
+else
+  fail "gated HEAD's tag or tip and falsely demanded a release for a clean pushed ref"
+fi
+
+# --- 19. A branch deletion is a no-op, not a confusing git failure ---
+# pre-commit sets PRE_COMMIT_TO_REF to an all-zeros sha when the push deletes a
+# branch. Nothing is being shipped, and the sha resolves to nothing, so without
+# an explicit guard the gate reports "could not diff" on an unrelated operation.
+echo ""
+echo "--- exits 0 when PRE_COMMIT_TO_REF is the all-zeros branch-deletion sha ---"
+FIXTURE19="$(make_tagged_fixture)"; track "$FIXTURE19"
+echo "v2" > "$FIXTURE19/scripts/skill-size-check.sh"
+(cd "$FIXTURE19" && git add -A && git commit -q -m "release-relevant change")
+if run_check "$FIXTURE19" "refs/heads/main" "0000000000000000000000000000000000000000" > /dev/null; then
+  pass "treats an all-zeros PRE_COMMIT_TO_REF as a branch deletion and exits 0"
+else
+  fail "turned a branch deletion into a failure instead of a no-op"
+fi
+
+# --- 20. The repo's own .pre-commit-hooks.yaml satisfies the entry constraints ---
+# The parser guards above are only safe to ship if the manifest actually in tree
+# passes them. It is replayed into a fixture (with the paths its entries name
+# created) rather than run against the real repo, which has no release tag yet.
+echo ""
+echo "--- accepts the real .pre-commit-hooks.yaml this repo ships ---"
+FIXTURE20="$(mktemp -d)"; track "$FIXTURE20"
+(cd "$FIXTURE20" && git init -q && git config user.email t@t.t && git config user.name t)
+cp "$REPO_ROOT/.pre-commit-hooks.yaml" "$FIXTURE20/.pre-commit-hooks.yaml"
+while IFS= read -r real_entry; do
+  mkdir -p "$FIXTURE20/$(dirname "$real_entry")"
+  echo "v1" > "$FIXTURE20/$real_entry"
+done < <(sed -n 's/^[[:space:]]*entry:[[:space:]]*//p' "$REPO_ROOT/.pre-commit-hooks.yaml")
+(cd "$FIXTURE20" && git add -A && git commit -q -m "initial" && git tag v1.0.0)
+OUT20=$(run_check "$FIXTURE20" "refs/heads/main" || true)
+if [[ -z "$OUT20" ]]; then
+  pass "parses every entry in the repo's real .pre-commit-hooks.yaml without complaint"
+else
+  fail "the repo's own .pre-commit-hooks.yaml no longer satisfies the entry constraints: $OUT20"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 302f6d0c19fa35bd8d72b18545ef674de92d96f3 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 17:23:51 +0000
Subject: [PATCH 34/45] fix(lint): tighten the SKILL.md word ceiling to 2770
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MAX_WORDS=2900 was calibrated to the corpus median density and carried no
margin: at the densest observed 7.22 chars/word (~1.81 tokens/word) it permits
~5,240 tokens against the 5,000 it proxies for. 2770 holds the worst observed
density under the ceiling. The largest SKILL.md is 2,489 words, so the change
costs nothing today — 281 words of margin — and the header comment now argues
the new calibration rather than swapping the digits.

Both enforcement points move together, and a new test asserts they agree, since
a SKILL.md passing its own audit while the commit hook blocks it is the
disagreement this pair exists to prevent.

CONTEXT.md is deliberately left ungated: it is 2,816 words, and gating it would
block the build. Recorded here so the omission reads as a decision rather than
an oversight.

skill-audit's manual-fallback path listed only the line ceiling, so an agent
taking that path passed an oversized SKILL.md the hook then rejected. The word
ceiling is now named alongside it. agent-audit is deliberately unchanged: the
size hook scopes to SKILL.md only and agent-audit's validate.sh has no word
gate, so claiming it there would be false.

The Vale research doc still showed the MDX {/* vale off */} form under a
Markdown heading, contradicting CONTEXT.md and vale-run's troubleshooting
reference — that form suppresses nothing in plain .md. Fixed in both places it
appeared.

tests/run-tests.sh used mapfile (bash 4.0+) with unguarded array expansion,
though AGENTS.md tells contributors to run it and macOS ships bash 3.2. It now
collects via a while-read loop over process substitution and guards every
expansion. The newline-delimited find|sort pipeline is kept rather than -print0
with sort -z, whose BSD portability is the weaker link, and which matches
mapfile -t's previous behaviour exactly.

Refs: #85
ADR: 0013
---
 CONTEXT.md                                    |  2 +-
 ...013-vale-harness-scope-and-rule-sources.md |  9 +++---
 .../kyberforge/skills/skill-audit/SKILL.md    |  2 +-
 .../skills/skill-audit/scripts/validate.sh    |  6 +++-
 .../research/docs/vale/troubleshooting.md     | 19 ++++++++++--
 scripts/skill-size-check.sh                   | 18 +++++++-----
 tests/run-tests.sh                            | 18 +++++++++---
 tests/test-skill-size-check.sh                | 29 +++++++++++++++++--
 8 files changed, 80 insertions(+), 23 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index b386d21..b77c576 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -74,7 +74,7 @@ Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Descr
 
 Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions. Verified by reproduction, not assumed: `>` folded scalars, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars all yield 0 alerts and exit 0 on a deliberately-bad fixture, while a `|` literal block spanning the same 2+ lines lints normally (alerts fire, exit 1). The wrapper flattens those three broken forms to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; `|` literal blocks and single-line descriptions pass through untouched, already linting correctly. The plain and quoted forms previously passed silently — unflattened and unmatched — so a bad description in either sailed through the prefilter. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root. Both audit skills' Step 1 now passes no `--config` either: it resolves the script relative to the skill's own directory so the call works from an installed plugin cache, but a relative `--config` alongside it would still resolve against the cwd, yielding `E100 Runtime error ... does not exist` and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to full LLM judgment. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/agents/[^/]+\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
 
-This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's `SKILL.md` ceiling as two blocking gates: `MAX_LINES=500` and `MAX_WORDS=2900` (a word-count proxy for the 5,000-token limit, calibrated from this repo's measured ~1.6-1.7 tokens per word). Both are inclusive, and `skill-audit/scripts/validate.sh` checks the same pair on the same terms, so a `SKILL.md` can no longer pass its own audit yet be blocked by the commit hook. Scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
+This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the 41 skill/agent files, one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforcing agentskills.io's `SKILL.md` ceiling as two blocking gates: `MAX_LINES=500` and `MAX_WORDS=2770` (a word-count proxy for the 5,000-token limit, calibrated to the densest prose measured in this repo — 1.81 tokens per word — so even a worst-case `SKILL.md` at the ceiling stays under 5,000 tokens). Both are inclusive, and `skill-audit/scripts/validate.sh` checks the same pair on the same terms, so a `SKILL.md` can no longer pass its own audit yet be blocked by the commit hook. Scoped to `^plugins/[^/]+/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
 
 ### LESSONS.md
 Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
diff --git a/docs/adr/0013-vale-harness-scope-and-rule-sources.md b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
index 1774b89..2dfb67d 100644
--- a/docs/adr/0013-vale-harness-scope-and-rule-sources.md
+++ b/docs/adr/0013-vale-harness-scope-and-rule-sources.md
@@ -96,10 +96,11 @@ every rule to `level: error` is what actually implements this decision.
   "cherry-picked rules" is one rule, not two.
 - A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
   500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. Both halves of that
-  ceiling are blocking gates, not just the line count: `MAX_LINES=500`, and `MAX_WORDS=2900` as a
-  word-count proxy for the 5,000-token limit (calibrated from this repo's measured ~1.6-1.7 tokens
-  per word — `wc -w` is not BPE tokenization). Either one exceeded fails the hook. Both are
-  inclusive: a file at exactly 500 lines or exactly 2,900 words passes, and only one past a ceiling
+  ceiling are blocking gates, not just the line count: `MAX_LINES=500`, and `MAX_WORDS=2770` as a
+  word-count proxy for the 5,000-token limit (calibrated to the densest prose this repo measured,
+  1.81 tokens per word, so a worst-case `SKILL.md` at the ceiling still lands under 5,000 tokens —
+  `wc -w` is not BPE tokenization). Either one exceeded fails the hook. Both are
+  inclusive: a file at exactly 500 lines or exactly 2,770 words passes, and only one past a ceiling
   fails. `skill-audit/scripts/validate.sh` enforces the same pair on the same inclusive terms, so
   the audit and the commit hook cannot disagree about whether a given `SKILL.md` is over size.
 - `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index 6f71299..e09ba5d 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -37,7 +37,7 @@ bash scripts/validate-provenance.sh <skill-dir>
 scripts/vale-wrap.sh <skill-dir>/SKILL.md
 ```
 
-Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
+Note any structural FAILs — they will appear in the report as a `### Structure` dimension. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines and ≤2770 words (the word count is a proxy for the ~5,000-token ceiling, and blocks a commit exactly like the line count does), no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts.
 
 Note any Provenance FAILs and INFO findings from `validate-provenance.sh` — they surface in the report as a `### Provenance` dimension (separate from `### Structure`). The script embeds full FAIL/INFO format with Why and Fix per finding; surface them verbatim.
 
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/validate.sh b/plugins/kyberforge/skills/skill-audit/scripts/validate.sh
index e9ac95b..0c0473e 100755
--- a/plugins/kyberforge/skills/skill-audit/scripts/validate.sh
+++ b/plugins/kyberforge/skills/skill-audit/scripts/validate.sh
@@ -140,7 +140,11 @@ else:
 # no single source to share. Keep the two in sync by hand: if they drift, this
 # audit will report a skill ready to ship that the commit hook then rejects.
 MAX_LINES = 500
-MAX_WORDS = 2900  # word-count proxy for the ~5,000-token ceiling
+# Word-count proxy for the ~5,000-token ceiling, calibrated to the densest
+# prose in the corpus (7.22 chars/word): 2770 words is ~20,000 characters,
+# ~5,000 tokens at 4 characters per token. See skill-size-check.sh's header
+# for the full measurement.
+MAX_WORDS = 2770
 
 line_count = len(content.splitlines())
 if line_count <= MAX_LINES:
diff --git a/plugins/lint/docs/research/docs/vale/troubleshooting.md b/plugins/lint/docs/research/docs/vale/troubleshooting.md
index b5cd1ca..e75a817 100644
--- a/plugins/lint/docs/research/docs/vale/troubleshooting.md
+++ b/plugins/lint/docs/research/docs/vale/troubleshooting.md
@@ -8,7 +8,14 @@ source_keys:
 
 Vale supports inline markup comments to disable checks for a section of content. Syntax varies by format:
 
-Markdown/MDX:
+Markdown — HTML comments; the MDX `{/* */}` form suppresses nothing in a plain `.md` file:
+```markdown
+<!-- vale off -->
+This text will be ignored.
+<!-- vale on -->
+```
+
+MDX:
 ```mdx
 {/* vale off */}
 This text will be ignored.
@@ -24,7 +31,15 @@ This text will be ignored.
 
 ## Disabling a Specific Rule for Specific Matches
 
-Rather than disabling all checks, target one rule and specific known-exception strings, then re-enable:
+Rather than disabling all checks, target one rule and specific known-exception strings, then re-enable. Same per-format comment syntax as above — Markdown:
+
+```markdown
+<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->
+This is some text ACT test
+<!-- vale Style.Redundancy["ACT test","OTHER"] = YES -->
+```
+
+MDX:
 
 ```mdx
 {/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
diff --git a/scripts/skill-size-check.sh b/scripts/skill-size-check.sh
index 3f877b4..a1cf3bc 100755
--- a/scripts/skill-size-check.sh
+++ b/scripts/skill-size-check.sh
@@ -20,13 +20,15 @@ set -euo pipefail
 # ~4-characters-per-token English approximation that is 1.49 / 1.70 / 1.69 /
 # 1.81 tokens per word.
 #
-# MAX_WORDS=2900 is therefore calibrated to the corpus MEDIAN, not to its worst
-# case, and carries no margin: 2900 x 1.70 = ~4,900 tokens for a median-density
-# file, but 2900 x 1.81 = ~5,240 tokens for the densest file in the corpus. So
-# what this gate actually guarantees is "under 5,000 tokens for a file of
-# typical prose density"; a prose-dense SKILL.md can sit at exactly MAX_WORDS
-# and still be a few hundred tokens over the agentskills.io ceiling. Holding
-# the worst observed ratio under 5,000 tokens would need MAX_WORDS ~2770.
+# MAX_WORDS=2770 is therefore calibrated to the corpus WORST case rather than
+# its median: 2770 words at the densest observed 7.22 chars/word is ~20,000
+# characters, or ~5,000 tokens at the 4-characters-per-token approximation. So
+# what this gate guarantees is "under 5,000 tokens even for the densest prose
+# the corpus has produced" — the earlier median-calibrated MAX_WORDS=2900 let
+# such a file sit at exactly the ceiling and still spend ~5,240 tokens. A
+# median-density file at 2770 words spends ~4,700 tokens, so typical prose
+# gives up ~130 words of headroom to close that gap. The largest SKILL.md in
+# the repo is 2,489 words, so no current file is affected.
 #
 # It is a one-sided proxy in the useful direction — nothing under the word
 # ceiling is wildly over the token ceiling — but it is not exact BPE
@@ -34,7 +36,7 @@ set -euo pipefail
 # any of these numbers as still current.
 
 MAX_LINES=500
-MAX_WORDS=2900
+MAX_WORDS=2770
 FAIL=0
 
 for f in "$@"; do
diff --git a/tests/run-tests.sh b/tests/run-tests.sh
index 1f3c067..1e73765 100755
--- a/tests/run-tests.sh
+++ b/tests/run-tests.sh
@@ -35,14 +35,24 @@ fi
 
 run_bats
 
-mapfile -t SCRIPTS < <(
+# Collected with a `while read` loop rather than `mapfile` — macOS ships
+# /bin/bash 3.2, which has no `mapfile`. Process substitution (not a pipe)
+# keeps the loop in this shell so the appends survive. `sort` is still fed
+# newline-delimited output, exactly as before.
+SCRIPTS=()
+while IFS= read -r script; do
+  SCRIPTS+=("$script")
+done < <(
   find "$SEARCH_ROOT" -name "test-*.sh" \
     -not -path "*/.git/*" \
     -not -path "*/.claude/worktrees/*" \
     | sort
 )
 
-for script in "${SCRIPTS[@]}"; do
+# bash before 4.4 treats "${arr[@]}" on an empty array as unbound under
+# `set -u`, so every array expansion here uses the ${arr[@]+"${arr[@]}"} guard,
+# including the SKIPPED/FAILED loops already fenced by a count check.
+for script in ${SCRIPTS[@]+"${SCRIPTS[@]}"}; do
   rel="${script#"$SEARCH_ROOT/"}"
   echo "=== $rel ==="
   rc=0
@@ -60,13 +70,13 @@ done
 echo "=== Summary: $PASSED passed, ${#SKIPPED[@]} skipped, ${#FAILED[@]} failed ==="
 if [[ ${#SKIPPED[@]} -gt 0 ]]; then
   echo "Skipped scripts:"
-  for s in "${SKIPPED[@]}"; do
+  for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do
     echo "  $s"
   done
 fi
 if [[ ${#FAILED[@]} -gt 0 ]]; then
   echo "Failed scripts:"
-  for s in "${FAILED[@]}"; do
+  for s in ${FAILED[@]+"${FAILED[@]}"}; do
     echo "  $s"
   done
   exit 1
diff --git a/tests/test-skill-size-check.sh b/tests/test-skill-size-check.sh
index 32133db..b62aaf4 100755
--- a/tests/test-skill-size-check.sh
+++ b/tests/test-skill-size-check.sh
@@ -1,12 +1,14 @@
 #!/usr/bin/env bash
 # Regression test for scripts/skill-size-check.sh: enforces agentskills.io's
 # 500-line/5,000-token SKILL.md size ceiling. The token half is enforced via a
-# word-count proxy (MAX_WORDS, currently 2900) — 5,000 is the token ceiling,
-# 2,900 is the word budget the script derives from it.
+# word-count proxy (MAX_WORDS, currently 2770) — 5,000 is the token ceiling,
+# 2,770 is the word budget the script derives from it at the corpus's densest
+# measured prose.
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 SCRIPT="$REPO_ROOT/scripts/skill-size-check.sh"
+VALIDATE="$REPO_ROOT/plugins/kyberforge/skills/skill-audit/scripts/validate.sh"
 PASS=0
 FAIL=0
 
@@ -67,6 +69,29 @@ fi
 MAX_WORDS="$(grep -oE '^MAX_WORDS=[0-9]+' "$SCRIPT" | cut -d= -f2)"
 MAX_LINES="$(grep -oE '^MAX_LINES=[0-9]+' "$SCRIPT" | cut -d= -f2)"
 
+# The audit (skill-audit/scripts/validate.sh) duplicates both ceilings, because
+# a cache-installed plugin's scripts cannot read files outside the plugin
+# directory. Nothing but this assertion stops the copies drifting, and drift
+# means a SKILL.md passes its own audit and is then rejected by the commit hook.
+echo ""
+echo "--- the hook and skill-audit's validate.sh agree on both ceilings ---"
+if [[ ! -f "$VALIDATE" ]]; then
+  fail "skill-audit validate.sh not found at $VALIDATE"
+else
+  V_MAX_WORDS="$(grep -oE '^MAX_WORDS = [0-9]+' "$VALIDATE" | grep -oE '[0-9]+')"
+  V_MAX_LINES="$(grep -oE '^MAX_LINES = [0-9]+' "$VALIDATE" | grep -oE '[0-9]+')"
+  if [[ "$V_MAX_WORDS" == "$MAX_WORDS" ]]; then
+    pass "both enforce MAX_WORDS=$MAX_WORDS"
+  else
+    fail "MAX_WORDS drift: hook says $MAX_WORDS, validate.sh says ${V_MAX_WORDS:-<unset>}"
+  fi
+  if [[ "$V_MAX_LINES" == "$MAX_LINES" ]]; then
+    pass "both enforce MAX_LINES=$MAX_LINES"
+  else
+    fail "MAX_LINES drift: hook says $MAX_LINES, validate.sh says ${V_MAX_LINES:-<unset>}"
+  fi
+fi
+
 # make_line_fixture builds a file with an exact total line count (frontmatter
 # included), independent of word count, for the line-boundary tests.
 make_line_fixture() {
-- 
2.43.0


From 997f0df23ba18791799e62d82df43cfbd1250e18 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 17:24:08 +0000
Subject: [PATCH 35/45] chore(plugins): patch-bump kyberforge and lint for
 shipped changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

kyberforge 1.2.7 -> 1.2.8: both vale-wrap.sh copies, skill-audit's validate.sh
and its SKILL.md changed after the last bump. lint 1.1.4 -> 1.1.5: the Vale
research troubleshooting doc changed after its last bump.

Without the bump, installed copies keep serving the cached version. This is the
fourth time in this PR the bump was missed after shipped content changed —
check-manifests.sh validates parity between the two manifests but not that a
content change was accompanied by a bump, which is the gap that keeps letting
it through.

Refs: #85
---
 plugins/kyberforge/.claude-plugin/plugin.json | 2 +-
 plugins/kyberforge/plugin.json                | 2 +-
 plugins/lint/.claude-plugin/plugin.json       | 2 +-
 plugins/lint/plugin.json                      | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json
index 2c67fcb..98049c5 100644
--- a/plugins/kyberforge/.claude-plugin/plugin.json
+++ b/plugins/kyberforge/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.2.7"
+  "version": "1.2.8"
 }
diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json
index 7609ef2..1554ed0 100644
--- a/plugins/kyberforge/plugin.json
+++ b/plugins/kyberforge/plugin.json
@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.2.7"
+  "version": "1.2.8"
 }
diff --git a/plugins/lint/.claude-plugin/plugin.json b/plugins/lint/.claude-plugin/plugin.json
index 81b9cf1..76e11d9 100644
--- a/plugins/lint/.claude-plugin/plugin.json
+++ b/plugins/lint/.claude-plugin/plugin.json
@@ -13,5 +13,5 @@
   ],
   "license": "MIT",
   "name": "lint",
-  "version": "1.1.4"
+  "version": "1.1.5"
 }
diff --git a/plugins/lint/plugin.json b/plugins/lint/plugin.json
index f4c1a12..faf571e 100644
--- a/plugins/lint/plugin.json
+++ b/plugins/lint/plugin.json
@@ -18,5 +18,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.1.4"
+  "version": "1.1.5"
 }
-- 
2.43.0


From 7cf9a98509b18d8dda8ae1f498dd6b83a205cbe8 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 17:24:08 +0000
Subject: [PATCH 36/45] docs(lessons): record two patterns from PR #85's round
 6
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The aggregate-assertion failure joins the "a clean result can mean nothing ran"
family as its fifth instance: a total over N subjects is satisfiable by a
proper subset, so it proves nothing about any individual subject. Records the
reverse mutation sweep — neuter each assertion, confirm exactly one case fails
— as standing practice for checks whose failure mode is silence.

The second entry is about accepted residuals: the U+2019 rewrite survived
review because its justification was documented in the same breath as the
workaround, and the covering test asserted the residual's presence rather than
the behaviour it cost. Documentation records a belief; a belief adjacent to a
workaround is the one most worth attacking.

Refs: #85
---
 LESSONS.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/LESSONS.md b/LESSONS.md
index a95342c..835a386 100644
--- a/LESSONS.md
+++ b/LESSONS.md
@@ -142,6 +142,8 @@ During write-skill refactor, an "open thread" note (about a deferred research st
 
 Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **[graduated → core/instructions/testing.md]** (4th instance below, kept for audit trail).
 
+**5th instance (2026-08-09, PR #85 round 6):** `tests/test-vale-hooks-consumer.sh` asserted `grep -c "VagueWording" >= 2` across the *combined* output of both shipped Vale hooks, and the SKILL.md fixture alone raised two alerts — so one working hook satisfied the threshold and the agent hook could be disabled entirely (glob retargeted to match nothing) while the suite still reported `3 passed` under the message "both hooks flatten and flag". The `Skipped` guard did not catch it: the hook still *matched* the file, Vale simply linted nothing, reported `0 errors in 1 file`, and exited 0, which pre-commit renders as `Passed`. The general shape: **an assertion that aggregates over N subjects proves nothing about any individual subject** — a total is satisfiable by a proper subset. Fix: attribute each signal to its source before asserting (alerts are now filed by path, with a distinct trigger token per fixture so one hook's alert cannot be credited to another), and assert per subject. Corollary technique, now standing practice for any check whose failure mode is silence: run the mutation sweep in *reverse* as well — neuter each assertion in turn and confirm exactly one test case fails. Applied to `check-vale-style-sync.sh` it exposed two assertions bound to no failing case at all, one of them masked by a stronger check that ran first.
+
 **4th instance (2026-08-09, ADR-0014):** splitting the single root `.vale.ini` into two skill-scoped copies (skill-audit: `SKILL.md` only; agent-audit: agent files only) meant a single retargeted pre-commit hook pointed at agent-audit's copy alone would have silently scanned 0 `SKILL.md` files and exited 0 — caught only because the full corpus was dry-run against both the old and new config and the outputs diffed before the old config was deleted, not because any test asserted on file counts. Standing practice going forward: when a Vale (or any linter) config that serves multiple file-glob scopes is split or moved, dry-run the full corpus through both the old and new config and diff the outputs before removing the superseded source — a hook silently scanning 0 files looks identical to a clean pass.
 
 ## 2026-08-08 — One signal, two consumers, no named distinction
@@ -159,3 +161,7 @@ The root `.pre-commit-hooks.yaml` shipped Vale hooks whose `entry:` carried a `-
 ## 2026-08-09 — Deleting a token from a shared artifact breaks whatever parses it, silently
 
 Dropping the `--config` argument from `.pre-commit-hooks.yaml` was the right fix, but `scripts/check-release-needed.sh` derived its release-relevant path list by scanning those same `entry:` lines for `--config` and taking the target's `dirname` — that parse was the only thing giving the bundled `.vale.ini` and its sibling `styles/` tree release coverage. With the token gone the loop simply never fired: no error, no failing test, no warning, just a path list that shrank from six entries to four and lost both `assets/vale/` trees. Consequence: a change to a Vale *rule* could land on `main` without demanding a release tag, leaving external consumers pinned to an old `rev:` with stale rules — the exact drift the gate exists to prevent. It surfaced only because the agent making the change reported it as a suspected side effect of its own edit, and was confirmed by diffing the derived path list before and after. Fix: before removing a token from an artifact more than one script reads, grep for everything that *parses* the artifact, not just everything that consumes its documented purpose. The smell to watch for is a loop that builds a list, where an empty or short list is indistinguishable from a correct one — assert on the expected members, so a derivation whose input vanished fails loudly instead of quietly covering less.
+
+## 2026-08-09 — A documented impossibility is a claim, not a constraint
+
+`vale-wrap.sh` flattens multi-line YAML `description:` scalars so Vale's `text.frontmatter.description` scope keeps matching. Its last-resort branch rewrote ASCII `'` to U+2019, justified at the emission site and in review as "the single combination no YAML scalar can carry verbatim" — an accepted-by-design residual, documented and test-covered, which is exactly why nobody retested it. The claim was false: a `|-` literal block with one indented content line carries `'`, `"`, `\` and `: ` verbatim, keeps the scope alive, and the wrapper's own header docstring already said literal blocks were unaffected. The cost of the unexamined claim was a silent underlint on 12 of 54 in-scope files — any rule whose token contained an apostrophe simply never fired, and the covering test (case 20) pinned only "the scope stays alive", so it passed either way. Fix: when a residual is accepted because something is "impossible", write down the specific claim in a falsifiable form and test *that*, not the workaround built on top of it. The tell here was that the residual and its justification were documented in the same breath by the same author — documentation records a belief, and a belief adjacent to a workaround is the one most worth attacking. Related: an assertion written to cover an accepted residual tends to assert the residual's *presence* rather than the behaviour it costs; case 20b asserted the scope survived flattening, never that a rule matching the rewritten characters still fired.
-- 
2.43.0


From 9a3f72b6966be0c2a6293b66775e547cafa7009e Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 17:28:07 +0000
Subject: [PATCH 37/45] test(lint): stop the release-gate suite inheriting the
 caller's PRE_COMMIT refs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

run_check set PRE_COMMIT_REMOTE_BRANCH and, when asked, PRE_COMMIT_TO_REF, but
never cleared what was already in the environment. Standalone that is invisible
— nothing sets those vars. Under the pre-push hook this suite exists to guard,
pre-commit exports PRE_COMMIT_TO_REF and PRE_COMMIT_FROM_REF as shas of the
real repo; the fixtures inherited them, the script resolved a rev that does not
exist in the fixture, and 13 of 20 cases failed. The suite passed in every
context except the only one that matters.

The variables are now cleared in both branches, so a standalone run and a
pre-push run are the same test. Verified 20/20 with the vars unset and with
them set to real shas of this repo.

Found by the pre-push hook rejecting the push, not by any test — the same shape
as the --config regression: the local invocation exercised a different thing
than the shipped one, and the two were indistinguishable by reading the file.

Refs: #85
---
 tests/test-check-release-needed.sh | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/tests/test-check-release-needed.sh b/tests/test-check-release-needed.sh
index 75d15e2..440960b 100755
--- a/tests/test-check-release-needed.sh
+++ b/tests/test-check-release-needed.sh
@@ -76,12 +76,21 @@ EOF
 # $3 is optional: pre-commit's PRE_COMMIT_TO_REF, the local sha being pushed.
 # Left off entirely, the variable stays unset and the script falls back to HEAD,
 # exactly as a plain `git push <remote> <current-branch>` behaves.
+# The fixture repo is the subject under test, so every PRE_COMMIT_* input must
+# come from this function and nowhere else. Any such variable already in the
+# environment belongs to the *caller's* repo: run under the pre-push hook this
+# suite guards, PRE_COMMIT_TO_REF holds a sha of the real repo, which does not
+# exist in the fixture, and the script resolves against the wrong rev. Clearing
+# them is what makes a standalone run and a pre-push run the same test — this
+# suite passed everywhere except under the hook it exists to protect.
 run_check() {
   local dir="$1" branch="$2"
   if [[ $# -ge 3 ]]; then
-    (cd "$dir" && PRE_COMMIT_REMOTE_BRANCH="$branch" PRE_COMMIT_TO_REF="$3" bash "$SCRIPT" 2>&1)
+    (cd "$dir" && unset PRE_COMMIT_FROM_REF \
+      && PRE_COMMIT_REMOTE_BRANCH="$branch" PRE_COMMIT_TO_REF="$3" bash "$SCRIPT" 2>&1)
   else
-    (cd "$dir" && PRE_COMMIT_REMOTE_BRANCH="$branch" bash "$SCRIPT" 2>&1)
+    (cd "$dir" && unset PRE_COMMIT_FROM_REF PRE_COMMIT_TO_REF \
+      && PRE_COMMIT_REMOTE_BRANCH="$branch" bash "$SCRIPT" 2>&1)
   fi
 }
 
-- 
2.43.0


From 0a41b2c7d39b45a2897d67eb7cbca8d19e10e883 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 19:55:19 +0000
Subject: [PATCH 38/45] fix(kyberforge): restore skill-audit's action-verb
 opening check

skill-audit's Description dimension implied Vale's DescriptionOpener
alert fully covers imperative-phrasing checks, but that rule only
matches the literal "This skill..." pattern. agent-audit kept its
equivalent manual "does the description open with a verb" fallback
bullet; skill-audit's got dropped when Vale wiring landed in #85,
leaving other non-imperative openers (gerunds, passive phrasing) to
sail through unflagged. Restore the parallel check.
---
 plugins/kyberforge/skills/skill-audit/SKILL.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md
index e09ba5d..474c784 100644
--- a/plugins/kyberforge/skills/skill-audit/SKILL.md
+++ b/plugins/kyberforge/skills/skill-audit/SKILL.md
@@ -55,6 +55,7 @@ Work through each dimension internally. Collect findings only; report them in St
 
 Vale's `Kyberforge.DescriptionOpener` ("This skill..." openers) and `Kyberforge.VagueWording` (filler like "helps with", "utilize") alerts from Step 1 — both FAILs — cover imperative phrasing and known vague-wording filler directly; report them as findings without re-deriving by judgment. The rest is still a judgment call:
 
+- **Action-verb opening**: does the description start with a verb ("Audits...", "Reviews...", "Validates...")? Vale's `Kyberforge.DescriptionOpener` alert only catches the literal "This skill..." pattern — confirming an arbitrary opening word is genuinely a strong verb still requires judgment.
 - **Specificity beyond the filler blocklist**: are capabilities stated precisely ("parses OpenAPI specs") or genuinely vaguely ("handles files")?
 - **Indirect triggers**: does it cover cases where the user doesn't name the domain directly?
 - **Near-miss exclusions**: are "Do not use when..." clauses present if a near-miss skill could steal activations?
-- 
2.43.0


From 050aec4c80ae8d664715c87707fccc9f9214649d Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 19:55:27 +0000
Subject: [PATCH 39/45] docs(kyberforge): document Vale-wiring files in
 skill-audit/agent-audit READMEs

Both READMEs' file tables predate #85's Vale wiring and never picked
up scripts/vale-wrap.sh or the assets/vale/ style tree, so a reader
of either README had no way to find where the new Step 1 sub-check
actually lives. List the new files and note the Vale sub-check in
"What it does" for both skills.
---
 plugins/kyberforge/skills/agent-audit/README.md | 9 ++++++++-
 plugins/kyberforge/skills/skill-audit/README.md | 8 +++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/plugins/kyberforge/skills/agent-audit/README.md b/plugins/kyberforge/skills/agent-audit/README.md
index 9476dec..2053c91 100644
--- a/plugins/kyberforge/skills/agent-audit/README.md
+++ b/plugins/kyberforge/skills/agent-audit/README.md
@@ -4,7 +4,7 @@ Audits a Claude Code and Copilot agent definition file pair for correctness and
 
 ## What it does
 
-Accepts either file in a CC `.md` / Copilot `.agent.md` pair, derives the counterpart automatically, and validates both. Runs structural checks via `validate.sh` (required fields, kebab-case name, no placeholders, no CC-only fields in the Copilot file, silently-ignored fields at plugin scope), provenance chain validation via `validate-provenance.sh` (checks `source_keys` against `sources.md` at the plugin root), then qualitative checks on description phrasing and system prompt quality. Produces a compact findings report in the same format as `skill-audit`.
+Accepts either file in a CC `.md` / Copilot `.agent.md` pair, derives the counterpart automatically, and validates both. Runs structural checks via `validate.sh` (required fields, kebab-case name, no placeholders, no CC-only fields in the Copilot file, silently-ignored fields at plugin scope), provenance chain validation via `validate-provenance.sh` (checks `source_keys` against `sources.md` at the plugin root), then qualitative checks on description phrasing and system prompt quality. Step 1 also runs a Vale-based prose sub-check via `vale-wrap.sh` against both files of the pair, using the `Kyberforge` style (both files) and `KyberforgeCopilot` style (Copilot file only) — every alert is a `FAIL`, cited by rule ID — falling back to Step 2 judgment when the `vale` binary is unavailable or reports `0 files` scanned. Produces a compact findings report in the same format as `skill-audit`.
 
 ## Usage
 
@@ -19,6 +19,12 @@ Pass the path to either agent file as the argument.
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` |
+| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This skill/agent" instead of an imperative "Use when..." |
+| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references |
+| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly |
+| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions |
+| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions |
 | `references/README.md` | Directory documentation for references/ |
 | `references/description-quality.md` | Qualitative guide for borderline description findings |
 | `references/field-inventory.md` | Authoritative list of valid CC and Copilot agent fields |
@@ -26,6 +32,7 @@ Pass the path to either agent file as the argument.
 | `scripts/README.md` | Directory documentation for scripts/ |
 | `scripts/validate.sh` | Structural validation script for agent file pairs |
 | `scripts/validate-provenance.sh` | Provenance chain validation script for agent pairs against `sources.md` (plugin root) |
+| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation |
 | `tests/README.md` | Bats test dependency and run instructions |
 | `tests/validate.bats` | Bats tests for validate.sh |
 | `tests/validate-provenance.bats` | Bats tests for validate-provenance.sh |
diff --git a/plugins/kyberforge/skills/skill-audit/README.md b/plugins/kyberforge/skills/skill-audit/README.md
index 83d0876..95b714e 100644
--- a/plugins/kyberforge/skills/skill-audit/README.md
+++ b/plugins/kyberforge/skills/skill-audit/README.md
@@ -4,7 +4,7 @@ Audit a skill directory against the agentskills.io specification. Runs structura
 
 ## What it does
 
-1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance checks
+1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags known-bad description openers, vague wording, padding phrases, and "There is/are" sentence openers
 2. Reads all files in the skill directory
 3. Applies qualitative checks across seven dimensions
 4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — and a result block with handoff to /skill-improve
@@ -24,6 +24,12 @@ Provide the path to the skill directory to audit when invoking.
 | `SKILL.md` | Skill instructions for agents |
 | `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description length, line count, placeholder detection, script executable bit, and interactive-prompt detection |
 | `scripts/validate-provenance.sh` | Provenance validator — checks sources.md completeness, source_keys/slug consistency, Contributing files existence, bidirectional linkage, Research doc: fields, and upstream research doc alignment |
+| `scripts/vale-wrap.sh` | Vale prefilter wrapper — runs the bundled `Kyberforge` Vale styles against SKILL.md and reports alerts as deterministic FAILs ahead of Step 3's qualitative review |
+| `assets/vale/.vale.ini` | Vale configuration — points Vale at the bundled `Kyberforge` style path, self-located relative to `vale-wrap.sh` |
+| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Vale rule — flags literal "This skill..."/"This agent..." description openers |
+| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Vale rule — flags generic "see references/" padding phrasing in conditional references |
+| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Vale rule — flags body sentences starting with "There is"/"There are" |
+| `assets/vale/styles/Kyberforge/VagueWording.yml` | Vale rule — flags known filler wording (e.g. "helps with", "utilize") |
 | `references/description-quality.md` | Spec-grounded rubric for description auditing — loaded when a finding is borderline |
 | `references/body-discipline.md` | Spec-grounded rubric for body discipline auditing — loaded when padding vs necessity is unclear |
 | `references/sources.md` | Provenance record — agentskills.io sources that informed this skill and which files each contributed to |
-- 
2.43.0


From 6910f1b5a5b38ae959552a14e98ea2a03d7b2ba8 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 19:55:36 +0000
Subject: [PATCH 40/45] fix(lint): reject checkpoint-suffixed tags as the
 release-gate baseline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git describe --match is a shell glob, not a regex: the trailing `*`s
in 'v[0-9]*.[0-9]*.[0-9]*' match any suffix, so a tag like
v1.2.3-checkpoint or v1.2.3-rc1 satisfied the pattern and could be
picked as LAST_TAG instead of the true last release. That silently
shifts the diff baseline and can let a push skip a required release.
--exclude '*-*' rules out any tag carrying a hyphenated suffix.

Added a regression test that tags a release-relevant change with a
v1.0.1-checkpoint tag right after v1.0.0 and asserts the gate still
fires — confirmed it fails against the pre-fix script and passes
against the fix.
---
 scripts/check-release-needed.sh    |  7 ++++++-
 tests/test-check-release-needed.sh | 18 ++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/scripts/check-release-needed.sh b/scripts/check-release-needed.sh
index 61b8b27..ad2e094 100755
--- a/scripts/check-release-needed.sh
+++ b/scripts/check-release-needed.sh
@@ -55,7 +55,12 @@ fi
 # experiment tag reachable from the pushed ref must not shift the diff baseline.
 # The tag is resolved from $PUSHED_REF, not HEAD, for the same reason the diff
 # is: a tag reachable only from HEAD is not part of the history being pushed.
-LAST_TAG="$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' "$PUSHED_REF" 2>/dev/null || true)"
+# --match is a shell glob, not a regex: its trailing `*`s match any suffix, so
+# without --exclude a pre-release/checkpoint tag like v1.2.3-checkpoint or
+# v1.2.3-rc1 also satisfies 'v[0-9]*.[0-9]*.[0-9]*' and could be picked over the
+# true last release tag. --exclude is glob syntax too, so '*-*' is what actually
+# rules out any tag carrying a hyphenated suffix, leaving only bare vMAJOR.MINOR.PATCH.
+LAST_TAG="$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' --exclude '*-*' "$PUSHED_REF" 2>/dev/null || true)"
 
 if [[ -z "$LAST_TAG" ]]; then
   echo "FAIL: no release tag exists yet, but .pre-commit-hooks.yaml already exposes hooks to external consumers." >&2
diff --git a/tests/test-check-release-needed.sh b/tests/test-check-release-needed.sh
index 440960b..410281b 100755
--- a/tests/test-check-release-needed.sh
+++ b/tests/test-check-release-needed.sh
@@ -419,6 +419,24 @@ else
   fail "the repo's own .pre-commit-hooks.yaml no longer satisfies the entry constraints: $OUT20"
 fi
 
+# --- 21. A vX.Y.Z-suffixed checkpoint tag must not satisfy the release gate ---
+# git describe --match uses shell-glob semantics, not regex: the trailing `*` in
+# 'v[0-9]*.[0-9]*.[0-9]*' matches any suffix, so a pre-release/checkpoint tag like
+# v1.0.1-checkpoint also satisfies the glob and can be picked as LAST_TAG instead
+# of the true last release tag — hiding a real release-relevant change that landed
+# before the checkpoint tag from the diff.
+echo ""
+echo "--- ignores a vX.Y.Z-checkpoint tag and still flags the change since the real release tag ---"
+FIXTURE21="$(make_tagged_fixture)"; track "$FIXTURE21"
+echo "v2" > "$FIXTURE21/scripts/skill-size-check.sh"
+(cd "$FIXTURE21" && git add -A && git commit -q -m "real release-relevant change" && git tag v1.0.1-checkpoint)
+OUT21=$(run_check "$FIXTURE21" "refs/heads/main" || true)
+if echo "$OUT21" | grep -q "skill-size-check.sh"; then
+  pass "still flags the release-relevant change since v1.0.0, ignoring the vX.Y.Z-checkpoint tag"
+else
+  fail "a vX.Y.Z-checkpoint tag satisfied the glob and hid a real release-relevant change"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [[ $FAIL -eq 0 ]]
-- 
2.43.0


From 680aa4f43c9b6fb0b1d546f7268bb3dcaae241ca Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 20:14:23 +0000
Subject: [PATCH 41/45] refactor(kyberforge): consolidate vale-wrap.sh's config
 parsing and subprocess spawns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two efficiency findings from a code-review pass:
- The separated (--config X) and joined (--config=X) argument branches
  duplicated ~20 lines of absolutize-if-relative path logic. Extracted
  into abs_config_value(), used by both branches; the redundant
  --config=/* special case falls out since the helper already passes
  absolute paths through unchanged.
- The common single-file path spawned python3 twice per file (once for
  abspath resolution, once for flatten()). flatten() now optionally
  takes a tmpdir arg and does both in one process. The per-file loop
  under a directory argument is unchanged — that path wasn't flagged.

agent-audit's copy is canonical; skill-audit's copy was regenerated via
scripts/sync-vale-styles.sh, not hand-edited, to guarantee byte parity.
No hardening (bash 3.2 compat, surrogateescape, symlink guards) touched.
Verified: tests/test-vale-wrap.sh 39/39, check-vale-style-sync.sh clean,
full suite 12/12.
---
 .../skills/agent-audit/scripts/vale-wrap.sh   | 85 +++++++++++++------
 .../skills/skill-audit/scripts/vale-wrap.sh   | 85 +++++++++++++------
 2 files changed, 114 insertions(+), 56 deletions(-)

diff --git a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
index dae60b4..862f44c 100755
--- a/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/agent-audit/scripts/vale-wrap.sh
@@ -77,6 +77,17 @@ is_builtin_output() {
     *) false ;;
   esac
 }
+# Absolutizes a `--config` value against the caller's cwd. Shared by both
+# argument forms below — separated (`--config X`) and joined (`--config=X`)
+# — so the "already absolute vs. needs $cwd prefixed" check lives in exactly
+# one place instead of being duplicated per form.
+abs_config_value() {
+  if [[ "$1" == /* ]]; then
+    printf '%s' "$1"
+  else
+    printf '%s' "$cwd/$1"
+  fi
+}
 for arg in "$@"; do
   if [[ -n "$pending_flag" ]]; then
     # Value of a separated two-argv flag. It is never a lint target, however
@@ -85,11 +96,7 @@ for arg in "$@"; do
     case "$pending_flag" in
       --config)
         # Always a path, and required to exist.
-        if [[ "$arg" == /* ]]; then
-          vale_args+=("$arg")
-        else
-          vale_args+=("$cwd/$arg")
-        fi
+        vale_args+=("$(abs_config_value "$arg")")
         ;;
       --output|--path)
         # See `is_builtin_output` above for why the built-in `--output` names
@@ -117,13 +124,8 @@ for arg in "$@"; do
       config_given=true
       continue
       ;;
-    --config=/*)
-      vale_args+=("$arg")
-      config_given=true
-      continue
-      ;;
     --config=*)
-      vale_args+=("--config=$cwd/${arg#--config=}")
+      vale_args+=("--config=$(abs_config_value "${arg#--config=}")")
       config_given=true
       continue
       ;;
@@ -204,11 +206,33 @@ abspath() {
 }
 
 flatten() {
-  python3 - "$1" "$2" <<'PYTHON'
+  # Two call shapes: `flatten src dest` (dest already resolved and inside the
+  # scratch tree — the per-markdown-file calls in the directory branch below)
+  # writes straight to `dest`. `flatten src raw_dest tmpdir` (the single-file
+  # branch further down) additionally resolves `raw_dest` the way a separate
+  # `abspath` call used to, applies the same sandbox-escape guard, and prints
+  # the resolved path — folding two python3 spawns per file into one.
+  python3 - "$@" <<'PYTHON'
+import os
 import re
 import sys
 
-src, dest = sys.argv[1], sys.argv[2]
+src, dest_input = sys.argv[1], sys.argv[2]
+tmpdir = sys.argv[3] if len(sys.argv) > 3 else None
+
+if tmpdir is None:
+    dest = dest_input
+else:
+    dest = os.path.abspath(dest_input)
+    if not dest.startswith(tmpdir + os.sep):
+        print(
+            f"vale-wrap.sh: refusing to lint '{src}': its scratch copy would "
+            f"land outside {tmpdir}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+
 # surrogateescape keeps a non-UTF-8 file (reachable via a directory argument)
 # a byte-for-byte round trip instead of aborting the whole run on a decode error.
 with open(src, encoding='utf-8', errors='surrogateescape') as fh:
@@ -435,6 +459,9 @@ if header_m:
 
 with open(dest, 'w', encoding='utf-8', errors='surrogateescape') as fh:
     fh.write(content)
+
+if tmpdir is not None:
+    print(dest)
 PYTHON
 }
 
@@ -449,23 +476,23 @@ mkdir -p "$mirror"
 argv_paths=()
 for arg in ${path_args[@]+"${path_args[@]}"}; do
   if [[ "$arg" == /* ]]; then
-    dest="$tmpdir$arg"
+    raw_dest="$tmpdir$arg"
   else
-    dest="$mirror/$arg"
+    raw_dest="$mirror/$arg"
   fi
-  dest="$(abspath "$dest")"
-  # A path argument with enough leading `..` to climb past the mirror root would
-  # write outside the scratch dir. The real filesystem clamps such a path at
-  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
-  case "$dest" in
-    "$tmpdir"/*) ;;
-    *)
-      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
-      exit 2
-      ;;
-  esac
-  mkdir -p "$(dirname "$dest")"
   if [[ -d "$arg" ]]; then
+    dest="$(abspath "$raw_dest")"
+    # A path argument with enough leading `..` to climb past the mirror root would
+    # write outside the scratch dir. The real filesystem clamps such a path at
+    # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
+    case "$dest" in
+      "$tmpdir"/*) ;;
+      *)
+        echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
+        exit 2
+        ;;
+    esac
+    mkdir -p "$(dirname "$dest")"
     # A directory is mirrored whole — vale applies its own format filtering to
     # the tree, so any file dropped here would be silently unlinted — and then
     # every markdown file in the copy is flattened in place. `.git` is pruned:
@@ -484,7 +511,9 @@ for arg in ${path_args[@]+"${path_args[@]}"}; do
       flatten "$md" "$md"
     done < <(find "$dest" -type f -name '*.md' -print0)
   else
-    flatten "$arg" "$dest"
+    # `abspath` + `flatten` folded into one python3 process — see the comment
+    # atop `flatten` above.
+    dest="$(flatten "$arg" "$raw_dest" "$tmpdir")"
   fi
   if [[ "$arg" == /* ]]; then
     argv_paths+=("$dest")
diff --git a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
index dae60b4..862f44c 100755
--- a/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
+++ b/plugins/kyberforge/skills/skill-audit/scripts/vale-wrap.sh
@@ -77,6 +77,17 @@ is_builtin_output() {
     *) false ;;
   esac
 }
+# Absolutizes a `--config` value against the caller's cwd. Shared by both
+# argument forms below — separated (`--config X`) and joined (`--config=X`)
+# — so the "already absolute vs. needs $cwd prefixed" check lives in exactly
+# one place instead of being duplicated per form.
+abs_config_value() {
+  if [[ "$1" == /* ]]; then
+    printf '%s' "$1"
+  else
+    printf '%s' "$cwd/$1"
+  fi
+}
 for arg in "$@"; do
   if [[ -n "$pending_flag" ]]; then
     # Value of a separated two-argv flag. It is never a lint target, however
@@ -85,11 +96,7 @@ for arg in "$@"; do
     case "$pending_flag" in
       --config)
         # Always a path, and required to exist.
-        if [[ "$arg" == /* ]]; then
-          vale_args+=("$arg")
-        else
-          vale_args+=("$cwd/$arg")
-        fi
+        vale_args+=("$(abs_config_value "$arg")")
         ;;
       --output|--path)
         # See `is_builtin_output` above for why the built-in `--output` names
@@ -117,13 +124,8 @@ for arg in "$@"; do
       config_given=true
       continue
       ;;
-    --config=/*)
-      vale_args+=("$arg")
-      config_given=true
-      continue
-      ;;
     --config=*)
-      vale_args+=("--config=$cwd/${arg#--config=}")
+      vale_args+=("--config=$(abs_config_value "${arg#--config=}")")
       config_given=true
       continue
       ;;
@@ -204,11 +206,33 @@ abspath() {
 }
 
 flatten() {
-  python3 - "$1" "$2" <<'PYTHON'
+  # Two call shapes: `flatten src dest` (dest already resolved and inside the
+  # scratch tree — the per-markdown-file calls in the directory branch below)
+  # writes straight to `dest`. `flatten src raw_dest tmpdir` (the single-file
+  # branch further down) additionally resolves `raw_dest` the way a separate
+  # `abspath` call used to, applies the same sandbox-escape guard, and prints
+  # the resolved path — folding two python3 spawns per file into one.
+  python3 - "$@" <<'PYTHON'
+import os
 import re
 import sys
 
-src, dest = sys.argv[1], sys.argv[2]
+src, dest_input = sys.argv[1], sys.argv[2]
+tmpdir = sys.argv[3] if len(sys.argv) > 3 else None
+
+if tmpdir is None:
+    dest = dest_input
+else:
+    dest = os.path.abspath(dest_input)
+    if not dest.startswith(tmpdir + os.sep):
+        print(
+            f"vale-wrap.sh: refusing to lint '{src}': its scratch copy would "
+            f"land outside {tmpdir}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+
 # surrogateescape keeps a non-UTF-8 file (reachable via a directory argument)
 # a byte-for-byte round trip instead of aborting the whole run on a decode error.
 with open(src, encoding='utf-8', errors='surrogateescape') as fh:
@@ -435,6 +459,9 @@ if header_m:
 
 with open(dest, 'w', encoding='utf-8', errors='surrogateescape') as fh:
     fh.write(content)
+
+if tmpdir is not None:
+    print(dest)
 PYTHON
 }
 
@@ -449,23 +476,23 @@ mkdir -p "$mirror"
 argv_paths=()
 for arg in ${path_args[@]+"${path_args[@]}"}; do
   if [[ "$arg" == /* ]]; then
-    dest="$tmpdir$arg"
+    raw_dest="$tmpdir$arg"
   else
-    dest="$mirror/$arg"
+    raw_dest="$mirror/$arg"
   fi
-  dest="$(abspath "$dest")"
-  # A path argument with enough leading `..` to climb past the mirror root would
-  # write outside the scratch dir. The real filesystem clamps such a path at
-  # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
-  case "$dest" in
-    "$tmpdir"/*) ;;
-    *)
-      echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
-      exit 2
-      ;;
-  esac
-  mkdir -p "$(dirname "$dest")"
   if [[ -d "$arg" ]]; then
+    dest="$(abspath "$raw_dest")"
+    # A path argument with enough leading `..` to climb past the mirror root would
+    # write outside the scratch dir. The real filesystem clamps such a path at
+    # `/`; the mirror can't, so refuse rather than scribble outside the sandbox.
+    case "$dest" in
+      "$tmpdir"/*) ;;
+      *)
+        echo "vale-wrap.sh: refusing to lint '$arg': its scratch copy would land outside $tmpdir" >&2
+        exit 2
+        ;;
+    esac
+    mkdir -p "$(dirname "$dest")"
     # A directory is mirrored whole — vale applies its own format filtering to
     # the tree, so any file dropped here would be silently unlinted — and then
     # every markdown file in the copy is flattened in place. `.git` is pruned:
@@ -484,7 +511,9 @@ for arg in ${path_args[@]+"${path_args[@]}"}; do
       flatten "$md" "$md"
     done < <(find "$dest" -type f -name '*.md' -print0)
   else
-    flatten "$arg" "$dest"
+    # `abspath` + `flatten` folded into one python3 process — see the comment
+    # atop `flatten` above.
+    dest="$(flatten "$arg" "$raw_dest" "$tmpdir")"
   fi
   if [[ "$arg" == /* ]]; then
     argv_paths+=("$dest")
-- 
2.43.0


From e62f68a1ccd3384b028768c3ca62bfcd533e7176 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Sun, 9 Aug 2026 20:14:36 +0000
Subject: [PATCH 42/45] refactor(lint): cache manifest parsing, single-pass
 size check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two more efficiency findings from the same code-review pass:

- check-vale-style-sync.sh's hook_file_regexes() reparsed both
  pre-commit manifests from scratch on every call. The final
  validation loop calls it once per probe (3 probes: skill-audit once,
  agent-audit twice for its two file shapes), so agent-audit's regex
  set was being parsed twice for no reason. Now cached per skill in a
  lazily-populated associative array, with a separate "seen" map so an
  empty result isn't mistaken for "not yet computed."
- skill-size-check.sh read the target file twice (separate awk and
  wc -w calls) to get line and word counts; now a single awk pass
  returns both. Also documented, next to MAX_LINES/MAX_WORDS, why
  those constants are duplicated against skill-audit/scripts/
  validate.sh's Python implementation rather than unified — same
  cross-language/cross-context tradeoff as vale-wrap.sh's duplication,
  guarded by tests/test-skill-size-check.sh's drift check.

Verified: test-check-vale-style-sync.sh 20/20, test-skill-size-check.sh
9/9, full suite 12/12, pre-commit --all-files clean.
---
 scripts/check-vale-style-sync.sh | 57 +++++++++++++++++++++-----------
 scripts/skill-size-check.sh      | 20 ++++++++---
 2 files changed, 53 insertions(+), 24 deletions(-)

diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh
index f6ede61..49e6a9d 100755
--- a/scripts/check-vale-style-sync.sh
+++ b/scripts/check-vale-style-sync.sh
@@ -80,26 +80,45 @@ done
 # Prints the `files:` regex of every hook, in either manifest, whose entry is
 # $1's vale-wrap.sh. Records are delimited by their `- id:` line, so the check
 # does not depend on `entry:` preceding `files:` within a record.
+#
+# Cached per skill (in HOOK_REGEX_CACHE, populated lazily) because the final
+# validation loop below probes agent-audit twice — once for its CC agent-file
+# shape, once for its Copilot .agent.md shape — and both probes need the same
+# regex set. Without the cache, that pair of calls would each re-parse both
+# manifest files from scratch for no new information. HOOK_REGEX_CACHE_SEEN is
+# a separate array so a skill with no matching hooks (empty result) is still
+# recognized as already computed, rather than re-parsed every call.
+declare -A HOOK_REGEX_CACHE=()
+declare -A HOOK_REGEX_CACHE_SEEN=()
 hook_file_regexes() {
-  local skill="$1" manifest raw
-  for manifest in "$REPO_ROOT/.pre-commit-hooks.yaml" "$REPO_ROOT/.pre-commit-config.yaml"; do
-    [[ -f "$manifest" ]] || continue
-    awk -v skill="$skill" '
-      function flush() {
-        if (entry ~ skill "/scripts/vale-wrap.sh" && files != "") print files
-        entry = ""; files = ""
-      }
-      /^[ \t]*-[ \t]*id:/ { flush() }
-      /^[ \t]*entry:/ { entry = $0 }
-      /^[ \t]*files:/ { files = $0; sub(/^[ \t]*files:[ \t]*/, "", files) }
-      END { flush() }
-    ' "$manifest"
-  done | while IFS= read -r raw; do
-    # Strip the surrounding YAML quotes; the regex itself never carries them.
-    raw="${raw%\'}"; raw="${raw#\'}"
-    raw="${raw%\"}"; raw="${raw#\"}"
-    printf '%s\n' "$raw"
-  done
+  local skill="$1" manifest raw result
+  if [[ -n "${HOOK_REGEX_CACHE_SEEN[$skill]:-}" ]]; then
+    printf '%s' "${HOOK_REGEX_CACHE[$skill]}"
+    return
+  fi
+  result="$(
+    for manifest in "$REPO_ROOT/.pre-commit-hooks.yaml" "$REPO_ROOT/.pre-commit-config.yaml"; do
+      [[ -f "$manifest" ]] || continue
+      awk -v skill="$skill" '
+        function flush() {
+          if (entry ~ skill "/scripts/vale-wrap.sh" && files != "") print files
+          entry = ""; files = ""
+        }
+        /^[ \t]*-[ \t]*id:/ { flush() }
+        /^[ \t]*entry:/ { entry = $0 }
+        /^[ \t]*files:/ { files = $0; sub(/^[ \t]*files:[ \t]*/, "", files) }
+        END { flush() }
+      ' "$manifest"
+    done | while IFS= read -r raw; do
+      # Strip the surrounding YAML quotes; the regex itself never carries them.
+      raw="${raw%\'}"; raw="${raw#\'}"
+      raw="${raw%\"}"; raw="${raw#\"}"
+      printf '%s\n' "$raw"
+    done
+  )"
+  HOOK_REGEX_CACHE[$skill]="$result"
+  HOOK_REGEX_CACHE_SEEN[$skill]=1
+  printf '%s' "$result"
 }
 
 # Asks vale — the thing that actually applies these globs — whether a config
diff --git a/scripts/skill-size-check.sh b/scripts/skill-size-check.sh
index a1cf3bc..2c555e6 100755
--- a/scripts/skill-size-check.sh
+++ b/scripts/skill-size-check.sh
@@ -35,6 +35,13 @@ set -euo pipefail
 # tokenization and does not replace one. Re-measure the corpus before treating
 # any of these numbers as still current.
 
+# These constants are intentionally duplicated in
+# skill-audit/scripts/validate.sh (Python) rather than shared from one file:
+# this script is a standalone bash pre-commit hook, that one is an in-skill
+# Python validator invoked in a different context (same rationale as
+# vale-wrap.sh's per-plugin duplication — see its own header comment).
+# tests/test-skill-size-check.sh asserts both files agree on these values, so
+# drift between them fails CI rather than silently diverging.
 MAX_LINES=500
 MAX_WORDS=2770
 FAIL=0
@@ -42,16 +49,19 @@ FAIL=0
 for f in "$@"; do
   [[ -f "$f" ]] || continue
 
-  # awk's NR counts the final line even without a trailing newline, matching
-  # Python's splitlines() semantics (used by skill-audit/scripts/validate.sh
-  # for its own line count) — `wc -l` undercounts by 1 in that case.
-  lines=$(awk 'END{print NR}' "$f")
+  # Single awk pass computes both line count and word count, avoiding a
+  # second read of the file. NR counts the final line even without a
+  # trailing newline, matching Python's splitlines() semantics (used by
+  # skill-audit/scripts/validate.sh for its own line count) — `wc -l`
+  # undercounts by 1 in that case. Word count uses awk's default
+  # whitespace-splitting NF, matching `wc -w` semantics.
+  read -r lines words <<< "$(awk '{w += NF} END{print NR, w+0}' "$f")"
+
   if (( lines > MAX_LINES )); then
     echo "ERROR: $f has $lines lines, exceeding the $MAX_LINES-line ceiling (agentskills.io skill-authoring.md)" >&2
     FAIL=1
   fi
 
-  words=$(wc -w < "$f")
   if (( words > MAX_WORDS )); then
     echo "ERROR: $f has $words words (proxy for tokens), exceeding the $MAX_WORDS-word ceiling (~5,000 tokens, agentskills.io skill-authoring.md)" >&2
     FAIL=1
-- 
2.43.0


From 389a4f0f7a600ed2fab264eabe1190214cb29410 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 07:37:55 +0000
Subject: [PATCH 43/45] fix(lint): avoid bash 4 associative arrays in
 check-vale-style-sync.sh
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

check-vale-style-sync.sh used `declare -A` for a per-skill regex cache.
Associative arrays are bash 4.0+; this script runs as an always-run
pre-push hook with `language: system`, so it inherits whatever bash is
first on the invoking user's PATH. On macOS's stock bash 3.2, `declare -A`
at top level aborts immediately under `set -euo pipefail` — every push
would hard-fail before the sync check ran anything.

Replaced with two parallel indexed arrays (HOOK_REGEX_CACHE_KEYS/_VALS),
linear-scanned by index — same caching behavior (avoids re-parsing both
pre-commit manifests when agent-audit is probed twice), but only ever
uses ${#arr[@]} and index access, never a bare ${arr[@]} expansion.

Extended test-vale-wrap.sh's existing bash-3.2 hazard sweep to scan this
file too, and added a check for `declare -A` itself — it previously only
caught unguarded ${arr[@]} expansions and mapfile/readarray, so this
exact regression had no test that would have caught it.

Refs: #85
---
 scripts/check-vale-style-sync.sh | 37 ++++++++++++++++++--------------
 tests/test-vale-wrap.sh          | 15 ++++++++++++-
 2 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh
index 49e6a9d..cd4a0d6 100755
--- a/scripts/check-vale-style-sync.sh
+++ b/scripts/check-vale-style-sync.sh
@@ -81,21 +81,26 @@ done
 # $1's vale-wrap.sh. Records are delimited by their `- id:` line, so the check
 # does not depend on `entry:` preceding `files:` within a record.
 #
-# Cached per skill (in HOOK_REGEX_CACHE, populated lazily) because the final
-# validation loop below probes agent-audit twice — once for its CC agent-file
-# shape, once for its Copilot .agent.md shape — and both probes need the same
-# regex set. Without the cache, that pair of calls would each re-parse both
-# manifest files from scratch for no new information. HOOK_REGEX_CACHE_SEEN is
-# a separate array so a skill with no matching hooks (empty result) is still
-# recognized as already computed, rather than re-parsed every call.
-declare -A HOOK_REGEX_CACHE=()
-declare -A HOOK_REGEX_CACHE_SEEN=()
+# Cached per skill (parallel HOOK_REGEX_CACHE_KEYS/_VALS arrays, populated
+# lazily) because the final validation loop below probes agent-audit twice —
+# once for its CC agent-file shape, once for its Copilot .agent.md shape — and
+# both probes need the same regex set. Without the cache, that pair of calls
+# would each re-parse both manifest files from scratch for no new information.
+# Plain indexed arrays, not `declare -A`: associative arrays are bash 4.0+ and
+# this script must run on macOS's stock bash 3.2. Only ${#arr[@]} (always safe
+# on an empty/unset array under `set -u`) and index access are used below —
+# never a bare `${arr[@]}` expansion, which aborts on bash < 4.4 under nounset.
+HOOK_REGEX_CACHE_KEYS=()
+HOOK_REGEX_CACHE_VALS=()
 hook_file_regexes() {
-  local skill="$1" manifest raw result
-  if [[ -n "${HOOK_REGEX_CACHE_SEEN[$skill]:-}" ]]; then
-    printf '%s' "${HOOK_REGEX_CACHE[$skill]}"
-    return
-  fi
+  local skill="$1" manifest raw result idx=0
+  while [[ $idx -lt ${#HOOK_REGEX_CACHE_KEYS[@]} ]]; do
+    if [[ "${HOOK_REGEX_CACHE_KEYS[$idx]}" == "$skill" ]]; then
+      printf '%s' "${HOOK_REGEX_CACHE_VALS[$idx]}"
+      return
+    fi
+    idx=$((idx + 1))
+  done
   result="$(
     for manifest in "$REPO_ROOT/.pre-commit-hooks.yaml" "$REPO_ROOT/.pre-commit-config.yaml"; do
       [[ -f "$manifest" ]] || continue
@@ -116,8 +121,8 @@ hook_file_regexes() {
       printf '%s\n' "$raw"
     done
   )"
-  HOOK_REGEX_CACHE[$skill]="$result"
-  HOOK_REGEX_CACHE_SEEN[$skill]=1
+  HOOK_REGEX_CACHE_KEYS[${#HOOK_REGEX_CACHE_KEYS[@]}]="$skill"
+  HOOK_REGEX_CACHE_VALS[${#HOOK_REGEX_CACHE_VALS[@]}]="$result"
   printf '%s' "$result"
 }
 
diff --git a/tests/test-vale-wrap.sh b/tests/test-vale-wrap.sh
index c823a38..f883df6 100755
--- a/tests/test-vale-wrap.sh
+++ b/tests/test-vale-wrap.sh
@@ -447,7 +447,10 @@ fi
 # scripts, and the test runner AGENTS.md tells contributors to run by hand.
 # `mapfile` is checked alongside, because it is bash 4.0+ and the expansion scan
 # cannot see it — run-tests.sh carried one until it was replaced with a
-# `while read` loop, and nothing would have caught its return.
+# `while read` loop, and nothing would have caught its return. `declare -A`
+# (bash 4.0+ associative arrays) is checked for the same reason — the
+# expansion scan cannot see it, and check-vale-style-sync.sh carried a pair of
+# them until they were replaced with index-scanned plain arrays.
 echo ""
 echo "--- no unguarded array expansion remains in the macOS-facing scripts ---"
 unguarded_expansions() {
@@ -474,6 +477,7 @@ for BASH32_SCRIPT in \
   "$SCRIPT" \
   "$REPO_ROOT/scripts/skill-size-check.sh" \
   "$REPO_ROOT/scripts/check-release-needed.sh" \
+  "$REPO_ROOT/scripts/check-vale-style-sync.sh" \
   "$REPO_ROOT/tests/run-tests.sh"; do
   FOUND16="$(unguarded_expansions "$BASH32_SCRIPT")"
   if [[ -n "$FOUND16" ]]; then
@@ -486,6 +490,15 @@ for BASH32_SCRIPT in \
   if [[ -n "$FOUND16B" ]]; then
     HAZARDS16+="${BASH32_SCRIPT##*/}:$FOUND16B "
   fi
+  # `declare -A` (associative arrays) is bash 4.0+ with no 3.2 fallback. The
+  # flag cluster can carry other letters in any order (-Ag, -rA, ...); what
+  # matters is a literal uppercase A appearing in it, so match on that rather
+  # than the exact string "-A".
+  FOUND16C="$(awk '{ if ($0 ~ /^[[:space:]]*#/) print ""; else print }' "$BASH32_SCRIPT" \
+    | grep -nE '(^|[^[:alnum:]_])declare[[:space:]]+-[a-zA-Z]*A[a-zA-Z]*([[:space:]]|$)' || true)"
+  if [[ -n "$FOUND16C" ]]; then
+    HAZARDS16+="${BASH32_SCRIPT##*/}:$FOUND16C "
+  fi
 done
 if [[ -n "$HAZARDS16" ]]; then
   fail "unguarded array expansion(s) abort on bash < 4.4 under set -u: $(echo "$HAZARDS16" | tr '\n' ' ')"
-- 
2.43.0


From 76e0df6f5bcb87f0bf10eac134bdf1f265371bfb Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 07:38:09 +0000
Subject: [PATCH 44/45] chore(plugins): patch-bump gitea for shipped content
 changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

gitea 1.3.2 -> 1.3.3. The round-1 Vale corpus fix (3324a73) changed
shipped skill content (gitea-issues, gitea-prs, gitea-releases SKILL.md)
without touching this plugin's manifests, so installed copies would keep
serving the old content from cache. Every other plugin whose content
changed in this PR got this bump (bin, kyberforge, lint, four times
total) — gitea was missed each time.

Marketplace entries carry no per-plugin version, so both marketplace.json
files are untouched, matching prior version-bump commits in this PR.

Refs: #85
---
 plugins/gitea/.claude-plugin/plugin.json | 2 +-
 plugins/gitea/plugin.json                | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/gitea/.claude-plugin/plugin.json b/plugins/gitea/.claude-plugin/plugin.json
index 15a1214..2fc7c81 100644
--- a/plugins/gitea/.claude-plugin/plugin.json
+++ b/plugins/gitea/.claude-plugin/plugin.json
@@ -15,5 +15,5 @@
   ],
   "license": "MIT",
   "name": "gitea",
-  "version": "1.3.2"
+  "version": "1.3.3"
 }
diff --git a/plugins/gitea/plugin.json b/plugins/gitea/plugin.json
index 9601cec..ccef22b 100644
--- a/plugins/gitea/plugin.json
+++ b/plugins/gitea/plugin.json
@@ -20,5 +20,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.3.2"
+  "version": "1.3.3"
 }
-- 
2.43.0


From cf5de2bd87d39386cca21b3a183800d3975fe825 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 07:45:58 +0000
Subject: [PATCH 45/45] fix(lint): fail loudly on a nonexistent REPO_ROOT in
 check-vale-style-sync.sh
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A bad or stale REPO_ROOT argument fell through to the "neither copy
present" no-op guard and exited 0 — the exact "clean result can mean
nothing was checked" anti-pattern this PR spent multiple review rounds
eliminating elsewhere. That guard exists for a repo that legitimately has
no kyberforge plugin installed, not for a typo'd path.

Only the documented manual-invocation mode was affected: the shipped
pre-push hook always calls this script with zero args, which resolves via
`git rev-parse --show-toplevel` and is always valid inside a repo.

Added a regression test asserting a nonexistent REPO_ROOT exits non-zero.

Refs: #85
---
 scripts/check-vale-style-sync.sh    | 12 +++++++++---
 tests/test-check-vale-style-sync.sh | 13 +++++++++++++
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/scripts/check-vale-style-sync.sh b/scripts/check-vale-style-sync.sh
index cd4a0d6..a547604 100755
--- a/scripts/check-vale-style-sync.sh
+++ b/scripts/check-vale-style-sync.sh
@@ -10,11 +10,17 @@ set -euo pipefail
 # only one of the two. Run from repo root or pass REPO_ROOT as arg.
 
 REPO_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+# A nonexistent REPO_ROOT must fail loudly, not fall through to the "neither
+# copy present" no-op below — that guard exists for a repo that legitimately
+# has no kyberforge plugin installed, not for a typo'd or stale path, and a
+# clean exit 0 here would read as "checked, in sync" when nothing ran at all.
+if [[ ! -d "$REPO_ROOT" ]]; then
+  echo "Vale style sync check failed: REPO_ROOT '$REPO_ROOT' is not a directory." >&2
+  exit 1
+fi
 # Absolutized because the glob probe below `cd`s into a scratch tree, where a
 # relative --config path would stop resolving.
-if [[ -d "$REPO_ROOT" ]]; then
-  REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
-fi
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
 FAIL=0
 
 err() { echo "  FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
diff --git a/tests/test-check-vale-style-sync.sh b/tests/test-check-vale-style-sync.sh
index c4f88bb..965e3e2 100755
--- a/tests/test-check-vale-style-sync.sh
+++ b/tests/test-check-vale-style-sync.sh
@@ -123,6 +123,19 @@ else
   fail "exited non-zero when skill-audit/agent-audit are simply absent"
 fi
 
+# --- 5b. Exits 1 when REPO_ROOT does not exist ---
+# A nonexistent path used to fall through to the "neither copy present" no-op
+# (test 5 above) and exit 0 — indistinguishable from a real, verified in-sync
+# result. That guard is for a repo legitimately missing kyberforge, not a
+# typo'd or stale path.
+echo ""
+echo "--- exits 1 when REPO_ROOT does not exist ---"
+if bash "$SCRIPT" "/nonexistent/path/$(date +%s)-$$" > /dev/null 2>&1; then
+  fail "exited 0 for a nonexistent REPO_ROOT — expected exit 1"
+else
+  pass "exits non-zero for a nonexistent REPO_ROOT"
+fi
+
 # --- 6. Exits 1 when only one of the two copies is present ---
 # The no-op guard used `||`, so a single missing copy also exited 0 — a deleted
 # or renamed copy passed the sync check silently.
-- 
2.43.0