session-orchestrator 3.19.0 → 3.21.0

package/scripts/lib/validate/check-owner-leakage.mjs

@@ -9,11 +9,14 @@
  * `canonicalizeLine()` collapses every known textual encoding of a path
  * (URL-percent, dash-as-separator, backslash, double-slash, `\uXXXX`/`%uXXXX`
  * escapes, HTML/numeric entities, unicode homoglyph slashes/dashes, case)
- * into ONE canonical slash-form, and the owner-secret patterns are matched
- * ONCE against that canonical form (plus the raw line, for belt-and-braces).
- * A novel encoding of the same path normalizes to the same canonical string,
- * so it is caught structurally — no new regex required. Err toward
- * over-matching: this is a security guard, a false-positive is cheap, a
+ * into ONE canonical slash-form. CP1 is matched against that canonical form;
+ * the four DOT-anchored host/IP rules (CP2, CP3, CP7, CP8) are matched against
+ * the raw line AND the canonical form (#1080). The remaining rules stay RAW by
+ * measurement, not oversight — see the `canon` comment in the line loop for why
+ * the slash-anchored (CP4, CP10) and slug-anchored (CP6) rules must not be
+ * canonicalized. A novel encoding of the same path normalizes to the same
+ * canonical string, so it is caught structurally — no new regex required. Err
+ * toward over-matching: this is a security guard, a false-positive is cheap, a
  * false-negative ships a leak to the public mirror.
  *
  * Usage: check-owner-leakage.mjs <plugin-root>
@@ -65,6 +68,13 @@
  *      (a real string-literal events.gotzendorfer.at elsewhere in that file still FAILs)
  *   6. tests/scripts/export-hw-learnings.test.mjs — exempt from P8 ONLY: the RFC1918
  *      IPs there are the redaction subject of the anonymizeString suite, not leaks.
+ *   7. The public-site URL in the three PUBLISHED site pages (site/index.html,
+ *      site/impressum/index.html, site/datenschutz/index.html) — the domain is a
+ *      legally mandated publication (Impressum, §5 ECG) plus the JSON-LD
+ *      publisher/author identity and the rel="author" footer link. Like every
+ *      exclusion above it is LINE-SCOPED and reached only via isAllowlisted(), which
+ *      only CP3 and CP7 consult — CP1/CP2/CP4/CP5/CP6/CP8/CP10/CP11 still fail on
+ *      these files, on the very same line. (#1076)
  *
  * Exit codes:
  *   0 — all checks passed
@@ -434,6 +444,41 @@ const CP6_INPROCESS_PATTERNS = PRIVATE_SLUGS
 /** CP7: catch-all gotzendorfer.at (must not match allowlist) */
 const CP7 = /gotzendorfer\.at/;
 
+/**
+ * GLOBAL twins of the two allowlist-consulting domain rules, used to count
+ * OCCURRENCES in the raw vs the canonical form of a line (#1080 Finding A).
+ *
+ * Why an occurrence COUNT and not simply a second `.test()` on the canonical
+ * form: CP3 and CP7 are the only rules whose verdict is filtered by
+ * isAllowlisted(), and that allowlist matches a LINE FORM — the sanctioned
+ * Impressum/author URL, and the exact events doc-comment contract line.
+ * Canonicalization folds every `-` run to `/`, which mangles precisely that
+ * prose: ` *   - No literal ...` canonicalizes to ` *   / No literal ...`. So
+ * re-running isAllowlisted() against the canonical form would fail to recognise
+ * its own sanctioned line and turn this gate — and with it .husky/pre-commit —
+ * permanently red on a clean tree. Measured, not reasoned: that exact exclusion
+ * regex returns true on the raw line and false on its canonical form.
+ *
+ * The occurrence count separates the two cases without touching the allowlist:
+ * when the canonical form carries MORE domain tokens than the raw line, the
+ * surplus was produced by DECODING an escape, and a decoded token can never be
+ * the sanctioned publication the allowlist covers — so it bypasses the allowlist.
+ * When the counts are equal, the rule behaves exactly as it always did and
+ * consults the allowlist on the raw line.
+ */
+const CP3_G = /\bevents\.gotzendorfer\.at\b/g;
+const CP7_G = /gotzendorfer\.at/g;
+
+/**
+ * Count matches of a GLOBAL regex in `s` (0 when none).
+ * @param {RegExp} re a regex carrying the `g` flag
+ * @param {string} s
+ * @returns {number}
+ */
+function countMatches(re, s) {
+  return (s.match(re) || []).length;
+}
+
 /**
  * CP8: full RFC1918 private dotted-quad — internal-IP leak.
  * Matches only literal 4-octet private IPs (10.x.x.x, 192.168.x.x, 172.16-31.x.x).
@@ -511,6 +556,29 @@ function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+// DELIBERATE DUPLICATE — do not replace the function below with an import from
+// `scripts/lib/redact-spans.mjs`. This scanner is a documented STANDALONE
+// SINGLE-FILE vendoring target (`.claude/rules/security.md` § "Owner-Privacy
+// Pre-Commit Hook": consumer repos copy exactly this ONE file into their tree as
+// a pre-commit stage). A static import resolves in-tree but throws
+// ERR_MODULE_NOT_FOUND in every vendored copy — under the husky stage that means
+// empty stdout + exit 1 on a CLEAN tree, i.e. every commit blocked. Not
+// hypothetical: `tests/husky/pre-commit-owner-leakage.test.mjs` cpSync()s this
+// single file into a tmp repo, and the static-import variant turned all three of
+// its cases red (#974).
+//
+// The dynamic-import degrade used by getConfidentialNamePatterns() is NOT
+// available here. That helper degrades to `[]` — CP11 goes inert, CP1–CP10 keep
+// running, nothing leaks. A failed REDACTION has the opposite failure direction:
+// it prints confidential names verbatim into a PUBLIC GitHub-Actions log, which
+// is precisely the exposure this function exists to prevent (Fix 1 below). The
+// redaction sink must be unconditionally present, so it lives inline.
+//
+// `scripts/lib/redact-spans.mjs` is the shared primitive for IN-TREE consumers
+// (e.g. `scripts/lib/secret-masker.mjs`); this copy serves the vendored path.
+// The two are pinned byte-for-byte against each other by the drift guard in
+// `tests/lib/redact-spans.test.mjs` — change one and that suite goes red until
+// both agree again.
 /**
  * Redact every confidential-name span from `line`, ORDER-INDEPENDENTLY (Fix 1 + Fix 2).
  *
@@ -622,7 +690,47 @@ async function getConfidentialNamePatterns() {
 // ---------------------------------------------------------------------------
 // Text-scan extension allowlist (spec A.2)
 // ---------------------------------------------------------------------------
-const TEXT_EXTS = new Set(['.md', '.mjs', '.js', '.ts', '.json', '.yml', '.yaml', '.sh', '.txt']);
+// '.html' (#1076): the site/ tree is PUBLICLY SHIPPED (vercel.json outputDirectory:
+// "site"), so it is the highest-consequence class to scan, yet it was ungated here and
+// therefore invisible to all eleven CP rules.
+//
+// CORRECTION (#1080 Finding A). An earlier revision of this comment justified '.html'
+// partly by claiming its addition "revives canonicalizeLine()'s HTML-entity decoding,
+// which was dead in practice". That was true of exactly ONE of the eleven rules.
+// matchOwnerPath() (CP1) was the SOLE consumer of the canonical form — CP2-CP8, CP10
+// and CP11 each tested the RAW line — so an entity-encoded private host inside an href
+// (a link the BROWSER resolves and the scanner did not) still reported nothing. The
+// per-line canonical re-test in the scan loop below is what actually closes that, and
+// only for the four dot-anchored rules; see the `canon` comment there for why the rest
+// stay raw.
+//
+// '.xml', '.svg', '.css' (#1080 Finding B): the PUBLICLY-SHIPPED sentence above is true
+// VERBATIM of site/sitemap.xml and site/favicon.svg — same directory, same publication,
+// same consequence — which the '.html' addition walked past. Measured with one identical
+// planted defect per class before adding: the .html and .txt copies FAILed, the .xml and
+// .svg copies reported nothing. Cost is zero: the five tracked files in these classes
+// (assets/icon.svg, assets/og-card.svg, site/favicon.svg, site/sitemap.xml,
+// templates/static-html/styles.css) carry no hits — 1542 -> 1547 scanned, 0 findings.
+// `.jsonl` closes a gap this very wave opened: the harvested golden-record fixture at
+// tests/lib/vault-mirror/fixtures/golden-sessions.jsonl is tracked production data that
+// `.json` does not match, so the scanner would have skipped it for good. Measured before
+// adding: all 7 tracked `.jsonl` files pass (1525 -> 1532 scanned, 0 findings).
+const TEXT_EXTS = new Set([
+  '.md',
+  '.mjs',
+  '.js',
+  '.ts',
+  '.json',
+  '.jsonl',
+  '.yml',
+  '.yaml',
+  '.sh',
+  '.txt',
+  '.html',
+  '.xml',
+  '.svg',
+  '.css',
+]);
 
 // Dotfiles to include (checked by basename, BEFORE the extension gate —
 // extname('.env.example') is '.example' (truthy), so an extension-first check
@@ -723,16 +831,33 @@ function isAllowlisted(relPath, line) {
     '.claude-plugin/plugin.json',
     '.claude-plugin/marketplace.json',
     '.codex-plugin/plugin.json',
+    // A.4 exclusion 7 (#1076): the three PUBLISHED static pages (vercel.json
+    // outputDirectory: "site"). Rule-based, never file-based — membership here only
+    // buys the line-form test below, and isAllowlisted() is consulted by CP3 and CP7
+    // ONLY. A SELF_EXCLUSIONS entry would instead have switched off all eleven rules
+    // for these files; that broad form is deliberately NOT used.
+    'site/index.html',
+    'site/impressum/index.html',
+    'site/datenschutz/index.html',
   ]);
   const inAllowlistedFile = ALLOWLISTED_URL_PATHS.has(norm);
 
   if (inAllowlistedFile) {
     // Check that the only gotzendorfer.at occurrences on this line are sanctioned URLs or emails
     const SANCTIONED_URL = /https?:\/\/gotzendorfer\.at\b/g;
+    // The published site uses the www. host throughout, which SANCTIONED_URL cannot
+    // match — it requires the bare domain IMMEDIATELY after the scheme. Without this
+    // second form the three site entries above would exclude NOTHING and the gate
+    // (including .husky/pre-commit) would be permanently red. The two forms are
+    // DISJOINT: the www. prefix is mandatory here and impossible there, so no line
+    // can be counted twice (README.md stays at 1 token / 1 sanctioned match).
+    const SANCTIONED_PUBLIC_SITE = /(?:https?:\/\/)?www\.gotzendorfer\.at\b/g;
     const allGotzOnLine = [...line.matchAll(/gotzendorfer\.at/g)];
     const sanctionedUrlMatches = [...line.matchAll(SANCTIONED_URL)];
+    const sanctionedSiteMatches = [...line.matchAll(SANCTIONED_PUBLIC_SITE)];
     const emailMatches = [...line.matchAll(SANCTIONED_EMAILS)];
-    const totalSanctioned = sanctionedUrlMatches.length + emailMatches.length;
+    const totalSanctioned =
+      sanctionedUrlMatches.length + sanctionedSiteMatches.length + emailMatches.length;
     if (allGotzOnLine.length > 0 && allGotzOnLine.length === totalSanctioned) {
       return true;
     }
@@ -781,8 +906,6 @@ const textFiles = allFiles.filter(isTextFile);
 //   - .orchestrator/audits/** never scanned (A.2/A.4-5)
 //   - This guard's own source file (pattern-doc-comments define the scanner — not leaks).
 //   - This guard's own test file (string-literal fixtures exercise the detector — not leaks).
-//   - Persona content-lint tests (assert template files don't contain leakage strings;
-//     the assertion literals themselves match the scanner regex — fixtures, not leaks).
 // Self-exclusions are the design-time fix for the latent bug exposed when scanner
 // fixture files transition from untracked → tracked in the same commit that tightens
 // detection (commit a68e94f for the original two; commit 95c8237 deep-3 W4 added the
@@ -791,7 +914,9 @@ const textFiles = allFiles.filter(isTextFile);
 const SELF_EXCLUSIONS = new Set([
   'scripts/lib/validate/check-owner-leakage.mjs',
   'tests/lib/validate/check-owner-leakage.test.mjs',
-  'tests/templates/personas/content-lint.test.mjs',
+  // content-lint.test.mjs entry removed with the file itself (#985 Tier A,
+  // 2026-08-05) — a dangling exclusion would pre-authorize any future file
+  // at that path to bypass this scanner.
   'tests/husky/pre-commit-owner-leakage.test.mjs',
   // #634: encoding-contract fixtures (`-Users-bernhardg-` expected-value literals
   // are load-bearing for the resolveMemoryDir() assertions; P9 would self-flag them)
@@ -839,6 +964,33 @@ for (const filePath of scanFiles) {
   lines.forEach((line, idx) => {
     const lineNum = idx + 1;
 
+    // The canonical form of this line, computed ONCE (#1080 Finding A). Until now
+    // matchOwnerPath (CP1) was the ONLY consumer of canonicalizeLine; every other rule
+    // tested the raw line, so an entity-encoded private host inside an href resolved in
+    // the browser and reported nothing here. The four DOT-anchored rules (CP2, CP3, CP7,
+    // CP8) are re-tested against it below.
+    //
+    // Why exactly those four, and not every rule — the discriminator is which character
+    // the rule ANCHORS on, and it was measured, not assumed:
+    //   - Canonicalization can FABRICATE a '/' out of any benign hyphen run
+    //     (`@goetzendorfer-team` -> `@goetzendorfer/team`, `~-Projects-Bernhard` ->
+    //     `~/Projects/Bernhard`; both flip false -> true under canon). So the
+    //     SLASH-anchored rules CP4 and CP10 would gain folding artifacts, and stay raw.
+    //   - It can never fabricate a '.' from a separator: `gitlab-gotzendorfer-at`
+    //     canonicalizes to `gitlab/gotzendorfer/at`, dot-free. A '.' appears in the
+    //     canonical form ONLY by decoding an escape — which is the evasion itself. So for
+    //     the DOT-anchored rules (CP2, CP3, CP7, CP8) every canonical-only hit is a
+    //     decoded evasion by construction, and the false-positive surface is empty.
+    //   - CP6 stays raw for the mirror-image reason: it anchors on `\b`-delimited slug
+    //     literals, and the dash folding SHREDS five of the seven slugs
+    //     (`mail-assistant` -> `mail/assistant`, which `\bmail-assistant\b` no longer
+    //     matches), so a canonical test there is a no-op at best.
+    //   - CP5 anchors on an identifier and CP11 on host-local names; neither is a path or
+    //     host spelling, so neither is re-tested.
+    // Repo-wide cost of the four, measured over 1547 tracked files before landing: 0 new
+    // findings.
+    const canon = canonicalizeLine(line);
+
     // CP1: personal home path — CANONICALIZED match (#661). One structural rule
     // replaces the slash-form (P1, #631) + dash-encoded (P9, #634) treadmill and
     // catches percent/unicode/backslash/homoglyph encodings of the same path.
@@ -847,14 +999,22 @@ for (const filePath of scanFiles) {
       violations.push({ relPath, lineNum, pattern: ownerPathHit, lineContent: line.trim() });
     }
 
-    // CP2: private GitLab host
-    if (CP2.test(line)) {
+    // CP2: private GitLab host — raw OR canonical (#1080). ONE `if` per rule, so a
+    // line matching BOTH forms still reports exactly ONE violation. (The pre-existing
+    // 'CP2: private GitLab host' scan row, which expects fails: 2 for the CP2+CP7 pair,
+    // is the standing guard against a double-count regression here.) CP2 consults no
+    // allowlist, so the raw/canonical split CP3 and CP7 need does not arise.
+    if (CP2.test(line) || CP2.test(canon)) {
       violations.push({ relPath, lineNum, pattern: 'CP2 (gitlab.gotzendorfer.at)', lineContent: line.trim() });
     }
 
-    // CP3: private events domain — check exclusion 6 first
-    if (CP3.test(line)) {
-      if (!isAllowlisted(relPath, line)) {
+    // CP3: private events domain — the raw form consults the exclusion allowlist
+    // exactly as before; a DECODED surplus occurrence (canonical count > raw count)
+    // bypasses it, because an encoded spelling is never the sanctioned publication.
+    // See CP3_G / CP7_G for why this is a count and not isAllowlisted(relPath, canon).
+    const cp3Decoded = countMatches(CP3_G, canon) > countMatches(CP3_G, line);
+    if (CP3.test(line) || cp3Decoded) {
+      if (cp3Decoded || !isAllowlisted(relPath, line)) {
         violations.push({ relPath, lineNum, pattern: 'CP3 (events.gotzendorfer.at)', lineContent: line.trim() });
       }
     }
@@ -879,15 +1039,23 @@ for (const filePath of scanFiles) {
       }
     }
 
-    // CP7: catch-all gotzendorfer.at — check exclusion allowlist
-    if (CP7.test(line)) {
-      if (!isAllowlisted(relPath, line)) {
+    // CP7: catch-all gotzendorfer.at — same split as CP3: the raw form consults the
+    // exclusion allowlist, a decoded surplus occurrence bypasses it. This is the arm
+    // that catches the sharpest shape of #1080 Finding A — a WORKING link on a published
+    // page, `<a href="https://gitlab&#46;gotzendorfer&#46;at/...">`, which the browser
+    // resolves and the raw-only rule read as ordinary text.
+    const cp7Decoded = countMatches(CP7_G, canon) > countMatches(CP7_G, line);
+    if (CP7.test(line) || cp7Decoded) {
+      if (cp7Decoded || !isAllowlisted(relPath, line)) {
         violations.push({ relPath, lineNum, pattern: 'CP7 (gotzendorfer.at catch-all)', lineContent: line.trim() });
       }
     }
 
-    // CP8: full RFC1918 private dotted-quad — internal IP leak (redaction-test fixtures exempt)
-    if (CP8.test(line) && !CP8_ALLOWLIST.has(relPath)) {
+    // CP8: full RFC1918 private dotted-quad — internal IP leak (redaction-test fixtures
+    // exempt). Raw OR canonical: `10&#46;11&#46;12&#46;13` decodes to a literal quad.
+    // The allowlist here is PATH-scoped, not line-scoped, so it needs no raw/canonical
+    // split — it applies identically to both forms.
+    if ((CP8.test(line) || CP8.test(canon)) && !CP8_ALLOWLIST.has(relPath)) {
       violations.push({ relPath, lineNum, pattern: 'CP8 (RFC1918 private IP)', lineContent: line.trim() });
     }
 

package/scripts/lib/validate/check-rules.mjs

@@ -23,6 +23,13 @@
 //           identical `hasEmptyGlobs` fix below.
 //       (b) learning-key must be present (traceability back to the emitter source).
 //       (c) expires-at must be present (auto-generated rules must have a TTL).
+//     Plus, ahead of the auto/handwritten split and binding on EVERY rule file
+//     regardless of cohort:
+//       (d) the frontmatter must PARSE (#1015). An unparseable file used to be
+//           skipped as "not auditable"; rule-loader.mjs, however, treats a
+//           parse error as always-on with empty meta, so the skipped file is
+//           exactly the one that loads everywhere and clears every gate. See
+//           the inline rationale at the parse site below.
 //
 // (2) HANDWRITTEN rules (no `auto-generated: true` — #880 FA5, WARN-only,
 //     NEVER affects the exit code). The auto-generated brandmauer above only
@@ -154,9 +161,9 @@ if (mdFiles.length === 0) {
 }
 
 // Parse every rule file once, splitting into the auto-generated and
-// handwritten cohorts. Malformed frontmatter → skipped from BOTH checks
-// (matches pre-#880 behaviour: a rule whose frontmatter cannot be parsed is
-// neither PASS'd nor FAIL'd).
+// handwritten cohorts. Malformed frontmatter → a cohort-independent hard FAIL
+// (#1015). It was previously skipped from BOTH checks ("neither PASS'd nor
+// FAIL'd"); see the parse site below for why that abstention was a blind spot.
 const autoGeneratedEntries = [];
 const handwrittenEntries = [];
 
@@ -173,8 +180,27 @@ for (const name of mdFiles.sort()) {
   let parsed;
   try {
     parsed = parseGlobsFrontmatter(contents);
-  } catch {
-    // Malformed frontmatter — not auditable by either branch, skip.
+  } catch (err) {
+    // MALFORMED FRONTMATTER IS A HARD FAIL (#1015) — it used to `continue`.
+    //
+    // The skip looked like a neutral abstention ("not auditable by either
+    // branch") but was in fact this validator's single blind spot, and it was
+    // blind to precisely the worst state. rule-loader.mjs catches the SAME
+    // throw (~:500-507), falls back to `globs = null, meta = {}, parseError =
+    // true`, and then (~:519-530) pushes the entry with `alwaysOn: true`.
+    // Empty meta means applyGates() has nothing to gate on, so the file also
+    // clears tier/host-class/mode/EXPIRY gating by design ("a rule is never
+    // silently dropped"). Net effect: the one file this branch declined to
+    // audit is the one file the loader loads ALWAYS-ON, in every context,
+    // forever — the exact state the never-always-on invariant (#668/#687)
+    // exists to forbid, and the landing state of a frontmatter-injection whose
+    // payload happens to be colon-less (an injected `\n` + a line with no `:`).
+    // Unparseable therefore means UNSAFE, not "unknown": FAIL, never skip.
+    fail(
+      `.claude/rules/${name} — frontmatter does not parse (${err.message}) — rule-loader.mjs treats a parse ` +
+        'error as ALWAYS-ON with EMPTY meta, so this file loads in every context and clears every gate ' +
+        '(no expiry, no tier, no host-class, no mode). Fix the frontmatter or remove the file.',
+    );
     continue;
   }
 

package/scripts/lib/validate/check-skills.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// check-skills.mjs — Validate the frontmatter contract of every skills/<name>/SKILL.md.
+// Usage: check-skills.mjs <plugin-root>
+// Outputs lines of the form "  PASS: ..." / "  FAIL: ..."
+// Exit 0 = all checks passed; exit 1 = at least one failure.
+//
+// WHY A REAL PARSER: the sibling check-agents.mjs validates agent frontmatter with
+// line-oriented regexes. That is exactly why 12 of 46 SKILL.md frontmatter blocks
+// could sit unparseable in the tree unnoticed — an unquoted single-line
+// `description:` containing a `: ` (e.g. "Iron Law: NO FIXES") is not YAML, but a
+// regex that only looks for `^description:` sees nothing wrong. Claude Code's own
+// loader is lenient, so the defect was latent rather than visible. This check
+// follows check-commands.mjs instead: a real js-yaml CORE_SCHEMA parse (R8) is the
+// rule the other five hang off, because none of the field rules can be evaluated
+// on a block that does not parse.
+//
+// DELIBERATELY NOT IMPLEMENTED — see the report for #<wave>:
+//   * A block-scalar ban. check-agents.mjs bans `description: >` for agents/*.md
+//     because the agent loader cannot read it. For SKILL.md the sign is REVERSED:
+//     the folded block scalar is the only form that makes the `: ` collision above
+//     structurally impossible, 23 of 46 files already use it, and the 12 repairs
+//     that made this check green all landed on it. Porting the agent rule here
+//     would red 35 of 46 files and forbid the fix.
+//   * Length ceilings on `name` / `description`. No spec vendored in this repo
+//     states one, and an invented requirement is worse than none. (Measured
+//     2026-08-15 at the repairing commit: longest name 22 chars, longest
+//     description 1012 chars — a hypothetical 1024 ceiling would sit 12 chars
+//     above the live corpus and go red on the next sentence added.)
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+import { extractInitialFrontmatter } from './frontmatter-block.mjs';
+
+const [, , pluginRoot] = process.argv;
+
+if (!pluginRoot) {
+  console.error('Usage: check-skills.mjs <plugin-root>');
+  process.exit(1);
+}
+
+const SKILLS_DIR_NAME = 'skills';
+const SKILL_FILE = 'SKILL.md';
+const KEBAB_CASE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) {
+  console.log(`  PASS: ${msg}`);
+  passed++;
+}
+
+function fail(msg) {
+  console.log(`  FAIL: ${msg}`);
+  failed++;
+}
+
+/**
+ * Enumerate `skills/<dir>/SKILL.md` one level below the skills root.
+ *
+ * Depth is capped at one level on purpose: R5 (name === directory name) is only
+ * meaningful for a skill that owns its immediate directory. Measured 2026-08-15:
+ * `find skills -mindepth 3 -name SKILL.md` returns 0, so the cap loses nothing
+ * today. Revisit if nested skill packages ever land.
+ *
+ * @param {string} skillsDir - absolute path to the skills root
+ * @returns {Array<{ dirName: string, relPath: string, absPath: string }>} sorted by directory name
+ */
+function collectSkillFiles(skillsDir) {
+  const found = [];
+  for (const dirName of readdirSync(skillsDir).sort()) {
+    const dirPath = join(skillsDir, dirName);
+    let isDir;
+    try {
+      isDir = statSync(dirPath).isDirectory();
+    } catch {
+      isDir = false;
+    }
+    if (!isDir) continue;
+
+    const absPath = join(dirPath, SKILL_FILE);
+    if (!existsSync(absPath)) continue;
+
+    found.push({ dirName, relPath: `${SKILLS_DIR_NAME}/${dirName}/${SKILL_FILE}`, absPath });
+  }
+  return found;
+}
+
+/**
+ * Apply the frontmatter contract to one SKILL.md.
+ *
+ * Rules: R1 frontmatter block present · R8 block parses as a YAML mapping ·
+ * R2 `name` present · R3 `name` is kebab-case · R5 `name` === directory name ·
+ * R6 `description` present and non-empty.
+ *
+ * @param {{ dirName: string, relPath: string, absPath: string }} skill
+ * @returns {boolean} true when every rule holds
+ */
+function validateSkillFrontmatter(skill) {
+  const before = failed;
+  const content = readFileSync(skill.absPath, 'utf8');
+
+  // R1 — frontmatter block present.
+  const extracted = extractInitialFrontmatter(content);
+  if (!extracted.ok) {
+    fail(`${skill.relPath}: ${extracted.diagnostic}`);
+    return false;
+  }
+
+  // R8 — the block is valid YAML. Everything below depends on this holding.
+  let frontmatter;
+  try {
+    frontmatter = yaml.load(extracted.yamlText, { schema: yaml.CORE_SCHEMA });
+  } catch (error) {
+    const reason = error?.reason ?? error?.message ?? String(error);
+    const location = error?.mark
+      ? ` at frontmatter line ${error.mark.line + 1}, column ${error.mark.column + 1}`
+      : '';
+    fail(`${skill.relPath}: invalid YAML frontmatter: ${reason}${location}`);
+    return false;
+  }
+
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    fail(`${skill.relPath}: YAML frontmatter must be a non-null mapping/object`);
+    return false;
+  }
+
+  // R2 — name present.
+  const name = frontmatter.name;
+  if (typeof name !== 'string' || name.trim() === '') {
+    fail(`${skill.relPath}: missing or empty required frontmatter field: name`);
+  } else {
+    // R3 — name is kebab-case.
+    if (!KEBAB_CASE.test(name)) {
+      fail(`${skill.relPath}: name must be kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$), got: '${name}'`);
+    }
+    // R5 — name matches the directory that owns the skill.
+    if (name !== skill.dirName) {
+      fail(`${skill.relPath}: name '${name}' does not match its directory '${skill.dirName}'`);
+    }
+  }
+
+  // R6 — description present and non-empty.
+  const description = frontmatter.description;
+  if (typeof description !== 'string' || description.trim() === '') {
+    fail(`${skill.relPath}: missing or empty required frontmatter field: description`);
+  }
+
+  return failed === before;
+}
+
+// ============================================================================
+// Check: skill frontmatter (SKILL.md)
+// ============================================================================
+console.log('--- Check: skill frontmatter (SKILL.md) ---');
+
+const skillsDir = join(pluginRoot, SKILLS_DIR_NAME);
+
+if (!existsSync(skillsDir)) {
+  fail(`skills directory not found at conventional location: ./${SKILLS_DIR_NAME}`);
+} else {
+  let skills;
+  try {
+    skills = collectSkillFiles(skillsDir);
+  } catch (error) {
+    skills = [];
+    fail(`skills directory is unreadable: ${error?.message ?? String(error)}`);
+  }
+
+  if (skills.length === 0) {
+    fail(`skills directory contains no ${SKILL_FILE} files`);
+  } else {
+    pass(`skills directory contains ${skills.length} ${SKILL_FILE} files`);
+
+    let valid = 0;
+    for (const skill of skills) {
+      if (validateSkillFrontmatter(skill)) valid++;
+    }
+
+    if (valid === skills.length) {
+      pass(`all ${skills.length} ${SKILL_FILE} frontmatter blocks parse as YAML and carry a kebab-case name matching their directory plus a non-empty description`);
+    }
+  }
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+
+process.exit(failed > 0 ? 1 : 0);