simt-dev 0.2.0 → 0.2.2

package/src/compare/row.mjs

@@ -17,11 +17,12 @@
 // reordered its columns would make every comparison between two runs unreadable.
 
 import { checkTargets, PRIMARY_TARGET } from '../projection/project.mjs';
-import { readManifest } from '../projection/manifest.mjs';
+import { manifestDrift, readManifest } from '../projection/manifest.mjs';
 import { loadRules, select } from '../projection/rules.mjs';
+import { resolvePacks } from '../packs.mjs';
 import { knownGates } from '../hooks/resolve.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { readHooksState } from './hooksstate.mjs';
+import { readHooksState, wantsShim } from './hooksstate.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 
@@ -34,6 +35,10 @@ import { MANIFEST_FILE } from '../name.mjs';
  * @property {string[]} stack
  * @property {string[]} facts
  * @property {string[]} profiles  profile ids that would be selected
+ * @property {{path: string, profiles: string[], status: string, detail: string|null}[]} packages
+ *   one nested region per workspace package, sorted by path
+ * @property {{path: string, profiles: string[], status: string, detail: string|null}[]} packageProblems
+ *   the nested regions that are not `current`; empty for an unadopted repository
  * @property {string|null} pinnedSha
  * @property {string|null} recordedSha
  * @property {'current'|'drift'|'unmanaged'|'absent'|'malformed'} region
@@ -42,6 +47,8 @@ import { MANIFEST_FILE } from '../name.mjs';
  * @property {boolean} hooksComplete every event installed, executable, not stale
  * @property {string[]} gatesDeclared
  * @property {string[]} gateProblems
+* @property {{name: string, source: string|null, version: string|null, digest: string|null, ok: boolean}[]} packs
+*   the shared rule sets this repo declares, with the digest it has pinned for each
  * @property {string[]} problems     everything wrong, one line each; drives the exit code
  * @property {string[]} notes        worth knowing, but not wrong; does NOT drive the exit code
  */
@@ -55,15 +62,37 @@ import { MANIFEST_FILE } from '../name.mjs';
  * @param {{expectedSha: string, gates: Set<string>}} context
  * @returns {Promise<RepoRow>}
  */
