raptor-aios 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -3,7 +3,123 @@
 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
 

package/README.md

@@ -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`
 

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).",
@@ -284,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/fetcher.js

@@ -6,15 +6,19 @@ function warn(opts, message) {
     else
         process.stderr.write(`Warning: ${message}\n`);
 }
-function scopeSkipWarning(url) {
+function scopeSkipWarning(url, someCaptured) {
+    if (someCaptured) {
+        return (`ref sem node-id (link sem ?node-id=); só ESTE link não foi capturado — ` +
+            `linke o frame específico no card para incluí-lo: ${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}`);
+        `linke o frame no card, ou rode com --design-scope file para o arquivo inteiro: ${url}`);
 }
-function warnOnce(opts, seen, url) {
+function warnOnce(opts, seen, url, someCaptured) {
     if (seen.has(url))
         return;
     seen.add(url);
-    warn(opts, scopeSkipWarning(url));
+    warn(opts, scopeSkipWarning(url, someCaptured));
 }
 export async function fetchDesignData(refs, client, opts = {}) {
     const varMap = {};
@@ -59,9 +63,10 @@ async function captureScreens(refs, client, opts, scopeWarned) {
     const scope = opts.scope ?? "node";
     const out = [];
     const seen = new Set();
+    const someCaptured = refs.some((r) => Boolean(r.nodeId));
     for (const ref of refs) {
         if (scope === "node" && !ref.nodeId) {
-            warnOnce(opts, scopeWarned, ref.url);
+            warnOnce(opts, scopeWarned, ref.url, someCaptured);
             continue;
         }
         try {
@@ -90,10 +95,11 @@ async function captureAssets(refs, client, typography, opts, scopeWarned) {
     const pending = [];
     const seenPaths = new Set();
     const scope = opts.scope ?? "node";
+    const someCaptured = refs.some((r) => Boolean(r.nodeId));
     if (client.captureAssets) {
         for (const ref of refs) {
             if (scope === "node" && !ref.nodeId) {
-                warnOnce(opts, scopeWarned, ref.url);
+                warnOnce(opts, scopeWarned, ref.url, someCaptured);
                 continue;
             }
             try {

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

@@ -1,9 +1,9 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { isTokensEmpty, parseDesignTokens } from "./tokens.js";
 import { parseAssetManifest } from "./manifest.js";
 import { renderScreenMarkdown, screenSlug } from "./screens.js";
-import { slugify } from "./slug.js";
+import { normalizePath, slugify } from "./slug.js";
 import { ASSET_MANIFEST_SCHEMA, } from "./types.js";
 export const ASSET_DIRS = [
     "assets/images",
@@ -81,28 +81,64 @@ 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) {
+function ensureAssetGitignore(root, relPaths) {
     try {
+        const wanted = [...new Set(relPaths.map((p) => normalizePath(p)).filter(Boolean))];
+        if (wanted.length === 0)
+            return false;
         const gitignorePath = join(root, ".gitignore");
-        const existing = existsSync(gitignorePath)
-            ? readFileSync(gitignorePath, "utf8")
-            : "";
-        if (existing.includes(GITIGNORE_BEGIN))
+        const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+        const lines = existing.split(/\r?\n/);
+        let begin = -1;
+        let end = -1;
+        for (let i = 0; i < lines.length; i++) {
+            if (begin === -1 && lines[i].trim() === GITIGNORE_BEGIN)
+                begin = i;
+            else if (begin !== -1 && lines[i].trim() === GITIGNORE_END) {
+                end = i;
+                break;
+            }
+        }
+        const wellFormed = begin !== -1 && end !== -1;
+        if (begin !== -1 && end === -1)
+            end = lines.length;
+        const hasBlock = begin !== -1;
+        const blockEntries = hasBlock
+            ? lines.slice(begin + 1, end).map((l) => l.trim()).filter(Boolean)
+            : [];
+        const outside = new Set((hasBlock ? [...lines.slice(0, begin), ...lines.slice(end + 1)] : lines).map((l) => l.trim()));
+        const managed = new Set(blockEntries);
+        for (const p of wanted) {
+            if (!outside.has(p) && !outside.has(`/${p}`))
+                managed.add(p);
+        }
+        const newEntries = [...managed].sort();
+        if (newEntries.length === 0)
             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)
+        const oldSorted = [...new Set(blockEntries)].sort();
+        if (wellFormed && newEntries.length === oldSorted.length && newEntries.every((e, i) => e === oldSorted[i])) {
             return false;
-        const block = (existing.length && !existing.endsWith("\n") ? "\n" : "") +
-            `${GITIGNORE_BEGIN}\n${missing.join("\n")}\n${GITIGNORE_END}\n`;
-        appendFileSync(gitignorePath, block);
+        }
+        let outLines;
+        if (hasBlock) {
+            outLines = [...lines.slice(0, begin), GITIGNORE_BEGIN, ...newEntries, GITIGNORE_END, ...lines.slice(end + 1)];
+        }
+        else {
+            outLines = existing.length ? [...lines] : [];
+            while (outLines.length && outLines[outLines.length - 1].trim() === "")
+                outLines.pop();
+            if (outLines.length)
+                outLines.push("");
+            outLines.push(GITIGNORE_BEGIN, ...newEntries, GITIGNORE_END);
+        }
+        let next = outLines.join("\n");
+        if (!next.endsWith("\n"))
+            next += "\n";
+        writeFileSync(gitignorePath, next);
         return true;
     }
     catch {
@@ -145,6 +181,7 @@ export function seedDesignArtifacts(featureDir, root, capture, refs) {
     }
     const screensDir = join(designDir, "screens");
     const used = new Set();
+    const usedNames = new Set();
     for (const screen of capture.screens) {
         const base = screenSlug(screen);
         let slug = screen.nodeId ? `${base}-${slugify(screen.nodeId)}` : base;
@@ -154,9 +191,20 @@ export function seedDesignArtifacts(featureDir, root, capture, refs) {
             n++;
         }
         used.add(slug);
-        if (writeIfMissing(join(screensDir, `${slug}.md`), renderScreenMarkdown(screen))) {
+        const nameKey = slugify(screen.name);
+        const screenToRender = nameKey && usedNames.has(nameKey) && screen.nodeId
+            ? { ...screen, name: `${screen.name} (${screen.nodeId})` }
+            : screen;
+        if (nameKey)
+            usedNames.add(nameKey);
+        if (writeIfMissing(join(screensDir, `${slug}.md`), renderScreenMarkdown(screenToRender))) {
             result.screensWritten.push(slug);
         }
     }
+    const downloaded = capture.assets
+        .filter((a) => a.status === "downloaded")
+        .map((a) => a.path);
+    if (downloaded.length > 0)
+        ensureAssetGitignore(root, downloaded);
     return result;
 }

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

@@ -213,7 +213,11 @@ export function renderScreenMarkdown(screen) {
         data["summary"] = screen.summary;
     const display = bodyName(screen.name);
     const body = `\n<!-- Screen captured from Figma. Flesh out: states, navigation, components, data, edge cases.\n` +
-        `     Reference it from the spec/tasks as [screen: ${display}]. -->\n\n` +
+        `     Reference it from the spec/tasks as [screen: ${display}].\n` +
+        `     Before writing the \`## Anatomy\` fidelity contract, CAPTURE this frame with the Figma MCP\n` +
+        `     get_screenshot, save the PNG under design/screens/, and record its path in this file's\n` +
+        `     frontmatter under \`figma_screenshot:\`. Derive every region/element from that real pixel —\n` +
+        `     gate.design.anatomy blocks an anatomy authored without a captured reference. -->\n\n` +
         `## ${display}\n\n` +
         `_Placeholder — detail this screen during \`/raptor-specify\`._\n`;
     return stringifyFrontmatter(data, body);

package/dist/_core/dist/frontmatter/index.js

@@ -11,6 +11,32 @@ export function parseFrontmatter(source) {
     const data = (yamlBlock.trim().length === 0 ? {} : (parseYaml(yamlBlock) ?? {}));
     return { data, body, hasFrontmatter: true, raw: source };
 }
+export function frontmatterField(source, field) {
+    const m = source.match(FRONTMATTER_RE);
+    if (!m)
+        return undefined;
+    const block = m[1] ?? '';
+    try {
+        const data = parseYaml(block);
+        const v = data == null ? undefined : data[field];
+        if (typeof v === 'string')
+            return v;
+        if (typeof v === 'number' || typeof v === 'boolean')
+            return String(v);
+    }
+    catch {
+    }
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const lm = block.match(new RegExp(`^${escaped}[ \\t]*:[ \\t]*(.*\\S)[ \\t]*$`, 'm'));
+    if (!lm)
+        return undefined;
+    let val = lm[1].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+    }
+    return val.trim() || undefined;
+}
 export function stringifyFrontmatter(data, body) {
     const yamlBlock = stringifyYaml(data).trimEnd();
     const trimmedBody = body.startsWith('\n') ? body : '\n' + body;