Status: Approved · v1.1 · SPEC-SDD-001

depends_on: SPEC-PRINCIPLES-001, SPEC-ARCH-BOUNDARIES-001, SPEC-ARCH-QUALITY-001

Sistema de Spec-Driven Development do RaizFC

Este documento governa o desenvolvimento orientado por specs do RaizFC. Ele organiza o conhecimento existente sem substituir regras de produto, domínio, UX, API, contracts ou ADRs. O processo é independente de fornecedor de IA, usa aprovação humana para decisões sensíveis e aplica progressive disclosure.

Fluxo e papel dos artefatos

Visão e princípios → Regras de produto/domínio → UX → API/contracts → Arquitetura/mocks
→ Change Request → Impact Analysis → Increment Specification → Execution Pack
→ Implementação → Review → Validation → Convergence → Handoff → Encerramento

• Visão/princípios definem propósito, limites e critérios duráveis.
• Specs de produto/domínio definem atores, regras, invariantes, estados, exceções e MVP/pós-MVP.
• Specs de UX descrevem jornadas, estados e acessibilidade; não autorizam alterar regra de domínio.
• API/contracts definem a fronteira compartilhada; packages/contracts é a fonte executável de shapes.
• Arquitetura/mocks definem boundaries e como simular o contrato sem acoplar telas a fixtures.
• Change Request (CR) registra por que mudar antes de editar uma spec.
• Impact Analysis (IA) percorre todas as superfícies e riscos afetados.
• Increment Specification (IS) é a unidade de resultado/capacidade, não uma tarefa isolada.
• Execution Pack (EP) é a unidade operacional executável por um agente, com paths, tarefas, gates e evidências.
• Implementação produz o diff; Review procura divergências independentemente; Validation executa checks/evidências; Convergence compara código e artefatos e cria trabalho residual, sem promover critérios parciais.
• Handoff resume operação; evidência detalhada é append-only. Encerramento é uma transição atômica.

Fontes de verdade

