@estiva-app/ui 0.33.0 → 0.35.0

package/src/eslint/no-copied-look.ts

@@ -0,0 +1,203 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import type { Rule } from 'eslint'
+import type ts from 'typescript'
+import { ESCAPE_MESSAGES, isEscaped } from './escape'
+import { classUnits, componentsOf, copies, looksOf, parseForLooks, sharedLooksOf, type ClassUnit } from './looks-of'
+
+/**
+ * UIG-25: a component's look typed again by hand. **A warning, never an error**
+ * (Katerina, 13 September): a copy is found by how alike two lists are, and
+ * likeness is a judgement — a warning gets read, a guess that blocks gets
+ * switched off.
+ *
+ * Every class list in the file (see `looks-of.ts` for where one is read) is
+ * compared, by its look words alone, against the looks of every catalogued
+ * part in another file. A list is a copy when it shares `MIN_SHARED` look words
+ * with one of a part's looks, covering `MIN_COVER` of the shorter of the two.
+ *
+ * - **In an app**, the parts are the package's — read from the catalogue the
+ *   installed package ships (`@estiva-app/ui/registry.json`, its `looks`) — and
+ *   the app's own exported components, read from its `src`. So a part added to
+ *   either is covered the day it is added, with no list kept here. The fix:
+ *   use the part.
+ * - **In the package**, the parts are its own. The fix: write the look once in
+ *   `src/looks.ts` and use it in both.
+ *
+ * Left alone: a part's look in its own file, and a component named like the
+ * part it wraps (Peek's `Avatar` over the package's). A constant imported from
+ * another file is a look written once, not a copy. Peek and Ship copying each
+ * other is not seen here — each app knows only itself and the package — and
+ * is counted by `gates:status`.
+ */
+
+interface Look {
+  part: string
+  file: string
+  look: string[]
+  /** The installed package's part, this repo's own part, or a shared look (`…_CLASSES`) this repo writes once. */
+  from: 'package' | 'own' | 'shared'
+}
+
+const packageDirCache = new Map<string, string | null>()
+function packageDirOf(file: string): string | null {
+  const start = dirname(resolve(file))
+  if (packageDirCache.has(start)) return packageDirCache.get(start) ?? null
+  let dir = start
+  for (;;) {
+    if (existsSync(join(dir, 'package.json'))) break
+    const up = dirname(dir)
+    if (up === dir) {
+      dir = ''
+      break
+    }
+    dir = up
+  }
+  packageDirCache.set(start, dir || null)
+  return dir || null
+}
+
+const PACKAGE = '@estiva-app/ui'
+const nameOf = (dir: string) => {
+  try {
+    return (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: string }).name
+  } catch {
+    return undefined
+  }
+}
+
+/** The installed package's parts and their looks, from the catalogue it ships. */
+const shippedCache = new Map<string, { mtime: number; looks: Look[] }>()
+function shippedLooks(appDir: string): Look[] {
+  for (let dir = appDir; ; dir = dirname(dir)) {
+    const file = join(dir, 'node_modules', PACKAGE, 'registry.json')
+    if (existsSync(file)) {
+      const mtime = statSync(file).mtimeMs
+      const cached = shippedCache.get(file)
+      if (cached && cached.mtime === mtime) return cached.looks
+      let looks: Look[] = []
+      try {
+        const registry = JSON.parse(readFileSync(file, 'utf8')) as { entries: { name: string; sourceFile: string; looks?: string[] }[] }
+        looks = registry.entries.flatMap((e) => (e.looks ?? []).map((l) => ({ part: e.name, file: e.sourceFile, look: l.split(' '), from: 'package' as const })))
+      } catch {
+        // A catalogue that does not parse is its own check's business.
+      }
+      shippedCache.set(file, { mtime, looks })
+      return looks
+    }
+    if (dirname(dir) === dir) return []
+  }
+}
+
+/** The names a file exports. */
+function exportedNames(source: ts.SourceFile): Set<string> {
+  const names = new Set<string>()
+  const text = source.text
+  for (const m of text.matchAll(/export\s+(?:default\s+)?(?:function|const)\s+([A-Z]\w*)/g)) names.add(m[1])
+  for (const m of text.matchAll(/export\s*\{([^}]*)\}/g)) for (const part of m[1].split(',')) {
+    const name = part.trim().split(/\s+as\s+/).pop()
+    if (name && /^[A-Z]/.test(name)) names.add(name)
+  }
+  return names
+}
+
+/** A repo's own exported components and their looks, from its `src`. */
+const ownCache = new Map<string, { mtime: number; looks: Look[] }>()
+function ownLooks(repoDir: string): Look[] {
+  const out: Look[] = []
+  const walk = (dir: string) => {
+    let names: string[] = []
+    try {
+      names = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const name of names) {
+      if (name === 'node_modules' || name === 'dist') continue
+      const path = join(dir, name)
+      if (statSync(path).isDirectory()) walk(path)
+      else if (/\.tsx?$/.test(name) && !/\.(?:stories|test)\.tsx?$/.test(name) && !name.endsWith('.d.ts')) {
+        const mtime = statSync(path).mtimeMs
+        let cached = ownCache.get(path)
+        if (!cached || cached.mtime !== mtime) {
+          const text = readFileSync(path, 'utf8')
+          const source = parseForLooks(path, text)
+          const exported = name.endsWith('.tsx') ? [...componentsOf(source).keys()].filter((n) => exportedNames(source).has(n)) : []
+          const file = relative(repoDir, path).replace(/\\/g, '/')
+          const looks: Look[] = [...looksOf(source, exported)].flatMap(([part, lists]) => lists.map((l) => ({ part, file, look: l.split(' '), from: 'own' as const })))
+          // A shared look written once (`…_CLASSES`): a copy of it is told to use it.
+          if (text.includes('_CLASSES')) for (const [part, lists] of sharedLooksOf(source)) for (const l of lists) looks.push({ part, file, look: l.split(' '), from: 'shared' })
+          cached = { mtime, looks }
+          ownCache.set(path, cached)
+        }
+        out.push(...cached.looks)
+      }
+    }
+  }
+  walk(join(repoDir, 'src'))
+  return out
+}
+
+export const noCopiedLook: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: { description: "A part's look typed again by hand, where the part (or a shared look) should be used" },
+    schema: [],
+    messages: {
+      usePart:
+        "This class list is `{{part}}`'s look, typed again ({{count}} words: {{words}}). Use `{{part}}` from {{from}}: a copy looks right today and stays behind the day `{{part}}` changes.",
+      shareIt:
+        'This look is also written in `{{part}}` ({{file}}): {{words}}. Write it once in src/looks.ts and use it in both, so the two cannot drift apart.',
+      useShared:
+        'This class list is `{{part}}` ({{file}}), typed again: {{words}}. Use `{{part}}`: a look written once cannot drift apart.',
+      ...ESCAPE_MESSAGES,
+    },
+  },
+  create(context) {
+    const file = context.filename
+    const repoDir = packageDirOf(file)
+    if (!repoDir) return {}
+    const inPackage = nameOf(repoDir) === PACKAGE
+    return {
+      Program() {
+        const here = relative(repoDir, file).replace(/\\/g, '/')
+        const source = parseForLooks(file, context.sourceCode.text)
+        const declared = new Set(componentsOf(source).keys())
+        const looks = [...(inPackage ? [] : shippedLooks(repoDir)), ...ownLooks(repoDir)].filter((l) => l.file !== here && !declared.has(l.part))
+        if (!looks.length) return
+        const units = classUnits(source)
+        // A string inside a className is read with it; report the className once.
+        const within = (u: ClassUnit) => units.some((o) => o !== u && o.via === 'attribute' && u.via === 'literal' && u.start >= o.start && u.end <= o.end)
+        const reported = new Set<number>()
+        for (const unit of units) {
+          if (within(unit) || reported.has(unit.start)) continue
+          let best: { look: Look; shared: string[] } | null = null
+          for (const look of looks) {
+            // A shared look is compared with the package's parts only: the parts here that use it are not its copies.
+            if (unit.shared && look.from !== 'package') continue
+            const shared = copies(unit.look, look.look)
+            // On a tie, the shared look: using it is the whole fix.
+            if (shared && (!best || shared.length > best.shared.length || (shared.length === best.shared.length && look.from === 'shared'))) best = { look, shared }
+          }
+          if (!best) continue
+          // A className built from a constant of this file is reported once, at the constant.
+          const found = best
+          if (unit.via === 'attribute' && units.some((o) => o.via === 'literal' && !within(o) && found.shared.every((w) => o.look.includes(w)) && looks.some((l) => copies(o.look, l.look)))) continue
+          const loc = { start: context.sourceCode.getLocFromIndex(unit.start), end: context.sourceCode.getLocFromIndex(unit.end) }
+          const at = { start: context.sourceCode.getLocFromIndex(unit.anchor), end: loc.end }
+          if (isEscaped(context, { loc: at, range: [unit.anchor, unit.end] })) continue
+          reported.add(unit.start)
+          const words = best.shared.map((w) => `\`${w}\``).join(' ')
+          if (best.look.from === 'shared') context.report({ loc, messageId: 'useShared', data: { part: best.look.part, file: best.look.file, words } })
+          else if (inPackage) context.report({ loc, messageId: 'shareIt', data: { part: best.look.part, file: best.look.file, words } })
+          else
+            context.report({
+              loc,
+              messageId: 'usePart',
+              data: { part: best.look.part, count: String(best.shared.length), words, from: best.look.from === 'package' ? PACKAGE : `\`${best.look.file}\`` },
+            })
+        }
+      },
+    }
+  },
+}

