@ultimat3/cli 19.4.0 → 20.1.0

package/src/templates/guard-semantic-interactive.ts

@@ -0,0 +1,244 @@
+// The `semantic-interactive` guard `x new` ships: an element that answers a click IS a control.
+// The cheapest a11y win there is, and the one an agent undoes by reflex — WebAIM's annual survey of
+// a million home pages finds pages using ARIA average ~41% MORE detected errors than pages using
+// none, because `role="button"` is a PROMISE (Space, Enter, focus, disabled) and only the native
+// element keeps it. Nothing in the gate could see a `<div onClick>` before this file existed.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'semantic-interactive';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// semantic-interactive: a click is answered by a control, and a role is a promise.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to. Delete it to drop the rule.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/**
+ * Elements with no behaviour of their own: no tab stop, no Enter, no Space, no disabled state.
+ * A handler on one of these reaches a mouse and nothing else.
+ */
+const INERT = new Set([
+  'div',
+  'span',
+  'li',
+  'p',
+  'section',
+  'article',
+  'aside',
+  'header',
+  'footer',
+  'main',
+  'nav',
+  'ul',
+  'ol',
+  'td',
+  'tr',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+]);
+
+/** A role whose native element already exists, and the element to write instead of the role. */
+const NATIVE = new Map([
+  ['button', { tag: 'button', write: '<button type="button">' }],
+  ['link', { tag: 'a', write: '<a href="…">' }],
+  ['checkbox', { tag: 'input', write: '<input type="checkbox">' }],
+]);
+
+/** \`(?<![\\w-])\` on every one: \`data-role\` is not \`role\`, and \`maxWidth\` is not \`width\`. */
+const HANDLER = /(?<![\\w-])(on(?:Click|MouseDown|KeyDown))\\s*=/;
+const ROLE = /(?<![\\w-])role\\s*=\\s*["']([a-z]+)["']/;
+const TABINDEX = /(?<![\\w-])tab[Ii]ndex\\s*=/;
+const KEYS = /(?<![\\w-])onKey(?:Down|Up|Press)\\s*=/;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+interface Tag {
+  readonly name: string;
+  readonly attrs: string;
+  readonly index: number;
+}
+
+/** Comments blanked IN PLACE — not deleted — so a reported line number still points at the source. */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+const NAME_AT = /^([A-Za-z][\\w.-]*)/;
+
+/**
+ * Every opening tag, with its attribute text. The tag ends at the first \`>\` OUTSIDE braces and
+ * quotes, which is the whole reason this is a scanner and not a regex: \`onClick={() => save()}\`
+ * holds a \`>\` that closes nothing, so a pattern reading to the next \`>\` cuts the element in half
+ * and misses every handler written as an arrow — the way all of them are written.
+ */
+function openingTags(text: string): readonly Tag[] {
+  const tags: Tag[] = [];
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] !== '<') continue;
+    const name = NAME_AT.exec(text.slice(i + 1, i + 64))?.[1];
+    if (name === undefined) continue;
+    const from = i + 1 + name.length;
+    let depth = 0;
+    let quote = '';
+    let end = from;
+    for (; end < text.length; end += 1) {
+      const ch = text[end];
+      if (quote !== '') {
+        if (ch === quote) quote = '';
+        continue;
+      }
+      if (ch === '"' || ch === "'" || ch === '\`') quote = ch;
+      else if (ch === '{') depth += 1;
+      else if (ch === '}') depth -= 1;
+      else if (depth === 0 && (ch === '>' || ch === '<')) break;
+    }
+    tags.push({ name, attrs: text.slice(from, end), index: i });
+    // Continue from just after the NAME, never after the tag: a nested element inside a brace
+    // expression — \`{items.map((i) => <li onClick={…}>…)}\` — is a tag this rule has to see.
+    i = from - 1;
+  }
+  return tags;
+}
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function semanticInteractive(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const tag of openingTags(text)) {
+      // A role, a tab stop and a key handler together are the COMPLETE set the ARIA practices
+      // guide asks for — a deliberate widget, written by someone who read the obligation. This
+      // rule is about the incomplete ones, so all three present is the one shape it passes over.
+      if (ROLE.test(tag.attrs) && TABINDEX.test(tag.attrs) && KEYS.test(tag.attrs)) continue;
+      const at = \`\${file.path}:\${lineOf(text, tag.index)}\`;
+      const role = ROLE.exec(tag.attrs)?.[1] ?? '';
+      const native = NATIVE.get(role);
+      // One finding per tag, role first: \`<div role="button" onClick>\` is one mistake with two
+      // symptoms, and two findings would make the reader fix it twice.
+      if (native !== undefined && tag.name !== native.tag) {
+        findings.push({
+          code: CODE,
+          cause: \`\${at} puts role="\${role}" on <\${tag.name}> — a role is a promise, and this one obliges the element to answer Space, Enter, focus and disabled, which the native element already does\`,
+          fix: \`replace <\${tag.name} role="\${role}"> in \${file.path} with \${native.write}, then: x verify\`,
+          at: file.path,
+        });
+        continue;
+      }
+      const handler = INERT.has(tag.name) ? HANDLER.exec(tag.attrs)?.[1] : undefined;
+      if (handler === undefined) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${at} hangs \${handler} on <\${tag.name}>, which takes no focus and answers no key — a keyboard, a screen reader and a switch reach a mouse handler on an inert element in exactly one way, which is not at all\`,
+        fix: \`write <button type="button"> — or the native control this element means — in place of <\${tag.name}> at \${at}, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a click is answered by a control, never by a div with a handler',
+  async check(root) {
+    const files: SourceFile[] = [];
+    // TWO globs, and the rule is that a brace ALTERNATIVE may not contain a \`/\`. Measured on Bun
+    // 1.4.0 against \`examples/dummy\`: \`{apps/*/{site,app},packages/*/src}/**/*.tsx\` and
+    // \`{apps/web,packages/ui}/**/*.tsx\` each match ZERO files, where \`apps/*/{site,app}/**/*.tsx\`
+    // matches 17 — so folding these into one line silently turns the guard off, which is worse than
+    // the hole it closes. A LEADING group is fine and four guards here rely on it:
+    // \`{apps,packages}/**/*.scss\` matches all 15.
+    for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
+      for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+        const path = entry.split('\\\\').join('/');
+        if (path.includes('node_modules/') || /\\.test\\.tsx?$/.test(path)) continue;
+        files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+      }
+    }
+    return semanticInteractive(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { semanticInteractive } from './semantic-interactive';
+
+const file = (source: string) => [{ path: 'apps/web/app/post/page.tsx', source }];
+
+unitTest('a div with a click handler is refused, and the finding names the line', () => {
+  const findings = semanticInteractive(
+    file('<main>\\n  <div onClick={() => save()}>Save</div>\\n</main>'),
+  );
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+  expect(findings[0]?.fix).toContain('<button type="button">');
+});
+
+unitTest('role="button" on a div names the native element to write instead', () => {
+  const findings = semanticInteractive(file('<div role="button" onClick={go}>Go</div>'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.cause).toContain('a role is a promise');
+  expect(findings[0]?.fix).toContain('<button type="button">');
+});
+
+unitTest('the native control it names is not itself a finding', () => {
+  expect(semanticInteractive(file('<button type="button" onClick={go}>Go</button>'))).toEqual([]);
+  expect(semanticInteractive(file('<a href="/x" onClick={go}>Go</a>'))).toEqual([]);
+});
+
+// The boundary, stated: a role, a tab stop and a key handler together are the complete set the
+// ARIA practices guide asks for. This rule reports the INCOMPLETE widget, never the deliberate one.
+unitTest('a role with a tab stop and a key handler is a deliberate widget', () => {
+  const widget = '<div role="button" tabindex="0" onClick={go} onKeyDown={go}>Go</div>';
+  expect(semanticInteractive(file(widget))).toEqual([]);
+});
+
+unitTest('data-role is not role, and a live region is not a control', () => {
+  expect(semanticInteractive(file('<p data-role="status" role="status">Saved</p>'))).toEqual([]);
+});
+
+// The reason the tag end is scanned rather than matched: an arrow function's \`>\` closes nothing,
+// and a pattern that stopped at it would read the element as ending before its own handler.
+unitTest('an arrow function in an earlier attribute does not end the tag', () => {
+  const source = '<div class={cx(() => a > b)} onClick={go}>Go</div>';
+  expect(semanticInteractive(file(source))).toHaveLength(1);
+});
+
+unitTest('a commented-out handler is a note, not an element', () => {
+  expect(semanticInteractive(file('// <div onClick={go}>Go</div>\\nconst a = 1;'))).toEqual([]);
+});
+`;
+
+/** `guards/semantic-interactive.ts` and its test. The directory is the registration. */
+export const semanticInteractiveGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/semantic-interactive.ts', contents: source() },
+  { path: 'guards/semantic-interactive.test.ts', contents: test() },
+];

