@bongos/core 1.19.525 → 1.19.527

package/scripts/gds/skill-lint.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// scripts/gds/skill-lint.js — lint SKILL.md frontmatter the way Claude Code's YAML parser reads it.
+//
+// Why (task 1003548): nine of this repo's fifty skills shipped with an unquoted
+// `description:` that contained ": " (e.g. "on it: (re)connect", "HARD RULE: never").
+// YAML reads a colon-space inside a plain scalar as a new mapping key and the whole
+// frontmatter fails to parse; Claude Code then loads the skill with EVERY field
+// dropped — the name falls back to the folder, the description to the body's first
+// line — and nothing warns. Nothing in CI caught it. This linter reproduces the
+// parser's failure modes without a YAML dependency, so it can run in fitness.js
+// (CI), as a PostToolUse hook on SKILL.md edits, and by hand.
+//
+// It also reports the context cost: the skill listing is budgeted at ~1% of the
+// context window, and a description is resident in EVERY session, so long ones
+// crowd the others out and get truncated (skill routing degrades).
+//
+// NOT A YAML PARSER, on purpose. These are targeted regex checks for the hazards that
+// actually bit us (a plain scalar carrying ": " or " #", an unclosed quote or flow
+// collection, a tab, a continuation line), so the repo gains a CI gate with no new
+// dependency. It can therefore under-report an exotic frontmatter shape. The reference
+// parser is `claude plugin validate .claude`, which uses Claude Code's own YAML reader —
+// run it when a file looks fine here but the skill still loads wrong, and treat its
+// verdict as authoritative over this one.
+//
+// Usage:
+//   node scripts/gds/skill-lint.js                 lint every .claude/skills/*/SKILL.md; exit 1 on any error
+//   node scripts/gds/skill-lint.js <file...>       lint specific files
+//   node scripts/gds/skill-lint.js --hook          PostToolUse mode: read the hook JSON on stdin, lint the
+//                                                  edited file if it is a SKILL.md, print findings, exit 0
+//   node scripts/gds/skill-lint.js --json          machine-readable
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DESC_WARN_CHARS = 400;      // longer than this and the listing entry is likely truncated
+const DESC_HARD_CHARS = 1024;     // Claude Code's own cap on a description
+const LISTING_BUDGET_CHARS = 8000; // ~2k tokens ≈ 1% of a 200k window (names + descriptions, all skills)
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// The YAML plain-scalar hazards that make the WHOLE frontmatter unparseable or
+// silently change a value. Each returns a message or null.
+const PLAIN_SCALAR_CHECKS = [
+  (v) => (/: /.test(v) || /:$/.test(v)) ? 'contains ": " (colon-space) — YAML reads it as a new key and the whole frontmatter fails to parse' : null,
+  (v) => / #/.test(v) ? 'contains " #" — YAML starts a comment there and silently truncates the value' : null,
+  (v) => (/^\[/.test(v) && !/\]$/.test(v)) || (/^\{/.test(v) && !/\}$/.test(v)) ? 'opens a flow sequence/map it never closes on the same line' : null,
+  (v) => /^[\]}>|*&!%@`,]/.test(v) ? `starts with "${v[0]}" — a YAML indicator; the value will not be read as text` : null,
+  (v) => /^-\s/.test(v) ? 'starts with "- " — YAML reads a list, not text' : null,
+];
+
+// Split the leading frontmatter block. Returns null when the file has none.
+function splitFrontmatter(text) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const lines = text.split(eol);
+  if (lines[0] !== '---') return null;
+  const end = lines.indexOf('---', 1);
+  if (end < 0) return null;
+  return { lines: lines.slice(1, end), bodyStart: end + 1, eol };
+}
+
+// Lint one frontmatter block (array of lines). Returns { errors, warnings, fields }.
+// `fields` holds each top-level key's raw value; block scalars are joined.
+function lintFrontmatter(lines) {
+  const errors = [], warnings = [], fields = {};
+  let cur = null, curKind = null; // curKind: 'plain' | 'block' | 'quoted'
+  lines.forEach((ln, i) => {
+    const n = i + 2; // 1-based line number in the file (line 1 is the opening ---)
+    if (!ln.trim()) return;
+    if (/^\t/.test(ln)) { errors.push(`line ${n}: tab indentation — YAML forbids tabs`); return; }
+    const kv = /^([A-Za-z0-9_-]+):(?:\s+(.*))?$/.exec(ln);
+    if (kv && !/^\s/.test(ln)) {
+      cur = kv[1];
+      const v = (kv[2] || '').trim();
+      if (fields[cur] !== undefined) errors.push(`line ${n}: duplicate key "${cur}"`);
+      if (v === '' ) { fields[cur] = ''; curKind = 'nested'; return; }
+      if (/^[>|][+-]?\d*$/.test(v)) { fields[cur] = ''; curKind = 'block'; return; }
+      if (/^(["']).*\1$/.test(v)) { fields[cur] = v.slice(1, -1); curKind = 'quoted'; return; }
+      if (/^["']/.test(v)) { errors.push(`line ${n}: "${cur}" opens a quote it never closes on the same line`); fields[cur] = v; curKind = 'plain'; return; }
+      curKind = 'plain'; fields[cur] = v;
+      for (const chk of PLAIN_SCALAR_CHECKS) { const m = chk(v); if (m) { errors.push(`line ${n}: "${cur}" ${m}. Fix: write it as a block scalar — "${cur}: >-" then the text indented two spaces`); break; } }
+      return;
+    }
+    if (/^\s+\S/.test(ln)) {
+      if (!cur) { errors.push(`line ${n}: indented text before any key`); return; }
+      if (curKind === 'block' || curKind === 'nested') { fields[cur] = (fields[cur] ? fields[cur] + ' ' : '') + ln.trim(); return; }
+      errors.push(`line ${n}: continuation under "${cur}" — a plain value cannot span lines; use "${cur}: >-" with the text indented`);
+      return;
+    }
+    errors.push(`line ${n}: not "key: value" — "${ln.slice(0, 60)}"`);
+  });
+  return { errors, warnings, fields };
+}
+
+// Lint one SKILL.md file's text. `file` is used for the name check and messages.
+function lintSkillFile(text, { file = 'SKILL.md' } = {}) {
+  const dirName = path.basename(path.dirname(file));
+  const fm = splitFrontmatter(text);
+  const res = { file, errors: [], warnings: [], name: null, description: '', listingChars: 0 };
+  if (!fm) { res.errors.push('no YAML frontmatter (the file must start with --- and carry name + description)'); return res; }
+  const { errors, warnings, fields } = lintFrontmatter(fm.lines);
+  res.errors.push(...errors); res.warnings.push(...warnings);
+  const name = fields.name || '', desc = fields.description || '';
+  if (!name) res.errors.push('missing "name"');
+  else if (name !== dirName && dirName !== 'SKILL.md') res.warnings.push(`name "${name}" differs from its folder "${dirName}" — the folder name wins in listings`);
+  if (!desc) res.errors.push('missing or empty "description" — the skill would match on its body text');
+  if (desc.length > DESC_HARD_CHARS) res.errors.push(`description is ${desc.length} chars — over Claude Code's ${DESC_HARD_CHARS}-char cap`);
+  else if (desc.length > DESC_WARN_CHARS) res.warnings.push(`description is ${desc.length} chars — over the ~${DESC_WARN_CHARS} we aim for; every char is resident in every session`);
+  res.name = name || dirName; res.description = desc; res.listingChars = res.name.length + desc.length;
+  return res;
+}
+
+// Every SKILL.md under .claude/skills/ (one level deep).
+function listSkillFiles(root = REPO_ROOT) {
+  const dir = path.join(root, '.claude', 'skills');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => path.join(dir, d.name, 'SKILL.md'))
+    .filter((f) => fs.existsSync(f));
+}
+
+// Lint a set of files; returns per-file results plus the listing total vs budget.
+function lintSkills(files) {
+  const results = files.map((f) => lintSkillFile(fs.readFileSync(f, 'utf8'), { file: f }));
+  const listingChars = results.reduce((a, r) => a + r.listingChars, 0);
+  return { results, listingChars, budgetChars: LISTING_BUDGET_CHARS, overBudget: listingChars > LISTING_BUDGET_CHARS };
+}
+
+function isSkillMd(p) { return /[\\/]\.claude[\\/]skills[\\/][^\\/]+[\\/]SKILL\.md$/.test(String(p || '')); }
+
+function format(report, { relTo = REPO_ROOT } = {}) {
+  const out = [];
+  for (const r of report.results) {
+    const rel = path.relative(relTo, r.file).replace(/\\/g, '/');
+    for (const e of r.errors) out.push(`✗ ${rel}: ${e}`);
+    for (const w of r.warnings) out.push(`! ${rel}: ${w}`);
+  }
+  const errs = report.results.reduce((a, r) => a + r.errors.length, 0);
+  const warns = report.results.reduce((a, r) => a + r.warnings.length, 0);
+  out.push(`skill-lint: ${report.results.length} skill(s), ${errs} error(s), ${warns} warning(s); listing ${report.listingChars} chars (~${Math.round(report.listingChars / 4)} tokens) vs ~${report.budgetChars}-char budget${report.overBudget ? ' — OVER: entries get truncated and routing degrades' : ''}`);
+  return out.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  if (argv.includes('--hook')) {
+    // PostToolUse: stdin carries {tool_input:{file_path}}. Only speak when a SKILL.md was touched.
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => { raw += d; });
+    process.stdin.on('end', () => {
+      try {
+        const j = JSON.parse(raw || '{}');
+        const fp = (j.tool_input && (j.tool_input.file_path || j.tool_input.path)) || '';
+        if (!isSkillMd(fp) || !fs.existsSync(fp)) return;
+        const report = lintSkills([fp]);
+        const r = report.results[0];
+        if (r.errors.length || r.warnings.length) console.log('[skill-lint] ' + format(report).split('\n').slice(0, -1).join('\n[skill-lint] '));
+      } catch (_) { /* a hook never breaks the edit */ }
+      process.exitCode = 0;
+    });
+    return;
+  }
+  const files = argv.filter((a) => !a.startsWith('--'));
+  const report = lintSkills(files.length ? files.map((f) => path.resolve(f)) : listSkillFiles());
+  if (json) console.log(JSON.stringify(report, null, 1)); else console.log(format(report));
+  process.exitCode = report.results.some((r) => r.errors.length) ? 1 : 0;
+}
+
+module.exports = { lintFrontmatter, lintSkillFile, lintSkills, listSkillFiles, splitFrontmatter, isSkillMd, format, DESC_WARN_CHARS, DESC_HARD_CHARS, LISTING_BUDGET_CHARS };
+if (require.main === module) main();

