@estiva-app/ui 0.35.2 → 0.37.0

package/src/eslint/raw-element-outside-a-wrapper.test.ts

@@ -35,7 +35,7 @@ tester.run('raw-element-outside-a-wrapper', rawElementOutsideAWrapper, {
     { name: 'layout inside a component', code: component('    <div>\n      <span>Issues</span>\n    </div>') },
     {
       name: 'a nested element with its reason on the line above',
-      code: component('    <div>\n      {/* @estiva-escape: the trail is one line of text and an anchor keeps it */}\n      <a href="/x">Issues</a>\n    </div>'),
+      code: component('    <div>\n      {/* @estiva-escape(raw-element-outside-a-wrapper): the trail is one line of text and an anchor keeps it */}\n      <a href="/x">Issues</a>\n    </div>'),
     },
   ],
   invalid: [
@@ -66,14 +66,14 @@ tester.run('raw-element-outside-a-wrapper', rawElementOutsideAWrapper, {
     },
     {
       name: 'a reason too short to be a reason',
-      code: component('    <div>\n      {/* @estiva-escape: short */}\n      <a href="/x">Issues</a>\n    </div>'),
+      code: component('    <div>\n      {/* @estiva-escape(raw-element-outside-a-wrapper): short */}\n      <a href="/x">Issues</a>\n    </div>'),
       errors: [{ messageId: 'escapeWithoutReason' }, { messageId: 'nested', data: { name: 'a' } }],
     },
     {
       name: 'an eslint-disable instead of a reason',
       // The tester runs the rule under its bare name; in a real lint the plugin
       // prefixes it, and `isEscaped` compares against whichever the rule has.
-      code: component('    <div>\n      {/* eslint-disable-next-line rule-to-test/raw-element-outside-a-wrapper -- @estiva-escape: the trail keeps its anchor */}\n      <a href="/x">Issues</a>\n    </div>'),
+      code: component('    <div>\n      {/* eslint-disable-next-line rule-to-test/raw-element-outside-a-wrapper -- @estiva-escape(raw-element-outside-a-wrapper): the trail keeps its anchor */}\n      <a href="/x">Issues</a>\n    </div>'),
       // The directive silences the rule's own report, which is exactly why it is
       // refused: `countGates` sees the silenced report and the gate fails on it.
       errors: [{ messageId: 'escapeInDirective' }],

package/src/gates/app-checks.ts

@@ -31,7 +31,7 @@ export interface AppCheckOptions {
   chain?: { ref: string; owner: boolean }
   /** The token lint configs the app has, relative to the app. */
   tokenConfigs?: string[]
-  /** The part a hand-made column header should name (UIG-22): `ContainerHeader`. */
+  /** The part a hand-made column header should name (UIG-22): `Panel` since 0.37.0, `ContainerHeader` before. */
   headers?: string[]
 }
 
@@ -70,7 +70,7 @@ function all(h: GateHelpers, steps: (() => CheckResult | Promise<CheckResult>)[]
   }
 }
 
-export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG-3', owner: false }, tokenConfigs = ['eslint.tokens.config.js', 'eslint.config.js'], headers = ['ContainerHeader'] }: AppCheckOptions): GateTicket[] {
+export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG-3', owner: false }, tokenConfigs = ['eslint.tokens.config.js', 'eslint.config.js'], headers = ['Panel'] }: AppCheckOptions): GateTicket[] {
   const WEB = app === '.' ? '' : `${app.replace(/\/$/, '')}/`
   const cwd = app === '.' ? undefined : app
   const PROBE = 'src/components/__gates_probe__.tsx'
@@ -114,6 +114,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
     ]),
     ticket('UIG-7', [
       { what: 'a raw <input> is an error naming TextInput', run: probe(component('<input />'), 'error', 'TextInput') },
+      { what: 'a clickable <div> is an error naming Button (R5)', run: probe(component('<div onClick={() => history.back()}>Back</div>'), 'error', '`Button`') },
       { what: 'a raw <a> is an error naming Link', run: all(h, [probe(component('<a href="/topics">Topics</a>'), 'error', 'Link'), probe(component('<a href="/issues">Issues</a>'), 'error', 'Link')], 'a raw <a> is an error naming Link') },
       { what: 'a raw <form> is an error naming Form, and a file input one naming FilePicker', run: async () => {
         const form = await probe(component('<form />'), 'error', '`Form`')()
@@ -131,7 +132,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'an escaped element is not an error, while the same element is', run: async () => {
         const raw = await probe(component('<form />'), 'error')()
         if (raw.result !== 'pass') return h.FAIL(`a raw <form> is not caught yet, so this proves nothing: ${raw.detail}`)
-        return probe('export function Probe() {\n  return (\n    // @estiva-escape: a probe that keeps its element on purpose\n    <form />\n  )\n}\n', 'none')()
+        return probe('export function Probe() {\n  return (\n    // @estiva-escape(no-raw-element): a probe that keeps its element on purpose\n    <form />\n  )\n}\n', 'none')()
       } },
       { what: 'a real page, full of elements that are not controls, gets no error', run: realPage },
     ]),
@@ -154,7 +155,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'an escaped listener is not an error, while the same listener is', run: async () => {
         const raw = await probe("export function listen() {\n  document.addEventListener('mousedown', () => {})\n}\n", 'error', undefined, 'src/lib/__gates_probe__.ts')()
         if (raw.result !== 'pass') return h.FAIL(`a page listener is not caught yet, so this proves nothing: ${raw.detail}`)
-        return probe("export function listen() {\n  // @estiva-escape: a probe that keeps its listener on purpose\n  document.addEventListener('mousedown', () => {})\n}\n", 'none', undefined, 'src/lib/__gates_probe__.ts')()
+        return probe("export function listen() {\n  // @estiva-escape(no-rebuilt-behaviour): a probe that keeps its listener on purpose\n  document.addEventListener('mousedown', () => {})\n}\n", 'none', undefined, 'src/lib/__gates_probe__.ts')()
       } },
       { what: 'a real page gets no error', run: realPage },
     ]),
