[EPIC][P0][Prototype-First] Validar maquetes, esquemas, modelos e PoCs antes da implementação completa

[wesleysimplicio]

Objetivo

Implementar no caminho produtivo do simplicio-loop um Prototype-First Gate obrigatório e adaptativo, capaz de gerar, comparar, validar, rejeitar e promover protótipos baratos antes da implementação completa.

A meta é evitar gastar tokens, tempo de agente, CPU, RAM, I/O e atenção humana construindo uma solução correta para o problema errado.

Compressão barateia a execução escolhida. Prototype-First evita executar a escolha errada.

Resultado esperado

work item
→ task contract + map/context
→ prototype necessity decision
→ prototype plan + bounded budget
→ generate 1..N isolated candidates
→ deterministic checks + independent judge
→ ACCEPT | REVISE | REJECT | BLOCKED
→ vertical slice
→ revalidation
→ full implementation
→ complete quality/delivery flow

O gate deve estar ligado concretamente ao intake, planning, task anchor, backlog/DAG, stage agents, coordinator, token/cost ledger, reporting, findings, delivery e completion auditor. Criar apenas documentação, prompt ou script não invocado pelo fluxo não satisfaz esta epic.

Escopo do ecossistema

A semântica central pertence ao simplicio-loop; consumidores implementam adapters:

• simplicio-runtime: sandbox, quotas, artifacts e execução determinística;
• simplicio-mapper: mapa de impacto e context pack do protótipo;
• simplicio-dev-cli: scaffold/dry-run/validate/promote;
• simplicio-agent: geração de alternativas, crítica e síntese;
• simplicio-code: preview, comparação, decisão e promoção na UX;
• simplicio-local-any-llm-16gb: worker local barato para protótipos;
• simplicio-loop-oss: reproducer/patch experimental antes de PR;
• simplicio-loop-marketing: storyboard/copy/mock/dry-run antes de publish/spend;
• simplicio-sprint: simulação de backlog/DAG/capacidade antes de SendSprint;
• simplicio-prompt: variantes/evals antes de promover prompt.

Tipos canônicos de protótipo

• wireframe / maquete / fluxo de telas;
• architecture_diagram / DAG / state machine;
• schema / API contract / event contract;
• data_model / migration dry-run / query plan;
• failing_reproducer / teste vermelho;
• benchmark_spike / baseline de performance;
• mock_or_fake / adapter contratual;
• code_spike / algoritmo isolado;
• vertical_slice / um fluxo real mínimo;
• prompt_candidate / golden eval;
• workflow_simulation / capacity/critical-path replay;
• storyboard / creative/campaign preview;
• policy_or_security_model / threat model/failure model.

A enumeração deve ser extensível por schema versionado sem quebrar consumidores.

Níveis e orçamentos

Nível	Resultado	Limite inicial recomendado
P0	artefato estrutural não executável	1–3% do budget estimado
P1	PoC isolada com mock/dado sintético	até 10%
P2	vertical slice real e reversível	até 20%
FULL	implementação completa	somente após decisão aceita

Os percentuais são defaults de policy, não números hardcoded. O coordinator pode ajustar dentro de limites configurados e deve registrar justificativa.

Quando o gate é obrigatório

• arquitetura ou contrato novo;
• UI/UX, fluxo ou experiência nova;
• modelo de dados/migration;
• API/event schema;
• mudança multi-repo;
• efeito externo, publicação, gasto ou operação irreversível;
• nova dependência/runtime/provider;
• alta incerteza ou múltiplas abordagens plausíveis;
• tarefa acima do token/cost/time threshold;
• performance/otimização sem baseline;
• bug sem reproducer;
• segurança ou blast radius alto;
• histórico de retries/failure fingerprint;
• pedido humano explícito de preview/maquete/PoC.

Pode ser dispensado para tarefa trivial, mecânica e de baixo risco somente mediante prototype_not_required receipt com razão, estimativa e policy aplicada. O próprio implementador não pode dispensar unilateralmente o gate em tarefa high/critical.

Contratos versionados

simplicio.prototype-plan/v1

• run/task/source/plan IDs e revisions;
• problema, hipótese e resultado esperado;
• uncertainty/risk/blast-radius classification;
• tipos e níveis selecionados;
• alternatives/candidates requeridos;
• budgets de tokens, custo, tempo, CPU, RAM, disco e slots;
• isolation e mutation policy;
• synthetic/real data policy;
• validators, judge e acceptance criteria;
• promotion/rollback rules;
• upstream component versions/hashes.

simplicio.prototype-candidate/v1

• candidate/strategy/agent/model/runtime IDs;
• artifact content hash e location;
• inputs/context/source hash;
• assumptions, limitations e out-of-scope;
• measured costs;
• validation results e evidence refs;
• safety/truth classification;
• status e terminal reason.

