simt-dev 0.2.0 → 0.2.2

package/rules/stacks/typescript.md

@@ -7,6 +7,8 @@ simt-title: TypeScript
 # repositories are selected for. Two fallbacks both apply when nothing more specific
 # matched.
 simt-applies: [typescript]
+simt-priority: convention
+simt-scope: ["tsconfig.json", "*.ts", "*.tsx"]
 simt-fallback: true
 ---
 

package/rules/stacks/uv.md

@@ -5,6 +5,8 @@ simt-title: uv
 # `uv.lock` in its body while selecting on any Python marker, so a Poetry project was
 # told to run a tool manager it does not use (S28, ADR-047).
 simt-applies: [has-uv-lock]
+simt-priority: convention
+simt-scope: ["uv.lock", "pyproject.toml"]
 ---
 
 # Stack profile: uv

package/src/argv.mjs

@@ -12,23 +12,48 @@
 
 import { EXIT, fail } from './output/index.mjs';
 
-const BOOL_FLAGS = new Set([
+// `--quiet`, `--semantic` and `--mermaid` were here and were read by nothing (review
+// 0001 filed it; it survived every change to this file since). Each was a plan's
+// intention rather than a feature: `--semantic` was to be an explicitly non-canonical
+// escape hatch, `--mermaid` belonged to a `skills graph` command that was never built,
+// and `--quiet` was to shorten `help`. The plans keep those records; the parser does not
+// need to keep a promise no code makes.
+//
+// An accepted flag that changes nothing is worse than an absent one. `--nonsense` exits
+// 2 and tells the reader the flag does not exist; `--quiet` exits 0 and tells them
+// nothing happened, which is indistinguishable from the output being quiet on purpose.
+// Removing them makes `test/help.test.mjs`'s "every flag is described" assertion able to
+// mean something, which it could not while three accepted flags had no description.
+
+export const BOOL_FLAGS = new Set([
   'json',
   'all',
   'dry-run',
   'yes',
   'check',
-  'quiet',
   'plan',
-  'semantic',
-  'mermaid',
   'help',
   'version',
+  // JSON output: indent it. Off by default because a pipe is not a person, and the
+  // bytes an agent pays for indentation are bytes it never reads.
+  'pretty',
   'accept-conflicts',
+  'backup',
   'list',
+  // tokens: measure every repository under the root, not just the one. Plan 0003 R06
+  // names this flag `--workspace`, and that name has been a VALUE flag since plan
+  // 0002 - it is where the skill sources live. One flag with two meanings is the
+  // silent-ignore defect this file's header refuses, so the meter's switch is named
+  // for what it selects.
+  'repos',
+  // harness detect: also report the directories in the user's home. Off by default
+  // because the home directory belongs to the reader rather than the repository, and a
+  // command whose output changes because something was installed elsewhere is one a
+  // reader stops trusting.
+  'user',
 ]);
 
-const VALUE_FLAGS = new Set([
+export const VALUE_FLAGS = new Set([
   'budget',
   'max-bytes',
   'paths',
@@ -41,8 +66,28 @@ const VALUE_FLAGS = new Set([
   'variant',
   'from',
   'surfaces',
+  // graph lint: which specification to check the skills against. A value rather than a
+  // boolean because "lint against the spec" would not say WHICH spec, and a lint that
+  // silently applied an unnamed set of rules is the decoration this repository exists
+  // to refuse. One is on offer today, so the command rejects any other by name.
+  'spec',
 ]);
 
+/**
+ * Flags that accumulate rather than overwrite.
+ *
+ * `--skill` was documented as "(repeatable)" and was not: `flags.skill = value` meant
+ * `--skill a --skill b` resolved to `b`, with `a` silently dropped. No error, no
+ * warning, and a brief that quietly lacked a skill the caller named — which is the one
+ * failure mode a tool whose job is to be explainable cannot have (ADR-009, "the answer
+ * is a function of what was asked").
+ *
+ * Comma separation still works, because the consumer splits on commas either way. This
+ * is a superset of the old behaviour, not a replacement: `--skill a,b` parsed before it
+ * parses now.
+ */
+export const REPEATABLE_FLAGS = new Set(['skill']);
+
 /**
  * @param {string[]} argv raw arguments, excluding node and the script path
  * @returns {{ok: true, value: object} | {ok: false, code: number}}
@@ -96,7 +141,10 @@ export function parse(argv) {
         }
         flags[camel(raw)] = n;
       } else {
-        flags[camel(raw)] = value;
+        const key = camel(raw);
+        flags[key] = REPEATABLE_FLAGS.has(raw)
+          ? [...(Array.isArray(flags[key]) ? flags[key] : []), value]
+          : value;
       }
       continue;
     }

package/src/ci/dependabot.mjs

@@ -142,7 +142,7 @@ function header(own) {
 # only writer here, so an entry is added deliberately rather than as a side effect.
 `;
   }
-  return `# Written by simt-dev when this repo was adopted. Yours from here: simt-dev
+  return `# Written by simt-dev when this repo was adopted. Yours from here: ${CLI}
 # creates this file once and never rewrites it, so your own cadence, ignore rules
 # and groups stay yours.
 #

package/src/ci/workflow.mjs

@@ -50,6 +50,7 @@ import { PACKAGE_ROOT } from '../workspace.mjs';
 import { PACKAGE_NAME, WORKFLOW_FILE_NAME } from '../name.mjs';
 import { renderLocator } from '../locate.mjs';
 import { CLI } from '../name.mjs';
+import { packageVersion } from '../package-version.mjs';
 
 /** Directory whose presence means this repo runs GitHub Actions. */
 export const WORKFLOWS_DIR = '.github/workflows';
@@ -169,12 +170,16 @@ function skeleton(name, steps, { matrix = null } = {}) {
   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.
+#
+# 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
+# be cleared before the next one lands. \`pull_request\` asks one question — may this
+# merge — and answers it once. \`main\` here is the branch protection list, not a
+# trigger: the gate that has to pass is the one the pull request runs, and the one
+# on \`main\` is whatever CI the repository already has there.
 on:
   pull_request:
-  push:
-    branches:
-      - main
-      - master
 
 # Read-only is enough to check a repo, and a gate job does not need to write to it.
 permissions:
@@ -235,7 +240,7 @@ function indent(text, spaces) {
  * @param {{own?: boolean}} [options]
  * @returns {string} YAML, LF-terminated
  */
-export function renderWorkflow({ own = false } = {}) {
+export function renderWorkflow({ own = false, npm = true, version } = {}) {
   if (own) {
     const floor = nodeFloor();
     return `${header(true)}${skeleton(
@@ -267,17 +272,34 @@ export function renderWorkflow({ own = false } = {}) {
     )}\n`;
   }
 
-  const locator = renderLocator('check --root "$ROOT"', {
-    remedy: `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`,
-  });
+  const v = version ?? packageVersion();
+  // 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 installs the same pinned global
+  // binary the machine remedy names. The two must agree, or the gate passes in one
+  // place and cannot start in the other.
+  const install = npm
+    ? [
+        '      - name: install dependencies',
+        '        # `npm ci` needs a lockfile; a repo without one is still gated, not skipped.',
+        '        run: npm ci || npm install',
+      ]
+    : [
+        '      - name: install the pinned gate binary',
+        '        # No node_modules to pin in, so a pinned global install: the same bytes',
+        '        # the machine remedy names, so the gate cannot pass locally and fail here.',
+        `        run: npm i -g ${PACKAGE_NAME}@${v}`,
+      ];
+  const remedy = npm
+    ? `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`
+    : `REMEDY run: npm i -g ${PACKAGE_NAME}@${v}   (the gate runs from a pinned global install)`;
+  const locator = renderLocator('check --root "$ROOT"', { remedy });
   return `${header(false)}${skeleton(
     `${CLI} check`,
     [
       uses('checkout'),
       setupNode(nodeFloor()),
-      '      - name: install dependencies',
-      '        # \`npm ci\` needs a lockfile; a repo without one is still gated, not skipped.',
-      '        run: npm ci || npm install',
+      ...install,
       `      - name: ${CLI} check`,
       '        run: |',
       indent(`set -eu\nROOT="\${GITHUB_WORKSPACE}"\n${locator}`, 10),

package/src/commands/compare.mjs

@@ -98,6 +98,8 @@ export async function compareCommand(positional, flags) {
         noRegion: summary.noRegion,
         malformed: summary.malformed,
         staleRuleFiles: summary.staleRuleFiles,
+        packageRegions: summary.packageRegions,
+        stalePackages: summary.stalePackages,
         hooksRouted: summary.hooksRouted,
         withProblems: summary.withProblems,
         withOwnHooks: summary.withOwnHooks,
@@ -155,6 +157,14 @@ function render(rows, summary, found) {
     `repos     ${summary.repos} (${summary.adopted} adopted, ${summary.unmanaged} unmanaged${summary.broken > 0 ? `, ${summary.broken} broken` : ''})`,
     `region    ${summary.current} current, ${summary.drifted} drifted, ${summary.noRegion} with no region, ${summary.malformed} malformed`,
     `rules     ${summary.staleRuleFiles === 0 ? 'every rule file current' : `${summary.staleRuleFiles} rule file${summary.staleRuleFiles === 1 ? '' : 's'} not current`}`,
+    // One line, and only when there is a package region to report. A workspace of
+    // single-repository members is the common case and must not grow a line that
+    // always reads "none".
+    ...(summary.packageRegions > 0
+      ? [
+          `packages  ${summary.stalePackages === 0 ? `every package region current (${summary.packageRegions})` : `${summary.stalePackages} of ${summary.packageRegions} package region${summary.packageRegions === 1 ? '' : 's'} not current`}`,
+        ]
+      : []),
     `hooks     ${summary.hooksRouted}/${summary.adopted} adopted repos route the shared dispatcher`,
     `          ${summary.withOwnHooks} repo${summary.withOwnHooks === 1 ? '' : 's'} run their own hooks; adopting replaces them (a note, not a problem)`,
     `problems  ${summary.withProblems} repo${summary.withProblems === 1 ? '' : 's'}`,
@@ -167,6 +177,11 @@ function render(rows, summary, found) {
     lines.push(`          adoption ${r.adoption}${r.id && r.id !== r.name ? ` (id ${r.id})` : ''}`);
     lines.push(`          stack   ${r.stack.length > 0 ? r.stack.join(', ') : '(none)'}${r.declaredStack.length > 0 ? ` (manifest declares ${r.declaredStack.join(', ')})` : ''}`);
     if (r.facts.length > 0) lines.push(`          facts   ${r.facts.join(', ')}`);
+    // Per package, and only for a repository that has packages: a single-repository
+    // member must not print an empty list of packages on every line of every run.
+    for (const p of r.packages) {
+      lines.push(`          package ${p.path} ${p.status}${p.profiles.length > 0 ? ` (${p.profiles.join(', ')})` : ''}`);
+    }
     lines.push(`          region  ${r.region}${r.regionDetail ? ` (${r.regionDetail})` : ''}`);
     // The rule files are the answer to "does every editor see the same rule?".
     lines.push(

package/src/commands/graph.mjs

@@ -6,41 +6,68 @@
 // Output is line-oriented and bounded (plan 0002 section 6). A lint failure names
 // the offending node, the file it disagrees with, and both numbers.
 
-import { EXIT, emit, fail, isJson } from '../output/index.mjs';
-import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { loadRegistry } from '../graph/load.mjs';
+import { lintSpec } from '../graph/speccheck.mjs';
+import { SPEC, SPEC_SOURCE } from '../graph/spec.mjs';
+import { CLI } from '../name.mjs';
 
 export async function lintCommand(positional, flags) {
-  const path = positional[0] ?? REGISTRY_PATH;
-  const { ok, registry, errors, warnings, verified, workspace } = await loadRegistry(path, flags);
+  const spec = flags.spec ?? null;
+  if (spec !== null && spec !== SPEC) {
+    return fail(`unknown --spec "${spec}"`, EXIT.USAGE, `the one specification this lints is: ${SPEC}`);
+  }
+
+  // The resolved path comes back from the loader, because when no positional is given it
+  // falls back to the member that holds the registry in this workspace (ADR-061) - and the
+  // reader should see where it actually looked, not a constant that no longer exists.
+  const { ok, registry, errors, warnings, verified, workspace, path } = await loadRegistry(
+    positional[0] ?? null,
+    flags,
+  );
+
+  // The conformance pass is separate from the registry pass on purpose. The registry
+  // answers "does the bookkeeping match the files"; the specification answers "would a
+  // client accept these files", and the second question needs no registry at all. A
+  // reader with no registry can still lint a skill directory, so the two are additive
+  // rather than one gating the other.
+  const specReport = registry && workspace?.root
+    ? await lintSpec(registry, workspace.root)
+    : { errors: [], warnings: [], checked: 0 };
+  errors.push(...specReport.errors);
+  warnings.push(...specReport.warnings);
 
   if (isJson(flags)) {
-    emit(
-      `${JSON.stringify(
-        {
-          ok,
-          registry: path,
-          capabilities: registry?.capabilities?.length ?? 0,
-          skills: registry?.skills?.length ?? 0,
-          // `verified: false` means the byte counts in the registry were NOT
-          // checked against files on disk. It is not a failure - it is the difference
-          // between "the registry is right" and "the registry could not be checked",
-          // and an agent that cannot see the difference will trust a number nobody
-          // measured (ADR-014).
-          verified,
-          workspace,
-          errors,
-          warnings,
-        },
-        null,
-        2,
-      )}\n`,
+    emitJson(
+      {
+        ok,
+        registry: path,
+        capabilities: registry?.capabilities?.length ?? 0,
+        skills: registry?.skills?.length ?? 0,
+        // `verified: false` means the byte counts in the registry were NOT
+        // checked against files on disk. It is not a failure - it is the difference
+        // between "the registry is right" and "the registry could not be checked",
+        // and an agent that cannot see the difference will trust a number nobody
+        // measured (ADR-014).
+        verified,
+        workspace,
+        // Present only when asked for, so a reader of the default output is not told
+        // about a pass that never ran. `null` is the honest value; `true` would be a
+        // claim about conformance nobody checked.
+        spec: spec === null ? null : { name: SPEC, source: SPEC_SOURCE, checked: specReport.checked },
+        errors,
+        warnings,
+      },
       { maxBytes: flags.maxBytes ?? 0 },
     );
     return ok ? EXIT.OK : EXIT.REGISTRY;
   }
 
   if (!registry) {
-    return fail(errors[0] ?? `${path}: unreadable`, EXIT.REGISTRY);
+    // The default remedy for this exit code is `run: simt-dev graph lint`, which from
+    // inside `graph lint` is circular: the reader just ran it and got this. Name the
+    // argument the command takes, because an explicit path is the way out (ADR-061).
+    return fail(errors[0] ?? `${path}: unreadable`, EXIT.REGISTRY, `run: ${CLI} graph lint <path-to-registry>`);
   }
 
   const lines = [
@@ -48,6 +75,12 @@ export async function lintCommand(positional, flags) {
     `nodes     ${registry.skills.length} skills, ${registry.capabilities.length} capabilities`,
     `verified  ${verified ? 'byte counts checked against disk' : 'NOT checked - see WARN below'}`,
   ];
+  if (spec !== null) {
+    lines.push(
+      `spec      ${specReport.checked} skills checked against ${SPEC_SOURCE}` +
+        `${specReport.checked === 0 ? ' (none had a readable SKILL.md)' : ''}`,
+    );
+  }
 
   const deferred = registry.skills.filter((s) => s.deferred);
   lines.push(

package/src/commands/harness.mjs

@@ -0,0 +1,150 @@
+// `simt harness detect` - which harnesses this repository (and this user) is set up
+// for, and which of them simt-dev has a channel for.
+//
+// Why this is a command and not a sentence in the docs: the question "which harness
+// reads my rules" has two halves that used to be answered in different places, and the
+// second half was answered by a reader's guess. What is present on disk is observable
+// and belongs to the tool; what a given harness actually loads is a vendor fact, and a
+// vendor fact is only trustworthy when it names its source. So the table that says "we
+// have a channel for this" and the table that says "we have not verified one" are kept
+// apart, and this command reports both without collapsing them into a verdict.
+//
+// It exits 0 whatever it finds. A harness with no channel is a fact about coverage, not
+// a defect in the repository: the rules in AGENTS.md still reach whichever harnesses
+// read that file, and a reader who wanted a failing command could not tell the
+// difference between "no channel" and "broken".
+
+import { stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { EXIT, emit, emitJson, isJson, note } from '../output/index.mjs';
+import { SURFACES, CANDIDATE_DIRS } from '../projection/surfaces.mjs';
+
+/**
+ * `simt-dev harness detect`. The subcommand is validated by dispatch, which rejects a
+ * second token that is not in the group registry rather than silently routing to the
+ * default; this function therefore has exactly one thing to do and no second spelling
+ * to keep in step with it.
+ *
+ * @param {string[]} positional arguments after the command path
+ * @param {object} flags
+ * @returns {Promise<number>} process exit code
+ */
+export async function harnessCommand(positional, flags) {
+  const root = flags.root ?? process.cwd();
+
+  const repo = await scan(root);
+  // Only on request. The home directory is the reader's, not the repository's, and a
+  // command that reports both by default is a command whose output changes because
+  // somebody installed something elsewhere.
+  const user = flags.user === true ? await scan(homedir()) : null;
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'harness detect',
+      root,
+      repo,
+      ...(user === null ? {} : { user }),
+    });
+    return EXIT.OK;
+  }
+
+  emit(render(root, repo, user));
+  if (repo.rows.length === 0) {
+    note(
+      `note     no harness configuration directory found in ${root}. That is a repository ` +
+        'nobody has set an agent up in - not a finding.',
+    );
+  }
+  const unclaimed = countUnclaimed(repo);
+  if (unclaimed > 0) {
+    note(
+      `note     ${unclaimed} present configur${unclaimed === 1 ? 'ation has' : 'ations have'} ` +
+        'no rule channel in this release. Each one is reported as present, not as ' +
+        'unsupported: whether it reads AGENTS.md is a vendor question this tool does not ' +
+        'answer without a source, and a guess here would be the reader\'s problem later.',
+    );
+  }
+  return EXIT.OK;
+}
+
+/**
+ * Every harness directory present under one root, sorted by directory name.
+ *
+ * A directory whose stat fails for any reason other than absence is treated as absent
+ * rather than raised: a permissions error on one candidate must not make the whole
+ * command fail, and the difference between "could not look" and "not there" is one
+ * note in the output rather than a second failure mode nobody asked for.
+ */
+async function scan(root) {
+  const rows = [];
+  for (const s of SURFACES) {
+    for (const dir of s.configDirs ?? []) {
+      if (await present(root, dir)) {
+        rows.push(row(dir, s.label, { id: s.id, verified: s.verified ?? null, readsAgentsMd: s.readsAgentsMd, rule: s.rule }));
+      }
+    }
+  }
+  for (const c of CANDIDATE_DIRS) {
+    if (await present(root, c.dir)) rows.push(row(c.dir, c.harness, {}));
+  }
+  rows.sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
+  return { root, rows };
+}
+
+async function present(root, dir) {
+  try {
+    return (await stat(join(root, dir))).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** One present directory, and what - if anything - this tool can project into it. */
+function row(dir, label, surface) {
+  const id = surface.id ?? null;
+  return {
+    dir,
+    label,
+    surface: id,
+    // `channel: false` is the honest half of the answer: the directory exists and this
+    // release has no rule file to write there. Reported as its own field rather than
+    // left implicit, because "we found it and did nothing" and "we found nothing" look
+    // identical in a list of names.
+    channel: id !== null && surface.rule != null,
+    readsAgentsMd: surface.readsAgentsMd ?? null,
+    verified: surface.verified ?? null,
+  };
+}
+
+function countUnclaimed(scan) {
+  return scan.rows.filter((r) => r.surface === null).length;
+}
+
+/**
+ * One line per present directory, in the order the scanner found them.
+ *
+ * `surface` is printed when there is one, and `AGENTS.md` is named when the surface
+ * loads it - because the answer a reader actually wants is "do my rules reach this",
+ * and the channel column alone does not answer it.
+ */
+function render(root, repo, user) {
+  const lines = [`repo     ${root}`];
+  lines.push(...block(repo, '        '));
+  if (user !== null) {
+    lines.push(`user     ${user.root}`);
+    lines.push(...block(user, '        '));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function block(scan, pad) {
+  if (scan.rows.length === 0) return [`${pad}(none present)`];
+  return scan.rows.map((r) => {
+    const through = r.surface === null ? 'no rule channel in this release' : r.channel ? 'projected rule file' : 'AGENTS.md';
+    const agents = r.readsAgentsMd === 'all' ? ' (reads AGENTS.md)' : r.readsAgentsMd === 'some' ? ' (some readers read AGENTS.md)' : '';
+    return `${pad}${r.dir.padEnd(12)} ${r.label.padEnd(38)} ${through}${agents}`;
+  });
+}

package/src/commands/help.mjs

@@ -4,7 +4,8 @@ import { CLI } from '../name.mjs';
 
 const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
                            (dry-run unless --yes; conflicts block without
-                           --accept-conflicts; never commits or pushes)
+                           --accept-conflicts; in place unless --backup;
+                           never commits or pushes)
 ${CLI} doctor                 classify a repo and check config health
 ${CLI} check                  the gate: projection drift, manifest validity, policy
 ${CLI} sync [--yes]           regenerate the projection (idempotent)
@@ -19,6 +20,10 @@ ${CLI} skills brief --task    tier-1 pre-assembled brief  <- the common case
 ${CLI} skills show <name>     tier-2 body (respects --max-bytes)
 ${CLI} skills why <name>      the signal chain that selected it
 ${CLI} skills find <query>    search across capability and keyword
+${CLI} skills eval [corpus]   measure the resolver against a gold corpus
+                           (reports precision and recall; exits non-zero on
+                            regression; without an argument, the corpus in this
+                            checkout)
 ${CLI} skills install <name>  pin a skill into the repo as a local override
                            (dry-run unless --yes; a multi-variant skill needs
                            --variant or --from rather than a guess)
@@ -26,20 +31,35 @@ ${CLI} skills install <name>  pin a skill into the repo as a local override
 ${CLI} rules list             the rule catalogue (--root marks what applies to a repo)
 ${CLI} rules show <id>        one rule body
 ${CLI} rules why <id|ADR-NNN> the decision that settled it, and whether it is still in force
+                           (--all prints every ruling, not the first two)
 ${CLI} hooks install [--yes]   install the shared dispatcher; report what it would run
                            (dry-run unless --yes; refuses to take over routing git
                             already uses, and --yes is that consent)
+${CLI} hooks status            what each git event routes to, and whether it is wired
+${CLI} hooks run <event>       run one event's gates now, as git would
+                           (pre-commit, pre-push, post-merge, ...)
+${CLI} graph lint              check the skill registry against the skills on disk
+                           (byte counts, dangling edges, unresolvable variants)
 ${CLI} ci                     simt-dev's own .github files: create or refresh them
                            (dry-run unless --yes; refreshes the templates' own copies
                             and no repository else's)
 ${CLI} compare                org-wide matrix across every sibling repo
                            (read-only; exits non-zero on defects, not on
                            repos that have not adopted yet)
+${CLI} tokens [--repos]       what a reader loads at session start, in bytes
+                           (read-only; exits 0 whatever it finds, because a
+                           measurement is not a verdict; --repos measures every
+                           repository under the root and what repeats an earlier)
+${CLI} harness detect         which harnesses this repo (and, with --user, you)
+                           are set up for, and which have a rule channel here
+                           (presence only: a directory found is not a claim about
+                           what its owner reads; exits 0 whatever it finds)
 ${CLI} mcp                    the read-only surface as MCP tools over stdio
                            (--list prints it without reading stdin; init, sync,
                            upgrade and the installers stay CLI-only by design)`;
 
-const FLAGS = `--json                 structured output
+const FLAGS = `--json                 structured output (compact; one document, one line)
+--pretty                indent --json for a human
 --max-bytes <n>         hard ceiling on emitted bytes (0 = unlimited, default 0)
 --budget <n>            context budget for skills brief (default 20480)
 --plan                  emit a fetch plan instead of inlining skill bodies
@@ -55,9 +75,21 @@ const FLAGS = `--json                 structured output
                         file, then the sibling heuristic if it verifies)
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
---all                   ignore the budget and resolve everything
+--check                 report drift and write nothing (sync, ci)
+--all                   ignore a cap: every ruling of a record, or the skills budget
 --variant <id>          which body of a multi-variant skill to use
---from <repo/path>      install from a declared source by name`;
+--from <repo/path>      install from a declared source by name
+--list                  print the MCP tool surface without reading stdin (mcp)
+--accept-conflicts      init: adopt rules that collide with hand-written ones
+--backup                init: tag the pre-adoption commit and branch onto
+                        simt-dev/adopt before writing (the undo path)
+--spec <name>           graph lint: also check every skill against a named
+                        specification (one exists: agentskills)
+--user                  harness detect: also report the directories in your home
+--repos                 tokens: measure every repository under the root, not
+                        just the one, and report what repeats an earlier one
+--help                  this text
+--version               the version, and the SHA it was built from`;
 
 const PRINCIPLES = `design rules:
   deterministic       same repo + same task = same answer, forever
@@ -78,7 +110,7 @@ export async function help(argv) {
     [
       'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
       '',
-      'usage: simt-dev <command> [args] [flags]',
+      `usage: ${CLI} <command> [args] [flags]`,
       '',
       'commands:',
       COMMANDS,