@@ -164,7 +165,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'an escaped look is not an error, while the same look is', run: async () => {
         const raw = await probe(`import { Link } from '@estiva-app/ui'\n${component('<Link href="/x" className="after:absolute after:inset-0">x</Link>')}`, 'error', '`Link`')()
         if (raw.result !== 'pass') return h.FAIL(`a restyled part is not caught yet, so this proves nothing: ${raw.detail}`)
-        return probe(`import { Link } from '@estiva-app/ui'\nexport function Probe() {\n  return (\n    // @estiva-escape: a probe that keeps its row link on purpose\n    <Link href="/x" className="after:absolute after:inset-0">x</Link>\n  )\n}\n`, 'none')()
+        return probe(`import { Link } from '@estiva-app/ui'\nexport function Probe() {\n  return (\n    // @estiva-escape(no-restyled-part): a probe that keeps its row link on purpose\n    <Link href="/x" className="after:absolute after:inset-0">x</Link>\n  )\n}\n`, 'none')()
       } },
       { what: 'a real page gets no error', run: realPage },
     ]),
@@ -220,7 +221,9 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
     ]),
     ticket('UIG-22', [
       // The Folders pane's own row, at the commit before peek 3dc663b.
-      { what: 'a hand-made column header is an error naming ContainerHeader', run: all(h, headers.map((name) => probe(component('<div className="flex h-full flex-col"><div className="flex items-center gap-2 px-3 py-2"><span>Folders</span></div><div /></div>'), 'error', name)), 'a hand-made column header is an error naming ContainerHeader') },
+      { what: `a hand-made column header is an error naming ${headers.join(' or ')}`, run: all(h, headers.map((name) => probe(component('<div className="flex h-full flex-col"><div className="flex items-center gap-2 px-3 py-2"><span>Folders</span></div><div /></div>'), 'error', name)), `a hand-made column header is an error naming ${headers.join(' or ')}`) },
+      // 26 September: the package's header on its own is a panel made by hand, whose box forgot to scroll.
+      { what: "the package's ContainerHeader on its own is an error naming Panel", run: probe(`import { ContainerHeader } from '@estiva-app/ui'\n${component('<div className="flex flex-col"><ContainerHeader title="Details" /><div className="px-4">x</div></div>')}`, 'error', '`Panel`') },
       { what: 'a group heading inside a list is left alone', run: probe(component('<section className="flex flex-col gap-px"><h3 className="flex h-8 items-center gap-2 px-3"><span>Todo</span></h3><div /></section>'), 'none') },
     ]),
     ticket('UIG-23', [

package/src/gates/ci.ts

@@ -0,0 +1,152 @@
+/// <reference types="node" />
+/**
+ * `estiva-gates ci` — CI's job `gate`, as one command (Katerina's ruling R13,
+ * 25 September). Until 0.36.0 each repo listed the gate's steps in its own
+ * workflow, and the lists had drifted: Peek ran `lint:tokens`, Ship the whole
+ * `lint`, and no repo checked the two things below. Now the steps live here,
+ * and a repo's `gate` job runs this and nothing else of the gate's.
+ *
+ * 1. The gate lint (`npm run lint:rules`), which writes `.gates-count.json`.
+ * 2. The count is committed (B2): a pull request that changes what the gate
+ *    finds and leaves the old count behind fails, so the file is the truth.
+ * 3. The token contract (`npm run lint:tokens`, or `npm run lint` where a repo
+ *    has no token lint of its own).
+ * 4. The catalogue (`npm run registry:check`).
+ * 5. The wall's own settings (B13): the committed `.claude/settings.json` runs
+ *    the editor hook before every Write and Edit, and that hook refuses a raw
+ *    button; every folder the gate skips is named on the debt page, with why.
+ *
+ * Every step runs, so one red step does not hide the others.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { TOKEN_LINT_IGNORES } from './token-lint'
+
+export interface CiOptions {
+  /** The repository's top folder, where the gate lints from. */
+  root?: string
+  /** `package` is this package's own gate: its skipped folders are named in docs/GATES.md. */
+  audience?: 'app' | 'package'
+  /** Print as the steps run. Defaults to stdout. */
+  print?: (line: string) => void
+}
+
+/** The part a CI run writes to the probe: a raw button, which every gate refuses. */
+const PROBE = '/** A probe CI writes to check the editor hook; never on disk. */\nexport function GateProbe() {\n  return <button type="button">x</button>\n}\n'
+
+const npm = (root: string, script: string) => spawnSync('npm', ['run', script], { cwd: root, stdio: 'inherit', shell: true }).status === 0
+
+/** `.gates-count.json` as the gate lint left it matches the committed file; the lines that say otherwise. */
+export function countCommitted(root: string): string[] {
+  const run = spawnSync('git', ['status', '--porcelain', '--', '.gates-count.json'], { cwd: root, encoding: 'utf8' })
+  if (run.status !== 0) return [`git could not read .gates-count.json's state: ${run.stderr.trim()}`]
+  if (!run.stdout.trim()) return []
+  const diff = spawnSync('git', ['diff', '--', '.gates-count.json'], { cwd: root, encoding: 'utf8' }).stdout.trim()
+  return [
+    'The gate found something other than the committed count: run `npm run lint:rules` and commit `.gates-count.json` with the change that moved it.',
+    ...(diff ? diff.split('\n').filter((l) => /^[+-]\s/.test(l)).map((l) => `  ${l}`) : ['  .gates-count.json is not committed at all']),
+  ]
+}
+
+interface HookEntry {
+  matcher?: string
+  hooks?: { type?: string; command?: string }[]
+}
+
+/** The committed hook runs before every Write and Edit and refuses a raw button; the lines that say otherwise. */
+export function hookRuns(root: string): string[] {
+  const file = join(root, '.claude', 'settings.json')
+  if (!existsSync(file)) return ['.claude/settings.json is missing: the editor hook is not switched on (docs/GATES.md §23).']
+  let entries: HookEntry[]
+  try {
+    entries = ((JSON.parse(readFileSync(file, 'utf8')) as { hooks?: { PreToolUse?: HookEntry[] } }).hooks?.PreToolUse ?? [])
+  } catch (error) {
+    return [`.claude/settings.json does not read as JSON: ${error instanceof Error ? error.message : String(error)}`]
+  }
+  const covers = (matcher: string | undefined, tool: string) => {
+    if (!matcher || matcher === '*') return true
+    try {
+      return new RegExp(`^(?:${matcher})$`).test(tool)
+    } catch {
+      return false
+    }
+  }
+  const input = JSON.stringify({ tool_name: 'Write', session_id: 'estiva-gates-ci', cwd: root, tool_input: { file_path: join(root, 'src', 'GateProbe.tsx'), content: PROBE } })
+  const tried: string[] = []
+  for (const entry of entries) {
+    if (!covers(entry.matcher, 'Write') || !covers(entry.matcher, 'Edit')) continue
+    for (const hook of entry.hooks ?? []) {
+      if (hook.type !== 'command' || !hook.command) continue
+      // The project folder, written in: a Windows shell does not expand `$VAR`.
+      const command = hook.command.replace(/\$\{?CLAUDE_PROJECT_DIR\}?/g, root.split('\\').join('/'))
+      const run = spawnSync(command, { cwd: root, input, encoding: 'utf8', shell: true, env: { ...process.env, CLAUDE_PROJECT_DIR: root }, timeout: 120_000 })
+      if (run.status === 2 && /UI Guardrails/.test(run.stderr)) return []
+      tried.push(`  ${hook.command}  → exit ${run.status ?? 'none'}${run.stderr.trim() ? `: ${run.stderr.trim().split('\n')[0]}` : ''}`)
+    }
+  }
+  return [
+    tried.length
+      ? 'The editor hook let a raw button through: no PreToolUse hook in .claude/settings.json refused it.'
+      : 'No PreToolUse hook in .claude/settings.json runs before both Write and Edit: the editor gate is off.',
+    ...tried,
+  ]
+}
+
+/** A glob as the words a page would name it by: `demo-scenarios/**` → `demo-scenarios`. */
+const plain = (glob: string) => glob.replace(/\/\*\*.*$|\/$/, '')
+
+/** The folders a gate config skips beyond the package's own three, from the config itself. */
+export async function skippedFolders(root: string): Promise<string[]> {
+  const found = new Set<string>()
+  for (const name of ['eslint.gates.config.js', 'eslint.tokens.config.js']) {
+    const file = join(root, name)
+    if (!existsSync(file)) continue
+    // The file as it is now: Node keeps a module it has imported once, by its URL.
+    const loaded = (await import(`${pathToFileURL(file).href}?at=${statSync(file).mtimeMs}`)) as { default?: unknown }
+    const configs = [loaded.default].flat(Infinity) as { ignores?: string[]; [key: string]: unknown }[]
+    for (const c of configs) {
+      // Only a config with nothing but `ignores` skips a folder for every rule.
+      if (!c || typeof c !== 'object' || !Array.isArray(c.ignores) || Object.keys(c).some((k) => k !== 'ignores' && k !== 'name')) continue
+      for (const glob of c.ignores) if (!TOKEN_LINT_IGNORES.includes(glob)) found.add(glob)
+    }
+  }
+  return [...found]
+}
+
+/** Every skipped folder is named on the debt page; the lines that say otherwise. */
+export async function skipsListed(root: string, audience: 'app' | 'package'): Promise<string[]> {
+  const page = audience === 'package' ? 'docs/GATES.md' : 'docs/GATES-DEBT.md'
+  const skipped = await skippedFolders(root)
+  if (!skipped.length) return []
+  const text = existsSync(join(root, page)) ? readFileSync(join(root, page), 'utf8') : ''
+  const missing = skipped.filter((glob) => !text.includes(plain(glob)))
+  if (!missing.length) return []
+  return [`The gate skips folders ${page} does not name. Name each there, with why it is not checked (B11):`, ...missing.map((g) => `  ${g}`)]
+}
+
+export async function runCi({ root = process.cwd(), audience = 'app', print = (line) => process.stdout.write(`${line}\n`) }: CiOptions = {}): Promise<number> {
+  const scripts = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}
+  const tokens = scripts['lint:tokens'] ? 'lint:tokens' : 'lint'
+  const failed: string[] = []
+  const step = async (title: string, run: () => boolean | string[] | Promise<string[]>) => {
+    print(`\n▸ ${title}`)
+    const result = await run()
+    const problems = result === true ? [] : result === false ? [`${title}: failed (above)`] : result
+    if (problems.length) {
+      failed.push(title)
+      for (const line of problems) print(process.env.GITHUB_ACTIONS && !line.startsWith(' ') ? `::error::${line}` : line)
+    } else print('  ✓')
+  }
+
+  await step('The gate lint (npm run lint:rules)', () => npm(root, 'lint:rules'))
+  await step('The count is committed (.gates-count.json)', () => countCommitted(root))
+  await step(`The token contract (npm run ${tokens})`, () => npm(root, tokens))
+  await step('The catalogue (npm run registry:check)', () => npm(root, 'registry:check'))
+  await step('The editor hook refuses a raw button (.claude/settings.json)', () => hookRuns(root))
+  await step('Every folder the gate skips is named on the debt page', () => skipsListed(root, audience))
+
+  print(failed.length ? `\nThe gate failed: ${failed.join('; ')}.` : '\nThe gate passed.')
+  return failed.length ? 1 : 0
+}

