raptor-aios 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -3,7 +3,202 @@
 All notable changes to this project will be documented in this file.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.16.0] - 2026-06-24
+
+Correções P0/P1/P2 do re-teste KAN-20 v2 (DuCorre/FastBoy): fechar o **processo
+de fidelidade** para o erro não nascer, não só ser pego no fim, e endurecer
+rastreabilidade/determinismo nas pontas (resiliência de gate, hash unificado,
+backbone de fidelidade instalado, clarify determinístico, drift acionável). Esta
+versão também **entrega os dois deferidos** — constituição em **fonte única** e
+**edições pós-implement auditadas** — e incorpora os achados de uma **revisão
+integrada adversarial** que a suíte verde escondia (corrupção latente do
+`audit.jsonl` por campo `undefined`; vazamento residual do laço de fidelidade).
+
+### Added
+
+- **`gate.design.anatomy`** (M3, _required_) — a `## Anatomy` (contrato de fidelidade)
+  precisa **nascer do pixel real**: cada tela com anatomia tem que registrar um
+  `figma_screenshot:` (capturado via `get_screenshot`) presente em disco e ≥ 1 KB. Sem
+  isso o gate bloqueia o verify — impede o contrato de nascer cego e o `implement`
+  construir fielmente a coisa errada (F10-2). Os prompts (`spec.md.hbs`, `/raptor-specify`)
+  agora mandam capturar o screenshot ANTES de autorar a anatomia.
+- **Backbone de fidelidade instalado no projeto** — `init`/`upgrade` agora copiam
+  `scripts/review/{hex-scan,diff-tokens}.mjs` e `scripts/app/screenshot.sh` para
+  `.raptor/scripts/`, e o prompt do scorer referencia `.raptor/scripts/...`. Antes os
+  comandos do scorer apontavam para `scripts/...` que nenhum comando instalava — hex-scan
+  e o screenshot do app ficavam indisponíveis no caminho documentado (F8-1).
+- **`implement --finalize` audita edições pós-implement** — quando o finalize absorve um
+  artefato que mudou após ser registrado (drift), emite o evento `implement.drift_detected`
+  (dedup por `(path|hash)`, idempotente), tornando a edição pós-Fase-7 visível no trilho de
+  audit em vez de reconciliada em silêncio. A detecção é pura (`reconstructImplLogFromAudit`
+  expõe os drifts); o `verify` segue read-only e o gate M7 segue puro (F7-untracked).
+
+### Changed
+
+- **`raptor design fidelity` virou laço fechado** — sai **não-zero** enquanto houver
+  região < threshold, scorecard com problema ou `design-decision` pendente, e **0** só na
+  convergência. Um laço de agente/CI itera até passar, em vez de a convergência depender
+  de disciplina manual (F10-3). O `evaluateFeatureFidelity` agora expõe
+  `pendingDesignDecisions`, e tanto o loop quanto a lente `raptor verify fidelity` passam a
+  reportar **não-ok** numa `design-decision` pendente — alinhados com `gate.design.fidelity`
+  (antes a lente dava verde enquanto o gate bloqueava).
+- **`raptor design fidelity` converge ao veredito do gate (vazamento residual do F10-3)** — a
+  lente do laço só olhava os scorecards, então o comando podia sair **0** ("converged") enquanto
+  `raptor verify` falharia por falta de evidência de screenshot ou cobertura por região da
+  anatomia. Agora o comando roda `gate.design.fidelity` e `gate.design.anatomy` como autoridade
+  da convergência (só engajam com spec aprovada). Um laço de agente que parava no verde otimista
+  passa a iterar até o gate de fato passar.
+- **Constituição em fonte única** — `.raptor/constitution.md` passa a ser a **única** cópia; o
+  espelho `.raptor/memory/constitution.md` foi removido. `init` não o escreve mais, `upgrade`
+  remove o órfão (com backup antes), e `preset add`/`doctor` só olham o canônico. Os prompts
+  (`templates/commands/*`, `plan.md.hbs`), o `scripts/bash/common.sh` (`CONSTITUTION_PATH`) e os
+  docs foram repointados; snapshots E2E regenerados. Fim da duplicação que o `upgrade` mantinha
+  em sync (F5-1b). _(Scripts PowerShell ficam como follow-up.)_
+- **Skill `/raptor-clarify` alinhada ao caminho determinístico** — a skill 2.1.0 deixou de
+  hand-editar `## Clarifications` num formato (`### Session` + `- Q:→A:`) divergente do CLI;
+  agora emite `answers.json` e roda `raptor clarify --apply` (o CLI é o dono único da seção,
+  formato canônico `- **label** — answer`, UPSERT idempotente). Fim do spec híbrido de dois
+  escritores (F3-1/2). Os snapshots E2E passam a cobrir `clarify` (trava o formato).
+- **Drift do impl-log agora é acionável** — `gate.m7.diff_hash_matches` já re-hasha o working
+  tree no `verify` e flaga arquivo que mudou/sumiu após ser registrado; a mensagem agora nomeia
+  a causa (**impl-log STALE** — edição pós-implement não re-logada) e a remediação
+  (`raptor implement --finalize` ou reverter) (F7-stale).
+
+### Fixed
+
+- **`.gitignore` não engole mais os assets do app** — o `--design-fetch` deixou de
+  ignorar os diretórios `assets/{images,icons,fonts}` inteiros; agora ignora apenas os
+  arquivos exatos que o RAPTOR baixou (bloco gerenciado único, idempotente). Assets
+  próprios do app (fontes, imagens de onboarding) param de sumir silenciosamente do
+  controle de versão (F1-2).
+- **`/raptor-specify` não duplica mais uma feature já seedada** — `create-new-feature.sh`
+  ganhou guarda determinística por **slug** (espelhando o `raptor new`): um
+  `.raptor/specs/NNN-<slug>` existente é **reusado** (`REUSED: true`), não recriado com um
+  número novo que orfanaria a feature seedada (F2-1). `--number` e `--timestamp` optam por
+  fora.
+- **`gate.design.ready` resiliente a YAML inválido** — um campo irmão malformado no
+  frontmatter de uma tela (ex.: um `screen_role` não-quotado escrito pelo agente) fazia o
+  `parseFrontmatter` lançar e o gate descartar o `name`, caindo no slug do arquivo que nunca
+  casa (`[screen: X]` reportado como ausente). Novo helper `frontmatterField()` lê o campo
+  por line-scan quando o parse YAML falha; usado em `gate.design.ready` e `gate.design.anatomy`
+  (F9-1).
+- **Hash da constituição unificado** — dentro do mesmo comando, o prompt-context gravava o
+  hash whole-file enquanto `plan`/audit gravavam o hash do bloco RAPTOR-CORE. `buildCanonicalPrompt`
+  passa a registrar o **mesmo** core-block hash (helper `constitutionHashFromContent`), então
+  prompt e artefato concordam em "qual constituição governou isto" (F5-1).
+- **Serializer do `audit.jsonl` robusto a `undefined`** — o `stableStringify` emitia
+  `"chave":undefined` (JSON inválido) para uma propriedade com valor `undefined`, corrompendo a
+  linha e a cadeia `prev_hash` a partir dela — e isso **disparava de fato** em `raptor plan`/`init`
+  num projeto sem preset. Agora omite chaves `undefined` e mapeia `undefined` em array para `null`
+  (espelhando `JSON.stringify`). Achado da revisão integrada adversarial.
+- **`upgrade` não apaga mais o espelho da constituição sem backup** (`backup()` antes do `rmSync`),
+  e a regex que remove a chave morta `branch_prefix` foi **ancorada na coluna 0** (não casa uma
+  chave homônima aninhada sob outra seção). Achados da revisão integrada.
+
+#### Polimento (P2)
+
+- **`raptor approve` emite `spec.approved`** (evento distinto, não mais o genérico `spec.updated`) e
+  grava `audit_ref` no frontmatter apontando para o id da entrada do audit — link bidirecional
+  artefato↔audit (C4), antes sempre null (F4-1/F4-2).
+- **`clarify --apply` faz backup do spec** antes de sobrescrever (a recuperação não depende mais só
+  do ledger/hashes) (F3-3).
+- **Warning de scope não empurra mais `--design-scope file`** quando outras refs foram capturadas —
+  uma ref sem node-id agora vira aviso suave ("linke o frame específico"), e o escape hatch
+  file-wide só aparece quando NADA foi capturado (F1-warn).
+- **Nome de tela duplicado é desambiguado** — dois frames Figma com o mesmo `name` ganham um sufixo
+  de node-id no 2º+ , para `[screen: X]` resolver para um arquivo só (F1-dup).
+- **`audit` `file_keys` deduplicado**; **tabela `Post-Design Check` do `plan.md.hbs`** consertada
+  (separador/linha partidos quebravam a renderização) (F5-2).
+- **`audit.jsonl` ganha cadeia tamper-evident** — cada evento grava `prev_hash` (sha256 da linha
+  anterior; null no genesis), e `raptor verify audit --strict` valida a cadeia e detecta adulteração
+  de eventos passados. Campo opcional no schema (back-compat com logs pré-cadeia) (prev_hash).
+- **Branch do `/raptor-specify` (bash) alinhada à convenção do `raptor new`** — o branch agora carrega
+  o prefixo `feat/` (`feat/NNN-slug`); o diretório da spec continua o `NNN-slug` puro. `get_next_feature_number`
+  e `check_feature_branch` passam a entender o prefixo. `raptor upgrade` remove a chave morta
+  `branch_prefix` de projetos legados e o label "legacy cleanup" só aparece quando algo foi de fato
+  limpo (F2-2 / F0-2 / F0-3).
+- **`raptor design status --check`** valida o token figma-rest de verdade (chamada `/v1/me`): um token
+  clobberado/revogado-mas-presente agora reporta NOT connected, em vez do falso "connected" por
+  presença (F0-1).
+
+## [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
 

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
 
