simt-dev 0.6.2 → 0.7.0

package/src/secrets.mjs

@@ -0,0 +1,374 @@
+// A zero-dependency scan of the staged diff for secrets (plan 0003 R52).
+//
+// Two finding sources, deliberately both. A pattern library catches the shapes
+// vendors publish — an AWS key id, a private key header, a token prefix — and
+// Shannon entropy catches the high-entropy blobs that carry no prefix at all:
+// a 32-character random base64 string is a secret whether or not a vendor named
+// it. Neither needs a network call or an install step, which is the point. A
+// gate that needs an install step is a gate a fresh clone does not have
+// (ADR-012, zero runtime dependencies).
+//
+// Three boundaries, each load-bearing:
+//
+//   - Added lines only. The scan reads `git diff --cached`, so a secret already
+//     sitting in history is not this gate's finding: the commit about to be made
+//     is. Flagging context lines would block commits for work the author did not
+//     stage, which is the failure `format`'s staged-only rule exists to prevent.
+//   - Findings never print the matched bytes. The hook output lands in a
+//     terminal, a CI log and often a transcript an agent reads back: echoing the
+//     secret into a report about the secret is the leak with extra steps. A
+//     finding carries a four-character prefix (the part a vendor publishes as a
+//     type — `AKIA`, `sk-`, `ghp_`) and nothing else.
+//   - Placeholders are not secrets. `password = "changeme-example"` in a README
+//     is documentation, and a gate that blocks it teaches the exact `--no-verify`
+//     habit the dispatcher's fail-closed rule exists to prevent.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+/** The length at which a token is worth measuring, and the entropy it must reach. */
+const ENTROPY_MIN_LENGTH = 32;
+export const ENTROPY_MIN_BITS = 4.5;
+
+/**
+ * A value is a placeholder when the WHOLE value is placeholder-shaped, not when
+ * it contains a placeholder word: a real secret may contain "example" and still
+ * be a secret, and the substring test blocked exactly that commit (review 0003 Q24).
+ */
+const PLACEHOLDER_WORD = /^(?:example|sample|placeholder|changeme|change[-_]?me|dummy|fake|redacted|notasecret|undefined|null|none|true|false|x+)$/i;
+const PLACEHOLDER_SLOT = /^(?:<[^<>]*>|\{\{?[a-z0-9_.-]+\}\}?|your[-_][a-z0-9_-]*|my[-_][a-z0-9_-]*)$/i;
+
+/**
+ * @param {string} value the candidate secret
+ * @returns {boolean} true when the whole value is documentation, not a leak
+ */
+function isPlaceholder(value) {
+  const v = String(value).trim();
+  if (v === '') return true;
+  if (PLACEHOLDER_SLOT.test(v)) return true;
+  const words = v.split(/[^a-zA-Z]+/).filter(Boolean);
+  if (words.length === 0) return true; // punctuation only: `…`, `-`
+  return words.every((w) => PLACEHOLDER_WORD.test(w));
+}
+
+/**
+ * The pattern library. Each row names itself so the finding tells the reader
+ * WHICH shape matched — "a secret was found" sends them hunting for it;
+ * "aws-access-key-id on line 12" says what to revoke.
+ *
+ * `groups`, when set, lists the captures that may hold the VALUE — what the
+ * placeholder check and the redaction run on; the first defined capture wins.
+ * Without it the whole match is the value.
+ */
+const PATTERNS = [
+  { id: 'aws-access-key-id', re: /\b(?:A3T[A-Z0-9]|AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/g },
+  // The type word is not the discriminator, "PRIVATE KEY" is: RSA, EC, DSA,
+  // OPENSSH, PGP and ENCRYPTED all carry the same header shape (review 0003 Q24).
+  { id: 'private-key-block', re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----/g },
+  { id: 'github-token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b|\bgithub_pat_[A-Za-z0-9_]{22,}\b/g },
+  { id: 'gitlab-token', re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g },
+  { id: 'npm-token', re: /\bnpm_[A-Za-z0-9]{36}\b/g },
+  { id: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { id: 'stripe-live-key', re: /\b(?:sk|rk)_live_[0-9a-zA-Z]{24,}\b/g },
+  { id: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { id: 'openai-style-key', re: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+  { id: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+  // The key name is prefix-aware — DB_PASSWORD, aws_secret_access_key — and the
+  // value may be quoted or bare, because .env and YAML do not quote (review 0003 Q24).
+  {
+    id: 'assigned-secret',
+    re: /\b[A-Za-z0-9_.-]*(?:password|passwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\b\s*[:=]\s*(?:"([^"]{8,})"|'([^']{8,})'|([A-Za-z0-9+/=_-]{8,}))/gi,
+    groups: [1, 2, 3],
+  },
+  // The password half of https://user:pw@host: the only place a URL carries one.
+  {
+    id: 'url-userinfo',
+    re: /\b[a-z][a-z0-9+.-]*:\/\/[^:/\s@]+:([A-Za-z0-9._~+-]{8,})@/g,
+    groups: [1],
+  },
+];
+
+/** Longest base64ish run worth measuring for entropy. */
+const ENTROPY_CANDIDATE = /[A-Za-z0-9+/=_-]{32,}/g;
+
+/**
+ * Subresource-integrity hashes: `sha256-<base64>` and kin. A deterministic
+ * digest of file content, present in every lockfile and build manifest —
+ * high-entropy bytes that are never a secret (review 0003 Q24).
+ */
+const SRI_HASH = /^sha(1|256|384|512)-[A-Za-z0-9+/]+={0,2}$/;
+
+/**
+ * Shannon entropy of a string, in bits per character.
+ *
+ * The detector's whole discriminator in one function: a uniformly random token
+ * approaches log2(alphabet size) — near 6 bits for base64 — while English,
+ * hex digests and repeated identifiers fall below 4.5. A sha256 hex digest tops
+ * out at 4.0 over sixteen symbols, which is exactly why the threshold sits above
+ * it: a commit hash is not a secret, and a gate that calls it one gets disabled.
+ */
+export function entropy(text) {
+  const freq = new Map();
+  for (const ch of text) freq.set(ch, (freq.get(ch) ?? 0) + 1);
+  let bits = 0;
+  for (const n of freq.values()) {
+    const p = n / text.length;
+    bits -= p * Math.log2(p);
+  }
+  return bits;
+}
+
+/** The four characters a finding may show: the prefix a vendor publishes as a type. */
+function redact(value) {
+  return `${value.slice(0, 4)}…`;
+}
+
+/**
+ * Every secret span in the text: pattern matches in library order, then entropy
+ * over whatever no pattern claimed. One function because the gate report and
+ * the redactor must agree on what a secret is: two matchers drift, and the
+ * drift is a token one of them stores (review 0003 Q36).
+ *
+ * @param {string} text
+ * @returns {{start: number, end: number, kind: string, preview: string, entropy?: number}[]}
+ */
+function findSpans(text) {
+  const found = [];
+  const claimed = [];
+
+  for (const pattern of PATTERNS) {
+    pattern.re.lastIndex = 0;
+    for (const match of text.matchAll(pattern.re)) {
+      const groups = pattern.groups ?? [0];
+      let value = null;
+      for (const g of groups) {
+        if (match[g] !== undefined) {
+          value = match[g];
+          break;
+        }
+      }
+      if (value === null) continue;
+      if (isPlaceholder(value)) continue;
+      const at = match.index + match[0].indexOf(value);
+      // Overlap, not equality: a token a pattern named is one finding, and the
+      // entropy reading of the same bytes would double the count a gate reports.
+      if (claimed.some(([a, b]) => at < b && a < at + value.length)) continue;
+      claimed.push([at, at + value.length]);
+      found.push({ start: at, end: at + value.length, kind: pattern.id, preview: redact(value) });
+    }
+  }
+
+  ENTROPY_CANDIDATE.lastIndex = 0;
+  for (const match of text.matchAll(ENTROPY_CANDIDATE)) {
+    const value = match[0];
+    if (value.length < ENTROPY_MIN_LENGTH) continue;
+    if (SRI_HASH.test(value)) continue;
+    if (isPlaceholder(value)) continue;
+    if (claimed.some(([a, b]) => match.index < b && a < match.index + value.length)) continue;
+    const bits = entropy(value);
+    if (bits < ENTROPY_MIN_BITS) continue;
+    found.push({
+      start: match.index,
+      end: match.index + value.length,
+      kind: 'high-entropy',
+      preview: redact(value),
+      entropy: Number(bits.toFixed(1)),
+    });
+  }
+
+  return found;
+}
+
+/**
+ * Scan one line's worth of added text.
+ *
+ * @param {string} text the added line, without the leading `+`
+ * @returns {{kind: string, preview: string, entropy?: number}[]} findings in
+ *   pattern order, then entropy over whatever no pattern claimed
+ */
+export function scanText(text) {
+  return findSpans(text).map(({ kind, preview, entropy }) =>
+    entropy === undefined ? { kind, preview } : { kind, preview, entropy },
+  );
+}
+
+/**
+ * Replace every secret span with `[redacted:<kind>]`, leaving the rest of the
+ * text byte-identical. Lesson candidates store the commands that failed, and a
+ * command can carry a token (`curl -H "Authorization: Bearer …"`); storing it
+ * verbatim writes the secret into a JSONL file that is then read, rendered and
+ * injected into prompts (review 0003 Q36).
+ *
+ * @param {string} text
+ * @returns {string} the text with secret values replaced
+ */
+export function redactText(text) {
+  const spans = findSpans(String(text ?? '')).sort((a, b) => b.start - a.start);
+  let out = String(text ?? '');
+  for (const span of spans) {
+    out = `${out.slice(0, span.start)}[redacted:${span.kind}]${out.slice(span.end)}`;
+  }
+  return out;
+}
+
+/**
+ * Lockfiles are skipped by default (review 0003 Q24): their high-entropy bytes
+ * are integrity hashes and version pins, and a dependency bump is a commit the
+ * gate must not block. The SRI allow-list above covers the same shapes wherever
+ * they appear outside a lockfile.
+ */
+const LOCKFILES = new Set([
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'yarn.lock',
+  'bun.lockb',
+  'pnpm-lock.yaml',
+  'Cargo.lock',
+  'go.sum',
+  'composer.lock',
+  'Gemfile.lock',
+  'Pipfile.lock',
+  'poetry.lock',
+  'uv.lock',
+  'pubspec.lock',
+  'mix.lock',
+]);
+
+/** A line carrying this marker is the author's explicit exemption for that line. */
+const PRAGMA = 'simt:allow-secret';
+
+/**
+ * One glob to one anchored regex: `**` crosses separators, `*` and `?` do not.
+ * The same small matcher the ignore lists render with, because a repository
+ * that writes `vendor/**` in `.simtignore` expects the same reading here.
+ */
+function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i += 1;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Scan the staged diff: the added lines of what the next commit would record.
+ *
+ * File attribution is a hunk state machine rather than a prefix test, because
+ * the two are indistinguishable by prefix alone: an added line whose content
+ * starts with `++ ` renders as `+++ something`, which looks exactly like a
+ * `+++ b/…` file header. Headers appear only outside hunks and content only
+ * inside them, so the `diff --git` boundary and the `@@` header decide which
+ * one a line is.
+ *
+ * @param {string} root repository root
+ * @param {{ignore?: string[]}} [options] `ignore` is the manifest's
+ *   `gates.secretScan.ignore`: globs of repository paths to skip (review 0003 Q24)
+ * @returns {Promise<{findings: {file: string, line: number, kind: string,
+ *   preview: string, entropy?: number}[], lines: number, error: string|null}>}
+ *   `error` is set only when git itself could not answer; callers fail closed on
+ *   it rather than reading silence as a clean diff.
+ */
+export async function scanStaged(root, options = {}) {
+  const ignore = (Array.isArray(options.ignore) ? options.ignore : [])
+    .filter((g) => typeof g === 'string' && g !== '')
+    .map(globToRegExp);
+
+  let stdout;
+  try {
+    // Every flag here defeats a way a repository can keep the scan from seeing its
+    // own staged bytes (review 0003 Q02): `diff.external` routes the diff to a
+    // program that prints nothing, `-diff` in `.gitattributes` and genuinely binary
+    // files make git print no text at all, a textconv rewrites the bytes on the way
+    // out, `diff.mnemonicPrefix` renames the header prefixes the attribution below
+    // reads, and C-quoting mangles a non-ASCII name. The scan asks git for the staged
+    // bytes with its own flags and ignores what the repository asked for.
+    ({ stdout } = await exec(
+      'git',
+      [
+        '-c', 'core.quotePath=false',
+        'diff',
+        '--cached',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--text',
+        '--unified=0',
+        '--no-color',
+        '--src-prefix=a/',
+        '--dst-prefix=b/',
+      ],
+      { cwd: root, maxBuffer: 32 * 1024 * 1024 },
+    ));
+  } catch (error) {
+    const stderr = String(error.stderr ?? '').trim();
+    const reason = (stderr || String(error.message ?? error)).split('\n')[0];
+    return { findings: [], lines: 0, error: reason };
+  }
+
+  const findings = [];
+  let lines = 0;
+  let file = null;
+  let lineNo = 0;
+  let inHunk = false;
+  let fileSkipped = false;
+
+  for (const raw of stdout.split('\n')) {
+    if (raw.startsWith('diff --git ')) {
+      inHunk = false;
+      continue;
+    }
+    if (raw.startsWith('@@ ')) {
+      const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+      if (hunk) {
+        lineNo = Number(hunk[1]);
+        inHunk = true;
+      }
+      continue;
+    }
+    if (!inHunk) {
+      // Outside a hunk: headers only. `+++ /dev/null` is the removal side of a
+      // deletion; nothing is added under it.
+      if (raw.startsWith('+++ ')) {
+        const path = raw.slice(4).trim();
+        file = path === '/dev/null' ? null : path.replace(/^b\//, '');
+        const name = file === null ? '' : file.slice(file.lastIndexOf('/') + 1);
+        fileSkipped = file !== null && (LOCKFILES.has(name) || ignore.some((re) => re.test(file)));
+      }
+      continue;
+    }
+    if (!raw.startsWith('+')) continue; // -U0 has no context; this is `\ No newline…`
+    lines += 1;
+    if (file !== null && !fileSkipped && !raw.includes(PRAGMA)) {
+      for (const hit of scanText(raw.slice(1))) {
+        findings.push({ file, line: lineNo, ...hit });
+      }
+    }
+    lineNo += 1;
+  }
+
+  return { findings, lines, error: null };
+}
+
+/** The report a failing gate prints: one finding per line, redacted. */
+export function renderFindings(findings) {
+  return findings
+    .map(
+      (f) =>
+        `  ${f.file}:${f.line}  ${f.kind}  ${f.preview}` +
+        (f.entropy !== undefined ? `  (entropy ${f.entropy} bits)` : ''),
+    )
+    .join('\n');
+}

package/src/state.mjs

@@ -0,0 +1,76 @@
+// Machine-local state lives here, not in the tree (review 0003 Q19).
+//
+// Everything this tool writes for itself — the ledger, the check cache, the
+// index, leases, the journal, briefs, gate logs, bench runs — used to live
+// directly under `.simt/`, so `simt check` changed the tree id its own
+// evidence was measured against, and a slice worktree landed in the main
+// checkout as an embedded gitlink. The fix is one directory: local state
+// goes under `.simt/local/`, which is ignored and excluded from the tree,
+// while committed content (`packs/`, `bin/`, `bench/tasks/`, profiles) stays
+// where it was.
+//
+// Readers try the new path first and fall back to the old one for one
+// release, so a repository whose state predates the move keeps working until
+// the next write migrates it. Writers always write the new path.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { STATE_DIR } from './name.mjs';
+
+/** The ignored directory every machine-local write goes under. */
+export const LOCAL_DIR = join(STATE_DIR, 'local');
+
+/** A machine-local path, relative to the repository root. */
+export function localRel(...parts) {
+  return join(LOCAL_DIR, ...parts);
+}
+
+/**
+ * Where a machine-local file is read from: the new path first, then each
+ * legacy path in order. Writers use only the first entry.
+ */
+function readCandidates(root, rel, legacy = []) {
+  return [join(root, rel), ...legacy.map((l) => join(root, l))];
+}
+
+/** The first readable candidate, or null when none exists. */
+export async function readStateFile(root, rel, legacy = []) {
+  for (const path of readCandidates(root, rel, legacy)) {
+    try {
+      return { text: await readFile(path, 'utf8'), path };
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  return { text: null, path: join(root, rel) };
+}
+
+/**
+ * Every machine-local path the tree id must exclude: the whole local area
+ * plus the legacy paths a pre-move checkout may still carry, so an old
+ * `check.json` or worktree can neither change the id nor be committed.
+ */
+export const TREE_EXCLUDES = [
+  LOCAL_DIR,
+  join(STATE_DIR, 'ledger.jsonl'),
+  join(STATE_DIR, 'lessons.jsonl'),
+  join(STATE_DIR, 'leases.json'),
+  join(STATE_DIR, 'check.json'),
+  join(STATE_DIR, 'index.sqlite'),
+  join(STATE_DIR, 'index.jsonl'),
+  join(STATE_DIR, 'brief.md'),
+  join(STATE_DIR, 'journal'),
+  join(STATE_DIR, 'worktrees'),
+  join(STATE_DIR, 'gate'),
+  join(STATE_DIR, 'distilled'),
+  join(STATE_DIR, 'reviews'),
+  join(STATE_DIR, 'proposals'),
+  join(STATE_DIR, 'compiled'),
+  join(STATE_DIR, 'critic-labels.jsonl'),
+  join(STATE_DIR, 'bench', 'runs'),
+  join(STATE_DIR, 'bench', 'vault'),
+  join(STATE_DIR, 'bench', 'prices.json'),
+  join(STATE_DIR, 'bench', 'ablation.json'),
+  join(STATE_DIR, 'bench', 'probes'),
+];

package/src/status.mjs

@@ -0,0 +1,157 @@
+// The `--line` status cache (plan 0003 R48).
+//
+// `status --line` is for shell prompts, tmux and agent status lines: it must
+// answer in well under 50 ms, which rules out everything `check` does (rule
+// loading, projection, gate probing). So `check` — the one command that
+// already measures all of it — writes `.simt/check.json` on every run, and
+// `--line` reads only that file plus one `git rev-parse HEAD` to notice new
+// commits. No fingerprint, no rule reads, no capability probe.
+//
+// Three honesties, each a failure this module refuses to be:
+//
+//   - The cache is local state, never content (the same standing as the
+//     journal, the ledger and the index). Writers that change files `check`
+//     reads (`init`, `sync`, `upgrade`, `hooks install`, `undo`) delete it
+//     when they apply, so the line goes back to "no cache" instead of
+//     reporting the tree as it was. Hand edits between checks are the
+//     documented blind spot: the line is the gate state *as of the last
+//     check*, and says `stale` only when HEAD moved.
+//   - A blocking finding that fits no slot still fails the line. The version
+//     pin, an invalid rule, a bad gate cwd — none of these is rules, hooks
+//     or gates-count, and a line that showed all slots green while the gate
+//     fails would be the lie prompts are for. So PASS/FAIL is carried
+//     explicitly rather than inferred from the symbols.
+//   - The write is atomic (tmp + rename) and fixed-size: only counts and
+//     booleans are stored, never findings, so a huge gate still leaves a
+//     ~200-byte file and a killed `check` never leaves half a document.
+
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { readHooksState, wantsShim } from './compare/hooksstate.mjs';
+import { LOCAL_DIR } from './state.mjs';
+
+const exec = promisify(execFile);
+
+const CACHE_FILE = join(LOCAL_DIR, 'check.json');
+const CACHE_FILE_LEGACY = '.simt/check.json';
+const CACHE_VERSION = 1;
+
+/**
+ * The commit the cached state was measured at, or null when git cannot say
+ * (not a repository, no commits yet, git missing). Null is trust, not failure:
+ * without a HEAD there is nothing to compare, and refusing the line would
+ * make exported trees — the ones with no `.git` at all — unreportable.
+ */
+export async function currentHead(root) {
+  try {
+    const { stdout } = await exec('git', ['rev-parse', 'HEAD'], { cwd: root });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function cachePath(root) {
+  return join(root, CACHE_FILE);
+}
+
+/**
+ * Add the when and the where to a check-measured summary. The summary itself
+ * is built by `check`, which is the only command that measures all of it;
+ * this only stamps it.
+ */
+export async function buildCacheRecord(root, summary) {
+  return {
+    version: CACHE_VERSION,
+    at: Date.now(),
+    head: await currentHead(root),
+    rulesOk: summary.rulesOk,
+    hooksOk: summary.hooksOk,
+    gatesRun: summary.gatesRun,
+    gatesTotal: summary.gatesTotal,
+    blocking: summary.blocking,
+    warnings: summary.warnings,
+  };
+}
+
+/** Atomically replace the cache. A killed `check` leaves the previous record, not half of one. */
+export async function writeCheckCache(root, record) {
+  const path = cachePath(root);
+  await mkdir(join(root, LOCAL_DIR), { recursive: true });
+  const body = `${JSON.stringify(record)}\n`;
+  const tmp = `${path}.tmp-${process.pid}`;
+  await writeFile(tmp, body, 'utf8');
+  await rename(tmp, path);
+}
+
+/** The last record `check` wrote, or null when it never ran (or a writer invalidated it). */
+export async function readCheckCache(root) {
+  // The pre-move path is a fallback for one release (review 0003 Q19).
+  let raw;
+  try {
+    raw = await readFile(cachePath(root), 'utf8').catch(async (error) => {
+      if (error.code !== 'ENOENT') throw error;
+      return readFile(join(root, CACHE_FILE_LEGACY), 'utf8');
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  try {
+    const record = JSON.parse(raw);
+    if (record.version !== CACHE_VERSION) return null;
+    return record;
+  } catch {
+    // A damaged cache is no cache: the next `check` rewrites it, and a prompt
+    // that refused to render over a corrupt byte would stay broken until then.
+    return null;
+  }
+}
+
+/**
+ * Forget the cached state. Called by writers that change files `check` reads,
+ * after they apply — never on preview or dry-run, where nothing changed and
+ * the record is still true.
+ */
+export async function invalidateCheckCache(root) {
+  try {
+    await unlink(cachePath(root));
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+}
+
+/**
+ * The hooks slot of the line: every declared gate routed through a current
+ * shim. A repository that declares no gate has nothing to enforce, so the
+ * slot is vacuously true rather than forever red (the same answer `init`
+ * prints in prose). Gates run/total is counted by `check` from the runnable
+ * verdicts, not here: routing and runnability are different slots.
+ */
+export async function hooksSummary(root, manifest, exists) {
+  const declared = [...(manifest?.gates?.preCommit ?? []), ...(manifest?.gates?.prePush ?? [])];
+  const evidence = manifest?.gates?.evidence === 'warn' || manifest?.gates?.evidence === 'block';
+  if (declared.length === 0 && !evidence) return { ok: true };
+  const state = await readHooksState(root, { declaresGate: (event) => wantsShim(manifest, exists, event) });
+  return { ok: state.complete };
+}
+
+/**
+ * One line, always: `simt PASS ✓rules ✓hooks 3/3gates`, longest honest case
+ * `simt FAIL ✗rules ✗hooks 0/12gates ⚠9 stale`. Counts stay small because they
+ * count gates and warnings, never findings; the ≤ 60-char budget is asserted
+ * on a synthetic worst case, not on the hope that gates stay few.
+ */
+export function renderStatusLine(record, stale) {
+  const outcome = record.blocking === 0 ? 'PASS' : 'FAIL';
+  const rules = record.rulesOk ? '✓rules' : '✗rules';
+  const hooks = record.hooksOk ? '✓hooks' : '✗hooks';
+  let line = `simt ${outcome} ${rules} ${hooks} ${record.gatesRun}/${record.gatesTotal}gates`;
+  if (record.warnings > 0) line += ` ⚠${record.warnings}`;
+  if (stale) line += ' stale';
+  return line;
+}

package/src/toolwords.mjs

@@ -22,6 +22,7 @@ import { VARIANTS_MARKER } from './kernel/variants.mjs';
 import { LESSON_KEYS } from './memory/lessons.mjs';
 import { DECISION_KEYS } from './memory/decide.mjs';
 import { PROMPT_WORDS } from './mcp/prompts.mjs';
+import { AGENT_STEM, SKILL_STEM } from './agents/render.mjs';
 
 /**
  * `simt-` names that belong to this tool and never to a repository.
@@ -45,6 +46,10 @@ export const TOOL_WORDS = new Set([
   'simt-dev',
   'simt-dev-check',
   'simt-hooks',
+  // The one agent this tool ships, named by the stem every harness's agents file shares.
+  AGENT_STEM,
+  // The companion skill the agent reads on demand; its stem is the directory name.
+  SKILL_STEM,
 ]);
 
 /**