package/src/templates/guard-untranslated-string.ts

@@ -36,8 +36,6 @@ const CODE = '${CODE}';
  * rule wants: a parent whose children are elements has no text of its own.
  */
 const ELEMENT = /<([A-Za-z][\\w.:-]*)(?:\\s[^<>]*)?>([^<>]*?)<\\/\\1>/g;
-/** A \`{…}\` child is an expression — \`{t('key')}\`, \`{props.row.title}\` — never typed prose. */
-const EXPRESSION = /\\{[^{}]*\\}/g;
 /** Two word characters in a row. One is \`&\`, \`×\`, an initial — never a sentence. */
 const PROSE = /[\\p{L}\\p{N}]{2,}/u;
 
@@ -55,13 +53,43 @@ const blank = (text: string): string =>
 
 const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
 
+/**
+ * Every \`{…}\` child removed — \`{t('key')}\`, \`{props.row.title}\` — leaving only what was TYPED
+ * between the tags.
+ *
+ * A depth scan and never a regex, because a JSX expression NESTS and a regex does not:
+ * \`/\\{[^{}]*\\}/g\` strips the INNER group of
+ * \`{t('app.feed.heading', { org: actor.org.name })}\` first, leaves the unbalanced remnant
+ * \`{t('app.feed.heading',  )}\`, and then reads that remnant as prose — so every \`t()\` call with an
+ * interpolation object or a template-literal key was reported as an untranslated string, which is
+ * the exact opposite of the rule. Measured at 12 findings, all false, before this scan replaced it.
+ *
+ * A closing brace with nothing open is kept: it is a stray character, and prose it is not.
+ */
+const withoutExpressions = (children: string): string => {
+  let out = '';
+  let depth = 0;
+  for (const character of children) {
+    if (character === '{') {
+      depth += 1;
+      continue;
+    }
+    if (character === '}' && depth > 0) {
+      depth -= 1;
+      continue;
+    }
+    if (depth === 0) out += character;
+  }
+  return out;
+};
+
 /** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
 export function untranslatedStrings(files: readonly SourceFile[]): readonly Finding[] {
   const findings: Finding[] = [];
   for (const file of files) {
     const text = blank(file.source);
     for (const match of text.matchAll(ELEMENT)) {
-      const typed = (match[2] ?? '').replaceAll(EXPRESSION, ' ').trim();
+      const typed = withoutExpressions(match[2] ?? '').trim();
       if (!PROSE.test(typed)) continue;
       findings.push({
         code: CODE,
@@ -83,9 +111,12 @@ export const guard: Guard = {
     // a hardcoded string there used to be green. \`api/\` renders nothing and \`shared/\` is a leaf of
     // helpers; \`packages/*/dist\` is a build output, not source.
     //
-    // TWO globs, never one with a leading \`{a,b}\` group: \`Bun.Glob.scan()\` matches nothing at all
-    // for a pattern that starts with a brace group — measured — so folding these into one line
-    // silently turns the guard off, which is worse than the hole it closes.
+    // TWO globs, and the rule is that a brace ALTERNATIVE may not contain a \`/\`. Measured on Bun
+    // 1.4.0 against \`examples/dummy\`: \`{apps/*/{site,app},packages/*/src}/**/*.tsx\` and
+    // \`{apps/web,packages/ui}/**/*.tsx\` each match ZERO files, where \`apps/*/{site,app}/**/*.tsx\`
+    // matches 17 — so folding these into one line silently turns the guard off, which is worse than
+    // the hole it closes. A LEADING group is fine and four guards here rely on it:
+    // \`{apps,packages}/**/*.scss\` matches all 15.
     for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
       for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
         const path = entry.split('\\\\').join('/');
@@ -119,6 +150,23 @@ unitTest('a t() child satisfies it, and so does any other expression', () => {
   expect(untranslatedStrings(file('<li class={styles.item}>{row.title}</li>'))).toEqual([]);
 });
 
+// The legitimate lookalike, and the one this rule got wrong: a JSX expression NESTS. A mask that
+// does not strips the inner \`{ org: … }\` first and reads the unbalanced remnant as prose, so the
+// guard reported the very calls it exists to require.
+unitTest('a t() call carrying an interpolation object is not typed prose', () => {
+  const interpolated = "<h1>{t('app.feed.heading', { org: actor.org.name })}</h1>";
+  expect(untranslatedStrings(file(interpolated))).toEqual([]);
+  expect(untranslatedStrings(file(\`<span>{t(\\\`plans.\\\${plan}.name\\\`)}</span>\`))).toEqual([]);
+});
+
+// The other direction: masking a nested child may not swallow the prose beside it.
+unitTest('prose beside an interpolating t() call is still refused', () => {
+  const mixed = "<h1>{t('app.feed.heading', { org: actor.org.name })} Welcome back</h1>";
+  const findings = untranslatedStrings(file(mixed));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.cause).toContain('Welcome back');
+});
+
 // The reason the rule reads a CLOSING tag: a generic type argument is a > followed by source that
 // looks exactly like prose, and a pattern reading to the next < reports every one of them.
 unitTest('a generic type argument is not a JSX text node', () => {

package/src/templates/island.ts

@@ -5,7 +5,7 @@
 // compiles. All three are pinned by the emitted test, which builds the chunk and mounts it.
 
 import type { GeneratedFile } from './naming';
-import { kebab, pascal } from './naming';
+import { camel, kebab, pascal } from './naming';
 
 export interface IslandOptions {
   /** Directory the entry lands in, app-root-relative and POSIX — normally a route's own folder. */
@@ -170,12 +170,55 @@ describe('the ${name} island', () => {
 });
 `;
 
