@estiva-app/ui 0.35.1 → 0.36.0

package/src/gates/create-app.ts

@@ -284,7 +284,8 @@ import reactHooks from 'eslint-plugin-react-hooks'
  * TypeScript's the package names itself.
  *
  * A place that keeps something the gate refuses says why, on the line above:
- * \`// @estiva-escape: <reason>\`. Never \`eslint-disable\`: the count refuses it.
+ * \`// @estiva-escape(<rule>): <reason>\`, naming the rule it keeps off. Never
+ * \`eslint-disable\`: the count refuses it.
  */
 export default gateConfig({ quiet: { 'react-hooks': reactHooks } })
 `,
@@ -316,8 +317,14 @@ export default function define(h) {
 Nothing. ${title} was made with every gate on, at zero.
 
 It should stay that way. A place that keeps something the gate refuses says why on
-the line above it, \`// @estiva-escape: <reason>\`, and the count lists it; a whole
-file that cannot pass yet goes here, with its reason.
+the line above it, \`// @estiva-escape(<rule>): <reason>\`. This page does not list those:
+\`npm run gates:status -- --escapes\` does, from the code, with each one's age, and
+\`npm run gates:status\` shows the ones older than 30 days, to keep with a new reason or fix.
+
+## Folders the gate does not read
+
+None. A folder the gate skips is named here, with why; CI's job \`gate\` fails on one
+that is not.
 `,
 
     '.github/workflows/deploy.yml': `name: deploy
@@ -382,16 +389,14 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
-      - name: Gate lint
-        run: npm run lint:rules
-      # Colours, type, corners and shadows from the preset only. In \`check\` too,
-      # inside \`npm run lint\`, but only \`gate\` blocks a merge.
-      - name: Token lint
-        run: npm run lint:tokens
-      # Every part of the app says in one line what it is for, so the catalogue
-      # (\`npm run ui:find\`) can offer it before someone builds it again.
-      - name: Every part is described
-        run: npm run registry:check
+      # Every step of the gate, the same command Peek and Ship run: the gate
+      # lint and \`.gates-count.json\` (committed, or this fails), the token
+      # contract, the catalogue (every part says in one line what it is for),
+      # and the wall's own settings: the editor hook in .claude/settings.json
+      # refuses a raw button, and every folder the gate skips is named in
+      # docs/GATES-DEBT.md.
+      - name: The gate (estiva-gates ci)
+        run: npx estiva-gates ci
 `,
 
     'src/index.css': `@import '@estiva-app/ui/tokens.css';
@@ -996,12 +1001,13 @@ nothing arrives.
 |---|---|
 | \`npm run typecheck\` | TypeScript, the app and its settings files |
 | \`npm run lint\` | everything: TypeScript's and React's rules, the token contract, the gate |
-| \`npm run lint:rules\` | the gate alone, and \`.gates-count.json\` — CI's job \`gate\` |
+| \`npm run lint:rules\` | the gate alone, and \`.gates-count.json\` |
 | \`npm test\` | the tests |
 | \`npm run build\` | the build |
 | \`npm run gates:status\` | which gates are on, read from the code |
 | \`npm run ui:find <words>\` | what the package and this app already have for it |
-| \`npm run registry:check\` | every part says what it is for — CI's job \`gate\` |
+| \`npm run registry:check\` | every part says what it is for |
+| \`npx estiva-gates ci\` | every step of CI's job \`gate\`: the gate, its count committed, the tokens, the catalogue, the hook |
 | \`npm run storybook\` | the stories |
 
 The gates are the package's, imported rather than copied, so a rule written later
@@ -1026,7 +1032,7 @@ instead. What it refuses is the package's to say, and grows with it: the
 (the hook in \`.claude/settings.json\`, for a session started in this folder), in
 \`npm run lint:rules\` and in CI. A session started elsewhere: run
 \`npm run lint:rules\` after changing \`src/\`, and fix what it reports. Keep something
-only with its reason on the line above, \`// @estiva-escape: <reason>\`, never with
+only with its reason on the line above, \`// @estiva-escape(<rule>): <reason>\`, never with
 \`eslint-disable\`.
 
 **Tokens only.** Colours, type, corners and shadows come from the package's preset.

package/src/gates/escapes.ts

@@ -0,0 +1,111 @@
+/// <reference types="node" />
+/**
+ * Every escape in a repository, listed (Katerina's ruling B1, 25 September):
+ * where it is, which rules it keeps off, why, and how old it is.
+ *
+ * The count (`.gates-count.json`) holds numbers per rule; the plan asked for
+ * escapes "listed in a report, reviewed", and the hand-written debt pages had
+ * drifted from the count in all three repos. This reads the markers themselves,
+ * both forms:
+ *
+ * - the gate's, `// @estiva-escape(<rule>): <reason>` (or in a JSX comment);
+ * - the token lint's, `// eslint-disable-next-line <rule> -- @estiva-escape: <reason>`
+ *   (ruling A2, 15 September), which no count sees.
+ *
+ * Age comes from git (the day the marker's line was last written), so it cannot
+ * be forgotten or faked. Review is by age, monthly: `gates:status` shows every
+ * escape older than {@link REVIEW_AFTER_DAYS} days, and Katerina keeps it (with
+ * a new reason) or it gets fixed.
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { readMarker } from '../eslint/escape'
+
+/** An escape older than this many days is shown for review. */
+export const REVIEW_AFTER_DAYS = 30
+
+export interface Escape {
+  file: string
+  line: number
+  /** The rules it keeps off, as the marker names them. */
+  rules: string[]
+  reason: string
+  /** Whole days since the marker's line was written, or null outside git. */
+  days: number | null
+  /** `gate` for the gate's marker, `token` for the token lint's directive. */
+  kind: 'gate' | 'token'
+}
+
+const SOURCE = /\.[cm]?[jt]sx?$/
+const SKIP = new Set(['node_modules', 'dist', '.git', 'storybook-static', 'coverage'])
+const DIRECTIVE = /eslint-disable(?:-next-line|-line)?\s+(.*?)\s+--\s+@estiva-escape\s*:?\s*(.*)$/
+
+function sourceFiles(dir: string, out: string[] = []): string[] {
+  if (!existsSync(dir)) return out
+  for (const name of readdirSync(dir)) {
+    if (SKIP.has(name)) continue
+    const path = join(dir, name)
+    if (statSync(path).isDirectory()) sourceFiles(path, out)
+    else if (SOURCE.test(name) && !/\.test\.[cm]?[jt]sx?$/.test(name)) out.push(path)
+  }
+  return out
+}
+
+/** The day each line of a file was last written, from `git blame`, in seconds since 1970. */
+function lineTimes(root: string, file: string): Map<number, number> {
+  const times = new Map<number, number>()
+  try {
+    const out = execFileSync('git', ['blame', '--line-porcelain', '--', relative(root, file)], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 << 20 }).toString()
+    let line = 0
+    for (const row of out.split('\n')) {
+      const header = /^[0-9a-f]{40} \d+ (\d+)/.exec(row)
+      if (header) line = Number(header[1])
+      else if (row.startsWith('author-time ')) times.set(line, Number(row.slice(12)))
+    }
+  } catch {
+    // Not in git, or a file git does not track yet: its escapes have no age.
+  }
+  return times
+}
+
+/** Every escape under `src`, and in any other folder named, oldest first. */
+export function listEscapes(root: string, { folders = ['src'], now = Date.now() }: { folders?: string[]; now?: number } = {}): Escape[] {
+  const found: Escape[] = []
+  for (const file of folders.flatMap((f) => sourceFiles(join(root, f)))) {
+    const lines = readFileSync(file, 'utf8').split(/\r?\n/)
+    const hits: Omit<Escape, 'days'>[] = []
+    lines.forEach((text, i) => {
+      if (!text.includes('@estiva-escape')) return
+      const rel = relative(root, file).split('\\').join('/')
+      // A real marker opens its comment; documentation mentions one mid-sentence, or with a placeholder.
+      if (/<(reason|why|rule)\b/.test(text)) return
+      const directive = /^\s*(?:\/\/|\{?\/\*)\s*eslint-disable/.test(text) ? DIRECTIVE.exec(text) : null
+      if (directive) {
+        hits.push({ file: rel, line: i + 1, rules: directive[1].split(/[\s,]+/).filter(Boolean), reason: directive[2].replace(/\*\/\s*}?\s*$/, '').trim(), kind: 'token' })
+        return
+      }
+      if (!/^\s*(?:\/\/+|\{?\/\*+)?\s*@estiva-escape(?:\s*\(|\s*:)/.test(text)) return
+      const marker = readMarker(text)
+      if (!marker) return
+      hits.push({ file: rel, line: i + 1, rules: marker.rules, reason: marker.reason.replace(/\*\/\s*}?\s*$/, '').trim(), kind: 'gate' })
+    })
+    if (!hits.length) continue
+    const times = lineTimes(root, file)
+    for (const hit of hits) {
+      const at = times.get(hit.line)
+      found.push({ ...hit, days: at === undefined ? null : Math.floor((now - at * 1000) / 86_400_000) })
+    }
+  }
+  return found.sort((a, b) => (b.days ?? -1) - (a.days ?? -1) || a.file.localeCompare(b.file) || a.line - b.line)
+}
+
+/** The lines `gates:status` prints: a total, and every escape due for review (or every one, with `all`). */
+export function escapeLines(escapes: Escape[], { all = false }: { all?: boolean } = {}): string[] {
+  const due = escapes.filter((e) => (e.days ?? 0) > REVIEW_AFTER_DAYS)
+  const shown = all ? escapes : due
+  const gate = escapes.filter((e) => e.kind === 'gate').length
+  const out = [`Escapes: ${escapes.length} (${gate} of the gate's, ${escapes.length - gate} of the token lint's) · ${due.length} older than ${REVIEW_AFTER_DAYS} days, to review: keep with a new reason, or fix${all ? '' : ' · every escape: add -- --escapes'}`]
+  for (const e of shown) out.push(`  ${e.file}:${e.line}  ${e.rules.join(', ') || '(no rule named)'} · ${e.days === null ? 'not in git yet' : `${e.days} days`}\n      ${e.reason}`)
+  return out
+}

package/src/gates/gate-config.ts

@@ -21,6 +21,7 @@ import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
 import { parser as typescriptParser } from 'typescript-eslint'
 import estiva from '../eslint/index'
 import { KNOWN_PLUGINS, TOKEN_LINT_IGNORES } from './token-lint'
+import { tokenStylePlugin } from './token-style'
 
 export interface GateConfigOptions {
   /** `app` (the default) runs `configs.recommended`; `package` runs this package's inward set. */
@@ -44,8 +45,10 @@ export interface GateConfigOptions {
 export function gateLint({ audience = 'app' }: Pick<GateConfigOptions, 'audience'> = {}): Linter.Config {
   return {
     ...(audience === 'package' ? estiva.configs.package : estiva.configs.recommended),
-    files: audience === 'package' ? ['src/**/*.tsx'] : ['src/**/*.{ts,tsx}'],
-    ignores: ['**/*.test.ts', '**/*.test.tsx'],
+    // An app's every script type: a raw <button> in a .jsx, or a key listener in a .mts,
+    // passed while only .ts and .tsx were read (the re-review after the audit before UIG-26).
+    files: audience === 'package' ? ['src/**/*.tsx'] : ['src/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'],
+    ignores: ['**/*.test.*'],
     languageOptions: {
       parser: typescriptParser,
       parserOptions: { ecmaFeatures: { jsx: true } },
@@ -68,6 +71,7 @@ export function gateConfig({ audience = 'app', quiet = {}, ignores = [] }: GateC
         'better-tailwindcss': betterTailwindcss,
         'token-values': betterTailwindcss,
         'token-spacing': betterTailwindcss,
+        'token-style': tokenStylePlugin,
       },
       // Every other config's directives are unused here, because their rules are
       // off here. Reporting them would be this config complaining about the

package/src/gates/gates.test.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { ESLint, type Linter } from 'eslint'
 import { afterAll, describe, expect, it } from 'vitest'
+import { countCommitted, hookRuns, skippedFolders, skipsListed } from './ci'
 import { writeGateCount } from './count'
 import { gateConfig, gateLint } from './gate-config'
 import { runHook } from './hook'
@@ -78,6 +79,18 @@ describe('tokenLint and tokenValues', () => {
     expect(await lintWith([tokenLint()], "import { cn } from '@estiva-app/ui'\nexport const merged = cn('p-2', 'p-3')\n", 'src/lib/probe.ts')).toEqual([])
   })
 
+  it('refuse a colour in a style with its key in quotes, or kept in a const (R9)', async () => {
+    const quoted = await lintWith([tokenLint(), tokenValues()], component(`<div style={{ 'background': 'red' }}>x</div>`), 'src/Probe.tsx')
+    expect(quoted.filter((m) => m.severity === 2).map((m) => m.ruleId)).toEqual(['no-restricted-syntax'])
+    const kept = `const look = { background: 'red', width: 20 } as const\n${component('<div style={look}>x</div>')}`
+    const constant = await lintWith([tokenLint(), tokenValues()], kept, 'src/Probe.tsx')
+    expect(constant.filter((m) => m.severity === 2)).toEqual([expect.objectContaining({ ruleId: 'token-style/no-token-style', line: 1 })])
+    // A size in a const, and a style worked out while it runs, pass.
+    expect((await lintWith([tokenLint(), tokenValues()], `const at = { width: 20 }\n${component('<div style={at}><div style={props.style} /></div>')}`, 'src/Probe.tsx')).filter((m) => m.severity === 2)).toEqual([])
+    // Its escape works in the gate too: the gate knows the rule's name.
+    expect(await lintWith(gateConfig(), `// eslint-disable-next-line token-style/no-token-style -- @estiva-escape: a colour the probe keeps\n${kept}`, 'src/Probe.tsx')).toEqual([])
+  })
+
   it('leave a test file to its test', async () => {
     const messages = await lintWith([tokenLint(), tokenValues()], component('<div style={{ color: "red" }}>x</div>'), 'src/Probe.test.tsx')
     expect(messages.filter((m) => m.severity === 2)).toEqual([])
@@ -147,7 +160,7 @@ describe('tokenConfig', () => {
 describe('writeGateCount', () => {
   it('writes the count once, leaves it alone when nothing changed, and fails on a rule switched off', async () => {
     const dir = app('count', {
-      'src/Kept.tsx': component('(\n    // @estiva-escape: a probe that keeps its element on purpose\n    <form />\n  )'),
+      'src/Kept.tsx': component('(\n    // @estiva-escape(no-raw-element): a probe that keeps its element on purpose\n    <form />\n  )'),
     })
     const first = await writeGateCount({ root: dir, repo: 'probe' })
     expect(first.changed).toBe(true)
@@ -164,6 +177,47 @@ describe('writeGateCount', () => {
   })
 })
 
+describe('estiva-gates ci: the steps no lint runs (B2, B13)', () => {
+  const git = (dir: string, ...args: string[]) => execFileSync('git', ['-c', 'user.name=probe', '-c', 'user.email=probe@example.com', ...args], { cwd: dir, stdio: 'ignore' })
+
+  it('fails when the count the gate writes is not the committed one', async () => {
+    const dir = app('ci-count', { 'src/Plain.tsx': component('<div>x</div>') })
+    git(dir, 'init', '-q')
+    await writeGateCount({ root: dir, repo: 'probe' })
+    git(dir, 'add', '.')
+    git(dir, 'commit', '-q', '-m', 'count')
+    expect(countCommitted(dir)).toEqual([])
+    writeFileSync(join(dir, 'src', 'Kept.tsx'), component('(\n    // @estiva-escape(no-raw-element): a probe that keeps its element on purpose\n    <form />\n  )'))
+    await writeGateCount({ root: dir, repo: 'probe' })
+    const moved = countCommitted(dir)
+    expect(moved[0]).toContain('commit `.gates-count.json`')
+    expect(moved.join('\n')).toContain('"escapes": 1')
+  })
+
+  it('fails when no hook runs before both Write and Edit, or the hook lets a raw button through', () => {
+    const cli = join(root, 'dist', 'gates', 'cli.js').split('\\').join('/')
+    const settings = (matcher: string, command: string) => JSON.stringify({ hooks: { PreToolUse: [{ matcher, hooks: [{ type: 'command', command }] }] } })
+    const dir = app('ci-hook', { '.claude/settings.json': settings('Edit|Write', `node "${cli}" hook`) })
+    expect(hookRuns(dir)).toEqual([])
+    writeFileSync(join(dir, '.claude', 'settings.json'), settings('Write', `node "${cli}" hook`))
+    expect(hookRuns(dir)[0]).toContain('before both Write and Edit')
+    writeFileSync(join(dir, '.claude', 'settings.json'), settings('Edit|Write', 'node -e "process.exit(0)"'))
+    expect(hookRuns(dir)[0]).toContain('let a raw button through')
+    rmSync(join(dir, '.claude'), { recursive: true })
+    expect(hookRuns(dir)[0]).toContain('missing')
+  })
+
+  it('fails when the gate skips a folder the debt page does not name', async () => {
+    const dir = app('ci-skips', { 'docs/GATES-DEBT.md': '# Debt\n\nNothing skipped.\n' })
+    expect(await skipsListed(dir, 'app')).toEqual([])
+    writeFileSync(join(dir, 'eslint.gates.config.js'), `import { gateConfig } from '${built}'\nexport default gateConfig({ ignores: ['demo-scenarios/**'] })\n`)
+    expect(await skippedFolders(dir)).toEqual(['demo-scenarios/**'])
+    expect((await skipsListed(dir, 'app')).join('\n')).toContain('demo-scenarios/**')
+    writeFileSync(join(dir, 'docs', 'GATES-DEBT.md'), '# Debt\n\n`demo-scenarios` is not checked: fixtures for the demo, never shipped.\n')
+    expect(await skipsListed(dir, 'app')).toEqual([])
+  })
+})
+
 describe('runHook', () => {
   const dir = app('hook', { 'src/Page.tsx': 'export function Page() {\n  return <div>x</div>\n}\n' })
   const write = (file_path: string, content: string) => ({ tool_name: 'Write', tool_input: { file_path, content } })
@@ -182,6 +236,36 @@ describe('runHook', () => {
     expect((await runHook({ root: dir, input: fine })).code).toBe(0)
   })
 
+  // B4 (Katerina, 25 September): the token contract is refused before the write, not only in CI.
+  it('refuses a hand-written size and a raw colour before the write, naming the token', async () => {
+    const result = await runHook({ root: dir, input: write('src/Probe.tsx', component('<div className="text-[13px] bg-[#ff0000]">x</div>')) })
+    expect(result.code).toBe(2)
+    expect(result.message).toContain('token-values/no-restricted-classes')
+  })
+
+  // R10: a copied look only warns, so the write goes through, with a note Claude sees.
+  it('lets a copied look through with a note, and no note when nothing is copied', async () => {
+    const own = app('hook-copied', {
+      // An app's Tailwind config, on the package preset: the token lint knows its classes from it.
+      'tailwind.config.js': `import estiva from '${pathToFileURL(join(root, 'tailwind-preset.js')).href}'\nexport default { presets: [estiva], content: ['./src/**/*.tsx'] }\n`,
+      'src/Badge.tsx': '/** A badge. */\nexport function Badge() {\n  return <span className="inline-flex items-center rounded-md border border-border-default bg-bg-elevated px-2 text-caption text-text-secondary">x</span>\n}\n',
+      // Already there, so the write is an edit of a part, not a new one the search stops.
+      'src/Probe.tsx': component('<span>y</span>'),
+    })
+    const copied = await runHook({ root: own, input: write('src/Probe.tsx', component('<span className="inline-flex items-center rounded-md border border-border-default bg-bg-elevated px-2 text-caption text-text-secondary">y</span>')) })
+    expect(copied.code).toBe(0)
+    expect(copied.note).toContain('Badge')
+    const plain = await runHook({ root: own, input: write('src/Probe.tsx', component('<span className="mt-2">y</span>')) })
+    expect(plain).toEqual({ code: 0, message: '' })
+  })
+
+  // The re-review after the audit before UIG-26: only .ts and .tsx were read, so these passed.
+  it('reads every script type under src: a raw button in a .jsx, a page listener in a .mts', async () => {
+    expect((await runHook({ root: dir, input: write('src/Probe.jsx', component('<button type="button">x</button>')) })).code).toBe(2)
+    expect((await runHook({ root: dir, input: write('src/lib/probe.mts', "export function listen() {\n  document.addEventListener('keydown', () => {})\n}\n") })).code).toBe(2)
+    expect((await runHook({ root: dir, input: write('src/Probe.test.jsx', component('<button type="button">x</button>')) })).code).toBe(0)
+  })
+
   it('lets through a test, a declaration file, and anything outside src', async () => {
     for (const path of ['src/Probe.test.tsx', 'src/types.d.ts', 'scripts/probe.tsx']) {
       expect((await runHook({ root: dir, input: write(path, component('<button type="button">x</button>')) })).code).toBe(0)
@@ -235,6 +319,14 @@ describe('gates:status', () => {
     expect(h.ciJob('gate', 'lint:rules').result).toBe('pass')
     expect(h.ciJob('check', 'lint:rules').result).toBe('fail')
     expect(h.script('package.json', 'gates:status').result).toBe('pass')
+    // A job that runs `estiva-gates ci` runs the gate's scripts (R13), and nothing else.
+    writeFileSync(join(dir, '.github', 'workflows', 'deploy.yml'), 'jobs:\n  gate:\n    steps:\n      - run: npx estiva-gates ci\n')
+    expect(h.ciJob('gate', 'lint:rules').result).toBe('pass')
+    expect(h.ciJob('gate', 'registry:check').result).toBe('pass')
+    expect(h.ci('lint:tokens').result).toBe('pass')
+    expect(h.ciJob('gate', 'test').result).toBe('fail')
+    writeFileSync(join(dir, '.github', 'workflows', 'deploy.yml'), 'jobs:\n  gate:\n    steps:\n      # - run: npx estiva-gates ci\n      - run: npm test\n')
+    expect(h.ciJob('gate', 'lint:rules').result).toBe('fail')
   })
 
   // Audit A2: a hook is judged by running it, the way Claude Code does, on a raw

package/src/gates/hook.ts

@@ -13,7 +13,9 @@
  * UIG-4 findings).
  *
  * It runs the gate's own config and reimplements nothing: a hook and a lint
- * that could disagree would be worse than neither. Tests are not checked
+ * that could disagree would be worse than neither. Since 0.36.0 it runs the
+ * token contract too, keeping only that contract's errors (B4), and a copied
+ * look, which only warns, reaches Claude as a note on a write let through (R10). Tests are not checked
  * (Katerina, 13 September); stories are. This package's inward gate reads `.tsx`
  * only, as its lint does.
  *
@@ -37,8 +39,9 @@ import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import type { ESLint as ESLintClass } from 'eslint'
+import type { ESLint as ESLintClass, Linter } from 'eslint'
 import { countGates } from '../eslint/index'
+import { tokenConfig } from './token-lint'
 import { repositoryOf } from '../registry/skill'
 
 export interface HookOptions {
@@ -59,6 +62,27 @@ export interface HookResult {
   code: 0 | 2
   /** What goes to stderr when refused. */
   message: string
+  /** A note for Claude on a write let through: a copied look, which only warns. */
+  note?: string
+}
+
+/** The token contract's own rules: what the hook keeps from its lint, and nothing else. */
+const TOKEN_RULE_IDS = new Set(tokenConfig().flatMap((c) => Object.keys(c.rules ?? {})))
+
+/**
+ * The token contract's errors for the text about to be written. The app's own
+ * token config when it has one (`eslint.tokens.config.js`, which knows the app's
+ * other plugins' names); otherwise the package's `tokenConfig`. Only the token
+ * rules' errors count, so an app's wider lint (TypeScript's, React's) never
+ * blocks a write that is still being made.
+ */
+async function tokenErrors(ESLint: typeof ESLintClass, appDir: string, file: string, text: string, audience: 'app' | 'package'): Promise<Linter.LintMessage[]> {
+  const own = join(appDir, 'eslint.tokens.config.js')
+  const eslint = existsSync(own)
+    ? new ESLint({ cwd: appDir, overrideConfigFile: own })
+    : new ESLint({ cwd: appDir, overrideConfigFile: true, overrideConfig: tokenConfig({ audience }) })
+  const results = await eslint.lintText(text, { filePath: file })
+  return results.flatMap((r) => r.messages.filter((m) => m.severity === 2 && m.ruleId && TOKEN_RULE_IDS.has(m.ruleId)))
 }
 
 interface ToolCall {
@@ -69,6 +93,8 @@ interface ToolCall {
 }
 
 const PASS: HookResult = { code: 0, message: '' }
+/** An app's source the gate reads: every script type, with or without JSX. */
+const APP_SOURCE = /^src\/.+\.[cm]?[jt]sx?$/
 
 export async function runHook({ root, app = '.', audience = 'app', input, seen }: HookOptions = {}): Promise<HookResult> {
   let call: ToolCall
@@ -84,8 +110,10 @@ export async function runHook({ root, app = '.', audience = 'app', input, seen }
   const appDir = resolve(top, app)
   const file = isAbsolute(args.file_path) ? args.file_path : resolve(call.cwd ?? top, args.file_path)
   const rel = relative(appDir, file).split(sep).join('/')
-  const source = audience === 'package' ? /^src\/.+\.tsx$/ : /^src\/.+\.tsx?$/
-  if (rel.startsWith('../') || isAbsolute(rel) || !source.test(rel) || /\.test\.tsx?$/.test(rel) || /\.d\.ts$/.test(rel)) return PASS
+  // Every script under an app's src/, as the gate reads it (a raw <button> in a .jsx passed
+  // before, the re-review after the audit before UIG-26); the package's own gate is .tsx only.
+  const source = audience === 'package' ? /^src\/.+\.tsx$/ : APP_SOURCE
+  if (rel.startsWith('../') || isAbsolute(rel) || !source.test(rel) || /\.test\.[cm]?[jt]sx?$/.test(rel) || /\.d\.[cm]?ts$/.test(rel)) return PASS
 
   const text = proposed(call.tool_name, args, file)
   if (text === null) return PASS
@@ -99,14 +127,24 @@ export async function runHook({ root, app = '.', audience = 'app', input, seen }
   // A rule's errors only. Code that does not parse yet (one edit of several) is
   // the typecheck's to judge; the gate looks again at the edit that completes it.
   const errors = results.flatMap((r) => r.messages.filter((m) => m.severity === 2 && m.ruleId))
+  // The token contract too (Katerina's ruling B4, 25 September): a colour or a size
+  // is refused before the write, as CI's gate refuses it, not only at the PR.
+  errors.push(...(await tokenErrors(ESLint, appDir, file, text, audience)))
   const { disabled } = countGates(results)
-  if (errors.length === 0 && disabled.length === 0) return searchFirst(call, file, text, appDir, top, seen) ?? PASS
+  if (errors.length === 0 && disabled.length === 0) {
+    const stopped = searchFirst(call, file, text, appDir, top, seen)
+    if (stopped) return stopped
+    // A copied look is a warning (C2): it never blocks, and Claude hears of it now,
+    // not only in CI (R10, 25 September).
+    const copies = results.flatMap((r) => r.messages.filter((m) => m.severity === 1 && m.ruleId === 'estiva/no-copied-look'))
+    return copies.length ? { code: 0, message: '', note: copies.map((m) => `${relative(top, file).split(sep).join('/')}:${m.line}  ${m.message}`).join('\n') } : PASS
+  }
 
   const shown = (p: string) => relative(top, p).split(sep).join('/')
   const lines = [`${shown(file)} was not written: the UI Guardrails refuse it (${shown(config)}).`]
   for (const m of errors) lines.push(`  ${m.line}:${m.column}  ${m.message}${m.ruleId ? `  (${m.ruleId})` : ''}`)
   const keep = audience === 'package' ? 'Keep it only' : 'Keep the element only'
-  for (const d of disabled) lines.push(`  ${d.line}  an eslint-disable switches ${d.ruleId} off. ${keep} with its reason on the line above: // @estiva-escape: <reason>`)
+  for (const d of disabled) lines.push(`  ${d.line}  an eslint-disable switches ${d.ruleId} off. ${keep} with its reason on the line above: // @estiva-escape(${d.ruleId.slice(d.ruleId.lastIndexOf('/') + 1)}): <reason>`)
   return { code: 2, message: `${lines.join('\n')}\n` }
 }
 

package/src/gates/index.ts

@@ -11,21 +11,25 @@
  * - `tokenConfig` — the token lint on its own, as `lint:tokens` runs it (UIG-37).
  * - `gateLint`, `gateConfig` — where the rules apply, and the gate that runs them alone.
  * - `writeGateCount` — `.gates-count.json` (seam S3).
+ * - `runCi` — CI's job `gate`, every step of it (R13).
  * - `runHook` — the editor gate a `PreToolUse` hook runs.
  * - `runStatus`, `helpers` — gates:status and the helpers a checks file is written with.
  *
  * - `appChecks` — the gate checks every app runs, for its `scripts/gates-checks.mjs`.
  * - `appFiles`, `createApp`, `themes` — a new app with every gate on (`create-estiva-app`).
  *
- * `estiva-gates` (`cli.ts`) runs the count, the hook and the status as one command.
+ * `estiva-gates` (`cli.ts`) runs the gate's CI, the count, the hook and the status as one command.
  *
  * Built by build.mjs into `dist/gates/`, for Node. Nothing here reaches the
  * components' browser bundle.
  */
 export { TOKEN_LINT_IGNORES, tokenConfig, tokenLint, tokenValues, type TokenAudience, type TokenConfigOptions, type TokenLintOptions } from './token-lint'
 export { gateConfig, gateLint, type GateConfigOptions } from './gate-config'
+export { countCommitted, hookRuns, runCi, skippedFolders, skipsListed, type CiOptions } from './ci'
 export { writeGateCount, type CountOptions, type CountResult } from './count'
 export { runHook, type HookOptions, type HookResult } from './hook'
+export { nameEscapes, type NameEscapesOptions, type NameEscapesResult } from './name-escapes'
+export { escapeLines, listEscapes, REVIEW_AFTER_DAYS, type Escape } from './escapes'
 export { ENGINE, helpers, runStatus, type CheckResult, type GateCheck, type GateHelpers, type GateSpec, type GateTicket, type LintProbe, type StatusOptions, type TicketListEntry } from './status'
 export { APP_TICKET_TITLES, appChecks, type AppCheckOptions } from './app-checks'
 export { appFiles, askNpm, createApp, themes, type CreateAppOptions } from './create-app'

package/src/gates/name-escapes.ts

@@ -0,0 +1,77 @@
+/// <reference types="node" />
+/**
+ * `estiva-gates name-escapes`: write into every escape marker the rules it keeps
+ * off, once (Katerina's ruling B3, 25 September).
+ *
+ * A marker used to keep off every rule on its element; now it keeps off only the
+ * rules it names, `// @estiva-escape(no-raw-element): <reason>`. So that nothing
+ * that was escaped breaks, this asks the gate itself which rules each unnamed
+ * marker stands for: linted with the new reader, an unnamed marker is reported
+ * once per rule that finds its element ("Name the rule … `@estiva-escape(<rule>)`"),
+ * and those names are written into the marker. Nothing is guessed, and a marker
+ * no rule reaches is left as it is and listed.
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { ESLint as ESLintClass } from 'eslint'
+
+export interface NameEscapesOptions {
+  /** The folder the gate lints from. */
+  root?: string
+  /** The gate's config file, relative to `root`. */
+  config?: string
+}
+
+export interface NameEscapesResult {
+  /** One line per marker rewritten: `file:line  rule, rule`. */
+  named: string[]
+  /** Markers no rule reached, left unnamed. */
+  unreached: string[]
+}
+
+const UNNAMED = /@estiva-escape(?!\s*\()/
+const NAMED_IN_MESSAGE = /@estiva-escape\(([^)]+)\)/
+
+export async function nameEscapes({ root = process.cwd(), config = 'eslint.gates.config.js' }: NameEscapesOptions = {}): Promise<NameEscapesResult> {
+  const resolved = createRequire(join(root, 'package.json')).resolve('eslint')
+  const { ESLint } = (await import(pathToFileURL(resolved).href)) as { ESLint: typeof ESLintClass }
+  const eslint = new ESLint({ cwd: root, overrideConfigFile: join(root, config) })
+  const results = await eslint.lintFiles(['.'])
+
+  const named: string[] = []
+  const unreached: string[] = []
+  for (const result of results) {
+    // The rules each unnamed marker stands for, by the line its comment starts on.
+    const byLine = new Map<number, Set<string>>()
+    for (const m of result.messages) {
+      if (m.messageId !== 'escapeWithoutRule') continue
+      const rule = NAMED_IN_MESSAGE.exec(m.message)?.[1]
+      if (!rule) continue
+      byLine.set(m.line, (byLine.get(m.line) ?? new Set()).add(rule))
+    }
+    const source = result.source ?? readFileSync(result.filePath, 'utf8')
+    const eol = source.includes('\r\n') ? '\r\n' : '\n'
+    const lines = source.split(/\r?\n/)
+    let changed = false
+    const file = relative(root, result.filePath).split('\\').join('/')
+    for (const [line, rules] of byLine) {
+      // The marker is on the comment's first line, or within the next few (a block comment).
+      for (let i = line - 1; i < Math.min(lines.length, line + 3); i++) {
+        if (!UNNAMED.test(lines[i])) continue
+        const names = [...rules].sort().join(', ')
+        lines[i] = lines[i].replace(UNNAMED, `@estiva-escape(${names})`)
+        named.push(`${file}:${i + 1}  ${names}`)
+        changed = true
+        break
+      }
+    }
+    if (changed) writeFileSync(result.filePath, lines.join(eol), 'utf8')
+    // Unnamed markers the gate did not report: nothing of the gate's reaches that element.
+    lines.forEach((text, i) => {
+      if (UNNAMED.test(text) && !/eslint-disable/.test(text) && /\/\/|\/\*/.test(text)) unreached.push(`${file}:${i + 1}`)
+    })
+  }
+  return { named, unreached }
+}