package/scripts/gds/strand-watch.js

@@ -202,6 +202,9 @@ function line(r, { max = 3 } = {}) {
   }[worst.shape] || 'parked mid-pipeline';
   return `Stranded ship${r.strands.length === 1 ? '' : 's'}: ${shown.join('; ')}${more}. `
     + `Worst: ${lead} — ${worst.remedy}. `
+    // Name the skill, not just the diagnosis: 19 of the last 30 days' session logs mention a strand,
+    // and the next claim is refused REBASE_REQUIRED until one is landed or released (task 1003548).
+    + `Run /strand-fix ${worst.id} to walk it. `
     + 'A strand produces no signal of its own; this line is the only one.';
 }
 

package/src/module-api.js

@@ -45,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.525'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.527'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/claude_materialize.mjs

@@ -49,6 +49,16 @@ t('bongosify: $CLAUDE_PROJECT_DIR + surrounding quotes are stripped', () => {
   assert.equal(m.bongosify('node "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"'), 'bongos exec scripts/gds/session-cost.js');
 });
 
+t('bongosify: the run-node.sh resolver form (task 1003548) collapses to the same bongos form', () => {
+  const wrap = 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"';
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"`), 'bongos exec scripts/gds/session-cost.js');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/deploy-divergence.js" --line --timeout-ms 2500`), 'bongos exec scripts/gds/deploy-divergence.js --line --timeout-ms 2500');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/ship.js" 1885`), 'bongos ship 1885');
+  // …and a resolver call whose target is a .claude/hooks/*.js stays instance-local, like the bare-node form.
+  const hook = `${wrap} "$CLAUDE_PROJECT_DIR/.claude/hooks/secret-gate.js"`;
+  assert.equal(m.bongosify(hook), hook);
+});
+
 t('bongosify: a .claude/hooks/ reference is LEFT untouched (instance-local after materialize)', () => {
   const cmd = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.js"';
   assert.equal(m.bongosify(cmd), cmd);

package/tests/edit_hints.mjs

@@ -0,0 +1,78 @@
+// tests/edit_hints.mjs — the PostToolUse edit-hints hook maps an edited path to the generator it makes
+// stale, reconciles the path shapes Windows hosts hand it, and stays silent on everything else
+// (task 1003548; evidence: a stale generated file in ~a quarter of the last 30 days' sessions).
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HOOK = path.join(ROOT, '.claude', 'hooks', 'edit-hints.js');
+if (!fs.existsSync(HOOK)) {
+  console.log('edit_hints: SKIP — .claude/hooks/ is not materialized in this checkout (package-excluded).');
+  process.exit(0);
+}
+const hints = require(HOOK);
+
+test('each generator input maps to its generator; unrelated paths map to nothing', () => {
+  const cases = [
+    ['modules/hall-ui/public/people.js', 'copy-inventory.js'],
+    ['modules/status-ui/public/index.html', 'copy-inventory.js'],
+    ['src/bongos/auth.js', 'gen-repo-map.js'],
+    ['modules/lifecycle/routes/claims.js', 'gen-api-docs.js'],
+    ['.claude/skills/dev/SKILL.md', 'gen-file-map.js'],
+    ['docs/session-logs/2026-09-03-x.md', 'gen-session-index.js'],
+    ['docs/adr/0236-something.md', 'fitness.js'],
+  ];
+  for (const [p, gen] of cases) {
+    const h = hints.generatorHint(p);
+    assert.ok(h && h.includes(gen), `${p} → expected ${gen}, got ${h}`);
+  }
+  for (const p of ['README.md', 'tests/foo.mjs', 'modules/hall-ui/CLAUDE.md', 'scripts/gds/ship.js']) {
+    assert.equal(hints.generatorHint(p), null, `${p} should be silent`);
+  }
+});
+
+test('rel() reconciles C:\\, C:/ and /c/ shapes between CLAUDE_PROJECT_DIR and file_path', () => {
+  const want = 'modules/hall-ui/public/people.js';
+  assert.equal(hints.rel('C:\\r\\repo\\modules\\hall-ui\\public\\people.js', 'C:\\r\\repo'), want);
+  assert.equal(hints.rel('C:\\r\\repo\\modules\\hall-ui\\public\\people.js', 'C:/r/repo'), want);
+  assert.equal(hints.rel('/c/r/repo/modules/hall-ui/public/people.js', 'C:\\r\\repo'), want);
+  assert.equal(hints.rel('c:/r/repo/modules/hall-ui/public/people.js', 'C:/r/repo/'), want);
+  assert.equal(hints.rel('/home/u/repo/modules/hall-ui/public/people.js', '/home/u/repo'), want);
+});
+
+test('run as a hook: prints one hint for a generator input, nothing for an unrelated file, exit 0 both times', () => {
+  const projectDir = ROOT;
+  const run = (relPath) => spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify({ tool_input: { file_path: path.join(projectDir, ...relPath.split('/')) } }),
+    encoding: 'utf8', timeout: 15000, env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir },
+  });
+  const a = run('modules/hall-ui/public/people.js');
+  assert.equal(a.status, 0, a.stderr);
+  assert.match(a.stdout, /copy-registry\.json is now stale/);
+  assert.match(a.stdout, /copy-inventory\.js/);
+  const b = run('README.md');
+  assert.equal(b.status, 0, b.stderr);
+  assert.equal(b.stdout.trim(), '');
+});
+
+test('run as a hook on a SKILL.md with a broken description: names the line and the fix', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'edit-hints-'));
+  const skill = path.join(tmp, '.claude', 'skills', 'demo', 'SKILL.md');
+  fs.mkdirSync(path.dirname(skill), { recursive: true });
+  fs.writeFileSync(skill, '---\nname: demo\ndescription: Do it: now\n---\nBody\n');
+  const r = spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify({ tool_input: { file_path: skill } }),
+    encoding: 'utf8', timeout: 15000, env: { ...process.env, CLAUDE_PROJECT_DIR: ROOT },
+  });
+  fs.rmSync(tmp, { recursive: true, force: true });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /\[skill-lint\] ✗ .*line 3/);
+  assert.match(r.stdout, /description: >-/);
+});