+/**
+ * The states file beside the entry, and it ships WITH the island rather than after it: `x verify`'s
+ * `boundaries` step refuses an island that declares none (`guards/island-without-states.ts`), so a
+ * generator that wrote only the component would scaffold a file that fails the app's own gate on
+ * the next command. The second state is the point of the whole mechanism — a label a translation
+ * is three times as long in is a state nobody can reach by clicking in the locale they develop in.
+ */
+const islandStates = (name: string, dir: string): string => {
+  const Name = pascal(name);
+  return `// The states \`${name}\` can be photographed in. \`x shot --island ${name} --json\` takes one
+// picture per state per theme into \`.x/shot/island/${name}/\`, and the states worth declaring are
+// the ones a running app will not produce on request.
+//
+// PURE DATA. No JSX, no \`solid-js\`, and the one import below is \`import type\`, which
+// \`verbatimModuleSyntax\` erases entirely — the command that takes the pictures has to know the
+// complete expected list before a browser exists. \`X_TEST_ISLAND_STATES_NOT_PURE\` is the refusal.
+//
+// The labels are literals here and that is not a \`t()\` violation: an island's props cross the seam
+// as JSON inside the document, so the SERVER translates and the browser is handed text.
+
+import { defineIslandStates } from '@ultimat3/testing';
+import type { ${Name}Props } from './${name}.island';
+
+export const ${camel(name)}States = defineIslandStates({
+  island: '${dir}/${name}.island.tsx',
+  states: [
+    {
+      id: 'idle',
+      title: 'the first paint, before anything has been clicked',
+      props: { label: 'Open' } satisfies ${Name}Props,
+    },
+    {
+      id: 'long-label',
+      title: 'the label a translation is three times as long in',
+      note: 'you cannot reach this by clicking: it needs a locale whose word for this is long, and the one this was written in is not it',
+      props: { label: 'Abrechnungseinstellungen anzeigen' } satisfies ${Name}Props,
+    },
+  ],
+});
+`;
+};
+
 export function islandFiles(rawName: string, options: IslandOptions): readonly GeneratedFile[] {
   const name = kebab(rawName);
   const dir = options.dir.replace(/\/+$/, '');
   return [
     { path: `${dir}/${name}.island.tsx`, contents: islandSource(name) },
     { path: `${dir}/${name}.module.scss`, contents: islandStyle() },
+    { path: `${dir}/${name}.island.states.ts`, contents: islandStates(name, dir) },
     { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name, dir) },
   ];
 }

