novahiz 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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`:
+the installer's dead `plugin` config key, the unread `tokens` block of the
+example config, and the scheduler's 0 ms wake loop on a busy task.
+
+### Fixed
+
+- `install/install.mjs` no longer writes a `"plugin"` array of **file paths**
+  into a freshly created `opencode.jsonc`. opencode never read it (the plugins
+  are loaded from `<config>/plugins`, proved in E2E: the key pointed at the
+  repo while the loaded copies came from the plugins directory) and a file
+  entry triggered `configured plugin path must be a directory` at every
+  startup. Existing configs are left untouched.
+- `novahiz.config.example.json` no longer advertises a `tokens` block
+  (`enabled`, `trimOutputs`, `keepHeadLines`, `dedupeReads`, `capOutputTokens`,
+  `trimTools`, …) that no code ever read — a leftover of a layer that was never
+  shipped. The example now carries exactly the keys `defaultConfig()` writes,
+  and `docs/TOKENS.md` states it instead of pointing at a block that should
+  not be there.
+- `mcp/clepsydre/src/scheduler.ts`: `arm()` no longer arms a timer for a task
+  that is already running. A past-due schedule on a busy task used to feed a
+  0 ms `wake → skip → arm` loop (one task-store read per turn) for the whole
+  execution, and a manual trigger could sustain it. The lock release now goes
+  through `release()`, which re-evaluates the calendar once the task is free,
+  so a due occurrence is still caught up exactly once instead of by the spin.
+
 ## [0.5.1] - 2026-10-05
 
 Fix-forward release: the `v0.5.0` tag was pushed but its CI never reached

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/docs/TOKENS.md

@@ -95,9 +95,10 @@ from the local enforcement database.
 
 ## Not implemented
 
-`novahiz.config.example.json` still carries a `tokens` block (`enabled`,
-`trimOutputs`, `keepHeadLines`, `keepTailLines`, `keepErrorLines`,
-`dedupeReads`, `capOutputTokens`, `trimTools`, `readTools`). No code reads it:
-it is a leftover of a layer that was never shipped, and neither the plugin nor
-`novahiz tokens` consumes it. Configure the plugin with the environment
-variables above instead.
+There is no `tokens` section in `novahiz.config.example.json`: no code ever
+read the one it carried (`enabled`, `trimOutputs`, `keepHeadLines`,
+`keepTailLines`, `keepErrorLines`, `dedupeReads`, `capOutputTokens`,
+`trimTools`, `readTools`) — a leftover of a layer that was never shipped, and
+neither the plugin nor `novahiz tokens` consumes it. It has been removed from
+the example rather than left to contradict this document. Token economy is
+configured with the environment variables above, and nothing else.

package/install/install.mjs

@@ -236,9 +236,11 @@ async function main() {
     }
   }
 
-  // opencode charge les .ts posés dans <config>/plugins: E2E montre que le
-  // registre des plugins déclare le chemin de ce répertoire, pas celui du
-  // tableau "plugin" de la config — les deux restent en cohérence.
+  // opencode charge automatiquement les .ts de <config>/plugins. Preuve E2E:
+  // le tableau "plugin" de la config pointait vers ce depôt alors que les
+  // plugins charges venaient de <config>/plugins — le tableau est donc retire
+  // du modele de config, une entree fichier y declenchait l'avertissement
+  // "configured plugin path must be a directory" a chaque demarrage.
   for (const pluginFile of ["novahiz-plugin.ts", "novahiz-token-economy.ts"]) {
     const pluginSource = join(home, "adapters", "opencode", pluginFile);
     const pluginTarget = join(pluginsDir, pluginFile);
@@ -519,9 +521,6 @@ async function main() {
         "skills": {
           "paths": [skillsDir]
         },
-        "plugin": [
-          join(home, "adapters", "opencode", "novahiz-plugin.ts")
-        ],
         "compaction": {
           "auto": true,
           "prune": true,

package/mcp/clepsydre/src/scheduler.ts

@@ -11,6 +11,10 @@
 // bascule toujours en traitement special : une tache n'execute jamais deux
 // fois en parallele (verrou `busy`), meme si la cadence est plus rapide que
 // la duree de l'execution.
+// Le verrou ne s'arme jamais : `arm()` ignore les taches busy, sinon une
+// echeance passee donnerait un timer 0 ms en boucle (`skip -> arm`) pendant
+// toute l'execution ; la liberation re-evalue les echeances et rattrape
+// l'occurrence due une seule fois.
 
 import { appendExecution, findTask, loadTasks, mutateTasks, newId, saveTasks, type Task } from "./store.ts";
 import { nextRun, parseSchedule, type Schedule } from "./cron.ts";
@@ -125,6 +129,11 @@ export class Scheduler {
   }
 
   /** Arme le prochain reveil sur l'echeance la plus proche.
+   *  Une tache en execution (verrou `busy`) est ignoree : son echeance passe
+   *  reste en file jusqu'a la liberation, et un reveil dessus ne ferait que
+   *  boucler (`timer 0 ms -> wake -> skip -> arm`) pendant toute
+   *  l'execution, a coup de lecture disque. Le reveil de liberation
+   *  (`release`) re-evalue les echeances quand le verrou saute.
    *  Retourne le delai retenu (null : aucune tache a armer), pour test. */
   arm(): number | null {
     this.stopTimer();
@@ -133,6 +142,7 @@ export class Scheduler {
     let earliest: number | null = null;
     for (const task of tasks) {
       if (!task.enabled || !task.schedule) continue;
+      if (this.busy.has(task.id)) continue;
       const due = this.dueMs(task);
       if (due === null) continue;
       if (earliest === null || due < earliest) earliest = due;
@@ -239,6 +249,17 @@ export class Scheduler {
     this.arm();
   }
 
+  /** Libere le verrou d'une tache puis re-evalue les echeances.
+   *  Sans ce reveil, une occurrence devenue due pendant l'execution
+   *  (`triggerNow` / `runNow` n'avancent pas le calendrier) resterait due sur
+   *  disque en panne depuis que `arm()` ignore les taches busy. Le
+   *  rattrapage reste unique : le premier reveil avance `nextRunAt`, le
+   *  suivant ne trouve plus rien a lancer. */
+  private release(id: string): void {
+    this.busy.delete(id);
+    this.wake();
+  }
+
   /** Declenchement manuel DETACHE : pre-controles synchrones (tache connue,
    *  aucune execution en cours), puis execution en arriere-plan. Le serveur
    *  stdio reste disponible pour les autres requetes ; le resultat se lit
@@ -257,7 +278,7 @@ export class Scheduler {
         // non capte qui tuerait le serveur.
       })
       .finally(() => {
-        this.busy.delete(task.id);
+        this.release(task.id);
       });
     return { ok: true };
   }
@@ -275,7 +296,7 @@ export class Scheduler {
     } catch (error) {
       return { ok: false, reason: error instanceof Error ? error.message : String(error) };
     } finally {
-      this.busy.delete(task.id);
+      this.release(task.id);
     }
   }
 
@@ -300,7 +321,7 @@ export class Scheduler {
         .then(() => runOne(index + 1));
     };
     void runOne(0).finally(() => {
-      this.busy.delete(task.id);
+      this.release(task.id);
     });
   }
 

package/novahiz.config.example.json

@@ -19,17 +19,5 @@
     "autoRegister": true,
     "autoInstall": true,
     "disabled": []
-  },
-  "tokens": {
-    "enabled": true,
-    "trimOutputs": true,
-    "maxOutputBytes": 40000,
-    "keepHeadLines": 120,
-    "keepTailLines": 40,
-    "keepErrorLines": 40,
-    "dedupeReads": true,
-    "capOutputTokens": 0,
-    "trimTools": ["read", "bash", "shell"],
-    "readTools": ["read"]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novahiz",
-  "version": "0.5.1",
+  "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.