novahiz 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-06
+
+Feature release: the gate learns project scope, and Stitch design projects
+get a capture → composite → fidelity-verdict loop.
+
+### Added
+
+- **`R16-stitch-fidelity` gate rule**: editing a UI file (`*.tsx`, `*.jsx`,
+  `*.vue`, `*.svelte`, `*.dart`, `*.css`, `*.scss`, `*.html`) now requires
+  the `novahiz-stitch-fidelity` skill — but only inside a project that
+  carries `stitch/**` references. This is the new `projectGlobs` selector
+  (`src/spec.ts`, `src/gate.ts`): nearest ancestor of the edited file
+  holding `.git`, `package.json` or `pubspec.yaml`, globs written from that
+  root. Projects without Stitch references are unaffected.
+- **`novahiz-stitch-fidelity` skill**: `scripts/stitch_capture.mjs` (adb:
+  uiautomator dump, screencap, input, adb.autoStart), `scripts/stitch_composite.mjs`
+  (screenshot ↔ design overlay), the fidelity judgment grid, capture
+  recipes and a `verify.config.defaults.json`.
+- **`stitch-fidelity` provider** (`kind: commands`): adb prerequisite with
+  per-OS bootstrap (winget / brew / apt), categories `design-ui`, `expo`,
+  `flutter`; `stitch_capture.mjs --check` reports the seven readiness items.
+- Optional `stitch-verify` roadmap step (`kind: verify`) in two roadmaps.
+- Tests: `tests/gate-stitch-fidelity.test.ts` — project-scoped enforcement.
+
+### Changed
+
+- README headline and counts refreshed: 99 skills, 13 gate rules, 8 MCP
+  providers, version line at 0.6.0 (was advertising 96/11/7 and 0.4.1).
+
 ## [0.5.2] - 2026-10-05
 
 Maintenance release closing the three leftovers traced right after `0.5.1`:

package/README.md

@@ -2,9 +2,9 @@
 
 > **Couche d'application sans dépendance pour les agents de code IA** — classe les prompts, attribue des roadmaps d'exécution, bloque les éditions non sûres tant que les bonnes skills ne sont pas chargées, et persiste les décisions d'une session à l'autre — tout cela de façon déterministe, sans appel de modèle.
 
-17 catégories, 96 skills, 11 gate rules, 7 MCP providers — tout déterministe, tout local, tout JSON.
+17 catégories, 99 skills, 13 gate rules, 8 MCP providers — tout déterministe, tout local, tout JSON.
 