package/src/templates/resource-form-island.ts

@@ -265,6 +265,69 @@ describe('the ${feature.kebab} form island', () => {
 });
 `;
 
+/**
+ * The states file beside the entry, and it ships WITH the island rather than after it: `x verify`'s
+ * `boundaries` step refuses an island that declares none (`guards/island-without-states.ts`), so a
+ * generator that wrote only the component would scaffold a file that fails the app's own gate on
+ * the next command.
+ */
+const formIslandStates = (
+  feature: NameSet,
+  dir: string,
+): string => `// The states the ${feature.kebab} form can be photographed in. \`x shot --island ${feature.kebab}-form --json\`
+// takes one picture per state per theme into \`.x/shot/island/${feature.kebab}-form/\`, and the states
+// worth declaring are the ones a running app will not produce on request.
+//
+// PURE DATA. No JSX, no \`solid-js\`, and the one import below is \`import type\`, which
+// \`verbatimModuleSyntax\` erases entirely — the command that takes the pictures has to know the
+// complete expected list before a browser exists. \`X_TEST_ISLAND_STATES_NOT_PURE\` is the refusal.
+//
+// The labels are literals here and that is not a \`t()\` violation: an island's props cross the seam
+// as JSON inside the document, so the SERVER translates and the browser is handed text. These are
+// the text the server would have handed it.
+
+import { defineIslandStates } from '@ultimat3/testing';
+import type { ${feature.pascal}FormProps } from './${feature.kebab}-form.island';
+
+/** What a working render hands the form — the baseline the state below departs from. */
+const BASE = {
+  endpoint: '/api/create-${feature.kebab}',
+  locale: 'en',
+  labels: {
+    title: 'Title',
+    submit: 'Save',
+    saved: 'Saved',
+    retry: 'That did not save. Try again.',
+  },
+} satisfies ${feature.pascal}FormProps;
+
+export const ${feature.camel}FormStates = defineIslandStates({
+  island: '${dir}/${feature.kebab}-form.island.tsx',
+  states: [
+    {
+      id: 'idle',
+      title: 'the first paint, before anything has been typed',
+      props: BASE satisfies ${feature.pascal}FormProps,
+    },
+    {
+      id: 'long-labels',
+      title: 'the same form in a locale whose words are three times as long',
+      note: 'you cannot reach this by clicking: it needs a translation, and the locale this was written in is the one that fits',
+      props: {
+        ...BASE,
+        locale: 'de',
+        labels: {
+          title: 'Bezeichnung des Beitrags',
+          submit: 'Änderungen speichern',
+          saved: 'Änderungen gespeichert',
+          retry: 'Das konnte nicht gespeichert werden. Bitte erneut versuchen.',
+        },
+      } satisfies ${feature.pascal}FormProps,
+    },
+  ],
+});
+`;
+
 /**
  * The slice's form, as the one client shape: `<dir>/<feature>-form.island.tsx` plus its test.
  *
@@ -281,6 +344,10 @@ export function formIslandFiles(
       path: `${dir}/${feature.kebab}-form.island.tsx`,
       contents: formIslandSource(feature, formIslandSpecifier(feature, dir, pageDir)),
     },
+    {
+      path: `${dir}/${feature.kebab}-form.island.states.ts`,
+      contents: formIslandStates(feature, dir),
+    },
     {
       path: `${dir}/${feature.kebab}-form.island.test.ts`,
       contents: formIslandTest(feature, dir),

package/src/templates/scaffold-claude-agents.ts

@@ -131,8 +131,17 @@ calls. A change outside that set is a collision — report it, do not make it.
 | Semantic tokens only | never a raw hex, in a component or a stylesheet |
 | Dates name a zone | explicit IANA time zone at every call site, no ambient default |
 | A page calls primitives | queries and actions, never a repo and never the database |
+| A click needs a control | \`<button>\`, \`<a href>\`, \`<input>\` — never a \`<div onClick>\`, and never \`role="button"\` where the tag exists. A role is a promise: it obliges you to answer Space, Enter, focus and disabled |
+| The focus ring is replaced | \`outline: none\` on its own leaves a keyboard user with nothing. \`@include tokens.focus-ring\`, or a \`:focus-visible\` box-shadow beside it |
+| Every image has a box | width + height, or an aspect-ratio. An unsized image moves everything under it when its bytes land, and the priority one is never \`loading="lazy"\` |
+| Animate transform and opacity | nothing else composites: a \`top\`, a \`width\` or a \`box-shadow\` costs a layout pass every frame, and \`transition: all\` animates properties nobody chose. \`tokens.duration()\` / \`tokens.easing()\` are the values |
+| An island declares its states | a sibling \`<name>.island.states.ts\`, so \`x shot --island <name> --json\` can photograph the failures nobody can click to |
 
-Inspect before you change: \`x routes --json\`, and \`x i18n check\` for catalog gaps.
+Every one of the last five is a build error, not a preference — \`guards/\` holds them and \`x verify\`'s
+\`boundaries\` step runs them. Read the guard rather than guessing at the rule.
+
+Inspect before you change: \`x routes --json\`, \`x i18n check\` for catalog gaps, and
+\`x shot <route> --json\` when you need to see what you built.
 
 Checks: \`bun test <path>/page.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
 once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.

package/src/templates/scaffold-claude-commands.ts

@@ -6,7 +6,7 @@
 import type { GeneratedFile, NameSet } from './naming';
 
 const feature = (app: NameSet): string => `---