-export async function buildRow(path, context) {
-  const name = path.split('/').filter(Boolean).pop() ?? path;
+/**
+ * A nested-region finding in the row's own vocabulary.
+ *
+ * `checkTargets` speaks in `file` because a finding is printed with the path it names;
+ * a row field is read by key, and a reader looking for `packages[].path` should not
+ * have to know that the finding underneath calls the same thing `file`. One mapper, so
+ * the two arrays cannot drift into different shapes.
+ */
+function packageEntry(f) {
+  return { path: f.file, profiles: f.profiles ?? [], status: f.status, detail: f.detail ?? null };
+}
+
+export async function buildRow(path, context) {  const name = path.split('/').filter(Boolean).pop() ?? path;
   const problems = [];
   const notes = [];
 
-  const [manifest, fp, hooks, findings] = await Promise.all([
-    readManifest(path),
+  // The manifest first, and on its own. The predicate below reads it, and a
+  // destructured binding in the same `Promise.all` array is still in its temporal dead
+  // zone when the array is evaluated - so this is the same defect ADR-045 records in
+  // this file one level up: a gate reading a field the line above has not set yet.
+  const manifest = await readManifest(path);
+
+  const [fp, hooks, findings] = await Promise.all([
     fingerprint(path),
-    readHooksState(path),
+    // The same predicate `hooks install` writes by. Without it this row defaulted to
+    // "a shim is wanted for every event", so a repository declaring only `prePush`
+    // gates was reported `hooksComplete: false` for the pre-commit shim it has no
+    // reason to write - and no number of runs of `hooks install` could clear it,
+    // because the command and the dashboard were answering different questions.
+    // Four estate repositories were in that state.
+    readHooksState(path, { declaresGate: (e) => wantsShim(manifest.manifest, manifest.exists, e) }),
     checkTargets(path),
   ]);
 
@@ -73,6 +102,12 @@ export async function buildRow(path, context) {
   // state a rule written to four surfaces can drift into.
   const region = findings.find((f) => f.file === PRIMARY_TARGET) ?? { status: 'absent' };
   const ruleFindings = findings.filter((f) => f.surface !== undefined);
+  // A nested region is identified by its path, not by a field: `checkTargets` builds
+  // those findings from `checkRegion`, which knows nothing about monorepos, and the
+  // one thing this row needs from them is "which file, what state".
+  const packageFindings = findings
+    .filter((f) => f.file !== undefined && f.file.endsWith(`/${PRIMARY_TARGET}`))
+    .sort((a, b) => (a.file < b.file ? -1 : 1));
   const pointers = findings.filter((f) => f.status?.startsWith('pointer'));
 
   // Adoption is settled BEFORE any problem is collected. Every gate below asks
@@ -94,6 +129,13 @@ export async function buildRow(path, context) {
   // prose above it was still true.
   const { selected: chosen } = select(await loadRules(path), fp.stack ?? [], fp.facts ?? []);
 
+  // The packs this repo shares with its siblings, with the digest it has pinned.
+  // A dashboard that reported `current: 14` while half their rules lived in a
+  // directory that was not there described an estate nobody had. The digest is
+  // the per-repo answer to "which bytes were these", which is what P4 asks for and
+  // what a reviewer comparing two repositories actually wants to see.
+  const { packs, findings: packFindings } = await resolvePacks(path);
+
   const row = {
     name,
     path,
@@ -108,6 +150,12 @@ export async function buildRow(path, context) {
     region: region.status,
     regionDetail: region.detail ?? null,
     surfaces: manifest.manifest?.surfaces ?? null,
+    // One entry per nested region, for the same reason `ruleFiles` is its own object:
+    // a monorepo can have a current root region and one stale package region, and a
+    // single `region` field cannot say which. Sorted by path, because `checkTargets`
+    // returns findings in the order the detector found packages and a dashboard that
+    // reorders rows between runs is a dashboard nobody diffs.
+    packages: packageFindings.map(packageEntry),
     ruleFiles: {
       total: ruleFindings.filter((f) => f.status !== 'orphaned').length,
       current: ruleFindings.filter((f) => f.status === 'current').length,
@@ -119,6 +167,19 @@ export async function buildRow(path, context) {
       orphaned: ruleFindings.filter((f) => f.status === 'orphaned').map((f) => f.file),
     },
     pointers: pointers.map((p) => ({ file: p.file, state: p.status })),
+    // A nested region that is not `current` is a problem for the same reason a stale
+    // rule file is: `check` exits 1 on it, and a row that reported the repository as
+    // current anyway is ADR-045's defect one level down. Gated on adoption, like every
+    // other gate here — an unadopted repo has no root region and therefore no nested
+    // findings to report, which is not a second defect for the same missing adoption.
+    packageProblems: adoption === 'adopted' ? packageFindings.filter((f) => f.status !== 'current').map(packageEntry) : [],
+    packs: packs.map((p) => ({
+      name: p.name,
+      source: p.source,
+      version: p.version,
+      digest: p.declared || null,
+      ok: p.ok,
+    })),
     hooksRouted: hooks.routed,
     hooksComplete: hooks.complete,
     gatesDeclared: declaredGates(manifest.manifest),
@@ -152,6 +213,40 @@ export async function buildRow(path, context) {
     problems.push(`${MANIFEST_FILE} ${manifest.error}`);
   }
 
+  // Stale nested regions, named by path, with the remedy the finding already carries.
+  // A monorepo with four packages and one drifted region must not report `current`.
+  for (const f of row.packageProblems) {
+    problems.push(`${f.path}: ${f.detail ?? 'the package region is not current'}; run: ${CLI} sync --yes`);
+  }
+
+  // `pack-unpinned` is a note here for the same reason it is non-blocking in
+  // `check`: the rules render, and only the record of which bytes they were is
+  // absent. A missing or mismatched pack is a problem, because that row would
+  // otherwise report a repository `current` while projecting fewer rules than the
+  // manifest declares - the defect ADR-045 was about, reached a different way.
+  for (const f of packFindings) {
+    if (f.status === 'pack-unpinned') notes.push(`${f.file}: ${f.detail}; ${f.remedy}`);
+    else problems.push(`${f.file}: ${f.detail}; ${f.remedy}`);
+  }
+
+  // A generated field of the manifest is stale, and `check` refuses on it. This row
+  // said the repository was `current` anyway, in all fourteen adopted repositories at
+  // once, so a dashboard that reported `current: 14, problems: 0` was describing a
+  // green estate on which every gate exited 1.
+  //
+  // ADR-045 went the other way: `compare` counted a defect it had been hiding. This is
+  // the same defect from the far side — a refusal the dashboard does not count — and
+  // the acceptance criterion in the review that owns this ("compare reports current:
+  // 14") was satisfiable while `check` exited 1 in every row it covered.
+  //
+  // `drift.remedy` verbatim, for both statuses. The remedy is the repair command, and
+  // two commands answering one question with different instructions is ADR-050's
+  // subject; if `check` changes its mind, this row changes with it for free.
+  if (adoption === 'adopted') {
+    const drift = await manifestDrift(path, row.stack, context.expectedSha);
+    if (drift) problems.push(`${drift.file}: ${drift.detail}; ${drift.remedy}`);
+  }
+
   // --- region --------------------------------------------------------------
   // Only meaningful for an adopted repo. An unmanaged repo has no manifest, so
   // its `absent` region is a consequence of not having adopted, not a second
@@ -289,6 +384,11 @@ export function summarise(rows, extra = {}) {
     malformed: count((r) => r.region === 'malformed'),
     hooksRouted: count((r) => r.hooksRouted),
     staleRuleFiles: rows.reduce((n, r) => n + (r.ruleFiles?.stale?.length ?? 0), 0),
+    // Counted here and not derived from `withProblems`: one monorepo with three drifted
+    // packages is one repository with three findings, and a reader asking "how much is
+    // stale" wants 3, not 1. `withProblems` still counts the repository once.
+    stalePackages: rows.reduce((n, r) => n + (r.packageProblems?.length ?? 0), 0),
+    packageRegions: rows.reduce((n, r) => n + (r.packages?.length ?? 0), 0),
     withProblems: count((r) => r.problems.length > 0),
     withOwnHooks: count((r) => (r.foreignHooks ?? []).length > 0),
     shas: [...shas.entries()].sort((a, b) => (a[0] === '(none)' ? 1 : b[0] === '(none)' ? -1 : b[1] - a[1])),

package/src/decisions/index.mjs

@@ -180,7 +180,7 @@ export function citations(text) {
  *
  * @returns {Promise<{ok: boolean, decisions: object[], errors: string[]}>}
  */
-export async function loadDecisions() {
+export async function loadDecisions({ all = false } = {}) {
   let names;
   try {
     names = (await readdir(DECISIONS_DIR)).filter((n) => /^ADR-\d{3}-.*\.md$/.test(n)).sort();
@@ -240,7 +240,7 @@ export async function loadDecisions() {
         (m) => `ADR-${m[1]}`,
       ),
       partial,
-      summary: summarise(text, partial),
+      summary: summarise(text, partial, { all }),
       bytes: Buffer.byteLength(text),
     });
   }
@@ -283,9 +283,12 @@ export function byId(decisions) {
  * @param {{ruling: number|null, kind: string, by: string|null}[]} partial the record's
  *   partial supersessions, so a ruling that is no longer in force can say so where it is
  *   printed rather than only in the status line above it
- * @returns {{ruled: string[], rulingNumbers: (number|null)[], rejected: string[], writtenAgainst: string[]}}
+ * @param {{all?: boolean}} [options] `all` keeps every ruling instead of the first two.
+ *   The cap exists for the common case, where a rule cites one record and two rulings
+ *   answer "why is this here"; the reader who needs the rest asks.
+ * @returns {{ruled: string[], rulingNumbers: (number|null)[], rulingCount: number, rejected: string[], writtenAgainst: string[]}}
  */
-function summarise(text, partial = []) {
+function summarise(text, partial = [], { all = false } = {}) {
   // A section ends at the next `## ` — but not at one inside a fenced code block.
 // ADR-007's entire ruling is a document skeleton in a fence whose headings are `##`,
 // so the old lookahead ended the section at the first line of the ruling itself. It
@@ -418,9 +421,21 @@ const section = (name) => {
   const ruled = units(section('Ruling') || section('Rulings'));
   const withLead = ruled.filter((p, i) => !p.text.endsWith(':') || i === ruled.length - 1);
 
-  const printed = withLead.slice(0, 2);
+  // Two by default, and every one of them on request. Fifty-five of the sixty records
+  // carry more than two rulings, so the default is an excerpt for almost every record —
+  // which is fine as a budget and wrong as a silence, and the count below says so.
+  //
+  // The full set is kept rather than discarded, because the command that names where the
+  // rest of it is has to be able to produce it. A remedy that cannot be followed is the
+  // defect this whole command exists to prevent, and the first version of this fix
+  // printed "the rest: simt rules show ADR-019", which exits 2: `rules show` takes a rule
+  // id. So `--all` is the command the excerpt points at, and this is what it reads.
+  const printed = all ? withLead : withLead.slice(0, 2);
   return {
     ruled: printed.map((p) => mark(sentence(redactCommand(p.text)), p.number)),
+    // How many rulings the record carries. Parallel to `ruled`: "two of eight" and "two"
+    // are different answers to the same question and only one of them is true.
+    rulingCount: withLead.length,
     // The number each printed ruling declares, parallel to `ruled`. It is the join
     // between a supersession and the text it applies to, so it is exported rather than
     // kept inside: a family that stopped numbering its rulings — `**One.**` losing the
@@ -493,7 +508,7 @@ export function redactEstate(text) {
  */
 const VERB = '(?:init|doctor|check|sync|upgrade|ci|compare|hooks|mcp|rules|skills|graph|--[a-z-]+)';
 
-export function redactCommand(text) {
+function redactCommand(text) {
   return String(text ?? '').replace(new RegExp(`\\bsimt-dev (?=${VERB})\\b`, 'g'), `${CLI} `);
 }
 

package/src/graph/load.mjs

@@ -15,15 +15,95 @@
 
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 
 import { KNOWN_TAGS } from '../resolve/fingerprint.mjs';
 import { matchesGlob, syntheticPathFor, tokenize } from '../resolve/resolve.mjs';
-import { resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
+import { PACKAGE_ROOT, resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
 
-const HERE = dirname(fileURLToPath(import.meta.url));
-export const REGISTRY_PATH = resolve(HERE, '..', '..', 'graph', 'skills.graph.json');
+/**
+ * The registry is workspace data (ADR-061): it describes which skill bodies a particular
+ * workspace holds, where they are, how big they are, and which tags separate the variants.
+ * It therefore lives in a MEMBER of the workspace, not in the workspace root - the root is
+ * the directory that CONTAINS the member repositories, and it holds no `graph/` of its own.
+ * An explicitly named path always wins over everything below.
+ */
+function defaultRegistryPath() {
+  return join(PACKAGE_ROOT, 'graph', 'skills.graph.json');
+}
+
+/**
+ * The registry to read when the reader names none, in order (ADR-061 ruling 3):
+ *
+ * 1. The package root, when it holds one. In this checkout that is how the tool finds its
+ *    own registry; in an installed package `graph` is not in the published `files`, so it
+ *    never does, and the reader falls through to 2 instead of being handed this workspace's
+ *    catalogue.
+ * 2. A member of the resolved workspace, when exactly one holds one: a tool installed from
+ *    node_modules or a formula resolves its workspace by configuration, and the member that
+ *    holds the registry is usually the tool's own checkout. More than one holding it is
+ *    ambiguity and the reader must pick; none is an honest absence, reported with the
+ *    workspace that was looked in.
+ *
+ * Every step is file existence plus the configured workspace, so the answer can be
+ * explained to whoever asks (determinism). `errors` empty means a path was found.
+ *
+ * @returns {Promise<{where: string|null, errors: string[], workspace: {root: string|null, source: string, detail: string}|null}>}
+ */
+async function defaultRegistry(flags) {
+  const own = defaultRegistryPath();
+  if (existsSync(own)) return { where: own, errors: [], workspace: null };
+
+  const ws = await workspace(flags);
+  const info = { root: ws.root, source: ws.source, detail: ws.detail };
+  const absent = `no skill registry at ${own}; create one there, or name it explicitly`;
+  if (ws.error) {
+    return { where: own, errors: [`${ws.detail}: ${ws.error}`, absent], workspace: info };
+  }
+  if (ws.root === null) {
+    return { where: own, errors: [absent], workspace: info };
+  }
+  if (!existsSync(ws.root)) {
+    return {
+      where: own,
+      errors: [`no skill registry: the configured workspace ${ws.root} (${ws.detail}) does not exist`],
+      workspace: info,
+    };
+  }
+
+  const members = [];
+  let entries;
+  try {
+    entries = await readdir(ws.root, { withFileTypes: true });
+  } catch {
+    entries = null;
+  }
+  for (const entry of entries ?? []) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    if (existsSync(join(ws.root, entry.name, 'graph', 'skills.graph.json'))) members.push(entry.name);
+  }
+
+  if (members.length === 1) {
+    return { where: join(ws.root, members[0], 'graph', 'skills.graph.json'), errors: [], workspace: info };
+  }
+  if (members.length > 1) {
+    return {
+      where: null,
+      errors: [
+        `ambiguous registry: ${members.length} members of workspace ${ws.root} each hold ` +
+          `graph/skills.graph.json (${members.join(', ')}); name one explicitly`,
+      ],
+      workspace: info,
+    };
+  }
+  return {
+    where: own,
+    errors: [
+      `no skill registry in workspace ${ws.root} (${ws.detail}); create one in a member, or name it explicitly`,
+    ],
+    workspace: info,
+  };
+}
 
 /**
  * Where sibling repos live. Sources are declared as `repo/path`, so resolving one
@@ -44,11 +124,6 @@ export function workspace(flags = {}) {
   return workspacePromise;
 }
 
-/** Test seam: forget the memoised workspace so the next call re-resolves. */
-export function resetWorkspace() {
-  workspacePromise = null;
-}
-
 const VALID_ROLES = new Set(['canonical', 'variant', 'stub', 'duplicate', 'deprecated']);
 
 /**
@@ -63,15 +138,47 @@ const VALID_ROLES = new Set(['canonical', 'variant', 'stub', 'duplicate', 'depre
  * @returns {Promise<{ok: boolean, registry: object|null, errors: string[], warnings: string[],
  *                    verified: boolean, workspace: {root: string|null, source: string, detail: string}>}
  */
-export async function loadRegistry(path = REGISTRY_PATH, flags = {}) {
+export async function loadRegistry(path = null, flags = {}) {
+  // An explicitly named path wins over the default (ADR-061). When none is given,
+  // `defaultRegistry` looks in the package root and then in the workspace's members; its
+  // errors are facts about ABSENCE - no registry here, or more than one and the reader must
+  // pick - and are reported as such. A named path that is missing is a different fact: the
+  // reader pointed at a file that is not there, and it names that path.
+  let where = path;
+  let resolveErrors = null;
+  let resolvedWorkspace = null;
+  if (path === null) {
+    const found = await defaultRegistry(flags);
+    where = found.where;
+    resolveErrors = found.errors;
+    resolvedWorkspace = found.workspace;
+  }
+
+  if (resolveErrors !== null && resolveErrors.length > 0) {
+    return {
+      ok: false,
+      registry: null,
+      path: where,
+      errors: resolveErrors,
+      warnings: [],
+      verified: false,
+      workspace: resolvedWorkspace ?? { root: null, source: 'none', detail: 'not resolved' },
+    };
+  }
+
   let registry;
   try {
-    registry = JSON.parse(await readFile(path, 'utf8'));
+    registry = JSON.parse(await readFile(where, 'utf8'));
   } catch (error) {
+    const message =
+      path === null && error.code === 'ENOENT'
+        ? `no skill registry at ${where}; create one there, or name it explicitly`
+        : `${where}: unreadable or invalid JSON (${error.message})`;
     return {
       ok: false,
       registry: null,
-      errors: [`${path}: unreadable or invalid JSON (${error.message})`],
+      path: where,
+      errors: [message],
       warnings: [],
       verified: false,
       workspace: { root: null, source: 'none', detail: 'not resolved' },
@@ -127,6 +234,7 @@ export async function loadRegistry(path = REGISTRY_PATH, flags = {}) {
   return {
     ok: errors.length === 0,
     registry,
+    path: where,
     errors,
     warnings,
     verified,
@@ -465,8 +573,11 @@ async function lintSourcesOnDisk(registry, workspaceRoot) {
         continue;
       }
       if (typeof source.bytes === 'number' && source.bytes !== measured.bytes) {
+        // The delta is computed here, not in `measureSkill`: that function measures
+        // one path and knows nothing about the declaration it is being compared with.
+        const delta = measured.bytes - source.bytes;
         errors.push(
-          `${at}: declared ${source.bytes} bytes, on disk ${measured.bytes} (${measured.delta > 0 ? '+' : ''}${measured.delta})`,
+          `${at}: declared ${source.bytes} bytes, on disk ${measured.bytes} (${delta > 0 ? '+' : ''}${delta})`,
         );
       }
       if (!source.bytes) warnings.push(`${at}: no declared bytes to compare against`);

package/src/graph/spec.mjs

@@ -0,0 +1,227 @@
+// Agent Skills conformance, checked against the specification.
+//
+// Every rule here was read from agentskills.io rather than recalled, for the reason
+// ADR-067 records: a lint that checks the wrong rule is worse than no lint, because it
+// reports a clean file that a client will reject.
+//
+// The distinction the file draws is the one the specification draws. A "must" is an error
+// and stops the exit code; a "should" or a recommendation is a warning and does not. An
+// error the reader cannot act on is a papercut that trains people to skip the gate, so
+// every message names the rule it broke and the fix.
+
+/** The one specification this knows, and the name `--spec` accepts. */
+export const SPEC = 'agentskills';
+
+export const SPEC_SOURCE = 'agentskills.io/specification';
+
+/** Fields the specification defines. Anything else in the frontmatter is unknown. */
+const SPEC_FIELDS = ['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools'];
+
+/** Tokens, not bytes, because the specification counts tokens and every number here is
+ *  the same four-bytes-per-token estimate the context meter uses. */
+const BODY_TOKEN_BUDGET = 5000;
+const BODY_LINE_BUDGET = 500;
+const BYTES_PER_TOKEN = 4;
+
+/** The `name` rules, as one predicate with the rule it enforces. */
+const NAME_RULES = {
+  max: 64,
+  // Lowercase alphanumerics and hyphens only. Unicode lowercase is deliberately NOT
+  // allowed even though the specification says "unicode lowercase alphanumeric": a
+  // skill directory travels between machines and shells, and the subset every client
+  // accepts is the ASCII one. Reported as the ASCII rule because that is the one a
+  // reader can fix without reading a Unicode table.
+  pattern: /^[a-z0-9-]+$/,
+};
+
+/**
+ * The first naming rule `name` breaks, or null when it breaks none.
+ *
+ * Exported because two commands need the same answer: the lint, which reports it, and
+ * `skills install`, which refuses to create a directory a client could never address by
+ * the name inside it. Two copies of these rules would be two sets, and the one nobody
+ * linted would be the one that let an unaddressable skill through.
+ *
+ * @param {string} name
+ * @returns {string|null} the rule, phrased as a defect
+ */
+export function nameProblems(name) {
+  if (name.length === 0) return 'is empty; the specification requires 1 to 64 characters';
+  if (name.length > NAME_RULES.max) {
+    return `is ${name.length} characters; the specification allows at most ${NAME_RULES.max}`;
+  }
+  if (!NAME_RULES.pattern.test(name)) return `is not lowercase letters, digits and hyphens`;
+  if (name.startsWith('-') || name.endsWith('-')) return `starts or ends with a hyphen`;
+  if (name.includes('--')) return `contains consecutive hyphens`;
+  return null;
+}
+
+/**
+ * Check one skill against the specification.
+ *
+ * @param {object} input
+ * @param {string} input.directoryName the directory the skill lives in
+ * @param {string} [input.fileName] the file the frontmatter came from
+ * @param {string} input.text the whole SKILL.md
+ * @param {string} input.at how the reader names this skill in a finding
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function checkSkill({ directoryName, fileName = 'SKILL.md', text, at }) {
+  const errors = [];
+  const warnings = [];
+  const fail = (detail) => errors.push(`${at}: ${detail}`);
+  const warn = (detail) => warnings.push(`${at}: ${detail}`);
+
+  if (fileName !== 'SKILL.md') {
+    // The layout is part of the specification, not a naming preference: a client looks
+    // for that file by name. ADR-009's flat `skills/<name>.md` form is the case here,
+    // and it is reported rather than accepted.
+    fail(`the specification requires the file to be named SKILL.md; this skill is a single ${fileName}`);
+  }
+
+  const { meta, body, present } = readFrontmatter(text);
+
+  // --- name -------------------------------------------------------------------
+  const name = meta.name ?? '';
+  if (name.length === 0) {
+    fail('frontmatter has no `name`, which the specification requires');
+  } else {
+    const broken = nameProblems(name);
+    if (broken !== null) fail(`name "${name}" ${broken}`);
+    // The rule the review did not list and the one that breaks installs: a directory
+    // and a name that disagree cannot both be addressed, and the client that resolves
+    // by name never finds the directory it was given.
+    if (directoryName !== undefined && name !== directoryName) {
+      fail(`name "${name}" does not match its directory "${directoryName}"; the specification requires them to be equal`);
+    }
+  }
+
+  // --- description ------------------------------------------------------------
+  const description = meta.description ?? '';
+  if (description.length === 0) {
+    fail('frontmatter has no `description`, which the specification requires');
+  } else if (description.length > 1024) {
+    fail(`description is ${description.length} characters; the specification allows at most 1024`);
+  } else if (description.length < 30) {
+    // A recommendation, not a rule: the specification asks for what the skill does and
+    // when to use it, and a client matching on keywords finds nothing in three words.
+    warn(`description is ${description.length} characters; it should say what the skill does AND when to use it`);
+  }
+
+  // --- compatibility ----------------------------------------------------------
+  const compatibility = meta.compatibility;
+  if (compatibility !== undefined && String(compatibility).length > 500) {
+    fail(`compatibility is ${String(compatibility).length} characters; the specification allows at most 500`);
+  }
+
+  // --- metadata ---------------------------------------------------------------
+  // Stated as a map from string keys to string values, but not as a hard requirement,
+  // so a value of another type is a warning. A client that reads it strictly will drop
+  // the field, and the reader deserves to know before a client does.
+  for (const [key, value] of Object.entries(meta.metadata ?? {})) {
+    if (typeof value !== 'string') {
+      warn(`metadata.${key} is ${typeof value}, not a string; the specification describes a map of string keys to string values`);
+    }
+  }
+
+  // --- unknown fields ---------------------------------------------------------
+  for (const key of present) {
+    if (!SPEC_FIELDS.includes(key)) {
+      warn(`frontmatter carries "${key}", which the specification does not define`);
+    }
+  }
+
+  // --- body -------------------------------------------------------------------
+  const bytes = Buffer.byteLength(text);
+  const tokens = Math.ceil(bytes / BYTES_PER_TOKEN);
+  if (tokens > BODY_TOKEN_BUDGET) {
+    warn(`body is ~${tokens} tokens (${bytes} bytes); the specification recommends under ${BODY_TOKEN_BUDGET}, with detail in reference files`);
+  }
+  const lines = body.split('\n').length;
+  if (lines > BODY_LINE_BUDGET) {
+    warn(`body is ${lines} lines; the specification recommends keeping SKILL.md under ${BODY_LINE_BUDGET}`);
+  }
+  // The three progressive-disclosure numbers, reported as one line so a reader sees
+  // the cost before the fix rather than one warning at a time.
+  if (tokens > BODY_TOKEN_BUDGET) {
+    const perHundred = Math.round(tokens / (lines / 100));
+    warn(`~${perHundred} tokens per 100 lines: the agent loads all of this once the skill activates, and reference files load only when asked`);
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Frontmatter as flat scalars, folded block scalars, plus a nested `metadata` map.
+ *
+ * Deliberately its own reader rather than the two that live in the projection: those
+ * strip the block and keep the values this file never looks at, and one of them would
+ * have to grow a block-scalar branch for a second caller.
+ *
+ * The block scalar is here because it is not optional: `description: >-` followed by
+ * indented lines is the spelling most real skills use for a long description, and a
+ * reader that took `>-` as the value reported a 200-character description as two
+ * characters. That is the whole failure this file exists to prevent, one level down - a
+ * lint that is confidently wrong about a conforming file.
+ */
+function readFrontmatter(text) {
+  const meta = {};
+  const present = [];
+  const body = text.replace(/^/, '');
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(body);
+  if (!match) return { meta, present, body };
+  const lines = match[1].split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^\s/.test(line)) continue; // Consumed by the block it belongs to, or metadata.
+    const field = /^([A-Za-z0-9_.-]+)\s*:\s*(.*)$/.exec(line);
+    if (!field) continue;
+    const [, key, raw] = field;
+    present.push(key);
+
+    const block = /^([|>])([-+]?)\s*$/.exec(raw.trim());
+    if (block !== null) {
+      const folded = block[1] === '>';
+      const collected = [];
+      while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || lines[i + 1].trim() === '')) {
+        const next = lines[i + 1];
+        if (next.trim() === '' && !/^\s/.test(next)) break;
+        collected.push(next.trim());
+        i += 1;
+        if (i + 1 >= lines.length) break;
+        if (!/^\s/.test(lines[i + 1]) && lines[i + 1].trim() !== '') break;
+      }
+      // A folded scalar joins its lines with spaces; a literal one keeps the newlines.
+      // Either way the blank lines a paragraph break introduced become a single space,
+      // because the count that matters here is characters, not layout.
+      meta[key] = collected.join(folded ? ' ' : '\n').replace(/\s+/g, folded ? ' ' : '\n').trim();
+      if (key === 'metadata') meta.metadata = {};
+      continue;
+    }
+
+    if (raw.trim() === '') {
+      meta[key] = '';
+      if (key === 'metadata') {
+        meta.metadata = {};
+        // An indented `key: value` block belongs to it.
+        while (i + 1 < lines.length && /^\s+/.test(lines[i + 1])) {
+          const nested = /^\s+([A-Za-z0-9_.-]+)\s*:\s*(.*)$/.exec(lines[i + 1]);
+          if (nested && key === 'metadata') meta.metadata[nested[1]] = scalar(nested[2]);
+          i += 1;
+        }
+      }
+      continue;
+    }
+    meta[key] = scalar(raw);
+  }
+  return { meta, present, body: body.slice(match[0].length) };
+}
+
+/** Strip the quoting and the trailing comment a scalar may carry. */
+function scalar(raw) {
+  const value = raw.trim().replace(/\s+#.*$/, '').trim();
+  if (value.startsWith('"') && value.endsWith('"')) return value.slice(1, -1);
+  if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+  return value;
+}