raptor-aios 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,85 @@ 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

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-1481%20passing-22c55e)](#️-desenvolvimento-local)
-[![version](https://img.shields.io/badge/version-0.14.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
 ```
 
 ---
@@ -201,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                    |
 | -------------------------------------- | --------------------------------------------------- |
@@ -210,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
 
@@ -271,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`
 
@@ -521,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)
@@ -535,6 +539,8 @@ 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`.
 
+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`.
+
 > 🎯 **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).
@@ -557,7 +563,7 @@ O provider **`figma-rest`** usa a REST API da Figma com um PAT (`${FIGMA_TOKEN}`
 🎨 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
 
@@ -622,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/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/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);

package/dist/_core/dist/design/screens.js

@@ -177,6 +177,24 @@ export function pageIdsFromMetadata(data) {
 export function screenSlug(screen) {
     return slugify(screen.name) || slugify(screen.nodeId ?? "screen") || "screen";
 }
+export function orphanScreenStems(presentStems, screens) {
+    const present = new Set(presentStems);
+    const suffixedBases = new Set();
+    const bareBases = new Set();
+    for (const screen of screens) {
+        if (screen.nodeId)
+            suffixedBases.add(screenSlug(screen));
+        else
+            bareBases.add(screenSlug(screen));
+    }
+    const orphans = [];
+    for (const base of suffixedBases) {
+        if (present.has(base) && !bareBases.has(base) && !orphans.includes(base)) {
+            orphans.push(base);
+        }
+    }
+    return orphans;
+}
 function bodyName(name) {
     return (name
         .replace(/[\r\n]+/g, " ")

package/dist/_core/dist/gates/builtin.js

@@ -6,7 +6,7 @@ import { extractCoreBlock } from "../constitution/core.js";
 import { parsePlan } from "../models/plan.js";
 import { parseSpec } from "../models/spec.js";
 import { parseTaskList, parseTasks } from "../models/tasks.js";
-import { detectClarificationMarkers, stripHtmlComments, } from "../models/clarify.js";
+import { detectClarificationMarkers, hasUnresolvedPlaceholder, stripHtmlComments, } from "../models/clarify.js";
 import { gateBranchNaming } from "./branch-gate.js";
 function extractIdsByPattern(source, re) {
     const seen = new Set();
@@ -418,11 +418,11 @@ export const gateSpecReady = {
             };
         }
         const problems = [];
-        if (/\[PREENCHER\b/i.test(body)) {
+        if (hasUnresolvedPlaceholder(body, /\[PREENCHER\b/i)) {
             problems.push("unfilled [PREENCHER] placeholder(s) remain");
         }
-        const storyIds = new Set([...body.matchAll(/\bUS-?(\d+)\b/g)].map((m) => `US${m[1]}`));
-        const coveredStories = new Set([...body.matchAll(/covers\b[^.\n]*?\bUS-?(\d+)/gi)].map((m) => `US${m[1]}`));
+        const storyIds = new Set([...body.matchAll(/\bUS-?(\d+)\b/g)].map((m) => `US${Number(m[1])}`));
+        const coveredStories = new Set([...body.matchAll(/covers\b[^.\n]*?\bUS-?(\d+)/gi)].map((m) => `US${Number(m[1])}`));
         const uncovered = [...storyIds].filter((s) => !coveredStories.has(s));
         if (storyIds.size > 0 && uncovered.length > 0) {
             problems.push(`user stor${uncovered.length > 1 ? "ies" : "y"} without acceptance coverage: ${uncovered.join(", ")}`);
@@ -523,7 +523,11 @@ export const gatePlanInputHash = {
                 level: this.level,
                 article: this.article,
                 status: "fail",
-                message: `stale: plan declares spec_hash=${plan.data.spec_hash.slice(0, 20)}…, current spec hash=${spec.hash.slice(0, 20)}…`,
+                message: `stale: plan declares spec_hash=${plan.data.spec_hash.slice(0, 20)}…, current spec hash=${spec.hash.slice(0, 20)}…\n` +
+                    `  spec.md changed after plan.md was generated (likely a clarify/re-approve). ` +
+                    `If the edit was intentional, run 'raptor resync <feature> --artifact plan' to re-bless plan.md's spec_hash, ` +
+                    `then re-run 'raptor verify' (and re-approve if the change is material). ` +
+                    `Otherwise regenerate plan.md with 'raptor plan <feature>'.`,
                 details: {
                     declared: plan.data.spec_hash,
                     current: spec.hash,
@@ -600,7 +604,11 @@ export const gateTasksInputHash = {
                 level: this.level,
                 article: this.article,
                 status: "fail",
-                message: `stale: tasks declares plan_hash=${tasks.data.plan_hash.slice(0, 20)}…, current plan hash=${plan.hash.slice(0, 20)}…`,
+                message: `stale: tasks declares plan_hash=${tasks.data.plan_hash.slice(0, 20)}…, current plan hash=${plan.hash.slice(0, 20)}…\n` +
+                    `  plan.md changed after tasks.md was generated (likely a clarify/re-approve upstream). ` +
+                    `If the edit was intentional, run 'raptor resync <feature> --artifact tasks' to re-bless tasks.md's plan_hash, ` +
+                    `then re-run 'raptor verify' (and re-approve if the change is material). ` +
+                    `Otherwise regenerate tasks.md with 'raptor tasks <feature>'.`,
                 details: {
                     declared: tasks.data.plan_hash,
                     current: plan.hash,
@@ -911,7 +919,7 @@ export const gatePlanReady = {
         if (detectClarificationMarkers(body).length > 0) {
             problems.push("unresolved [NEEDS CLARIFICATION] marker(s) remain");
         }
-        if (/\[PREENCHER\b/i.test(stripped)) {
+        if (hasUnresolvedPlaceholder(body, /\[PREENCHER\b/i)) {
             problems.push("unfilled [PREENCHER] placeholder(s) remain");
         }
         if (/\bStatus:\s*`?pending`?/i.test(stripped) || /\|\s*pending\s*\|/i.test(stripped)) {
@@ -1010,12 +1018,22 @@ export const gateTasksReady = {
         if (detectClarificationMarkers(body).length > 0) {
             problems.push("unresolved [NEEDS CLARIFICATION] marker(s) remain");
         }
-        if (/\[PREENCHER\b/i.test(stripped)) {
+        if (hasUnresolvedPlaceholder(body, /\[PREENCHER\b/i)) {
             problems.push("unfilled [PREENCHER] placeholder(s) remain");
         }
+        const PHASE_HEADING_RE = /^#{2,}\s/;
+        const bodyLines = body.split("\n");
+        const lineToPhase = new Array(bodyLines.length);
+        let phaseBucket = 0;
+        for (let i = 0; i < bodyLines.length; i++) {
+            if (PHASE_HEADING_RE.test(bodyLines[i]))
+                phaseBucket++;
+            lineToPhase[i] = phaseBucket;
+        }
         const noUS = [];
         const noAC = [];
         const noFile = [];
+        const phaseHasPath = new Set();
         for (const it of items) {
             if (META_TASK_RE.test(it.raw))
                 continue;
@@ -1023,8 +1041,13 @@ export const gateTasksReady = {
                 noUS.push(it.id);
             if (!/\[AC-\d+\]/i.test(it.raw))
                 noAC.push(it.id);
-            if (!FILE_RE.test(it.raw))
+            const phase = lineToPhase[it.lineIndex] ?? 0;
+            if (FILE_RE.test(it.raw)) {
+                phaseHasPath.add(phase);
+            }
+            else if (!phaseHasPath.has(phase)) {
                 noFile.push(it.id);
+            }
         }
         if (noUS.length > 0) {
             problems.push(`task(s) without a [US#] (orphan, not [meta]): ${noUS.join(", ")}`);