simt-dev 0.2.1 → 0.2.2

package/src/commands/tokens.mjs

@@ -0,0 +1,138 @@
+// simt-dev tokens - what a reader loads, counted.
+//
+// Review 0002 S38 put the estate's always-on context at 90 KB per turn, 72% of it a
+// paragraph an earlier root had already loaded, and could only say so by reading seven
+// repositories by hand. This command is that reading, and it is the figure plan 0003's
+// later slices are measured against: the context budget (S38 P7), the kernel split
+// (R07) and the workspace dedupe (R11) all need a number that moves when the
+// projection moves, or they are opinions.
+//
+// Three decisions keep the figure honest:
+//
+//   1. It is a READ. No write, no git object, no lock - the same ruling `compare`
+//      follows. An agent running this to orient itself must not be able to change what
+//      the next run will measure.
+//   2. It exits 0. A measurement is not a verdict: a repository over budget is a fact
+//      about the repository, and a command that went red for it would train people to
+//      ignore the number it exists to print. The only failure is being pointed at a
+//      directory that holds no repository to measure.
+//   3. It counts bytes and calls the tokens an approximation every time it prints one.
+//      See src/measure/context.mjs for what that costs and why.
+
+import { resolve } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { discover } from '../compare/discover.mjs';
+import { targetRoot } from '../workspace.mjs';
+import {
+  ALWAYS_ON_BUDGET_BYTES,
+  BYTES_PER_TOKEN,
+  annotate,
+  measureRoot,
+  mcpTools,
+  totals,
+} from '../measure/context.mjs';
+
+/** `1234567`, never `1,234,567`. `toLocaleString` output depends on the locale, and
+ *  this command exists so two machines produce two numbers a pull request can diff. */
+function plain(n) {
+  return String(n);
+}
+
+function files(n) {
+  return n === 1 ? '1 file' : `${plain(n)} files`;
+}
+
+export async function tokensCommand(positional, flags) {
+  // `targetRoot` owns the precedence, so `tokens`, `compare` and `upgrade` cannot
+  // disagree about which directory was named (ADR-014).
+  const target = await targetRoot(flags, positional);
+  const root = resolve(target.root);
+
+  const found = await discover(root);
+  if (flags.repos) {
+    if (found.error) {
+      return fail(`${root}: ${found.error}`, EXIT.CONFIG, 'pass --root <path>');
+    }
+    if (found.repos.length === 0) {
+      return fail(
+        `${root} contains no git repositories`,
+        EXIT.CONFIG,
+        `point --root at the directory holding the repositories, or at one repository without --repos`,
+      );
+    }
+    // `discover` sorts, and the order decides which root owns a shared paragraph. A
+    // second sort here would move duplicate bytes between roots and make the workspace
+    // figure irreproducible.
+  } else if (found.shape === 'workspace') {
+    return fail(
+      `${root} holds repositories rather than being one`,
+      EXIT.CONFIG,
+      `measure one with: ${CLI} tokens --root <path>, or every repository under it with: ${CLI} tokens --repos --root ${root}`,
+    );
+  }
+  const roots = flags.repos ? found.repos : [root];
+
+  const rows = [];
+  for (const path of roots) rows.push(await measureRoot(path));
+  annotate(rows);
+
+  const summary = totals(rows);
+  const mcp = mcpTools();
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'tokens',
+      root,
+      mode: flags.repos ? 'repositories' : 'repository',
+      source: target.source,
+      budget: { bytes: ALWAYS_ON_BUDGET_BYTES, bytesPerToken: BYTES_PER_TOKEN },
+      mcp,
+      roots: rows.map(({ documents, ...row }) => row),
+      totals: summary,
+    });
+    return EXIT.OK;
+  }
+
+  const lines = [];
+  if (flags.repos) {
+    lines.push(`tokens   ${root}  ${plain(summary.roots)} repositories  (${target.source})`);
+    for (const row of rows) {
+      const budget = row.budget.over ? `  over budget by ${plain(row.budget.overBy)} B` : '';
+      lines.push(
+        `${row.name}  generated ${plain(row.generatedBytes)} B  duplicate ${plain(row.redundancy.duplicateBytes)} B  unique ${plain(row.redundancy.uniqueBytes)} B${budget}`,
+      );
+      for (const finding of row.findings) lines.push(`note     ${row.name}: ${finding}`);
+    }
+    const share =
+      summary.generatedBytes === 0 ? 0 : Math.round((summary.duplicateBytes / summary.generatedBytes) * 100);
+    lines.push(
+      `totals   generated ${plain(summary.generatedBytes)} B  duplicate ${plain(summary.duplicateBytes)} B (${plain(share)}% of generated)  unique ${plain(summary.uniqueBytes)} B  repeat ${plain(summary.repeatBytes)} B  ~${plain(summary.tokens)} tokens`,
+    );
+  } else {
+    const row = rows[0];
+    lines.push(`tokens   ${row.path}`);
+    lines.push(`state    ${row.adoption}  surfaces ${row.surfaces.length === 0 ? '(AGENTS.md only)' : row.surfaces.join(', ')}`);
+    for (const channel of row.channels) {
+      lines.push(
+        `${channel.channel.padEnd(9)}${files(channel.files)}  ${plain(channel.generatedBytes)} B generated  ${plain(channel.readerBytes)} B read`,
+      );
+    }
+    const verdict = row.budget.over ? `over by ${plain(row.budget.overBy)} B` : 'within budget';
+    lines.push(
+      `always-on ${plain(row.generatedBytes)} B generated  ~${plain(row.generatedTokens)} tokens  budget ${plain(row.budget.bytes)} B  ${verdict}`,
+    );
+    lines.push(
+      `redundant ${plain(row.redundancy.duplicateBytes)} B repeats an earlier repository  ${plain(row.redundancy.repeatBytes)} B repeats an earlier document here  ${plain(row.redundancy.uniqueBytes)} B unique of ${plain(row.redundancy.blockBytes)} B counted in blocks`,
+    );
+    for (const finding of row.findings) lines.push(`note     ${finding}`);
+  }
+  lines.push(
+    `mcp      tools/list ${plain(mcp.bytes)} B of ${plain(mcp.tools)} tools  (the same for every repository, so it is not in any total)`,
+  );
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/compare/row.mjs

