simt-dev 0.6.3 → 0.7.1

package/src/bench/variants.mjs

@@ -3,14 +3,14 @@
 // Discovers `simt-variants` slots across applicable rules, runs candidate
 // variants on the 10-task canary suite (escalating when significant), records
 // the winning variant with `{winner, variant, model, harness, dR, dC, n, p}`
-// in `simt-dev.lock.json`, and re-opens the experiment whenever the target
+// in `simt.lock.json`, and re-opens the experiment whenever the target
 // model or harness changes.
 
 import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
 import { extractVariantsFromRule, readLockedVariants } from '../kernel/variants.mjs';
-import { MANIFEST_FILE, STATE_DIR } from '../name.mjs';
+import { LOCK_FILE, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { writeLockVariants } from '../projection/lock.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
@@ -21,12 +21,22 @@ import { CANARY_ALPHA, DEFAULT_CANARY_SIZE, DEL_R_TOLERANCE, shouldEscalateCanar
 import {
   DEFAULT_BOOTSTRAP_SAMPLES,
   DEFAULT_BOOTSTRAP_SEED,
+  collapseArmByTask,
   compareArms,
   evaluateRunRecord,
+  holmAdjust,
   loadPrices,
   loadRunRecords,
 } from './report.mjs';
 
+/**
+ * Harnesses that grade, not answer: `gold` applies the oracle patch and `noop` does
+ * nothing (`src/bench/adapters.json`, `kind: "builtin"`). Their runs measure the
+ * grader, not the rule text, so they must never close a variant experiment by
+ * writing a lock entry (Q45). A test asserts this set matches the adapter table.
+ */
+export const BUILTIN_HARNESSES = new Set(['gold', 'noop']);
+
 /**
  * Discover every `simt-variants` slot across applicable rules for `root`.
  */
@@ -131,6 +141,19 @@ export async function applyVariantInWorkspace(workDir, variant) {
   delete nextManifest.mode;
   await writeFile(manifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
 
+  // plan() writes the lock as a target (Q29). Left behind, it records this arm's
+  // winner as locked, and the next selectRuleVariants on the same tree reads the
+  // experiment as closed and never runs the runner. Restore it, like the manifest.
+  const lockPath = join(workDir, LOCK_FILE);
+  let originalLockBytes = null;
+  let hadLock = false;
+  try {
+    originalLockBytes = await readFile(lockPath, 'utf8');
+    hadLock = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
   const planned = await plan(workDir, {
     variants: { [slotId]: { winner: variantKey } },
   });
@@ -146,30 +169,36 @@ export async function applyVariantInWorkspace(workDir, variant) {
   } else if (originalManifestBytes !== null) {
     await writeFile(manifestPath, originalManifestBytes, 'utf8');
   }
+  if (!hadLock) {
+    await unlink(lockPath).catch(() => {});
+  } else {
+    await writeFile(lockPath, originalLockBytes, 'utf8');
+  }
 }
 
+/**
+ * Mean per-task R and C for one arm's evaluated runs.
+ *
+ * `collapseArmByTask` is the shared per-task aggregation: the evaluated rows carry
+ * the cost in `C`, and the old body summed `costUsd` — a field the rows never had —
+ * so C was NaN and the cost rank degenerated to a key tie-break (Q45).
+ */
 function summarizeEvaluated(evaluated) {
-  if (evaluated.length === 0) {
-    return { n: 0, R: 0, C: 0 };
-  }
-  const byTask = new Map();
-  for (const row of evaluated) {
-    const list = byTask.get(row.task) ?? [];
-    list.push(row);
-    byTask.set(row.task, list);
-  }
+  const tasks = collapseArmByTask(evaluated);
+  if (tasks.length === 0) return { n: 0, R: 0, C: null };
   let sumR = 0;
   let sumC = 0;
-  for (const list of byTask.values()) {
-    sumR += list.reduce((a, x) => a + x.R, 0) / list.length;
-    sumC += list.reduce((a, x) => a + x.costUsd, 0) / list.length;
+  let costComplete = true;
+  for (const t of tasks) {
+    sumR += t.R;
+    if (t.C === null) costComplete = false;
+    else sumC += t.C;
   }
-  const n = byTask.size;
-  return { n, R: sumR / n, C: sumC / n };
+  return { n: tasks.length, R: sumR / tasks.length, C: costComplete ? sumC / tasks.length : null };
 }
 
 /**
- * Run or evaluate variant selection on the canary suite and record winners in `simt-dev.lock.json`.
+ * Run or evaluate variant selection on the canary suite and record winners in `simt.lock.json`.
  */
 export async function selectRuleVariants(
   root,
@@ -267,19 +296,31 @@ export async function selectRuleVariants(
       for (const { slot } of openStates) {
         const baseArm = variantArmName(slot.slotId, slot.baseline);
         const baseRecs = canaryEvaluated.filter((r) => r.arm === baseArm);
+        const slotComps = [];
         for (const key of Object.keys(slot.variants)) {
           if (key === slot.baseline) continue;
           const candArm = variantArmName(slot.slotId, key);
           const candRecs = canaryEvaluated.filter((r) => r.arm === candArm);
           if (baseRecs.length > 0 && candRecs.length > 0) {
-            const comp = compareArms(baseArm, baseRecs, candArm, candRecs, { samples, seed });
-            if (shouldEscalateCanary(comp, { alpha: CANARY_ALPHA })) {
-              includeBaseline.add(baseArm);
-              armsToEscalate.push(candArm);
-              escalatedArms.add(candArm);
-            }
+            slotComps.push({
+              candArm,
+              comp: compareArms(baseArm, baseRecs, candArm, candRecs, { samples, seed }),
+            });
           }
         }
+        // Family = every variant of this slot versus its baseline: testing several
+        // variants at α 0.05 each inflates the false-positive rate, so the p-values
+        // are Holm-adjusted before the escalation decision (review 0003 Q46).
+        const adjusted = holmAdjust(
+          slotComps.map(({ comp }) => Math.min(comp.rTest.pValue, comp.wilcoxon.pValue)),
+        );
+        slotComps.forEach(({ candArm, comp }, i) => {
+          if (shouldEscalateCanary(comp, { alpha: CANARY_ALPHA, pValue: adjusted[i] })) {
+            includeBaseline.add(baseArm);
+            armsToEscalate.push(candArm);
+            escalatedArms.add(candArm);
+          }
+        });
       }
       const fullEscalationArms = [...includeBaseline, ...armsToEscalate];
       if (fullEscalationArms.length > 0) {
@@ -321,6 +362,7 @@ export async function selectRuleVariants(
         reason,
         measured: true,
         winner: winnerKey,
+        locked: true,
         model: lockedEntry.model ?? resolvedModel,
         harness: lockedEntry.harness ?? harness,
         dR: Number(lockedEntry.dR ?? 0),
@@ -367,6 +409,7 @@ export async function selectRuleVariants(
         reason,
         measured: false,
         winner: slot.baseline,
+        locked: false,
         model: resolvedModel,
         harness,
         dR: 0,
@@ -377,13 +420,16 @@ export async function selectRuleVariants(
       continue;
     }
 
-    // Rank variants: higher R (beyond tolerance), then lower C, then fewer bytes, then key.
+    // Rank variants: higher R (beyond tolerance), then lower C (an unknown cost is
+    // worst — it cannot be ranked cheaper), then fewer bytes, then key.
     const ranked = [...candidates].sort((a, b) => {
       if (Math.abs(b.summary.R - a.summary.R) > DEL_R_TOLERANCE) {
         return b.summary.R - a.summary.R;
       }
-      if (Math.abs(a.summary.C - b.summary.C) > 1e-9) {
-        return a.summary.C - b.summary.C;
+      const ca = a.summary.C === null ? Number.POSITIVE_INFINITY : a.summary.C;
+      const cb = b.summary.C === null ? Number.POSITIVE_INFINITY : b.summary.C;
+      if (Math.abs(ca - cb) > 1e-9) {
+        return ca - cb;
       }
       if (a.bytes !== b.bytes) return a.bytes - b.bytes;
       return a.key.localeCompare(b.key);
@@ -397,10 +443,13 @@ export async function selectRuleVariants(
 
     if (best.key !== slot.baseline && best.comparison) {
       dR = Number(best.comparison.deltas.R.toFixed(4));
-      dC = Number(best.comparison.deltas.C.toFixed(4));
+      dC =
+        best.comparison.deltas.C === null
+          ? 0
+          : Number(best.comparison.deltas.C.toFixed(4));
       n = best.comparison.pairedTasks;
       p = Number(
-        Math.min(best.comparison.mcnemar.pValue, best.comparison.wilcoxon.pValue).toFixed(4),
+        Math.min(best.comparison.rTest.pValue, best.comparison.wilcoxon.pValue).toFixed(4),
       );
     } else {
       const runnerUp = ranked.find((c) => c.key !== slot.baseline && c.comparison);
@@ -409,17 +458,33 @@ export async function selectRuleVariants(
       }
     }
 
-    const lockEntry = {
-      winner: best.key,
-      variant: best.key,
-      model: resolvedModel,
-      harness,
-      dR,
-      dC,
-      n,
-      p,
-    };
-    nextVariantsLock[slot.slotId] = lockEntry;
+    // A non-baseline winner locks only when it is significant AND non-inferior
+    // (Q45): p below the canary alpha, and dR within the deletion tolerance.
+    // Anything else locks the baseline: the experiment ran, and its conclusion is
+    // "keep what we had" - recorded, so the next run on this model and harness
+    // reads it as closed instead of re-measuring.
+    const significant =
+      best.key !== slot.baseline &&
+      best.comparison !== null &&
+      p < CANARY_ALPHA &&
+      dR >= -DEL_R_TOLERANCE;
+    const winnerKey = significant ? best.key : slot.baseline;
+
+    // Built-in harnesses grade, they do not answer: their runs must not close the
+    // experiment, so no lock entry is written for them and the next run re-measures
+    // (Q45). The result still reports the measured best, flagged `locked: false`.
+    if (!BUILTIN_HARNESSES.has(harness)) {
+      nextVariantsLock[slot.slotId] = {
+        winner: winnerKey,
+        variant: winnerKey,
+        model: resolvedModel,
+        harness,
+        dR,
+        dC,
+        n,
+        p,
+      };
+    }
 
     results.push({
       slotId: slot.slotId,
@@ -430,7 +495,14 @@ export async function selectRuleVariants(
       reopened,
       reason,
       measured: true,
-      ...lockEntry,
+      winner: BUILTIN_HARNESSES.has(harness) ? best.key : winnerKey,
+      locked: significant && !BUILTIN_HARNESSES.has(harness),
+      model: resolvedModel,
+      harness,
+      dR,
+      dC,
+      n,
+      p,
     });
   }
 

package/src/brief/assemble.mjs

@@ -34,7 +34,10 @@
 // command and the tool leave it on. It is inert either way in a repository that declared no
 // servers.
 
+import { join } from 'node:path';
+
 import { CLI, STATE_DIR } from '../name.mjs';
+import { parse as parseRegion } from '../projection/markers.mjs';
 import { DEFAULT_BRIEF_BYTES, buildPacket, collect } from './packet.mjs';
 import { classifyTask, cardVerbs } from './kind.mjs';
 import { briefAdvice } from '../advice/advice.mjs';
@@ -81,22 +84,38 @@ const MAP_FACTOR = 8;
  * space is never part of a task's scope.
  */
 
-/** Every file git tracks that carries a generated region, one `git grep` away. */
+/**
+ * Every file git tracks that carries a generated region, one `git grep` away.
+ *
+ * A file that merely mentions the marker is not carrying a region: a rule file, a review
+ * and this test all quote `simt:begin`, and warning that they are generated sends a reader
+ * to edit a source file that has no generated bytes at all (review 0003 Q52). The grep is
+ * only the candidate list; the region parser decides.
+ */
 async function generatedRegions(root) {
   const { execFile } = await import('node:child_process');
   const { promisify } = await import('node:util');
+  const { readFile } = await import('node:fs/promises');
+  let candidates;
   try {
     const { stdout } = await promisify(execFile)(
       'git',
       ['grep', '-lF', '--', `${'simt'}:begin`],
       { cwd: root, maxBuffer: 8 << 20 },
     );
-    return stdout.split('\n').filter((line) => line.length > 0).sort();
+    candidates = stdout.split('\n').filter((line) => line.length > 0).sort();
   } catch {
     // No match is exit 1, and a directory that is not a repository fails too. Both mean
     // the same thing to a reader: no generated region was found to warn about.
     return [];
   }
+  const carrying = [];
+  for (const path of candidates) {
+    const text = await readFile(join(root, path), 'utf8').catch(() => null);
+    if (text === null) continue;
+    if (parseRegion(text, 'html').status === 'ok') carrying.push(path);
+  }
+  return carrying;
 }
 
 /**
@@ -113,6 +132,9 @@ async function generatedRegions(root) {
  * @param {boolean} [options.build] whether an empty index may be built here
  * @param {boolean} [options.federate] whether a declared external server may be asked one
  *   question; a delivered packet turns it off to keep its 300 ms bar
+ * @param {string[]} [options.commands] the dispatchable command paths (`COMMANDS`). A
+ *   decision's `Affects:` token is a command only when the tool has that command, so a
+ *   packet that does not know them reports every one of them as unresolved
  * @returns a packet, or `{ error }` carrying the exit code a failure already reported, or
  *   `{ cold: true }` when the index is empty and this caller may not build one
  */
@@ -124,6 +146,7 @@ export async function assembleBrief({
   flags = {},
   build = true,
   federate = true,
+  commands = [],
 } = {}) {
   const named = paths !== null;
   const dirty = (await dirtyPaths(root)).filter((path) => !path.startsWith(`${STATE_DIR}/`));
@@ -132,6 +155,7 @@ export async function assembleBrief({
   const graph = await loadGraph(root, { build });
   if (graph.error) return { error: graph.error };
   if (graph.cold) return { cold: true };
+  const graphStale = graph.stale === true;
   const { files, symbols, edges, fts = [], embeddings = [] } = graph;
   const filePaths = new Set(files.map((file) => file.path));
 
@@ -150,6 +174,11 @@ export async function assembleBrief({
       why: ['an unasked question has no answer to be short of'],
     });
   }
+  if (graphStale) {
+    packet.add('CAUTIONS', 'the index predates the current tree, so files added or removed since the last build are missing or ghosted', {
+      why: ['this caller may not rebuild the index; run a command that can before quoting the file list'],
+    });
+  }
 
   const repo = await fingerprint(root);
   const card = await commandCard({ root, manifest: repo.manifest ?? null, stack: repo.stack, facts: repo.facts });
@@ -181,6 +210,15 @@ export async function assembleBrief({
         })
       : null;
   const ranked = rankFiles({ files, symbols, edges, fts, bm25, embeddings, queryVector, task });
+  // An empty match is a different answer from a weak one: the ranking is then the graph
+  // hub, which is what a reader who asked about `zebracorn` must not read as a hit
+  // (review 0003 Q52).
+  const matched = ranked.filter((row) => (row.score ?? 0) > 0).length;
+  if (task.trim().length > 0 && matched === 0) {
+    packet.add('CAUTIONS', 'matched 0: no file or symbol mentions this task, so FILES is the graph hub rather than a match', {
+      why: ['an answer to a graph-shaped question is not an answer to this task'],
+    });
+  }
   const rendered = renderMap(ranked, symbols, { level: 'names', budget: budget > 0 ? budget * MAP_FACTOR : 0 });
   for (const line of rendered.text.split('\n')) {
     packet.add('FILES', line, { why: ['ranked by the task words against the import graph'] });
@@ -227,7 +265,10 @@ export async function assembleBrief({
   const records = await decisionRecords(root);
   const ctx = {
     files: filePaths,
-    commands: new Set(card.lines.map((line) => line.command)),
+    // The card's lines are shell commands (`npm run test`); a decision's Affects token is
+    // a command of this tool. Passing only the card's list made every `simt …` token
+    // unresolved — 47 false cautions on this repository (review 0003 Q52).
+    commands: new Set([...card.lines.map((line) => line.command), ...commands]),
     roots: sourceRoots([...filePaths]),
   };
   const decisions = new Map();

package/src/ci/workflow.mjs

@@ -52,6 +52,7 @@ import { renderLocator } from '../locate.mjs';
 import { CLI } from '../name.mjs';
 import { packageVersion } from '../package-version.mjs';
 import { LOCAL_BIN, LOCAL_BIN_DIR, assetNameExpr, localInstall, platformLines, releaseBase } from '../distribute/release.mjs';
+import { installCommands as nodeInstallCommands } from '../ecosystem/node-runner.mjs';
 
 /** Directory whose presence means this repo runs GitHub Actions. */
 export const WORKFLOWS_DIR = '.github/workflows';
@@ -166,7 +167,7 @@ function checkoutFull() {
  *  to. The own gate also varies the platforms and the Node versions, because this
  *  package is the one whose floor and whose ADR-012 claim have to hold on more than
  *  the minimum. */
-function skeleton(name, steps, { matrix = null } = {}) {
+function skeleton(name, steps, { matrix = null, timeoutMinutes = 5, gateMain = false } = {}) {
   const axes = matrix
     ? Object.entries(matrix)
         .map(([axis, values]) => `        ${axis}: [${values.map((v) => `'${v}'`).join(', ')}]`)
@@ -181,9 +182,22 @@ function skeleton(name, steps, { matrix = null } = {}) {
   // it is written escaped, the same way the `concurrency` line below spells its own two.
   const runner = matrix?.os ? '\${{ matrix.os }}' : 'ubuntu-latest';
   const job = matrix?.node ? '\${{ matrix.os }} node \${{ matrix.node }}' : name;
-  return `name: ${name}
-
-# Pull requests only, and that is a decision rather than a default.
+  // Two trigger blocks, because the two copies answer different questions. An
+  // adopting repository merges through pull requests, which is where its gate runs.
+  // This repository merges locally, so a merge never opens a pull request: without a
+  // push trigger the commit that lands on `main` is the one no gate ever ran on
+  // (review 0003 Q57). Each block ships only in the copy whose claim it states.
+  const trigger = gateMain
+    ? `# Pull requests ask whether a change may merge; a push to \`main\` asks whether
+# what already merged is sound. This repository merges locally, so a merge never
+# opens a pull request — without the second trigger the commit that lands on
+# \`main\` is the one no gate ran on.
+on:
+  pull_request:
+  push:
+    branches: [main]
+`
+    : `# Pull requests only, and that is a decision rather than a default.
 #
 # A gate that runs on every push re-runs itself for every commit that pushes a
 # branch forward, including the ones nobody asked it about, and its verdict has to
@@ -193,7 +207,10 @@ function skeleton(name, steps, { matrix = null } = {}) {
 # on \`main\` is whatever CI the repository already has there.
 on:
   pull_request:
+`;
+  return `name: ${name}
 
+${trigger}
 # Read-only is enough to check a repo, and a gate job does not need to write to it.
 permissions:
   contents: read
@@ -206,7 +223,7 @@ jobs:
   check:
     name: ${job}
     runs-on: ${runner}
-${strategy}    timeout-minutes: 5
+${strategy}    timeout-minutes: ${timeoutMinutes}
     steps:
 ${steps}`;
 }
@@ -253,7 +270,7 @@ function indent(text, spaces) {
  * @param {{own?: boolean}} [options]
  * @returns {string} YAML, LF-terminated
  */
-export function renderWorkflow({ own = false, npm = true, version } = {}) {
+export function renderWorkflow({ own = false, npm = true, manager = null, version } = {}) {
   if (own) {
     const floor = nodeFloor();
     return `${header(true)}${skeleton(
@@ -267,7 +284,7 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
         '      - name: tests',
         '        run: npm test',
         '      - name: skill registry lint',
-        '        run: node bin/simt.mjs graph lint',
+        '        run: npm run lint',
         '      - name: the gate copy in this repo is current',
         // The drift this exception exists to prevent, checked where it would be caught.
         // Without it a template change lands with the copy still describing the old
@@ -281,11 +298,24 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
       // sentence was false in the one repository that could have made it true, and no
       // check read it - the package declares `os` for npm to enforce, and nothing here
       // ever ran a test on a second platform.
-      { matrix: { os: ['ubuntu-latest', 'macos-latest'], node: [floor, '24', '26'] } },
+      // The slowest leg (macOS, full suite plus the registry lint) ran 4 min 28 s
+      // against a 5-minute timeout, so the timeout that was meant to bound a hang
+      // was about to fail a passing run instead. 15 leaves the hang bounded and the
+      // run alone; the sharding that would make it short again is Q92, not this row.
+      //
+      // `gateMain` because this repository merges locally: `pull_request` alone left
+      // the one commit that reached `main` ungated (review 0003 Q57).
+      { matrix: { os: ['ubuntu-latest', 'macos-latest'], node: [floor, '24', '26'] }, timeoutMinutes: 15, gateMain: true },
     )}\n`;
   }
 
   const v = version ?? packageVersion();
+  // Q31: the install step names the repo's own manager. `manager` wins over the
+  // legacy `npm` boolean so old callers keep their bytes; a Node repo installs
+  // with its lockfile's frozen command, anything else takes the release binary.
+  // The resolver row also decides setup-node (bun ships its own runtime).
+  const nodeManager = manager ?? (npm ? 'npm' : null);
+  const nodeInstall = nodeManager ? nodeInstallCommands(nodeManager) : null;
   // The install step is the whole of S35's consumer CI: a repository with npm pins
   // simt-dev as a devDependency and `npm ci` restores it; one without (Gradle,
   // Connect IQ) has no node_modules to pin in, so CI downloads the release binary
@@ -301,11 +331,11 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
   // `${{ runner.* }}` expression: an expression substituted into `$( … )` is a
   // command substitution trying to execute "Linux", which set -eu refuses - the
   // install would fail on every run in the one repository kind this channel is for.
-  const install = npm
+  const install = nodeInstall
     ? [
         '      - name: install dependencies',
-        '        # `npm ci` needs a lockfile; a repo without one is still gated, not skipped.',
-        '        run: npm ci || npm install',
+        `        # \`${nodeInstall.install}\` needs a lockfile; a repo without one is still gated, not skipped.`,
+        `        run: ${nodeInstall.install} || ${nodeInstall.fallback}`,
       ]
     : [
         '      - name: install the pinned gate binary',
@@ -329,8 +359,9 @@ mkdir -p ${LOCAL_BIN_DIR}
 mv "$asset" ${LOCAL_BIN}
 chmod +x ${LOCAL_BIN}`, 10),
       ];
-  const remedy = npm
-    ? `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`
+  const addDev = { npm: `npm i -D ${PACKAGE_NAME}`, pnpm: `pnpm add -D ${PACKAGE_NAME}`, yarn: `yarn add -D ${PACKAGE_NAME}`, bun: `bun add -d ${PACKAGE_NAME}` }[nodeManager] ?? null;
+  const remedy = nodeInstall && addDev
+    ? `REMEDY run: ${addDev}   (the gate runs from the pinned dependency)`
     : `REMEDY run: ${localInstall(v)}   (the gate runs from the release binary in .simt/bin)`;
   const locator = renderLocator('check --root "$ROOT"', { remedy });
   return `${header(false)}${skeleton(
@@ -338,7 +369,8 @@ chmod +x ${LOCAL_BIN}`, 10),
     [
       uses('checkout'),
       // The binary branch has no setup-node: see the install step above.
-      ...(npm ? [setupNode(nodeFloor())] : []),
+      // Q31: bun ships its own runtime, so only managers that need Node get it.
+      ...(nodeInstall && nodeInstall.setupNode ? [setupNode(nodeFloor())] : []),
       ...install,
       `      - name: ${CLI} check`,
       '        run: |',

package/src/cli.mjs

@@ -0,0 +1,45 @@
+// The CLI proper, imported by `bin/simt.mjs` after the runtime floor is checked.
+//
+// It lives here rather than in `bin/` because a static import in the entry point is
+// evaluated before the entry point's own code: the version check could not run first,
+// and an old Node failed inside the module graph instead of saying which version it
+// needed (review 0003 Q54).
+
+import { parse, rawJsonFlag } from './argv.mjs';
+import { EXIT, fail, jsonFailMode, jsonIndentDefault } from './output/index.mjs';
+
+try {
+  const argv = process.argv.slice(2);
+  const parsed = parse(argv);
+  if (!parsed.ok) {
+    // The flags do not exist yet, so the JSON mode is read off the raw words:
+    // a parse failure under `--json` is a JSON document on stdout, not text on
+    // stderr with an empty stdout (Q11, ADR-070 ruling 4).
+    jsonFailMode(rawJsonFlag(argv));
+    process.exit(fail(parsed.error.message, parsed.error.code));
+  }
+  const { flags, positional } = parsed.value;
+
+  // Set before anything can fail: `no command given` under `--json` is a JSON
+  // document too, and a failure that prints as text with an empty stdout breaks
+  // the same ruling the parse failure above honours (Q11, ADR-070 ruling 4).
+  jsonIndentDefault(flags.pretty === true);
+  jsonFailMode(flags.json === true);
+
+  // No arguments at all is a usage error, not a silent help dump: an agent that
+  // ran the wrong thing should be told so rather than handed 40 lines of prose.
+  if (positional.length === 0 && !flags.help && !flags.version) {
+    process.exit(fail('no command given', EXIT.USAGE));
+  }
+
+  const { dispatch } = await import('./commands/index.mjs');
+  const code = (await dispatch(argv)) ?? EXIT.OK;
+  // Assigned, not forced: a large document on stdout (a `--json --diff` over a
+  // skill-sized body exceeds the 64 KiB pipe buffer) is still draining when the
+  // command resolves, and `process.exit()` cuts it — exit 0 with half a JSON
+  // document on stdout. Letting the loop empty first makes the exit honest
+  // (plan 0003 R50; the S10 contract asserts the document parses).
+  process.exitCode = code;
+} catch (error) {
+  process.exit(fail(error?.message ?? String(error), EXIT.FAIL));
+}