simt-dev 0.2.0 → 0.2.1

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/hooks/capability.mjs

@@ -18,9 +18,10 @@
 // cannot run a `lint` gate, and this reads the manifest rather than the dependency graph
 // so the two can never disagree about what a script does.
 
-import { readdir, readFile, stat } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { access, readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { manifestPath } from '../projection/manifest.mjs';
+import { ECOSYSTEMS, manifestPath } from '../projection/manifest.mjs';
 
 /** Binaries the shared dispatcher shells out to directly, rather than via a script. */
 const BIN_DIR = join('node_modules', '.bin');
@@ -59,14 +60,49 @@ async function fileExists(path) {
   }
 }
 
+/**
+ * Does an EXECUTABLE file exist at this path?
+ *
+ * A wrapper that exists but is not executable is a probe failure, not a success:
+ * declaring it would plant a command that fails closed on every commit — the defect
+ * ADR-017 exists to prevent, reached from the ecosystem table rather than the stack.
+ */
+async function executableFile(path) {
+  try {
+    if (!(await stat(path)).isFile()) return false;
+    await access(path, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Can this machine run the ecosystem's program?
+ *
+ * Two kinds of evidence, matching the two kinds of tool in `ECOSYSTEMS`: a binary on
+ * PATH, probed directory by directory the way the shell would find it, and a file the
+ * repository commits (the Maven wrapper), probed in place the way `gradlew` is probed.
+ * Either answer that is not a positive YES is NO: a seed that guesses a toolchain is
+ * a declared gate that cannot run, and the dispatcher fails closed on it.
+ */
+async function probeTool(root, eco) {
+  if (eco.file) return executableFile(join(root, eco.tool));
+  const dirs = (process.env.PATH ?? '').split(':').filter(Boolean);
+  for (const dir of dirs) {
+    if (await executableFile(join(dir, eco.tool))) return true;
+  }
+  return false;
+}
+
 /**
  * Read what this repo can run.
  *
  * @param {string} root
- * @returns {Promise<{scripts: Record<string,string>, binaries: string[], commands: Record<string,string>, runner: string, error: string|null}>}
+ * @returns {Promise<{scripts: Record<string,string>, binaries: string[], commands: Record<string,string>, tools: string[], runner: string, error: string|null}>}
  */
 export async function readCapability(root) {
-  const capability = { scripts: {}, binaries: [], commands: {}, runner: null, error: null };
+  const capability = { scripts: {}, binaries: [], commands: {}, tools: [], runner: null, error: null };
 
   try {
     const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
@@ -104,6 +140,14 @@ export async function readCapability(root) {
     // No node_modules is the same as no installed binaries.
   }
 
+  // `tools` answers "can this MACHINE run the ecosystem's program", which the marker
+  // file in the repo cannot: a Cargo.toml without cargo installed is an ecosystem that
+  // is here but whose gates would all fail closed. The probe is per-row, because a row
+  // that marks its tool `file` lives in the repository, not on PATH.
+  for (const eco of ECOSYSTEMS) {
+    if (await probeTool(root, eco)) capability.tools.push(eco.tool);
+  }
+
   // `gates.commands` lives in simt-dev.json, NOT package.json, so it has to be read
   // here or a command gate looks undeclared to `check` while the dispatcher runs it
   // successfully — the gate and the checker disagreeing about the same manifest.

package/src/hooks/dispatcher.mjs

@@ -27,11 +27,12 @@ import { GATES } from './gates.mjs';
 import { resolveGate } from './resolve.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
+import { assertVersionPin } from '../package-version.mjs';
 
 const exec = promisify(execFile);
 
 /** Gates that are known but not required for the event to pass. */
-export const DEFAULT_EVENTS = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
+const DEFAULT_EVENTS = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
 
 /**
  * @param {string} event 'pre-commit' | 'pre-push'
@@ -65,6 +66,21 @@ export async function runGates(event, { root, manifest }) {
     };
   }
 
+  // The gates below run from the binary that resolved this shim. For a repository
+  // without npm that is a global install, whose version nothing else pins: if it is not
+  // the one this repo adopted, the gates that run here are not the ones CI runs.
+  // Placed after the empty-list check on purpose - with no gates there is nothing the
+  // version could get wrong, and failing that case would block commits in repos that
+  // deliberately declare none.
+  const mismatch = assertVersionPin(manifest);
+  if (mismatch) {
+    return {
+      event,
+      gates: [{ name: 'version', status: 'failed', detail: mismatch, remedy: `run: ${CLI} upgrade --yes`, adr: null }],
+      failed: true,
+    };
+  }
+
   const pkg = await readPkg(root);
   const staged = event === 'pre-commit' ? await stagedFiles(root) : [];
   const unstaged = event === 'pre-commit' ? await unstagedFiles(root) : new Set();
@@ -131,7 +147,7 @@ export async function runGates(event, { root, manifest }) {
       formatted = targets;
     }
 
-    const outcome = await run(resolution.argv, root);
+    const outcome = await runGate(resolution, root);
     results.push({
       name,
       status: outcome.code === 0 ? 'passed' : 'failed',
@@ -186,6 +202,37 @@ async function run(argv, cwd) {
   }
 }
 
+/**
+ * Run a gate's resolution, as a shell line or as an argv.
+ *
+ * A declared command is a line the repository wrote in its own manifest and would type
+ * into its own shell (ADR-019 ruling 8), so it goes through `sh -c` and everything it
+ * wrote survives — quotes, pipes, `&&`, a flag with a space in its value. Everything
+ * this tool resolved itself stays an argv, because that is a path this tool chose out of
+ * `node_modules/.bin` and handing it to a shell would be a change of trust for no gain.
+ *
+ * `sh -c` is not a sandbox and is not meant to be. The trust boundary is the repository:
+ * the line came from its own manifest, which it can read and change, and it runs on the
+ * author's own machine at the author's own request. The only property worth defending is
+ * that the two sources stay distinguishable, which is why this is a separate branch
+ * rather than a flag on `run`.
+ */
+async function runGate(resolution, cwd) {
+  if (resolution.shell === true && typeof resolution.command === 'string') {
+    try {
+      const { stdout, stderr } = await exec('sh', ['-c', resolution.command], { cwd, maxBuffer: 8 * 1024 * 1024 });
+      return { code: 0, stdout, stderr };
+    } catch (error) {
+      return {
+        code: typeof error.code === 'number' ? error.code : 1,
+        stdout: error.stdout ?? '',
+        stderr: error.stderr ?? String(error.message ?? error),
+      };
+    }
+  }
+  return run(resolution.argv, cwd);
+}
+
 async function readPkg(root) {
   try {
     return JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
@@ -212,7 +259,7 @@ export async function stagedFiles(root) {
  * A path staged as DELETED is not here: the index and the working tree agree that
  * it is gone, so there is no unstaged work to protect and no reason to refuse.
  */
-export async function unstagedFiles(root) {
+async function unstagedFiles(root) {
   try {
     const { stdout } = await exec('git', ['diff', '--name-only'], { cwd: root });
     return new Set(stdout.split('\n').map((s) => s.trim()).filter(Boolean));
@@ -264,5 +311,3 @@ function tail(text, lines = 12) {
   const parts = String(text).trimEnd().split('\n');
   return parts.slice(-lines).join('\n');
 }
-
-export const __internals = { tail, basename };

package/src/hooks/gates.mjs

@@ -140,5 +140,3 @@ export function unresolved(name, { hasScript, binary, command, stack }) {
 export function gateNames() {
   return Object.keys(GATES).sort();
 }
-
-export const __internals = { FORMATTABLE, GATES };

package/src/hooks/resolve.mjs

@@ -14,7 +14,7 @@ import { access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { join } from 'node:path';
 
-import { FORMATTABLE, GATES, GATES as _G } from './gates.mjs';
+import { FORMATTABLE, GATES } from './gates.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 
 /** Gate names the shared dispatcher knows, sorted. */
@@ -22,23 +22,8 @@ export function knownGates() {
   return Object.keys(GATES).sort();
 }
 
-export function gateKind(name) {
-  return GATES[name]?.kind ?? null;
-}
-
-export function gateWhy(name) {
-  return GATES[name]?.why ?? null;
-}
-
-export function gateAdr(name) {
-  return GATES[name]?.adr ?? null;
-}
-
-/**
- * Is this path an executable file?
- * @param {string} path
- */
-export async function isExecutable(path) {
+/** Is this path an executable file? */
+async function isExecutable(path) {
   try {
     await access(path, constants.X_OK);
     return true;
@@ -96,8 +81,20 @@ export async function resolveGate(gate, { root, pkg, staged, commands }) {
   // own remedy, to "name the program under gates.commands"; a dispatcher that then
   // ignored that declaration would contradict the remedy, and so would `check`.
   if (declared) {
-    const argv = declared.trim().split(/\s+/).filter(Boolean);
-    if (argv.length === 0) {
+    // The declaration is a SHELL COMMAND LINE, not an argv (ADR-019, ruling 8).
+    //
+    // It was split on whitespace, so every declaration a repository would plausibly
+    // write was wrong: `npm run test -- --watch=false` became seven arguments with the
+    // flag value as a separate one, and `sh -c "a && b"` became eleven, with the quotes
+    // passed to the program. A repository had no way to write a gate with a quoted
+    // argument, and nothing said so — the gate simply ran the wrong thing.
+    //
+    // Splitting is also a parse without an owner. `execFile` takes an argv because it
+    // must not use a shell, which is right for a path this tool chose and wrong for a
+    // line the repository wrote in full view of its own shell. The two cases are now
+    // different types rather than one `argv` field carrying both.
+    const line = declared.trim();
+    if (line === '') {
       return {
         ok: false,
         gate: name,
@@ -109,12 +106,16 @@ export async function resolveGate(gate, { root, pkg, staged, commands }) {
     return {
       ok: true,
       kind: gate.kind,
-      argv,
+      // Kept alongside `command` because the dispatcher prints and passes it to
+      // `hooks status`, and two representations of one thing is how they drift.
+      argv: line.split(/\s+/).filter(Boolean),
+      command: line,
+      shell: true,
       // The dispatcher has to know whether these argv entries are paths it chose or
       // words it was handed. Sniffing the detail string meant the safety guard on
       // partial stages would quietly stop working the day that wording changed.
       declared: true,
-      detail: `declared command: ${declared}`,
+      detail: `declared command: ${line}`,
     };
   }
 
@@ -189,6 +190,4 @@ export async function resolveGate(gate, { root, pkg, staged, commands }) {
 function extname(path) {
   const dot = path.lastIndexOf('.');
   return dot > 0 ? path.slice(dot).toLowerCase() : '';
-}
-
-export const __internals = { extname, FORMATTABLE };
+}

package/src/hooks/shim.mjs

@@ -17,7 +17,20 @@
 // start in CI. See src/locate.mjs.
 
 import { renderLocator } from '../locate.mjs';
-import { BIN_ENV, CLI, MANIFEST_FILE } from '../name.mjs';
+import { BIN_ENV, CLI, MANIFEST_FILE, PACKAGE_NAME } from '../name.mjs';
+import { packageVersion } from '../package-version.mjs';
+
+/**
+ * A line only this tool's dispatcher shim carries.
+ *
+ * The banner, not the path and not the name. `pre-commit` is what a hand-written gate
+ * is called too, and the file can sit wherever git looks, so neither of those can say
+ * who wrote it. Exported rather than matched as a literal somewhere else because the
+ * question this answers is asked from both sides: this file writes it, and
+ * `readHooksState` reads it back to decide whether a hook it cannot recognise as
+ * current is nonetheless its own.
+ */
+export const SHIM_MARKER = '# Generated by simt-dev. Do not edit.';
 
 /** Events the shared dispatcher knows how to run. */
 export const EVENTS = ['pre-commit', 'pre-push'];
@@ -34,15 +47,26 @@ export function fileFor(event) {
 
 /**
  * @param {string} event one of EVENTS
+ * @param {{npm?: boolean, version?: string}} [opts]
+ *   `npm` is whether the repository has a package.json: it decides the remedy's install
+ *   (a devDependency where one exists, a pinned global install where there is no
+ *   node_modules to pin in). `version` defaults to the running package's own version,
+ *   so a shim generated by 0.2.0 names 0.2.0 in its remedy and CI install.
  * @returns {string} POSIX sh source, LF-terminated, executable
  */
-export function renderShim(event) {
+export function renderShim(event, { npm = true, version } = {}) {
   if (!EVENTS.includes(event)) {
     throw new Error(`unknown hook event ${event}; known: ${EVENTS.join(', ')}`);
   }
+  const v = version ?? packageVersion();
+  // The install that finds the binary when node_modules and PATH both come up empty.
+  // A repository with a package.json pins simt-dev as a devDependency, so the remedy
+  // installs it there; one without (Gradle, Connect IQ) has no node_modules to pin in,
+  // so the remedy is a pinned global install - the same pinned bytes CI gets.
+  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : `npm i -g ${PACKAGE_NAME}@${v}`;
   const D = '$';
   return `#!/bin/sh
-# Generated by simt-dev. Do not edit.
+${SHIM_MARKER}
 #
 # Every decision this hook makes is declared in ${MANIFEST_FILE}, so a reviewer reads
 # the gate list in a diff instead of reverse-engineering shell. Reinstall with:
@@ -51,7 +75,7 @@ export function renderShim(event) {
 # This file only locates the dispatcher and hands over. It resolves in order:
 #   1. ${D}SIMT_DEV_BIN    explicit override, for CI images and odd checkouts
 #   2. node_modules/       the pinned project dependency
-#   3. simt-dev on PATH    a global install
+#   3. ${CLI} on PATH       a global install
 # If none resolves it REFUSES rather than exiting 0. A hook that cannot verify
 # anything must never report success - that is what teaches authors to reach for
 # --no-verify.
@@ -62,7 +86,7 @@ ROOT="${D}(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 
 ${renderLocator(`hooks run ${event} --root "${D}ROOT"`, {
     subject: 'the dispatcher',
-    remedy: `REMEDY set ${BIN_ENV} to the ${CLI} binary, or unset ${HOOKS_PATH_KEY} to opt out`,
+    remedy: `REMEDY run: ${install}, or set ${BIN_ENV} to the ${CLI} binary, or unset ${HOOKS_PATH_KEY} to opt out`,
   })}`;
 }
 

package/src/identity.mjs

@@ -173,17 +173,6 @@ export async function includeOwnIdentity(root) {
   await git(root, ['config', '--local', '--replace-all', INCLUDE_KEY, `../${IDENTITY_FILE}`]);
 }
 
-/**
- * Whether the repository tracks the identity file, which it should not.
- *
- * @param {string} root
- * @returns {Promise<boolean>}
- */
-export async function tracksIdentity(root) {
-  const listed = await git(root, ['ls-files', '--error-unmatch', IDENTITY_FILE]);
-  return listed === IDENTITY_FILE;
-}
-
 /**
  * Add the identity file to .gitignore, if it is not already there.
  *

package/src/mcp/tools.mjs

@@ -19,7 +19,7 @@
 // cause by accident because the caller cannot see the size until it has paid for it.
 
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+import { loadRegistry } from '../graph/load.mjs';
 import { tokenize, rankSkills, closure, selectWithinBudget, scoreSkill, selectionVerdict, stackCompatible } from '../resolve/resolve.mjs';
 import { loadRules, select, checkTargets, provenanceDigest } from '../projection/project.mjs';
 import { loadDecisions, byId, citations } from '../decisions/index.mjs';
@@ -46,7 +46,7 @@ function rootOf(args) {
 }
 
 async function registry(args) {
-  const { registry, errors, ok, verified, workspace } = await loadRegistry(REGISTRY_PATH, args ?? {});
+  const { registry, errors, ok, verified, workspace } = await loadRegistry(null, args ?? {});
   if (!ok) {
     throw Object.assign(new Error(errors[0]), {
       remedy: `run: ${CLI} graph lint`,

package/src/output/index.mjs

@@ -12,13 +12,18 @@ export const EXIT = {
   OK: 0,
   FAIL: 1, // a gate failed: drift, policy violation, missing evidence
   USAGE: 2, // bad arguments; the remedy is in the message
-  CONFIG: 3, // simt-dev.json missing or invalid
+  CONFIG: 3, // simt.json missing or invalid
   REGISTRY: 4, // skills.graph.json invalid: orphan, dangling edge, cycle
   UNSUPPORTED: 5, // the request cannot be satisfied on this platform or repo
 };
 
 const REMEDY = {
-  [EXIT.USAGE]: 'run: simt-dev --help',
+  // Every default remedy below is `${CLI}` and not the package name, because this
+  // package installs exactly one binary and `package.json`'s `bin` map says which:
+  // `simt`. A remedy naming `simt-dev` is a command the reader types and gets
+  // `unknown command` from, which is the one answer that leaves them with no next
+  // step at all - and it was this default, printed on every bad invocation.
+  [EXIT.USAGE]: `run: ${CLI} --help`,
   [EXIT.CONFIG]: `run: ${CLI} init`,
   [EXIT.REGISTRY]: `run: ${CLI} graph lint`,
 };
@@ -32,7 +37,7 @@ export function fail(message, code = EXIT.FAIL, remedy) {
   // default and it was only ever resolvable from inside simt-dev's own checkout;
   // a reader in a consumer repo got a remedy naming a file that does not exist
   // where they are. Every remedy here is something the reader can run.
-  const resolved = remedy ?? REMEDY[code] ?? 'run: simt-dev --help';
+  const resolved = remedy ?? REMEDY[code] ?? `run: ${CLI} --help`;
   process.stderr.write(`ERROR ${code} ${message}\nREMEDY ${resolved}\n`);
   return code;
 }
@@ -60,10 +65,6 @@ export function writeMode(flags) {
   return { dryRun, apply: flags.yes === true && !dryRun };
 }
 
-export function isTty() {
-  return process.stdout.isTTY === true && !process.env.NO_COLOR;
-}
-
 /**
  * Emit a block of text under a heading, respecting --max-bytes.
  * Truncation is always announced with an explicit line, never a silent ellipsis:

package/src/package-version.mjs

@@ -0,0 +1,74 @@
+// How simt-dev is installed, and the version a repository holds it to.
+//
+// Three distinct things that must not be confused:
+//   - packageVersion() is the version of the binary that is RUNNING. It is read from
+//     the package this code lives in, so it is correct whether the binary was resolved
+//     from node_modules, a global install, or a source checkout.
+//   - hasNpm(root) is the KIND of repository: does it have a package.json? That decides
+//     how it obtains simt-dev at all — pinned as a devDependency where one exists, a
+//     pinned global install where there is no node_modules to pin in.
+//   - the pin is the version a repository recorded when it adopted simt-dev, stored in
+//     the manifest's projection.version. It is what a global install must match: npm
+//     pins the node_modules copy for us, but nothing pins a global binary, so the gate
+//     compares the running version against the pin and refuses on a mismatch.
+
+import { readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { MANIFEST_FILE } from './name.mjs';
+
+/**
+ * The version of the simt-dev package this code is running from.
+ *
+ * Sync, because the render functions it feeds are sync: a rendered artifact bakes in
+ * the version that produced it, and that must be known before the bytes are written.
+ * A missing or unreadable package.json degrades to 'unknown' rather than throwing —
+ * the same call already tolerates it in `--version`, and a render that cannot read its
+ * own version is not a reason to crash the command that calls it.
+ */
+export function packageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Whether a repository has a package.json, i.e. whether it pins simt-dev as a
+ * devDependency (npm) or must fall back to a global install. Async because the render
+ * call sites that feed it (init, hooks install, the compare stale check) are all async,
+ * and a missing file is an answer (false), not an error.
+ */
+export async function hasNpm(root) {
+  try {
+    await stat(join(root, 'package.json'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the running binary matches the version a repository pinned when it adopted
+ * simt-dev. Returns null when there is nothing to refuse, otherwise a message that
+ * names both versions and the one command that fixes it.
+ *
+ * This is the gate's fail-closed guard against a stale global binary: for a repository
+ * without npm, simt-dev is a global install and the only thing that knows which version
+ * it should be is the pin. A node_modules copy is pinned by npm itself, so its mismatch
+ * is a stale manifest, which `upgrade` refreshes — the remedy is the same either way.
+ *
+ * A manifest with no recorded pin (adopted before the field existed) is skipped, not
+ * failed: there is nothing to compare against, and failing it would turn every pre-0.2
+ * repository into a red gate the moment this check ships.
+ */
+export function assertVersionPin(manifest) {
+  const pin = manifest?.projection?.version;
+  if (!pin || pin === 'unknown') return null;
+  const running = packageVersion();
+  if (running === pin) return null;
+  return `simt-dev version mismatch: ${MANIFEST_FILE} pins ${pin}, the running binary is ${running}`;
+}