-> **Version 0.4.1** — publiée sur npm (`npm install -g --allow-scripts=novahiz novahiz` installe et configure tout : core, plugin, agent, skills packs et Playwright MCP). `CHANGELOG.md` et `scripts/` sont dans le tarball.
+> **Version 0.6.0** — publiée sur npm (`npm install -g --allow-scripts=novahiz novahiz` installe et configure tout : core, plugin, agent, skills packs et Playwright MCP). `CHANGELOG.md` et `scripts/` sont dans le tarball.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────┐
@@ -35,7 +35,7 @@
                  └─ tier, skills ──────│         └─ block : charger les skills nommées, retry une fois
 ```
 
-**17 catégories**, **96 skills**, **11 gate rules**, **7 MCP providers** — tout déterministe, tout local, tout JSON.
+**17 catégories**, **99 skills**, **13 gate rules**, **8 MCP providers** — tout déterministe, tout local, tout JSON.
 
 ---
 
@@ -310,7 +310,7 @@ Deux pièces complémentaires : la session consomme moins sans perdre en puissan
 
 ## Skills installées
 
-Novahiz livre 98 skills couvrant toutes les catégories :
+Novahiz livre 99 skills couvrant toutes les catégories :
 
 | Catégorie | Skills | Objectif |
 |-----------|--------|----------|

package/catalog/categories.json

@@ -198,6 +198,13 @@
           "kind": "skill",
           "requireSkills": ["dart-add-unit-test"]
         },
+        {
+          "id": "stitch-verify",
+          "label": "Verify screens against Stitch references (projects carrying stitch/**)",
+          "kind": "verify",
+          "requireSkills": ["novahiz-stitch-fidelity"],
+          "optional": true
+        },
         {
           "id": "impeccable-critique",
           "label": "Impeccable critique (UI work)",
@@ -307,6 +314,13 @@
           "kind": "edit",
           "requireSkills": ["novahiz-implement"]
         },
+        {
+          "id": "stitch-verify",
+          "label": "Verify screens against Stitch references (projects carrying stitch/**)",
+          "kind": "verify",
+          "requireSkills": ["novahiz-stitch-fidelity"],
+          "optional": true
+        },
         {
           "id": "converge",
           "label": "Converge",

package/catalog/providers.json

@@ -108,6 +108,31 @@
     "categories": ["audit"],
     "purpose": "Local stdio static-analysis server (zero npm dependency): scans files and directories with local security rules (SQL injection, XSS, command injection, hardcoded secrets, insecure deserialization), creates custom rules behind a ReDoS gate, exports json/sarif/csv/html. Original clean-room implementation for the audit category."
   },
+  {
+    "id": "stitch-fidelity",
+    "label": "Stitch fidelity capture (adb + Android emulator)",
+    "kind": "commands",
+    "requires": ["adb"],
+    "bootstrap": {
+      "win32": [
+        "winget install --id Google.PlatformTools",
+        "winget install --id Google.AndroidStudio"
+      ],
+      "darwin": [
+        "brew install --cask android-platform-tools",
+        "brew install --cask android-commandlinetools"
+      ],
+      "linux": [
+        "sudo apt-get install -y adb",
+        "sudo apt-get install -y android-sdk"
+      ],
+      "default": ["install Android platform-tools (adb) and the Android emulator on PATH"]
+    },
+    "source": "https://github.com/novahiz/novahiz",
+    "license": "Apache-2.0",
+    "categories": ["design-ui", "expo", "flutter"],
+    "purpose": "Prerequisite for skill novahiz-stitch-fidelity: `adb` drives the capture (uiautomator dump, screencap, input). `emulator` is only needed to auto-start a device when nothing is online (adb.autoStart); `stitch_capture.mjs --check` reports all seven readiness items."
+  },
   {
     "id": "novahiz-gate",
     "label": "novahiz-gate",

package/catalog/rules.json

@@ -156,5 +156,24 @@
       ]
     },
     "require": ["token-economy"]
+  },
+  {
+    "id": "R16-stitch-fidelity",
+    "description": "Load novahiz-stitch-fidelity before editing the UI of a project that carries Stitch references (stitch/**): capture, composite and fidelity verdict must be part of that loop.",
+    "when": {
+      "match": "all",
+      "pathGlobs": [
+        "**/*.tsx",
+        "**/*.jsx",
+        "**/*.vue",
+        "**/*.svelte",
+        "**/*.dart",
+        "**/*.css",
+        "**/*.scss",
+        "**/*.html"
+      ],
+      "projectGlobs": ["stitch/**"]
+    },
+    "require": ["novahiz-stitch-fidelity"]
   }
 ]

package/dist/gate.js

@@ -1,4 +1,5 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { hasPlaceholder, hasProse, hasStyle, isTrivial } from "./content.js";
 import { determineTier } from "./complexity.js";
 // Shared ledger enforcement (audit P1-D/M1): the CLI command and the MCP
@@ -215,6 +216,76 @@ export function contentSatisfies(content, patterns) {
         }
     });
 }
+// R16: "only in projects that carry X" cannot be expressed per file — the gate
+// sees the edited path, not the repository. `when.projectGlobs` closes that gap:
+// the globs are resolved from the project root (the nearest ancestor of the
+// edited file holding .git, package.json or pubspec.yaml) and scanned from the
+// glob's literal prefix, so a rule never walks node_modules.
+const PROJECT_ROOT_MARKERS = [".git", "package.json", "pubspec.yaml"];
+const PROJECT_SKIP_DIRS = new Set([".git", "node_modules"]);
+export function projectRootOf(filePath) {
+    let dir = dirname(resolve(filePath || "."));
+    for (;;) {
+        if (PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(dir, marker))))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function listFilesUnder(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // unreadable directory: contributes nothing rather than throwing
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!PROJECT_SKIP_DIRS.has(entry.name))
+                listFilesUnder(full, out);
+        }
+        else if (entry.isFile()) {
+            out.push(full);
+        }
+    }
+}
+export function projectGlobsMatch(root, globs) {
+    if (!root) {
+        console.error("[Novahiz] projectGlobs: project root could not be resolved — the rule will not apply");
+        return false;
+    }
+    for (const glob of globs) {
+        const normalized = glob.replace(/\\/g, "/");
+        // Scanning starts at the literal prefix: "stitch/**" only reads stitch/.
+        // A glob whose prefix is pure wildcards cannot be scoped — fail closed on
+        // that pattern (never matches) instead of walking the whole project.
+        const literalPrefix = normalized.split(/[?*[\]]/, 1)[0].replace(/\/+$/, "");
+        if (literalPrefix.length === 0) {
+            console.error(`[Novahiz] projectGlobs "${glob}" must start with a literal segment — skipped`);
+            continue;
+        }
+        const base = join(root, literalPrefix);
+        const stats = statSync(base, { throwIfNoEntry: false });
+        if (!stats)
+            continue;
+        const candidates = [];
+        if (stats.isFile())
+            candidates.push(base);
+        else
+            listFilesUnder(base, candidates);
+        const pattern = globToRegExp(normalized);
+        for (const file of candidates) {
+            const rel = relative(root, file).split("\\").join("/");
+            if (pattern.test(rel))
+                return true;
+        }
+    }
+    return false;
+}
 function selectorMatches(rule, classification, path, categories, pathless = false) {
     const when = rule.when;
     const checks = [];
@@ -290,9 +361,22 @@ export function evaluateGate(input) {
         const tier = input.tier ?? determineTier(prompt.length > 0 ? prompt : content);
         const requiredSkills = [];
         const matchedRules = [];
+        // Resolved lazily: only a rule carrying projectGlobs pays for the walk up to
+        // the project root (and the result is reused by every following rule).
+        let projectRoot;
         for (const rule of input.spec.rules) {
             if (!selectorMatches(rule, classification, path, categories, pathless))
                 continue;
+            if (rule.when.projectGlobs && rule.when.projectGlobs.length > 0) {
+                // Pathless probes carry no file: there is no repository to inspect, so
+                // an unprovable project condition never grants the rule (fail closed).
+                if (pathless)
+                    continue;
+                if (projectRoot === undefined)
+                    projectRoot = projectRootOf(path);
+                if (!projectGlobsMatch(projectRoot, rule.when.projectGlobs))
+                    continue;
+            }
             // Tier gating for R6-Novahiz: trivial = skip entirely, lite = only implement+converge
             if (rule.id === "R6-Novahiz") {
                 if (tier === "trivial")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novahiz",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Enforce AI agent skills before every file edit: prompt classifier, skill catalog, and pre-edit gate.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/novahiz-stitch-fidelity/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: novahiz-stitch-fidelity
+description: Prove a screen matches its Stitch reference instead of asserting it — capture the running app, composite reference vs render with a fresh marker, judge on a fixed grid, then fix and re-verify until the verdict is clean. Use when a screen originates from a Stitch maquette, when the user asks whether the build is identical to the mockup, before shipping screens in a project that carries stitch/ exports, or when a fidelity todo must be closed with evidence. Different from novahiz-wcag-audit (accessibility) and impeccable (design quality judgement): this one returns a per-screen PASS or DIVERGE verdict against one specific reference image, with measured numbers. Works for Expo, Flutter and any adb-driven mobile app; needs stitch/verify.config.json in the project.
+license: Apache-2.0
+metadata:
+  author: novahiz
+---
+
+# novahiz-stitch-fidelity
+
+A fidelity claim is only true once a screenshot of the running app has been compared with the Stitch
+reference **in the same session, with a marker that proves the image is current**. This skill is the
+loop that produces that proof: reach the screen, capture it, build the comparison, judge it, fix it,
+capture again.
+
+The gate (rule `R16-stitch-fidelity`) blocks edits to screens in a project that carries Stitch
+references until this skill is loaded. Load it before touching those files, ahead of the refusal.
+
+## When this applies
+
+- The screen was built from a Stitch maquette (a `stitchId` in the screen registry, or a reference
+  file in `stitch/`).
+- The user asks "identique à la maquette ?", "does it match the mockup?", "vérifie la fidélité".
+- A verification todo of kind `verify` targets screens of a Stitch project.
+
+Not this skill: judging whether a design is *good* (use `impeccable`), whether it is *accessible*
+(use `novahiz-wcag-audit`), whether the *code* is correct (use `novahiz-converge`).
+
+## Contract: `stitch/verify.config.json`
+
+Everything project-specific lives there, so both scripts stay framework-agnostic. Create it next to
+the references if it does not exist.
+
+```jsonc
+{
+  "adb": { "serial": "emulator-5554", "density": 2.625 },  // density = dp -> px factor
+  "launch": {
+    // {route} is replaced by the route of the screen. Leave null to use the ladder below.
+    "deepLink": "exp://10.0.2.2:8081/--/{route}",   // Expo Go example; Flutter: "myapp://"
+    "waitForIdleMs": 4500,
+    "batch": 3                                        // screens per shell command, max 3
+  },
+  "screens": [
+    { "id": "otp",  "route": "/otp",          "ref": "stitch/10-otp-hi.png",       "stitchId": "0e0fad..." },
+    { "id": "home", "route": "/",             "ref": "stitch/01-home-hi.png" }
+  ],
+  "out": "stitch/_cmp",        // git-ignored: captures, bounds, composites
+  "serve": { "root": "stitch", "port": 8123 },
+  "project": { "stitchProjectId": "14523755384223316097" }  // optional, for MCP fetch
+}
+```
+
+## The loop
+
+Scripts live in this skill's `scripts/` directory (base directory shown with the skill). Run them
+from the project root so relative paths in the config resolve.
+
+1. **References first.** Confirm every screen you are about to judge has a local reference PNG.
+   Missing one: fetch it from the Stitch MCP (`stitch.get_screen`, project id above, `htmlCode`
+   plus a screenshot) or from the exported `*-hi.png`, and write it to the path in `config.screens`.
+   No reference, no verdict — record the screen as *not evaluable*.
+2. **Server up.** The app must be running (Metro / `flutter run`) in an **external terminal**, and
+   the device awake and unlocked.
+3. **Capture:** `node <scripts>/stitch_capture.mjs --config stitch/verify.config.json [--only otp,home]`
+   Writes `<out>/<id>.png` and `<out>/<id>.bounds.json` (uiautomator bounds, for measured numbers)
+   and prints a per-screen status table (`ok` / `unreachable`). Non-zero exit if any selected screen
+   failed. Never run more than `launch.batch` screens in one command: adb drops past ~3.
+4. **Composite:** `node <scripts>/stitch_composite.mjs --config stitch/verify.config.json`
+   Writes `<out>/verify_<nonce>.html`: reference and capture side by side, `<img>` cache-busted with
+   `?v=<nonce>`, a unique marker `STITCH_FRESH_<nonce>`, and a legend per screen with the deltas
+   computed from the bounds files (bottom inset px, tap target sizes, text bounds).
+5. **Look at the composite, fresh.** Serve `serve.root` on `serve.port` and open
+   `http://localhost:<port>/_cmp/verify_<nonce>.html?v=<nonce>` in a **new browser tab**, then take a
+   screenshot of that tab. Before any verdict, confirm the marker `STITCH_FRESH_<nonce>` is visible
+   in what you just captured. Not visible → you are looking at a stale render: restart at step 5.
+6. **Judge** every screen on the grid in `references/judgment-grid.md`. Each line gets PASS or
+   DIVERGE **with a number** (px, dp, hex, token name). A DIVERGE without a measurement is a guess.
+7. **Fix** the divergences in the app code, then re-run steps 3 → 5 for those screens only.
+8. **Close** with the table: screen, verdict, measurement, commit. Screens that stayed unreachable
+   are reported as *not evaluable* with the reason. Never report a screen as matching because the
+   code "looks like" the reference.
+
+Repeat 3 → 7 until every reachable screen is PASS, or until the remaining divergences are recorded
+as known and accepted.
+
+## Reaching a screen
+
+Not every screen is one deep link away. Use the ladder in order and stop when one works:
+
+1. **Deep link** — `config.launch.deepLink`, cold start when the route is guarded.
+2. **Initial route** — start the app and the screen appears first (useful for `/`).
+3. **Taps** — drive the real UI: `uiautomator dump`, read `bounds`, `adb shell input tap x y`.
+   Prefer this over hacks; a screen only reachable through taps must be reached through taps.
+4. **Not evaluable** — auth wall, backend state, or an animation that cannot be settled. Record the
+   screen with the reason and move on. **This is a valid outcome; a fabricated verdict is not.**
+
+Details per framework (Expo vs Flutter, launch, wait, gesture insets) in
+`references/capture-recipes.md`.
+
+## Failure notes
+
+- `uiautomator dump` fails with "idle state" while an animation runs: wait, retry once, then tap a
+  neutral point to settle the UI.
+- adb silently truncates `screencap`: always use `adb exec-out screencap -p`.
+- dp → px: multiply by `adb.density`. Never compare raw dp to raw px.
+- Composites are git-ignored artifacts. Commit app code only — never `stitch/_cmp/`.
+- The reference PNG must be the *hi* export, not a thumbnail; a scaled reference makes every
+  spacing comparison wrong.
+
+## Sources
+
+Loop, anti-staleness protocol and access ladder synthesised from the Novahiz Stitch integration
+sessions (Expo + adb). Reference: Stitch exports and the project's own `stitch/` folder.

