simt-dev 0.2.1 → 0.3.0

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',

package/src/kernel/card.mjs

@@ -0,0 +1,254 @@
+// The command card: the exact commands for THIS repository, at the top of the
+// projected region (plan 0003 R10).
+//
+// The card holds the bytes a reader cannot infer. "Run the tests" is useless advice in a
+// repository whose test command is `./gradlew :app:testDebugUnitTest`; the runner, the
+// wrapper and the task name are facts about this repository, and none of them are in the
+// rules, which are the same in every repository. So the card is derived rather than
+// written: from the manifest's declared gates, the repository's own `package.json`
+// scripts, and the marker files that name its ecosystem.
+//
+// It reads committed evidence ONLY. It must never consult PATH or `node_modules`, because
+// the projected region is required to be byte-identical on two machines (plan 0003 P4,
+// R13) and a card that named whichever linter happened to be installed would differ
+// between a laptop and CI for no reason a diff could explain. Runnability is a property
+// of the machine; a command is a property of the repository.
+//
+// The focused-test entries are TEMPLATES. `{file}`, `{pkg}`, `{Test}` and `{class}` are
+// placeholders the reader fills from the file they are editing, and the label names the
+// path kind so a template is never mistaken for a command that can be pasted as-is.
+// Refining which test a given `{file}` maps to is R24's job, not R10's.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { ECOSYSTEMS } from '../projection/manifest.mjs';
+
+/**
+ * The card's ceiling in bytes (plan 0003 R10). Over it, the least valuable lines are
+ * dropped rather than the ceiling raised: the point of the card is the bytes a reader
+ * most needs, and an unbounded card is a second copy of the rules.
+ */
+export const CARD_LIMIT_BYTES = 600;
+
+/**
+ * The verbs the card carries, in the order a reader meets them. The plan names exactly
+ * these five. A `build` command exists only where a repository declares one, so the order
+ * is a priority as well as a sequence: the most universally true verb comes first.
+ *
+ * Exported because a second reader has to agree with it: a rule may declare `card:<verb>`
+ * as the evidence that makes its line redundant (R09), and a copy of this list living in
+ * the filter would let the card name a verb the filter called unknown.
+ */
+export const CARD_VERBS = ['build', 'test', 'lint', 'format', 'typecheck'];
+
+const VERBS = CARD_VERBS;
+
+/**
+ * The order verbs are dropped in when the card is over its ceiling: the verb whose loss a
+ * reader misses least goes first. `test` is absent on purpose — a card that dropped the
+ * test command would have dropped the one command it exists to carry.
+ */
+const DROP_ORDER = ['format', 'typecheck', 'lint', 'build'];
+
+/**
+ * Build commands for ecosystems whose build entrypoint is not a package script. Keyed by
+ * a marker fact or stack tag, whichever the ecosystem is identified by. `npm` is handled
+ * before this table, because a Node repository states its own build script and stating it
+ * again here would be a second answer to the same question.
+ */
+const BUILDS = [
+  { fact: 'has-cargo-toml', command: 'cargo build' },
+  { fact: 'has-go-mod', command: 'go build ./...' },
+  { fact: 'has-nuget', command: 'dotnet build' },
+  { fact: 'has-swift-package', command: 'swift build' },
+  { fact: 'has-mix', command: 'mix compile' },
+  { stack: 'gradle', command: './gradlew build' },
+];
+
+/**
+ * One focused-test template per path kind. Entries are ordered, and the FIRST match wins,
+ * so a repository that carries more than one marker gets the more specific template:
+ * `has-uv-lock` before `has-pyproject`, `has-android-manifest` before the plain `gradle`
+ * tag, `has-deno-config` before the Node fallback. A duplicate template for the same path
+ * kind would be two answers, and the second is the wrong one.
+ */
+const FOCUSED = [
+  { kind: 'Android', when: (s, f) => f.has('has-android-manifest'), template: () => './gradlew :{module}:testDebugUnitTest --tests {class}' },
+  { kind: 'JVM', when: (s) => s.has('gradle'), template: () => './gradlew test --tests {class}' },
+  { kind: 'Maven', when: (s, f) => f.has('has-maven-pom'), template: () => './mvnw test -Dtest={class}' },
+  { kind: 'Go package', when: (s, f) => f.has('has-go-mod'), template: () => 'go test ./{pkg} -run {Test}' },
+  { kind: 'Rust', when: (s, f) => f.has('has-cargo-toml'), template: () => 'cargo test {name}' },
+  { kind: 'Python', when: (s, f) => f.has('has-uv-lock'), template: () => 'uv run -m pytest {file}::{test}' },
+  { kind: 'Python', when: (s, f) => f.has('has-pyproject') || f.has('has-requirements'), template: () => 'pytest {file}::{test}' },
+  { kind: '.NET', when: (s, f) => f.has('has-nuget'), template: () => 'dotnet test --filter {test}' },
+  { kind: 'Swift', when: (s, f) => f.has('has-swift-package'), template: () => 'swift test --filter {test}' },
+  { kind: 'Deno', when: (s, f) => f.has('has-deno-config'), template: () => 'deno test {file}' },
+  { kind: 'Ruby', when: (s, f) => f.has('has-gemfile'), template: () => 'bundle exec rspec {file}' },
+  { kind: 'Dart', when: (s, f) => f.has('has-pubspec'), template: () => 'dart test {file}' },
+  { kind: 'Elixir', when: (s, f) => f.has('has-mix'), template: () => 'mix test {file}' },
+  {
+    kind: 'Node',
+    when: (s) => s.has('node'),
+    // The repo's own runner decides the shape. A repository whose test script is vitest
+    // or jest takes a file argument through the script; one with no such script gets the
+    // built-in runner, which is the only answer that needs nothing installed to already
+    // be true. `npm test -- <file>` is the ADR-010 shape (never `npx`).
+    template: (s, f, scripts) => {
+      const test = scripts?.test ?? '';
+      return /vitest|jest/.test(test) ? 'npm test -- {file}' : 'node --test {file}';
+    },
+  },
+];
+
+/**
+ * Verbs for ecosystems the gate table does not seed, used by the card alone.
+ *
+ * Python is the case, and it is not an oversight that the tool seeds no Python gate: the
+ * runner genuinely varies (uv, poetry, tox, nox, a project wrapper), so a seeded gate would
+ * be wrong in the repositories it guessed about. The card can still name the one command a
+ * repository has proved: a committed `uv.lock` means uv, and the uv profile is explicit
+ * that `uv run -m pytest` is correct and `uv run pytest` is not — the console entrypoint
+ * can miss the `uv` import path and run a different copy of the package than the one under
+ * test. Without a lockfile the card names the plain runner, which is what the python
+ * profile assumes when it says "no `pytest.skip`".
+ */
+const CARD_FALLBACKS = [
+  { when: (s, f) => f.has('has-uv-lock'), commands: { test: 'uv run -m pytest' } },
+  { when: (s, f) => f.has('has-pyproject') || f.has('has-requirements'), commands: { test: 'pytest' } },
+];
+
+/** A non-empty string, or null. Guards JSON that is present but not a command. */
+function text(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}
+
+/** The repository's own `package.json` scripts, or an empty map. */
+async function readScripts(root) {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    return pkg && typeof pkg.scripts === 'object' && pkg.scripts ? pkg.scripts : {};
+  } catch {
+    // No package.json is a normal shape (a Python or Go repository), and an unreadable one
+    // is reported by the manifest path. Either way the card has no scripts to draw on.
+    return {};
+  }
+}
+
+/**
+ * The command for one verb, or null when this repository proves none.
+ *
+ * Precedence is deliberate and mirrors the manifest's own. A declared `gates.commands`
+ * entry is the repository naming its own program and wins over anything inferred; a
+ * `package.json` script is the repository's declared entrypoint (`npm run <verb>`); and
+ * the ecosystem table is the canonical command for a marker that is present but whose
+ * repository has declared nothing. The last is the same table the tool seeds gates from,
+ * so the card and the gate list cannot name two different commands for one repository.
+ */
+function resolveVerb(verb, { manifest, facts, stack, scripts }) {
+  const declared = text(manifest?.gates?.commands?.[verb]);
+  if (declared) return declared;
+
+  // The script a verb maps to. `format` is a staged gate rather than a script gate, so its
+  // two conventional script names are tried directly — `format:check` first, because that
+  // is the one a hook and CI run, which is what the card is reporting.
+  const scriptNames = verb === 'format' ? ['format:check', 'format'] : [verb];
+  for (const name of scriptNames) {
+    if (text(scripts?.[name])) return `npm run ${name}`;
+  }
+
+  if (verb === 'build') {
+    if (text(scripts?.build)) return 'npm run build';
+    for (const row of BUILDS) {
+      if (row.fact && facts.has(row.fact)) return row.command;
+      if (row.stack && stack.has(row.stack)) return row.command;
+    }
+    return null;
+  }
+
+  for (const eco of ECOSYSTEMS) {
+    if (!facts.has(eco.fact)) continue;
+    const command = text(eco.commands?.[verb]);
+    if (command) return command;
+  }
+  for (const row of CARD_FALLBACKS) {
+    if (!row.when(stack, facts, scripts)) continue;
+    const command = text(row.commands?.[verb]);
+    if (command) return command;
+  }
+  return null;
+}
+
+/** The text a set of lines renders to. Kept beside `commandCard` so both agree. */
+function renderCard(lines) {
+  const body = lines.map((l) => `- ${l.label}: \`${l.command}\``).join('\n');
+  return `Commands for this repository:\n\n${body}`;
+}
+
+function renderBytes(lines) {
+  return lines.length === 0 ? 0 : Buffer.byteLength(renderCard(lines));
+}
+
+/**
+ * The index of the next line to drop, or -1 when nothing may be dropped.
+ *
+ * Verbs drop in `DROP_ORDER`. Focused templates drop only after every verb, from the last
+ * first, because a focused template is the plan's headline content and a repository with
+ * several is the one case where dropping one still leaves the reader a template.
+ */
+function pickDroppable(lines) {
+  for (const verb of DROP_ORDER) {
+    const at = lines.findIndex((l) => l.verb === verb);
+    if (at !== -1) return at;
+  }
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (lines[i].verb === 'focused') return i;
+  }
+  return -1;
+}
+
+/**
+ * Build the card for one repository.
+ *
+ * @param {{root: string, manifest?: object, stack?: string[], facts?: string[]}} input
+ * @returns {Promise<{text: string, bytes: number, lines: {label: string, command: string,
+ *   verb: string}[], dropped: string[]}>}
+ */
+export async function commandCard({ root, manifest = null, stack = [], facts = [] }) {
+  const factSet = new Set(facts);
+  const stackSet = new Set(stack);
+  const scripts = await readScripts(root);
+
+  const lines = [];
+  for (const verb of VERBS) {
+    const command = resolveVerb(verb, { manifest, facts: factSet, stack: stackSet, scripts });
+    if (command) lines.push({ label: verb, command, verb });
+  }
+  for (const entry of FOCUSED) {
+    if (!entry.when(stackSet, factSet, scripts)) continue;
+    // One template per path kind: `has-uv-lock` and `has-pyproject` both match a uv repo,
+    // and two Python lines would be two answers with the second one wrong.
+    if (lines.some((l) => l.kind === entry.kind)) continue;
+    lines.push({
+      label: `focused test (${entry.kind})`,
+      command: entry.template(stackSet, factSet, scripts),
+      kind: entry.kind,
+      verb: 'focused',
+    });
+  }
+
+  // Fit under the ceiling by dropping whole lines, least valuable first. Nothing is cut
+  // silently: `dropped` names every line removed so the caller can say so, because a card
+  // that quietly lost a command is a card a reader cannot tell is incomplete.
+  const dropped = [];
+  let kept = lines.slice();
+  while (renderBytes(kept) > CARD_LIMIT_BYTES) {
+    const victim = pickDroppable(kept);
+    if (victim === -1) break;
+    dropped.push(kept[victim].label);
+    kept = kept.filter((_, i) => i !== victim);
+  }
+
+  const text = kept.length > 0 ? renderCard(kept) : '';
+  return { text, bytes: Buffer.byteLength(text), lines: kept, dropped };
+}