raptor-aios 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-06-21
+
+### Fixed
+
+- **Correções do code-review xhigh do épico de fidelidade visual.** `gate.design.fidelity`
+  resiliente a race (`readFileSync`/`statSync` não crasham mais) e com contenção de
+  evidência à prova de symlink (`realpathSync`); duplicata de screenshot comparada por
+  path resolvido. Parser do scorecard mais estrito: divergência com enum inválido e
+  região sem `id` são **descartadas** (em vez de retornar objeto com tipo inválido).
+  `token-diff` normaliza hex de 4 dígitos (`#rgba`). Scripts `hex-scan`/`screenshot.sh`
+  validam argumentos (sem crash de `shift`; resolução do core com mensagem clara). Doc:
+  diagrama Mermaid corrigido (linter havia transformado arestas em tabela).
+
 ## [0.14.0] - 2026-06-21
 
 ### Added

package/README.md

@@ -7,8 +7,8 @@
 [![npm](https://img.shields.io/npm/v/raptor-aios?color=ef4444&label=raptor-aios&logo=npm)](https://www.npmjs.com/package/raptor-aios)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3c873a?logo=node.js&logoColor=white)](https://nodejs.org)
 [![platform](https://img.shields.io/badge/target-React%20Native-61dafb?logo=react&logoColor=black)](https://reactnative.dev)
-[![tests](https://img.shields.io/badge/tests-1374%20passing-22c55e)](#️-desenvolvimento-local)
-[![version](https://img.shields.io/badge/version-0.13.0-ef4444)](CHANGELOG.md)
+[![tests](https://img.shields.io/badge/tests-1481%20passing-22c55e)](#️-desenvolvimento-local)
+[![version](https://img.shields.io/badge/version-0.14.0-ef4444)](CHANGELOG.md)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
@@ -40,6 +40,7 @@ raptor new login-biometrico -d "Permitir login com Face ID / digital"
 - [📱 Fluxo correto com React Native](#-fluxo-correto-com-react-native)
 - [🛡️ Gates: o que bloqueia o quê](#️-gates-o-que-bloqueia-o-quê)
 - [🔬 A ponta de verificação (`verify`)](#-a-ponta-de-verificação-verify)
+- [🎯 Fidelidade visual (Figma → React Native)](#-fidelidade-visual-figma--react-native)
 - [🧰 Capacidades do Raptor](#-capacidades-do-raptor)
 - [📖 Referência de comandos CLI](#-referência-de-comandos-cli)
 - [🗂️ Estrutura criada no projeto](#️-estrutura-criada-no-projeto)
@@ -61,6 +62,7 @@ O Raptor leva o SDD a sério para o mundo mobile, adicionando o que falta para u
 | 📜 **Trilha de auditoria**              | Cada passo emite eventos em `audit.jsonl`, validáveis contra um JSON Schema canônico.                                                                                   |
 | 🔗 **Rastreabilidade código↔spec (M7)** | Cada artefato de código aponta para os critérios de aceitação que satisfaz, com evidência pareada (*code + test*).                                                      |
 | 🔬 **Verificação real**                 | `verify a11y/perf/stores/os-matrix` medem o app de verdade e comparam com o que a spec/plan declararam.                                                                 |
+| 🎯 **Fidelidade visual (Figma→RN)**      | Decompõe a tela em **anatomia**, dá **nota por micro-região** (mín. 95) e **trava o merge** via `gate.design.fidelity` até a implementação replicar o Figma. Guia: [docs/visual-fidelity-loop.md](docs/visual-fidelity-loop.md). |
 | 🤖 **Agnóstico de agente**              | Materializa slash commands para Claude Code, Cursor, Copilot, Codex, Gemini e Antigravity.                                                                              |
 | ✨ **Specs sem pontas soltas**          | A spec nasce preenchida (defaults informados), com teto de 3 dúvidas de alto impacto, e um `/raptor-clarify` investigativo que caça lacunas antes do planejamento.      |
 | 🌿 **Branch & commit sob controle**     | Cada feature ganha sua branch (`feat/001-…`) automaticamente, e hooks *warn-only* alertam sobre arquivos sensíveis ou fora do contexto — sem travar seu fluxo git.      |
@@ -461,6 +463,41 @@ Declarar não é cumprir. O Raptor **mede** e compara com o declarado:
 
 ---
 
+## 🎯 Fidelidade visual (Figma → React Native)
+
+> **Novo na v0.14.0.** Transforma _"a tela tem os tokens"_ em _"a tela **replica** o Figma"_.
+
+<p align="center"><img src="docs/assets/visual-fidelity-loop.svg" alt="Visual Fidelity Loop — anatomia, loop de fidelidade e gate" width="760"></p>
+
+Capturar o design não garante fidelidade. O Raptor decompõe cada tela em **anatomia**
+(regiões → elementos amarrados a token), pontua cada **micro-região de 60 a 100** (mínimo
+**95**) e **trava o `verify`** via `gate.design.fidelity` até a implementação replicar o
+protótipo — com um **backbone determinístico** (hex / `rgb()` / token + screenshots de
+evidência) que o Raptor mede sozinho, então o agente **não consegue inflar a nota**.
+
+```bash
+raptor design fidelity 001-home   # driver do loop: reporta a fidelidade + emite o prompt do scorer
+raptor verify fidelity 001-home   # lente read-only: nota por micro-região (60–100, mín. 95)
+raptor verify 001-home            # gate.design.fidelity (estático) trava se alguma região < mínimo
+```
+
+```
+=== fidelity: 001-home ===
+  ✅ home-unavailable [unavailable] header: 97/95
+  ✅ home-unavailable [unavailable] earnings-card: 99/95
+  ✅ home-unavailable [unavailable] status-component: 98/95
+  Summary: 5 region(s) scored — 5 pass, 0 fail.
+```
+
+O agente `design-fidelity` (read-only, _"na dúvida, reprova"_) é acionado **depois do
+implement**: extrai os valores reais do Figma, captura o app rodando, pontua cada
+micro-região e escreve `design/visual-review/<slug>.fidelity.json`. O gate **estático** lê
+esse scorecard (como os gates M7 leem `impl-log.md`) e nunca roda o app.
+
+> 📖 **Guia completo** — use cases, workflow, exemplos e diagramas: [docs/visual-fidelity-loop.md](docs/visual-fidelity-loop.md).
+
+---
+
 ## 🧰 Capacidades do Raptor
 
 |       Capacidade        |                                           Para que serve                                           |                         Comandos                         |
@@ -498,17 +535,7 @@ raptor design sync home             # re-captura idempotente (nunca sobrescreve
 
 O provider **`figma-rest`** usa a REST API da Figma com um PAT (`${FIGMA_TOKEN}` no `raptor.yml`), é determinístico e roda em CI. A captura gera `design/tokens.json` (colors/typography/spacing/radii), `design/screens/<slug>.md` (frames de topo) e `design/assets-manifest.json` (assets baixados com SHA-256, guarda anti-SSRF). Quando há captura real, os prompts fazem o **flip REDISTRIBUIR**: o agente passa a *refinar e redistribuir* os artefatos em disco em vez de "olhar o Figma" — cobrado pelo `gate.design.ready`.
 
-#### 🎯 Loop de fidelidade visual (Figma → React Native)
-
-Para garantir que a tela implementada **replica o Figma** (e não só "tem os tokens"), o Raptor adota anatomia + nota por micro-região:
-
-```bash
-raptor design fidelity home-entregador   # driver do loop: reporta a fidelidade e emite o prompt do scorer
-raptor verify fidelity home-entregador   # lente read-only: nota por micro-região (60–100, mín. 95)
-raptor verify home-entregador            # gate.design.fidelity (estático) trava se alguma região < mínimo
-```
-
-Cada tela ganha uma seção `## Anatomy` em `design/screens/<slug>.md` (regiões→elementos amarrados a token) — o **contrato** de fidelidade. O agente `design-fidelity` (read-only, adversarial — "na dúvida, reprova") extrai os valores reais do Figma, captura o app rodando (`scripts/app/screenshot.sh`), pontua cada micro-região e escreve `design/visual-review/<slug>.fidelity.json` (schema `raptor.fidelity/v1`). O **backbone determinístico** que o Raptor mede sozinho — hex hardcoded (`scripts/review/hex-scan.mjs`), drift de token (`scripts/review/diff-tokens.mjs`), screenshots de evidência — impede inflar a nota. O `gate.design.fidelity` é **estático** (lê o scorecard, nunca roda o app), como os gates M7 leem o `impl-log.md`. Detalhes: [docs/visual-fidelity-loop.md](docs/visual-fidelity-loop.md).
+> 🎯 **Fidelidade visual:** depois do `implement`, um loop garante que a tela **replica** o Figma (anatomia + nota por micro-região + `gate.design.fidelity`) — veja [🎯 Fidelidade visual (Figma → React Native)](#-fidelidade-visual-figma--react-native).
 
 > 📖 Detalhes, providers e limitações: [docs/design-figma-sync.md](docs/design-figma-sync.md) e [docs/design-gate.md](docs/design-gate.md).
 

package/dist/_core/dist/design/anatomy.js

@@ -4,8 +4,11 @@ const REGION_PREFIX = /^(?:region|regi[aã]o)\s*:\s*(.+)$/i;
 const DELIM = /\s+[—–-]\s+|\s*:\s+/;
 function splitHead(text) {
     const m = DELIM.exec(text);
-    if (!m || m.index <= 0)
+    if (!m)
         return { head: text.trim() };
+    if (m.index <= 0) {
+        return { head: "", tail: text.slice(m.index + m[0].length).trim() || undefined };
+    }
     return {
         head: text.slice(0, m.index).trim(),
         tail: text.slice(m.index + m[0].length).trim() || undefined,

package/dist/_core/dist/design/fidelity.js

@@ -22,18 +22,24 @@ function validateDivergence(d, label, problems) {
         problems.push(`${label}: divergence must be an object`);
         return null;
     }
+    let valid = true;
     const dim = d["dimension"];
     if (typeof dim !== "string" || !FIDELITY_DIMENSIONS.includes(dim)) {
         problems.push(`${label}: divergence "dimension" must be one of ${FIDELITY_DIMENSIONS.join("|")}`);
+        valid = false;
     }
     const sev = d["severity"];
     if (typeof sev !== "string" || !DIVERGENCE_SEVERITIES.includes(sev)) {
         problems.push(`${label}: divergence "severity" must be one of ${DIVERGENCE_SEVERITIES.join("|")}`);
+        valid = false;
     }
     const status = d["status"];
     if (typeof status !== "string" || !DIVERGENCE_STATUSES.includes(status)) {
         problems.push(`${label}: divergence "status" must be one of ${DIVERGENCE_STATUSES.join("|")}`);
+        valid = false;
     }
+    if (!valid)
+        return null;
     return {
         dimension: dim,
         figma: typeof d["figma"] === "string" ? d["figma"] : "",
@@ -51,6 +57,7 @@ function validateRegion(r, label, problems) {
     const id = r["id"];
     if (typeof id !== "string" || !id.trim()) {
         problems.push(`${label}: missing "id"`);
+        return null;
     }
     if (!isScore(r["score"])) {
         problems.push(`${label}: "score" must be a number 0–100`);
@@ -90,7 +97,7 @@ function validateRegion(r, label, problems) {
         }
     }
     return {
-        id: typeof id === "string" ? id : "",
+        id,
         ...(typeof r["label"] === "string" ? { label: r["label"] } : {}),
         score: isScore(r["score"]) ? r["score"] : 0,
         ...(dimensions ? { dimensions } : {}),

package/dist/_core/dist/design/token-diff.js

@@ -1,8 +1,10 @@
 import { slugify } from "./slug.js";
 function normColor(v) {
     const s = v.trim().toUpperCase();
-    const m = /^#([0-9A-F])([0-9A-F])([0-9A-F])$/.exec(s);
-    return m ? `#${m[1]}${m[1]}${m[2]}${m[2]}${m[3]}${m[3]}` : s;
+    const m = /^#([0-9A-F])([0-9A-F])([0-9A-F])([0-9A-F])?$/.exec(s);
+    if (!m)
+        return s;
+    return "#" + m.slice(1).filter(Boolean).map((c) => c + c).join("");
 }
 function normDim(v) {
     return v.trim().replace(/px$/i, "").trim();

package/dist/_core/dist/gates/design-gates.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { parseSpec } from "../models/spec.js";
 import { parseTasks } from "../models/tasks.js";
@@ -185,6 +185,12 @@ export const gateDesignFidelity = {
         }
         const reviewDir = join(designDir, "visual-review");
         const featureRoot = resolve(featureDir);
+        let featureRealRoot = featureRoot;
+        try {
+            featureRealRoot = realpathSync(featureRoot);
+        }
+        catch {
+        }
         const problems = [];
         const warnings = [];
         let anatomyScreens = 0;
@@ -197,7 +203,14 @@ export const gateDesignFidelity = {
         }
         for (const file of screenFiles) {
             const slug = slugify(file.slice(0, -3));
-            const { regions: anatomy, problems: anatomyProblems } = parseAnatomy(readFileSync(join(screensDir, file), "utf8"));
+            let screenContent;
+            try {
+                screenContent = readFileSync(join(screensDir, file), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const { regions: anatomy, problems: anatomyProblems } = parseAnatomy(screenContent);
             if (anatomyProblems.some((p) => /no `## Anatomy` section/.test(p)))
                 continue;
             anatomyScreens++;
@@ -246,15 +259,27 @@ export const gateDesignFidelity = {
                         problems.push(`${slug} [${st.state}]: ${kind} screenshot ${shot} escapes the feature directory`);
                         continue;
                     }
-                    if (!existsSync(abs)) {
-                        problems.push(`${slug} [${st.state}]: ${kind} screenshot ${shot} not found on disk`);
-                        continue;
+                    try {
+                        if (!existsSync(abs)) {
+                            problems.push(`${slug} [${st.state}]: ${kind} screenshot ${shot} not found on disk`);
+                            continue;
+                        }
+                        const real = realpathSync(abs);
+                        if (real !== featureRealRoot && !real.startsWith(featureRealRoot + sep)) {
+                            problems.push(`${slug} [${st.state}]: ${kind} screenshot ${shot} escapes the feature directory`);
+                            continue;
+                        }
+                        if (statSync(real).size < MIN_SCREENSHOT_BYTES) {
+                            problems.push(`${slug} [${st.state}]: ${kind} screenshot ${shot} is too small to be real evidence (<${MIN_SCREENSHOT_BYTES}B)`);
+                        }
                     }
-                    if (statSync(abs).size < MIN_SCREENSHOT_BYTES) {
-                        problems.push(`${slug} [${st.state}]: ${kind} screenshot ${shot} is too small to be real evidence (<${MIN_SCREENSHOT_BYTES}B)`);
+                    catch {
+                        problems.push(`${slug} [${st.state}]: ${kind} screenshot ${shot} is not readable`);
                     }
                 }
-                if (pair.figma && pair.app && normalizePath(pair.figma) === normalizePath(pair.app)) {
+                if (pair.figma &&
+                    pair.app &&
+                    resolve(featureRoot, normalizePath(pair.figma)) === resolve(featureRoot, normalizePath(pair.app))) {
                     problems.push(`${slug} [${st.state}]: figma and app screenshots are the same file (illusory evidence)`);
                 }
             }

package/dist/_core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raptor/core",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "main": "dist/index.js"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raptor-aios",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Raptor — Spec-Driven Development (SDD) CLI for modern mobile apps. Constitutional gates, audit trail, real verification (a11y/perf/stores/OS matrix), and AI-agent slash commands.",
   "type": "module",
   "bin": {

package/scripts/app/screenshot.sh

@@ -16,8 +16,12 @@ DEVICE=""
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    --platform) PLATFORM="${2:-}"; shift 2 ;;
-    --device)   DEVICE="${2:-}"; shift 2 ;;
+    --platform)
+      [ $# -ge 2 ] || { echo "error: --platform needs a value (ios|android)" >&2; exit 2; }
+      PLATFORM="$2"; shift 2 ;;
+    --device)
+      [ $# -ge 2 ] || { echo "error: --device needs a value" >&2; exit 2; }
+      DEVICE="$2"; shift 2 ;;
     -h|--help)
       sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'
       exit 0 ;;

package/scripts/prepare-npm.mjs

@@ -29,7 +29,7 @@ const CLI = join(ROOT, "packages", "cli");
 const CORE = join(ROOT, "packages", "core");
 const OUT = join(ROOT, "build", "npm");
 
-const VERSION = "0.14.0";
+const VERSION = "0.14.1";
 
 function log(msg) {
   process.stdout.write(`  ${msg}\n`);

package/scripts/review/hex-scan.mjs

@@ -23,7 +23,11 @@ function resolveCore() {
     resolve(HERE, "..", "..", "packages", "core", "dist", "index.js"),
     resolve(HERE, "..", "..", "dist", "_core", "dist", "index.js"),
   ];
-  return candidates.find((c) => existsSync(c)) ?? candidates[0];
+  const found = candidates.find((c) => existsSync(c));
+  if (!found) {
+    die(`@raptor/core build not found — run \`pnpm -r build\` (monorepo) or reinstall raptor-aios. Tried:\n  ${candidates.join("\n  ")}`, 2);
+  }
+  return found;
 }
 const { scanHardcodedHex, hexFindingsToScorecard } = await import(resolveCore());
 
@@ -40,7 +44,7 @@ for (let i = 0; i < argv.length; i++) {
   if (argv[i] === "--json") continue;
   if (argv[i] === "--allow") {
     const v = argv[++i];
-    if (!v) die("--allow needs a value", 2);
+    if (!v || v.startsWith("--")) die("--allow needs a value (got a flag or nothing)", 2);
     allowPaths.push(v);
   } else {
     positionals.push(argv[i]);