From 5e40e598b458ab826d97784527ad575c1c4d322d Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Tue, 28 Jul 2026 10:03:56 +0800 Subject: [PATCH 1/2] docs(agents): add external skill precedence and evidence rules The Front-End Checklist skill corpus (~390 skills) and the caveman output-style plugin are installed user-global and know nothing about this repo's contracts. Adds a tie-breaker section so generic guidance never overrides committed docs or tests. - Repo docs win on conflict: wiring-conventions, search-chrome-behaviour, rag-behaviour, the @theme tokens in globals.css, and any committed test. - Records the touch-target collision: generic WCAG 44px guidance maps to min-h-11, which hit a sub-pixel rounding flake in ui-smoke, so production tap targets use min-h-12. Design-scratch mockups still carry min-h-11 and remain gate-exempt. - Output-style compression never applies to verification evidence or calibration: paste the decisive gate line, state verified vs assumed, and treat third-party fix claims as unverified until checked. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 222a970b9f..28e0a2c1c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -222,6 +222,42 @@ The shared search chrome must adapt by page ownership, not by ad-hoc padding or + + +# External skill precedence + +User-global skills and output-style plugins are installed outside this repo and know nothing about +its contracts. Repo docs and committed tests always win. This section is the tie-breaker. + +- **Repo contracts outrank generic rules.** The Front-End Checklist skill corpus (~390 user-global + skills: `alt-text`, `touch-targets`, `focus-styles`, `reduced-motion`, `color-contrast`, and so + on) is generic guidance. On any conflict these win: `docs/wiring-conventions.md`, + `docs/search-chrome-behaviour.md`, `docs/rag-behaviour/`, the `@theme` tokens in + `src/app/globals.css`, and any committed test. +- **Never regress a fixed flake to satisfy a generic rule.** Known collision: generic touch-target + guidance teaches the WCAG 44px minimum, which is `min-h-11` in Tailwind, but `min-h-11` hit a + sub-pixel rounding flake in `ui-smoke`, so production tap targets use `min-h-12` (for example + `src/components/specifiers/`). Design-scratch mockups (`*-mockups.tsx`) still carry `min-h-11` + and are gate-exempt. Do not "fix" production back to `min-h-11` to satisfy the generic rule. +- **Unlayered CSS is deliberate.** Component classes in `globals.css` intentionally override + Tailwind utilities. Generic specificity and utility-first advice does not apply here. +- **Cite the source when applying an external rule.** If a checklist rule drives a change, name the + rule and confirm it contradicts no repo doc or test. + +## Evidence and calibration are never compressed + +Output-style plugins such as caveman mode may compress prose. They must never compress proof. + +- **Always paste the decisive line.** Report gates with real output, not a summary. `npm run +verify:ui` exits 0 without running a single Playwright test when another worktree holds the heavy + lock, so grep for the "N passed" line; exit 0 alone is not proof. +- **State verified versus assumed.** Calibration is not filler. Say what was actually run, what was + read, and what is inferred. Do not drop uncertainty to save tokens. +- **Third-party fix claims stay unverified until checked.** Bot or agent claims that a fix landed + require `git fetch` plus inspection of the ref before they are repeated as fact. + + + # Supabase project safety From 57bfe6567b1390449b842359c5b0e3c1b2741089 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Tue, 28 Jul 2026 03:31:59 +0000 Subject: [PATCH 2/2] fix: apply CodeRabbit auto-fixes Fixed 1 file(s) based on 2 unresolved review comments. Co-authored-by: CodeRabbit --- AGENTS.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 28e0a2c1c5..f090e428cd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -235,10 +235,12 @@ its contracts. Repo docs and committed tests always win. This section is the tie `docs/search-chrome-behaviour.md`, `docs/rag-behaviour/`, the `@theme` tokens in `src/app/globals.css`, and any committed test. - **Never regress a fixed flake to satisfy a generic rule.** Known collision: generic touch-target - guidance teaches the WCAG 44px minimum, which is `min-h-11` in Tailwind, but `min-h-11` hit a - sub-pixel rounding flake in `ui-smoke`, so production tap targets use `min-h-12` (for example - `src/components/specifiers/`). Design-scratch mockups (`*-mockups.tsx`) still carry `min-h-11` - and are gate-exempt. Do not "fix" production back to `min-h-11` to satisfy the generic rule. + guidance often teaches the WCAG 2.1/2.2 AAA-level "enhanced" criterion (2.5.5: 44×44 px, which is + `min-h-11` in Tailwind), though the AA-level minimum is 24×24 px (2.5.8). This repo's production + tap targets use `min-h-12` (48 px) — exceeding both the AA minimum and the AAA enhanced criterion — + because `min-h-11` (44 px) hit a sub-pixel rounding flake in `ui-smoke`. Design-scratch mockups + (`*-mockups.tsx`) still carry `min-h-11` and are gate-exempt. Do not "fix" production back to + `min-h-11` to satisfy the generic rule. - **Unlayered CSS is deliberate.** Component classes in `globals.css` intentionally override Tailwind utilities. Generic specificity and utility-first advice does not apply here. - **Cite the source when applying an external rule.** If a checklist rule drives a change, name the @@ -254,7 +256,10 @@ verify:ui` exits 0 without running a single Playwright test when another worktre - **State verified versus assumed.** Calibration is not filler. Say what was actually run, what was read, and what is inferred. Do not drop uncertainty to save tokens. - **Third-party fix claims stay unverified until checked.** Bot or agent claims that a fix landed - require `git fetch` plus inspection of the ref before they are repeated as fact. + must be verified against the actual ref/commit content before being repeated as fact. Prioritize + inspecting already-fetched local refs (`git log`, `git show`) first; `git fetch` or other + network/provider access requires explicit user confirmation per the "API and provider confirmation + boundary" section.