raptor-aios 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,98 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-06-22
+
+Tema do épico KAN-20: **determinismo e consentimento**. Tudo que antes "passava em
+silêncio", "escrevia no card sem perguntar" ou "despejava o arquivo Figma inteiro"
+agora é explícito, opt-in ou escopado por node.
+
+### Added
+
+- **`--design-scope node|file`** (em `new`, `design sync`, `design pull`). Controla o
+  escopo da captura de telas/assets. Em `new` e `design sync` o default é `node` (só o
+  frame linkado pela URL); em `design pull` o default é `file` (inspeção do arquivo
+  inteiro). `--design-scope file` é o escape hatch para o comportamento legado (arquivo
+  todo). Uma ref COM node-id captura aquele node sob qualquer scope.
+- **`raptor new --activate` / `--no-activate`.** `new` agora aponta
+  `.raptor/feature.json` para a feature recém-criada (default ligado). `--no-activate`
+  preserva a feature anterior.
+- **`--sync-jira`** (em `approve`, `implement`, `taskstoissues`). Opt-in para escrever
+  de volta no card Jira (comentário de ciclo de vida + transição; em `taskstoissues`,
+  comentário-resumo dos issues criados). Sem a flag, só loga a ação pretendida.
+- **`raptor implement --finalize`.** Reconstrói `impl-log.md` a partir dos eventos
+  `code.generated` do `audit.jsonl` quando as tasks foram fechadas sem `--task`.
+  Recupera traces de AC das tags `[AC-#]` do `tasks.md`; quando não há, deixa vazio
+  para o gate M7 cobrar (não fabrica pass). Respeita `--dry-run`.
+
+### Changed
+
+- **`--design-fetch` agora é escopo por node-id por default** (era arquivo inteiro,
+  até 107 telas). Card sem node-id pula a captura com aviso acionável; a spec referencia
+  `assets-manifest.json` em vez de listar tudo. **Migração:** use `--design-scope file`
+  para o comportamento antigo.
+- **`raptor new` ativa a feature criada por default.** `feature.json` é dobrado no
+  auto-commit para empilhar specs sem sujar a árvore. **Migração:** use `--no-activate`
+  se contava com a feature anterior continuar ativa.
+- **Escrita no Jira é opt-in (`--sync-jira`)** em `approve`/`implement`/`taskstoissues`.
+  **Migração:** pipelines que esperavam status-sync automático precisam adicionar a flag.
+- **`gate.design.fidelity` bloqueia por scorecards.** Avalia scorecards sempre que
+  existirem; retorna `skipped` (nunca mais `pass` falso) só quando não há scorecards
+  nem impl-log. **Migração:** projetos cujo fidelity passava verde sem evidência podem
+  ver o gate bloquear agora.
+- **Gates M7 falham (não skipam) quando há tasks concluídas mas falta `impl-log.md`.**
+  Sem tasks concluídas continua `skipped`. A skill `/raptor-implement` foi reescrita
+  para registrar cada task via `raptor implement --task`.
+- **Namespace de specs unificado em `.raptor/specs`.** `get_next_feature_number` deixa
+  de saltar numeração por varrer `specs/` legado (002 → 011); legado vira só fallback
+  de leitura. Espelhado no PowerShell.
+- **`branch_prefix` removido do schema/`raptor.yml`** (dead config, 0 leituras).
+  **Migração:** pode remover do `raptor.yml` — não tinha efeito.
+- **stderr do MCP silenciado por default** (`StdioClientTransport` usa `stderr:'ignore'`).
+  Reative diagnóstico com `RAPTOR_MCP_DEBUG=1`.
+- **Assets do fetch isolados com `.gitignore` RAPTOR-managed + guarda de colisão** —
+  binários baixados não entram em versionamento por acidente; a captura nunca
+  sobrescreve arte já versionada.
+
+### Fixed
+
+- **Falso negativo de cobertura de US eliminado** — `gate.spec.ready` normaliza IDs:
+  header `US-001` casa com `[US1]`.
+- **Markers falsos não acusam mais** — detector ignora code-spans (`` `[PREENCHER]` ``)
+  e linhas de checklist negadoras; helper compartilhado em spec/plan/tasks.ready.
+- **Checklist sem ID conta corretamente** — parser conta itens `[x]` mesmo sem `CK-#`
+  (contido em `status`; gates estruturados inalterados).
+- **Path in-place no redesign** — `gate.tasks.ready` herda path por fase; reset por
+  heading preserva detecção de drift.
+- **Hash stale agora orienta a correção** — `gate.plan/tasks.input_hash` sugere
+  `raptor resync <feature> --artifact plan|tasks`.
+- **`clarify --apply` popula `## Clarifications`** (upsert das Q&A; CLI é dono único,
+  skill só produz `answers.json`), preserva frontmatter e não mascara marker real.
+- **Wiki-markup do Jira → Markdown no seeding** — `flattenAdf` converte `{quote}`,
+  `{{...}}`, `||tabela||`, `hN.`, `{code}`/`{noformat}`, gateado por detecção de wiki
+  (não toca Markdown existente; preserva `5 * 4`).
+- **Ator canônico único no audit** — `currentActor` fixa o `user` no `git user.email`
+  (fallback name → `USER`).
+- **`HAS_GIT` correto no `--dry-run`** — `create-new-feature.sh` detecta git antes da
+  bifurcação dry-run. Skill `specify` passa `--short-name` (slug kebab-case).
+- **Robustez do seeding de design** — tokens vazios direcionam ao MCP `get_variable_defs`
+  e o gate bloqueia `tokens.json` vazio (`radii` sempre presente); `gate.design.ready`
+  casa telas por `name` do frontmatter (tolerante a sufixo node-id); `design sync`
+  avisa (não apaga) telas órfãs da convenção antiga de slug.
+
+## [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-1597%20passing-22c55e)](#️-desenvolvimento-local)
+[![version](https://img.shields.io/badge/version-0.15.0-ef4444)](CHANGELOG.md)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
@@ -24,7 +24,7 @@ npm install -g raptor-aios
 cd meu-app-react-native
 raptor setup        # 🧭 assistente guiado: IA/IDE, preset, Jira/Figma (ou 'raptor init' direto)
 raptor new login-biometrico -d "Permitir login com Face ID / digital"
-#  → cria a feature E já troca para a branch feat/001-login-biometrico
+#  → cria a feature, forka a branch feat/001-login-biometrico do HEAD e a ativa
 ```
 
 ---
@@ -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.      |
@@ -199,7 +201,7 @@ Isolamento e coerência **sem configurar nada** — o `init` já deixa tudo pron
 
 ### Uma branch por unidade de trabalho
 
-`raptor new` cria e troca para a branch certa, sempre ramificando de `main`:
+`raptor new` cria e troca para a branch certa, **forkando do HEAD atual** (modelo empilhado, não de `main`): cada nova feature ramifica de onde você está, então specs se **empilham** umas sobre as outras. Ao final, a feature recém-criada vira a **ativa** em `.raptor/feature.json` (comandos seguintes a resolvem sem `--feature`); use `--no-activate` para manter a feature anterior ativa (`--activate` é o default).
 
 |               Você roda                |                    Branch criada                    |
 | -------------------------------------- | --------------------------------------------------- |
@@ -208,7 +210,7 @@ Isolamento e coerência **sem configurar nada** — o `init` já deixa tudo pron
 | `raptor new refactor-auth --kind=debt` | `debt/003-refactor-auth`                            |
 | `raptor new login --jira APP-1234`     | `feat/004-login.app-1234` *(tipo inferido do Jira)* |
 
-Numeração sequencial global, prefixo por tipo (`feat`/`bugfix`/`debt`), e a chave do Jira no fim quando houver. Já vem ligado (`git.branch_per_feature`); desligue com `--no-branch` num comando ou `no_git` no projeto.
+Numeração sequencial global, prefixo por tipo (`feat`/`bugfix`/`debt`), e a chave do Jira no fim quando houver. Já vem ligado (`git.branch_per_feature`); desligue com `--no-branch` num comando ou `no_git` no projeto. Por padrão a spec scaffoldada é **commitada** na própria branch (para o próximo `raptor new` empilhar em cima); `--no-commit` deixa a spec sem commit.
 
 ### Commits coerentes, sem travar seu fluxo
 
@@ -269,9 +271,11 @@ Gera checklists de qualidade temáticos (code quality, testes, segurança, perfo
 
 Executa as tarefas em ordem de fase, respeitando paralelização e (se exigido) TDD. Marca cada tarefa `[x]` ao concluir e registra a **evidência M7** (qual arquivo cobre qual critério de aceitação).
 
+> ⚠️ **`impl-log.md` é inegociável.** Cada `raptor implement --task <id> --files … --acceptance …` atualiza o `impl-log.md` com as execuções, artefatos e traces. Se ele estiver **ausente após a implementação**, os gates M7 **bloqueiam** o `verify` (deixam de "pular" por arquivo inexistente e passam a falhar). Se o agente esqueceu de registrar tarefa por tarefa via `--task`, rode `raptor implement <feat> --finalize` para **reconstruir** o `impl-log.md` a partir dos eventos `code.generated` do `audit.jsonl` — traces de aceitação ausentes ficam vazios para o gate M7 cobrar (complete-os com `--amend --acceptance <AC-#>`).
+
 ### 🎫 `/raptor-taskstoissues`
 
-Converte as tarefas em issues de um tracker (GitHub via MCP, Jira via integração).
+Converte as tarefas em issues de um tracker (GitHub via MCP, Jira via integração). Criar as issues é o propósito do comando, mas **escrever de volta no card pai** (comentário de resumo) é **opt-in via `--sync-jira`** — sem a flag, nada é mutado no ticket de origem.
 
 ### 🌿 `/raptor-commit-review`
 
@@ -461,6 +465,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                         |
@@ -484,6 +523,8 @@ raptor jira pull APP-1234           # importa a issue
 raptor new login --jira APP-1234    # semeia a spec a partir da issue
 ```
 
+> 🔒 **Escrita no Jira é opt-in.** O `raptor new --jira` só **lê** o card. Os comandos do ciclo que poderiam escrever de volta no ticket de origem (`approve`, `implement`, `taskstoissues`) **só mutam o Jira** — comentário de lifecycle e transição opcional — quando você passa **`--sync-jira`**. Sem a flag, o Raptor apenas anuncia o que faria.
+
 > 📖 Como o card é capturado **por inteiro** (campos ricos, links de Figma) e redistribuído na spec — com os gates cobrando: veja [docs/jira-spec-enrichment.md](docs/jira-spec-enrichment.md).
 
 ### 🎨 Integração com Figma (design determinístico)
@@ -498,17 +539,9 @@ 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
-```
+A captura no `raptor new` é **opt-in via `--design-fetch`** (default ligado): com o Figma conectado, ela puxa tokens/telas/assets e semeia `design/`; com `--no-design-fetch` apenas scaffolda o link, sem buscar. O **escopo** é controlado por `--design-scope`: `node` (default) captura **só o frame linkado** (o node-id na URL); `file` é uma escotilha de fuga que puxa o **arquivo Figma inteiro** (comportamento legado). O mesmo `--design-scope` vale para `raptor design sync`.
 
-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).
 
@@ -530,7 +563,7 @@ Cada tela ganha uma seção `## Anatomy` em `design/screens/<slug>.md` (regiões
 🎨 Figma/Design  design connect · status · pull · sync · disconnect
 ```
 
-Rode `raptor <comando> --help` para os detalhes (flags, exemplos) de cada um.
+Rode `raptor <comando> --help` para os detalhes (flags, exemplos) de cada um, ou veja a **[📖 Referência de flags (docs/cli-reference.md)](docs/cli-reference.md)** — flags relevantes e novas da v0.15.0, por comando, com defaults.
 
 ### 💬 Quando você erra um comando
 
@@ -595,6 +628,7 @@ Comece pelo **[📖 Glossário Canônico](docs/glossary.md)** — a referência
 |                             Documento                              |                                       Sobre                                        |
 | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
 | **[📖 docs/glossary.md](docs/glossary.md)**                         | Glossário canônico: conceitos, hierarquias, catálogo de 48 gates e de comandos CLI |
+| [📖 docs/cli-reference.md](docs/cli-reference.md)                   | Referência de flags por comando (novas/relevantes da v0.15.0) com defaults         |
 | [🧭 docs/setup-wizard.md](docs/setup-wizard.md)                     | Assistente de instalação `raptor setup`: onboarding, IA/IDE, preset, Jira/Figma    |
 | [🛡️ docs/readiness-gates.md](docs/readiness-gates.md)              | Gates de prontidão (`spec/plan/tasks.ready`) em detalhe                            |
 | [🎨 docs/design-figma-sync.md](docs/design-figma-sync.md)           | Captura determinística do Figma (`figma-rest`): tokens/telas/assets/fontes + flip REDISTRIBUIR |

package/dist/_core/dist/agents/prompt-builder.js

@@ -158,6 +158,9 @@ const PHASE_MAP = {
             "6. Se a feature tiver design (pasta `design/`): consuma os assets já catalogados em",
             "   `design/assets-manifest.json` (baixados em `assets/{images,icons,fonts}`) e baixe via",
             "   Figma MCP só o que faltar; referencie por caminho concreto (tags `[screen: X]` / `[asset: X]`).",
+            "7. PRESERVE o frontmatter existente de `tasks.md` ao reescrevê-lo — em especial o",
+            "   campo `plan_hash` (e qualquer outro já presente). NÃO o remova nem o reescreva:",
+            "   o gate de staleness o usa para detectar `tasks.md` desatualizado. (NÃO NEGOCIÁVEL)",
         ].join("\n"),
     },
     implement: {
@@ -215,6 +218,13 @@ const PHASE_MAP = {
             "",
             "### Saída esperada:",
             'Um arquivo JSON contendo um array de objetos `{ "label": string, "answer": string }`.',
+            "",
+            "### Regras de escrita (NÃO NEGOCIÁVEL):",
+            "1. Produza APENAS `answers.json`. NÃO edite `spec.md` — nem a seção",
+            "   `## Clarifications` nem os marcadores inline.",
+            "2. A escrita no spec é determinística e exclusiva do CLI (`raptor clarify --apply`):",
+            "   ele resolve os marcadores e popula `## Clarifications` a partir do seu `answers.json`.",
+            "   Editar o spec aqui causaria dupla-escrita e regrediria o determinismo.",
         ].join("\n"),
     },
     analyze: {

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/asset-normalize.js

@@ -7,6 +7,7 @@ export function normalizeImagesToAssets(renders, fills, opts = {}) {
     const renderType = classifyAssetType(fmt);
     const renderExt = extForFormat(fmt);
     const renderDir = assetDirFor(renderType);
+    const screen = opts.screen?.trim() ? opts.screen.trim() : undefined;
     for (const [nodeId, url] of Object.entries(renders)) {
         if (!url)
             continue;
@@ -18,7 +19,14 @@ export function normalizeImagesToAssets(renders, fills, opts = {}) {
             path = `${renderDir}/${base}.${renderExt}`;
         }
         seen.add(path);
-        out.push({ name: human || base, type: renderType, path, url, figma_node_id: nodeId });
+        out.push({
+            name: human || base,
+            type: renderType,
+            path,
+            url,
+            figma_node_id: nodeId,
+            ...(screen ? { screen } : {}),
+        });
     }
     for (const [ref, url] of Object.entries(fills)) {
         if (!url)
@@ -31,7 +39,7 @@ export function normalizeImagesToAssets(renders, fills, opts = {}) {
             path = `assets/images/${base}.${ext}`;
         }
         seen.add(path);
-        out.push({ name: base, type: "image", path, url });
+        out.push({ name: base, type: "image", path, url, ...(screen ? { screen } : {}) });
     }
     return out;
 }

package/dist/_core/dist/design/downloader.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -64,16 +65,31 @@ export async function downloadAll(pending, root, opts = {}) {
                 if (isAbsolute(rel) || (within !== rootAbs && !within.startsWith(rootAbs + sep))) {
                     throw new DownloadError(`asset path escapes project root: ${a.path}`, 0);
                 }
+                if (isGitTracked(rootAbs, rel)) {
+                    const w = `asset "${a.name}" colidiria com arquivo versionado ${rel} — não sobrescrito`;
+                    if (opts.onWarn)
+                        opts.onWarn(w);
+                    else
+                        process.stderr.write(`Warning: ${w}\n`);
+                    results[i] = { ...base, status: "pending" };
+                    continue;
+                }
                 const destAbs = join(root, rel);
                 const { hash } = await downloadAsset(a.url, destAbs, opts);
                 results[i] = { ...base, hash, status: "downloaded" };
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
+                const where = assetWhere(a);
+                const oversized = err instanceof DownloadError && /exceeds max_bytes/.test(msg);
+                const advice = oversized
+                    ? " — pending, fora do manifest; eleve design.assets.max_bytes ou rebaixe via MCP"
+                    : "";
+                const line = `asset "${a.name}"${where} not downloaded: ${msg}${advice}`;
                 if (opts.onWarn)
-                    opts.onWarn(`asset "${a.name}" not downloaded: ${msg}`);
+                    opts.onWarn(line);
                 else
-                    process.stderr.write(`Warning: asset "${a.name}" not downloaded: ${msg}\n`);
+                    process.stderr.write(`Warning: ${line}\n`);
                 results[i] = { ...base, status: "pending" };
             }
         }
