simt-dev 0.4.0 → 0.6.0

package/src/compare/row.mjs

@@ -1,4 +1,4 @@
-// The matrix a `simt-dev compare` row is built from: one repo's adoption state.
+// The matrix a `simt compare` row is built from: one repo's adoption state.
 //
 // The shape of a row answers one question - "would this repo behave correctly if
 // an agent followed it today?" - from the four things that can make it not:
@@ -255,7 +255,7 @@ export async function buildRow(path, context) {  const name = path.split('/').fi
     if (region.status === 'drift') {
       // A drift has two causes with different fixes, and the SHA says which. When
       // the recorded SHA matches this simt-dev, the region was hand-edited and
-      // `simt-dev sync --yes` is right; when it does not, the repo is simply behind and the
+      // `simt sync --yes` is right; when it does not, the repo is simply behind and the
       // same command is also right - but the message must not claim a version
       // mismatch when the versions are identical, because that sends the reader
       // looking for a pin that is already correct.
@@ -274,7 +274,7 @@ export async function buildRow(path, context) {  const name = path.split('/').fi
     } else if (region.status === 'current' && row.pinnedSha && row.pinnedSha !== context.expectedSha) {
       // The region matches this simt-dev but the manifest pins an older one. The
       // next sync would stamp the newer SHA silently, so the pin is the thing
-      // that is stale - and it is the value `simt-dev upgrade` reads.
+      // that is stale - and it is the value `simt upgrade` reads.
       problems.push(
         `manifest pins simt-dev ${row.pinnedSha}, this is ${context.expectedSha}; run: ${CLI} upgrade`,
       );

package/src/decisions/index.mjs

@@ -1,4 +1,4 @@
-// The decision index: what `simt-dev rules why` traces back to.
+// The decision index: what `simt rules why` traces back to.
 //
 // Rule bodies cite the decision that settled them inline, as `(ADR-001)`. That
 // citation is the only thing standing between "a rule someone wrote" and "a rule

package/src/distill/distill.mjs

@@ -0,0 +1,246 @@
+// The distiller's orchestrator (plan 0003 R38): one target in, one proposal out.
+//
+// R37 gave this repository a local model client, and R38 is the first consumer of
+// it: distillation is the cheapest thing a local model can do that the
+// deterministic engine cannot — abstractive compression — and the one that most
+// needs the guardrails here, because its output is the kind a reader would paste
+// into a pack and forget to check.
+//
+// Nothing here writes outside `.simt/distilled/`, and nothing here edits a
+// source file (ADR-090, ADR-075). A proposal that a human did not merge is a dead
+// file, which is the intended failure mode: proposals expire, projections do not.
+
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { EXIT, fail } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { loadRegistry } from '../graph/load.mjs';
+import { nearMatches } from '../resolve/near.mjs';
+import { bodyFile, sourcePath } from '../resolve/body.mjs';
+import { resolveWorkspace } from '../workspace.mjs';
+import { readLocalConfig, chatEndpoint } from '../local/config.mjs';
+import { localChat } from '../local/client.mjs';
+import {
+  ENGINE_LOCAL,
+  ENGINE_OUTLINE,
+  buildLocalPrompt,
+  digestOf,
+  outlineSummary,
+  proposalFrontmatter,
+  promptHash,
+  sourceDigest,
+  verifyCitations,
+} from './engine.mjs';
+
+export const DEFAULT_BUDGET = 2048;
+const DISTILL_DIR = '.simt/distilled';
+
+/**
+ * The row's acceptance metric, stated where a caller reads results (ADR-076):
+ * "bench shows distilled body plus references match the full body on R at lower
+ * C, or the feature stays experimental." It is the second of the two until the
+ * bench measures it, so every report says so rather than implying parity.
+ */
+const METRIC_NOTE = 'parity at lower C unmeasured on R; experimental (plan 0003 R38)';
+
+/**
+ * Resolve `<skill|doc>` to an absolute source path.
+ *
+ * A name first: `distill core-rule` is read as the skill that `skills show` would
+ * read, so both commands answering differently is the defect. A path second:
+ * everything else is a file under the root, and one that escapes the root is
+ * refused — a proposal whose provenance names `../../etc` is provenance nobody
+ * should trust.
+ */
+async function resolveTarget(target, root, flags) {
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return { exit: fail(errors[0], EXIT.REGISTRY) };
+
+  const skill = registry.skills.find((s) => s.name === target);
+  if (skill) {
+    const ws = await resolveWorkspace(flags);
+    const full = await sourcePath(skill, ws.root ?? null, root);
+    const readable = full !== null && (full === root || bodyFile(full).startsWith(root + sep));
+    if (!readable) {
+      const near = nearMatches(target, registry.skills.map((s) => s.name));
+      return {
+        exit: fail(
+          `skill "${target}" resolved to ${full ?? 'no body'} and that body is not under ${root}`,
+          EXIT.FAIL,
+          `run ${CLI} skills show ${target} to see how the body resolves, or distill a doc path`,
+        ),
+      };
+    }
+    const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
+    return {
+      path: bodyFile(full),
+      name: canonical ? `${canonical.repo}/${canonical.path}` : skill.name,
+      how: 'skill',
+    };
+  }
+
+  const candidate = isAbsolute(target) ? target : resolve(root, target);
+  if (candidate !== root && !candidate.startsWith(root + sep)) {
+    return {
+      exit: fail(`${target} is outside ${root}`, EXIT.FAIL, 'distill reads docs under the repository root only'),
+    };
+  }
+  try {
+    const text = await readFile(bodyFile(candidate), 'utf8');
+    return {
+      path: candidate,
+      name: relative(root, candidate) || target,
+      how: 'doc',
+      text,
+    };
+  } catch {
+    const near = nearMatches(target, registry.skills.map((s) => s.name));
+    return {
+      exit: fail(
+        `no skill named "${target}" and no file ${relative(root, candidate) ?? target}`,
+        EXIT.FAIL,
+        near.length ? `did you mean the skill ${near.join(', ')}?` : `run ${CLI} skills index`,
+      ),
+    };
+  }
+}
+
+/**
+ * The engine dispatch, including the model path's guardrails.
+ *
+ * `--local` without a usable `local.chat` is a configuration error, not a silent
+ * fallback to the deterministic engine: a caller who asked for the model and got
+ * the outline would read the outline's confidence as the model's — and the
+ * reverse, reading model output as deterministic, is worse.
+ */
+async function runEngine(kind, text, budget, context) {
+  if (kind === ENGINE_OUTLINE) return outlineSummary(text, budget);
+
+  const { root, allowRemote, name } = context;
+  const config = await readLocalConfig(root, { allowRemote });
+  // The shared guard arrived from `local/config.mjs` when the critic became the
+  // second real user of the same rules (plan 0003 R39, ADR-002).
+  const endpoint = chatEndpoint(config);
+  if (endpoint.exit !== undefined) return endpoint;
+
+  const prompt = buildLocalPrompt(name, text, budget);
+  const chat = await localChat(config.chat, {
+    system: 'You compress documents for software agents. Follow the rules the user message states exactly.',
+    prompt,
+    temperature: 0,
+    maxTokens: budget === 0 ? 2048 : Math.min(2048, Math.max(256, Math.ceil(budget / 4))),
+    allowRemote,
+  });
+  if (!chat.ok) {
+    return {
+      exit: fail(
+        `local chat failed: ${chat.error}`,
+        EXIT.FAIL,
+        'fix the endpoint, or run without --local for the deterministic engine',
+      ),
+    };
+  }
+  return { engine: ENGINE_LOCAL, model: chat.model, body: String(chat.content).trim(), prompt };
+}
+
+function parseExistingFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const head = text.split('\n---', 1)[0];
+  const fields = {};
+  for (const line of head.split('\n').slice(1)) {
+    const m = /^([a-z]+):\s?(.*)$/.exec(line);
+    if (m) fields[m[1]] = m[2];
+  }
+  return fields;
+}
+
+function countCitations(text) {
+  return (text.match(/\[L\d+(-L\d+)?\]/g) ?? []).length;
+}
+
+/**
+ * Returns either the report object (ok) or an exit code (fail) — the same shape
+ * the command layer returns, so a failure passes through unchanged.
+ */
+export async function distillTarget(args, flags) {
+  const target = args[0];
+  if (!target) {
+    return fail(
+      'distill needs a skill name or a doc path',
+      EXIT.USAGE,
+      `usage: ${CLI} distill <skill|doc> [--budget <bytes>]`,
+    );
+  }
+
+  const root = resolve(flags.root ?? process.cwd());
+  const source = await resolveTarget(target, root, flags);
+  if (source.exit !== undefined) return source.exit;
+
+  const text = source.text ?? (await readFile(bodyFile(source.path), 'utf8'));
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const budget = Number.isInteger(flags.budget) ? flags.budget : DEFAULT_BUDGET;
+  const allowRemote = flags.allowRemote === true;
+  const engineKind = flags.local === true ? ENGINE_LOCAL : ENGINE_OUTLINE;
+  const digest = digestOf(text, engineKind, budget);
+  const relProposal = `${DISTILL_DIR}/${digest}.md`;
+  const absProposal = join(root, relProposal);
+  const lineCount = text.split('\n').length;
+
+  const cached = flags.refresh === true ? null : await readFile(absProposal, 'utf8').catch(() => null);
+  if (cached !== null) {
+    const fields = parseExistingFrontmatter(cached);
+    return {
+      ok: true,
+      command: 'distill',
+      target: { kind: source.how, source: source.name, bytes, lines: lineCount },
+      digest: sourceDigest(text),
+      engine: fields.engine ?? ENGINE_OUTLINE,
+      budget: Number(fields.budget ?? budget),
+      citations: countCitations(cached),
+      verified: fields.verified !== 'false',
+      metric: { note: METRIC_NOTE },
+      proposal: { path: relProposal, state: 'cached', bytes: Buffer.byteLength(cached, 'utf8') },
+    };
+  }
+
+  const outcome = await runEngine(engineKind, text, budget, { root, allowRemote, name: source.name });
+  if (outcome.exit !== undefined) return outcome.exit;
+
+  const check = verifyCitations(outcome.body, lineCount);
+  const faults = [...check.faults];
+  const bodyBytes = Buffer.byteLength(outcome.body, 'utf8');
+  if (budget > 0 && bodyBytes > budget) {
+    faults.push(`summary is ${bodyBytes} bytes against a ${budget}-byte budget`);
+  }
+
+  const provenance =
+    outcome.engine === ENGINE_LOCAL
+      ? `${ENGINE_LOCAL}:${outcome.model} (prompt ${promptHash(outcome.prompt)})`
+      : ENGINE_OUTLINE;
+  const proposal =
+    proposalFrontmatter({
+      source: source.name,
+      digest,
+      engine: provenance,
+      budget,
+      verified: faults.length === 0,
+    }) + `\n${outcome.body}\n`;
+
+  await mkdir(join(root, DISTILL_DIR), { recursive: true });
+  await writeFile(absProposal, proposal);
+
+  return {
+    ok: true,
+    command: 'distill',
+    target: { kind: source.how, source: source.name, bytes, lines: lineCount },
+    digest: sourceDigest(text),
+    engine: provenance,
+    budget,
+    citations: check.ranges.length,
+    verified: faults.length === 0,
+    ...(faults.length > 0 ? { faults } : {}),
+    metric: { note: METRIC_NOTE },
+    proposal: { path: relProposal, state: 'fresh', bytes: Buffer.byteLength(proposal, 'utf8') },
+  };
+}

package/src/distill/engine.mjs

@@ -0,0 +1,187 @@
+// The distiller's engines (plan 0003 R38).
+//
+// `simt distill` writes a budgeted summary of a skill body or doc, with every claim
+// citing the source line range it rests on. Two engines produce that shape:
+//
+//   - `outline` (default): a deterministic, extractive summary — the heading
+//     skeleton plus the first content of each section, cut to the budget. No
+//     model, no network, byte-stable: the same text at the same budget produces
+//     the same bytes forever (P1, P4).
+//   - `local`: the configured local chat model (R37) proposes a abstractive
+//     summary. It is opt-in (`--local`), loopback-only by default, and its output
+//     is verified against the source before anything is written.
+//
+// Both engines write the same artefact: a *proposal*, never a projection. The
+// proposal file carries its provenance in frontmatter (source, digest, engine,
+// prompt hash for the model path); a human merges it into the pack or repo, and
+// nothing in this module ever edits a source file (ADR-090/ADR-075, principle P2).
+
+import { createHash } from 'node:crypto';
+
+export const ENGINE_OUTLINE = 'outline';
+export const ENGINE_LOCAL = 'local';
+
+/**
+ * The cache key: source digest plus the recipe that shaped the output. Two
+ * proposals of the same text at different budgets are different answers, so one
+ * key carries both rather than letting a second write collide with the first.
+ */
+export function digestOf(text, engine, budget) {
+  const h = createHash('sha256');
+  h.update(`${engine}\0${budget}\0${text}`);
+  return `sha256-${h.digest('hex').slice(0, 16)}`;
+}
+
+/** Same function for the source itself, where the recipe does not apply. */
+export function sourceDigest(text) {
+  return `sha256-${createHash('sha256').update(text).digest('hex').slice(0, 16)}`;
+}
+
+/** The hash of the prompt sent to a model engine — the provenance P2 asks for. */
+export function promptHash(prompt) {
+  return `sha256-${createHash('sha256').update(prompt).digest('hex').slice(0, 16)}`;
+}
+
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^#{1,6}\s/;
+
+/**
+ * Build the prompt a local model receives (ENGINE_LOCAL only).
+ *
+ * The source ships with line numbers printed, because the only citation format
+ * the verifier can check is `[L<n>-<m>]` against those numbers. A model asked to
+ * "cite the source" but given unnumbered text can only guess, and every guess is
+ * a citation that looks true and cannot be checked — which is the defect this
+ * command exists to prevent.
+ */
+export function buildLocalPrompt(fileName, text, budget) {
+  const numbered = text
+    .split('\n')
+    .map((line, i) => `${i + 1}: ${line}`)
+    .join('\n');
+  return [
+    'Distill the document below into what an agent must know to act on it.',
+    `The summary must not exceed ${budget} bytes. Rules:`,
+    '- Every claim ends with a citation to a source line range, written [L12] or [L12-L15], using the line numbers printed below.',
+    '- Cite only lines that exist in the source. Never cite a line you cannot see.',
+    '- Copy commands, paths, thresholds and names verbatim; do not paraphrase them.',
+    '- Do not invent content, and do not add advice the source does not contain.',
+    `- Reply with the summary only; nothing else.`,
+    '',
+    `SOURCE ${fileName}`,
+    numbered,
+  ].join('\n');
+}
+
+/**
+ * The deterministic extractive engine (ENGINE_OUTLINE).
+ *
+ * Selection, readable as a score: every heading first (they are the document's
+ * own structure), then the immediate non-empty content under each heading. The
+ * result is the document in its own words, in document order, at a fraction of
+ * the bytes — which is the comparison the acceptance criterion asks the bench to
+ * run, and the honest thing an offline engine can claim.
+ *
+ * Bounds: the returned body never exceeds `budget` bytes (0 = unlimited), and
+ * every line it renders carries a citation the verifier below can check.
+ */
+export function outlineSummary(text, budget) {
+  const lines = text.split('\n');
+  const picks = [];
+  let inline = false;
+
+  // Pass 1: headings.
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (FENCE.test(line)) inline = !inline;
+    if (inline) continue;
+    if (HEADING.test(line)) picks.push(i);
+  }
+
+  // Pass 2: the first content line under each heading.
+  for (const i of [...picks]) {
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (FENCE.test(lines[j])) break;
+      if (HEADING.test(lines[j])) break;
+      if (lines[j].trim() === '') continue;
+      picks.push(j);
+      break;
+    }
+  }
+
+  if (picks.length === 0 && lines.some((l) => l.trim() !== '')) {
+    // No headings at all: a doc of prose. The whole thing is one section, so the
+    // first content line is the citation anchor rather than an empty summary.
+    const first = lines.findIndex((l) => l.trim() !== '' && !FENCE.test(l));
+    if (first !== -1) picks.push(first);
+  }
+
+  picks.sort((a, b) => a - b);
+
+  const body = [];
+  let used = 0;
+  for (const i of picks) {
+    const text = lines[i].trimEnd();
+    const bullet = `>[L${i + 1}] ${text}`;
+    const cost = Buffer.byteLength(`${bullet}\n`, 'utf8');
+    if (budget > 0 && used + cost > budget) break;
+    used += cost;
+    body.push(bullet);
+  }
+
+  return { engine: ENGINE_OUTLINE, body: body.join('\n'), citations: body.length, budgetUsed: used };
+}
+
+/**
+ * Check a summary's citations against the source that supposedly backs them.
+ *
+ * A citation naming a line past the end of the source is fabricated; a summary
+ * with any such citation is returned with `--json` detailed faults and is never
+ * silently trusted. The proposal still writes (it is only a proposal), but its
+ * provenance records `verified: false` so a reader cannot mistake it for checked
+ * output (ADR-083).
+ */
+export function verifyCitations(body, sourceLineCount) {
+  const faults = [];
+  const ranges = [];
+  const re = /\[L(\d+)(?:-L?(\d+))?\]/g;
+  let match;
+  while ((match = re.exec(body)) !== null) {
+    const start = Number(match[1]);
+    const end = match[2] === undefined ? start : Number(match[2]);
+    const kind =
+      start < 1 || start > sourceLineCount
+        ? `start`
+        : end < start
+          ? `order`
+          : end > sourceLineCount
+            ? `end`
+            : null;
+    if (kind !== null) {
+      faults.push(`citation [L${start}-L${end}] ${kind} outside the source (1..${sourceLineCount})`);
+      continue;
+    }
+    ranges.push({ start, end });
+  }
+  return { ok: faults.length === 0, ranges, faults };
+}
+
+/** The proposal file's frontmatter. No wall-clock value here: byte-stable (P4). */
+export function proposalFrontmatter({ source, digest, engine, budget, prompt, verified, verdict, advisory }) {
+  return [
+    '---',
+    `source: ${source}`,
+    `digest: ${digest}`,
+    `engine: ${engine}`,
+    `budget: ${budget}`,
+    prompt ? `prompt: ${prompt}` : null,
+    verdict ? `verdict: ${verdict}` : null,
+    advisory ? 'advisory: true' : null,
+    verified === false ? 'verified: false' : 'verified: true',
+    'status: proposal',
+    '---',
+    '',
+  ]
+    .filter((l) => l !== null)
+    .join('\n');
+}