simplicio.prototype-decision/v1

• decision ACCEPT|REVISE|REJECT|BLOCKED;
• judge identity e independence proof;
• ranked candidates e explainable score;
• AC coverage;
• selected candidate/hash;
• rejected candidates/reasons;
• required changes;
• allowed next stage;
• expiry/revalidation condition.

simplicio.prototype-receipt/v1

Liga hipótese→candidate→validation→decision→vertical slice→implementação→tests→delivery, com hashes, attempt, fence e plan/source revisions.

Regras de segurança e verdade

1. P0/P1 são read-only ou escrevem somente em sandbox/artifact store.
2. P2 usa worktree/branch/transaction isolada.
3. Protótipo nunca publica, gasta, migra produção, abre PR terminal ou altera shared target.
4. Dados reais exigem policy explícita; default é sintético/redigido.
5. Nenhum resultado é chamado “medido” sem comando/receipt reproduzível.
6. ACCEPT libera apenas o próximo nível; não declara a task concluída.
7. Candidate expirado por source/plan/schema drift volta para validação.
8. Judge deve ser independente do criador em tarefas medium/high/critical.
9. Primeiro candidate não vence por velocidade; vence o primeiro verificado ou o melhor pela policy.
10. Findings observados durante protótipo entram no finding lifecycle normal.

Passo a passo de implementação

1. Criar ADR do Prototype-First Gate e fronteiras do ecossistema.
2. Definir schemas, state machine e reason codes.
3. Implementar classificador de necessidade com policy configurável e explicável.
4. Integrar ao task contract/intake/planning antes de qualquer mutação FULL.
5. Integrar ao task anchor, backlog e dependency DAG.
6. Implementar budget reservation/ledger e hard caps.
7. Implementar artifact registry content-addressed.
8. Integrar mapper context/impact receipts.
9. Integrar Runtime sandbox/quotas/adapters.
10. Integrar dev-cli scaffold/dry-run/validate/promote.
11. Materializar prototype planner, candidate agents e judge independente.
12. Implementar fan-out seguro de alternativas e winner selection.
13. Implementar REVISE loop com stall detection e retry budget.
14. Implementar promotion P0→P1→P2→FULL com revalidation por hash.
15. Integrar stage reports, GitHub comments e progress protocol.
16. Integrar findings/evolution/adaptive architecture.
17. Bloquear implementation/full delivery/completion sem decision receipt válido quando required.
18. Expor CLI/API prototype plan|generate|list|show|validate|compare|decide|promote|reject|doctor --json.
19. Criar replay/shadow/canary para mudanças no próprio protocolo.
20. Atualizar skills, docs, bundles, installers e conformance matrix.
21. Publicar benchmarks antes/depois e token-waste report.
22. Ligar adapters filhos listados nesta epic por contract tests.

Testes obrigatórios

Unitários/contract

• classifier obrigatório/opcional/dispensado;
• schemas e backward compatibility;
• budget calculations e hard caps;
• state transitions e expiry;
• content hashes/source drift;
• score/ranking/decision explainability;
• authority negativa e judge independence.

Integração

• Mapper→Loop→Runtime→Dev CLI→Agent;
• P0→P1→P2→FULL;
• 1/2/4/N candidates e poucos slots em ondas;
• local model→remote escalation;
• crash/restart em cada boundary;
• outbox/report offline/retry;
• finding durante prototype;
• candidate artifact corrompido.

Sistema/E2E

• UI: wireframe rejeitado antes do frontend;
• API: schema/fake server aceito antes do backend;
• data: model/migration dry-run revisado;
• bug: reproducer/teste vermelho antes do fix;
• performance: baseline/spike antes da otimização;
• multi-repo: contratos compatíveis antes da implementação;
• trivial task: dispensa justificada;
• high-risk task: tentativa de bypass bloqueada.

Segurança/adversarial

• prompt injection tenta dispensar gate;
• candidate acessa secret/dado real;
• symlink/path traversal no artifact store;
• forged decision/receipt;
• creator se apresenta como judge;
• prototype tenta efeito externo;
• budget/slot exhaustion;
• malicious artifact e unsafe promotion.

Performance/economia

• 1.000 task contracts no classifier;
• time-to-first-evidence;
• tokens/custo P0/P1/P2/FULL;
• avoided implementation tokens;
• prototype conversion/rejection/revision rates;
• late rejection e retrabalho;
• p50/p95/p99 e overhead máximo do gate;
• qualidade/success rate preservadas.

Métricas obrigatórias