package/skills/novahiz-stitch-fidelity/defaults/verify.config.defaults.json

@@ -0,0 +1,29 @@
+{
+  // Global defaults for the novahiz-stitch-fidelity skill.
+  // Shipped with Novahiz: every project inherits these, a project's own
+  // stitch/verify.config.json only overrides what is really project specific
+  // (its screens, routes, references and deep link template).
+  "adb": {
+    "serial": "auto",
+    "autoStart": true,
+    "density": null,
+    "bootTimeoutMs": 180000
+  },
+  "launch": {
+    "deepLink": null,
+    "waitForIdleMs": 6000,
+    "maxWaitMs": 30000,
+    "pollMs": 800,
+    "tapSettleMs": 900,
+    "batch": 3,
+    "coldStart": false,
+    "resetScroll": true,
+    "scrollSettleMs": 900
+  },
+  "ready": {
+    "minTexts": 3,
+    "minNodes": 12
+  },
+  "out": "stitch/_cmp",
+  "serve": { "root": "stitch", "port": 8123 }
+}

package/skills/novahiz-stitch-fidelity/references/capture-recipes.md

@@ -0,0 +1,74 @@
+# Capture recipes
+
+Per-framework launch, device commands, and the anti-staleness protocol. Everything else lives in
+`SKILL.md` and `stitch/verify.config.json`.
+
+## Device basics
+
+```sh
+adb devices                                   # serial goes in config.adb.serial
+adb -s <serial> shell wm size                 # e.g. 1080x2424
+adb -s <serial> shell wm density              # e.g. 420 -> 2.625 px per dp
+adb -s <serial> shell input keyevent 82        # wake
+adb -s <serial> exec-out screencap -p > out.png   # never plain `screencap` (truncates)
+adb -s <serial> shell uiautomator dump /sdcard/d.xml && adb -s <serial> pull /sdcard/d.xml
+adb -s <serial> shell input tap <x> <y>
+```
+
+`uiautomator dump` fails with *"unable to get idle state"* while an animation runs. Wait, retry once,
+then tap an empty area of the screen to settle it before the second attempt.
+
+**Batch at most 3 screens per shell invocation.** Past that adb drops the connection and the batch
+dies midway; the capture script enforces `launch.batch`.
+
+## Expo (React Native / Expo Go)
+
+- Metro runs in an **external terminal** (`npx expo start`), never as a background shell of the agent.
+- Emulator reaches the host at `10.0.2.2`: `exp://10.0.2.2:8081/--/<route>`.
+- Cold start a guarded route: `adb shell am force-stop <package>` first, then
+  `adb shell am start -a android.intent.action.VIEW -d "<deeplink>"`.
+- Route `/foo` maps to `.../--/foo`; the app root is `--/` (with a trailing slash).
+- If a route renders blank, the file may be misnamed (`index.tsx` serves `/`, not `/index`): verify
+  with `uiautomator dump` before blaming the capture.
+
+## Flutter
+
+- `flutter run` in an external terminal; keep the same hot-reload session while fixing.
+- Deep link through the registered scheme: `adb shell am start -a android.intent.action.VIEW -d "<scheme>://<path>"`.
+- Widgets that are not routable (dialogs, bottom sheets) are reached by tap: dump, read bounds,
+  `input tap`.
+- Take screenshots from the device, never from the IDE preview or a widget test — neither renders
+  the real theme, real fonts, or real insets.
+
+## Reaching a screen (the ladder)
+
+1. Deep link from `launch.deepLink`.
+2. Initial route (cold start, screen appears first).
+3. Taps driven by `uiautomator dump` bounds.
+4. **Not evaluable** — record `unreachable` with the reason (auth wall, backend state, animation
+   that cannot settle). A recorded `unreachable` is an honest result; a fabricated PASS is not.
+
+## Anti-staleness protocol (mandatory before any verdict)
+
+A rendered file read back by an agent can be stale — the viewer, the cache, or the tool may hand you
+the previous image. Never compare what you did not just prove is fresh.
+
+1. Build the composite (`stitch_composite.mjs`) — it emits `STITCH_FRESH_<nonce>` in the page and
+   appends `?v=<nonce>` to **every** `<img>`.
+2. Serve `serve.root` on `serve.port` (`npx http-server stitch -p 8123`, or
+   `python -m http.server 8123 -d stitch`, in an external terminal).
+3. Open `http://localhost:<port>/_cmp/verify_<nonce>.html?v=<nonce>` in a **new browser tab**.
+4. Screenshot that tab.
+5. Confirm the marker string is present in the screenshot / DOM you just captured. Missing → the
+   render is stale: reload with a new `?v=` and repeat from step 3.
+6. Only then form a verdict.
+
+## Fix loop
+
+Change the screen code → hot reload → `stitch_capture.mjs --only <ids>` → `stitch_composite.mjs` →
+steps 3-5 of the protocol → re-judge **only those screens**. Cap iterations; after the cap, record
+the remaining divergences with their measurements instead of looping silently.
+
+## Out of scope for commits
+
+`stitch/_cmp/` holds captures, bounds JSON and composites — all git-ignored. Commit app code only.