-description: Build or fix one thing in ${app.kebab} end to end — name the primitive, generate it, wire it inside the boundaries, gate it with \`x verify\`.
+description: Build or fix one thing in ${app.kebab} end to end — name the primitive, generate it, wire it inside the boundaries, gate it with \`bin/check\`.
 argument-hint: <what you want built or fixed, plain language>
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, Skill
 ---
@@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, Skill
 You are a senior engineer on **${app.kebab}**, an Ultimate app. Read \`AGENTS.md\` before designing
 anything — it is the short form of every rule below, and it wins where the two disagree.
 
-**Done means \`x verify\` green.** A passing unit test is not done. A working \`x dev\` is not done.
+**Done means \`bin/check\` green.** A passing unit test is not done. A working \`x dev\` is not done.
 Report what you actually ran, never what you assume passed.
 
 ## Request
@@ -77,10 +77,16 @@ the filename never is. One interactive control on a 0kb page is an island: \`x g
 ## 4. Gate it
 
 \`\`\`sh
-x verify                # the gate. green = shippable
-x verify --json         # the same steps, machine-readable
+bin/check               # the gate. green = shippable
+bin/check --json        # the same, machine-readable
 \`\`\`
 
+\`bin/check\` is \`x build --target static\` and THEN \`x verify\`, and the order is the whole point:
+the \`budgets\` step measures \`.x/build-stats.json\`, which only a build writes, so \`x verify\` on
+its own reports X_BUDGET_UNMEASURED on a tree that is fine. \`--json\` is forwarded to both halves;
+a machine consumer takes the last line. CI runs this same script — \`.github/workflows/ci.yml\` is
+\`bin/setup\` and then \`bin/check\`, nothing else.
+
 Red is instructions, not a verdict: **every finding carries an executable \`fix:\` — run it verbatim
 before improvising**, and \`x errors explain <CODE>\` expands any code it names. Never narrow the gate
 to make it pass: there is no \`--only\` and no \`--skip\`, on purpose, and disabling a lint rule or
@@ -112,7 +118,7 @@ ISO code, never a float. Bun only.
 Primitive:  <which of the eight>    Slice: <dir>
 Generated:  <the x g invocations you ran>
 Changed:    <files>
-Gate:       x verify ✓ | ✗ <failing steps>
+Gate:       bin/check ✓ | ✗ <failing steps>
 Deferred:   <what you did not do, and why>      [never omit this line]
 \`\`\`
 `;