• time_to_first_evidence;
• prototype_tokens/cost/duration;
• estimated_full_cost_avoided;
• accept|revise|reject rate;
• late_rejection_rate;
• post_accept_rework_rate;
• prototype_to_delivery_conversion;
• judge_disagreement_rate;
• external_effect_count_during_prototype (meta 0);
• untracked_finding_count (meta 0).

Critérios de aceite

• Prototype-First é etapa produtiva do Loop, não documentação opcional.
• Classificador decide de forma explicável e policy-bound.
• Tarefas obrigatórias não alcançam FULL sem decision receipt válido.
• Dispensa gera receipt e é bloqueada em high/critical sem autoridade.
• P0/P1/P2 possuem isolamento e budgets reais.
• Protótipos não produzem efeitos externos.
• Candidate artifacts são content-addressed e auditáveis.
• Judge é independente quando exigido.
• REJECT encerra sem implementar e registra economia estimada/medida.
• REVISE é bounded e detecta stall.
• ACCEPT libera apenas o próximo estágio.
• Source/plan/schema drift invalida decisões antigas.
• Findings são roteados e completion continua fail-closed.
• Todos os projetos consumidores passam contract/conformance tests.
• Unitários, integração, sistema/E2E, regressão, segurança, caos e performance passam.
• Cobertura mínima de 85% no código novo/alterado.
• Benchmarks mostram redução de tokens desperdiçados sem queda de qualidade.
• Cada checkbox aponta para teste, receipt, PR ou artefato reproduzível.

Definition of Done

Executar um backlog sandbox contendo tarefa trivial, UI, API, modelo de dados, bug, performance, multi-repo e high-risk. O Loop deve dispensar apenas a trivial com receipt; gerar candidatos isolados; permitir rejeitar soluções antes da implementação; promover a vencedora em níveis; bloquear efeitos externos e bypasses; recuperar crash; reportar findings; e demonstrar quantitativamente tokens/custo/retrabalho evitados. Todos os adapters do ecossistema precisam passar conformance instalada.

Execução no ecossistema: issues filhas e gates

Estas issues são adapters obrigatórios do contrato desta epic. O checkbox só pode ser marcado com PR, teste de conformance e receipt reproduzível; fechar apenas com ADR, documentação ou PoC desconectada não é aceito.

• simplicio-runtime#3337 — sandbox, quotas, artifact store, fencing e zero efeito externo.
• simplicio-mapper#286 — context pack, impacto e estruturas mínimas bounded.
• simplicio-dev-cli#236 — scaffold, dry-run, validação e promoção segura.
• simplicio-agent#484 — planner, candidates, critic e judge independente.
• simplicio-code#60 — preview/comparação/decisão e bloqueio do Build.
• simplicio-local-any-llm-16gb#143 — geração e crítica local econômica.
• simplicio-loop-oss#11 — reproducer/patch experimental antes de PR.
• simplicio-loop-marketing#96 — storyboard/copy/creative e campaign dry-run antes de publish/spend.
• simplicio-sprint#308 — simulação de backlog, DAG, WIP e capacidade antes do SendSprint.
• simplicio-prompt#110 — variantes, golden evals e promoção versionada.

DAG de implementação e integração

Loop #568: schemas + state machine + policy + receipts
 ├─ Mapper #286 ───────────────┐
 ├─ Runtime #3337 ─────────────┼─> Dev CLI #236 ───────┐
 ├─ Prompt #110 ──┐            │                        │
 └─ Local LLM #143 ├─> Agent #484 ──────────────────────┼─> Code #60
                   │                                     ├─> Sprint #308
                   └─────────────────────────────────────┤
                                                         ├─> OSS #11
                                                         └─> Marketing #96
todos os adapters + Loop #568 ──> conformance cross-repo ──> FULL/delivery

Ordem de promoção

1. Congelar schemas/reason codes e fixtures no Loop.
2. Implementar Mapper e Runtime em paralelo contra as fixtures.
3. Integrar Prompt, LLM local e Agent, preservando independência do judge.
4. Ligar Dev CLI à promoção P0→P1→P2→FULL.
5. Ligar Code e Sprint aos mesmos receipts, sem estado paralelo.
6. Ligar OSS e Marketing como extensões do Loop, sem coordinator próprio.
7. Executar conformance cross-repo, fault injection e Product E2E.
8. Habilitar rollout em shadow/canary; somente então tornar o gate obrigatório por policy.

Gate de integração

• Nenhuma filha pode redefinir schemas ou semântica central localmente.
• Consumer incompatível fica fail-closed com diagnóstico e não cai em fallback silencioso.
• A epic não fecha enquanto qualquer adapter obrigatório estiver aberto, sem conformance ou abaixo de 85% de cobertura no código alterado.
• O fluxo de release deve bloquear regressão de contract test, efeito externo durante protótipo, promoção sem ACCEPT válido ou bypass high/critical.