package/src/eslint/no-restyled-part.ts

@@ -119,7 +119,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   Reaction: ['pressed'],
   ReactionPicker: ['surface'],
   SectionHeader: ['hover'],
-  SectionLabel: ['tone'],
+  SectionLabel: ['tone', 'truncate'],
   Select: ['size'],
   Tabs: ['size'],
   TextInput: ['size'],

package/src/gates/app-checks.ts

@@ -23,7 +23,7 @@
 import type { CheckResult, GateCheck, GateHelpers, GateTicket } from './status'
 
 export interface AppCheckOptions {
-  /** Where the app is inside the repository: `web` in Ship, `.` elsewhere. */
+  /** Where the app is inside the repository: `.` unless it sits in a folder of its own. */
   app?: string
   /** A real page of the app, relative to the app, full of elements that are not controls. */
   page: string
@@ -230,7 +230,7 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'a title= is an error naming WithTooltip', run: probe(`import { Button } from '@estiva-app/ui'\n${component('<Button title="Delete">x</Button>')}`, 'error', 'WithTooltip') },
     ]),
     ticket('UIG-25', [
-      { what: "SectionLabel's class list, typed by hand, is a warning", run: probe(component('<span className="text-[10px] uppercase tracking-wide text-text-muted">Label</span>'), 'warning', 'SectionLabel') },
+      { what: "SectionLabel's class list, typed by hand, is a warning", run: probe(component('<span className="text-h5 leading-3 signal:font-mono signal:text-small signal:uppercase signal:tracking-widest text-text-secondary">Label</span>'), 'warning', 'SectionLabel') },
     ]),
     ticket('UIG-27', [
       { what: 'the installed package has Link', run: () => h.contains(installed, /\bLink\b/, 'the installed @estiva-app/ui exports Link') },

package/src/gates/cli.ts

@@ -13,7 +13,8 @@
  *   node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook
  *
  * A repo whose app sits in a folder of its own runs both by path, from the
- * repo's top folder, and says where the app is — Ship (UIG-32):
+ * repo's top folder, and says where the app is (Ship did, from UIG-32 until
+ * PER-19 moved its app to the top folder):
  *
  *   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
@@ -44,9 +45,19 @@ async function main(): Promise<number> {
       return result.failures.length ? 1 : 0
     }
     case 'hook': {
-      const result = await runHook({ app: value('app'), audience })
-      if (result.code === 2) process.stderr.write(result.message)
-      return result.code
+      // 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
+      // run — no ESLint in the app's install, a config that does not load —
+      // refuses the write and says why, and the session fixes the install.
+      try {
+        const result = await runHook({ app: value('app'), audience })
+        if (result.code === 2) process.stderr.write(result.message)
+        return result.code
+      } catch (error) {
+        const why = error instanceof Error ? error.message.split('\n')[0] : String(error)
+        process.stderr.write(`The UI Guardrails could not check this write, so it was not made: ${why}\nRun \`npm ci\` in the app's folder, then try again.\n`)
+        return 2
+      }
     }
     case 'status': {
       process.stdout.write(`${await runStatus({ app: value('app'), json: flag('json'), detail: flag('detail') })}${flag('json') ? '' : '\n'}`)

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

@@ -1,9 +1,12 @@
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { afterAll, describe, expect, it } from 'vitest'
 import { buildAppRegistry } from '../registry/app'
 import { validateRegistry } from '../registry/schema'
+import { appChecks } from './app-checks'
 import { appFiles, ASKED_OF_NPM, createApp, themes } from './create-app'
+import { helpers, type GateHelpers } from './status'
 
 /**
  * `create-estiva-app` (UIG-10). What the app does when it runs is proved on a
@@ -59,7 +62,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 }])
+    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['docs/GATES-DEBT.md']).toContain('Nothing.')
   })
@@ -148,3 +151,55 @@ describe('create-estiva-app', () => {
     expect(() => createApp({ name: 'once', parent: scratch, versions })).toThrow(/already exists/)
   })
 })
+
+/**
+ * The made app, checked the way gates:status checks Peek and Ship (audit B5).
+ * The tests above pin the starter's files one by one; they could not see that
+ * its required job `gate` skipped the token lint, which every app check since
+ * 0.30.0 asks for. This runs every check an app runs on a freshly made app, for
+ * real: the package is linked in as the app's install, and ESLint, TypeScript
+ * and the plugins resolve from this repository's own, as they do for the gate
+ * tests. Only what needs GitHub or a commit is left out.
+ */
+describe('a made app, under the checks every app runs', () => {
+  it('passes every one on its first commit, but the tickets not built yet', async () => {
+    const dir = join(scratch, 'checked')
+    for (const [path, text] of Object.entries(files)) {
+      mkdirSync(dirname(join(dir, path)), { recursive: true })
+      writeFileSync(join(dir, path), text)
+    }
+    mkdirSync(join(dir, 'node_modules', '@estiva-app'), { recursive: true })
+    symlinkSync(process.cwd(), join(dir, 'node_modules', '@estiva-app', 'ui'), 'junction')
+    // The one plugin the app asks npm for that this repository does not use: the
+    // gate only needs its name known, so a stand-in with no rules does.
+    const hooks = join(dir, 'node_modules', 'eslint-plugin-react-hooks')
+    mkdirSync(hooks, { recursive: true })
+    writeFileSync(join(hooks, 'package.json'), JSON.stringify({ name: 'eslint-plugin-react-hooks', type: 'module', main: 'index.js' }))
+    writeFileSync(join(hooks, 'index.js'), 'export default { rules: {}, configs: { flat: { recommended: { rules: {} } } } }\n')
+    // Its first commit, as the ticket asks: the count file must be committed.
+    const git = (...a: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', '-c', 'core.autocrlf=false', ...a], { cwd: dir, stdio: 'pipe' })
+    git('init', '-q', '-b', 'main')
+    git('add', '-A')
+    git('commit', '-q', '-m', 'made by create-estiva-app')
+    const real = helpers(dir)
+    // "The installed package exports Link" reads its declarations, which CI's
+    // test step does not build (`pretest` bundles only): the same exports are read
+    // from their source when the declarations are not there.
+    const exportsFrom = (rel: string) => (rel.endsWith('dist/index.d.ts') && !real.exists(rel) ? join(process.cwd(), 'src', 'index.ts') : rel)
+    const h: GateHelpers = {
+      ...real,
+      contains: (rel, needle, label) => real.contains(exportsFrom(rel), needle, label),
+      protectedBranch: () => real.UNKNOWN('a rule on GitHub'),
+      gh: () => real.UNKNOWN('a question for GitHub'),
+    }
+    const failed: string[] = []
+    for (const ticket of appChecks(h, { page: 'src/pages/HomePage.tsx' })) {
+      for (const check of ticket.checks) {
+        const result = await check.run()
+        if (result.result === 'fail' || result.result === 'part') failed.push(`${ticket.ref} ${check.what}: ${result.detail}`)
+      }
+    }
+    // RichText is UIG-30's, not built yet: no app passes that one.
+    expect(failed.filter((f) => !f.startsWith('UIG-30 '))).toEqual([])
+  }, 300_000)
+})

package/src/gates/create-app.ts

@@ -365,9 +365,10 @@ jobs:
             exit 1
           fi
 
-  # The UI Guardrails' rules, on their own: a raw element, behaviour a part owns
-  # written by hand, a part restyled. \`npm run lint:rules\` also writes
-  # .gates-count.json and fails on an eslint-disable that switches a rule off.
+  # The UI Guardrails, the one check a merge requires: the package's gate rules
+  # (each refusal names what to use instead), the token contract, and the
+  # catalogue. \`npm run lint:rules\` also writes .gates-count.json and fails on
+  # an eslint-disable that switches a rule off.
   #
   # A job of its own, because GitHub can require only a whole job, by its name:
   # the rule on main requires \`gate\`. Renaming it leaves every pull request
@@ -383,6 +384,10 @@ jobs:
       - 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
@@ -1011,8 +1016,9 @@ UIG-6 as not done.
 ${title} is an Estiva app. Its parts, tokens and gates come from \`@estiva-app/ui\`.
 
 **Use the package's parts, never a raw element or a hand-built look.** The gate
-refuses a raw control, behaviour a part owns written by hand, and a part restyled
-through \`className\`, and names what to use instead. It runs before you write
+refuses code that reaches past the package, and each refusal names what to use
+instead. What it refuses is the package's to say, and grows with it: the
+\`estiva-ui\` skill lists it. It runs before you write
 (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

package/src/gates/gate-config.ts

@@ -4,7 +4,7 @@
  *
  * Until UIG-10 every repo wrote this itself: `eslint.gates.js` (the rules and
  * where they apply) and `eslint.gates.config.js` (the gate: those rules alone)
- * in Peek, in Ship's `web/`, and here pointed inward. The rules were always the
+ * in Peek, in Ship, and here pointed inward. The rules were always the
  * package's; these two files were copies. Now they are two functions.
  *
  * Where: every `.ts` and `.tsx` under `src`, stories included (a story is what

package/src/gates/gates.test.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process'
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -6,7 +7,7 @@ import { afterAll, describe, expect, it } from 'vitest'
 import { writeGateCount } from './count'
 import { gateConfig, gateLint } from './gate-config'
 import { runHook } from './hook'
-import { helpers, runStatus } from './status'
+import { behindMain, helpers, runStatus } from './status'
 import { tokenConfig, tokenLint, tokenValues } from './token-lint'
 
 /**
@@ -153,7 +154,7 @@ describe('writeGateCount', () => {
     const written = JSON.parse(readFileSync(join(dir, '.gates-count.json'), 'utf8'))
     expect(written).toMatchObject({ schemaVersion: 1, repo: 'probe' })
     expect(written.rules['estiva/no-raw-element']).toEqual({ errors: 0, warnings: 0, escapes: 1 })
-    expect(Object.keys(written.rules)).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title'])
+    expect(Object.keys(written.rules)).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part', 'estiva/no-handmade-header', 'estiva/no-handmade-empty-state', 'estiva/no-native-title', 'estiva/no-copied-look'])
 
     expect((await writeGateCount({ root: dir, repo: 'probe' })).changed).toBe(false)
 
@@ -233,10 +234,42 @@ describe('gates:status', () => {
     const h = helpers(dir)
     expect(h.ciJob('gate', 'lint:rules').result).toBe('pass')
     expect(h.ciJob('check', 'lint:rules').result).toBe('fail')
-    expect(h.hook('.claude/settings.json', 'gates').result).toBe('pass')
     expect(h.script('package.json', 'gates:status').result).toBe('pass')
   })
 
+  // Audit A2: a hook is judged by running it, the way Claude Code does, on a raw
+  // <button>. Only exit 2 blocks a write; a hook that cannot run exits 1, and
+  // the write goes through.
+  it('runs the committed hook and passes only when it refuses the write', () => {
+    const settings = (matcher: string, command: string) => ({ '.claude/settings.json': JSON.stringify({ hooks: { PreToolUse: [{ matcher, hooks: [{ type: 'command', command }] }] } }) })
+    const refuses = 'node -e "process.exit(2)" -- gates'
+    expect(helpers(app('hook-refuses', settings('Edit|Write', refuses))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'pass' })
+    const broken = helpers(app('hook-broken', settings('Edit|Write', 'node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook'))).hook('.claude/settings.json', 'gates')
+    expect(broken).toMatchObject({ result: 'fail', detail: expect.stringContaining('let a raw <button> through (exit 1)') })
+    expect(helpers(app('hook-waves', settings('Edit|Write', 'node -e "process.exit(0)" -- gates'))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'fail' })
+    expect(helpers(app('hook-never', settings('Read', refuses))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'fail', detail: expect.stringContaining('never for a Write') })
+    // The hook is handed the real project folder, as Claude Code hands it.
+    const seen = 'node -e "process.exit(String(process.env.CLAUDE_PROJECT_DIR).endsWith(process.argv[1]) ? 2 : 1)" hook-dir gates'
+    expect(helpers(app('hook-dir', settings('Edit|Write', seen))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'pass' })
+  })
+
+  // Audit A4: a checkout seven commits behind reported a finished ticket as not started.
+  it('says how far a checkout is behind main, after fetching it', () => {
+    const base = app('behind', {})
+    const git = (cwd: string, ...a: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', ...a], { cwd, stdio: 'pipe' }).toString().trim()
+    git(base, 'init', '-q', '--bare', '-b', 'main', 'origin.git')
+    git(base, 'clone', '-q', 'origin.git', 'writer')
+    const writer = join(base, 'writer')
+    git(writer, 'commit', '-q', '--allow-empty', '-m', 'one')
+    git(writer, 'push', '-q', 'origin', 'HEAD:main')
+    git(base, 'clone', '-q', 'origin.git', 'reader')
+    const reader = join(base, 'reader')
+    expect(behindMain(reader)).toBe('')
+    git(writer, 'commit', '-q', '--allow-empty', '-m', 'two')
+    git(writer, 'push', '-q', 'origin', 'HEAD:main')
+    expect(behindMain(reader)).toContain('1 commit behind origin/main')
+  })
+
   it('counts what loads into every session, imports included, and refuses a rule file with no paths (UIG-21)', () => {
     const lines = (n: number) => Array.from({ length: n }, (_, i) => `line ${i}`).join('\n') + '\n'
     const scoped = '---\npaths:\n  - "src/**"\n---\n\nA rule.\n'

package/src/gates/hook.ts

@@ -44,7 +44,7 @@ import { repositoryOf } from '../registry/skill'
 export interface HookOptions {
   /** The repository's top folder. Defaults to `$CLAUDE_PROJECT_DIR`, then the tool call's `cwd`. */
   root?: string
-  /** The folder that holds the app, relative to `root`: `web` in Ship, `.` elsewhere. */
+  /** The folder that holds the app, relative to `root`: `.` unless it sits in a folder of its own. */
   app?: string
   /** `package` gates `.tsx` only, as this package's inward lint does. */
   audience?: 'app' | 'package'

package/src/gates/status.ts

@@ -5,7 +5,7 @@
  *   estiva-gates status              one row per ticket
  *   estiva-gates status --detail     every check under every row
  *   estiva-gates status --json       machine output, read by estiva-ui's run
- *   estiva-gates status --app web    the app sits in `web/`, as Ship's does
+ *   estiva-gates status --app web    the app sits in `web/` (Ship's did, until PER-19)
  *
  * Every row is decided by checks on real files, a real lint run or a real
  * GitHub setting. Nothing here reads a list that someone ticks by hand.
@@ -19,13 +19,13 @@
  *
  * What differs per repo is `scripts/gates-checks.mjs`, beside the app: its
  * checks, or the checks every app runs (`appChecks`) plus its own. It sits with
- * the app because it imports the package — `web/scripts/` in Ship, whose app,
- * and whose install, are in `web/` (UIG-32).
+ * the app because it imports the package: in an app that sits in a folder of
+ * its own, the checks file sits there too (UIG-32).
  *
  * The rows and the reasons for each check are in estiva-ui docs/GATES.md §15
  * and §17.
  */
-import { execFileSync } from 'node:child_process'
+import { execFileSync, spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { join, relative, resolve } from 'node:path'
@@ -36,7 +36,7 @@ export type CheckResult = { result: 'pass' | 'fail' | 'part' | 'unknown'; detail
 type Maybe<T> = T | Promise<T>
 
 export interface LintProbe {
-  /** The folder ESLint runs from, relative to the repo: `web` in Ship. */
+  /** The folder ESLint runs from, relative to the repo: `.` unless the app sits in a folder of its own. */
   cwd?: string
   /** The config file, relative to `cwd`. */
   config: string
@@ -106,7 +106,7 @@ export interface GateSpec {
   tickets: GateTicket[]
   /** estiva-ui only: every ticket, and the repos it joins in. */
   all?: TicketListEntry[]
-  /** estiva-ui only: the repos beside it. `app` is the folder its app sits in: `web` in Ship. */
+  /** estiva-ui only: the repos beside it. `app` is the folder its app sits in, when not the top. */
   siblings?: { name: string; path: string; env: string; app?: string }[]
 }
 
@@ -292,16 +292,39 @@ export function helpers(ROOT: string): GateHelpers {
 
     hook(settingsRel, needle) {
       if (!exists(settingsRel)) return FAIL(`${settingsRel} does not exist`)
-      let s: { hooks?: { PreToolUse?: { hooks?: { command?: string }[] }[] } }
+      let s: { hooks?: { PreToolUse?: { matcher?: string; hooks?: { command?: string }[] }[] } }
       try {
         s = JSON.parse(read(settingsRel))
       } catch {
         return FAIL(`${settingsRel} is not valid JSON`)
       }
-      const commands = (s.hooks?.PreToolUse ?? []).flatMap((m) => (m.hooks ?? []).map((x) => x.command ?? ''))
-      const hit = commands.find((c) => c.includes(needle))
-      if (hit) return PASS(`${settingsRel} has a PreToolUse hook running ${needle}`)
-      return FAIL(commands.length ? `${settingsRel} has PreToolUse hooks, none running ${needle}` : `${settingsRel} has no PreToolUse hook`)
+      const entries = (s.hooks?.PreToolUse ?? []).flatMap((m) => (m.hooks ?? []).map((x) => ({ matcher: m.matcher ?? '', command: x.command ?? '' })))
+      const hit = entries.find((e) => e.command.includes(needle))
+      if (!hit) return FAIL(entries.length ? `${settingsRel} has PreToolUse hooks, none running ${needle}` : `${settingsRel} has no PreToolUse hook`)
+      // A hook that is written but never fires, or fires and cannot run, guards
+      // nothing — and Claude Code lets a write through on any exit but 2 (audit
+      // A2: Ship's hook pointed at an install its checkout did not have). So the
+      // hook is run, as Claude Code would run it, on a raw <button>.
+      let matches: boolean
+      try {
+        matches = hit.matcher === '' || hit.matcher === '*' || new RegExp(`^(?:${hit.matcher})$`).test('Write')
+      } catch {
+        return FAIL(`${settingsRel}: the hook's matcher "${hit.matcher}" is not a pattern`)
+      }
+      if (!matches) return FAIL(`${settingsRel}: the hook runs only for "${hit.matcher}", never for a Write`)
+      const top = ROOT.split('\\').join('/')
+      const app = /--app\s+("?)([^"\s]+)\1/.exec(hit.command)?.[2] ?? '.'
+      const input = JSON.stringify({
+        hook_event_name: 'PreToolUse',
+        cwd: top,
+        tool_name: 'Write',
+        tool_input: { file_path: `${resolve(ROOT, app, 'src', '__gates_hook_probe__.tsx').split('\\').join('/')}`, content: 'export function Probe() {\n  return <button type="button">x</button>\n}\n' },
+      })
+      const command = hit.command.replace(/\$\{?CLAUDE_PROJECT_DIR\}?/g, top)
+      const run = spawnSync(command, { cwd: ROOT, input, shell: true, encoding: 'utf8', timeout: 120_000, env: { ...process.env, CLAUDE_PROJECT_DIR: top } })
+      if (run.status === 2) return PASS(`${settingsRel}: the hook ran and refused a raw <button> (exit 2)`)
+      const why = `${run.stderr ?? ''}${run.stdout ?? ''}`.trim().split(/\r?\n/)[0] || (run.error ? String(run.error.message) : 'no output')
+      return FAIL(`${settingsRel}: the hook ran and let a raw <button> through (exit ${run.status ?? 'none'}): ${why}`)
     },
 
     json(rel, test = () => true, label) {
@@ -418,8 +441,8 @@ function statusOf(checks: CheckResult[]) {
 
 async function runRepo(ROOT: string, app: string, h: GateHelpers): Promise<{ spec: GateSpec; report: Report }> {
   // The checks file sits with the app, because it imports `appChecks` from the
-  // package: in Ship that install is `web/node_modules`, not the repo's top
-  // folder (UIG-32). Everything it names is still read from the repo's top.
+  // package: for an app in a folder of its own, that install is there, not in
+  // the repo's top folder (UIG-32). Everything it names is still read from the top.
   const checksFile = join(ROOT, app, 'scripts', 'gates-checks.mjs')
   const define = ((await import(pathToFileURL(checksFile).href)) as { default: (h: GateHelpers) => GateSpec }).default
   const spec = define(h)
@@ -452,7 +475,7 @@ async function runRepo(ROOT: string, app: string, h: GateHelpers): Promise<{ spe
  * Another repository's report. A repo on the package's engine runs it from its
  * own install; a repo still carrying `scripts/gates-status.mjs` runs that copy.
  *
- * `app` is the folder that repo's app sits in — `web` in Ship — where its
+ * `app` is the folder that repo's app sits in, when not the top, where its
  * install and its checks file are. The report is still of the whole repo.
  */
 function runSibling(dir: string, app: string, shown: string): { report?: Report; error?: string } {
@@ -479,6 +502,28 @@ function runSibling(dir: string, app: string, shown: string): { report?: Report;
   }
 }
 
+/**
+ * How far a checkout is behind its remote's main, after fetching it. Status reads
+ * the checkout, not main: a copy seven commits behind once reported a finished
+ * ticket as not started (audit A4). Empty when it is level; a warning otherwise.
+ */
+export function behindMain(dir: string): string {
+  const git = (...a: string[]) => {
+    try {
+      return execFileSync('git', a, { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'], timeout: 30000 }).toString().trim()
+    } catch {
+      return null
+    }
+  }
+  if (git('rev-parse', '--is-inside-work-tree') !== 'true') return ''
+  const fetched = git('fetch', '-q', 'origin') !== null
+  const main = (git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD') ?? 'origin/main').trim()
+  const count = Number(git('rev-list', '--count', `HEAD..${main}`))
+  const stale = fetched ? '' : ' (could not fetch: compared with the last fetch)'
+  if (!Number.isFinite(count) || count === 0) return stale ? ` ·${stale}` : ''
+  return ` · ⚠️ ${count} commit${count === 1 ? '' : 's'} behind ${main}${stale}: pull, or this reads old code`
+}
+
 function pad(s: string, n: number) {
   const len = [...s].length
   return len >= n ? s : s + ' '.repeat(n - len)
@@ -509,7 +554,7 @@ function summary(rows: Row[]) {
 export interface StatusOptions {
   /** The repository to report on. */
   root?: string
-  /** The folder that holds the app, relative to `root`: `web` in Ship, `.` elsewhere. */
+  /** The folder that holds the app, relative to `root`: `.` unless it sits in a folder of its own. */
   app?: string
   json?: boolean
   detail?: boolean
@@ -526,7 +571,7 @@ export async function runStatus({ root = process.cwd(), app = '.', json = false,
 
   const out: string[] = []
   out.push('UI Guardrails · gates:status', 'Read from the code. Nothing here is a hand-ticked list.', '')
-  out.push(`${pad(spec.repo, 10)} ${report.branch} @ ${report.commit}`)
+  out.push(`${pad(spec.repo, 10)} ${report.branch} @ ${report.commit}${behindMain(ROOT)}`)
 
   if (!spec.all) {
     // A sibling repo on its own: its own rows, then its parts of rows owned elsewhere.
@@ -553,7 +598,7 @@ export async function runStatus({ root = process.cwd(), app = '.', json = false,
       continue
     }
     const copy = r.report.engine !== ENGINE ? (r.report.engine.startsWith('@estiva-app/ui@') ? ` · on ${r.report.engine}'s engine` : ' · runs its own copy of the status engine; UIG-32 moves it onto the package') : ''
-    found.push({ name: s.name, note: `${r.report.branch} @ ${r.report.commit}, found at ${shown(dir)}${copy}` })
+    found.push({ name: s.name, note: `${r.report.branch} @ ${r.report.commit}, found at ${shown(dir)}${copy}${behindMain(dir)}` })
     reports.push(r.report)
   }
   for (const f of found) out.push(`${pad(f.name, 10)} ${f.note}`)