package/src/distribute/release.mjs

@@ -0,0 +1,142 @@
+// The binary channel: what a release publishes, where a repository keeps its copy,
+// and the one command that gets it there.
+//
+// This module is the single place that knows those facts, because three generated
+// surfaces must agree on them and they are rendered from different call sites: the
+// locator block (src/locate.mjs) checks a path, the hook shim's remedy prints a
+// download command, and the CI workflow renders the same download as a step. A
+// second copy of the asset name or the URL is a copy that drifts, and a drifted
+// remedy tells a reader to fetch bytes that do not exist.
+//
+// The channel is a fourth beside npm, PyPI and Homebrew (ADR-058), and unlike the
+// other three it is the one that needs no toolchain at all: the npm channel needs
+// npm, the wheel needs a Python, and the formula - until this release - needed
+// node. The binary is a file. That is the whole design (ADR-098), and it is why
+// the locator checks a path in the repository before it checks PATH: the bytes a
+// repository pinned are the bytes its gate runs, on a machine with nothing else.
+
+import { CLI, PACKAGE_NAME } from '../name.mjs';
+
+// The GitHub repository the release is published from. A fact about where the
+// bytes come from, like the npm registry host: a reader outside this estate
+// reads it as a URL, not as an organisation. Not exported: the only surface a
+// caller needs is the URL, and a second copy of the slug is a copy that drifts.
+const REPO_SLUG = 'QuazarMedia/simt-dev';
+
+/** The platforms the release builds. The set is small on purpose: it is the set
+ *  the locator's remedy and the CI step can name, and a platform in this list that
+ *  the release does not build is a remedy that downloads a 404. */
+export const TARGETS = ['darwin-arm64', 'darwin-x64', 'linux-x64'];
+
+// Where a repository keeps the binary it pinned, relative to its top level.
+// Beneath `.simt`, like every other per-repo state this tool writes, so a reader
+// who has seen one knows where to look for all of them. The name is the command,
+// not the package: the reader types one program and this is it, the same way
+// `bin/simt.mjs` is it on npm.
+const LOCAL_BIN_NAME = CLI;
+
+/** The directory a repository keeps its pinned binary in, relative to its top
+ *  level. Exported because a caller that installs the binary must create it and
+ *  has no other source for the fact. */
+export const LOCAL_BIN_DIR = '.simt/bin';
+
+/** The path the locator checks, relative to the repository's top level. */
+export const LOCAL_BIN = `${LOCAL_BIN_DIR}/${LOCAL_BIN_NAME}`;
+
+/**
+ * The release asset name for a version and a target.
+ *
+ * The package name, not the command: it sits beside its siblings in the release
+ * and next to the npm tarball `simt-dev-0.5.0.tgz`, where one name for the project
+ * is what a reader matching names expects.
+ *
+ * @param {string} version x.y.z
+ * @param {string} osArch one of TARGETS
+ * @returns {string} e.g. `simt-dev-0.5.0-darwin-arm64`
+ */
+export function assetName(version, osArch) {
+  if (!TARGETS.includes(osArch)) throw new Error(`unknown target ${osArch}; known: ${TARGETS.join(', ')}`);
+  return `${PACKAGE_NAME}-${version}-${osArch}`;
+}
+
+/**
+ * The asset name with the platform left for the shell to fill in at runtime.
+ *
+ * The CI step and the remedy both run on a machine whose platform is not known
+ * where the text was written, so the name is completed from `uname` or the
+ * runner there. One template shared with {@link assetName} keeps the two from
+ * drifting: a name rendered here that the release does not publish is a 404.
+ *
+ * @param {string} version x.y.z
+ * @returns {string} e.g. `simt-dev-0.5.0-$os-$arch`, for a shell with $os and $arch set
+ */
+export function assetNameExpr(version) {
+  return `${PACKAGE_NAME}-${version}-$os-$arch`;
+}
+
+/**
+ * The URL the release serves a version's assets from.
+ *
+ * @param {string} version x.y.z
+ * @returns {string}
+ */
+export function releaseBase(version) {
+  return `https://github.com/${REPO_SLUG}/releases/download/v${version}`;
+}
+
+/**
+ * The URL the release serves one asset from.
+ *
+ * @param {string} version x.y.z
+ * @param {string} osArch one of TARGETS
+ * @returns {string}
+ */
+export function releaseUrl(version, osArch) {
+  return `${releaseBase(version)}/${assetName(version, osArch)}`;
+}
+
+/**
+ * The download a reader without npm runs from their repository's top level: fetch
+ * the asset this machine needs and put it where the locator looks.
+ *
+ * One line on purpose - it is rendered into a remedy that a reader copies from an
+ * error message, and a multi-line script in an error message is not copied. The
+ * platform is derived rather than baked in, because the remedy lives in a file
+ * that is committed and shared: a URL rendered for the machine that wrote the
+ * shim would be a 404 for the colleague who clones it.
+ *
+ * The transport is TLS from the release, and the version the bytes report is
+ * checked against the repository's pin by the dispatcher itself (ADR-098), so
+ * the remedy does not also carry a checksum: it is the shortest command that
+ * reaches a working state, and the gate re-verifies what it runs.
+ *
+ * @param {string} version x.y.z
+ * @returns {string} POSIX sh, run from the repository's top level
+ */
+export function localInstall(version) {
+  return [
+    `mkdir -p ${LOCAL_BIN_DIR}`,
+    ...platformLines(),
+    `curl -fsSL "${releaseBase(version)}/${assetNameExpr(version)}" -o ${LOCAL_BIN}`,
+    `chmod +x ${LOCAL_BIN}`,
+  ].join(' && ');
+}
+
+/**
+ * The two shell lines that derive this machine's release target at run time.
+ *
+ * `uname -m` answers `x86_64` on both platforms' Intel builds and `arm64` on
+ * Apple Silicon, so one substitution covers the naming gap. Both the remedy and
+ * the generated CI step name their asset from these lines: the text is committed
+ * and shared, so a URL baked for the machine that wrote it is a 404 for the
+ * colleague who clones it, and a workflow expression interpolated into a command
+ * substitution is worse - the CI step once rendered `os=$('${{ runner.os }}' …)`,
+ * which the runner substitutes to `os=$('Linux' …)` and `set -eu` refuses, so the
+ * install failed on every run in the one repository kind this channel exists for.
+ * The step is executed, not pattern-matched, in test/binary.test.mjs.
+ *
+ * @returns {string[]} POSIX sh lines assigning `$os` and `$arch`
+ */
+export function platformLines() {
+  return [`os=$(uname -s | tr A-Z a-z)`, `arch=$(uname -m | sed "s/x86_64/x64/")`];
+}

package/src/graph/load.mjs

@@ -35,14 +35,15 @@ function defaultRegistryPath() {
 /**
  * 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
+ * 1. The package root, when it holds one. In a source checkout that is how the tool
+ *    finds its own registry, sitting next to the code that reads it. An installed
+ *    package holds no registry (ADR-061 ruling 2): the catalogue is workspace data,
+ *    and an install serving another estate's skills to an adopting repository would
+ *    be a confident wrong answer. This tier is a source-checkout convenience; when it
+ *    is empty, resolution falls through to the workspace member or an honest absence.
+ * 2. A member of the resolved workspace, when exactly one holds one: reachable in a checkout
+ *    whose package root holds no registry. 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

package/src/hooks/dispatcher.mjs

@@ -68,8 +68,9 @@ 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.
+  // without npm that is the release binary in `.simt/bin` (ADR-098), 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.