@@ -237,7 +237,7 @@ Você os executa **dentro do seu agente de IA**. São prompts versionados e rico
 
 ### 🧭 `/raptor-constitution`
 
-Cria ou atualiza os princípios do projeto (`.raptor/memory/constitution.md`). É o "contrato social" que todas as fases seguintes respeitam. Use no início, ou quando quiser ratificar uma mudança de regra (com bump de versão).
+Cria ou atualiza os princípios do projeto (`.raptor/constitution.md`). É o "contrato social" que todas as fases seguintes respeitam. Use no início, ou quando quiser ratificar uma mudança de regra (com bump de versão).
 
 ### 📝 `/raptor-specify`
 
@@ -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

@@ -1,6 +1,7 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { hashString, hashFile } from "../audit/hash.js";
+import { constitutionHashFromContent } from "../constitution/core.js";
 import { wrapSpec, wrapUntrusted } from "./prompt-markers.js";
 const PHASE_MAP = {
     new: {
@@ -80,14 +81,14 @@ const PHASE_MAP = {
             "2. Extraia do Figma os valores REAIS do nó com `get_design_context` / `get_variable_defs` /",
             "   `get_screenshot`. REGRA DE OURO: o nó vence a percepção — nunca chute px/cor/raio/peso.",
             "3. Capture o app RODANDO (evidência, não invente): rode",
-            "   `scripts/app/screenshot.sh design/visual-review/_shots/<tela>.<estado>.app.png` e salve o",
+            "   `.raptor/scripts/app/screenshot.sh design/visual-review/_shots/<tela>.<estado>.app.png` e salve o",
             "   screenshot do Figma como `…<estado>.figma.png`.",
             "4. Compare Figma×app POR MICRO-REGIÃO e pontue 60–100 em cada dimensão",
             "   (layout, spacing, color, typography, dimensions, icon, states). A nota da região = a",
             "   dimensão MAIS FRACA (o elo). Mínimo de aprovação = 95 (ou o threshold do preset).",
-            "5. Backbone determinístico (não falsifique): rode `node scripts/review/hex-scan.mjs src --json`",
+            "5. Backbone determinístico (não falsifique): rode `node .raptor/scripts/review/hex-scan.mjs src --json`",
             "   e preencha `deterministic.hex_hardcoded` com o resultado REAL; rode",
-            "   `node scripts/review/diff-tokens.mjs <figma-tokens.json> design/tokens.json --json` p/ o drift.",
+            "   `node .raptor/scripts/review/diff-tokens.mjs <figma-tokens.json> design/tokens.json --json` p/ o drift.",
             "6. Registre cada divergência `{ dimension, figma, rn, fix, severity, status }`. `status`:",
             "   `resolved` (corrigida), `open` (ainda falha) ou `design-decision` (desvio semântico —",
             "   troca de ícone/cor/copy — que EXIGE aprovação humana antes de passar o gate).",
@@ -158,6 +159,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 +219,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: {
@@ -274,7 +285,10 @@ export function buildCanonicalPrompt(input) {
             ? join(raptorDir, "constitution.md")
             : join(featureDir, inp.filename);
         if (existsSync(path)) {
-            inputs.push({ path: inp.filename, hash: hashFile(path), role: inp.role });
+            const hash = inp.filename === "constitution.md"
+                ? constitutionHashFromContent(readFileSync(path, "utf8"))
+                : hashFile(path);
+            inputs.push({ path: inp.filename, hash, role: inp.role });
         }
     }
     let body = phase.bodyTemplate;

package/dist/_core/dist/audit/logger.js

@@ -57,15 +57,25 @@ export function nextSequence(jsonlPath) {
     }
     return lines.length + 1;
 }
+export function lastEventHash(jsonlPath) {
+    if (!existsSync(jsonlPath))
+        return null;
+    const trimmed = readFileSync(jsonlPath, "utf8").trimEnd();
+    if (trimmed.length === 0)
+        return null;
+    const lines = trimmed.split("\n");
+    return hashString(lines[lines.length - 1]);
+}
 function stableStringify(obj) {
     if (obj === null || typeof obj !== "object")
         return JSON.stringify(obj);
     if (Array.isArray(obj))
-        return "[" + obj.map(stableStringify).join(",") + "]";
-    const keys = Object.keys(obj).sort();
-    const parts = keys.map((k) => JSON.stringify(k) +
-        ":" +
-        stableStringify(obj[k]));
+        return ("[" +
+            obj.map((v) => (v === undefined ? "null" : stableStringify(v))).join(",") +
+            "]");
+    const o = obj;
+    const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();
+    const parts = keys.map((k) => JSON.stringify(k) + ":" + stableStringify(o[k]));
     return "{" + parts.join(",") + "}";
 }
 export function appendAuditEvent(jsonlPath, event) {
@@ -75,6 +85,7 @@ export function appendAuditEvent(jsonlPath, event) {
         id: id ?? uuidv7(),
         sequence: sequence ?? nextSequence(jsonlPath),
         ts: ts ?? new Date().toISOString(),
+        prev_hash: lastEventHash(jsonlPath),
         ...rest,
     };
     assertC5(full);

package/dist/_core/dist/audit/schema.js

@@ -27,6 +27,10 @@ export const auditEventSchema = {
             format: "date-time",
             description: "ISO 8601 with timezone, millisecond precision recommended.",
         },
+        prev_hash: {
+            type: ["string", "null"],
+            description: "sha256 of the previous event's serialized line — a tamper-evident chain; null for the genesis event. Optional for back-compat with pre-chain logs.",
+        },
         event: {
             type: "string",
             enum: [
@@ -34,6 +38,7 @@ export const auditEventSchema = {
                 "feature.archived",
                 "spec.generated",
                 "spec.updated",
+                "spec.approved",
                 "clarify.added",
                 "clarify.scanned",
                 "clarify.applied",
@@ -48,6 +53,7 @@ export const auditEventSchema = {
                 "checklist.generated",
                 "checklist.created",
                 "task.completed",
+                "implement.drift_detected",
                 "gate.evaluated",
                 "gate.skipped",
                 "gate.approved",
@@ -152,6 +158,10 @@ export const auditEventSchema = {
             if: { properties: { event: { const: "code.generated" } } },
             then: { required: ["outputs", "task"] },
         },
+        {
+            if: { properties: { event: { const: "implement.drift_detected" } } },
+            then: { required: ["outputs", "detector"] },
+        },
         {
             if: {
                 properties: {

package/dist/_core/dist/audit/validate.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { Ajv2020, } from "ajv/dist/2020.js";
 import { auditEventSchema } from "./schema.js";
+import { hashString } from "./hash.js";
 let cachedValidator = null;
 function getValidator() {
     if (cachedValidator)
@@ -75,6 +76,7 @@ export function validateAuditFile(jsonlPath, opts = {}) {
     let validLines = 0;
     let prevSequence = 0;
     let prevTs = "";
+    let prevRaw = null;
     for (let i = 0; i < lines.length; i++) {
         const lineNum = i + 1;
         const raw = lines[i];
@@ -87,6 +89,8 @@ export function validateAuditFile(jsonlPath, opts = {}) {
             });
             continue;
         }
+        const prevLine = prevRaw;
+        prevRaw = raw;
         let parsed;
         try {
             parsed = JSON.parse(raw);
@@ -125,6 +129,17 @@ export function validateAuditFile(jsonlPath, opts = {}) {
                     keyword: "monotonicTs",
                 });
             }
+            if (obj.prev_hash !== undefined) {
+                const expected = prevLine === null ? null : hashString(prevLine);
+                if (obj.prev_hash !== expected) {
+                    errors.push({
+                        line: lineNum,
+                        path: "/prev_hash",
+                        message: `prev_hash chain broken — expected ${expected ?? "null (genesis)"}, got ${obj.prev_hash ?? "null"}`,
+                        keyword: "chain",
+                    });
+                }
+            }
             prevSequence = obj.sequence;
             prevTs = obj.ts;
         }

package/dist/_core/dist/constitution/core.js

@@ -89,6 +89,10 @@ export function extractCoreBlock(source) {
         endIndex: endMarkerIdx + CORE_END_MARKER.length,
     };
 }
+export function constitutionHashFromContent(content) {
+    const extracted = extractCoreBlock(content);
+    return extracted ? extracted.declaredHash : hashString(content);
+}
 export function rewriteCoreBlock(source) {
     const canonical = coreBlock();
     const extracted = extractCoreBlock(source);

package/dist/_core/dist/constitution/index.js

@@ -1 +1 @@
-export { CORE_VERSION, CORE_ARTICLES_TEXT, CORE_END_MARKER, CORE_START_MARKER_PREFIX, CORE_START_MARKER_RE, coreBlock, coreHash, extractCoreBlock, rewriteCoreBlock, } from "./core.js";
+export { CORE_VERSION, CORE_ARTICLES_TEXT, CORE_END_MARKER, CORE_START_MARKER_PREFIX, CORE_START_MARKER_RE, coreBlock, coreHash, constitutionHashFromContent, extractCoreBlock, rewriteCoreBlock, } from "./core.js";

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 {