package/src/gates/cli.ts

@@ -2,9 +2,11 @@
 /**
  * `estiva-gates` — the gate pieces as one command (docs/GATES.md §23).
  *
+ *   estiva-gates ci [--package]                    CI's job `gate`: every step of the gate (R13)
  *   estiva-gates count --repo <name> [--package]   write .gates-count.json (postlint:rules)
  *   estiva-gates hook [--app <dir>] [--package]    the editor gate, run by a PreToolUse hook
- *   estiva-gates status [--app <dir>] [--json] [--detail]   gates:status
+ *   estiva-gates name-escapes [--config <file>]    once: name the rule in every escape marker (B3)
+ *   estiva-gates status [--app <dir>] [--json] [--detail] [--escapes]   gates:status
  *
  * An app's `package.json` runs the first and the last through npm, which finds
  * the command in `node_modules/.bin`. The hook is run by path, from the
@@ -19,8 +21,10 @@
  *   node "$CLAUDE_PROJECT_DIR/web/node_modules/@estiva-app/ui/dist/gates/cli.js" hook --app web
  *   node web/node_modules/@estiva-app/ui/dist/gates/cli.js status --app web
  */
+import { runCi } from './ci'
 import { writeGateCount } from './count'
 import { runHook } from './hook'
+import { nameEscapes } from './name-escapes'
 import { runStatus } from './status'
 
 const [command, ...rest] = process.argv.slice(2)