package/tests/git_merge_regen.mjs

@@ -64,7 +64,7 @@ const MARKERS = /^(<{7}|={7}|>{7})/m;
 }
 
 // ── helpers to build nested-CLAUDE.md fixtures from the real committed file ─────
-const NESTED = 'scripts/gds/CLAUDE.md';
+const NESTED = 'src/bongos/CLAUDE.md'; // scripts/gds left NESTED_DIRS in task 1003548
 const realNested = fs.readFileSync(path.join(repo, NESTED), 'utf8');
 assert.ok(realNested.includes(G.BEGIN) && realNested.includes(G.END), 'fixture file must carry the generated block markers');
 // Replace the INNER block text (keep the BEGIN/END marker lines intact).

package/tests/hooks_drain.mjs

@@ -20,7 +20,13 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const HOOKS = ['recall-hints', 'rank-change-greeting', 'conductor'].map((n) => path.join(ROOT, '.claude', 'hooks', `${n}.js`));
+const HOOKS = ['recall-hints', 'rank-change-greeting', 'conductor', 'pull-memory', 'edit-hints'].map((n) => path.join(ROOT, '.claude', 'hooks', `${n}.js`));
+// The SessionStart/SessionEnd scripts that did network work and then process.exit()ed — 59 recorded
+// UV_HANDLE_CLOSING aborts in three days (task 1003548). Same contract: exit 0 on their own, no abort.
+// session-digest requires `pg` at load (via db-kernel), so it can only be exercised where node_modules
+// is installed — the CI lane; a bare Windows worktree skips it rather than reporting a phantom fail.
+const hasPg = fs.existsSync(path.join(ROOT, 'node_modules', 'pg'));
+const SCRIPTS = ['fetch-sound-prefs', 'session-cost', ...(hasPg ? ['session-digest'] : [])].map((n) => path.join(ROOT, 'scripts', 'gds', `${n}.js`));
 
 if (!HOOKS.every((p) => fs.existsSync(p))) {
   console.log('hooks_drain: SKIP — .claude/hooks/ is not materialized in this checkout (package-excluded).');
@@ -42,7 +48,7 @@ const payload = JSON.stringify({ session_id: 's1', transcript_path: transcript,
 const env = { ...process.env, HOME, USERPROFILE: HOME, CLAUDE_PROJECT_DIR: ROOT };
 for (const k of Object.keys(env)) if (/_API_BASE$|^OTB_|^CLOUDBONGOS_|^GDS_|^PMS_/.test(k)) delete env[k];
 
-for (const hook of HOOKS) {
+for (const hook of [...HOOKS, ...SCRIPTS]) {
   t(`${path.basename(hook)} exits on its own with 0 and no libuv abort (x3)`, () => {
     for (let i = 0; i < 3; i++) {
       const r = spawnSync(process.execPath, [hook], { input: payload, encoding: 'utf8', timeout: 15000, env });

package/tests/repo_map.mjs

@@ -67,7 +67,7 @@ test('the generated repo map has the ranked global table and real signatures', (
 test('each nested CLAUDE.md carries a delimited generated block with signatures', () => {
   const BEGIN = '<!-- BEGIN GENERATED REPO-MAP';
   const END = '<!-- END GENERATED REPO-MAP -->';
-  for (const dir of ['src/bongos', 'src/bongos/routes', 'scripts/gds']) {
+  for (const dir of ['src/bongos', 'src/bongos/routes']) { // scripts/gds left NESTED_DIRS in task 1003548
     const doc = readFileSync(path.join(ROOT, dir, 'CLAUDE.md'), 'utf8');
     assert.ok(doc.includes(BEGIN), `${dir}/CLAUDE.md should have a generated-block start marker`);
     assert.ok(doc.includes(END), `${dir}/CLAUDE.md should have a generated-block end marker`);

package/tests/skill_lint.mjs

@@ -0,0 +1,73 @@
+// tests/skill_lint.mjs — the SKILL.md frontmatter linter reproduces the YAML failure modes that
+// silently broke ten skills (task 1003548), and the committed skills all pass it.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lint = require('../scripts/gds/skill-lint.js');
+
+const fm = (desc, extra = '') => `---\nname: demo\ndescription: ${desc}\n${extra}---\n\nBody text.\n`;
+const run = (text) => lint.lintSkillFile(text, { file: path.join('x', '.claude', 'skills', 'demo', 'SKILL.md') });
+
+test('a plain description containing ": " is an error (the whole frontmatter would fail to parse)', () => {
+  const r = run(fm('Show the box and help them get on it: reconnect or wake.'));
+  assert.equal(r.errors.length, 1, r.errors.join('; '));
+  assert.match(r.errors[0], /colon-space/);
+  assert.match(r.errors[0], /description: >-/, 'the message carries the fix');
+});
+
+test('a plain description containing " #" is an error (YAML would truncate it as a comment)', () => {
+  const r = run(fm('Connect the box (ADR 0031, #701) and open the terminal.'));
+  assert.equal(r.errors.length, 1);
+  assert.match(r.errors[0], / #/);
+});
+
+test('the same text as a folded block scalar is clean', () => {
+  const r = run('---\nname: demo\ndescription: >-\n  Show the box and help them get on it: reconnect (ADR 0031, #701) or wake.\n---\n\nBody.\n');
+  assert.deepEqual(r.errors, []);
+  assert.match(r.description, /reconnect \(ADR 0031, #701\)/);
+});
+
+test('a double-quoted description is clean; an unclosed quote is an error', () => {
+  assert.deepEqual(run(fm('"Do it: now"')).errors, []);
+  assert.equal(run(fm('"Do it: now')).errors.length, 1);
+});
+
+test('a flow list in requires is valid YAML and not flagged', () => {
+  const r = run(fm('Fine text.', 'requires: [gh, main-checkout]\n'));
+  assert.deepEqual(r.errors, []);
+});
+
+test('missing name or description is an error; a folder/name mismatch is a warning', () => {
+  assert.match(run('---\nname: demo\n---\nBody\n').errors.join(' '), /missing or empty "description"/);
+  assert.match(run('---\ndescription: x\n---\nBody\n').errors.join(' '), /missing "name"/);
+  const r = lint.lintSkillFile('---\nname: other\ndescription: x\n---\nBody\n', { file: path.join('x', '.claude', 'skills', 'demo', 'SKILL.md') });
+  assert.match(r.warnings.join(' '), /differs from its folder/);
+});
+
+test('a long description warns; an over-cap one errors', () => {
+  assert.equal(run(fm('a'.repeat(450))).warnings.filter((w) => /chars/.test(w)).length, 1);
+  assert.equal(run(fm('a'.repeat(1100))).errors.filter((w) => /cap/.test(w)).length, 1);
+});
+
+test('no frontmatter at all is an error', () => {
+  assert.equal(run('# Title\n\nBody.\n').errors.length, 1);
+});
+
+test('the hook path filter matches only .claude/skills/<name>/SKILL.md', () => {
+  assert.ok(lint.isSkillMd('C:\\repo\\.claude\\skills\\dev\\SKILL.md'));
+  assert.ok(lint.isSkillMd('/repo/.claude/skills/dev/SKILL.md'));
+  assert.ok(!lint.isSkillMd('/repo/.claude/skills/dev/notes.md'));
+  assert.ok(!lint.isSkillMd('/repo/modules/ui-design/skills/dev/SKILL.md'));
+});
+
+test('every committed skill parses (the ten that did not on 2026-09-03 must stay fixed)', () => {
+  const report = lint.lintSkills(lint.listSkillFiles(ROOT));
+  const broken = report.results.filter((r) => r.errors.length).map((r) => path.relative(ROOT, r.file) + ': ' + r.errors.join('; '));
+  assert.deepEqual(broken, [], broken.join('\n'));
+  assert.ok(report.results.length >= 40, 'the repo ships dozens of skills; the lister found ' + report.results.length);
+});