Informação	Source of truth	Derivados/compatibilidade
visão e regras de produto	docs/01_product, docs/02_domain, docs/03_ux	knowledge indexes e resumos
decisões arquiteturais	docs/09_decisions	DECISIONS.md, adapters
shapes/DTOs	packages/contracts	mocks, API e consumers
catálogo de specs	docs/index.json + frontmatter correspondente	.sdd/generated/traceability.json
catálogo de IS	increments/index.yaml + documento do IS	status no índice é gerado
catálogo de EP	.ai/execution/index.yaml + diretório do EP	manifests legados
estado dinâmico	.sdd/state.yaml	README, START_HERE, CURRENT_STATE, NEXT_STEPS e manifests
capabilities/playbooks	.sdd/registry.yaml	.ai/skills/*.yaml preservados como descritores
evidências	.sdd/evidence/<run-id>/	handoff curto
derivados	.sdd/generated/	nunca editados manualmente

CURRENT_STATE.md e NEXT_STEPS.md preservam narrativa histórica, mas seu único bloco operacional é gerado. Campos status em frontmatters/contexts históricos são snapshots legados; o estado canônico prevalece.

Consumidores derivados

Ferramenta que lê artefatos do SDD diretamente (ex.: tools/sdd-dashboard) não é derivado gerado por pnpm sdd:generate — é consumidor vivo, mantido manualmente. Qualquer agente, de qualquer fornecedor de IA, que altere a estrutura de um artefato do SDD (schemas em .sdd/schemas/*, shape de state.yaml, changes, evidence, execution pack, increments/index.yaml, docs/index.json) deve atualizar esses consumidores no mesmo trabalho, não depois; alteração estrutural sem atualizar consumidor conhecido é tratada como o mesmo tipo de falha de "alteração silenciosa só em documento derivado" descrito abaixo. Consumidor conhecido hoje: tools/sdd-dashboard/app.py, registrado em docs/07_delivery/sdd_operations_dashboard.md e CR-SDD-DASHBOARD-001. Um novo consumidor deve se registrar aqui e no seu próprio CR.

Specs canônicas e evolução

Uma spec possui ID estável, título, domínio/tags, status, versão, owner, atualização, dependências, relações, requisitos, invariantes, casos-limite, critérios verificáveis, decisões pendentes, corte MVP/pós-MVP e histórico de depreciação quando aplicável. Nem toda spec é uma tarefa.

Uma mudança relevante segue:

1. criar CR por .sdd/templates/change-request.yaml;
2. esclarecer lacunas e conflitos;
3. produzir IA por .sdd/templates/impact-analysis.yaml;
4. obter aprovação humana quando sensível;
5. atualizar a spec canônica, com versão/depreciação/substituição explícita;
6. atualizar plano de contracts e mocks;
7. criar/atualizar IS e EP;
8. registrar compatibilidade/migração;
9. rodar geração e validação de derivados.

Alteração silenciosa só em documento derivado falha. Spec alterada sem IA no diff falha. Uma descoberta durante implementação volta ao artefato que a possui; não se corrige apenas no código.

Change Request e Impact Analysis

CR registra problema/oportunidade, motivação, origem, comportamento atual, resultado desejado, escopo, não objetivos, áreas potenciais, riscos, decisões, classificação e aprovação. IA avalia specs, domínio, contracts, mocks, endpoints, services/hooks, web, mobile, UI compartilhada, testes, acessibilidade, segurança, privacidade, dinheiro/carteira, observabilidade, documentação, IS/EP existentes, compatibilidade, migração e regressão.

Um CR aprovado limita escrita por allowed_write. IA não autoriza decisão sensível; ela identifica a decisão e o responsável.

Increment Specification e Execution Pack

IS define resultado, problema, escopo/não objetivos, requisitos, artefatos, dependências, riscos, aceite, MVP/pós-MVP, owner, specs, EP e necessidade de aprovação. IS planejado pode ainda não ter EP; quando executável, a relação IS↔EP deve ser única e válida.

Contexts EP v2 seguem .sdd/schemas/execution-pack.schema.json e declaram ID/IS, tipo, dependências, specs/contracts/ADRs/playbooks, allowlists de leitura/escrita/negação, artefatos por path/glob, tarefas, comandos, evidências, aceite, stop conditions, handoff, base SHA e revisão exata das specs. Texto como “documentação necessária” não substitui um path verificável.

Os 73 EPs históricos concluídos ficam no formato original e preservam evidência. EP ativo/futuro deve usar schema v2.

Três fluxos

Full SDD

Obrigatório para produto, domínio, contracts/APIs públicas, dinheiro/carteira, permissões, privacidade, segurança, arquitetura estrutural, UX relevante, redesign e breaking changes:

CR → Clarify → IA → Specs → IS → EP → Implement → Review → Validation → Converge → Close.

SDD Lite

Usado em refactor sem mudança comportamental, tooling, infraestrutura, docs operacionais, otimização interna e atualização técnica controlada. Exige problema, escopo, não objetivos, impacto, tarefas, riscos, testes, evidências e handoff curto. Se a análise revelar mudança canônica, promova para Full SDD.

Bug Flow

Report → Reproduction → Diagnosis → Failing Test → Fix → Regression Validation → Close.

Use .sdd/templates/bug.yaml. Bug não exige spec nova quando restaura comportamento já definido; se o fix mudar o comportamento canônico, abra CR/IA e evolua a spec.

Máquina de estados

Estado	Significado
draft	artefato ainda incompleto/não elegível
ready	completo para iniciar; dependências satisfeitas
in_progress	um implementador autorizado escreve
review	implementação congelada para revisão independente
validation	comandos/evidências em verificação
blocked	impedimento explícito com motivo e ação necessária
converged	requisitos/diff/evidências sem gap obrigatório
completed	handoff encerrado e derivados sincronizados
superseded	substituído com referência de sucessão/decisão
cancelled	encerrado sem entrega, com justificativa humana

Transições permitidas:

• draft → ready|cancelled;
• ready → in_progress|blocked|cancelled;
• in_progress → review|blocked|cancelled;
• review → in_progress|validation|blocked;
• validation → in_progress|review|converged|blocked;
• blocked → ready|in_progress|review|validation|superseded|cancelled;
• converged → completed|in_progress;
• completed → superseded.

Dependências devem estar completed/converged antes de ready; só um EP pode estar in_progress, salvo exceção documentada com arquivos não sobrepostos. validation exige review; converged exige validation e zero gate pendente; completed exige validation, convergence, handoff e nenhum critério obrigatório parcial. superseded/cancelled exigem Human Approver. Retomada de blocked remove o bloqueio e volta ao estágio registrado, nunca pula evidência.

Implementação completa com validação externa pendente fica em validation, com pending_gates; é o caso observado de EP-MVP-18.1. IS e EP transitam juntos. Use pnpm sdd:transition; não edite arquivos em paralelo. Um gate só pode ser removido atomicamente na transição para converged, usando --clear-gate <id> junto de todos os tipos declarados em required_evidence.

Protocolo multi-IA

AGENTS.md é universal. CLAUDE/AI e futuros adapters de Codex/Copilot/Cursor/Gemini apontam para ele sem replicar regras. Papéis: Orchestrator, Spec and Impact Analyst, Implementer, Reviewer, Validator e Human Approver. Reviewer usa diff/specs como evidência; validator usa códigos de saída/logs. Uma IA não aprova sozinha sua implementação.

Conflitos seguem: aprovação humana registrada → spec/ADR/contract → estado → EP/IS → derivado. Produto, dinheiro, privacidade, segurança e arquitetura continuam humanos. Execuções registram agente/modelo disponível, horário, base SHA e resultado.

Context compiler

pnpm sdd:context --ep <id> gera manifesto determinístico de paths, hashes, bytes, estimativa de tokens, revisões e ausências. Usa state.updated_at como data reprodutível e não concatena conteúdo sensível. Inclui AGENTS, estado, context, IS, specs/contracts/ADRs referenciados, boundaries e arquivos de tarefa/review/validation. Exclui handoffs históricos, screenshots, imagens, logs, builds, evidências antigas e specs não referenciadas.

Review, validation, evidências e handoff

Review classifica achados por risco e cita requisito. Validation diferencia executado/aprovado, parcial, não executado, bloqueio ambiental e inferência estática. Convergence não converte parcial em pronto; devolve gaps à implementação.

Handoff contém status, resultado, arquivos, decisões, testes, critérios atendidos/pendentes, riscos, bloqueios e próximo passo. Evidência detalhada fica append-only em .sdd/evidence/<run-id>/: metadata, comandos/códigos, logs relevantes, screenshots, métricas, testes, base SHA e agente. Handoffs históricos em .ai/execution/** não são apagados.

CI, segurança e diff

CI roda pnpm sdd:validate; geração obsoleta, YAML/JSON inválido, IDs/paths/refs inválidos, ciclos, estado incoerente, capability ausente, context v2 incompleto ou entrypoint stale falham. --changed-since também verifica allowlist, IA para specs/contracts e código de produto em mudança documental.

Segredos nunca entram em contexto/evidência. Paths proibidos prevalecem sobre allowlists. Dinheiro, permissões, privacidade, segurança, contratos e arquitetura exigem aprovação humana. Falha do validador não pode ser contornada editando derivado.

GitHub Spec Kit

A avaliação oficial em 2026-08-22 fixou github/spec-kit@v1.0.1. O core oferece constitution, specify, clarify, plan, tasks, analyze, implement, converge e checklist; presets mudam formato/workflow, extensions adicionam capacidades, e integrações geram arquivos específicos de agente.

Mapeamento: Constitution → princípios RaizFC; Specify/Clarify → CR/clarificação; Plan → IS; Tasks → EP; Analyze → preflight; Implement → execução; Converge → review/validation/correções; Checklist → critérios; Preset → vocabulário/templates RaizFC.

Decisão em ADR-015: preparação/adaptador, sem specify init neste repositório. Inicialização criaria .specify e specs/plans/tasks concorrentes, além de o ambiente atual não ter uv/Python. O piloto estrutural fictício fica em .sdd/spec-kit/pilot/ e não é canônico. Adoção futura deve ocorrer em branch limpa, com v1.0.1 fixada, preset/overrides, diff revisado, rollback e prova multi-agente. O SDD RaizFC continua funcional sem Spec Kit.

Exemplos pequenos

• Regra de produto: CR Full SDD → IA identifica domínio/contracts/mocks/API/web/mobile → aprovação → spec versionada → IS/EP.
• Refactor técnico: SDD Lite declara invariância comportamental, allowlist, testes e handoff.
• Bug: reprodução e teste falho provam o problema; fix e regressão fecham sem spec se o comportamento já era canônico.
• EP bloqueado: sdd:transition ... --to blocked --reason ...; estado exige ação necessária e retomada explícita.
• Spec que afeta contracts: IA e plano de compatibilidade obrigatórios; validator falha se só um derivado mudar.
• Redesign futuro: o primeiro artefato será um CR específico referenciando protótipo aprovado; não uma edição direta das specs atuais.

Preparação do futuro redesign

Após aprovação do protótipo: referenciá-lo; abrir CR de redesign; registrar objetivos/não objetivos; comparar atual/proposto; inventariar telas/componentes; produzir IA; separar regras preservadas de mudanças visuais/funcionais; atualizar specs UX; atualizar tokens/contracts de UI; criar IS; decompor EPs; implementar em fatias; validar web/mobile, responsividade e acessibilidade; convergir. Nenhum desses passos foi executado nesta migração e nenhum artefato de redesign foi criado.

Migração, rollback e troubleshooting

A migração preserva IDs, paths e 75 diretórios EP. Status legados viraram derivados; descriptors continuam no lugar; entrypoints apontam ao estado; narrativa antiga permanece histórica. Detalhes em .sdd/MIGRATION_REPORT.md.

• Estado parece errado: rode pnpm sdd:status e pnpm sdd:validate; corrija .sdd/state.yaml via transição.
• Derivado stale: rode pnpm sdd:generate, confira diff e repita com --check.
• Context ref ausente: corrija catálogo/context/registry na fonte; não remova silenciosamente.
• Transição recusada: satisfaça dependência/evidência/gate ou registre bloqueio.
• Docker ausente: mantenha EP em validation; execute o gate em host apropriado.
• Recuperação: use state.history, evidências e Git; não faça reset destrutivo. Reverter a migração consiste em reverter seus arquivos, sem apagar histórico de produto.

Mapa operacional

Artefato	Finalidade	Source of truth	Derivado de	Validado por
spec	comportamento estável	documento + docs/index.json	CR/IA aprovado	sdd:validate
CR	intenção/limites	.sdd/changes/*.yaml	pedido aprovado	schema + diff guard
IA	impactos/riscos	.sdd/impacts/*.yaml	CR + grafo	schema + validator
IS	resultado de entrega	increments/**/índice	specs/IA	grafo SDD
EP	execução	.ai/execution/**/índice	IS	schema v2 + context compiler
estado	fase/status/gates	.sdd/state.yaml	transições atômicas	state validator
contexto	pacote mínimo	.sdd/generated/context	EP + catálogos + estado	hashes/refs
handoff	resumo	arquivo do EP/execução	resultado/evidência	completion gate
evidência	prova append-only	.sdd/evidence	comandos/review/validation	validator
manifests/entrypoints	compatibilidade	gerados	estado/catálogos	sdd:generate --check