fix(lint): resolve round-1 and round-2 review findings on the Vale prefilter

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

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

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)