@@ -19,6 +19,7 @@
 import { checkTargets, PRIMARY_TARGET } from '../projection/project.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, wantsShim } from './hooksstate.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,8 +62,19 @@ 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 = [];
 
@@ -84,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
@@ -105,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,
@@ -119,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,
@@ -130,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),
@@ -163,6 +213,22 @@ 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
@@ -318,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/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;
+}

package/src/graph/speccheck.mjs

@@ -0,0 +1,68 @@
+// Walking the registry to the files on disk, so the conformance checker sees text.
+//
+// `graph lint` already resolves every skill to a path and measures it; this module does
+// the same walk for a different reason - it needs the bytes, not the count - and it is
+// separate rather than folded into that pass because one of the two questions may run
+// without the other.
+
+import { readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { checkSkill } from './spec.mjs';
+
+/**
+ * Check every skill the registry names against the Agent Skills specification.
+ *
+ * Only the canonical source is checked, because a skill with two bodies would give two
+ * answers to one question and the reader would have to know which is which. A skill
+ * whose body cannot be read is a warning and not an error: the registry pass already
+ * reports a path that does not exist as an error, and saying it twice with two exit
+ * paths is the "two commands, two answers" defect this repository exists to end.
+ *
+ * @param {{skills: object[]}} registry
+ * @param {string} workspaceRoot
+ * @returns {Promise<{errors: string[], warnings: string[], checked: number}>}
+ */
+export async function lintSpec(registry, workspaceRoot) {
+  const errors = [];
+  const warnings = [];
+  let checked = 0;
+
+  for (const skill of registry.skills ?? []) {
+    const source = (skill.sources ?? []).find((s) => s.role === 'canonical');
+    if (!source?.repo || !source?.path) continue;
+    const at = `${skill.name}: ${source.repo}/${source.path}`;
+    const full = join(workspaceRoot, source.repo, source.path);
+
+    let info;
+    try {
+      info = await stat(full);
+    } catch {
+      warnings.push(`${at}: the conformance pass could not read it; the registry pass above reports the path`);
+      continue;
+    }
+
+    // A skill directory holds its instructions in SKILL.md. A single file is the flat
+    // form ADR-009 says will be wrapped: it is still checked, because its frontmatter
+    // breaks the same rules, and the file name is reported as one of them.
+    const file = info.isDirectory() ? join(full, 'SKILL.md') : full;
+    let text;
+    try {
+      text = await readFile(file, 'utf8');
+    } catch {
+      warnings.push(`${at}: no SKILL.md in the directory, so there is nothing to check`);
+      continue;
+    }
+
+    const report = checkSkill({
+      directoryName: info.isDirectory() ? basename(full) : undefined,
+      fileName: basename(file),
+      text,
+      at,
+    });
+    errors.push(...report.errors);
+    warnings.push(...report.warnings);
+    checked += 1;
+  }
+  return { errors, warnings, checked };
+}

package/src/hooks/dispatcher.mjs

@@ -19,8 +19,8 @@
 //   its reason, so "passed" can never be mistaken for "only some of it passed".
 
 import { execFile } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 
 import { GATES } from './gates.mjs';
@@ -85,6 +85,12 @@ export async function runGates(event, { root, manifest }) {
   const staged = event === 'pre-commit' ? await stagedFiles(root) : [];
   const unstaged = event === 'pre-commit' ? await unstagedFiles(root) : new Set();
   const commands = manifest?.gates?.commands;
+  // `gates.cwd` is a separate map rather than a second shape for `gates.commands`.
+  // A monorepo needs the gate to run inside one package, and the reader declaring it
+  // already knows the gate by name — putting the directory beside the command would
+  // mean re-reading the command string to find out where anything runs, and a manifest
+  // written by an older release would have to be rewritten to gain the capability.
+  const cwds = manifest?.gates?.cwd ?? {};
   const results = [];
   // What the format gate rewrote, so restage touches those files and nothing else.
   let formatted = [];
@@ -147,7 +153,33 @@ export async function runGates(event, { root, manifest }) {
       formatted = targets;
     }
 
-    const outcome = await runGate(resolution, root);
+    // The gate's directory, if it declares one. Resolved against the repo root and
+    // checked for containment: a `cwd` that escaped the repository would run a command
+    // against files this commit cannot see, and the gate would be green about them.
+    // Containment is checked on the RESOLVED path, not the string, because `..` and a
+    // symlink both get past a prefix test on the text.
+    let cwd = root;
+    const declaredCwd = cwds[name];
+    if (declaredCwd !== undefined) {
+      const resolved = resolve(root, declaredCwd);
+      const inside = resolved === root || resolved.startsWith(`${root}${sep}`);
+      const exists = inside && (await stat(resolved).catch(() => null))?.isDirectory();
+      if (!exists) {
+        results.push({
+          name,
+          status: 'failed',
+          detail: inside
+            ? `gates.cwd["${name}"] is ${declaredCwd}, which is not a directory in this repository`
+            : `gates.cwd["${name}"] is ${declaredCwd}, which is outside the repository`,
+          remedy: `point gates.cwd["${name}"] at a directory in this repository, or remove it to run the gate at the root`,
+          adr: gate.adr,
+        });
+        continue;
+      }
+      cwd = resolved;
+    }
+
+    const outcome = await runGate(resolution, cwd);
     results.push({
       name,
       status: outcome.code === 0 ? 'passed' : 'failed',