package/skills/novahiz-stitch-fidelity/references/judgment-grid.md

@@ -0,0 +1,67 @@
+# Judgment grid
+
+Run every reachable screen through these eight lines. Each line ends with **PASS** or **DIVERGE**,
+and a DIVERGE carries a measurement: px, dp (after `adb.density`), hex, or token name. A verdict
+without a number is a guess — discard it.
+
+## 1. Layout and hierarchy
+
+- Same skeleton as the reference: header, primary block, action zone, tab bar. No extra block, no
+  missing block.
+- Measure with the anchor bounds from `<id>.bounds.json`, not by eye. Overlay the reference at the
+  same device width and compare the block edges.
+
+## 2. Spacing and rhythm
+
+- Padding, gaps and margins equal the reference within 1 dp. Report the delta in dp *and* px.
+- Rhythm: the vertical gaps inside a stack are consistent with each other, not just with the ref.
+
+## 3. Color and surfaces
+
+- Every fill matches a design token (`tokens.ts`, `theme`, `ColorScheme`) — no raw hex in a screen
+  file that duplicates an existing token.
+- Opaque vs translucent: a scrim or sticky footer must be opaque or explicitly conditional. A
+  `rgba()` backdrop painted outside its modal is a DIVERGE even when the modal is closed.
+- Check the reference at full resolution for subtle tints; a thumbnail hides them.
+
+## 4. Typography
+
+- Sizes, weights and line heights match the reference token scale. Compare the token values against
+  the reference's own type ramp, not against each other.
+- No default platform font creeping in where the project declares one.
+
+## 5. Copy
+
+- Strings identical to the reference: wording, punctuation, casing, plural.
+- Project forbidden-terms list respected (for a West-African FCFA app: no supranational-institution
+  names in product copy). Exact match required — this line has zero tolerance.
+
+## 6. States
+
+- Whatever state the reference shows (empty, loading, error, disabled, focused) exists in the build,
+  and a state the reference does *not* show is not painted unconditionally.
+
+## 7. Native-ness
+
+- Real platform components (native button, native list row) instead of web-shaped markup. Nested
+  interactive elements, `<div>`-style wrappers, and browser-only behaviour are DIVERGE.
+
+## 8. Gesture and safe-area clearance
+
+- Bottom action bars clear the system gesture area: measure the distance from the last interactive
+  element to the screen bottom in px, convert to dp, and compare with the reference.
+- Pattern to check in code: `paddingBottom` driven by an inset **plus** a constant (`max(inset, 16) +
+  32`), never the raw inset value.
+- No tappable control within 8 dp of another (fat-finger collisions).
+
+## Tolerance policy
+
+| Dimension | Tolerance |
+|---|---|
+| Copy | exact |
+| Colors | exact token match |
+| Layout blocks, spacing | 1 dp |
+| Gesture clearance | must exceed the device inset |
+
+Anything outside tolerance is DIVERGE. When two lines disagree (looks right, measures wrong),
+**the measurement wins**.