@@ -81,6 +97,26 @@ export async function downloadAll(pending, root, opts = {}) {
     await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, worker));
     return results;
 }
+function isGitTracked(rootAbs, rel) {
+    try {
+        const r = spawnSync("git", ["ls-files", "--error-unmatch", "--", rel], {
+            cwd: rootAbs,
+            stdio: "ignore",
+        });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function assetWhere(a) {
+    const parts = [];
+    if (a.screen)
+        parts.push(`screen: ${a.screen}`);
+    if (a.figma_node_id)
+        parts.push(`node ${a.figma_node_id}`);
+    return parts.length ? ` (${parts.join(", ")})` : "";
+}
 function assertSafeAssetUrl(url, allowHttp) {
     let u;
     try {

package/dist/_core/dist/design/fetcher.js

@@ -6,6 +6,16 @@ function warn(opts, message) {
     else
         process.stderr.write(`Warning: ${message}\n`);
 }
+function scopeSkipWarning(url) {
+    return (`ref sem node-id (link sem ?node-id=); telas/assets não capturados — ` +
+        `rode com --design-scope file para o arquivo inteiro, ou linke o frame no card: ${url}`);
+}
+function warnOnce(opts, seen, url) {
+    if (seen.has(url))
+        return;
+    seen.add(url);
+    warn(opts, scopeSkipWarning(url));
+}
 export async function fetchDesignData(refs, client, opts = {}) {
     const varMap = {};
     for (const ref of refs) {
@@ -30,10 +40,11 @@ export async function fetchDesignData(refs, client, opts = {}) {
         }
     }
     const tokens = normalizeVariablesToTokens(varMap, opts.source);
-    const screens = await captureScreens(refs, client, opts);
+    const scopeWarned = new Set();
+    const screens = await captureScreens(refs, client, opts, scopeWarned);
     const assets = [];
     if (opts.root) {
-        assets.push(...(await captureAssets(refs, client, tokens.typography, opts)));
+        assets.push(...(await captureAssets(refs, client, tokens.typography, opts, scopeWarned)));
     }
     return {
         tokens,
@@ -42,12 +53,17 @@ export async function fetchDesignData(refs, client, opts = {}) {
         libraries: [...libraries],
     };
 }
-async function captureScreens(refs, client, opts) {
+async function captureScreens(refs, client, opts, scopeWarned) {
     if (!client.captureScreens)
         return [];
+    const scope = opts.scope ?? "node";
     const out = [];
     const seen = new Set();
     for (const ref of refs) {
+        if (scope === "node" && !ref.nodeId) {
+            warnOnce(opts, scopeWarned, ref.url);
+            continue;
+        }
         try {
             for (const s of await client.captureScreens(ref.fileKey, ref.nodeId)) {
                 const key = s.nodeId
@@ -65,7 +81,7 @@ async function captureScreens(refs, client, opts) {
     }
     return out;
 }
-async function captureAssets(refs, client, typography, opts) {
+async function captureAssets(refs, client, typography, opts, scopeWarned) {
     const root = opts.root;
     const format = opts.assets?.format ?? "svg";
     const scale = opts.assets?.scale ?? 2;
@@ -73,8 +89,13 @@ async function captureAssets(refs, client, typography, opts) {
     const fetchImpl = opts.deps?.fetchImpl;
     const pending = [];
     const seenPaths = new Set();
+    const scope = opts.scope ?? "node";
     if (client.captureAssets) {
         for (const ref of refs) {
+            if (scope === "node" && !ref.nodeId) {
+                warnOnce(opts, scopeWarned, ref.url);
+                continue;
+            }
             try {
                 const found = await client.captureAssets(ref.fileKey, ref.nodeId, { format, scale });
                 for (const p of found) {
@@ -100,8 +121,15 @@ async function captureAssets(refs, client, typography, opts) {
         for (const e of entries) {
             if (e.status === "downloaded")
                 out.push(e);
-            else
-                warn(opts, `asset "${e.name}" could not be downloaded — left pending (not catalogued)`);
+            else {
+                const where = [
+                    e.screen ? `screen: ${e.screen}` : "",
+                    e.figma_node_id ? `node ${e.figma_node_id}` : "",
+                ]
+                    .filter(Boolean)
+                    .join(", ");
+                warn(opts, `asset "${e.name}"${where ? ` (${where})` : ""} could not be downloaded — left pending (not catalogued)`);
+            }
         }
     }
     const fontEntries = await resolveFonts(typography, {
@@ -183,9 +211,7 @@ export function normalizeVariablesToTokens(map, source) {
                 break;
         }
     }
-    const tokens = { colors, typography, spacing };
-    if (radii.length)
-        tokens.radii = radii;
+    const tokens = { colors, typography, spacing, radii };
     if (source) {
         tokens.source = {
             provider: source.provider,

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/figma-rest.js

@@ -62,6 +62,7 @@ export function makeFigmaRest(token, opts = {}) {
             const scale = assetOpts.scale ?? 2;
             let renders = {};
             let scopedRefs = null;
+            let screen;
             if (nodeId) {
                 const q = `ids=${encodeURIComponent(nodeId)}&format=${encodeURIComponent(format)}&scale=${scale}`;
                 const data = await getJson(`/v1/images/${encodeURIComponent(fileKey)}?${q}`);
@@ -70,7 +71,9 @@ export function makeFigmaRest(token, opts = {}) {
                 }
                 renders = parseImagesResponse(data);
                 try {
-                    scopedRefs = collectImageRefs(await readNodes(fileKey, nodeId));
+                    const nodesDoc = await readNodes(fileKey, nodeId);
+                    scopedRefs = collectImageRefs(nodesDoc);
+                    screen = screensFromNodes(nodesDoc, fileKey)[0]?.name;
                 }
                 catch {
                     scopedRefs = new Set();
@@ -88,7 +91,7 @@ export function makeFigmaRest(token, opts = {}) {
                 const refs = scopedRefs;
                 fills = Object.fromEntries(Object.entries(fills).filter(([ref]) => refs.has(ref)));
             }
-            return normalizeImagesToAssets(renders, fills, { format });
+            return normalizeImagesToAssets(renders, fills, { format, ...(screen ? { screen } : {}) });
         },
         async captureScreens(fileKey, nodeId) {
             if (!fileKey)

package/dist/_core/dist/design/mapper.js

@@ -1,4 +1,5 @@
 import { seededTokensCount } from "./fetcher.js";
+import { isTokensEmpty } from "./tokens.js";
 export function mapDesignToSpecContext(refs, capture) {
     const designRefs = refs.map((r) => ({
         url: r.url,
@@ -20,6 +21,7 @@ export function mapDesignToSpecContext(refs, capture) {
     return {
         ...base,
         designSeeded: true,
+        seededTokensEmpty: isTokensEmpty(t),
         seededTokensCount: seededTokensCount(t),
         seededScreens: capture.screens.map((s) => ({
             name: s.name,

package/dist/_core/dist/design/scaffold.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { isTokensEmpty, parseDesignTokens } from "./tokens.js";
 import { parseAssetManifest } from "./manifest.js";
@@ -14,6 +14,7 @@ const EMPTY_TOKENS = {
     colors: [],
     typography: [],
     spacing: [],
+    radii: [],
 };
 function writeIfMissing(path, content) {
     if (existsSync(path))
@@ -34,8 +35,11 @@ by the agent through its Figma MCP tools and enforced by \`gate.design.ready\`.
 ${links}
 
 ## Files
-- \`tokens.json\` — design tokens (colors, typography, spacing). Fill via
-  \`get_variable_defs\`.
+- \`tokens.json\` — design tokens (colors, typography, spacing, radii). Fill via
+  \`get_variable_defs\`. NOTE: the deterministic capture reads Figma *Variables*
+  (Enterprise-plan REST) and falls back to published *styles*; a file with
+  neither yields an EMPTY tokens.json — populate it via the Figma MCP
+  \`get_variable_defs\` (it can read what the REST capture could not).
 - \`screens/<name>.md\` — one file per screen, with frontmatter (name, nodeId) and
   a short spec. Create from \`get_design_context\` / \`get_screenshot\`.
 - \`assets-manifest.json\` — catalogue of every downloaded asset
@@ -77,8 +81,34 @@ export function writeDesignScaffold(featureDir, root, refs) {
             created.push(`${dir}/.gitkeep`);
         }
     }
+    if (ensureAssetGitignore(root)) {
+        created.push(".gitignore");
+    }
     return created;
 }
+const GITIGNORE_BEGIN = "# RAPTOR design assets";
+const GITIGNORE_END = "# /RAPTOR design assets";
+function ensureAssetGitignore(root) {
+    try {
+        const gitignorePath = join(root, ".gitignore");
+        const existing = existsSync(gitignorePath)
+            ? readFileSync(gitignorePath, "utf8")
+            : "";
+        if (existing.includes(GITIGNORE_BEGIN))
+            return false;
+        const lines = new Set(existing.split(/\r?\n/).map((l) => l.trim()));
+        const missing = ASSET_DIRS.filter((d) => !lines.has(d) && !lines.has(`/${d}`));
+        if (missing.length === 0)
+            return false;
+        const block = (existing.length && !existing.endsWith("\n") ? "\n" : "") +
+            `${GITIGNORE_BEGIN}\n${missing.join("\n")}\n${GITIGNORE_END}\n`;
+        appendFileSync(gitignorePath, block);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function writeJson(path, data) {
     writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
 }
@@ -117,11 +147,10 @@ export function seedDesignArtifacts(featureDir, root, capture, refs) {
     const used = new Set();
     for (const screen of capture.screens) {
         const base = screenSlug(screen);
-        let slug = base;
-        let n = 1;
+        let slug = screen.nodeId ? `${base}-${slugify(screen.nodeId)}` : base;
+        let n = 2;
         while (used.has(slug)) {
-            const suffix = n === 1 && screen.nodeId ? slugify(screen.nodeId) : String(n);
-            slug = `${base}-${suffix}`;
+            slug = `${base}-${n}`;
             n++;
         }
         used.add(slug);