@@ -33,6 +37,8 @@ const audience = flag('package') ? 'package' : 'app'
 
 async function main(): Promise<number> {
   switch (command) {
+    case 'ci':
+      return runCi({ audience })
     case 'count': {
       const repo = value('repo')
       if (!repo) {
@@ -44,6 +50,13 @@ async function main(): Promise<number> {
       if (result.failures.length) process.stderr.write(`${result.failures.join('\n')}\n`)
       return result.failures.length ? 1 : 0
     }
+    case 'name-escapes': {
+      // Once, after taking 0.36.0: every unnamed marker gets the rules it keeps off (B3).
+      const result = await nameEscapes({ config: value('config') })
+      process.stdout.write(`${result.named.length} markers named:\n  ${result.named.join('\n  ')}\n`)
+      if (result.unreached.length) process.stdout.write(`${result.unreached.length} unnamed markers no rule reaches, left as they are:\n  ${result.unreached.join('\n  ')}\n`)
+      return 0
+    }
     case 'hook': {
       // A hook that fails open guards nothing: Claude Code lets a write through
       // on any exit but 2, and a crash exits 1 (audit A2). So a gate that cannot
@@ -52,6 +65,9 @@ async function main(): Promise<number> {
       try {
         const result = await runHook({ app: value('app'), audience })
         if (result.code === 2) process.stderr.write(result.message)
+        // A note on a write let through reaches Claude as additional context: plain
+        // stdout on exit 0 does not, for a PreToolUse hook (code.claude.com/docs/en/hooks-guide).
+        else if (result.note) process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: `A copied look, let through (it only warns):\n${result.note}` } })}\n`)
         return result.code
       } catch (error) {
         const why = error instanceof Error ? error.message.split('\n')[0] : String(error)
@@ -60,11 +76,11 @@ async function main(): Promise<number> {
       }
     }
     case 'status': {
-      process.stdout.write(`${await runStatus({ app: value('app'), json: flag('json'), detail: flag('detail') })}${flag('json') ? '' : '\n'}`)
+      process.stdout.write(`${await runStatus({ app: value('app'), json: flag('json'), detail: flag('detail'), escapes: flag('escapes') })}${flag('json') ? '' : '\n'}`)
       return 0
     }
     default:
-      process.stderr.write('estiva-gates <count | hook | status>\n')
+      process.stderr.write('estiva-gates <ci | count | hook | status | name-escapes>\n')
       return 1
   }
 }

package/src/gates/count.ts

@@ -69,7 +69,7 @@ export async function writeGateCount({ root = process.cwd(), repo, audience = 'a
 
   const failures: string[] = []
   if (disabled.length > 0) {
-    failures.push('', 'An eslint-disable switched a gate rule off. Write the reason above the element instead: // @estiva-escape: <reason>')
+    failures.push('', 'An eslint-disable switched a gate rule off. Write the reason above the element instead, naming the rule: // @estiva-escape(<rule>): <reason>')
     for (const d of disabled) failures.push(`  ${relative(root, d.filePath)}:${d.line}  ${d.ruleId}`)
   }
   return { rules, disabled, changed, lines, failures }

package/src/gates/create-app.test.ts

@@ -71,7 +71,7 @@ describe('create-estiva-app', () => {
   it('starts the count at zero and keeps the CI job named gate', () => {
     const count = JSON.parse(files['.gates-count.json'])
     expect(Object.values(count.rules)).toEqual([{ errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }])
-    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*npm run lint:rules/)
+    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*run: npx estiva-gates ci/)
     expect(files['docs/GATES-DEBT.md']).toContain('Nothing.')
   })
 
@@ -131,7 +131,7 @@ describe('create-estiva-app', () => {
     expect(registry.filesWithoutParts.map((file) => file.file)).toEqual(['src/main.tsx'])
     const scripts = JSON.parse(files['package.json']).scripts
     expect(scripts).toMatchObject({ 'ui:find': 'estiva-ui find', registry: 'estiva-ui build', 'registry:check': 'estiva-ui check' })
-    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*npm run registry:check/)
+    expect(files['.github/workflows/deploy.yml']).toMatch(/\n {2}gate:\n[\s\S]*run: npx estiva-gates ci/)
     expect(files['.gitignore'].split('\n')).toContain('registry.json')
   })
 

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. */
@@ -70,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