@@ -166,7 +172,7 @@ slice it lives in. If it fits none, the design is wrong — say so here instead
 - What to add, next to the source as \`<file>.test.ts\`. Command to run it.
 
 ## Done when
-- Acceptance criteria, ending in \`x verify\` green.
+- Acceptance criteria, ending in \`bin/check\` green.
 
 ## Risks
 - Anything the executor must decide, and every claim in the ask the code disproves.
@@ -179,7 +185,7 @@ slice it lives in. If it fits none, the design is wrong — say so here instead
 - No checkboxes. The plan is a map, not a tracker.
 - The plan must obey the app's own rules — one way to do each thing, generators over hand-written
   files, imports that never cross a surface boundary, a stable error code with a runnable \`fix:\` for
-  every new failure, and \`x verify\` green as the last line of *Done when*.
+  every new failure, and \`bin/check\` green as the last line of *Done when*.
 
 ## Output
 
@@ -196,13 +202,18 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 # /verify
 
-Run \`x verify\`.
+Run \`bin/check\`.
+
+It is \`x build --target static\` and then \`x verify\`, and it is THE gate — the one CI runs
+(\`.github/workflows/ci.yml\`) and the one \`README.md\` names. \`x verify\` alone is half of it:
+the \`budgets\` step measures \`.x/build-stats.json\`, which only the build writes, so a bare
+\`x verify\` reports X_BUDGET_UNMEASURED on a tree with nothing wrong with it.
 
 Green: say so and stop.
 
 Red: fix every finding, then re-run until green. Each finding carries a stable code, a cause and an
 executable \`fix:\` — **run the \`fix:\` verbatim before improvising**, and use \`x errors explain <CODE>\`
-when the cause is not enough. \`x verify --json\` gives the same steps machine-readably; \`x doctor\`
+when the cause is not enough. \`bin/check --json\` gives the same steps machine-readably; \`x doctor\`
 covers the case where the environment, not the code, is what is broken.
 
 Do not narrow the gate to make it pass. There is no \`--only\` and no \`--skip\`; disabling a lint rule,